Python 2.3.3-jp ドキュメント - June 28, 2004

Python ドキュメント モジュールインデクス

Python ドキュメント

リリース 2.3.3-jp
June 28, 2004

  • チュートリアル
    (ここから読み始めてください)
  • Python 更新情報 (英語)
    (一つ前のメジャーリリースからの変更)
  • グローバルモジュールインデクス
    (全ドキュメントにすばやくアクセスできます)
  • ライブラリリファレンス
    (枕の下にいつも置いておきましょう)
  • Macintosh モジュールリファレンス
    (Macintosh を使っているならこれも)
  • Python モジュールのインストール
    (管理者向け)
  • Python モジュールの配布
    (開発者，パッケージ作成者向け)
  • リファレンスマニュアル
    (弁語士向け)
  • 拡張と埋め込み
    (C/C++ プログラマ向けチュートリアル)
  • Python/C API
    (C/C++ プログラマ向けリファレンス)
  • Python ドキュメントの作成
    (ドキュメント作者用の情報)
  • ドキュメント作成本部 (英語)
    (すべての人に)
  • Python How-To ガイド (英語)
    (専門的な話題)

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。


グローバルモジュールインデクス

モジュール名の後ろにある注釈は、利用できるプラットフォームを表しています。

__builtin__
__future__
__main__
_winreg (Windows)
aepack (Mac)
aetools (Mac)
aetypes (Mac)
aifc
AL (IRIX)
al (IRIX)
anydbm
applesingle (Mac)
array
asynchat
asyncore
atexit
audioop
autoGIL (Mac)
base64
BaseHTTPServer
Bastion
binascii
binhex
bisect
bsddb (Unix, Windows)
buildtools (Mac)
bz2
calendar
Carbon.AE (Mac)
Carbon.AH (Mac)
Carbon.App (Mac)
Carbon.CaronEvt (Mac)
Carbon.CF (Mac)
Carbon.CG (Mac)
Carbon.Cm (Mac)
Carbon.Ctl (Mac)
Carbon.Dlg (Mac)
Carbon.Evt (Mac)
Carbon.Fm (Mac)
Carbon.Folder (Mac)
Carbon.Help (Mac)
Carbon.List (Mac)
Carbon.Menu (Mac)
Carbon.Mlte (Mac)
Carbon.Qd (Mac)
Carbon.Qdoffs (Mac)
Carbon.Qt (Mac)
Carbon.Res (Mac)
Carbon.Scrap (Mac)
Carbon.Snd (Mac)
Carbon.TE (Mac)
Carbon.Win (Mac)
cd (IRIX)
cfmfile (Mac)
cgi
CGIHTTPServer
cgitb
chunk
cmath
cmd
code
codecs
codeop
ColorPicker (Mac)
colorsys
commands (Unix)
compileall
compiler
compiler.ast
compiler.visitor
ConfigParser
Cookie
copy
copy_reg
cPickle
crypt (Unix)
cStringIO
csv
curses
curses.ascii
curses.panel
curses.textpad
curses.wrapper
datetime
dbhash (Unix, Windows)
dbm (Unix)
DEVICE (IRIX)
difflib
dircache
dis
distutils
dl (Unix)
doctest
DocXMLRPCServer
dumbdbm
dummy_thread
dummy_threading
EasyDialogs (Mac)
email
email.Charset
email.Generator
email.Header
email.Iterators
email.Message
email.Parser
email.Utils
encodings.idna
errno
exceptions
fcntl (Unix)
filecmp
fileinput
findertools (Mac)
FL (IRIX)
fl (IRIX)
flp (IRIX)
fm (IRIX)
fnmatch
formatter
fpectl (Unix)
fpformat
FrameWork (Mac)
ftplib
gc
gdbm (Unix)
gensuitemodule (Mac)
getopt
getpass
gettext
GL (IRIX)
gl (IRIX)
glob
gopherlib
grp (Unix)
gzip
heapq
hmac
hotshot
hotshot.stats
htmlentitydefs
htmllib
HTMLParser
httplib
ic (Mac)
icopen (Mac)
imageop
imaplib
imgfile (IRIX)
imghdr
imp
inspect
itertools
jpeg (IRIX)
keyword
linecache
locale
logging
mac (Mac)
macerrors (Mac)
macfs (Mac)
MacOS (Mac)
macostools (Mac)
macpath
macresource (Mac)
mailbox
mailcap
marshal
math
md5
mhlib
mimetools
mimetypes
MimeWriter
mimify
MiniAEFrame (Mac)
mkcwproject (Mac)
mmap
mpz
msvcrt (Windows)
multifile
mutex
Nac (Mac)
netrc
new
nis (UNIX)
nntplib
nsremote (Mac)
operator
optparse
os
os.path
ossaudiodev (Linux, FreeBSD, おそらく他の Unix 系システムでも)
parser
pdb
pickle
pipes (Unix)
PixMapWrapper (Mac)
pkgutil
popen2 (Unix, Windows)
poplib
posix (Unix)
posixfile (Unix)
pprint
preferences (Mac)
profile
pstats
pty (IRIX, Linux)
pwd (Unix)
py_compile
py_resource (Mac)
pyclbr
pydoc
pythonprefs (Mac)
Queue
quietconsole (Mac)
quopri
random
re
readline (Unix)
repr
resource (Unix)
rexec
rfc822
rgbimg
rlcompleter (Unix)
robotparser
rotor
sched
ScrolledText (Tk)
select
sets
sgmllib
sha
shelve
shlex
shutil
signal
SimpleHTTPServer
SimpleXMLRPCServer
site
smtplib
sndhdr
socket
SocketServer
stat
statcache
statvfs
string
StringIO
stringprep
struct
sunau
SUNAUDIODEV (SunOS)
sunaudiodev (SunOS)
symbol
sys
syslog (Unix)
tabnanny
tarfile
telnetlib
tempfile
TERMIOS (Unix)
termios (Unix)
test
test.test_support
textwrap
thread
threading
time
timeit
Tix
Tkinter
token
tokenize
traceback
tty (Unix)
turtle (Tk)
types
unicodedata
unittest
urllib
urllib2
urlparse
user
UserDict
UserList
UserString
uu
videoreader (Mac)
W (Mac)
warnings
waste (Mac)
wave
weakref
webbrowser
whichdb
whrandom
winsound (Windows)
xdrlib
xml.dom
xml.dom.minidom
xml.dom.pulldom
xml.parsers.expat
xml.sax
xml.sax.handler
xml.sax.saxutils
xml.sax.xmlreader
xmllib
xmlrpclib
xreadlines
zipfile
zlib

up グローバルモジュールインデクス
Up: Python ドキュメントインデクス


What's New in Python 2.3

A.M. Kuchling

amk@amk.ca

  • 目次
  • 1 PEP 218: A Standard Set Datatype
  • 2 PEP 255: Simple Generators
  • 3 PEP 263: Source Code Encodings
  • 4 PEP 273: Importing Modules from Zip Archives
  • 5 PEP 277: Unicode file name support for Windows NT
  • 6 PEP 278: Universal Newline Support
  • 7 PEP 279: enumerate()
  • 8 PEP 282: The logging Package
  • 9 PEP 285: A Boolean Type
  • 10 PEP 293: Codec Error Handling Callbacks
  • 11 PEP 301: Package Index and Metadata for Distutils
  • 12 PEP 302: New Import Hooks
  • 13 PEP 305: Comma-separated Files
  • 14 PEP 307: Pickle Enhancements
  • 15 Extended Slices
  • 16 Other Language Changes
    • 16.1 String Changes
    • 16.2 Optimizations
  • 17 New, Improved, and Deprecated Modules
    • 17.1 Date/Time Type
    • 17.2 The optparse Module
  • 18 Pymalloc: A Specialized Object Allocator
  • 19 Build and C API Changes
    • 19.1 Port-Specific Changes
  • 20 Other Changes and Fixes
  • 21 Porting to Python 2.3
  • 22 Acknowledgements
  • この文書について...
Up One Level Next Page What's New in Python 2.3 Contents
Up: Python ドキュメントインデクス Next: 目次
Release 1.00.


1 PEP 218: A Standard Set Datatype

The new sets module contains an implementation of a set datatype. The Set class is for mutable sets, sets that can have members added and removed. The ImmutableSet class is for sets that can't be modified, and instances of ImmutableSet can therefore be used as dictionary keys. Sets are built on top of dictionaries, so the elements within a set must be hashable.

Here's a simple example:

>>> import sets
>>> S = sets.Set([1,2,3])
>>> S
Set([1, 2, 3])
>>> 1 in S
True
>>> 0 in S
False
>>> S.add(5)
>>> S.remove(3)
>>> S
Set([1, 2, 5])
>>>

The union and intersection of sets can be computed with the union() and intersection() methods; an alternative notation uses the bitwise operators & and |. Mutable sets also have in-place versions of these methods, union_update() and intersection_update().

>>> S1 = sets.Set([1,2,3])
>>> S2 = sets.Set([4,5,6])
>>> S1.union(S2)
Set([1, 2, 3, 4, 5, 6])
>>> S1 | S2                  # Alternative notation
Set([1, 2, 3, 4, 5, 6])
>>> S1.intersection(S2)
Set([])
>>> S1 & S2                  # Alternative notation
Set([])
>>> S1.union_update(S2)
>>> S1
Set([1, 2, 3, 4, 5, 6])
>>>

It's also possible to take the symmetric difference of two sets. This is the set of all elements in the union that aren't in the intersection. Another way of putting it is that the symmetric difference contains all elements that are in exactly one set. Again, there's an alternative notation (^), and an in-place version with the ungainly name symmetric_difference_update().

>>> S1 = sets.Set([1,2,3,4])
>>> S2 = sets.Set([3,4,5,6])
>>> S1.symmetric_difference(S2)
Set([1, 2, 5, 6])
>>> S1 ^ S2
Set([1, 2, 5, 6])
>>>

There are also issubset() and issuperset() methods for checking whether one set is a subset or superset of another:

>>> S1 = sets.Set([1,2,3])
>>> S2 = sets.Set([2,3])
>>> S2.issubset(S1)
True
>>> S1.issubset(S2)
False
>>> S1.issuperset(S2)
True
>>>

See Also:

PEP 218, Adding a Built-In Set Object Type
PEP written by Greg V. Wilson. Implemented by Greg V. Wilson, Alex Martelli, and GvR.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 目次 Up: What's New in Python Next: 2 PEP 255: Simple
Release 1.00.


2 PEP 255: Simple Generators

In Python 2.2, generators were added as an optional feature, to be enabled by a from __future__ import generators directive. In 2.3 generators no longer need to be specially enabled, and are now always present; this means that yield is now always a keyword. The rest of this section is a copy of the description of generators from the ``What's New in Python 2.2'' document; if you read it back when Python 2.2 came out, you can skip the rest of this section.

You're doubtless familiar with how function calls work in Python or C. When you call a function, it gets a private namespace where its local variables are created. When the function reaches a return statement, the local variables are destroyed and the resulting value is returned to the caller. A later call to the same function will get a fresh new set of local variables. But, what if the local variables weren't thrown away on exiting a function? What if you could later resume the function where it left off? This is what generators provide; they can be thought of as resumable functions.

Here's the simplest example of a generator function:

def generate_ints(N):
    for i in range(N):
        yield i

A new keyword, yield, was introduced for generators. Any function containing a yield statement is a generator function; this is detected by Python's bytecode compiler which compiles the function specially as a result.

When you call a generator function, it doesn't return a single value; instead it returns a generator object that supports the iterator protocol. On executing the yield statement, the generator outputs the value of i, similar to a return statement. The big difference between yield and a return statement is that on reaching a yield the generator's state of execution is suspended and local variables are preserved. On the next call to the generator's .next() method, the function will resume executing immediately after the yield statement. (For complicated reasons, the yield statement isn't allowed inside the try block of a try...finally statement; read PEP 255 for a full explanation of the interaction between yield and exceptions.)

Here's a sample usage of the generate_ints() generator:

>>> gen = generate_ints(3)
>>> gen
<generator object at 0x8117f90>
>>> gen.next()
0
>>> gen.next()
1
>>> gen.next()
2
>>> gen.next()
Traceback (most recent call last):
  File "stdin", line 1, in ?
  File "stdin", line 2, in generate_ints
StopIteration

You could equally write for i in generate_ints(5), or a,b,c = generate_ints(3).

Inside a generator function, the return statement can only be used without a value, and signals the end of the procession of values; afterwards the generator cannot return any further values. return with a value, such as return 5, is a syntax error inside a generator function. The end of the generator's results can also be indicated by raising StopIteration manually, or by just letting the flow of execution fall off the bottom of the function.

You could achieve the effect of generators manually by writing your own class and storing all the local variables of the generator as instance variables. For example, returning a list of integers could be done by setting self.count to 0, and having the next() method increment self.count and return it. However, for a moderately complicated generator, writing a corresponding class would be much messier. Lib/test/test_generators.py contains a number of more interesting examples. The simplest one implements an in-order traversal of a tree using generators recursively.

# A recursive generator that generates Tree leaves in in-order.
def inorder(t):
    if t:
        for x in inorder(t.left):
            yield x
        yield t.label
        for x in inorder(t.right):
            yield x

Two other examples in Lib/test/test_generators.py produce solutions for the N-Queens problem (placing $N$ queens on an $NxN$ chess board so that no queen threatens another) and the Knight's Tour (a route that takes a knight to every square of an $NxN$ chessboard without visiting any square twice).

The idea of generators comes from other programming languages, especially Icon (http://www.cs.arizona.edu/icon/), where the idea of generators is central. In Icon, every expression and function call behaves like a generator. One example from ``An Overview of the Icon Programming Language'' at http://www.cs.arizona.edu/icon/docs/ipd266.htm gives an idea of what this looks like:

sentence := "Store it in the neighboring harbor"
if (i := find("or", sentence)) > 5 then write(i)

In Icon the find() function returns the indexes at which the substring ``or'' is found: 3, 23, 33. In the if statement, i is first assigned a value of 3, but 3 is less than 5, so the comparison fails, and Icon retries it with the second value of 23. 23 is greater than 5, so the comparison now succeeds, and the code prints the value 23 to the screen.

Python doesn't go nearly as far as Icon in adopting generators as a central concept. Generators are considered part of the core Python language, but learning or using them isn't compulsory; if they don't solve any problems that you have, feel free to ignore them. One novel feature of Python's interface as compared to Icon's is that a generator's state is represented as a concrete object (the iterator) that can be passed around to other functions or stored in a data structure.

See Also:

PEP 255, Simple Generators
Written by Neil Schemenauer, Tim Peters, Magnus Lie Hetland. Implemented mostly by Neil Schemenauer and Tim Peters, with other fixes from the Python Labs crew.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 1 PEP 218: A Up: What's New in Python Next: 3 PEP 263: Source
Release 1.00.


3 PEP 263: Source Code Encodings

Python source files can now be declared as being in different character set encodings. Encodings are declared by including a specially formatted comment in the first or second line of the source file. For example, a UTF-8 file can be declared with:

#!/usr/bin/env python
# -*- coding: UTF-8 -*-

Without such an encoding declaration, the default encoding used is 7-bit ASCII. Executing or importing modules that contain string literals with 8-bit characters and have no encoding declaration will result in a DeprecationWarning being signalled by Python 2.3; in 2.4 this will be a syntax error.

The encoding declaration only affects Unicode string literals, which will be converted to Unicode using the specified encoding. Note that Python identifiers are still restricted to ASCII characters, so you can't have variable names that use characters outside of the usual alphanumerics.

See Also:

PEP 263, Defining Python Source Code Encodings
Written by Marc-André Lemburg and Martin von Löwis; implemented by Suzuki Hisao and Martin von Löwis.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 2 PEP 255: Simple Up: What's New in Python Next: 4 PEP 273: Importing
Release 1.00.


4 PEP 273: Importing Modules from Zip Archives

The new zipimport module adds support for importing modules from a ZIP-format archive. You don't need to import the module explicitly; it will be automatically imported if a ZIP archive's filename is added to sys.path. For example:

amk@nyman:~/src/python$ unzip -l /tmp/example.zip
Archive:  /tmp/example.zip
  Length     Date   Time    Name
 --------    ----   ----    ----
     8467  11-26-02 22:30   jwzthreading.py
 --------                   -------
     8467                   1 file
amk@nyman:~/src/python$ ./python
Python 2.3 (#1, Aug 1 2003, 19:54:32)
>>> import sys
>>> sys.path.insert(0, '/tmp/example.zip')  # Add .zip file to front of path
>>> import jwzthreading
>>> jwzthreading.__file__
'/tmp/example.zip/jwzthreading.py'
>>>

An entry in sys.path can now be the filename of a ZIP archive. The ZIP archive can contain any kind of files, but only files named *.py, *.pyc, or *.pyo can be imported. If an archive only contains *.py files, Python will not attempt to modify the archive by adding the corresponding *.pyc file, meaning that if a ZIP archive doesn't contain *.pyc files, importing may be rather slow.

A path within the archive can also be specified to only import from a subdirectory; for example, the path /tmp/example.zip/lib/ would only import from the lib/ subdirectory within the archive.

See Also:

PEP 273, Import Modules from Zip Archives
Written by James C. Ahlstrom, who also provided an implementation. Python 2.3 follows the specification in PEP 273, but uses an implementation written by Just van Rossum that uses the import hooks described in PEP 302. See section 12 for a description of the new import hooks.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 3 PEP 263: Source Up: What's New in Python Next: 5 PEP 277: Unicode
Release 1.00.


5 PEP 277: Unicode file name support for Windows NT

On Windows NT, 2000, and XP, the system stores file names as Unicode strings. Traditionally, Python has represented file names as byte strings, which is inadequate because it renders some file names inaccessible.

Python now allows using arbitrary Unicode strings (within the limitations of the file system) for all functions that expect file names, most notably the open() built-in function. If a Unicode string is passed to os.listdir(), Python now returns a list of Unicode strings. A new function, os.getcwdu(), returns the current directory as a Unicode string.

Byte strings still work as file names, and on Windows Python will transparently convert them to Unicode using the mbcs encoding.

Other systems also allow Unicode strings as file names but convert them to byte strings before passing them to the system, which can cause a UnicodeError to be raised. Applications can test whether arbitrary Unicode strings are supported as file names by checking os.path.supports_unicode_filenames, a Boolean value.

Under MacOS, os.listdir() may now return Unicode filenames.

See Also:

PEP 277, Unicode file name support for Windows NT
Written by Neil Hodgson; implemented by Neil Hodgson, Martin von Löwis, and Mark Hammond.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 4 PEP 273: Importing Up: What's New in Python Next: 6 PEP 278: Universal
Release 1.00.


6 PEP 278: Universal Newline Support

The three major operating systems used today are Microsoft Windows, Apple's Macintosh OS, and the various Unix derivatives. A minor irritation of cross-platform work is that these three platforms all use different characters to mark the ends of lines in text files. Unix uses the linefeed (ASCII character 10), MacOS uses the carriage return (ASCII character 13), and Windows uses a two-character sequence of a carriage return plus a newline.

Python's file objects can now support end of line conventions other than the one followed by the platform on which Python is running. Opening a file with the mode 'U' or 'rU' will open a file for reading in universal newline mode. All three line ending conventions will be translated to a "\n" in the strings returned by the various file methods such as read() and readline().

Universal newline support is also used when importing modules and when executing a file with the execfile() function. This means that Python modules can be shared between all three operating systems without needing to convert the line-endings.

This feature can be disabled when compiling Python by specifying the --without-universal-newlines switch when running Python's configure script.

See Also:

PEP 278, Universal Newline Support
Written and implemented by Jack Jansen.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 5 PEP 277: Unicode Up: What's New in Python Next: 7 PEP 279: enumerate()
Release 1.00.


7 PEP 279: enumerate()

A new built-in function, enumerate(), will make certain loops a bit clearer. enumerate(thing), where thing is either an iterator or a sequence, returns a iterator that will return (0, thing[0]), (1, thing[1]), (2, thing[2]), and so forth.

A common idiom to change every element of a list looks like this:

for i in range(len(L)):
    item = L[i]
    # ... compute some result based on item ...
    L[i] = result

This can be rewritten using enumerate() as:

for i, item in enumerate(L):
    # ... compute some result based on item ...
    L[i] = result

See Also:

PEP 279, The enumerate() built-in function
Written and implemented by Raymond D. Hettinger.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 6 PEP 278: Universal Up: What's New in Python Next: 8 PEP 282: The
Release 1.00.


8 PEP 282: The logging Package

A standard package for writing logs, logging, has been added to Python 2.3. It provides a powerful and flexible mechanism for generating logging output which can then be filtered and processed in various ways. A configuration file written in a standard format can be used to control the logging behavior of a program. Python includes handlers that will write log records to standard error or to a file or socket, send them to the system log, or even e-mail them to a particular address; of course, it's also possible to write your own handler classes.

The Logger class is the primary class. Most application code will deal with one or more Logger objects, each one used by a particular subsystem of the application. Each Logger is identified by a name, and names are organized into a hierarchy using "." as the component separator. For example, you might have Logger instances named "server", "server.auth" and "server.network". The latter two instances are below "server" in the hierarchy. This means that if you turn up the verbosity for "server" or direct "server"messages to a different handler, the changes will also apply to records logged to "server.auth" and "server.network". There's also a root Logger that's the parent of all other loggers.

For simple uses, the logging package contains some convenience functions that always use the root log:

import logging

logging.debug('Debugging information')
logging.info('Informational message')
logging.warning('Warning:config file %s not found', 'server.conf')
logging.error('Error occurred')
logging.critical('Critical error -- shutting down')

This produces the following output:

WARNING:root:Warning:config file server.conf not found
ERROR:root:Error occurred
CRITICAL:root:Critical error -- shutting down

In the default configuration, informational and debugging messages are suppressed and the output is sent to standard error. You can enable the display of informational and debugging messages by calling the setLevel() method on the root logger.

Notice the warning() call's use of string formatting operators; all of the functions for logging messages take the arguments (msg, arg1, arg2, ...) and log the string resulting from msg % (arg1, arg2, ...).

There's also an exception() function that records the most recent traceback. Any of the other functions will also record the traceback if you specify a true value for the keyword argument exc_info.

def f():
    try:    1/0
    except: logging.exception('Problem recorded')

f()

This produces the following output:

ERROR:root:Problem recorded
Traceback (most recent call last):
  File "t.py", line 6, in f
    1/0
ZeroDivisionError: integer division or modulo by zero

Slightly more advanced programs will use a logger other than the root logger. The getLogger(name) function is used to get a particular log, creating it if it doesn't exist yet. getLogger(None) returns the root logger.

log = logging.getLogger('server')
 ...
log.info('Listening on port %i', port)
 ...
log.critical('Disk full')
 ...

Log records are usually propagated up the hierarchy, so a message logged to "server.auth" is also seen by "server" and "root", but a Logger can prevent this by setting its propagate attribute to False.

There are more classes provided by the logging package that can be customized. When a Logger instance is told to log a message, it creates a LogRecord instance that is sent to any number of different Handler instances. Loggers and handlers can also have an attached list of filters, and each filter can cause the LogRecord to be ignored or can modify the record before passing it along. When they're finally output, LogRecord instances are converted to text by a Formatter class. All of these classes can be replaced by your own specially-written classes.

With all of these features the logging package should provide enough flexibility for even the most complicated applications. This is only an incomplete overview of its features, so please see the package's reference documentation for all of the details. Reading PEP 282 will also be helpful.

See Also:

PEP 282, A Logging System
Written by Vinay Sajip and Trent Mick; implemented by Vinay Sajip.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 7 PEP 279: enumerate() Up: What's New in Python Next: 9 PEP 285: A
Release 1.00.


9 PEP 285: A Boolean Type

A Boolean type was added to Python 2.3. Two new constants were added to the __builtin__ module, True and False. (True and False constants were added to the built-ins in Python 2.2.1, but the 2.2.1 versions are simply set to integer values of 1 and 0 and aren't a different type.)

The type object for this new type is named bool; the constructor for it takes any Python value and converts it to True or False.

>>> bool(1)
True
>>> bool(0)
False
>>> bool([])
False
>>> bool( (1,) )
True

Most of the standard library modules and built-in functions have been changed to return Booleans.

>>> obj = []
>>> hasattr(obj, 'append')
True
>>> isinstance(obj, list)
True
>>> isinstance(obj, tuple)
False

Python's Booleans were added with the primary goal of making code clearer. For example, if you're reading a function and encounter the statement return 1, you might wonder whether the 1 represents a Boolean truth value, an index, or a coefficient that multiplies some other quantity. If the statement is return True, however, the meaning of the return value is quite clear.

Python's Booleans were not added for the sake of strict type-checking. A very strict language such as Pascal would also prevent you performing arithmetic with Booleans, and would require that the expression in an if statement always evaluate to a Boolean result. Python is not this strict and never will be, as PEP 285 explicitly says. This means you can still use any expression in an if statement, even ones that evaluate to a list or tuple or some random object. The Boolean type is a subclass of the int class so that arithmetic using a Boolean still works.

>>> True + 1
2
>>> False + 1
1
>>> False * 75
0
>>> True * 75
75

To sum up True and False in a sentence: they're alternative ways to spell the integer values 1 and 0, with the single difference that str() and repr() return the strings 'True' and 'False' instead of '1' and '0'.

See Also:

PEP 285, Adding a bool type
Written and implemented by GvR.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 8 PEP 282: The Up: What's New in Python Next: 10 PEP 293: Codec
Release 1.00.


10 PEP 293: Codec Error Handling Callbacks

When encoding a Unicode string into a byte string, unencodable characters may be encountered. So far, Python has allowed specifying the error processing as either ``strict'' (raising UnicodeError), ``ignore'' (skipping the character), or ``replace'' (using a question mark in the output string), with ``strict'' being the default behavior. It may be desirable to specify alternative processing of such errors, such as inserting an XML character reference or HTML entity reference into the converted string.

Python now has a flexible framework to add different processing strategies. New error handlers can be added with codecs.register_error, and codecs then can access the error handler with codecs.lookup_error. An equivalent C API has been added for codecs written in C. The error handler gets the necessary state information such as the string being converted, the position in the string where the error was detected, and the target encoding. The handler can then either raise an exception or return a replacement string.

Two additional error handlers have been implemented using this framework: ``backslashreplace'' uses Python backslash quoting to represent unencodable characters and ``xmlcharrefreplace'' emits XML character references.

See Also:

PEP 293, Codec Error Handling Callbacks
Written and implemented by Walter Dörwald.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 9 PEP 285: A Up: What's New in Python Next: 11 PEP 301: Package
Release 1.00.


11 PEP 301: Package Index and Metadata for Distutils

Support for the long-requested Python catalog makes its first appearance in 2.3.

The heart of the catalog is the new Distutils register command. Running python setup.py register will collect the metadata describing a package, such as its name, version, maintainer, description, &c., and send it to a central catalog server. The resulting catalog is available from http://www.python.org/pypi.

To make the catalog a bit more useful, a new optional classifiers keyword argument has been added to the Distutils setup() function. A list of Trove-style strings can be supplied to help classify the software.

Here's an example setup.py with classifiers, written to be compatible with older versions of the Distutils:

from distutils import core
kw = {'name': "Quixote",
      'version': "0.5.1",
      'description': "A highly Pythonic Web application framework",
      # ...
      }

if (hasattr(core, 'setup_keywords') and
    'classifiers' in core.setup_keywords):
    kw['classifiers'] = \
        ['Topic :: Internet :: WWW/HTTP :: Dynamic Content',
         'Environment :: No Input/Output (Daemon)',
         'Intended Audience :: Developers'],

core.setup(**kw)

The full list of classifiers can be obtained by running python setup.py register --list-classifiers.

See Also:

PEP 301, Package Index and Metadata for Distutils
Written and implemented by Richard Jones.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 10 PEP 293: Codec Up: What's New in Python Next: 12 PEP 302: New
Release 1.00.


12 PEP 302: New Import Hooks

While it's been possible to write custom import hooks ever since the ihooks module was introduced in Python 1.3, no one has ever been really happy with it because writing new import hooks is difficult and messy. There have been various proposed alternatives such as the imputil and iu modules, but none of them has ever gained much acceptance, and none of them were easily usable from C code.

PEP 302 borrows ideas from its predecessors, especially from Gordon McMillan's iu module. Three new items are added to the sys module:

  • sys.path_hooks is a list of callable objects; most often they'll be classes. Each callable takes a string containing a path and either returns an importer object that will handle imports from this path or raises an ImportError exception if it can't handle this path.

  • sys.path_importer_cache caches importer objects for each path, so sys.path_hooks will only need to be traversed once for each path.

  • sys.meta_path is a list of importer objects that will be traversed before sys.path is checked. This list is initially empty, but user code can add objects to it. Additional built-in and frozen modules can be imported by an object added to this list.

Importer objects must have a single method, find_module(fullname, path=None). fullname will be a module or package name, e.g. "string" or "distutils.core". find_module() must return a loader object that has a single method, load_module(fullname), that creates and returns the corresponding module object.

Pseudo-code for Python's new import logic, therefore, looks something like this (simplified a bit; see PEP 302 for the full details):

for mp in sys.meta_path:
    loader = mp(fullname)
    if loader is not None:
        <module> = loader.load_module(fullname)

for path in sys.path:
    for hook in sys.path_hooks:
        try:
            importer = hook(path)
        except ImportError:
            # ImportError, so try the other path hooks
            pass
        else:
            loader = importer.find_module(fullname)
            <module> = loader.load_module(fullname)

# Not found!
raise ImportError

See Also:

PEP 302, New Import Hooks
Written by Just van Rossum and Paul Moore. Implemented by Just van Rossum.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 11 PEP 301: Package Up: What's New in Python Next: 13 PEP 305: Comma-separated
Release 1.00.


13 PEP 305: Comma-separated Files

Comma-separated files are a format frequently used for exporting data from databases and spreadsheets. Python 2.3 adds a parser for comma-separated files.

Comma-separated format is deceptively simple at first glance:

Costs,150,200,3.95

Read a line and call line.split(','): what could be simpler? But toss in string data that can contain commas, and things get more complicated:

"Costs",150,200,3.95,"Includes taxes, shipping, and sundry items"

A big ugly regular expression can parse this, but using the new csv package is much simpler:

import csv

input = open('datafile', 'rb')
reader = csv.reader(input)
for line in reader:
    print line

The reader function takes a number of different options. The field separator isn't limited to the comma and can be changed to any character, and so can the quoting and line-ending characters.

Different dialects of comma-separated files can be defined and registered; currently there are two dialects, both used by Microsoft Excel. A separate csv.writer class will generate comma-separated files from a succession of tuples or lists, quoting strings that contain the delimiter.

See Also:

PEP 305, CSV File API
Written and implemented by Kevin Altis, Dave Cole, Andrew McNamara, Skip Montanaro, Cliff Wells.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 12 PEP 302: New Up: What's New in Python Next: 14 PEP 307: Pickle
Release 1.00.


14 PEP 307: Pickle Enhancements

The pickle and cPickle modules received some attention during the 2.3 development cycle. In 2.2, new-style classes could be pickled without difficulty, but they weren't pickled very compactly; PEP 307 quotes a trivial example where a new-style class results in a pickled string three times longer than that for a classic class.

The solution was to invent a new pickle protocol. The pickle.dumps() function has supported a text-or-binary flag for a long time. In 2.3, this flag is redefined from a Boolean to an integer: 0 is the old text-mode pickle format, 1 is the old binary format, and now 2 is a new 2.3-specific format. A new constant, pickle.HIGHEST_PROTOCOL, can be used to select the fanciest protocol available.

Unpickling is no longer considered a safe operation. 2.2's pickle provided hooks for trying to prevent unsafe classes from being unpickled (specifically, a __safe_for_unpickling__ attribute), but none of this code was ever audited and therefore it's all been ripped out in 2.3. You should not unpickle untrusted data in any version of Python.

To reduce the pickling overhead for new-style classes, a new interface for customizing pickling was added using three special methods: __getstate__, __setstate__, and __getnewargs__. Consult PEP 307 for the full semantics of these methods.

As a way to compress pickles yet further, it's now possible to use integer codes instead of long strings to identify pickled classes. The Python Software Foundation will maintain a list of standardized codes; there's also a range of codes for private use. Currently no codes have been specified.

See Also:

PEP 307, Extensions to the pickle protocol
Written and implemented by Guido van Rossum and Tim Peters.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 13 PEP 305: Comma-separated Up: What's New in Python Next: 15 Extended Slices
Release 1.00.


15 Extended Slices

Ever since Python 1.4, the slicing syntax has supported an optional third ``step'' or ``stride'' argument. For example, these are all legal Python syntax: L[1:10:2], L[:-1:1], L[::-1]. This was added to Python at the request of the developers of Numerical Python, which uses the third argument extensively. However, Python's built-in list, tuple, and string sequence types have never supported this feature, raising a TypeError if you tried it. Michael Hudson contributed a patch to fix this shortcoming.

For example, you can now easily extract the elements of a list that have even indexes:

>>> L = range(10)
>>> L[::2]
[0, 2, 4, 6, 8]

Negative values also work to make a copy of the same list in reverse order:

>>> L[::-1]
[9, 8, 7, 6, 5, 4, 3, 2, 1, 0]

This also works for tuples, arrays, and strings:

>>> s='abcd'
>>> s[::2]
'ac'
>>> s[::-1]
'dcba'

If you have a mutable sequence such as a list or an array you can assign to or delete an extended slice, but there are some differences between assignment to extended and regular slices. Assignment to a regular slice can be used to change the length of the sequence:

>>> a = range(3)
>>> a
[0, 1, 2]
>>> a[1:3] = [4, 5, 6]
>>> a
[0, 4, 5, 6]

Extended slices aren't this flexible. When assigning to an extended slice, the list on the right hand side of the statement must contain the same number of items as the slice it is replacing:

>>> a = range(4)
>>> a
[0, 1, 2, 3]
>>> a[::2]
[0, 2]
>>> a[::2] = [0, -1]
>>> a
[0, 1, -1, 3]
>>> a[::2] = [0,1,2]
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
ValueError: attempt to assign sequence of size 3 to extended slice of size 2

Deletion is more straightforward:

>>> a = range(4)
>>> a
[0, 1, 2, 3]
>>> a[::2]
[0, 2]
>>> del a[::2]
>>> a
[1, 3]

One can also now pass slice objects to the __getitem__ methods of the built-in sequences:

>>> range(10).__getitem__(slice(0, 5, 2))
[0, 2, 4]

Or use slice objects directly in subscripts:

>>> range(10)[slice(0, 5, 2)]
[0, 2, 4]

To simplify implementing sequences that support extended slicing, slice objects now have a method indices(length) which, given the length of a sequence, returns a (start, stop, step) tuple that can be passed directly to range(). indices() handles omitted and out-of-bounds indices in a manner consistent with regular slices (and this innocuous phrase hides a welter of confusing details!). The method is intended to be used like this:

class FakeSeq:
    ...
    def calc_item(self, i):
        ...
    def __getitem__(self, item):
        if isinstance(item, slice):
            indices = item.indices(len(self))
            return FakeSeq([self.calc_item(i) for i in range(*indices)])
        else:
            return self.calc_item(i)

From this example you can also see that the built-in slice object is now the type object for the slice type, and is no longer a function. This is consistent with Python 2.2, where int, str, etc., underwent the same change.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 14 PEP 307: Pickle Up: What's New in Python Next: 16 Other Language Changes
Release 1.00.


16 Other Language Changes

Here are all of the changes that Python 2.3 makes to the core Python language.

  • The yield statement is now always a keyword, as described in section 2 of this document.

  • A new built-in function enumerate() was added, as described in section 7 of this document.

  • Two new constants, True and False were added along with the built-in bool type, as described in section 9 of this document.

  • The int() type constructor will now return a long integer instead of raising an OverflowError when a string or floating-point number is too large to fit into an integer. This can lead to the paradoxical result that isinstance(int(expression), int) is false, but that seems unlikely to cause problems in practice.

  • Built-in types now support the extended slicing syntax, as described in section 15 of this document.

  • A new built-in function, sum(iterable, start=0), adds up the numeric items in the iterable object and returns their sum. sum() only accepts numbers, meaning that you can't use it to concatenate a bunch of strings. (Contributed by Alex Martelli.)

  • list.insert(pos, value) used to insert value at the front of the list when pos was negative. The behaviour has now been changed to be consistent with slice indexing, so when pos is -1 the value will be inserted before the last element, and so forth.

  • list.index(value), which searches for value within the list and returns its index, now takes optional start and stop arguments to limit the search to only part of the list.

  • Dictionaries have a new method, pop(key[, default]), that returns the value corresponding to key and removes that key/value pair from the dictionary. If the requested key isn't present in the dictionary, default is returned if it's specified and KeyError raised if it isn't.

    >>> d = {1:2}
>>> d
{1: 2}
>>> d.pop(4)
Traceback (most recent call last):
  File "stdin", line 1, in ?
KeyError: 4
>>> d.pop(1)
2
>>> d.pop(1)
Traceback (most recent call last):
  File "stdin", line 1, in ?
KeyError: 'pop(): dictionary is empty'
>>> d
{}
>>>

    There's also a new class method, dict.fromkeys(iterable, value), that creates a dictionary with keys taken from the supplied iterator iterable and all values set to value, defaulting to None.

    (Patches contributed by Raymond Hettinger.)

    Also, the dict() constructor now accepts keyword arguments to simplify creating small dictionaries:

    >>> dict(red=1, blue=2, green=3, black=4)
{'blue': 2, 'black': 4, 'green': 3, 'red': 1}

    (Contributed by Just van Rossum.)

  • The assert statement no longer checks the __debug__ flag, so you can no longer disable assertions by assigning to __debug__. Running Python with the -O switch will still generate code that doesn't execute any assertions.

  • Most type objects are now callable, so you can use them to create new objects such as functions, classes, and modules. (This means that the new module can be deprecated in a future Python version, because you can now use the type objects available in the types module.) For example, you can create a new module object with the following code:

    >>> import types
>>> m = types.ModuleType('abc','docstring')
>>> m
<module 'abc' (built-in)>
>>> m.__doc__
'docstring'

  • A new warning, PendingDeprecationWarning was added to indicate features which are in the process of being deprecated. The warning will not be printed by default. To check for use of features that will be deprecated in the future, supply -Walways::PendingDeprecationWarning:: on the command line or use warnings.filterwarnings().

  • The process of deprecating string-based exceptions, as in raise "Error occurred", has begun. Raising a string will now trigger PendingDeprecationWarning.

  • Using None as a variable name will now result in a SyntaxWarning warning. In a future version of Python, None may finally become a keyword.

  • The xreadlines() method of file objects, introduced in Python 2.1, is no longer necessary because files now behave as their own iterator. xreadlines() was originally introduced as a faster way to loop over all the lines in a file, but now you can simply write for line in file_obj. File objects also have a new read-only encoding attribute that gives the encoding used by the file; Unicode strings written to the file will be automatically converted to bytes using the given encoding.

  • The method resolution order used by new-style classes has changed, though you'll only notice the difference if you have a really complicated inheritance hierarchy. Classic classes are unaffected by this change. Python 2.2 originally used a topological sort of a class's ancestors, but 2.3 now uses the C3 algorithm as described in the paper ``A Monotonic Superclass Linearization for Dylan''. To understand the motivation for this change, read Michele Simionato's article ``Python 2.3 Method Resolution Order'', or read the thread on python-dev starting with the message at http://mail.python.org/pipermail/python-dev/2002-October/029035.html. Samuele Pedroni first pointed out the problem and also implemented the fix by coding the C3 algorithm.

  • Python runs multithreaded programs by switching between threads after executing N bytecodes. The default value for N has been increased from 10 to 100 bytecodes, speeding up single-threaded applications by reducing the switching overhead. Some multithreaded applications may suffer slower response time, but that's easily fixed by setting the limit back to a lower number using sys.setcheckinterval(N). The limit can be retrieved with the new sys.getcheckinterval() function.

  • One minor but far-reaching change is that the names of extension types defined by the modules included with Python now contain the module and a "." in front of the type name. For example, in Python 2.2, if you created a socket and printed its __class__, you'd get this output:

    >>> s = socket.socket()
>>> s.__class__
<type 'socket'>

    In 2.3, you get this:

    >>> s.__class__
<type '_socket.socket'>

  • One of the noted incompatibilities between old- and new-style classes has been removed: you can now assign to the __name__ and __bases__ attributes of new-style classes. There are some restrictions on what can be assigned to __bases__ along the lines of those relating to assigning to an instance's __class__ attribute.

16.1 String Changes

  • The in operator now works differently for strings. Previously, when evaluating X in Y where X and Y are strings, X could only be a single character. That's now changed; X can be a string of any length, and X in Y will return True if X is a substring of Y. If X is the empty string, the result is always True.

    >>> 'ab' in 'abcd'
True
>>> 'ad' in 'abcd'
False
>>> '' in 'abcd'
True

    Note that this doesn't tell you where the substring starts; if you need that information, use the find() string method.

  • The strip(), lstrip(), and rstrip() string methods now have an optional argument for specifying the characters to strip. The default is still to remove all whitespace characters:

    >>> '   abc '.strip()
'abc'
>>> '><><abc<><><>'.strip('<>')
'abc'
>>> '><><abc<><><>\n'.strip('<>')
'abc<><><>\n'
>>> u'\u4000\u4001abc\u4000'.strip(u'\u4000')
u'\u4001abc'
>>>

    (Suggested by Simon Brunning and implemented by Walter Dörwald.)

  • The startswith() and endswith() string methods now accept negative numbers for the start and end parameters.

  • Another new string method is zfill(), originally a function in the string module. zfill() pads a numeric string with zeros on the left until it's the specified width. Note that the % operator is still more flexible and powerful than zfill().

    >>> '45'.zfill(4)
'0045'
>>> '12345'.zfill(4)
'12345'
>>> 'goofy'.zfill(6)
'0goofy'

    (Contributed by Walter Dörwald.)

  • A new type object, basestring, has been added. Both 8-bit strings and Unicode strings inherit from this type, so isinstance(obj, basestring) will return True for either kind of string. It's a completely abstract type, so you can't create basestring instances.

  • Interned strings are no longer immortal and will now be garbage-collected in the usual way when the only reference to them is from the internal dictionary of interned strings. (Implemented by Oren Tirosh.)

16.2 Optimizations

  • The creation of new-style class instances has been made much faster; they're now faster than classic classes!

  • The sort() method of list objects has been extensively rewritten by Tim Peters, and the implementation is significantly faster.

  • Multiplication of large long integers is now much faster thanks to an implementation of Karatsuba multiplication, an algorithm that scales better than the O(n*n) required for the grade-school multiplication algorithm. (Original patch by Christopher A. Craig, and significantly reworked by Tim Peters.)

  • The SET_LINENO opcode is now gone. This may provide a small speed increase, depending on your compiler's idiosyncrasies. See section 20 for a longer explanation. (Removed by Michael Hudson.)

  • xrange() objects now have their own iterator, making for i in xrange(n) slightly faster than for i in range(n). (Patch by Raymond Hettinger.)

  • A number of small rearrangements have been made in various hotspots to improve performance, such as inlining a function or removing some code. (Implemented mostly by GvR, but lots of people have contributed single changes.)

The net result of the 2.3 optimizations is that Python 2.3 runs the pystone benchmark around 25% faster than Python 2.2.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 15 Extended Slices Up: What's New in Python Next: 17 New, Improved, and
Release 1.00.


17 New, Improved, and Deprecated Modules

As usual, Python's standard library received a number of enhancements and bug fixes. Here's a partial list of the most notable changes, sorted alphabetically by module name. Consult the Misc/NEWS file in the source tree for a more complete list of changes, or look through the CVS logs for all the details.

  • The array module now supports arrays of Unicode characters using the "u" format character. Arrays also now support using the += assignment operator to add another array's contents, and the *= assignment operator to repeat an array. (Contributed by Jason Orendorff.)

  • The bsddb module has been replaced by version 4.1.6 of the PyBSDDB package, providing a more complete interface to the transactional features of the BerkeleyDB library.

    The old version of the module has been renamed to bsddb185 and is no longer built automatically; you'll have to edit Modules/Setup to enable it. Note that the new bsddb package is intended to be compatible with the old module, so be sure to file bugs if you discover any incompatibilities. When upgrading to Python 2.3, if the new interpreter is compiled with a new version of the underlying BerkeleyDB library, you will almost certainly have to convert your database files to the new version. You can do this fairly easily with the new scripts db2pickle.py and pickle2db.py which you will find in the distribution's Tools/scripts directory. If you've already been using the PyBSDDB package and importing it as bsddb3, you will have to change your import statements to import it as bsddb.

  • The new bz2 module is an interface to the bz2 data compression library. bz2-compressed data is usually smaller than corresponding zlib-compressed data. (Contributed by Gustavo Niemeyer.)

  • A set of standard date/type types has been added in the new datetime module. See the following section for more details.

  • The Distutils Extension class now supports an extra constructor argument named depends for listing additional source files that an extension depends on. This lets Distutils recompile the module if any of the dependency files are modified. For example, if sampmodule.c includes the header file sample.h, you would create the Extension object like this:

    ext = Extension("samp",
                sources=["sampmodule.c"],
                depends=["sample.h"])

    Modifying sample.h would then cause the module to be recompiled. (Contributed by Jeremy Hylton.)

  • Other minor changes to Distutils: it now checks for the CC, CFLAGS, CPP, LDFLAGS, and CPPFLAGS environment variables, using them to override the settings in Python's configuration (contributed by Robert Weber).

  • Previously the doctest module would only search the docstrings of public methods and functions for test cases, but it now also examines private ones as well. The DocTestSuite( function creates a unittest.TestSuite object from a set of doctest tests.

  • The new gc.get_referents(object) function returns a list of all the objects referenced by object.

  • The getopt module gained a new function, gnu_getopt(), that supports the same arguments as the existing getopt() function but uses GNU-style scanning mode. The existing getopt() stops processing options as soon as a non-option argument is encountered, but in GNU-style mode processing continues, meaning that options and arguments can be mixed. For example:

    >>> getopt.getopt(['-f', 'filename', 'output', '-v'], 'f:v')
([('-f', 'filename')], ['output', '-v'])
>>> getopt.gnu_getopt(['-f', 'filename', 'output', '-v'], 'f:v')
([('-f', 'filename'), ('-v', '')], ['output'])

    (Contributed by Peter Åstrand.)

  • The grp, pwd, and resource modules now return enhanced tuples:

    >>> import grp
>>> g = grp.getgrnam('amk')
>>> g.gr_name, g.gr_gid
('amk', 500)

  • The gzip module can now handle files exceeding 2 Gb.

  • The new heapq module contains an implementation of a heap queue algorithm. A heap is an array-like data structure that keeps items in a partially sorted order such that, for every index k, heap[k] <= heap[2*k+1] and heap[k] <= heap[2*k+2]. This makes it quick to remove the smallest item, and inserting a new item while maintaining the heap property is O(lg n). (See http://www.nist.gov/dads/HTML/priorityque.html for more information about the priority queue data structure.)

    The heapq module provides heappush() and heappop() functions for adding and removing items while maintaining the heap property on top of some other mutable Python sequence type. Here's an example that uses a Python list:

    >>> import heapq
>>> heap = []
>>> for item in [3, 7, 5, 11, 1]:
...    heapq.heappush(heap, item)
...
>>> heap
[1, 3, 5, 11, 7]
>>> heapq.heappop(heap)
1
>>> heapq.heappop(heap)
3
>>> heap
[5, 7, 11]

    (Contributed by Kevin O'Connor.)

  • The IDLE integrated development environment has been updated using the code from the IDLEfork project (http://idlefork.sf.net). The most notable feature is that the code being developed is now executed in a subprocess, meaning that there's no longer any need for manual reload() operations. IDLE's core code has been incorporated into the standard library as the idlelib package.

  • The imaplib module now supports IMAP over SSL. (Contributed by Piers Lauder and Tino Lange.)

  • The itertools contains a number of useful functions for use with iterators, inspired by various functions provided by the ML and Haskell languages. For example, itertools.ifilter(predicate, iterator) returns all elements in the iterator for which the function predicate() returns True, and itertools.repeat(obj, N) returns obj N times. There are a number of other functions in the module; see the package's reference documentation for details. (Contributed by Raymond Hettinger.)

  • Two new functions in the math module, degrees(rads) and radians(degs), convert between radians and degrees. Other functions in the math module such as math.sin() and math.cos() have always required input values measured in radians. Also, an optional base argument was added to math.log() to make it easier to compute logarithms for bases other than e and 10. (Contributed by Raymond Hettinger.)

  • Several new POSIX functions (getpgid(), killpg(), lchown(), loadavg(), major(), makedev(), minor(), and mknod()) were added to the posix module that underlies the os module. (Contributed by Gustavo Niemeyer, Geert Jansen, and Denis S. Otkidach.)

  • In the os module, the *stat() family of functions can now report fractions of a second in a timestamp. Such time stamps are represented as floats, similar to the value returned by time.time().

    During testing, it was found that some applications will break if time stamps are floats. For compatibility, when using the tuple interface of the stat_result time stamps will be represented as integers. When using named fields (a feature first introduced in Python 2.2), time stamps are still represented as integers, unless os.stat_float_times() is invoked to enable float return values:

    >>> os.stat("/tmp").st_mtime
1034791200
>>> os.stat_float_times(True)
>>> os.stat("/tmp").st_mtime
1034791200.6335014

    In Python 2.4, the default will change to always returning floats.

    Application developers should enable this feature only if all their libraries work properly when confronted with floating point time stamps, or if they use the tuple API. If used, the feature should be activated on an application level instead of trying to enable it on a per-use basis.

  • The optparse module contains a new parser for command-line arguments that can convert option values to a particular Python type and will automatically generate a usage message. See the following section for more details.

  • The old and never-documented linuxaudiodev module has been deprecated, and a new version named ossaudiodev has been added. The module was renamed because the OSS sound drivers can be used on platforms other than Linux, and the interface has also been tidied and brought up to date in various ways. (Contributed by Greg Ward and Nicholas FitzRoy-Dale.)

  • The new platform module contains a number of functions that try to determine various properties of the platform you're running on. There are functions for getting the architecture, CPU type, the Windows OS version, and even the Linux distribution version. (Contributed by Marc-André Lemburg.)

  • The parser objects provided by the pyexpat module can now optionally buffer character data, resulting in fewer calls to your character data handler and therefore faster performance. Setting the parser object's buffer_text attribute to True will enable buffering.

  • The sample(population, k) function was added to the random module. population is a sequence or xrange object containing the elements of a population, and sample() chooses k elements from the population without replacing chosen elements. k can be any value up to len(population). For example:

    >>> days = ['Mo', 'Tu', 'We', 'Th', 'Fr', 'St', 'Sn']
>>> random.sample(days, 3)      # Choose 3 elements
['St', 'Sn', 'Th']
>>> random.sample(days, 7)      # Choose 7 elements
['Tu', 'Th', 'Mo', 'We', 'St', 'Fr', 'Sn']
>>> random.sample(days, 7)      # Choose 7 again
['We', 'Mo', 'Sn', 'Fr', 'Tu', 'St', 'Th']
>>> random.sample(days, 8)      # Can't choose eight
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
  File "random.py", line 414, in sample
      raise ValueError, "sample larger than population"
ValueError: sample larger than population
>>> random.sample(xrange(1,10000,2), 10)   # Choose ten odd nos. under 10000
[3407, 3805, 1505, 7023, 2401, 2267, 9733, 3151, 8083, 9195]

    The random module now uses a new algorithm, the Mersenne Twister, implemented in C. It's faster and more extensively studied than the previous algorithm.

    (All changes contributed by Raymond Hettinger.)

  • The readline module also gained a number of new functions: get_history_item(), get_current_history_length(), and redisplay().

  • The rexec and Bastion modules have been declared dead, and attempts to import them will fail with a RuntimeError. New-style classes provide new ways to break out of the restricted execution environment provided by rexec, and no one has interest in fixing them or time to do so. If you have applications using rexec, rewrite them to use something else.

    (Sticking with Python 2.2 or 2.1 will not make your applications any safer because there are known bugs in the rexec module in those versions. To repeat: if you're using rexec, stop using it immediately.)

  • The rotor module has been deprecated because the algorithm it uses for encryption is not believed to be secure. If you need encryption, use one of the several AES Python modules that are available separately.

  • The shutil module gained a move(src, dest) function that recursively moves a file or directory to a new location.

  • Support for more advanced POSIX signal handling was added to the signal but then removed again as it proved impossible to make it work reliably across platforms.

  • The socket module now supports timeouts. You can call the settimeout(t) method on a socket object to set a timeout of t seconds. Subsequent socket operations that take longer than t seconds to complete will abort and raise a socket.timeout exception.

    The original timeout implementation was by Tim O'Malley. Michael Gilfix integrated it into the Python socket module and shepherded it through a lengthy review. After the code was checked in, Guido van Rossum rewrote parts of it. (This is a good example of a collaborative development process in action.)

  • On Windows, the socket module now ships with Secure Sockets Layer (SSL) support.

  • The value of the C PYTHON_API_VERSION macro is now exposed at the Python level as sys.api_version. The current exception can be cleared by calling the new sys.exc_clear() function.

  • The new tarfile module allows reading from and writing to tar-format archive files. (Contributed by Lars Gustäbel.)

  • The new textwrap module contains functions for wrapping strings containing paragraphs of text. The wrap(text, width) function takes a string and returns a list containing the text split into lines of no more than the chosen width. The fill(text, width) function returns a single string, reformatted to fit into lines no longer than the chosen width. (As you can guess, fill() is built on top of wrap(). For example:

    >>> import textwrap
>>> paragraph = "Not a whit, we defy augury: ... more text ..."
>>> textwrap.wrap(paragraph, 60)
["Not a whit, we defy augury: there's a special providence in",
 "the fall of a sparrow. If it be now, 'tis not to come; if it",
 ...]
>>> print textwrap.fill(paragraph, 35)
Not a whit, we defy augury: there's
a special providence in the fall of
a sparrow. If it be now, 'tis not
to come; if it be not to come, it
will be now; if it be not now, yet
it will come: the readiness is all.
>>>

    The module also contains a TextWrapper class that actually implements the text wrapping strategy. Both the TextWrapper class and the wrap() and fill() functions support a number of additional keyword arguments for fine-tuning the formatting; consult the module's documentation for details. (Contributed by Greg Ward.)

  • The thread and threading modules now have companion modules, dummy_thread and dummy_threading, that provide a do-nothing implementation of the thread module's interface for platforms where threads are not supported. The intention is to simplify thread-aware modules (ones that don't rely on threads to run) by putting the following code at the top:

    try:
    import threading as _threading
except ImportError:
    import dummy_threading as _threading

    In this example, _threading is used as the module name to make it clear that the module being used is not necessarily the actual threading module. Code can call functions and use classes in _threading whether or not threads are supported, avoiding an if statement and making the code slightly clearer. This module will not magically make multithreaded code run without threads; code that waits for another thread to return or to do something will simply hang forever.

  • The time module's strptime() function has long been an annoyance because it uses the platform C library's strptime() implementation, and different platforms sometimes have odd bugs. Brett Cannon contributed a portable implementation that's written in pure Python and should behave identically on all platforms.

  • The new timeit module helps measure how long snippets of Python code take to execute. The timeit.py file can be run directly from the command line, or the module's Timer class can be imported and used directly. Here's a short example that figures out whether it's faster to convert an 8-bit string to Unicode by appending an empty Unicode string to it or by using the unicode() function:

    import timeit

timer1 = timeit.Timer('unicode("abc")')
timer2 = timeit.Timer('"abc" + u""')

# Run three trials
print timer1.repeat(repeat=3, number=100000)
print timer2.repeat(repeat=3, number=100000)

# On my laptop this outputs:
# [0.36831796169281006, 0.37441694736480713, 0.35304892063140869]
# [0.17574405670166016, 0.18193507194519043, 0.17565798759460449]

  • The Tix module has received various bug fixes and updates for the current version of the Tix package.

  • The Tkinter module now works with a thread-enabled version of Tcl. Tcl's threading model requires that widgets only be accessed from the thread in which they're created; accesses from another thread can cause Tcl to panic. For certain Tcl interfaces, Tkinter will now automatically avoid this when a widget is accessed from a different thread by marshalling a command, passing it to the correct thread, and waiting for the results. Other interfaces can't be handled automatically but Tkinter will now raise an exception on such an access so that you can at least find out about the problem. See http://mail.python.org/pipermail/python-dev/2002-December/031107.html for a more detailed explanation of this change. (Implemented by Martin von Löwis.)

  • Calling Tcl methods through _tkinter no longer returns only strings. Instead, if Tcl returns other objects those objects are converted to their Python equivalent, if one exists, or wrapped with a _tkinter.Tcl_Obj object if no Python equivalent exists. This behavior can be controlled through the wantobjects() method of tkapp objects.

    When using _tkinter through the Tkinter module (as most Tkinter applications will), this feature is always activated. It should not cause compatibility problems, since Tkinter would always convert string results to Python types where possible.

    If any incompatibilities are found, the old behavior can be restored by setting the wantobjects variable in the Tkinter module to false before creating the first tkapp object.

    import Tkinter
Tkinter.wantobjects = 0

    Any breakage caused by this change should be reported as a bug.

  • The UserDict module has a new DictMixin class which defines all dictionary methods for classes that already have a minimum mapping interface. This greatly simplifies writing classes that need to be substitutable for dictionaries, such as the classes in the shelve module.

    Adding the mix-in as a superclass provides the full dictionary interface whenever the class defines __getitem__, __setitem__, __delitem__, and keys. For example:

    >>> import UserDict
>>> class SeqDict(UserDict.DictMixin):
...     """Dictionary lookalike implemented with lists."""
...     def __init__(self):
...         self.keylist = []
...         self.valuelist = []
...     def __getitem__(self, key):
...         try:
...             i = self.keylist.index(key)
...         except ValueError:
...             raise KeyError
...         return self.valuelist[i]
...     def __setitem__(self, key, value):
...         try:
...             i = self.keylist.index(key)
...             self.valuelist[i] = value
...         except ValueError:
...             self.keylist.append(key)
...             self.valuelist.append(value)
...     def __delitem__(self, key):
...         try:
...             i = self.keylist.index(key)
...         except ValueError:
...             raise KeyError
...         self.keylist.pop(i)
...         self.valuelist.pop(i)
...     def keys(self):
...         return list(self.keylist)
...
>>> s = SeqDict()
>>> dir(s)      # See that other dictionary methods are implemented
['__cmp__', '__contains__', '__delitem__', '__doc__', '__getitem__',
 '__init__', '__iter__', '__len__', '__module__', '__repr__',
 '__setitem__', 'clear', 'get', 'has_key', 'items', 'iteritems',
 'iterkeys', 'itervalues', 'keylist', 'keys', 'pop', 'popitem',
 'setdefault', 'update', 'valuelist', 'values']

    (Contributed by Raymond Hettinger.)

  • The DOM implementation in xml.dom.minidom can now generate XML output in a particular encoding by providing an optional encoding argument to the toxml() and toprettyxml() methods of DOM nodes.

  • The xmlrpclib module now supports an XML-RPC extension for handling nil data values such as Python's None. Nil values are always supported on unmarshalling an XML-RPC response. To generate requests containing None, you must supply a true value for the allow_none parameter when creating a Marshaller instance.

  • The new DocXMLRPCServer module allows writing self-documenting XML-RPC servers. Run it in demo mode (as a program) to see it in action. Pointing the Web browser to the RPC server produces pydoc-style documentation; pointing xmlrpclib to the server allows invoking the actual methods. (Contributed by Brian Quinlan.)

  • Support for internationalized domain names (RFCs 3454, 3490, 3491, and 3492) has been added. The ``idna'' encoding can be used to convert between a Unicode domain name and the ASCII-compatible encoding (ACE) of that name.

 >>> u"www.Alliancefran¸ caise.nu".encode("idna")
 'www.xn-alliancefranaise-npb.nu'

    The socket module has also been extended to transparently convert Unicode hostnames to the ACE version before passing them to the C library. Modules that deal with hostnames such as httplib and ftplib) also support Unicode host names; httplib also sends HTTP "Host" headers using the ACE version of the domain name. urllib supports Unicode URLs with non-ASCII host names as long as the path part of the URL is ASCII only.

    To implement this change, the stringprep module, the mkstringprep tool and the punycode encoding have been added.

17.1 Date/Time Type

Date and time types suitable for expressing timestamps were added as the datetime module. The types don't support different calendars or many fancy features, and just stick to the basics of representing time.

The three primary types are: date, representing a day, month, and year; time, consisting of hour, minute, and second; and datetime, which contains all the attributes of both date and time. There's also a timedelta class representing differences between two points in time, and time zone logic is implemented by classes inheriting from the abstract tzinfo class.

You can create instances of date and time by either supplying keyword arguments to the appropriate constructor, e.g. datetime.date(year=1972, month=10, day=15), or by using one of a number of class methods. For example, the date.today() class method returns the current local date.

Once created, instances of the date/time classes are all immutable. There are a number of methods for producing formatted strings from objects:

>>> import datetime
>>> now = datetime.datetime.now()
>>> now.isoformat()
'2002-12-30T21:27:03.994956'
>>> now.ctime()  # Only available on date, datetime
'Mon Dec 30 21:27:03 2002'
>>> now.strftime('%Y %d %b')
'2002 30 Dec'

The replace() method allows modifying one or more fields of a date or datetime instance, returning a new instance:

>>> d = datetime.datetime.now()
>>> d
datetime.datetime(2002, 12, 30, 22, 15, 38, 827738)
>>> d.replace(year=2001, hour = 12)
datetime.datetime(2001, 12, 30, 12, 15, 38, 827738)
>>>

Instances can be compared, hashed, and converted to strings (the result is the same as that of isoformat()). date and datetime instances can be subtracted from each other, and added to timedelta instances. The largest missing feature is that there's no standard library support for parsing strings and getting back a date or datetime.

For more information, refer to the module's reference documentation. (Contributed by Tim Peters.)

17.2 The optparse Module

The getopt module provides simple parsing of command-line arguments. The new optparse module (originally named Optik) provides more elaborate command-line parsing that follows the Unix conventions, automatically creates the output for --help, and can perform different actions for different options.

You start by creating an instance of OptionParser and telling it what your program's options are.

import sys
from optparse import OptionParser

op = OptionParser()
op.add_option('-i', '--input',
              action='store', type='string', dest='input',
              help='set input filename')
op.add_option('-l', '--length',
              action='store', type='int', dest='length',
              help='set maximum length of output')

Parsing a command line is then done by calling the parse_args() method.

options, args = op.parse_args(sys.argv[1:])
print options
print args

This returns an object containing all of the option values, and a list of strings containing the remaining arguments.

Invoking the script with the various arguments now works as you'd expect it to. Note that the length argument is automatically converted to an integer.

$ ./python opt.py -i data arg1
<Values at 0x400cad4c: {'input': 'data', 'length': None}>
['arg1']
$ ./python opt.py --input=data --length=4
<Values at 0x400cad2c: {'input': 'data', 'length': 4}>
[]
$

The help message is automatically generated for you:

$ ./python opt.py --help
usage: opt.py [options]

options:
  -h, --help            show this help message and exit
  -iINPUT, --input=INPUT
                        set input filename
  -lLENGTH, --length=LENGTH
                        set maximum length of output
$

See the module's documentation for more details.

Optik was written by Greg Ward, with suggestions from the readers of the Getopt SIG.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 16 Other Language Changes Up: What's New in Python Next: 18 Pymalloc: A Specialized
Release 1.00.


18 Pymalloc: A Specialized Object Allocator

Pymalloc, a specialized object allocator written by Vladimir Marangozov, was a feature added to Python 2.1. Pymalloc is intended to be faster than the system malloc() and to have less memory overhead for allocation patterns typical of Python programs. The allocator uses C's malloc() function to get large pools of memory and then fulfills smaller memory requests from these pools.

In 2.1 and 2.2, pymalloc was an experimental feature and wasn't enabled by default; you had to explicitly enable it when compiling Python by providing the --with-pymalloc option to the configure script. In 2.3, pymalloc has had further enhancements and is now enabled by default; you'll have to supply --without-pymalloc to disable it.

This change is transparent to code written in Python; however, pymalloc may expose bugs in C extensions. Authors of C extension modules should test their code with pymalloc enabled, because some incorrect code may cause core dumps at runtime.

There's one particularly common error that causes problems. There are a number of memory allocation functions in Python's C API that have previously just been aliases for the C library's malloc() and free(), meaning that if you accidentally called mismatched functions the error wouldn't be noticeable. When the object allocator is enabled, these functions aren't aliases of malloc() and free() any more, and calling the wrong function to free memory may get you a core dump. For example, if memory was allocated using PyObject_Malloc(), it has to be freed using PyObject_Free(), not free(). A few modules included with Python fell afoul of this and had to be fixed; doubtless there are more third-party modules that will have the same problem.

As part of this change, the confusing multiple interfaces for allocating memory have been consolidated down into two API families. Memory allocated with one family must not be manipulated with functions from the other family. There is one family for allocating chunks of memory and another family of functions specifically for allocating Python objects.

  • To allocate and free an undistinguished chunk of memory use the ``raw memory'' family: PyMem_Malloc(), PyMem_Realloc(), and PyMem_Free().

  • The ``object memory'' family is the interface to the pymalloc facility described above and is biased towards a large number of ``small'' allocations: PyObject_Malloc, PyObject_Realloc, and PyObject_Free.

  • To allocate and free Python objects, use the ``object'' family PyObject_New(), PyObject_NewVar(), and PyObject_Del().

Thanks to lots of work by Tim Peters, pymalloc in 2.3 also provides debugging features to catch memory overwrites and doubled frees in both extension modules and in the interpreter itself. To enable this support, compile a debugging version of the Python interpreter by running configure with --with-pydebug.

To aid extension writers, a header file Misc/pymemcompat.h is distributed with the source to Python 2.3 that allows Python extensions to use the 2.3 interfaces to memory allocation while compiling against any version of Python since 1.5.2. You would copy the file from Python's source distribution and bundle it with the source of your extension.

See Also:

http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/python/python/dist/src/Objects/obmalloc.c
For the full details of the pymalloc implementation, see the comments at the top of the file Objects/obmalloc.c in the Python source code. The above link points to the file within the SourceForge CVS browser.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 17 New, Improved, and Up: What's New in Python Next: 19 Build and C
Release 1.00.


19 Build and C API Changes

Changes to Python's build process and to the C API include:

  • The C-level interface to the garbage collector has been changed to make it easier to write extension types that support garbage collection and to debug misuses of the functions. Various functions have slightly different semantics, so a bunch of functions had to be renamed. Extensions that use the old API will still compile but will not participate in garbage collection, so updating them for 2.3 should be considered fairly high priority.

    To upgrade an extension module to the new API, perform the following steps:

    • Rename Py_TPFLAGS_GC to PyTPFLAGS_HAVE_GC.

    • Use PyObject_GC_New or PyObject_GC_NewVar to allocate objects, and PyObject_GC_Del to deallocate them.

    • Rename PyObject_GC_Init to PyObject_GC_Track and PyObject_GC_Fini to PyObject_GC_UnTrack.

    • Remove PyGC_HEAD_SIZE from object size calculations.

    • Remove calls to PyObject_AS_GC and PyObject_FROM_GC.

  • The cycle detection implementation used by the garbage collection has proven to be stable, so it's now been made mandatory. You can no longer compile Python without it, and the --with-cycle-gc switch to configure has been removed.

  • Python can now optionally be built as a shared library (libpython2.3.so) by supplying --enable-shared when running Python's configure script. (Contributed by Ondrej Palkovsky.)

  • The DL_EXPORT and DL_IMPORT macros are now deprecated. Initialization functions for Python extension modules should now be declared using the new macro PyMODINIT_FUNC, while the Python core will generally use the PyAPI_FUNC and PyAPI_DATA macros.

  • The interpreter can be compiled without any docstrings for the built-in functions and modules by supplying --without-doc-strings to the configure script. This makes the Python executable about 10% smaller, but will also mean that you can't get help for Python's built-ins. (Contributed by Gustavo Niemeyer.)

  • The PyArg_NoArgs() macro is now deprecated, and code that uses it should be changed. For Python 2.2 and later, the method definition table can specify the METH_NOARGS flag, signalling that there are no arguments, and the argument checking can then be removed. If compatibility with pre-2.2 versions of Python is important, the code could use PyArg_ParseTuple(args, "") instead, but this will be slower than using METH_NOARGS.

  • A new function, PyObject_DelItemString(mapping, char *key) was added as shorthand for PyObject_DelItem(mapping, PyString_New(key)).

  • File objects now manage their internal string buffer differently, increasing it exponentially when needed. This results in the benchmark tests in Lib/test/test_bufio.py speeding up considerably (from 57 seconds to 1.7 seconds, according to one measurement).

  • It's now possible to define class and static methods for a C extension type by setting either the METH_CLASS or METH_STATIC flags in a method's PyMethodDef structure.

  • Python now includes a copy of the Expat XML parser's source code, removing any dependence on a system version or local installation of Expat.

  • If you dynamically allocate type objects in your extension, you should be aware of a change in the rules relating to the __module__ and __name__ attributes. In summary, you will want to ensure the type's dictionary contains a '__module__' key; making the module name the part of the type name leading up to the final period will no longer have the desired effect. For more detail, read the API reference documentation or the source.

19.1 Port-Specific Changes

Support for a port to IBM's OS/2 using the EMX runtime environment was merged into the main Python source tree. EMX is a POSIX emulation layer over the OS/2 system APIs. The Python port for EMX tries to support all the POSIX-like capability exposed by the EMX runtime, and mostly succeeds; fork() and fcntl() are restricted by the limitations of the underlying emulation layer. The standard OS/2 port, which uses IBM's Visual Age compiler, also gained support for case-sensitive import semantics as part of the integration of the EMX port into CVS. (Contributed by Andrew MacIntyre.)

On MacOS, most toolbox modules have been weaklinked to improve backward compatibility. This means that modules will no longer fail to load if a single routine is missing on the curent OS version. Instead calling the missing routine will raise an exception. (Contributed by Jack Jansen.)

The RPM spec files, found in the Misc/RPM/ directory in the Python source distribution, were updated for 2.3. (Contributed by Sean Reifschneider.)

Other new platforms now supported by Python include AtheOS (http://www.atheos.cx/), GNU/Hurd, and OpenVMS.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 18 Pymalloc: A Specialized Up: What's New in Python Next: 20 Other Changes and
Release 1.00.


20 Other Changes and Fixes

As usual, there were a bunch of other improvements and bugfixes scattered throughout the source tree. A search through the CVS change logs finds there were 523 patches applied and 514 bugs fixed between Python 2.2 and 2.3. Both figures are likely to be underestimates.

Some of the more notable changes are:

  • If the PYTHONINSPECT environment variable is set, the Python interpreter will enter the interactive prompt after running a Python program, as if Python had been invoked with the -i option. The environment variable can be set before running the Python interpreter, or it can be set by the Python program as part of its execution.

  • The regrtest.py script now provides a way to allow ``all resources except foo.'' A resource name passed to the -u option can now be prefixed with a hyphen ("-") to mean ``remove this resource.'' For example, the option `-uall,-bsddb' could be used to enable the use of all resources except bsddb.

  • The tools used to build the documentation now work under Cygwin as well as Unix.

  • The SET_LINENO opcode has been removed. Back in the mists of time, this opcode was needed to produce line numbers in tracebacks and support trace functions (for, e.g., pdb). Since Python 1.5, the line numbers in tracebacks have been computed using a different mechanism that works with ``python -O''. For Python 2.3 Michael Hudson implemented a similar scheme to determine when to call the trace function, removing the need for SET_LINENO entirely.

    It would be difficult to detect any resulting difference from Python code, apart from a slight speed up when Python is run without -O.

    C extensions that access the f_lineno field of frame objects should instead call PyCode_Addr2Line(f->f_code, f->f_lasti). This will have the added effect of making the code work as desired under ``python -O'' in earlier versions of Python.

    A nifty new feature is that trace functions can now assign to the f_lineno attribute of frame objects, changing the line that will be executed next. A "jump" command has been added to the pdb debugger taking advantage of this new feature. (Implemented by Richie Hindle.)

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 19 Build and C Up: What's New in Python Next: 21 Porting to Python
Release 1.00.


21 Porting to Python 2.3

This section lists previously described changes that may require changes to your code:

  • yield is now always a keyword; if it's used as a variable name in your code, a different name must be chosen.

  • For strings X and Y, X in Y now works if X is more than one character long.

  • The int() type constructor will now return a long integer instead of raising an OverflowError when a string or floating-point number is too large to fit into an integer.

  • If you have Unicode strings that contain 8-bit characters, you must declare the file's encoding (UTF-8, Latin-1, or whatever) by adding a comment to the top of the file. See section 3 for more information.

  • Calling Tcl methods through _tkinter no longer returns only strings. Instead, if Tcl returns other objects those objects are converted to their Python equivalent, if one exists, or wrapped with a _tkinter.Tcl_Obj object if no Python equivalent exists.

  • Large octal and hex literals such as 0xffffffff now trigger a FutureWarning. Currently they're stored as 32-bit numbers and result in a negative value, but in Python 2.4 they'll become positive long integers.

    There are a few ways to fix this warning. If you really need a positive number, just add an "L" to the end of the literal. If you're trying to get a 32-bit integer with low bits set and have previously used an expression such as  (1 « 31), it's probably clearest to start with all bits set and clear the desired upper bits. For example, to clear just the top bit (bit 31), you could write 0xffffffffL &~(1L«31).

  • You can no longer disable assertions by assigning to __debug__.

  • The Distutils setup() function has gained various new keyword arguments such as depends. Old versions of the Distutils will abort if passed unknown keywords. A solution is to check for the presence of the new get_distutil_options() function in your setup.py and only uses the new keywords with a version of the Distutils that supports them:

    from distutils import core

kw = {'sources': 'foo.c', ...}
if hasattr(core, 'get_distutil_options'):
    kw['depends'] = ['foo.h']
ext = Extension(**kw)

  • Using None as a variable name will now result in a SyntaxWarning warning.

  • Names of extension types defined by the modules included with Python now contain the module and a "." in front of the type name.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 20 Other Changes and Up: What's New in Python Next: 22 Acknowledgements
Release 1.00.


22 Acknowledgements

The author would like to thank the following people for offering suggestions, corrections and assistance with various drafts of this article: Jeff Bauer, Simon Brunning, Brett Cannon, Michael Chermside, Andrew Dalke, Scott David Daniels, Fred L. Drake, Jr., David Fraser, Kelly Gerber, Raymond Hettinger, Michael Hudson, Chris Lambert, Detlef Lannert, Martin von Löwis, Andrew MacIntyre, Lalo Martins, Chad Netzer, Gustavo Niemeyer, Neal Norwitz, Hans Nowak, Chris Reedy, Francesco Ricciardi, Vinay Sajip, Neil Schemenauer, Roman Suzi, Jason Tishler, Just van Rossum.

Previous Page Up One Level Next Page What's New in Python 2.3 Contents
Previous: 21 Porting to Python Up: What's New in Python Next: この文書について...
Release 1.00.


Python チュートリアル

Guido van Rossum

PythonLabs
Email: docs@python.org

Fred L. Drake, Jr., editor

リリース 2.3.3
平成16年6月28日

日本語訳: Python ドキュメント翻訳プロジェクト

  • 序
  • 目次
  • 1. Python への意欲を高める
    • 1.1 ここからどこへ
  • 2. Python インタプリタを使う
    • 2.1 インタプリタを起動する
      • 2.1.1 引数の受け渡し
      • 2.1.2 対話モード
    • 2.2 インタプリタとその環境
      • 2.2.1 エラー処理
      • 2.2.2 実行可能な Python スクリプト
      • 2.2.3 ソースコードの文字コード方式 (encoding)
      • 2.2.4 対話モード用の起動時実行ファイル
  • 3. 形式ばらない Python の紹介
    • 3.1 Python を電卓として使う
      • 3.1.1 数
      • 3.1.2 文字列
      • 3.1.3 Unicode 文字列
      • 3.1.4 リスト
    • 3.2 プログラミングへの第一歩
  • 4. その他の制御フローツール
    • 4.1 if 文
    • 4.2 for 文
    • 4.3 range() 関数
    • 4.4 break 文と continue 文と ループの else 節
    • 4.5 pass 文
    • 4.6 関数を定義する
    • 4.7 関数定義についてもう少し
      • 4.7.1 デフォルトの引数値
      • 4.7.2 キーワード引数
      • 4.7.3 任意引数リスト
      • 4.7.4 引数リストのアンパック
      • 4.7.5 ラムダ形式
      • 4.7.6 ドキュメンテーション文字列
  • 5. データ構造
    • 5.1 リスト型についてもう少し
      • 5.1.1 リストをスタックとして使う
      • 5.1.2 リストをキューとして使う
      • 5.1.3 実用的なプログラミングツール
      • 5.1.4 リストの内包表記
    • 5.2 del 文
    • 5.3 タプルと配列
    • 5.4 辞書
    • 5.5 ループのテクニック
    • 5.6 条件についてもう少し
    • 5.7 配列とその他の型の比較
  • 6. モジュール
    • 6.1 モジュールについてもうすこし
      • 6.1.1 モジュール検索パス
      • 6.1.2 ``コンパイル'' された Python ファイル
    • 6.2 標準モジュール
    • 6.3 dir() 関数
    • 6.4 パッケージ
      • 6.4.1 パッケージから * を import する
      • 6.4.2 パッケージ内での参照
      • 6.4.3 複数ディレクトリ中のパッケージ
  • 7. 入力と出力
    • 7.1 ファンシーな出力の書式化
    • 7.2 ファイルを読み書きする
      • 7.2.1 ファイルオブジェクトのメソッド
      • 7.2.2 pickle モジュール
  • 8. エラーと例外
    • 8.1 構文エラー
    • 8.2 例外
    • 8.3 例外を処理する
    • 8.4 例外を送出する
    • 8.5 ユーザ定義の例外
    • 8.6 後片付け動作を定義する
  • 9. クラス
    • 9.1 用語について一言
    • 9.2 Python のスコープと名前空間
    • 9.3 クラス初見
      • 9.3.1 クラス定義の構文
      • 9.3.2 クラスオブジェクト
      • 9.3.3 インスタンスオブジェクト
      • 9.3.4 メソッドオブジェクト
    • 9.4 いろいろな注意点
    • 9.5 継承
      • 9.5.1 多重継承
    • 9.6 プライベート変数
    • 9.7 残りのはしばし
      • 9.7.1 例外はクラスであってもよい
    • 9.8 イテレータ (iterator)
    • 9.9 ジェネレータ (generator)
  • 10. 標準ライブラリの簡単なツアー
    • 10.1 オペレーティングシステムへのインタフェース
    • 10.2 ファイルのワイルドカード表記
    • 10.3 コマンドライン引数
    • 10.4 エラー出力のリダイレクトとプログラムの終了
    • 10.5 文字列のパターンマッチング
    • 10.6 数学
    • 10.7 インターネットへのアクセス
    • 10.8 日付と時刻
    • 10.9 データ圧縮
    • 10.10 パフォーマンスの計測
    • 10.11 品質管理
    • 10.12 一揃いあつらえ済み
  • 11. さあ何を？
  • A. 対話入力編集とヒストリ置換
    • A.1 行編集
    • A.2 ヒストリ置換
    • A.3 キー割り当て
    • A.4 解説
  • B. 浮動小数点演算、その問題と制限
    • B.1 表現エラー
  • C. 歴史とライセンス
    • C.1 History of the software
    • C.2 Terms and conditions for accessing or otherwise using Python
  • D. 日本語訳について
    • D.1 このドキュメントについて
    • D.2 翻訳者一覧 (敬称略)
  • E. 用語集
  • 索引
  • この文書について...
Up One Level Next Page Python チュートリアル Contents Index
Up: Python ドキュメントインデクス Next: 序
Release 2.3.3, documentation updated on 平成16年6月28日.


1. Python への意欲を高める

巨大なシェルスクリプトを書いたことがあるなら、 「もう一つ機能を追加したいのだけれど、プログラムはすでに遅くなりすぎて いるし、巨大すぎるし、複雑すぎる ...」、あるいは 「追加したい機能 にはシステムコールか、 C 言語からしかアクセスできない別の関数が必要 だ ...」 といった気持ちを理解できるでしょう。

身近な課題というのはたいてい、スクリプトを C 言語で書き直すほど大した ことではありません; そしてその課題にはおそらく可変長の文字列や (ファイル名をソートしたリストのような) 他のデータ型 が必要で、 これはシェルスクリプトで実装するのは簡単だが C 言語でやるのは大仕事に なるし、もしかするとあなた自身はそれほど C 言語に詳しくはないかも しれません。

別の状況として、「おそらくいくつかの C 言語のライブラリを使って 仕事をしなければならないのだけれど、C 言語でお決まりの、プログラム 作成／コンパイル／テスト／再コンパイルのサイクルは時間がかかりすぎる。 もっと早くプログラムを開発したい」、あるいは、「機能拡張のための 言語を使えるようなプログラムを書いたのだけれど、新しく言語を設計して、 その言語のためのインタプリタを実装して、テストして、自分の アプリケーションと連動させるまではやりたくない」といったことも あるでしょう。

これらのケースでは、Python はまさにあなたにぴったりの言語です。 Python は使い方は単純ですが、シェルスクリプトよりも多くのデータ 構造を扱うことができ、大規模なプログラムを行うためのサポートを 持った本物のプログラム言語です。一方で、 Python は C 言語よりも はるかに多くのエラーチェック機構を提供しています。また、 超高水準 (very-high-level) のプログラム言語で、柔軟性のある 配列や辞書といった高水準データ型が組み込まれています。これらの型を 効率よく処理するための実装を C 言語でやろうとすると数日がかりに なってしまうでしょう。比較的汎用性の高いデータ型を持つため、 Python は Awk や Perl さえはるかにしのぐ広い領域の 問題に適用することができます。その上、Python でやれば、多くの 仕事は上述の言語と少なくとも同じくらいに簡単にこなせます。

Python ではプログラムをモジュールに分割して他の Python プログラムで 再利用することができます。Python には膨大な標準モジュールが付属 していて、プログラムを作る上での基盤として -- あるいは Python プログラミングを学ぶために -- 利用することができます。組み込み モジュールではまた、ファイル I/O 、システムコール、ソケットといった 機能や、Tk のようなグラフィカルユーザインタフェースツールキットを使う ためのインタフェースさえも提供しています。

Python はインタプリタ言語です。このため、コンパイルやリンクが必要 ないので、プログラムを開発する際にかなりの時間を節約できます。 インタプリタは対話的に利用することもできます。対話的インタプリタの 利用によって、この言語の様々な機能について実験してみたり、やっつけ仕事 のプログラムを書いたり、ボトムアップでプログラムを開発する際に 関数をテストしたりといったことが簡単にできます。便利な電卓にもなります。

Python では、とてもコンパクトで読みやすいプログラムを書くことができます。 Python で書かれたプログラムは大抵、同じ機能を提供する C 言語や C++ 言語のプログラムよりもはるかに短くなります。これには以下のようないくつか の理由があります:

  • 高レベルのデータ型によって、複雑な操作を一つの実行文で表現することが できます;
  • 実行文のグループ化はグループの開始や終了の括弧を使う代わりに インデントで行うことができます;
  • 変数や引数の宣言が不要になります。

Python は 拡張する ことができます: C 言語でプログラムを書く方法 を知っているなら、新たな組み込み関数やモジュールをインタプリタに追加 することは簡単です。これによって、処理速度を決定的に左右する操作を 最大速度で動作するように実現したり、(ベンダ特有のグラフィクスライブラリ のように) バイナリ形式でしか手に入らないライブラリを Python にリンク したりできます。その気になれば、Python インタプリタを C で書かれた アプリケーションにリンクして、アプリケーションに対する拡張言語や 命令言語として使うこともできます。

ところで、この言語は BBC のショー番組、``モンティパイソンの空飛ぶ サーカス (Monty Python's Flying Circus)'' から取ったもので、 気味の悪い爬虫類とは関係ありません。このドキュメントにある モンティパイソンの寸劇を参照するのは、よいどころか、むしろ 奨励されています！

1.1 ここからどこへ

さて、皆さんはもう Python にとてもそそられて、もうちょっと詳しく 調べてみたくなったはずです。プログラミング言語を習得する最良の 方法は使ってみることですから、ここでやってみましょう。

次の章では、まずインタプリタを使うための機微を説明します。これはさして 面白みのない情報なのですが、後に説明する例題を試してみる上で 不可欠なことです。

チュートリアルの残りの部分では、Python プログラム言語と実行システム の様々な機能を例題を交えて紹介します。単純な式、実行文、データ型から 始めて、関数とモジュールを経て、最後には例外処理やユーザ定義クラス といったやや高度な概念にも触れます。

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 目次 Up: Python チュートリアル Next: 2. Python インタプリタを使う


2. Python インタプリタを使う

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 1. Python への意欲を高める Up: Python チュートリアル Next: 3. 形式ばらない Python の紹介
  • 2.1 インタプリタを起動する
    • 2.1.1 引数の受け渡し
    • 2.1.2 対話モード
  • 2.2 インタプリタとその環境
    • 2.2.1 エラー処理
    • 2.2.2 実行可能な Python スクリプト
    • 2.2.3 ソースコードの文字コード方式 (encoding)
    • 2.2.4 対話モード用の起動時実行ファイル

2. Python インタプリタを使う

2.1 インタプリタを起動する

Python が使える計算機なら、インタプリタはたいてい /usr/local/bin/python にインストールされています; Unix シェルのサーチパスに /usr/local/bin を入れれば、 シェルで

python

とコマンドを入力すれば使えるようになります。 インストールする際にどのディレクトリに Python インタプリタを入れるか をオプションで指定できるので、インタプリタは他のディレクトリにあるかも しれません; 身近な Python の導師 (guru) か、システム管理者に聞いてみて ください。(例えば、その他の場所として /usr/local/python が 一般的です。)

ファイル終端文字 (Unixでは Control-D、DOS や Windows では Control-Z) を一次プロンプト (primary prompt) に入力すると、 インタプリタは終了状態ゼロで終了します。もしこの操作がうまく働かないなら、 コマンド: "import sys; sys.exit()" を入力することで インタプリタを終了することができます。

通常、インタプリタの行編集機能は、あまり洗練されたものではありません。 Unixシステムでは、インタプリタをインストールした誰かが GNU readline ライブラリのサポートを有効にしていれば、洗練された対話的行編集や ヒストリ機能が追加されます。 コマンドライン編集機能がサポートされているかを最も手っ取り早く 調べる方法は、おそらく最初に表示された Python プロンプトに Control-P を入力してみることでしょう。ビープ音が鳴るなら、コマンドライン編集 機能があります; 編集キーについての解説は付録 A を 参照してください。何も起こらないように見えるか、P が エコーバックされるなら、コマンドライン編集機能は利用できません; 現在編集中の行から文字を削除するにはバックスペースを使うしかありません。

インタプリタはさながら Unix シェルのように働きます: 標準入力 が端末に接続された状態で呼び出されると、コマンドを対話的に読み込んで 実行します; ファイル名を引数にしたり、標準入力からファイルを入力 すると、インタプリタはファイルから スクリプト を読み込んで 実行します。

インタプリタを起動する第二の方法は "python -c command [arg] ..."です。この形式では、シェルの -c オプションと同じように、 command に指定した文を実行します。Python 文はしばしば スペースその他のシェルにとって特殊な意味をもつ文字を含むので、 command 全体を二重引用符を囲っておくのがベストです。

"python file" と "python <file" の違いに注意してください。 後者の場合、input() や raw_input() を呼び出した 時のようにプログラム自体から入力が要求されると、その入力は ファイル から調達されます。プログラムの実行が開始される前に ファイルはすでにパーザによってファイルの終端まで読み込まれているので、 入力はすぐにファイル終端に到達します。前者の場合 (大抵はこちらの 方が望ましい動作です)、入力には Python インタプリタの標準入力に 接続された何らかのファイルまたはデバイスが充てられます。

スクリプトファイルが使われた場合、スクリプトを走らせて、そのまま対話 モードに入れると便利なことがあります。これは -i を スクリプトの前に追加することで実現できます。(前の段落で述べたのと 同じ理由から、スクリプトが標準入力から読まれた場合にはこのオプション はうまく働きません。)

2.1.1 引数の受け渡し

インタプリタがスクリプト名と付加な引数を受け取ると、それらは 変数 sys.argv としてスクリプトに渡されます。これは 文字列からなるリストになります。リストの長さは少なくとも 1 です; スクリプト名も引数も与えられなければ、sys.argv[0] は 空の文字列になります。スクリプト名として '-' (標準入力を意味 します) を与えると、sys.argv[0] は '-' に設定されます。 -c command を使うと、sys.argv[0] は '-c' に設定されます。-c command より後ろに あるオプションは、Python インタプリタがオプションを処理する際には 使われませんが、command から扱えるように sys.argv に は残されます。

2.1.2 対話モード

命令文を tty から読み取っているときには、インタプリタは 対話モード (interactive mode) であるといいます。 このモードでは、インタプリタは 一次プロンプト(primary prompt) を表示して次のコマンドを入力するよう促します。 一次プロンプトは普通、三つの大なり記号 (">>> ") です; 継続する行 (continuation line) に対しては、インタプリタは 二次プロンプト (secondary prompt) を表示します。 これはデフォルトでは三つのドット ("... ") です。 インタプリタは、最初のプロンプトを出す前にバージョン番号と著作権表示 から始まる歓迎のメッセージを出力します。

python
Python 1.5.2b2 (#1, Feb 28 1999, 00:02:06)  [GCC 2.8.1] on sunos5
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>>

継続する行は、複数の行から構成される構文を入力するときに必要です。 例として、以下の if 文を見てください。

>>> the_world_is_flat = 1
>>> if the_world_is_flat:
...     print "Be careful not to fall off!"
...
Be careful not to fall off!

2.2 インタプリタとその環境

2.2.1 エラー処理

エラーが発生すると、インタプリタはエラーメッセージとスタックトレース (stack trace) を出力します。対話モードにいるときは、インタプリタは 一次プロンプトに戻ります; 入力がファイルからきているときには、 インタプリタはスタックトレースを出力した後、非ゼロの終了状態で終了します。 (try 文の except 節で処理された例外は、ここでいうエラー にはあたりません。) いくつかのエラーは無条件に致命的であり、非ゼロの終了状態となるプログラム の終了を引き起こします; これにはインタプリタ内部の矛盾や ある種のメモリ枯渇が当てはまります。 エラーメッセージは全て標準エラー出力ストリームに書き込まれます; これに対して、実行した命令からの通常出力される内容は標準出力に 書き込まれます。

割り込み文字 (interrupt character、普通は Control-C か DEL) を 一次または二次プロンプトに対して打鍵すると、入力が取り消されて 一次プロンプトに戻ります。 2.1コマンドの実行中に割り込み文字を打鍵すると KeyboardInterrupt 例外が送出されます。この例外は try 文で処理できます。

2.2.2 実行可能な Python スクリプト

BSD 風の Unix システムでは、Python スクリプトはシェルスクリプトの ようにして直接実行可能にできます。これを行うには、以下の行

#! /usr/bin/env python

(ここではインタプリタがユーザの PATH 上にあると仮定しています) をスクリプトの先頭に置き、スクリプトファイルに実行可能モードを 与えます。 "#!" はファイルの最初の２文字でなければなりません。 プラットフォームによっては、この最初の行を終端する改行文字が Mac OS 形式 ("\r") や Windows 形式 ("\r\n") で はなく、 Unix形式でなければならないことがあります。 ハッシュまたはポンド文字、すなわち "#" は、Python ではコメントを書き始めるために使われているので注意してください。

chmod コマンドを使えば、スクリプトに実行モード (または実行権限) を与えることができます:

$ chmod +x myscript.py

2.2.3 ソースコードの文字コード方式 (encoding)

ASCII 形式でない文字コード化方式 (エンコーディング: encoding) を Python ソースコードファイル中で使うことができます。最良の方法は、 #! 行の 直後に一行かそれ以上の特殊なコメントを挿入して、ソースファイルのエンコード を指定するというものです:

# -*- coding: iso-8859-1 -*-

このように宣言しておくと、ソースファイル中の全ての文字は iso-8859-1 でエンコードされているものとして扱われ、Unicode 文字列リテラルを指定した エンコードで直接記述することができます。利用可能なエンコードのリストは Python ライブラリリファレンス の codecs の節にあります。

利用しているエディタがファイルを UTF-8 バイト整列記号 (通称 BOM: Byte Order Mark) 付きの UTF-8 で保存できる場合、エンコード 宣言の代わりに使うことができます。 IDLE は Options/General/Default Source Encoding/UTF-8 が設定されている場合、 UTF-8 でエンコードされたファイルの識別機能をサポートします。UTF-8 シグネチャ は (2.2 以前の) 古い Python リリースでは解釈されず、オペレーティングシステムは #! ファイルを判別できなくなるので注意してください。

UTF-8 を (シグネチャやエンコード宣言を行って) 使うと、世界中の ほとんどの言語で使われている文字を文字列リテラルやコメントの中に 同時に使うことができます。識別子に対する非 ASCII文字の使用はサポート されていません。全ての文字を正しく表示できるようにするには、使っている エディタがファイルを UTF-8 であると認識することができなければならず、 かつファイル内で使われている全ての文字をサポートするようなフォントを 使わなければなりません。

2.2.4 対話モード用の起動時実行ファイル

Python を対話的に使うときには、インタプリタが起動する度に実行される 何らかの標準的なコマンドがあると便利なことがよくあります。 これを行うには、PYTHONSTARTUP と呼ばれる環境変数を、 インタプリタ起動時に実行されるコマンドが入ったファイル名に設定します。 この機能は Unix シェルの .profile に似ています。

このファイルは対話セッションのときだけ読み出されます。Python がコマンドを スクリプトから読み出しているときや、 /dev/tty がコマンドの 入力元として明示的に指定されている (この場合対話的セッションのように 動作します) わけではない 場合にはこのファイルは読み出されません。 ファイル内のコマンドは、対話的コマンドが実行される名前空間と同じ名前空間内で 実行されます。このため、ファイル内で定義されていたり import された オブジェクトは、限定子をつけなくても対話セッション内で使うことができます。 また、このファイル内で sys.ps1 や sys.ps2 を変更して、 プロンプトを変更することもできます。

もし現在のディレクトリから追加的なスタートアップファイルを読み出したいのなら、 グローバルのスタートアップファイルの中で "if os.path.isfile('.pythonrc.py'): execfile('.pythonrc.py')"のようなコードのプログラムを書くことができます。 スクリプト中でスタートアップファイルを使いたいのなら、以下のようにして スクリプト中で明示的に実行しなければなりません:

import os
filename = os.environ.get('PYTHONSTARTUP')
if filename and os.path.isfile(filename):
    execfile(filename)

... 一次プロンプトに戻ります。2.1
GNU Readline パッケージに関する問題のせいで妨げられることがあります。
Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 1. Python への意欲を高める Up: Python チュートリアル Next: 3. 形式ばらない Python の紹介


3. 形式ばらない Python の紹介

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 2. Python インタプリタを使う Up: Python チュートリアル Next: 4. その他の制御フローツール
  • 3.1 Python を電卓として使う
    • 3.1.1 数
    • 3.1.2 文字列
    • 3.1.3 Unicode 文字列
    • 3.1.4 リスト
  • 3.2 プログラミングへの第一歩

3. 形式ばらない Python の紹介

以下の例では、入力と出力は (">>> " や "... ") といった プロンプトがあるかないかで区別します: 例どおりに実行するなら、 プロンプトが表示されているときに、例中のプロンプトよりも後ろの内容全てを タイプ入力しなければなりません; プロンプトが先頭にない行はインタプリタ からの出力です 3.1。

例中には二次プロンプトだけが表示されている行がありますが、これは 空行を入力しなければならないことを意味するので注意してください; 空行の入力は複数の行からなる命令の終わりをインタプリタに教えるために 使われます。

このマニュアルにある例の多くは、対話プロンプトで入力されるものでも コメントを含んでいます。Python におけるコメント文はハッシュ文字 "#" で始まり、物理行の終わりまで続きます。 コメントは行の先頭にも、空白やコードの後にも書くことができますが、 文字列リテラル (string literal) の内部に置くことはできません。 文字列リテラル中のハッシュ文字はただのハッシュ文字です。

例:

# これは１番目のコメント
SPAM = 1                 # そしてこれは２番目のコメント
                         # ... そしてこれは３番目!
STRING = "# これはコメントではありません。"

3.1 Python を電卓として使う

それでは、簡単な Python コマンドをいくつか試しましょう。 インタプリタを起動して、 一次プロンプト、">>> " が現れるのを待ちます。 (そう長くはかからないはずです)

3.1.1 数

インタプリタは単純な電卓のように動作します: 式をタイプ入力することができ、その結果が書き出されます。 式の文法は素直なものです: 演算子 +, -, *, / は (Pascal や C といった) 他のほとんどの言語と同じように動作します。 括弧をグループ化に使うこともできます。例えば:

>>> 2+2
4
>>> # これはコメント
... 2+2
4
>>> 2+2  # そしてこれはコードと同じ行にあるコメント
4
>>> (50-5*6)/4
5
>>> # 整数の除算は floor (実数の解を越えない最大の整数) を返す:
... 7/3
2
>>> 7/-3
-3

C と同じく、等号 ("=") を使って変数に値を代入します。 代入された値は書き出されません:

>>> width = 20
>>> height = 5*9
>>> width * height
900

複数の変数に同時に値を代入することができます:

>>> x = y = z = 0  # x と y と z をゼロにする
>>> x
0
>>> y
0
>>> z
0

浮動小数点は完全にサポートしています; 被演算子の型が混合されているときには、 演算子は整数の被演算子を浮動小数点型に変換します。

>>> 3 * 3.75 / 1.5
7.5
>>> 7.0 / 2
3.5

複素数もサポートされています。虚数は接尾辞 "j" または "J" を 付けて書き表します。ゼロでない実数部をもつ複素数は "(real+imagj)" のように書き表すか、 "complex(real, imag)" 関数で生成できます。

>>> 1j * 1J
(-1+0j)
>>> 1j * complex(0,1)
(-1+0j)
>>> 3+1j*3
(3+3j)
>>> (3+1j)*3
(9+3j)
>>> (1+2j)/(1+1j)
(1.5+0.5j)

複素数は、常に実部と虚部に相当する二つの浮動小数点数で表されます。 複素数 z からそれぞれの部分を取り出すには、z.real と z.imag を使います。

>>> a=1.5+0.5j
>>> a.real
1.5
>>> a.imag
0.5

数値を浮動小数点数や整数へに変換する関数 (float(), int(), long()) は複素数に対しては動作しません -- 複素数を実数に変換する方法には、ただ一つの正解というものがないからです。 絶対値 (magnitude) を (浮動小数点数として) 得るには abs(z) を 使い、実部を得るには z.real を使ってください。

>>> a=3.0+4.0j
>>> float(a)
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: can't convert complex to float; use abs(z)
>>> a.real
3.0
>>> a.imag
4.0
>>> abs(a)  # sqrt(a.real**2 + a.imag**2)
5.0
>>>

対話モードでは、最後に印字された式は変数 _ に代入されます。 このことを利用すると、 Python を電卓として使うときに、計算を連続して 行う作業が多少楽になります。以下に例を示します:

>>> tax = 12.5 / 100
>>> price = 100.50
>>> price * tax
12.5625
>>> price + _
113.0625
>>> round(_, 2)
113.06
>>>

ユーザはこの変数を読取り専用の値として扱うべきです。 この変数に明示的な代入を行ってはいけません -- そんなことをすれば、 この組み込み変数と同じ名前で、元の組み込み変数の不思議な動作を覆い隠して しまうような、別個のローカルな変数が生成されてしまえいます。

3.1.2 文字列

数のほかに、Python は文字列も操作できます。 文字列はいくつもの方法で表現できます。 文字列はシングルまたはダブルのクォートで囲みます。

>>> 'spam eggs'
'spam eggs'
>>> 'doesn\'t'
"doesn't"
>>> "doesn't"
"doesn't"
>>> '"Yes," he said.'
'"Yes," he said.'
>>> "\"Yes,\" he said."
'"Yes," he said.'
>>> '"Isn\'t," she said.'
'"Isn\'t," she said.'

文字列リテラルはいくつもかの方法で複数行にまたがって記述することが できます。継続行を使うことができ、これには行の末尾の文字を バックスラッシュにします。こうすることで、次の行が現在の行と論理的に 継続していることを示します:

hello = "This is a rather long string containing\n\
several lines of text just as you would do in C.\n\
    Note that whitespace at the beginning of the line is\
 significant."

print hello

\n を使って文字列に改行位置を埋め込まなくてはならないことに注意 してください; 末尾のバックスラッシュの後ろにある改行文字は無視されます。 従って、上の例は以下のような出力を行います:

This is a rather long string containing
several lines of text just as you would do in C.
    Note that whitespace at the beginning of the line is significant.

一方、文字列リテラルを ``raw'' 文字列にすると、\n のような エスケープシーケンスは改行に変換されません。逆に、行末のバックスラッシュ やソースコード中の改行文字が文字列データに含められます。つまり、以下の例:

hello = r"This is a rather long string containing\n\
several lines of text much as you would do in C."

print hello

は、以下のような出力を行います:

This is a rather long string containing\n\
several lines of text much as you would do in C.

また、対になった三重クォート """ または ''' で 文字列を囲むこともできます。 三重クォートを使っているときには、行末をエスケープする必要はありません、 しかし、行末の改行文字も文字列に含まれることになります。

print """
Usage: thingy [OPTIONS]
     -h                        Display this usage message
     -H hostname               Hostname to connect to
"""

は以下のような出力を行います:

Usage: thingy [OPTIONS]
     -h                        Display this usage message
     -H hostname               Hostname to connect to

インタプリタは、文字列演算の結果を、タイプ入力する時のと同じ方法で 出力します: 文字列はクオート文字で囲い、クオート文字自体やその他の 奇妙な文字は、正しい文字が表示されるようにするために バックスラッシュでエスケープします。 文字列がシングルクオートを含み、かつダブルクオートを含まない場合には、 全体をダブルクオートで囲います。そうでない場合にはシングルクオートで 囲みます。 (後で述べる print を使って、クオートやエスケープ のない文字列を書くことができます。)

文字列は + 演算子で連結させる (くっつけて一つにする) ことができ、 * 演算子で反復させることができます。

>>> word = 'Help' + 'A'
>>> word
'HelpA'
>>> '<' + word*5 + '>'
'<HelpAHelpAHelpAHelpAHelpA>'

互いに隣あった二つの文字列リテラルは自動的に連結されます: 例えば、上記の最初の行は "word = 'Help' 'A'" と書くことも できました; この機能は二つともリテラルの場合にのみ働くもので、 任意の文字列表現で使うことができるわけではありません。

>>> 'str' 'ing'             #  <-  これは ok
'string'
>>> 'str'.strip() + 'ing'   #  <-  これは ok
'string'
>>> 'str'.strip() 'ing'     #  <-  これはダメ
  File "<stdin>", line 1, in ?
    'str'.strip() 'ing'
                  ^
SyntaxError: invalid syntax

文字列は添字表記 (インデクス表記) することができます; C 言語と同じく、文字列の最初の文字の添字 (インデクス) は 0 となります。 独立した文字型というものはありません; 単一の文字は、単に サイズが 1 の文字列です。Icon 言語と同じく、部分文字列を スライス表記: コロンで区切られた二つのインデクスで指定する ことができます。

>>> word[4]
'A'
>>> word[0:2]
'He'
>>> word[2:4]
'lp'

スライスのインデクスには便利なデフォルト値があります; 最初のインデクスを省略すると、0 と見なされます。 第 2 のインデクスを省略すると、スライスしようとする文字列のサイズと みなされます。

>>> word[:2]    # 最初の２文字
'He'
>>> word[2:]    # 最初の２文字を除くすべて
'lpA'

C 言語の文字列と違い、Python の文字列は変更できません。 インデクス指定された文字列中のある位置に代入を行おうとすると エラーになります:

>>> word[0] = 'x'
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: object doesn't support item assignment
>>> word[:1] = 'Splat'
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: object doesn't support slice assignment

一方、要素どうしを組み合わせた新たな文字列の生成は、簡単で効率的です:

>>> 'x' + word[1:]
'xelpA'
>>> 'Splat' + word[4]
'SplatA'

スライス演算には便利な不変式があります: s[:i] + s[i:] は s に等しくなります。

>>> word[:2] + word[2:]
'HelpA'
>>> word[:3] + word[3:]
'HelpA'

スライス表記に行儀の悪いインデクス指定をしても、値はたしなみよく処理 されます: インデクスが大きすぎる場合は文字列のサイズと置き換えられます。 スライスの下境界 (文字列の左端) よりも小さいインデクス値を上境界 (文字列の右端) に指定すると、空文字列が返されます。

>>> word[1:100]
'elpA'
>>> word[10:]
''
>>> word[2:1]
''

インデクスを負の数にして、右から数えることもできます。 例えば:

>>> word[-1]     # 最後の文字
'A'
>>> word[-2]     # 最後から二つめの文字
'p'
>>> word[-2:]    # 最後の２文字
'pA'
>>> word[:-2]    # 最後の２文字を除くすべて
'Hel'

-0 は 0 と全く同じなので、右から数えることができません。 注意してください!

>>> word[-0]     # (-0 は 0 に等しい)
'H'

負で、かつ範囲外のインデクスをスライス表記で行うと、インデクス は切り詰められます。しかし、単一の要素を指定する (スライスでない) インデクス指定でこれを行ってはいけません:

>>> word[-100:]
'HelpA'
>>> word[-10]    # エラー
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
IndexError: string index out of range

スライスの働きかたをおぼえる最も良い方法は、 インデクスが文字と文字のあいだ (between) を指しており、最初の 文字の左端が 0 になっていると考えることです。そうすると、 n 文字からなる文字列中の最後の文字の右端はインデクス n となります。例えば:

 +---+---+---+---+---+
 | H | e | l | p | A |
 +---+---+---+---+---+
 0   1   2   3   4   5
-5  -4  -3  -2  -1

といった具合です。

数が記された行のうち、最初の方の行は、文字列中のインデクス 0...5 の 位置を表します; 次の行は、対応する負のインデクスを表しています。 i から j までのスライスは、それぞれ i, j とラベル付けされたけられた端点間のすべての文字からなります。

非負のインデクス対の場合、スライスされた配列の長さは、スライスの両端の インデクスが境界内にあるかぎり、インデクス間の差になります。 例えば、 word[1:3] の長さは 2 になります。

組込み関数 len() は文字列の長さ (length) を返します。

>>> s = 'supercalifragilisticexpialidocious'
>>> len(s)
34

参考資料:

配列型
次節で記述されている文字列および Unicode 文字列は 配列型 の例であり、配列型でサポートされている共通の操作を サポートしています。
文字列メソッド
文字列や Unicode 文字列では、基本的な変換や検索を 行うための数多くのメソッドをサポートしています。
文字列フォーマット操作
文字列や Unicode 文字列が % 演算子の左被演算子 である場合に呼び出されるフォーマット操作については、ここで詳しく記述 されています。

3.1.3 Unicode 文字列

Python 2.0 から、プログラマはテキスト・データを格納するための新しい データ型、Unicode オブジェクトを利用できるようになりました。 Unicode オブジェクトを使うと、Unicode データ (http://www.unicode.org/ 参照) を記憶したり、操作したりできます。また、 Unicode オブジェクトは 既存の文字列オブジェクトとよく統合していて、必要に応じた自動変換機能を 提供しています。

Unicode には、古今のテキストで使われているあらゆる書き文字のあらゆる 文字について、対応付けを行うための一つの序数を規定しているという利点が あります。 これまでは、書き文字のために利用可能な序数は 256 個しかなく、テキストは 書き文字の対応付けを行っているコードページに束縛されているのが通常 でした。 このことは、とりわけソフトウェアの国際化 (通常 "i18n" -- "i" + 18 文字 + "n" の意) に対して大きな 混乱をもたらしました。Unicode では、すべての書き文字に対して単一の コードページを定義することで、これらの問題を解決しています。

Python では、Unicode 文字列の作成は通常の文字列を作成するのと 同じように単純なものです:

>>> u'Hello World !'
u'Hello World !'

クオートの前にある小文字の "u" は、Unicode 文字列を生成 することになっていることを示します。文字列に特殊な文字を 含めたければ、Python の Unicode-Escape エンコーディングを 使って行えます。以下はその方法を示しています:

>>> u'Hello\u0020World !'
u'Hello World !'

エスケープシーケンス \u0020 は、序数の値 0x0020 を持つ Unicode 文字 (スペース文字) を、指定場所に挿入することを示します。

他の文字は、それぞれの序数値をそのまま Unicode の序数値に用いて 解釈されます。多くの西洋諸国で使われている標準 Latin-1 エンコーディング のリテラル文字列があれば、Unicode の下位 256 文字が Latin-1 の 256 文字と同じになっていて便利だと思うことでしょう。

上級者のために、通常の文字列の場合と同じく raw モードもあります。 これには、文字列を開始するクオート文字の前に 'ur' を付けて、 Python に Raw-Unicode-Escape エンコーディングを使わせ なければなりません。このモードでは、上記の \uXXXX の 変換は機能、小文字の 'u' の前に奇数個のバックスラッシュがあるときにだけ 適用されます。

>>> ur'Hello\u0020World !'
u'Hello World !'
>>> ur'Hello\\u0020World !'
u'Hello\\\\u0020World !'

raw モードは、正規表現を記述する時のように、沢山のバックスラッシュを 入力しなければならないときとても役に立ちます。

これら標準のエンコーディングにとは別に、Python では、既知の 文字エンコーディングに基づいて Unicode 文字列を生成する一連の 手段を提供しています。

組込み関数 unicode() は、 登録されているすべての Unicode codecs (COder: エンコーダ と DECoder デコーダ) へのアクセス機能を提供します。codecs が変換できる エンコーディングには、よく知られているものとして Latin-1, ASCII, UTF-8 および UTF-16 が あります。後者の二つは可変長のエンコードで、各 Unicode 文字を 1 バイトまたはそれ以上のバイト列に保存します。デフォルトのエンコーディング は通常 ASCIIに設定されています。ASCIIでは 0 から 127 の範囲の 文字だけを通過させ、それ以外の文字は受理せずエラーを出します。 Unicode 文字列を印字したり、ファイルに書き出したり、 str() で変換すると、デフォルトのエンコーディングを 使った変換が行われます。

>>> u"abc"
u'abc'
>>> u"あいう"
u'\x82\xa0\x82\xa2\x82\xa4'
>>> str(u"あいう")
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
UnicodeEncodeError: 'ascii' codec can't encode characters in position 0-5:
ordinal not in range(128)

特定のエンコーディングを使って Unicode 文字列を 8 ビットの文字列に 変換するために、Unicode オブジェクトでは encode() メソッドを提供しています。このメソッドは単一の引数として エンコーディングの名前をとります。エンコーディング名には 小文字の使用が推奨されています。

>>> u"あいう".encode('utf-8')
'\xc2\x82\xc2\xa0\xc2\x82\xc2\xa2\xc2\x82\xc2\xa4'

特定のエンコーディングで書かれているデータがあり、そこから Unicode 文字列を生成したいなら、unicode() を使い、 第 2 引数にエンコーディング名を指定します。

unicode('\xc2\x82\xc2\xa0\xc2\x82\xc2\xa2\xc2\x82\xc2\xa4', 'utf-8')
u'\x82\xa0\x82\xa2\x82\xa4'

3.1.4 リスト

Python は数多くの 複合 (compound) データ型を備えており、 別々の値を一まとめにするために使えます。 最も汎用的なデータ型は リスト (list) で、コンマで区切られた 値からなるリストを各カッコで囲んだものとして書き表されます。 リストの要素をすべて同じ型にする必要はありません。

>>> a = ['spam', 'eggs', 100, 1234]
>>> a
['spam', 'eggs', 100, 1234]

文字列のインデクスと同じく、リストのインデクスは 0 から開始します。 また、スライス、連結なども行えます:

>>> a[0]
'spam'
>>> a[3]
1234
>>> a[-2]
100
>>> a[1:-1]
['eggs', 100]
>>> a[:2] + ['bacon', 2*2]
['spam', 'eggs', 'bacon', 4]
>>> 3*a[:3] + ['Boe!']
['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boe!']

変化不可能 (immutable) な文字列型と違い、 リストは個々の要素を変更することができます。

>>> a
['spam', 'eggs', 100, 1234]
>>> a[2] = a[2] + 23
>>> a
['spam', 'eggs', 123, 1234]

スライスに代入することもできます。スライスの代入を行って、 リストのサイズを変更することさえできます。

>>> # いくつかの項目を置換する:
... a[0:2] = [1, 12]
>>> a
[1, 12, 123, 1234]
>>> # いくつかの項目を除去する:
... a[0:2] = []
>>> a
[123, 1234]
>>> # いくつかの項目を挿入する:
... a[1:1] = ['bletch', 'xyzzy']
>>> a
[123, 'bletch', 'xyzzy', 1234]
>>> a[:0] = a     # それ自身 (のコピー) を先頭に挿入する
>>> a
[123, 'bletch', 'xyzzy', 1234, 123, 'bletch', 'xyzzy', 1234]

組込み関数 len() はリストにも適用できます。

>>> len(a)
8

リストを入れ子にする (ほかのリストを含むリストを造る) ことも可能です。 例えば、

>>> q = [2, 3]
>>> p = [1, q, 4]
>>> len(p)
3
>>> p[1]
[2, 3]
>>> p[1][0]
2
>>> p[1].append('xtra')     # 5.1節を参照
>>> p
[1, [2, 3, 'xtra'], 4]
>>> q
[2, 3, 'xtra']

最後の例では、 p[1] と q が実際には同一のオブジェクトを 参照していることに注意してください!　 オブジェクトの意味付け (semantics) については、後ほど触れることに します。

3.2 プログラミングへの第一歩

もちろん、2 たす 2 よりももっと複雑な仕事にも Python を使うことが できます。Fibonacci 級数列の先頭の部分列は次のようにして 書くことができます:

>>> # Fibonacci 級数:
... # 二つの要素の和が次の要素を定義する
... a, b = 0, 1
>>> while b < 10:
...       print b
...       a, b = b, a+b
...
1
1
2
3
5
8

上の例では、いくつか新しい機能を取り入れています。

  • 最初の行には 複数同時の代入 (multiple assignment) が入っています: 変数 a と b は、それぞれ同時に新しい値 0 と 1 に なっています。この代入は最後の行でも再度使われており、代入が 行われる前に右辺の式がまず評価されます。右辺の式は左から右へと 順番に評価されます。

  • while は、条件 (ここでは b < 10) が真である限り 実行を繰り返し (ループし) ます。Python では、C 言語と同様に、ゼロでない 整数値は真となり、ゼロは偽です。条件式は文字列値やリスト値、 実際には任意の配列型でもかまいません。例中で使われている条件テスト は単なる比較です。標準的な比較演算子は C 言語と同様です: すなわち、 < (より小さい)、 > (より大きい)、 == (等しい)、 <= (より小さいか等しい)、 >= (より大きいか等しい)、 および != (等しくない) 、 です。

  • ループの本体 (body) はインデント (indent, 字下げ) されています: インデントは Python において実行文をグループにまとめる 方法です。Python は (いまだに!) 賢い入力行編集機能を提供していないので、 インデントされた各行を入力するにはタブや (複数個の) スペースを 使わなければなりません。実際には、Python へのより複雑な入力を準備する にはテキストエディタを使うことになるでしょう; ほとんどのテキスト エディタは自動インデント機能を持っています。 複合文を対話的に入力するときには、(パーザはいつ最後の行を入力 したのか推し量ることができないので) 入力の完了を示すために最後に空行を 続けなければなりません。基本ブロックの各行は同じだけインデントされて いなければならないので注意してください。

  • print は指定した (1 つまたは複数の) 式の値を書き出します。 print は、(電卓の例でしたように) 単に値を出力したい式を書くの とは、複数の式や文字列を扱う方法が違います。 文字列は引用符無しで出力され、複数の要素の間にはスペースが挿入されるので、 以下のように出力をうまく書式化できます。

    >>> i = 256*256
>>> print 'The value of i is', i
The value of i is 65536

    末尾にコンマを入れると、出力を行った後に改行されません:

    >>> a, b = 0, 1
>>> while b < 1000:
...     print b,
...     a, b = b, a+b
...
1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987

    インタプリタは、最後に入力した行がまだ完全な文になっていない場合、 改行をはさんで次のプロンプトを出力することに注意してください。

... からの出力です3.1
入力と出力を区別するために異なるフォントを使おうとは思うのですが、 それに必要な LaTeX の hack 作業に必要な量が、今のところ私の能力を 超えています。
Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 2. Python インタプリタを使う Up: Python チュートリアル Next: 4. その他の制御フローツール


4. その他の制御フローツール

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 3. 形式ばらない Python の紹介 Up: Python チュートリアル Next: 5. データ構造
  • 4.1 if 文
  • 4.2 for 文
  • 4.3 range() 関数
  • 4.4 break 文と continue 文と ループの else 節
  • 4.5 pass 文
  • 4.6 関数を定義する
  • 4.7 関数定義についてもう少し
    • 4.7.1 デフォルトの引数値
    • 4.7.2 キーワード引数
    • 4.7.3 任意引数リスト
    • 4.7.4 引数リストのアンパック
    • 4.7.5 ラムダ形式
    • 4.7.6 ドキュメンテーション文字列

4. その他の制御フローツール

今しがた紹介した while 文の他に、Python では他の言語で おなじみの普通の制御フロー文を備えていますが、これらには多少 ひねりを加えてあります。

4.1 if 文

おそらく最もおなじみの文型は if 文でしょう。 例えば、

>>> x = int(raw_input("Please enter an integer: "))
>>> if x < 0:
...      x = 0
...      print 'Negative changed to zero'
... elif x == 0:
...      print 'Zero'
... elif x == 1:
...      print 'Single'
... else:
...      print 'More'
...

elif 部はゼロ個またはそれ以上にできます。 else 部を付けることもできます。 キーワード `elif' は `else if' を短くしたもので、 過剰なインデントを避けるのに役立ちます。 一連の if ... elif ... elif ... は、他の言語における switch 文や case 文の代用と なります。

4.2 for 文

Python の for 文は、読者が C 言語や Pascal 言語 で使いなれているかもしれない for 文とは少し違います。 (Pascal のように) 常に算術型の数列にわたる反復を行ったり、 (C のように) 繰返しステップと停止条件を両方ともユーザが定義できるように するのとは違い、Python の for 文は、任意の 配列型 (リストまたは文字列) にわたって反復を行います。反復の順番は 配列中に要素が現れる順番です。 (for example というしゃれではないけれど) 例えば 、

>>> # いくつかの文字列の長さを測る:
... a = ['cat', 'window', 'defenestrate']
>>> for x in a:
...     print x, len(x)
...
cat 3
window 6
defenestrate 12

反復操作の対象になっている配列をループので書き換える操作 (リストのような、変更可能 (mutable) な配列型でおきます) は、安全 ではありません。もし反復処理を行う対象とするリスト型を変更したいのなら、 (対象の要素を複製するなどして) コピーに対して反復を行わなければ なりません。この操作にはスライス表記を使うと特に便利です:

>>> for x in a[:]: # リスト全体のスライス・コピーを作る
...    if len(x) > 6: a.insert(0, x)
...
>>> a
['defenestrate', 'cat', 'window', 'defenestrate']

4.3 range() 関数

数列にわたって反復を行う必要がある場合、組み込み関数 range() が便利です。この関数は算術型の数列が入ったリストを生成します。

>>> range(10)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

指定した終端値は生成されるリストには入りません。 range(10) は 10 個の値からなるリストを生成し、 ちょうど長さ 10 の配列における各項目のインデクスとなります。 range を別の数から開始したり、他の増加量 (負の増加量でさえも; 増加量は時に `ステップ(step)' と呼ばれることもあります) を指定する こともできます:

>>> range(5, 10)
[5, 6, 7, 8, 9]
>>> range(0, 10, 3)
[0, 3, 6, 9]
>>> range(-10, -100, -30)
[-10, -40, -70]

ある配列にわたってインデクスで反復を行うには、 range() と len() を次のように組み合わせます:

>>> a = ['Mary', 'had', 'a', 'little', 'lamb']
>>> for i in range(len(a)):
...     print i, a[i]
...
0 Mary
1 had
2 a
3 little
4 lamb

4.4 break 文と continue 文と ループの else 節

break 文は、C 言語と同じく、最も内側の for または while ループを中断します。

continue 文は、これもまた C 言語から借りてきたものですが、 ループを次の反復処理に飛ばします。

ループ文は else 節を持つことができます; else 節は、 (for で) 反復処理対象のリストを使い切ってループが終了したとき、 または (while で) 条件が偽になったときに実行されますが、 break 文でループが終了したときは実行されません。 この動作を、素数を探す下記のループを例にとって示します:

>>> for n in range(2, 10):
...     for x in range(2, n):
...         if n % x == 0:
...            print n, 'equals', x, '*', n/x
...            break
...     else:
...          # 因数が見つからずにループが終了
...          print n, 'is a prime number'
...
2 is a prime number
3 is a prime number
4 equals 2 * 2
5 is a prime number
6 equals 2 * 3
7 is a prime number
8 equals 2 * 4
9 equals 3 * 3

4.5 pass 文

pass 文は何もしません。pass は、文を書くことが 構文上要求されているが、プログラム上何の動作もする必要がない時に 使われます。

>>> while True:
...       pass # キーボード割り込み (keyboard interrupt) をbusy-wait で待つ
...

4.6 関数を定義する

フィボナッチ数列 (Fibonacci series) を任意の上限値まで書き出すような 関数を作成できます:

>>> def fib(n):    # n までのフィボナッチ級数を出力する
...     """Print a Fibonacci series up to n."""
...     a, b = 0, 1
...     while b < n:
...         print b,
...         a, b = b, a+b
...
>>> # 今しがた定義した関数を呼び出す:
... fib(2000)
1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597

def は関数の定義 (definition) を導くキーワードです。 def の後には、関数名と仮引数 (formal parameter) を 丸括弧で囲んだリストを続けなければなりません。関数の実体を 校正する実行文は次の行から始め、インデントされていなければなりません。 関数の本体の記述する文の最初の行は文字列リテラルにすることもできます; その場合、文字列は関数の ドキュメンテーション文字列 (documentation string) 、または docstring です。

ドキュメンテーション文字列を使ったツールには、オンライン文書や 印刷文書を自動的に生成したり、ユーザが対話的にコードを閲覧できる ようにするものがあります; 自分が書くコードにドキュメンテーション 文字列を入れるのはよい習慣です。書く癖をつけるようにしてください。

関数を 実行 (execution) すると、関数のローカル変数のために 使われる新たなシンボルテーブル (symbol table) が取り込まれます。 もっと正確にいうと、関数内で変数への代入を行うと、その値はすべて このローカルなシンボルテーブルに記憶されます; 一方、変数の参照を 行うと、まずローカルなシンボルテーブルが検索され、その後グローバル なシンボルテーブルを調べ、最後に組み込みの名前テーブルを調べます。 従って、関数の中では、グローバルな変数を参照することはできますが、 直接値を代入することは (global 文で名前を挙げておかない限り) できません。

関数を呼び出す際の実際のパラメタ (引数) は、関数が呼び出されるときに 関数のローカルなシンボルテーブル内に取り込まれます; そうすることで、 引数は 値渡し (call by value) で関数に渡されることになります (ここでの 値 (value) とは常にオブジェクトへの 参照 (reference) をいい、オブジェクトの値そのものでは ありません) 4.1。 ある関数がほかの関数を呼び出すときには、新たな呼び出しのために ローカルなシンボルテーブルが新たに作成されます。

関数の定義を行うと、関数名は現在のシンボルテーブル内に取り入れられます。 関数名の値は、インタプリタからはユーザ定義関数 (user-defined function) として認識される型を持ちます。この値は別の名前に代入して、 その名前を後に関数として使うこともできます。 これは一般的な名前変更のメカニズムとして働きます。

>>> fib
<function object at 10042ed0>
>>> f = fib
>>> f(100)
1 1 2 3 5 8 13 21 34 55 89

fib は関数ではなく手続き (procedure) だと異論があるかも しれませんね。Python では C 言語と同様、手続きはただの関数で、 値を返さないに過ぎません。技術的に言えば、実際には手続きも ややつまらない値ですが値を返しています。この値は None と呼ばれます (これは組み込みの名前です)。None だけを 書き出そうとすると、インタプリタは通常出力を抑制します。 本当に出力したいのなら、以下のようにすると見ることができます:

>>> print fib(0)
None

フィボナッチ数列の数からなるリストを出力する代わりに、値を返すような 関数を書くのは簡単です:

>>> def fib2(n): #  n までのフィボナッチ級数を返す
...     """Return a list containing the Fibonacci series up to n."""
...     result = []
...     a, b = 0, 1
...     while b < n:
...         result.append(b)    # 下記参照
...         a, b = b, a+b
...     return result
...
>>> f100 = fib2(100)    # 関数を呼び出す
>>> f100                # 結果を出力する
[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]

例によって、この例は Python の新しい機能を示しています:

  • return 文では、関数から一つ値を返します。 return の引数となる式がない場合、 None が返ります。 手続きが終了したときにも None が返ります。

  • 文 result.append(b) では、リストオブジェクト result の メソッド (method) を呼び出しています。 メソッドとは、オブジェクトに `属している' 関数のことで、 obj を何らかのオブジェクト (式であっても構いません)、 methodname をそのオブジェクトで定義されているメソッド名 とすると、obj.methodname と書き表されます。 異なる型は異なるメソッドを定義しています。異なる型のメソッドで 同じ名前のメソッドを持つことができ、あいまいさを生じることはありません。 (自前のオブジェクト型とメソッドを定義することもできます。これには、 後でこのチュートリアルで述べる クラス (class) を使います。) 例で示されているメソッド append() は、リストオブジェクトで 定義されています; このメソッドはリストの末尾に新たな要素を追加します。 この例での append() は "result = result + [b]" と等価 ですが、より効率的です。

4.7 関数定義についてもう少し

可変個の引数を伴う関数を定義することもできます。引数の定義方法には 3 つの形式があり、それらを組み合わせることができます。

4.7.1 デフォルトの引数値

もっとも便利なのは、一つ以上の引数に対してデフォルトの値を指定する 形式です。この形式を使うと、定義されている引数より少ない個数の引数 で呼び出せる関数を作成します:

def ask_ok(prompt, retries=4, complaint='Yes or no, please!'):
    while True:
        ok = raw_input(prompt)
        if ok in ('y', 'ye', 'yes'): return True
        if ok in ('n', 'no', 'nop', 'nope'): return False
        retries = retries - 1
        if retries < 0: raise IOError, 'refusenik user'
        print complaint

この関数は、 ask_ok('Do you really want to quit?') のようにも、 ask_ok('OK to overwrite the file?', 2) のようにも呼び出す ことができます。

デフォルト値は、関数が定義された時点で、関数を 定義している 側の スコープ (scope) で評価されるので、

i = 5

def f(arg=i):
    print arg

i = 6
f()

は 5 を出力します。

重要な警告: デフォルト値は 1 度だけしか評価されません。 デフォルト値がリストや辞書のような変更可能なオブジェクトの時には その影響がでます。例えば以下の関数は、後に続く関数呼び出しで 関数に渡されている引数を累積します:

def f(a, L=[]):
    L.append(a)
    return L

print f(1)
print f(2)
print f(3)

このコードは、

[1]
[1, 2]
[1, 2, 3]

を出力します。

後続の関数呼び出しでデフォルト値を共有したくなければ、 代わりに以下のように関数を書くことができます:

def f(a, L=None):
    if L is None:
        L = []
    L.append(a)
    return L

4.7.2 キーワード引数

関数を "keyword = value" という形式のキーワード引数を 使って呼び出すこともできます。例えば、以下の関数:

def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
    print "-- This parrot wouldn't", action,
    print "if you put", voltage, "Volts through it."
    print "-- Lovely plumage, the", type
    print "-- It's", state, "!"

は、以下のいずれの方法でも呼び出せます:

parrot(1000)
parrot(action = 'VOOOOOM', voltage = 1000000)
parrot('a thousand', state = 'pushing up the daisies')
parrot('a million', 'bereft of life', 'jump')

しかし、以下の呼び出しはすべて不正なものです:

parrot()                     # 必要な引数がない
parrot(voltage=5.0, 'dead')  # キーワード引数の後に非キーワード引数がある
parrot(110, voltage=220)     # 引数に対して値が重複している
parrot(actor='John Cleese')  # 未知のキーワードを使用している

一般に、引数リストでは、固定引数 (positional argument) の後ろに キーワード引数を置かねばならず、キーワードは仮引数名から選ばなければ なりません。仮引数がデフォルト値を持っているかどうかは重要では ありません。引数はいずれも一つ以上の値を受け取りません -- 同じ関数呼び出しの中では、固定引数に対応づけられた仮引数名を キーワードとして使うことはできません。この制限のために 実行が失敗する例を以下に示します。

>>> def function(a):
...     pass
...
>>> function(0, a=0)
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: function() got multiple values for keyword argument 'a'

仮引数の最後に **name の形式のものがあると、 仮引数に対応しないすべてのキーワード引数が入った 辞書 を受け取ります。 **name は *name の形式をとる、仮引数のリスト を超えた固定引数の入ったタプルを受け取る引数 (次の節で述べます) と組み合わせることができます。 (*name は **name より前になければなりません)。 例えば、ある関数の定義を以下:

def cheeseshop(kind, *arguments, **keywords):
    print "-- Do you have any", kind, '?'
    print "-- I'm sorry, we're all out of", kind
    for arg in arguments: print arg
    print '-'*40
    keys = keywords.keys()
    keys.sort()
    for kw in keys: print kw, ':', keywords[kw]

のようにすると、呼び出しは以下:

cheeseshop('Limburger', "It's very runny, sir.",
           "It's really very, VERY runny, sir.",
           client='John Cleese',
           shopkeeper='Michael Palin',
           sketch='Cheese Shop Sketch')

のようになり、もちろん以下のように出力されます:

-- Do you have any Limburger ?
-- I'm sorry, we're all out of Limburger
It's very runny, sir.
It's really very, VERY runny, sir.
----------------------------------------
client : John Cleese
shopkeeper : Michael Palin
sketch : Cheese Shop Sketch

キーワード引数名のリストに対して sort() を呼び出した後に
keywords 辞書の内容を出力していることに注意してください;
sort() が呼び出されていないと、引数が出力される順番は
不確定となります。

4.7.3 任意引数リスト

最後に、最も使うことの少ない選択肢として、関数が任意の個数の引数で 呼び出せるよう指定する方法があります。これらの引数はタプルに くるまれます。可変個の引数の前に、ゼロ個かそれ以上の引数があっても 構いません。

def fprintf(file, format, *args):
    file.write(format % args)

4.7.4 引数リストのアンパック

引数がすでにリストやタプルになっていて、個別な固定引数を要求する 関数呼び出しに渡すためにアンパックする必要がある場合には、逆の 状況が起こります。例えば、組み込み関数 range() は 引数 start と stop を別に与える必要があります。 個別に引数を与えることができない場合、関数呼び出しを * 演算子を使って書き、リストやタプルから引数をアンパック します:

>>> range(3, 6)             # 個別の引数を使った通常の呼び出し
[3, 4, 5]
>>> args = [3, 6]
>>> range(*args)            # リストからアンパックされた引数での呼び出し
[3, 4, 5]

4.7.5 ラムダ形式

多くの人の要望により、関数型プログラミング言語や Lisp によくある いくつかの機能が Python に加えられました。 キーワード lambda を使うと、名前のない小さな関数を生成できます。 例えば "lambda a, b: a+b" は、二つの引数の和を返す関数です。 ラムダ形式 (lambda form) は、関数オブジェクトが要求されている場所 にならどこでも使うことができます。ラムダ形式は、構文上単一の式に 制限されています。意味付け的には、ラムダ形式はただ通常の関数に 構文的な糖衣をかぶせたものに過ぎません。入れ子構造になった関数定義 と同様、ラムダ形式もそれを取り囲むスコープから変数を参照することが できます。

>>> def make_incrementor(n):
...     return lambda x: x + n
...
>>> f = make_incrementor(42)
>>> f(0)
42
>>> f(1)
43

4.7.6 ドキュメンテーション文字列

ドキュメンテーション文字列については、その内容と書式に関する 慣習ができつつあります。

最初の行は、常に対象物の目的を短く簡潔にまとめたものでなくてはなりません。 簡潔に書くために、対象物の名前や型を明示する必要はありません。 名前や型は他の方法でも得られるからです (名前がたまたま関数の演算内容 を記述する動詞である場合は例外です)。 最初の行は大文字で始まり、ピリオドで終わっていなければなりません。

ドキュメンテーション文字列中にさらに記述すべき行がある場合、 二行目は空行にし、まとめの行と残りの記述部分を視覚的に分離 します。つづく行は一つまたはそれ以上の段落で、対象物の 呼び出し規約や副作用について記述します。

Python のパーザは複数行にわたる Python 文字列リテラルからインデントを 剥ぎ取らないので、ドキュメントを処理するツールでは必要に応じて インデントを剥ぎ取らなければなりません。この処理は以下の規約に従って 行います。最初の行の 後にある 空行でない最初の行が、ドキュメント 全体のインデントの量を決めます。 (最初の行は通常、文字列を開始する クオートに隣り合っているので、インデントが文字列リテラル中に現れない ためです。) このインデント量と ``等価な'' 空白が、文字列のすべての 行頭から剥ぎ取られます。インデントの量が少ない行を書いてはならないの ですが、もしそういう行があると、先頭の空白すべてが剥ぎ取られます。 インデントの空白の大きさが等しいかどうかは、タブ文字を (通常は 8 文字の スペースとして) 展開した後に調べられます。

以下に複数行のドキュメンテーション文字列の例を示します:

>>> def my_function():
...     """Do nothing, but document it.
...
...     No, really, it doesn't do anything.
...     """
...     pass
...
>>> print my_function.__doc__
Do nothing, but document it.

    No, really, it doesn't do anything.

... ありません)4.1
実際には、オブジェクトへの参照渡し (call by object reference) と書けばよいのかもしれません。というのは、変更可能なオブジェクトが 渡されると、関数の呼び出し側は、呼び出された側の関数がオブジェクト に (リストに値が挿入されるといった) 何らかの変更に出くわすことに なるからです。
Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 3. 形式ばらない Python の紹介 Up: Python チュートリアル Next: 5. データ構造


5. データ構造

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 4. その他の制御フローツール Up: Python チュートリアル Next: 6. モジュール
  • 5.1 リスト型についてもう少し
    • 5.1.1 リストをスタックとして使う
    • 5.1.2 リストをキューとして使う
    • 5.1.3 実用的なプログラミングツール
    • 5.1.4 リストの内包表記
  • 5.2 del 文
  • 5.3 タプルと配列
  • 5.4 辞書
  • 5.5 ループのテクニック
  • 5.6 条件についてもう少し
  • 5.7 配列とその他の型の比較

5. データ構造

この章では、すでに学んだことについてより詳しく説明するとともに、 いくつか新しいことを追加します。

5.1 リスト型についてもう少し

リストデータ型には、他にもいくつかメソッドがあります。リストオブジェクト のすべてのメソッドを以下に示します:

append( x)
リストの末尾に要素を一つ追加します。 a[len(a):] = [x] と等価です。

extend( L)
指定したリスト中のすべての要素を対象のリストに追加し、リストを 拡張します。 a[len(a):] = L と等価です。

insert( i, x)
指定した位置に要素を挿入します。 第 1 引数は、リストのインデクスで、そのインデクスを持つ要素の直前に挿入 が行われます。従って、a.insert(0, x) はリストの先頭に挿入 を行います。また a.insert(len(a), x) は a.append(x) と等価です。

remove( x)
リスト中で、値 x を持つ最初の要素を削除します。 該当する項目がなければエラーとなります。

pop( [i])
リスト中の指定された位置にある要素をリストから削除して、その要素を 返します。インデクスが指定されなければ、a.pop() はリストの 末尾の要素を返します。この場合も要素は削除されます。 (メソッドの用法 (signature) で i の両側にある角括弧は、 この引数がオプションであることを表しているだけなので、角括弧を 入力する必要はありません。この表記法は Python Library Reference の中で頻繁に見ることになるでしょう。)

index( x)
リスト中で、値 x を持つ最初の要素のインデクスを返します。 該当する項目がなければエラーとなります。

count( x)
リストでの x の出現回数を返します。

sort( )
リストの項目を、インプレース演算 (in place、元のデータを演算結果で 置き換えるやりかた) でソートします。

reverse( )
リストの要素を、インプレース演算で逆順にします。

以下にリストのメソッドをほぼ全て使った例を示します:

>>> a = [66.6, 333, 333, 1, 1234.5]
>>> print a.count(333), a.count(66.6), a.count('x')
2 1 0
>>> a.insert(2, -1)
>>> a.append(333)
>>> a
[66.6, 333, -1, 333, 1, 1234.5, 333]
>>> a.index(333)
1
>>> a.remove(333)
>>> a
[66.6, -1, 333, 1, 1234.5, 333]
>>> a.reverse()
>>> a
[333, 1234.5, 1, 333, -1, 66.6]
>>> a.sort()
>>> a
[-1, 1, 66.6, 333, 333, 1234.5]

5.1.1 リストをスタックとして使う

リスト型のメソッドのおかげで、簡単にリストをスタックとして使えます。 スタックでは、最後に追加された要素が最初に取り出されます (``last-in, first-out'') 。スタックの一番上に要素を追加するには append() を使います。スタックの一番上から要素を取り出すには pop() をインデクスを指定せずに使います。 例えば以下のようにします:

>>> stack = [3, 4, 5]
>>> stack.append(6)
>>> stack.append(7)
>>> stack
[3, 4, 5, 6, 7]
>>> stack.pop()
7
>>> stack
[3, 4, 5, 6]
>>> stack.pop()
6
>>> stack.pop()
5
>>> stack
[3, 4]

5.1.2 リストをキューとして使う

リストをキュー (queue) として手軽に使うこともできます。 キューでは、最初に追加された要素が最初に取り出されます (``first-in, first-out'')。キューの末尾に項目を追加するには append() を使います。キューの先頭から項目を取り出すには インデクスに 0 を指定して pop() を使います。 例えば以下のようにします:

>>> queue = ["Eric", "John", "Michael"]
>>> queue.append("Terry")           # Terry が到着 (arrive) する
>>> queue.append("Graham")          # Graham が到着する
>>> queue.pop(0)
'Eric'
>>> queue.pop(0)
'John'
>>> queue
['Michael', 'Terry', 'Graham']

5.1.3 実用的なプログラミングツール

組み込み関数には、リストで使うと非常に便利なものが三つあります: filter() 、 map() 、reduce() です。

"filter(function, sequence)" は、 配列 sequence 中の要素 item から、 function(item) が真となるような要素からなる 配列 (可能ならば sequence と同じ型の) 配列を返します。 例えば、いくつかの素数を計算するには以下のようにします:

>>> def f(x): return x % 2 != 0 and x % 3 != 0
...
>>> filter(f, range(2, 25))
[5, 7, 11, 13, 17, 19, 23]

"map(function, sequence)" は、 配列 sequence の各要素 item に対して function(item) を呼び出し、その戻り値からなる リストを返します。例えば、三乗された値の列を計算するには以下のように します:

>>> def cube(x): return x*x*x
...
>>> map(cube, range(1, 11))
[1, 8, 27, 64, 125, 216, 343, 512, 729, 1000]

>>> seq = range(8)
>>> def add(x, y): return x+y
...
>>> map(add, seq, seq)
[0, 2, 4, 6, 8, 10, 12, 14]

"reduce(func, sequence)" は単一の値を返します。 この値は 2 つの引数をとる関数 func を配列 sequence の最初の 二つの要素を引数として呼び出し、次にその結果と配列の次の要素を 引数にとり、以降これを繰り返すことで構成します。 例えば、 1 から 10 までの数の総和を計算するには以下のようにします:

>>> def add(x,y): return x+y
...
>>> reduce(add, range(1, 11))
55

配列中にただ一つしか要素がなければ、その値自体が返されます; 配列が空なら、例外が送出されます。

3 つめの引数をわたして、初期値を指定することもできます。 この場合、空の配列を渡すと初期値が返されます。それ以外の場合には、 まず初期値と配列中の最初の要素に対して関数が適用され、次いでその結果 と配列の次の要素に対して適用され、以降これが繰り返されます。例えば 以下のようになります:

>>> def sum(seq):
...     def add(x,y): return x+y
...     return reduce(add, seq, 0)
...
>>> sum(range(1, 11))
55
>>> sum([])
0

(2.3 以降では) 実際には、上の例のように sum() を定義しないでください: 数値の合計は広く必要とされている操作なので、すでに組み込み関数 sum(sequence) が提供されており、上の例と全く同様に 動作します。 バージョン2.3 以降で新規追加された 仕様です。

5.1.4 リストの内包表記

リストの内包表記 (list comprehension) は、リストの生成を map() や filter() や lambda の使用に 頼らずに行うための簡潔な方法を提供しています。 結果として得られるリストの定義は、しばしば上記の構文を使ってリストを 生成するよりも明快になります。各々のリストの内包表記は、 式、続いて for 節、そしてその後ろに続くゼロ個かそれ以上の for 節または if 節からなります。 式をタプルで評価したいなら、丸括弧で囲わなければなりません。

>>> freshfruit = ['  banana', '  loganberry ', 'passion fruit  ']
>>> [weapon.strip() for weapon in freshfruit]
['banana', 'loganberry', 'passion fruit']
>>> vec = [2, 4, 6]
>>> [3*x for x in vec]
[6, 12, 18]
>>> [3*x for x in vec if x > 3]
[12, 18]
>>> [3*x for x in vec if x < 2]
[]
>>> [[x,x**2] for x in vec]
[[2, 4], [4, 16], [6, 36]]
>>> [x, x**2 for x in vec]  # エラー - タプルには丸かっこが必要
  File "<stdin>", line 1, in ?
    [x, x**2 for x in vec]
               ^
SyntaxError: invalid syntax
>>> [(x, x**2) for x in vec]
[(2, 4), (4, 16), (6, 36)]
>>> vec1 = [2, 4, 6]
>>> vec2 = [4, 3, -9]
>>> [x*y for x in vec1 for y in vec2]
[8, 6, -18, 16, 12, -36, 24, 18, -54]
>>> [x+y for x in vec1 for y in vec2]
[6, 5, -7, 8, 7, -5, 10, 9, -3]
>>> [vec1[i]*vec2[i] for i in range(len(vec1))]
[8, 12, -54]

リストの内包表記は mao() よりもはるかに柔軟性があり、 一つ以上の引数を持つ関数や入れ子になった関数でも利用できます:

>>> [str(round(355/113.0, i)) for i in range(1, 6)]
['3.1', '3.14', '3.142', '3.1416', '3.14159']

5.2 del 文

指定された値の要素をリストから削除する代わりに、インデクスで指定する 方法があります: それが del 文です。この文はリストから スライスを除去することもできます (以前はスライスに空のリストを代入 して行っていました)。例えば以下のようにします:

>>> a
[-1, 1, 66.6, 333, 333, 1234.5]
>>> del a[0]
>>> a
[1, 66.6, 333, 333, 1234.5]
>>> del a[2:4]
>>> a
[1, 66.6, 1234.5]

del は変数全体の削除にも使えます:

>>> del a

この文の後で名前 a を参照すると、(別の値を a に 代入するまで) エラーになります。del の別の用途について はまた後で取り上げます。

5.3 タプルと配列

リストや文字列には、インデクスやスライスを使った演算のように、 数多くの共通の性質があることを見てきました。これらは 配列 (sequence) データ型 の二つの例です。Python はまだ 進歩の課程にある言語なので、他の配列データ型が追加されるかも しれません。標準の配列型はもう一つあります: タプル (tuple) 型です。

タプルはコンマで区切られたいくつかの値からなります。例えば以下の ように書きます:

>>> t = 12345, 54321, 'hello!'
>>> t[0]
12345
>>> t
(12345, 54321, 'hello!')
>>> # タプルを入れ子にしてもよい
... u = t, (1, 2, 3, 4, 5)
>>> u
((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))

ご覧のように、タプルは常に丸括弧で囲われています。これは、入れ子に なったタプルが正しく解釈されるようにするためです; 入力の際には 丸括弧なしでもかまいませんが、結局 (タプルがより大きな式の 一部分の場合) たいてい必要となります。

タプルの用途はたくさんあります。例えば、(x, y) 座標対、データベースから 取り出した従業員レコードなどです。タプルは文字列と同じく、変更不能です: タプルの個々の要素に代入を行うことはできません (スライスと連結を使って 同じ効果を実現することはできますが)。リストのような変更可能な オブジェクトの入ったタプルを作成することもできます。

問題は 0 個または 1 個の項目からなるタプルの構築です: これらの操作を 行うため、構文には特別な細工がされています。空のタプルは 空の丸括弧ペアで構築できます; 一つの要素を持つタプルは、 値の後ろにコンマを続ける (単一の値を丸括弧で囲むだけでは不十分です) ことで構築できます。美しくはないけれども、効果的です。例えば以下の ようにします:

>>> empty = ()
>>> singleton = 'hello',    # <-- 末尾のコンマに注目
>>> len(empty)
0
>>> len(singleton)
1
>>> singleton
('hello',)

文 t = 12345, 54321, 'hello!' は タプルのパック (tuple packing) の例です: 値 12345 、 54321 、および 'hello!' が一つのタプルにパックされます。 逆の演算も可能です:

>>> x, y, z = t

この操作は、配列のアンパック (sequence unpacking) とでも 呼ぶべきものです。配列のアンパックでは、左辺に列挙されている 変数が、右辺の配列の長さと同じであることが要求されます。 複数同時の代入が実はタプルのパックと配列のアンパックを 組み合わせたものに過ぎないことに注意してください！

この操作にはわずかな非対称性があります: 複数の値をパックすると 常にタプルが生成されますが、アンパックはどの配列にも働きます。

5.4 辞書

もう一つ、有用な型が Python に組み込まれています。それは 辞書 (dictionary) です。辞書は他の言語にも ``連想記憶 (associated memory)'' や ``連想配列 (associative array)'' として存在することがあります。 ある範囲の数でインデクス化されている配列と異なり、辞書は キー (key) でインデクス化されています。このキーは何らかの変更不能な型になります; 文字列、数値、およびタプルは常にキーにすることができます; ただし、タプルに 何らかの変更可能なオブジェクトが含まれている場合にはキーに使うことは できません。リストをキーとして使うことはできません。これは、リストの append() や extend() メソッドを使ったり、またスライス やインデクス指定の代入を行うと、インプレースで変更することができるため です。

辞書は順序付けのされていない キー(key): 値(value) のペアからなり、 キーが (辞書の中で) 一意でければならない、と考えると最もよいでしょう。 波括弧 (brace) のペア: {} は空の辞書を生成します。 カンマで区切られた key: value のペアを波括弧ペアの間に入れると、 辞書の初期値となる key: value が追加されます; この表現方法は 出力時に辞書が書き出されるのと同じ方法です。

辞書での主な操作は、ある値を何らかのキーを付けて記憶することと、 キーを指定して値を取り出すことです。 del で key: value のペアを 削除することもできます。 すでに使われているキーを使って値を記憶すると、以前そのキーに関連 づけられていた値は忘れ去られてしまいます。存在しないキーを使って 値を取り出そうとするとエラーになります。

辞書オブジェクトの keys() メソッドは、辞書で使われている 全てのキーからなるリストをランダムな順番で返します (リストをソート したいなら、このキーのリストに sort() を使ってください)。 ある単一のキーが辞書にあるかどうか調べるには、辞書の has_key() メソッドを使います。

以下に、辞書を使った小さな例を示します:

>>> tel = {'jack': 4098, 'sape': 4139}
>>> tel['guido'] = 4127
>>> tel
{'sape': 4139, 'guido': 4127, 'jack': 4098}
>>> tel['jack']
4098
>>> del tel['sape']
>>> tel['irv'] = 4127
>>> tel
{'guido': 4127, 'irv': 4127, 'jack': 4098}
>>> tel.keys()
['guido', 'irv', 'jack']
>>> tel.has_key('guido')
1

dict() コンストラクタは、キーと値のペアをタプルにしたもの からなるリストを使って直接辞書を生成します。キーと値のペアが あるパターンをなしているなら、リストの内包表現を使えばキーと値の リストをコンパクトに指定できます。

>>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])
{'sape': 4139, 'jack': 4098, 'guido': 4127}
>>> dict([(x, x**2) for x in vec])     # リスト内包表現を利用
{2: 4, 4: 16, 6: 36}

5.5 ループのテクニック

辞書の内容にわたってループを行う際、iteritems() メソッドを使うと、 キーとそれに対応する値を同時に取り出せます。

>>> knights = {'gallahad': 'the pure', 'robin': 'the brave'}
>>> for k, v in knights.iteritems():
...     print k, v
...
gallahad the pure
robin the brave

配列にわたるループを行う際、enumerate() 関数を使うと、要素の インデクスと要素を同時に取り出すことができます。

>>> for i, v in enumerate(['tic', 'tac', 'toe']):
...     print i, v
...
0 tic
1 tac
2 toe

二つまたはそれ以上の配列型を同時にループするために、 関数 zip() を使って各要素をひと組みにすることができます。

>>> questions = ['name', 'quest', 'favorite color']
>>> answers = ['lancelot', 'the holy grail', 'blue']
>>> for q, a in zip(questions, answers):
...     print 'What is your %s?  It is %s.' % (q, a)
...
What is your name?  It is lancelot.
What is your quest?  It is the holy grail.
What is your favorite color?  It is blue.

配列を逆方向に渡ってループするには、まず配列の範囲を順方向に指定し、 次いで関数reversed() を呼び出します。

>>> for i in reversed(xrange(1,10,2)):
...     print i
...
9
7
5
3
1

5.6 条件についてもう少し

前述の while や if 文 で使った条件 (condiction) には、 値の比較だけでなく、他の演算子も使うことができます、

比較演算子 in および not in は、ある値がある配列中に 存在するか (または存在しないか) どうかを調べます。演算子 is および is not は、二つのオブジェクトが実際に同じオブジェクト であるかどうかを調べます; この比較は、リストのような変更可能な オブジェクトにだけ意味があります。全ての比較演算子は同じ優先順位を 持っており、ともに数値演算子よりも低い優先順位となります。

比較は連鎖 (chain) させることができます。例えば、 a < b == c は、a が b より小さく、 かつ b と c が等しいかどうか、をテストします。

比較演算をブール演算子 and や or で組み合わせることができ、 比較演算 (あるいは何らかのブール式) の結果を not で否定 (negate) することもできます。これらは全て比較演算子よりもさらに低い優先順位を持ち ます。ブール演算子の中では、not が最も高い順位を持ち、 or が最も低くなります。これにより、 A and not B or C と (A and (not B)) or C は等価になります。 もちろん、丸括弧を使って望みの組み合わせを表現できます。

ブール演算子 and と or は、いわゆる 短絡 (short-circuit) 演算子です: これらの演算子の引数は 左から右へと順に評価され、結果が確定した時点で評価を止めます。 例えば、A と C は真で B が偽のとき、 A and B and C は式 C を評価しません。 一般に、短絡演算子の戻り値をブール値ではなくて一般的な値として用いると、 値は最後に評価された引数になります。

比較や他のブール式の結果を変数に代入することもできます。例えば、

>>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'
>>> non_null = string1 or string2 or string3
>>> non_null
'Trondheim'

Python では、C 言語と違って、式の内部で代入を行えないので注意してください。 C 言語のプログラマは不満を呈するかもしれませんが、この仕様は、 C 言語 プログラムで遭遇する、式の中で == のつもりで = とタイプ してしまうといったありふれた問題を回避します。

5.7 配列とその他の型の比較

配列オブジェクトは同じ配列型の他のオブジェクトと比較できます。 比較には 辞書的な (lexicographical) 順序が用いられます: まず、最初の二つの要素を比較し、その値が等しくなければその時点で 比較結果が決まります。等しければ次の二つの要素を比較し、以降 配列の要素が尽きるまで続けます。比較しようとする二つの要素が いずれも同じ配列型であれば、その配列間での辞書比較を再帰的に行います。 二つの配列の全ての要素の比較結果が等しくなれば、配列は等しいと みなされます。片方の配列がもう一方の先頭部分にあたる部分配列 ならば、短い方の配列が小さい (劣位の) 配列とみなされます。 文字列に対する辞書的な順序づけには、個々の文字ごとに ASCII 順序を 用います。 以下に、同じ型のオブジェクトを持つ配列間での比較を行った例を示します:

(1, 2, 3)              < (1, 2, 4)
[1, 2, 3]              < [1, 2, 4]
'ABC' < 'C' < 'Pascal' < 'Python'
(1, 2, 3, 4)           < (1, 2, 4)
(1, 2)                 < (1, 2, -1)
(1, 2, 3)             == (1.0, 2.0, 3.0)
(1, 2, ('aa', 'ab'))   < (1, 2, ('abc', 'a'), 4)

違う型のオブジェクト間の比較は認められていることに注意してください。 比較結果は決定性がありますが、その決め方は、型は型の名前で順番づけられる、 という恣意的なものです。従って、リスト (list) 型は常に文字列 (string) 型よりも小さく、文字列型は常にタプル (tuple) よりも小さい、といった 具合になります。型混合の数値の比較は、数値そのものに従って比較 されるので、例えば 0 は 0.0 と等しい、という結果になります。 5.1

... と等しい、という結果になります。5.1
異なる型のオブジェクトを比較するための規則を今後にわたって当てに してはいけません; Python 言語の将来のバージョンでは変更されるかも しれません。
Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 4. その他の制御フローツール Up: Python チュートリアル Next: 6. モジュール


6. モジュール

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 5. データ構造 Up: Python チュートリアル Next: 7. 入力と出力
  • 6.1 モジュールについてもうすこし
    • 6.1.1 モジュール検索パス
    • 6.1.2 ``コンパイル'' された Python ファイル
  • 6.2 標準モジュール
  • 6.3 dir() 関数
  • 6.4 パッケージ
    • 6.4.1 パッケージから * を import する
    • 6.4.2 パッケージ内での参照
    • 6.4.3 複数ディレクトリ中のパッケージ

6. モジュール

Python インタプリタを終了させ、再び起動すると、これまでに行ってきた 定義 (関数や変数) は失われています。ですから、より長いプログラムを 書きたいなら、テキストエディタを使ってインタプリタへの入力を用意して おき、手作業の代わりにファイルを入力に使って動作させるとよいでしょう。 この作業を スクリプト (script) の作成と言います; プログラムが 長くなるにつれ、メンテナンスを楽にするために、スクリプトをいくつかの ファイルに分割したくなるかもしれません。また、いくつかのプログラムで 書いてきた便利な関数について、その定義をコピーすることなく個々の プログラムで使いたいと思うかもしれません。

こういった要求をサポートするために、Python では定義をファイルに書いて おき、スクリプトの中やインタプリタの対話インスタンス上で使う方法が あります。 このファイルを モジュール (module) と呼びます; モジュール にある定義は、他のモジュールや main モジュール (実行の トップレベルや電卓モードでアクセスできる変数の集まりを指します) に import (取り込み) することができます。

モジュールは Python の定義や文が入ったファイルです。 ファイル名はモジュール名に接尾語 ,py がついたものになります。 モジュールの中では、(文字列の) モジュール名をグローバル変数 __name__ で取得できます。例えば、お気に入りのテキストエディタ を使って、現在のディレクトリに以下の内容のファイル fibo.py を 作成してみましょう:

# フィボナッチ数列モジュール

def fib(n):    # nまで加算されるフィボナッチ級数を印字
    a, b = 0, 1
    while b < n:
        print b,
        a, b = b, a+b

def fib2(n): # nまで加算されるフィボナッチ級数を返す
    result = []
    a, b = 0, 1
    while b < n:
        result.append(b)
        a, b = b, a+b
    return result

次に Python インタプリタに入り、モジュールを以下のコマンドで import しましょう。

>>> import fibo

この操作では、fibo で定義された関数の名前を直接現在の シンボルテーブルに入力することはありません; 単にモジュール名 fibo だけをシンボルテーブルに入れます。 関数にはモジュール名を使ってアクセスします:

>>> fibo.fib(1000)
1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
>>> fibo.fib2(100)
[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
>>> fibo.__name__
'fibo'

関数を度々使うのなら、ローカルな名前に代入できます:

>>> fib = fibo.fib
>>> fib(500)
1 1 2 3 5 8 13 21 34 55 89 144 233 377

6.1 モジュールについてもうすこし

モジュールには、関数定義に加えて実行文を入れることができます。 これらの実行文はモジュールを初期化するためのものです。 これらの実行文は、モジュールがどこかで最初に import された 時にだけ実行されます。6.1

各々のモジュールは、自前のプライベートなシンボルテーブルを持っていて、 モジュールで定義されている関数はこのテーブルをグローバルな シンボルテーブルとして使います。 したがって、モジュールの作者は、ユーザのグローバル変数と偶然的な衝突が 起こる心配をせずに、グローバルな変数をモジュールで使うことができます。 一方、自分が行っている操作をきちんと理解していれば、モジュール内の 関数を参照するのと同じ表記法 modname.itemname で、モジュールの グローバル変数をいじることもできます。

モジュールが他のモジュールを import することもできます。import 文は全てモジュールの先頭に (さらに言えばスクリプトでも) 置きますが、 これは慣習であって必須ではありません。import されたモジュール名は import を行っているモジュールのグローバルなシンボルテーブルに置かれます。

import 文には、あるモジュール内の名前を、import を実行 しているモジュールのシンボルテーブル内に直接取り込むという変型が あります。例えば:

>>> from fibo import fib, fib2
>>> fib(500)
1 1 2 3 5 8 13 21 34 55 89 144 233 377

この操作は、import の対象となるモジュール名をローカルな シンボルテーブル内に取り入れることはありません (従って上の例では、 fibo は定義されません)。

モジュールで定義されている名前を全て import するという変型もあります:

>>> from fibo import *
>>> fib(500)
1 1 2 3 5 8 13 21 34 55 89 144 233 377

上の操作は、アンダースコア (_) で開始する名前以外の全ての名前を import します。

6.1.1 モジュール検索パス

spam という名前のモジュールが import されると、インタプリタ は spam.py という名前のファイルを現在のディレクトリ内で探し、 次に環境変数PYTHONPATH に指定されているディレクトリのリスト から探します。PYTHONPATH はシェル変数 PATH と 同じ構文、すなわちディレクトリ名を並べたものです。PYTHONPATH が設定されていないか、探しているファイルが見つからなかった場合は、 検索対象をインストール方法に依存するデフォルトのパスにして続けます; Unixでは、このパスは通常 .:/usr/locall/lib/python です。

実際には、モジュールは変数 sys.path で指定されたディレクトリの リストから検索されます。sys.path は、入力とするスクリプトの 入ったディレクトリ (現在のディレクトリ)、PYTHONPATH、 およびインストール方法依存のデフォルト値を使って初期化されます。 Python プログラマは、自分の行っている操作を理解しているなら、 この変数を使ってモジュール検索パスを修正したり置き換えたりすることが できます。 起動しようとするスクリプトの入ったディレクトリが検索パス上にある ため、スクリプトが標準モジュールと同じ名前をもたないようにすることが 重要です。さもなければ、Python が標準モジュールを import するときに スクリプトをモジュールとして import しようと試みてしまうので注意 してください。このような誤りを犯すと、通常はエラーになります。 詳しくは 6.2 節、``標準モジュール.'' を参照して ください。

6.1.2 ``コンパイル'' された Python ファイル

たくさんの標準モジュールを使うような短いプログラムで重要となる 起動時間の高速化を行うために、spam.py が見つかったディレクトリに spam.pyc という名前のファイルがあった場合には、このファイルを モジュール spam の ``バイトコンパイルされた'' バージョン であると仮定します。 spam.pyc を生成するのに使われたバージョンの spam.py の ファイル修正時刻が spam.pyc に記録されており、この値が 一致しなければ spam.pyc ファイルは無視されます。

通常、spam.pyc ファイルを生成するために何かをする必要は ありません。spam.py が無事コンパイルされると、常に コンパイルされたバージョンを spam.pyc へ書き出すよう 試みます。この試みが失敗してもエラーにはなりません; 何らかの理由でファイルが完全に書き出されなかった場合、作成された smap.pyc は無効であるとみなされ、それ以後無視されます。 spam.pyc ファイルの内容はプラットフォームに依存しないので、 Python のモジュールのディレクトリは異なるアーキテクチャのマシン間で 共有することができます。

エキスパートへの助言:

  • Python インタプリタを -O フラグ付きで起動すると、 最適化 (optimize) されたコードが生成されて .pyo ファイルに 保存されます。最適化機構は今のところあまり役に立っていません; 最適化機構は assert 文と SET_LINENO 命令を除去 しているだけです。-O を使うと、すべての バイトコードが最適化されます; .pyc ファイルは無視され、 .py ファイルは最適化されたバイトコードにコンパイルされます。

  • 二つの -O フラグ (-OO) を Python インタプリタへ 渡すと、バイトコードコンパイラは、 まれにプログラムが正しく動作しなくなるかもしれないような最適化を 実行します。 現状では、ただ __doc__ 文字列をバイトコードから除去して、 よりコンパクトな .pyo ファイルにするだけです。 この文字列が利用できることをあてにしているプログラムがあるかもしれない ので、自分の行っている操作が何かわかっているときにだけこのオプションを 使うべきです。

  • .pyc ファイルや .pyo ファイルから 読み出されたとしても、プログラムは何ら高速に動作するわけでは ありません。.pyc ファイルや .pyo ファイルで高速化される のは、読み込まれるときの速度だけです。

  • スクリプトの名前をコマンドラインで指定して実行した場合、 そのスクリプトのバイトコードが .pyc や .pyo に 書き出されることはありません。従って、スクリプトのほとんどのコードを モジュールに移し、そのモジュールを import する小さなブートストラップ スクリプトを作れば、スクリプトの起動時間を短縮できるときがあります。 .pyc または .pyo ファイルの名前を直接コマンドラインに 指定することもできます。

  • 一つのモジュールについて、ファイル spam.py のない spam.pyc (-O を使ったときは spam.pyo) があってもかまいません。この仕様は、Python コードでできたライブラリを リバースエンジニアリングがやや困難な形式で配布するために使えます。

  • compileallは、.pyc ファイル (または -O を使ったときは.pyo ファイル) を ディレクトリ内の全てのモジュールに対して生成することができます。

6.2 標準モジュール

Python には標準モジュールのライブラリが付属しています。ライブラリは 独立したドキュメント Python ライブラリ リファレンス (Python Library Reference) (以降 ``ライブラリリファレンス'') で記述されています。 モジュールによってはインタプリタに組み込まれたものがあります; インタプリタに組み込まれているモジュールが提供しているのは、 言語の中核の部分ではありませんが、効率化のためや、システムコールのような オペレーティングシステムの根本機能へのアクセス手段を提供するための 操作です。これらのモジュールのセットは設定時に選択可能で、また 根底にあるプラットフォームにも依存します。例えば、amoeba モジュールは、 Amoeba の根本機能を何らかの形でサポートしているような システムでのみ提供されます。 とりわけ、注目に値するモジュールが一つあります: sys はどの Python インタプリタにも 組み込まれています。変数 sys.ps1 と sys.ps2 は、それぞれ 一次プロンプトと二次プロンプトとして使われる文字列を定義しています:

>>> import sys
>>> sys.ps1
'>>> '
>>> sys.ps2
'... '
>>> sys.ps1 = 'C> '
C> print 'Yuck!'
Yuck!
C>

これらの二つの変数は、インタプリタが対話モードにあるときだけ 定義されています。

変数 sys.path は文字列からなるリストで、インタプリタがモジュール を検索するときのパスを決定します。 sys.path は環境変数 PYTHONPATH から得たデフォルトパスに、 PYTHONPATH が設定されていなければ組み込みのデフォルト値に設定 されます。標準的なリスト操作で変更することができます:

>>> import sys
>>> sys.path.append('/ufs/guido/lib/python')

6.3 dir() 関数

組込み関数 dir() は、あるモジュールがどんな名前を定義して いるか調べるために使われます。 dir() はソートされた文字列のリストを返します:

>>> import fibo, sys
>>> dir(fibo)
['__name__', 'fib', 'fib2']
>>> dir(sys)
['__displayhook__', '__doc__', '__excepthook__', '__name__', '__stderr__',
 '__stdin__', '__stdout__', '_getframe', 'api_version', 'argv',
 'builtin_module_names', 'byteorder', 'callstats', 'copyright',
 'displayhook', 'exc_clear', 'exc_info', 'exc_type', 'excepthook',
 'exec_prefix', 'executable', 'exit', 'getdefaultencoding', 'getdlopenflags',
 'getrecursionlimit', 'getrefcount', 'hexversion', 'maxint', 'maxunicode',
 'meta_path', 'modules', 'path', 'path_hooks', 'path_importer_cache',
 'platform', 'prefix', 'ps1', 'ps2', 'setcheckinterval', 'setdlopenflags',
 'setprofile', 'setrecursionlimit', 'settrace', 'stderr', 'stdin', 'stdout',
 'version', 'version_info', 'warnoptions']

引数がなければ、dir() は現在定義している名前を列挙します。

>>> a = [1, 2, 3, 4, 5]
>>> import fibo, sys
>>> fib = fibo.fib
>>> dir()
['__name__', 'a', 'fib', 'fibo', 'sys']

変数、モジュール、関数、その他の、すべての種類の名前をリストすることに 注意してください。

dir() は、組込みの関数や変数の名前はリストしません。 これらの名前からなるリストが必要なら、標準モジュール __builtin__で定義されています:

>>> import __builtin__
>>> dir(__builtin__)
['ArithmeticError', 'AssertionError', 'AttributeError',
 'DeprecationWarning', 'EOFError', 'Ellipsis', 'EnvironmentError',
 'Exception', 'False', 'FloatingPointError', 'IOError', 'ImportError',
 'IndentationError', 'IndexError', 'KeyError', 'KeyboardInterrupt',
 'LookupError', 'MemoryError', 'NameError', 'None', 'NotImplemented',
 'NotImplementedError', 'OSError', 'OverflowError', 'OverflowWarning',
 'PendingDeprecationWarning', 'ReferenceError',
 'RuntimeError', 'RuntimeWarning', 'StandardError', 'StopIteration',
 'SyntaxError', 'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError',
 'True', 'TypeError', 'UnboundLocalError', 'UnicodeError', 'UserWarning',
 'ValueError', 'Warning', 'ZeroDivisionError', '__debug__', '__doc__',
 '__import__', '__name__', 'abs', 'apply', 'bool', 'buffer',
 'callable', 'chr', 'classmethod', 'cmp', 'coerce', 'compile', 'complex',
 'copyright', 'credits', 'delattr', 'dict', 'dir', 'divmod',
 'enumerate', 'eval', 'execfile', 'exit', 'file', 'filter', 'float',
 'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex', 'id',
 'input', 'int', 'intern', 'isinstance', 'issubclass', 'iter',
 'len', 'license', 'list', 'locals', 'long', 'map', 'max', 'min',
 'object', 'oct', 'open', 'ord', 'pow', 'property', 'quit',
 'range', 'raw_input', 'reduce', 'reload', 'repr', 'round',
 'setattr', 'slice', 'staticmethod', 'str', 'string', 'sum', 'super',
 'tuple', 'type', 'unichr', 'unicode', 'vars', 'xrange', 'zip']

6.4 パッケージ

パッケージ (package) は、Python のモジュール名前空間 を ``ドット付きモジュール名 (dotted module names)'' を使って 構造化する手段です。例えば、モジュール名 A.B は、 "A" というパッケージのサブモジュール "B" を表します。 ちょうど、モジュールを利用すると、別々のモジュールの著者が互いの グローバル変数名について心配しなくても済むようになるのと同じように、 ドット付きモジュール名を利用すると、 NumPy や Python Imaging Library のように複数モジュールからなる パッケージの著者が、互いのモジュール名について心配しなくても済むように なります。

音声ファイルや音声データを一様に扱うためのモジュールのコレクション (``パッケージ'') を設計したいと仮定しましょう。音声ファイルには 多くの異なった形式がある (通常は拡張子、例えば .wav, .aiff, .au などで認識されます) ので、 様々なファイル形式間で変換を行うためのモジュールからなる、 次第に増えていくモジュールのコレクションを作成したりメンテナンス したりする必要がありかもしれません。また、音声データに対して 実行したい様々な独自の操作 (ミキシング、エコーの追加、 イコライザ関数の適用、人工的なステレオ効果の作成など) があるかも しれません。そうなると、こうした操作を実行するモジュールを果てしなく 書くことになるでしょう。以下に (階層的なファイルシステムで表現した) パッケージの構造案を示します:

Sound/                          トップレベルのパッケージ
      __init__.py               サウンドパッケージを初期化する
      Formats/                  ファイルフォーマット変換用の下位パッケージ
              __init__.py
              wavread.py
              wavwrite.py
              aiffread.py
              aiffwrite.py
              auread.py
              auwrite.py
              ...
      Effects/                  サウンド効果用の下位パッケージ
              __init__.py
              echo.py
              surround.py
              reverse.py
              ...
      Filters/                  フィルタ用の下位パッケージ
              __init__.py
              equalizer.py
              vocoder.py
              karaoke.py
              ...

パッケージを import する際、 Python は sys.path 上のディレクトリ を検索して、トップレベルのパッケージの入ったサブディレクトリを探します。

あるディレクトリを、パッケージが入ったディレクトリとしてPython に 扱わせるには、ファイル __init__.py が必要です: このファイルを置かなければならないのは、"string" のような よくある名前のディレクトリにより、モジュール検索パスの後の方で見つかる 正しいモジュールが意図せず隠蔽されてしまうのを防ぐためです。 最も簡単なケースでは __init__.py はただの空ファイルで 構いませんが、__init__.py ではパッケージのための初期化コード を実行したり、後述の __all__ 変数を設定してもかまいません。

パッケージのユーザは、個々のモジュールをパッケージから import することができます。例えば:

import Sound.Effects.echo

この操作はサブモジュール Sound.Effects.echo をロードします。 このモジュールは、以下のように完全な名前で参照しなければなりません:

Sound.Effects.echo.echofilter(input, output, delay=0.7, atten=4)

サブモジュールを import するもう一つの方法を示します:

from Sound.Effects import echo

これもサブモジュール echo をロードし、echo を パッケージ名を表す接頭辞なしで利用できるようにします。従って以下のように 用いることができます:

echo.echofilter(input, output, delay=0.7, atten=4)

さらにもう一つのバリエーションとして、必要な関数や変数を直接 import する 方法があります:

from Sound.Effects.echo import echofilter

この操作も同様にサブモジュール echo をロードしますが、 echofilter を直接利用できるようにします。

echofilter(input, output, delay=0.7, atten=4)

from package import item を使う場合、item は パッケージ package のサブモジュール (またはサブパッケージ) でも かまいませんし、関数やクラス、変数のような、package で定義されて いる別の名前でもかまわないことに注意してください。 import 文はまず、item がパッケージ内で定義されているか どうか調べます; 定義されていなければ、item はモジュール 名であると仮定して、モジュールをロードしようと試みます。もし モジュールが見つからなければ、ImportError が送出されます。

反対に、import item.subitem.subsubitem のような構文を 使った場合、最後の subsubitem を除く各要素はパッケージで なければなりません; 最後の要素はモジュールかパッケージにできますが、 一つ前の要素で定義されているクラスや関数や変数にはできません。

6.4.1 パッケージから * を import する

それでは、ユーザが from Sound.Effects import * と書いたら、 どうなるのでしょうか？ 理想的には、何らかの方法でファイルシステムが 調べられ、そのパッケージにどんなサブモジュールがあるかを調べ上げ、 全てを import する、という処理を望むことでしょう。残念ながら、 この操作は Mac や Windows のプラットフォームではうまく動作しません。 これらのプラットフォームでは、ファイルシステムはファイル名の 大小文字の区別について正しい情報をもっているとは限らないからです！ こうしたプラットフォームでは、ファイル ECHO.PY を モジュール echo として import すべきか、Echo と すべきかが分かる確かな方法がないからです (例えば、 Windows 95 は すべてのファイル名の最初の文字を大文字にして表示するという困った 慣習があります)。また、DOS の 8+3 のファイル名制限のせいで、 長いモジュール名に関して別の奇妙な問題が追加されています。

唯一の解決策は、パッケージの作者にパッケージの索引を明示的に提供 させるというものです。 import 文は次の規約を使います: パッケージの __init__.py コード に __all__ という名前のリストが定義されていれば、 from package import * が現れたときに import する リストとして使います。新たなパッケージがリリースされるときに リストを最新の状態に更新するのはパッケージの作者の責任となります。 自分のパッケージから * を import するという使い方に同意できなければ、 パッケージの作者は __init__.py をサポートしないことにしても かまいません。 例えば、ファイル Sounds/Effects/__init__.py には、次のような コードを入れてもよいかもしれません:

__all__ = ["echo", "surround", "reverse"]

このコードは、 from Sound.Effects import * とすると、 Sound パッケージから指定された 3 つのサブモジュールが import されることになっている、ということを意味します。

もしも __all__ が定義されていなければ、実行文 from Sound.Effects import * は、パッケージ Sound.Effects の全てのサブモジュールを現在の名前空間の中へ import しません; この文は単に (場合によっては初期化コード __init__.py を実行して) パッケージ Sound.Effects が import されたということを確認し、 そのパッケージで定義されている名前を全て import するだけです。 import される名前には、__init__.py で定義された名前 (と、明示的にロードされたサブモジュール) が含まれます。 パッケージのサブモジュールで、以前の import 文で明示的にロードされた ものも含みます。以下のコードを考えてください:

import Sound.Effects.echo
import Sound.Effects.surround
from Sound.Effects import *

上の例では、echo と surround モジュールが現在の名前空間に import されます。これらのモジュールは from...import 文が 実行された際に Sound.Effects 内で定義されているからです (この機構は__all__ が定義されているときにも働きます)。

一般的には、モジュールやパッケージから * を import するという やり方には賛同できません。というのは、この操作を行うとしばしば可読性に 乏しいコードになるからです。しかし、対話セッションでキータイプの量を 減らすために使うのは構わないでしょう。それに、特定のモジュールでは、 特定のパターンに従った名前のみを公開 (export) するように設計されています。

from package import specific_submodule を使っても何も問題は ないことに留意してください！実際この表記法は、import を行うモジュールが 他のパッケージかと同じ名前を持つサブモジュールを使わなければ ならない場合を除いて推奨される方式です。

6.4.2 パッケージ内での参照

サブモジュール同士で互いに参照を行う必要がしばしば起こります。 例えば、surround モジュールは echo モジュールを 使うかもしれません。実際には、このような参照はよくあることなので、 import 文を実行すると、まず最初に import 文の入っている パッケージを検索し、その後になって標準のモジュール検索パスを 見に行きます。こうして、surround モジュールは単に import echo や from echo import echofilter を使うことができます。 import されたモジュールが現在のパッケージ (現在のモジュールを サブモジュールにしているパッケージ) 内に見つからなかった場合、 import 文は指定した名前のトップレベルのモジュールを検索 します。

パッケージが (前述の例の Sound パッケージのように) サブパッケージの集まりに構造化されている場合、兄弟関係にある パッケージを短縮された記法で参照する方法は存在しません - サブパッケージ の完全な名前を使わなければなりません。例えば、モジュール Sound.Filters.vocoder で Sound.Effects パッケージの echo モジュールを使いたいとすると、 from Sound.Effects import echo を使うことはできます。

6.4.3 複数ディレクトリ中のパッケージ

パッケージのサポートする特殊な属性には、もう一つ __path__ が あります。この属性は、パッケージの __init__.py 中のコードが 実行されるよりも前に、__init__.py の収められているディレクトリ名 の入ったリストになるよう初期化されます。 この変数は変更することができます; 変更を加えると、以降そのパッケージに 入っているモジュールやサブパッケージの検索に影響します。

この機能はほとんど必要にはならないのですが、パッケージ内に見つかる モジュールのセットを拡張するために使うことができます。

... 時にだけ実行されます。6.1
実際には、関数定義も `実行' される `文' です; モジュールを実行すると、関数名はモジュールのグローバルな シンボルテーブルに入力されます。
Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 5. データ構造 Up: Python チュートリアル Next: 7. 入力と出力


7. 入力と出力

プログラムの出力をもたらす方法はいくつかあります; データは人間が可読 な形で出力することも、将来使うためにファイルに書くこともできます。 この章では、こうした出力のいくつかの可能性について議論します。

7.1 ファンシーな出力の書式化

これまでのところ、値を出力する二つの方法: 式でできた文 (expression statement) と print 文が出てきました。(第三は ファイルオブジェクトの write() を使う方法です; 標準出力 を表すファイルは sys.stdout で参照できます。詳細は ライブラリリファレンスを参照してください。)

出力を書式化する際に、単に値をスペースで区切って出力するよりも もっときめ細かな制御をしたいと思うことがしばしばあるでしょう。 出力を書式化するには二つの方法があります; 第一の方法は、全ての 文字列を自分で処理するというものです; 文字列のスライスや結合といった操作を 使えば、思い通りのレイアウトを作成することができます。 標準モジュール stringには、 文字列を指定されたカラム幅にそろえるための便利な操作がいくつか あります; これらの操作ついては、後で簡単に説明します。 第二の方法は % 演算子を使い、文字列を演算子の左引数 (left argument) として使う方法です。% 演算子は、左引数を sprintf() のような形式で解釈して右引数に適用し、 その書式化操作で得られた文字列を返します。

もちろん、一つ問題があります。値をどうやって文字列に変換したら いいのでしょうか？幸運なことに、Python には値を文字列に変換する方法が あります: 値を repr() か str() 関数に渡して ください。逆クオート (``) は repr() と等しい 操作ですが、利用はお勧めしません。

str() 関数は、値を表現するときにかなり人間にとって可読な ものにするためのものです。一方、repr() は インタプリタで読めるような表現にする (あるいは、等価な値を表現する ための構文がない場合には SyntaxError を送出させる) ためのものです。 人間が利用するための特別な表現をもたないオブジェクトでは、 str() は repr() と同じ値を返します。 数値や、リストや辞書といった構造体のような多くの値は、どちらの関数でも 同じ表現になります。文字列と浮動小数点は特別で、二つの 別個の表現となります。

下にいくつか例を挙げます:

>>> s = 'Hello, world.'
>>> str(s)
'Hello, world.'
>>> repr(s)
"'Hello, world.'"
>>> str(0.1)
'0.1'
>>> repr(0.1)
'0.10000000000000001'
>>> x = 10 * 3.25
>>> y = 200 * 200
>>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
>>> print s
The value of x is 32.5, and y is 40000...
>>> # 文字列への repr() はクォートとバックスラッシュが付加される:
... hello = 'hello, world\n'
>>> hellos = repr(hello)
>>> print hellos
'hello, world\n'
>>> # repr() の引数は Python オブジェクトの場合もある:
... repr((x, y, ('spam', 'eggs')))
"(32.5, 40000, ('spam', 'eggs'))"
>>> # 逆クォートは対話セッショで便利である:
... `x, y, ('spam', 'eggs')`
"(32.5, 40000, ('spam', 'eggs'))"

以下に 2 乗と 3 乗の値からなる表を書く二つの方法を示します:

>>> for x in range(1, 11):
...     print repr(x).rjust(2), repr(x*x).rjust(3),
...     # 上の行の末尾のコンマに注意
...     print repr(x*x*x).rjust(4)
...
 1   1    1
 2   4    8
 3   9   27
 4  16   64
 5  25  125
 6  36  216
 7  49  343
 8  64  512
 9  81  729
10 100 1000
>>> for x in range(1,11):
...     print '%2d %3d %4d' % (x, x*x, x*x*x)
...
 1   1    1
 2   4    8
 3   9   27
 4  16   64
 5  25  125
 6  36  216
 7  49  343
 8  64  512
 9  81  729
10 100 1000

(各カラムの間のスペース一個は print の働きで追加されて いることに注意してください: print は引数間に常に 空白を追加します)

この例では、メソッド rjust() を実際に利用しています。 rjust() は文字列を指定された幅のフィールド内に 右詰めで入るように、左に空白を追加します。同様のメソッドとして、 ljust() と center() が あります。これらのメソッドは何か出力を行うわけではなく、ただ新しい文字列を 返します。入力文字列が長すぎる場合、文字列を切り詰めることはせず、 ただ値をそのまま返します; この仕様のために、カラムのレイアウトが 滅茶苦茶になるかもしれませんが、嘘の値が代わりに書き出される よりはましです。(本当に切り詰めを行いたいのなら、全てのカラムに "ljust(x, n)[0:n]") のようにスライス表記を加える こともできます。)

もう一つのメソッド、 zfill() は、数値文字列 の左側をゼロ詰めします。このメソッドは正と負の符号を正しく扱います:

>>> '12'.zfill(5)
'00012'
>>> '-3.14'.zfill(7)
'-003.14'
>>> '3.14159265359'.zfill(5)
'3.14159265359'

% 演算子を使う場合は以下のようになります:

>>> import math
>>> print 'The value of PI is approximately %5.3f.' % math.pi
The value of PI is approximately 3.142.

文字列の中に複数の書式がある場合には、以下の例のように、右側の被演算子 にタプルを渡す必要があります:

>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
>>> for name, phone in table.items():
...     print '%-10s ==> %10d' % (name, phone)
...
Jack       ==>       4098
Dcab       ==>       7678
Sjoerd     ==>       4127

ほとんどの書式化は C 言語と同じように動作し、正しい型を渡す 必要があります; しかし、正しい型を渡さなかった場合にはコアダンプ ではなく例外の送出になります。書式 %s はもっと寛大です: 対応する引数が文字列オブジェクトでなければ、組込み関数 str() を使って文字列に変換してくれます。また、数値表現の桁幅や精度を別個の (整数の) 引数として渡せるよう、* がサポートされています。 C 言語の書式 %n と %p はサポートされていません。

もしも長い書式化文字列があり、それを分割したくない場合には、 変数を引数の位置ではなく、変数の名前で参照できるとよいでしょう。 以下の形式 %(name)format を使えば可能になります:

>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
>>> print 'Jack: %(Jack)d; Sjoerd: %(Sjoerd)d; Dcab: %(Dcab)d' % table
Jack: 4098; Sjoerd: 4127; Dcab: 8637678

全てのローカルな変数が入った辞書を返す、新たに紹介する組み込み関数 vars() と組み合わせると特に便利です。

7.2 ファイルを読み書きする

open() はファイルオブジェクトを
返します。 open() は、
"open(filename, mode)" のように二つの引数を伴って
呼び出されることがほとんどです。

>>> f=open('/tmp/workfile', 'w')
>>> print f
<open file '/tmp/workfile', mode 'w' at 80a0960>

最初の引数はファイル名の入った文字列です。二つめの引数もまた文字列で、 ファイルをどのように使うかを示す数個の文字が入っています。 mode は、ファイルが読み出し専用なら 'r' 、 書き込み専用 (同名の既存のファイルがあれば消去されます) なら 'w' とします。'a' はファイルを追記用に開きます; ファイルに書き込まれた 内容は自動的にファイルの終端に追加されます。'r+' はファイルを読み 書き両用に開きます。mode 引数はオプションです; 省略された場合には 'r' であると仮定します。

Windows や Macintosh では、mode に 'b' を追加すると ファイルをバイナリモードで開きます。したがって、 'rb', 'wb', 'r+b' といったモードがあります。 Windows はテキストファイルとバイナリファイルを区別しています; テキストファイルでは、読み書きの際に行末文字が自動的に少し変更 されます。 この舞台裏でのファイルデータ変更は、ASCII でできたテキストファイル では差し支えないものですが、JPEG や .EXE ファイルのような バイナリデータは破損してしまうことになるでしょう。 こうしたファイルを読み書きする際にはバイナリモードを使うよう十分 注意してください。 (Macintosh では、テキストモードに対する 厳密な意味付けは、根底にある使用中の C 言語ライブラリに依存する ので注意してください。)

7.2.1 ファイルオブジェクトのメソッド

この節の以降の例は、f というファイルオブジェクトが既に 生成されているものと仮定します。

ファイルの内容を読み出すには、f.read(size) を呼び出します。 このメソッドはある量のデータを読み出して、文字列として返します。 size はオプションの数値引数です。size が省略されたり 負の数であった場合、ファイルの内容全てを読み出して返します; ただし、 ファイルがマシンのメモリの二倍の大きさもある場合にはどうなるか わかりません。 size が負でない数ならば、最大で size バイトを読み出して 返します。ファイルの終端にすでに達していた場合、f.read() は 空の文字列 ("") を返します。

>>> f.read()
'This is the entire file.\n'
>>> f.read()
''

f.readline() はファイルから 1 行だけを読み取ります; 改行文字 (\n) は読み出された文字列の終端に残ります。 改行が省略されるのは、ファイルが改行で終わっていない場合の最終行 のみです。これは、戻り値があいまいでないようにするためです; f.readline() が空の文字列を返したら、ファイルの終端に 達したことが分かります。一方、空行は '\n' 、すなわち 改行 1 文字だけからなる文字列で表現されます。

>>> f.readline()
'This is the first line of the file.\n'
>>> f.readline()
'Second line of the file\n'
>>> f.readline()
''

f.readlines() は、ファイルに入っているデータの全ての行からなる リストを返します。オプションのパラメタ sizehint が指定されて いれば、ファイルから指定されたバイト数を読み出し、さらに一行を完成 させるのに必要なだけを読み出して、読み出された行からなる リストを返します。このメソッドは巨大なファイルを行単位で効率的に 読み出すためによく使われます。未完成の行が返されることはありません。

>>> f.readlines()
['This is the first line of the file.\n', 'Second line of the file\n']

f.write(string) は、 string の内容をファイルに 書き込み、None を返します。

>>> f.write('This is a test\n')

f.tell() は、ファイルオブジェクトが指しているあるファイル中の 位置を示す整数を、ファイルの先頭からのバイト数で図った値で返します。 ファイルオブジェクトの位置を変更するには、"f.seek(offset, from_what)" を使います。ファイル位置は基準点 (reference point) にオフセット値 offset を足して計算されます; 参照点は from_what 引数で選びます。 from_what の値が 0 ならばファイルの先頭から測り、 1 ならば現在のファイル位置を使い、2 ならばファイルの終端を 参照点として使います。 from_what は省略することができ、デフォルトの値は 0 、すなわち 参照店としてファイルの先頭を使います。

>>> f=open('/tmp/workfile', 'r+')
>>> f.write('0123456789abcdef')
>>> f.seek(5)     # ファイルの第6バイトへ行く
>>> f.read(1)
'5'
>>> f.seek(-3, 2) # 終端から前へ第3バイトへ行く
>>> f.read(1)
'd'

ファイルが用済みになったら、f.close() を呼び出してファイルを 閉じ、ファイルを開くために取られていたシステム資源を解放します。 f.close() を呼び出した後、そのファイルオブジェクトを使おうと すると自動的に失敗します。

>>> f.close()
>>> f.read()
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
ValueError: I/O operation on closed file

ファイルオブジェクトには、他にも isatty() や truncate() といった、あまり使われないメソッドがあります; ファイルオブジェクトについての完全なガイドは、ライブラリリファレンスを 参照してください。

7.2.2 pickle モジュール

文字列をファイルに読み書きするのは簡単にできます。数値でもほんの わずかに苦労するくらいです。というのは、read() は文字列だけを 返すので、'123' のような文字列を受け取って、その数値 123 を返す int() のような関数に対して文字列を渡してやらなければ ならないからです。ところが、リストや辞書、クラスのインスタンスのように、 もっと複雑なデータ型を保存したいなら、事態はもっと複雑になります。

複雑なデータ型を保存するためのコードを利用者に毎回毎回書かせて デバッグさせる代わりに、Python では pickle という標準 モジュールを用意しています。pickle は驚くべきモジュールで、 ほとんどどんな Python オブジェクトも (ある形式の Python コード でさえも!) 受け取って文字列表現へ変換できます。 この変換過程は pickling (ピクルス (漬物) 化、以降 pickle 化) と呼ばれます。文字列表現からオブジェクトを再構成する操作は unpickling (逆 pickle 化)と呼びます。 pickle 化や逆 unpickle 化の間、オブジェクトを表現する文字列は ファイルやデータに保存したり、ネットワーク接続を介して離れたマシンに 送信したりできます。

オブジェクト x と、書込み用に開かれているファイルオブジェクト f があると仮定すると、オブジェクトを pickle 化する最も簡単な 方法は、たった一行のコードしか必要ありません:

pickle.dump(x, f)

逆 pickle 化して再びオブジェクトに戻すには、 f を読取り用に開かれているファイル・オブジェクトと仮定して:

x = pickle.load(f)

とします。

(逆 pickle 化にはいくつか変型があり、たくさんのオブジェクトを pickle 化 したり、 pickle 化されたデータをファイルに書きたくないときに使われます。 完全なドキュメントについては、 ライブラリリファレンス の pickle を調べてください。)

pickle は、Python のオブジェクトを保存できるようにし、 他のプログラムや、同じプログラムが将来起動されたときに再利用 できるようにする標準の方法です; 技術的な用語でいうと persistent (永続性) オブジェクトです。 pickle はとても広範に使われている ので、Python 拡張モジュールの多くの作者は、行列のような新たなデータ型が 正しく pickle 化/unpickle 化できるよう気をつけています。

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 6. モジュール Up: Python チュートリアル Next: 8. エラーと例外


8. エラーと例外

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 7. 入力と出力 Up: Python チュートリアル Next: 9. クラス
  • 8.1 構文エラー
  • 8.2 例外
  • 8.3 例外を処理する
  • 8.4 例外を送出する
  • 8.5 ユーザ定義の例外
  • 8.6 後片付け動作を定義する

8. エラーと例外

これまでエラーメッセージについては簡単に触れるだけでしたが、チュートリアル 中の例を自分で試していたら、実際にいくつかのエラーメッセージを見ている ことでしょう。エラーには (少なくとも) 二つのはっきり異なる種類があります: それは 構文エラー (syntax error) と例外 (exception) です。

8.1 構文エラー

構文エラーは構文解析エラー (parsing error) としても知られており、 まだ Python を学習中なら、おそらくもっともよく受け取る種の文句でしょう:

>>> while True print 'Hello world'
  File "<stdin>", line 1, in ?
    while True print 'Hello world'
                   ^
SyntaxError: invalid syntax

パーサは違反の起きている行を繰り返し、小さな `矢印' を表示して、 違反の起きている行中でエラーが検出された最初の位置を示します。 エラーは矢印の直前の トークンでひき起こされています (または、 少なくともそこで検出されています)。 上述の例の中では、エラーは print で検出されています。 コロン (":") がその前に無いからです。 入力がスクリプトから来ている場合は、どこを見ればよいか分かるように ファイル名と行番号が出力されます。

8.2 例外

たとえ文や式が構文的に正しくても、実行しようとしたときにエラーが 発生するかもしれません。 実行中に検出されたエラーは 例外 (exception) と呼ばれ、 常に致命的とは限りません: Python プログラムで例外をどのように扱うかは、 すぐに習得することでしょう。ほとんどの例外はプログラムで処理されず、 以下に示されるようなメッセージになります:

>>> 10 * (1/0)
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
ZeroDivisionError: integer division or modulo by zero
>>> 4 + spam*3
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
NameError: name 'spam' is not defined
>>> '2' + 2
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: cannot concatenate 'str' and 'int' objects

エラーメッセージの最終行は何が起こったかを示しています。 例外は様々な例外型 (type) で起こり、その型がエラーメッセージの 一部として出力されます: 上の例での型は ZeroDivisionError, NameError, TypeError です。 例外型として出力される文字列は、発生した例外の組み込み名です。 これは全ての組み込み例外について成り立ちますが、 ユーザ定義の例外では (成り立つようにするのは有意義な慣習ですが) 必ずしも成り立ちません。 標準例外の名前は組み込みの識別子です (予約語ではありません)。

残りの行は例外の詳細で、その解釈は例外の型に依存します; これらの行の意味するところは例外の型に依存します。

エラーメッセージの先頭部分では、例外が発生した実行コンテキスト (context) を、スタックのバックトレース (stack backtrace) の 形式で示しています。一般には、この部分にはソースコード行を リストしたバックトレースが表示されます; しかし、標準入力から 読み取られた行については表示しません。

Python ライブラリリファレンス には、組み込み例外とその意味がリストされています。

8.3 例外を処理する

例外を選別して処理するようなプログラムを書くことができます。 以下の例を見てください。この例では、有効な文字列が入力されるまで ユーザに入力を促しますが、ユーザがプログラムに (Control-C か、またはオペレーティングシステムがサポート している何らかのキーを使って) 割り込みをかけてプログラムを 中断させることができるようにしています; ユーザが生成した割り込みは、 KeyboardInterrupt 例外が送出されることで通知される ということに注意してください。

>>> while True:
...     try:
...         x = int(raw_input("Please enter a number: "))
...         break
...     except ValueError:
...         print "Oops! That was no valid number.  Try again..."
...

try 文は下記のように動作します。

  • まず、 try 節 (try clause) (キーワード try と except のあいだの文) が実行されます。

  • 何も例外が発生しなければ、except 節 をスキップして try 文の実行を終えます。

  • try 節内の実行中に例外が発生すると、その節の残りは飛ばされます。 次に、例外型が except キーワードの後に指定されている 例外に一致する場合、try 節の残りはスキップして、 except 節が実行 された後、 try 節の後の文に実行が継続されます。

  • もしも except 節で指定された例外と一致しない例外が発生すると、 その例外は try 文の外側に渡されます。例外に対する ハンドラ (handler、処理部) がどこにもなければ、 処理されない例外 (unhandled exception) となり、 上記に示したようなメッセージを出して実行を停止します。

一つの try 文に複数の except 節を設けて、さまざまな例外に 対するハンドラを指定することができます。同時に一つ以上のハンドラが 実行されることはありません。ハンドラは対応する try 節内で発生した 例外だけを処理し、同じ try 節内の別の例外ハンドラで起きた例外は 処理しません。except 節には複数の例外を丸括弧で囲ったリストにして 渡すことができます。例えば以下のようにします:

... except (RuntimeError, TypeError, NameError):
...     pass

最後の except 節では例外名を省いて、ワイルドカード (wildcard、総称記号) にすることができます。ワイルドカードの except 節は非常に注意して使って ください。というのは、ワイルドカードは通常のプログラムエラーをたやすく 隠してしまうからです！ワイルドカードの except 節はエラーメッセージを 出力した後に例外を再送出する (関数やメソッドの呼び出し側が同様にして 例外を処理できるようにする) 用途にも使えます:

import sys

try:
    f = open('myfile.txt')
    s = f.readline()
    i = int(s.strip())
except IOError, (errno, strerror):
    print "I/O error(%s): %s" % (errno, strerror)
except ValueError:
    print "Could not convert data to an integer."
except:
    print "Unexpected error:", sys.exc_info()[0]
    raise

try ... except 文には、オプションで else 節 (else clause) を設けることができます。else 節を設ける場合、全ての except 節よりも後ろに置かねばなりません。 except 節は、try 節で全く例外が送出されなかったときに 実行されるコードを書くのに役立ちます。例えば以下のようにします:

for arg in sys.argv[1:]:
    try:
        f = open(arg, 'r')
    except IOError:
        print 'cannot open', arg
    else:
        print arg, 'has', len(f.readlines()), 'lines'
        f.close()

追加のコードを追加するのは try 節の後ろよりも else 節の方がよいでしょう。なぜなら、そうすることで try ... except 文で保護したいコードから 送出されたもの以外の例外を偶然に捕捉してしまうという事態を避けられる からです。

例外が発生するとき、例外に関連付けられた値を持つことができます。 この値は例外の例外の引数 (argument) としても知られています。 引数の有無と引数の型がどうなっているかは例外の型に依存します。

except 節では、例外名 (または例外名リスト) の後に変数を指定することが できます。この変数は例外インスタンスに結び付けられており、 instance.args に例外インスタンス生成時の引数が入っています。 例外インスタンスには __getitem__ および __str__ が 定義されており、.args を参照しなくても引数に直接アクセスしたり 印字したりできるように利便性が図られています。

>>> try:
...    raise Exception('spam', 'eggs')
... except Exception, inst:
...    print type(inst)     # 例外インスタンス
...    print inst.args      # .args に記憶されている引数
...    print inst           # __str__ で引数を直接出力できる
...    x, y = inst          # __getitem__ で引数を直接アンパックできる
...    print 'x =', x
...    print 'y =', y
...
<type 'instance'>
('spam', 'eggs')
('spam', 'eggs')
x = spam
y = eggs

処理されない例外の場合、例外が引数を持っていれば、メッセージの 最後の (`詳細説明の') 部分に出力されます。

例外ハンドラは、try 節でじかに発生した例外を処理するだけではなく、 その try 節から呼び出された関数の内部で発生した例外も処理します (間接的に呼ばれていてもです) 。例えば:

>>> def this_fails():
...     x = 1/0
...
>>> try:
...     this_fails()
... except ZeroDivisionError, detail:
...     print 'Handling run-time error:', detail
...
Handling run-time error: integer division or modulo

8.4 例外を送出する

raise 文を使うと、プログラマは指定した例外を強制的に 送出させられます。例えば:

>>> raise NameError, 'HiThere'
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
NameError: HiThere

raise の第一引数には、ひき起こすべき例外を指定します。 オプションの第二引数では例外の引数を指定します。

例外が発生したかどうかは判定したいが、その処理を行おうとは思っていない 場合、単純な形式の raise 文を使って例外を再送出させることが できます:

>>> try:
...     raise NameError, 'HiThere'
... except NameError:
...     print 'An exception flew by!'
...     raise
...
An exception flew by!
Traceback (most recent call last):
  File "<stdin>", line 2, in ?
NameError: HiThere

8.5 ユーザ定義の例外

プログラム上で新しい例外クラスを作成することで、独自の例外を指定する ことができます。例外は、典型的に Exception クラスから、 直接または間接的に導出したものです。例えば:

>>> class MyError(Exception):
...     def __init__(self, value):
...         self.value = value
...     def __str__(self):
...         return repr(self.value)
...
>>> try:
...     raise MyError(2*2)
... except MyError, e:
...     print 'My exception occurred, value:', e.value
...
My exception occurred, value: 4
>>> raise MyError, 'oops!'
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
__main__.MyError: 'oops!'

例外クラスでは、他のクラスができることなら何でも定義することが できますが、通常は単純なものにしておきます。たいていは、いくつかの 属性だけを提供し、例外が発生したときにハンドラがエラーに関する情報 を取り出せるようにする程度にとどめます。 複数の別個の例外を送出するようなモジュールを作成する際には、 そのモジュールで定義されている例外の基底クラスを作成するのが 一般的なならわしです:

class Error(Exception):
    """Base class for exceptions in this module."""
    pass

class InputError(Error):
    """Exception raised for errors in the input.

    Attributes:
        expression -- input expression in which the error occurred
        message -- explanation of the error
    """

    def __init__(self, expression, message):
        self.expression = expression
        self.message = message

class TransitionError(Error):
    """Raised when an operation attempts a state transition that's not
    allowed.

    Attributes:
        previous -- state at beginning of transition
        next -- attempted new state
        message -- explanation of why the specific transition is not allowed
    """

    def __init__(self, previous, next, message):
        self.previous = previous
        self.next = next
        self.message = message

ほとんどの例外は、標準の例外の名前付けと同様に、 ``Error,'' で終わる名前で定義されています。

多くの標準モジュールでは、モジュールで定義されている関数内で発生する 可能性のあるエラーを報告させるために、独自の例外を定義しています。 クラスについての詳細な情報は 9 章、 ``クラス'' で 提供されています。

8.6 後片付け動作を定義する

try 文にはもう一つオプションの節があります。この節は クリーンアップ動作を定義するためのもので、どんな状況でも必ず 実行されます。例えば:

>>> try:
...     raise KeyboardInterrupt
... finally:
...     print 'Goodbye, world!'
...
Goodbye, world!
Traceback (most recent call last):
  File "<stdin>", line 2, in ?
KeyboardInterrupt

finally 節 (finally clause) は、 try 節で例外が発生したかどうかに関係なく実行されます。 例外が発生した時は、finally 節を実行した後、その例外を再送出します。 finally 節はまた、try 文から break 文や return 文経由で抜ける際にも、 ``抜ける途中で'' 実行されます。

finally 節中のコードは (ファイルやネットワーク接続のような) 外部の資源 について、資源の利用が成功したかどうかに関係なく解放を行うのに便利です。

try 文には、一個以上の except 節か、または一個の finally 節を持たねばなりませんが、両方持つことはできません。

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 7. 入力と出力 Up: Python チュートリアル Next: 9. クラス


9. クラス

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 8. エラーと例外 Up: Python チュートリアル Next: 10. 標準ライブラリの簡単なツアー
  • 9.1 用語について一言
  • 9.2 Python のスコープと名前空間
  • 9.3 クラス初見
    • 9.3.1 クラス定義の構文
    • 9.3.2 クラスオブジェクト
    • 9.3.3 インスタンスオブジェクト
    • 9.3.4 メソッドオブジェクト
  • 9.4 いろいろな注意点
  • 9.5 継承
    • 9.5.1 多重継承
  • 9.6 プライベート変数
  • 9.7 残りのはしばし
    • 9.7.1 例外はクラスであってもよい
  • 9.8 イテレータ (iterator)
  • 9.9 ジェネレータ (generator)

9. クラス

Python では、最小限の構文と意味付けを使ってクラス (class) のメカニズム を言語に追加しています。Python のクラスは、C++ と Modula-3 で 見られるクラスメカニズムを混合したものです。モジュールがそうであるように、 Python におけるクラスでは、クラス定義とユーザとの間に絶対的な障壁を おかず、ユーザが礼儀正しく、 ``定義に首を突っ込む'' ことはないと あてにしています。とはいえ、クラスにおける最も重要な機能はそのままに、 完全な力を持っています: クラスの継承 (inheritance) メカニズムでは、 複数の基底クラスを持つことができ、導出されたクラスでは基底クラスの 任意のメソッドをオーバライド (override, 上書き) することができます。 メソッドでは、基底クラスのメソッドを同じ名前で呼び出すことができます。 オブジェクトには任意のプライベートなデータを入れることができます。

C++ の用語では、全てのクラスメンバ (データメンバも含む) は public (公開されたデータ) であり、メンバ関数はすべて 仮想関数 (virtual) です。特別なコンストラクタ (constructor、 生成関数) やデストラクタ (destructor、破壊関数) はありません。 Module-3 にあるような、オブジェクトのメンバをメソッドから参照する ために短縮した記法を使うことはできません: メソッド関数の宣言では、 オブジェクト自体をあらわす明示的な第一の引数を伴います。オブジェクトは メソッド呼び出しの際に非明示的に渡されます。Smalltalk にあるように、 クラス自体もオブジェクトです。ただし広義のオブジェクトですが: Python では全てのデータ型はオブジェクトです。このことが、 import や名前変更といった操作の意味付けを提供しています。 しかし、C++ や Modula-3 と違って、 ユーザが組込みの型を基底クラスにして拡張することはできません。 また、C++ と同じで、Modula-3 とは違い、特別な構文を伴う ほとんどの組み込み演算子 (算術演算子 (arithmetic operator) や 添字表記) はクラスインスタンスで使うために再定義することができます。

9.1 用語について一言

クラスに関して広範に受け入れられている用語定義がないので、 Smalltalk と C++ の用語を場合に応じて使っていくことに します。 (オブジェクト指向における意味付けの方法は C++よりも Modula-3 のほうが Python に近いので Modula-3 の用語を使いたいのですが、 ほとんどの読者はそれを耳にしたことがないと思います。)

また、オブジェクト指向派の読者にとって用語上の落し穴があることを、 警告しておかねばなりません: Python では、``オブジェクト'' という言葉は 必ずしもクラスのインスタンスを意味しません。 C++ や Modula-3 と同じく、そして Smalltalk とは違い、Python では すべての型がクラスで定義されているとは限りません。 整数やリストのような基本的な組込み型はクラスではなく、 ファイルのような幾分珍しい型ですらクラスではありません。 とはいえ、Python の型は すべて、オブジェクトという言葉を使って 記述するのが最適な、ちょっとした共通の意味付けを共有しています。

オブジェクトには個体性があり、同一のオブジェクトに (複数のスコープの) 複数の名前を割り当てることができます。この機能は他の言語では 別名 (ailias) づけとして知られています。Python を一見しただけでは、 別名づけの重要性は分からないことが多く、変更不能な基本型 (数値、文字列、 タプル) を扱うときには無視して差し支えありません。 しかしながら、別名付けには、リストや辞書、またプログラムの外部 にある実体 (ファイル、ウィンドウ、など) を表現するためのほとんどの型 が入った Python コードで意味付けを行う上で (意図的な！) 効果があります。 別名付けはいくつかの点でポインタのように振舞うので、通常はプログラムに 利するように使われます。例えば、オブジェクトの受け渡しは、実装上は ポインタが渡されるだけなのでコストの低い操作になります; また、関数が あるオブジェクトを引数として渡されたとき、関数の呼び出し側から オブジェクトに対する変更を見ることができます -- これにより、 Pascal にあるような二つの引数渡し機構をもつ必要をなくしています。

9.2 Python のスコープと名前空間

クラスを紹介する前に、Python のスコープ規則についてあることを話して おかなければなりません。クラス定義はある巧みなトリックを名前空間に 施すので、何が起こっているのかを完全に理解するには、スコープと 名前空間がどのように動作するかを理解する必要があります。 ちなみに、この問題に関する知識は全ての Python プログラマにとって 有用です。

まず定義から始めましょう。

名前空間 (namespace) とは、 名前からオブジェクトへの対応付け (mapping) です。 ほとんどの名前空間は、現状では Python の辞書として実装されていますが、 そのことは通常は (パフォーマンス以外では) 目立つことはないし、 将来は変更されるかもしれません。 名前空間の例には、組込み名の集合 (abs() 等の関数や組込み 例外名)、モジュールないのグローバルな名前; 関数を呼び出したときの ローカルな名前、があります。その意味では、オブジェクトの属性から なる集合もまた、名前空間を形成します。名前空間について知っておくべき 重要なことは、異なった名前空間にある名前の間には全く関係がないと いうことです; 例えば、二つの別々のモジュールの両方で関数 ``maximize'' という関数を定義することができ、定義自体は混同され ることはありません -- モジュールのユーザは名前の前にモジュール名を つけなければなりません。

ところで、属性という言葉は、ドットに続く名前すべてに対して 使っています -- 例えば式 z.real で、real は オブジェクト z の属性です。厳密にいえば、モジュール内の名前に 対する参照は属性の参照です: 式 modname.funcname では、 modname はあるモジュールオブジェクトで、funcname は その属性です。この場合には、たまたまモジュールの属性とモジュール内の グローバルな名前の間には この場合はたまたま、モジュールの属性とモジュールで定義されている グローバル名の間には、直接的な対応付けがされます: これらの名前は 同じ名前空間を共有しているのです！ 9.1

属性は読取り専用にも、書き込み専用にもできます。 後者の場合、属性に代入することができます。 モジュール属性は書込み可能です: "modname.the_answer = 42" と書く ことができます。書込み可能な属性は、del 文で削除することも できます。例えば、"del modname.the_answer" は、modname で指定されたオブジェクトから属性 the_answer を除去します。

名前空間は様々な時点で作成され、その寿命も様々です。 組み込みの名前が入った名前空間は Python インタプリタが起動するときに 作成され、決して削除されることはありません。モジュールのグローバルな 名前空間は、モジュール定義が読み込まれたときに作成されます; 通常、 モジュールの名前空間は、インタプリタが終了するまで残ります。 インタプリタのトップレベルで実行された文は、スクリプトファイルから 読み出されたものでも対話的に読み出されたものでも、__main__ という名前のモジュールの一部分であるとみなされるので、独自の 名前空間を持つことになります。(組み込みの名前は実際にはモジュール内 に存在します; そのモジュールは __builtin__ と呼ばれています。)

関数のローカルな名前空間は、関数が呼び出されたときに作成され、 関数から戻ったときや、関数内で例外が送出され、かつ関数内で処理され なかった場合に削除されます。 (実際には、忘れられる、と言ったほうが起きていることをよく表して います。) もちろん、再帰呼出しのときには、各々の呼び出しで各自の ローカルな名前空間があります。

スコープ (scope) とは、ある名前空間が直接アクセスできる (directly accessible) ような、Python プログラムのテキスト上の領域 です。 ``直接アクセス可能'' とは、限定なし (unqualified) である名前を参照 した際に、その名前空間から名前を見つけようと試みることを意味します。

スコープは静的に決定されますが、動的に使用されます。 実行中はいつでも、直接名前空間にアクセス可能な、少なくとも三つの 入れ子になったスコープがあります: 最初に検索される最も内側のスコープには、ローカルな名前が入っています; あるいは、最も内側のスコープを囲んでいる関数群のスコープで、最も 近傍のスコープから検索を始めます; 中間のスコープが次に検索され、 このスコープには現在のモジュールのグローバルな名前が入っています; (最後に検索される) 最も外側のスコープは、組み込みの名前が入った 名前空間です。

名前がグローバルであると宣言されている場合、その名前に対する参照や 代入は全て、モジュールのグローバルな名前の入った中間のスコープに 対して直接行われます。そうでない場合、最も内側のスコープより外側に ある変数は全て読み出し専用となります。

通常、ローカルスコープは (プログラムテキスト上の) 現在の関数の ローカルな名前を参照します。関数の外側では、ローカルスコープは グローバルな名前空間と同じ名前空間: モジュールの名前空間を参照します。 クラスを定義すると、ローカルスコープの中にもう一つ名前空間が置かれ ます。

スコープはテキスト上で決定されていると理解することが重要です: モジュール内で定義される関数のグローバルなスコープは、 関数がどこから呼び出されても、どんな別名をつけて呼び出されても、 そのモジュールの名前空間になります。反対に、実際の名前の検索は 実行時に動的に行われます -- とはいえ、言語の定義は、``コンパイル'' 時の静的な名前解決の方向に進化しているので、 動的な名前解決に頼ってはいけません！ (事実、ローカルな変数は既に 静的に決定されています。)

Python 特有の癖として、代入を行うと名前がいつも最も内側のスコープに 入るというものがあります。代入はデータのコピーを行いません -- 単に名前をオブジェクトに結びつける (bind) だけです。オブジェクトの削除 でも同じです: "del x" は、x をローカルスコープが参照している 名前空間から削除します。実際、新たな名前を導入する操作は全てローカル スコープを用います: とりわけ、 import 文や関数定義は、モジュールや 関数の名前をローカルスコープに結び付けます。(global 文を使えば、 特定の変数がグローバルスコープにあることを示せます。)

9.3 クラス初見

クラスでは、新しい構文を少しと、三つの新たなオブジェクト型、そして 新たな意味付けをいくつか取り入れています。

9.3.1 クラス定義の構文

クラス定義の最も単純な形式は、以下のようになります:

class ClassName:
    <文-1>
    .
    .
    .
    <文-N>

関数定義 (def 文) と同様、クラス定義が効果をもつには まず実行しなければなりません。 (クラス定義を if 文の分岐先や関数内部に置くことも、 考え方としてはありえます。)

実際には、クラス定義の内側にある文は、通常は関数定義になりますが、 他の文を書くこともでき、それがそれが役に立つこともあります -- これについては後で述べます。クラス内の関数定義は通常、メソッドの 呼び出し規約で決められた独特の形式の引数リストを持ちます -- これについても後で述べます。

クラス定義に入ると、新たな名前空間が作成され、ローカルな 名前空間として使われます -- 従って、ローカルな変数に対する 全ての代入はこの新たな名前空間に名要ります。特に、関数定義を 行うと、新たな関数の名前はこの名前空間に結び付けられます。

クラス定義から普通に (定義の終端に到達して) 抜けると、 クラスオブジェクト (class object) が生成されます。 クラスオブジェクトは、基本的にはクラス定義で作成された名前空間の 内容をくるむラッパ (wrapper) です; クラスオブジェクトについては 次の節で詳しく学ぶことにします。(クラス定義に入る前に有効だった) 元のローカルスコープが復帰し、生成されたクラスオブジェクトは 復帰したローカルスコープにクラス定義のヘッダで指定した名前 (上の例では ClassName) で結び付けられます。

9.3.2 クラスオブジェクト

クラス・オブジェクトでは２種類の演算: 属性参照とインスタンス生成を サポートしています。

属性参照 (attribute reference) は、Python におけるすべての 属性参照で使われている標準的な構文、 obj.name を使います。 クラスオブジェクトが生成された際にクラスの名前空間にあった名前すべてが 有効な属性名です。従って、以下のようなクラス定義:

class MyClass:
    "A simple example class"
    i = 12345
    def f(self):
        return 'hello world'

では、MyClass.i と MyClass.f は妥当な属性参照であり、 それぞれ整数とメソッド・オブジェクトを返します。 クラス属性に代入を行うこともできます。従って、MyClass.i の値を 代入して変更できます。 __doc__ も有効な属性で、そのクラスに属している docstring、 この場合は "A simple example class" を返します。

クラスの インスタンス生成 (instantiation) には関数のような 表記法を使います。クラスオブジェクトのことを、単にクラスの新しい インスタンスを返すパラメタを持たない関数かのように扱います。 例えば (上記のクラスでいえば):

x = MyClass()

は、クラスの新しいインスタンス (instance) を生成し、 そのオブジェクトをローカル変数 x へ代入します。

インスタンス生成操作 (クラスオブジェクトの ``呼出し'') を行うと、 空のオブジェクト (empty object) を生成します。多くのクラスは、 オブジェクトを作成する際に、既知の初期状態になってほしいと望んで います。従って、クラスでは __init__() という名前の特別な メソッド定義することができます。例えば以下のようにします:

    def __init__(self):
        self.data = []

クラスが __init__() メソッドを定義している場合、 クラスのインスタンスを生成すると、新しく生成された クラスインスタンスに対して自動的に __init__() を呼び出します。 従って、この例では、新たな初期済みのインスタンスを以下のように して得ることができます:

x = MyClass()

もちろん、より大きな柔軟性を持たせるために、__init__() メソッドに複数の引数をもたせることができます。 その場合、クラスのインスタンス生成操作に渡された引数は __init__() に渡されます。例えば以下のように:

>>> class Complex:
...     def __init__(self, realpart, imagpart):
...         self.r = realpart
...         self.i = imagpart
...
>>> x = Complex(3.0, -4.5)
>>> x.r, x.i
(3.0, -4.5)

9.3.3 インスタンスオブジェクト

ところで、インスタンスオブジェクトを使うと何ができるのでしょうか？ インスタンスオブジェクトが理解できる唯一の操作は、属性の参照です。 有効な属性の名前には二種類あります。

一つ目の属性の種類は データ属性 (data attribute) と呼ぶことに しましょう。これは、これは Smalltalk の ``インスタンス変数'' (instance variable) や C++の ``データメンバ'' (data member) に相当します。 データ属性を宣言する必要はありません; ローカルな変数と同様に、 これらの属性は最初に代入された時点で湧き出てきます。例えば、 上で生成した MyClass のインスタンス x に対して、 以下のコード断片を実行すると、値 16 を印字し、x の 痕跡は残りません。

x.counter = 1
while x.counter < 10:
    x.counter = x.counter * 2
print x.counter
del x.counter

インスタンスオブジェクトが理解できる属性の参照の二つ目は メソッド (method) です。メソッドとは、オブジェクトに ``属している'' 関数のことです。(Python では、メソッドという用語はクラスインスタンス だけのものではありません: オブジェクト型にもメソッドを持つことができます。 例えば、リストオブジェクトには、 append, insert, remove, sort などといった メソッドがあります。とはいえ、以下では特に明記しない限り、クラスの インスタンスオブジェクトのメソッドだけを意味するものとして使うことに します。)

インスタンスオブジェクトで有効なメソッドは、そのクラスによって決まります。 定義により、クラスの全ての属性は、(ユーザが定義した) 関数オブジェクト インスタンスオブジェクトの妥当なメソッド名は、そのクラスによって 決まります。 定義により、(利用者定義の) 関数オブジェクトになっているクラス属性は全て、 そのインスタンスの対応するメソッドとなります。従って、例では、 MyClass.f は関数なので、 x.f はメソッドの参照として有効です。 しかし、MyClass.i は関数ではないので、 x.i はメソッドの参照 として有効ではありません。x.f は MyClass.f と同じものでは ありません -- 関数オブジェクトではなく、 メソッドオブジェクト (method object) です。

9.3.4 メソッドオブジェクト

普通、メソッドはその場ですぐに呼び出されます:

x.f()

私たちの例では、上のコードは文字列 'hello world' を返すでしょう。 しかしながら、必ずしもメソッドを正しい方法で呼び出さなければならない わけではありません: x.f はメソッドオブジェクトであり、 どこかに記憶しておいて後で呼び出すことができます。例えば以下のコード:

xf = x.f
while True:
    print xf()

は、 "hello world" を時が終わるまで印字し続けるでしょう。

メソッドが呼び出されるときには実際には何が起きているのでしょうか？ f の関数定義では引数を一つ指定していたにもかかわらず、 上記では x.f() が引数なしで呼び出されたことに気付いているかも しれませんね。引数はどうなったのでしょうか？ たしか、引数が必要な関数を 引数無しで呼び出すと、Python が例外を送出するはずです -- たとえその 引数が実際には使われなくても…。

実際、もう答は想像できているかもしれませんね: メソッドについて 特別なこととして、オブジェクトが関数の第 1 引数として渡される、 ということがあります。我々の例では、x.f() という呼び出しは、 MyClass.f(x) と厳密に等価なものです。 一般に、n 個の引数リストもったメソッドの呼出しは、 そのメソッドのオブジェクトを最初の引数の前に挿入した引数リストで メソッドに対応する関数を呼び出すことと等価です。

もしもまだメソッドの働きかたを理解できなければ、一度実装を見てみると 事情がよく分かるかもしれません。 データ属性ではないインスタンス属性が参照された時は、 そのクラスが検索されます。その名前が有効なクラス属性を表している 関数オブジェクトなら、インスタンスオブジェクトと見つかった 関数オブジェクト (へのポインタ) を抽象オブジェクト: すなわちメソッド オブジェクトにパック (pack) して作成します。 メソッドオブジェクトは、引数リストを伴って呼び出される際に再度 アンパック (unpack) され、新たな引数リストがインスタンスオブジェクト とオリジナルの引数リストから新たな引数リストが構成され、新たな引数 リストを使って関数オブジェクトを呼び出します。

9.4 いろいろな注意点

データ属性は同じ名前のメソッド属性を上書きしてしまいます; 大規模なプログラムでみつけにくいバグを引き起こすことがある この偶然的な名前の衝突を避けるには、衝突の可能性を最小限にするような 規約を使うのが賢明です。 可能な規約としては、メソッド名を大文字で始める、データ属性名の先頭に 短い一意的な文字列 (あるいはただの下線) をつける、またメソッドには動詞、 データ属性には名詞を用いる、などがあります。

データ属性は、メソッドから参照できると同時に、通常のオブジェクトの ユーザ (``クライアント'') からも参照できます。言い換えると、 クラスは純粋な抽象データ型として使うことができません。実際、 Python では、データ隠蔽を補強するための機構はなにもありません -- データの隠蔽はすべて規約に基づいています。(逆に、C 言語で書かれた Python の実装では実装の詳細を完全に隠蔽し、必要に応じてオブジェクト へのアクセスを制御できます; この機構は C 言語で書かれた Python 拡張 で使うことができます)

クライアントはデータ属性を注意深く扱うべきです -- クライアントは、 メソッドを使うことで維持しているデータ属性の不変式を踏みにじり、 台無しにするかもしれません。 クライアントは、名前の衝突が回避されている限り、メソッドの有効性に 影響を及ぼすことなくインスタンスに独自の属性を追加することができる、 ということに注意してください -- ここでも、名前付けの規約は 頭痛の種を無くしてくれます。

データ属性を (またはその他のメソッドも！) メソッドの中で参照するための 短縮された記法はありません。私は、この仕様が実際にメソッドの 可読性を高めていると考えています: あるメソッドを眺めているときに ローカルな変数とインスタンス変数を混同する可能性はまったくありません。

慣習として、メソッドの最初の引数を、しばしば self と呼びます。 この名前付けは単なる慣行でしかありません: self という名前は、 Python では何ら特殊な意味を持ちません。 (とはいえ、この慣行に従わないと、 コードは他の Python プログラマにとってやや読みにくいものとなります。 また、 クラスブラウザ (class browser) プログラムがこの慣行を あてにして書かれていないとも限りません。)

クラス属性である関数オブジェクトはいずれも、そのクラスのインスタンス のためのメソッドを定義しています。関数定義は、テキスト上では クラス定義の中に入っていなければならないわけではありません: 関数オブジェクトをクラスのローカルな変数の中に代入するのも OK です。 例えば以下のコードのようにします:

# クラスの外側で定義された関数
def f1(self, x, y):
    return min(x, x+y)

class C:
    f = f1
    def g(self):
        return 'hello world'
    h = g

これで、f、 g 、および h は、すべて C の属性であり関数オブジェクトを参照しています。 従って、これら全ては、C のインスタンスのメソッドとなります -- h は g と全く等価です。これを実践しても、大抵は 単にプログラムの読者に混乱をもたらすだけなので注意してください。

メソッドは、self 引数のメソッド属性を使って、 他のメソッドを呼び出すことができます:

class Bag:
    def __init__(self):
        self.data = []
    def add(self, x):
        self.data.append(x)
    def addtwice(self, x):
        self.add(x)
        self.add(x)

メソッドは、通常の関数と同じようにして、グローバルな名前を参照しても かまいません。あるメソッドに関連付けられたグローバルなスコープは、 クラス定義の入っているモジュールになります。 (クラス自体はグローバルな スコープとして用いられることはありません！) メソッドでグローバルな データを使う良い理由はほとんどありませんが、グローバルなスコープを 使う合法的な使い方は多々あります: 一つ挙げると、メソッド内では、 グローバルなスコープに import された関数やモジュールや、 その中で定義された関数やクラスを使うことができます。 通常、メソッドの入っているクラス自体はグローバルなスコープ内で 定義されています。次の章では、メソッドが自分のクラスを参照する理由 として正当なものを見てみましょう！

9.5 継承

言うまでもなく、継承の概念をサポートしない言語機能は ``クラス'' と呼ぶに 値しません。導出クラス (derived class) を定義する構文は以下のように なります:

class DerivedClassName(BaseClassName):
    <文-1>
    .
    .
    .
    <文-N>

基底クラス (base class) の名前 BaseClassName は、 派生クラス定義の入っているスコープで定義されていなければなりません。 基底クラス名のかわりに式を入れることもできます。 これは以下のように、

class DerivedClassName(modname.BaseClassName):

基底クラスが別モジュールで定義されているとき便利です。

導出クラス定義の実行は、基底クラスの場合と同じように進められます。 クラスオブジェクトが構築される時、基底クラスが記憶されます。 記憶された基底クラスは、属性参照を解決するために使われます: 要求された属性がクラスに見つからなかった場合、基底クラスから検索 されます。この規則は、基底クラスが他の何らかのクラスから導出された ものであった場合、再帰的に適用されます。

導出クラスのインスタンス化では、特別なことは何もありません: DerivedClassName() はクラスの新たなインスタンスを生成します。 メソッドの参照は以下のようにしてい解決されます: まず対応するクラス属性 が検索されます。検索は、必要に応じ、基底クラス連鎖を下って行われ、 検索の結果として何らかの関数オブジェクトがもたらされた場合、 メソッド参照は有効なものとなります。

導出クラスは基底クラスのメソッドを上書き (override) してもかまいません。 メソッドは同じオブジェクトの別のメソッドを呼び出す際に何ら特殊な権限を 持ちません。このため、ある基底クラスのメソッドが、同じ基底クラスで 定義されているもう一つのメソッド呼び出しを行っている場合、実際には 導出クラスで上書きされた何らかのメソッドが呼び出されることになる かもしれません。 (C++ プログラマへ: Python では、すべてのメソッドは 事実上 virtual です。)

導出クラスで上書きしているメソッドでは、実際は単に基底クラスの 同名のメソッドを置き換えるだけではなく、拡張を行いたいかもしれません。 基底クラスのメソッドを直接呼び出す簡単な方法があります: 単に "BaseClassName.methodname(self, arguments)" を呼び出すだけです。 この仕様は、場合によってはクライアントでも役に立ちます。 (この呼び出し方が動作するのは、基底クラスがグローバルなスコープ内で 定義されているか、直接 import されている場合だけなので注意してください。)

9.5.1 多重継承

Python では、限られた形式の多重継承 (multiple inheritance) も サポートしています。複数の基底クラスをもつクラス定義は以下のように なります:

class DerivedClassName(Base1, Base2, Base3):
    <文-1>
    .
    .
    .
    <文-N>

多重継承への意味付けを説明する上で必要な唯一の規則は、クラス属性の 参照を行うときに用いられる名前解決の規則 (resolution rule) です。 解決規則は深さ優先 (depth-first)、左から右へ (left-to-right) と なっています。従って、ある属性が DerivedClassName で 見つからなければ Base1 で検索され、次に Base1 の 基底クラスで (再帰的に) 検索されます。それでも見つからなければ はじめて Base2 で検索される、といった具合です。

(人によっては、幅優先 (breadth first) -- Base2 と Base3 を検索してから Base1 の基底クラスで検索する -- のほうが自然のように見えます。しかしながら、幅優先の検索では、 Base1 の特定の属性のうち、実際に定義されているのが Base1 なのか、その基底クラスなのかを知らなければ、 Base2 の属性との名前衝突がどんな結果をもたらすのか 分からないことになります。深さ優先規則では、 Base1 の直接の 属性と継承された属性とを区別しません。)

Python では偶然的な名前の衝突を慣習に頼って回避しているので、 見境なく多重継承の使用すると、メンテナンスの悪夢に陥ることは明らかです。 多重継承に関するよく知られた問題は、二つのクラスから導出された クラスがたまたま共通の基底クラスを持つ場合です。 この場合になにが起こるかを結論することは簡単です (インスタンスは 共通の基底クラスで使われている ``インスタンス変数'' の単一の コピーを持つことになります) が、この意味付けが何の役に立つのかは 明らかではありません。

9.6 プライベート変数

クラスプライベート (class-private) の識別子に関して限定的なサポート がなされています。__spam (先頭に二個以上の下線文字、末尾に 高々一個の下線文字) という形式の識別子、テキスト上では _classname__spam へと置換されるようになりました。 ここで classname は、現在のクラス名から先頭の下線文字を はぎとった名前になります。このような難号化 (mangle) は、識別子の 文法的な位置にかかわらず行われるので、クラスプライベートな インスタンス変数やクラス変数、メソッド、そしてグローバル変数を 定義するための利用できます。また、このクラスにとってプライベートな インスタンス変数を 他の クラスのインスタンスに格納するために 使うことさえできます。難号化した名前が 255 文字より長くなるときは、 切り詰めが起こるかもしれません。 クラスの外側や、クラス名が下線文字だけからできているときには、 難号化加工は起こりません。

名前の難号化は、クラスにおいて、 ``プライベートな'' インスタンス変数や メソッドを定義する際に、導出クラスで定義されるインスタンス変数を気に したり、クラスの外側のコードからインスタンス変数をいじりまわすことが ないように簡単に定義できるようにするためのものです。 難号化の規則は主に不慮の事故を防ぐためのものだということに注意して ください; 確信犯的な方法で、プライベートとされている変数にアクセス したり変更することは依然として可能なのです。デバッガのような特殊な 状況では、この仕様は便利ですらあります。そのため、この抜け穴は 塞がれていません。 (些細なバグ: 基底クラスと同じ名前のクラスを導出すると、基底クラスの プライベート変数を使えるようになります。)

exec や eval() や evalfile() へ渡されたコードでは、 呼出し元のクラス名を現在のクラスと見なさないことに注意してください; この仕様は global 文の効果と似ており、その効果もまた同様に、 バイトコンパイルされたコードに制限されています。 同じ制約が getattr() と setattr() と delattr() にも適用されます。また、__dict__ を直接参照するときにも適用されます。

9.7 残りのはしばし

Pascal の ``レコード (record)'' や、C 言語の ``構造体 (struct)'' のような、名前つきのデータ要素を一まとめにするデータ型があると 便利なことがたまにあります。空のクラス定義を使うとうまくできます:

class Employee:
    pass

john = Employee() # 空の従業員レコードを造る

# Fill the fields of the record
john.name = 'John Doe'
john.dept = 'computer lab'
john.salary = 1000

ある特定の抽象データ型を要求する Python コードの断片には、 そのデータ型のメソッドをエミュレーションするクラスを代わりに渡す ことができます。例えば、ファイルオブジェクトから何らかのデータを書式化 する関数がある場合、read() と readline() を持つクラス を定義して、ファイルではなく文字列バッファからデータを書式するように しておき、引数として渡すことができます。

インスタンスメソッドオブジェクトにもまた、属性があります: m.im_self はメソッドの属しているインスタンスオブジェクトで、 m.im_func はメソッドに対応する関数オブジェクトです。

9.7.1 例外はクラスであってもよい

ユーザ定義の例外をクラスとして識別することもできます。このメカニズムを 使って、拡張可能な階層化された例外を作成することができます。

新しく二つの (意味付け的な) 形式の raise 文ができました:

raise Class, instance

raise instance

第一の形式では、instance は Class またはその導出クラスの インスタンスでなければなりません。 第二の形式は以下の表記:

raise instance.__class__, instance

の短縮された記法です。

except 節には、文字列オブジェクトだけでなくクラスを並べることができます。 except 節のクラスは、同じクラスか基底クラスの例外のときに互換 (compatible) となります (逆方向では成り立ちません -- 導出クラスの例外がリストされている except 節は基底クラスの例外と互換ではありません)。 例えば、次のコードは、 B, C, D を順序通りに出力します:

class B:
    pass
class C(B):
    pass
class D(C):
    pass

for c in [B, C, D]:
    try:
        raise c()
    except D:
        print "D"
    except C:
        print "C"
    except B:
        print "B"

except 節が逆に並んでいた場合 ("except B" が最初にくる場合)、 B, B, B と出力されるはずだったことに注意してください -- 最初に 一致した except 節が駆動されるのです。

処理されないクラスの例外に対してエラーメッセージが出力されるとき、 まずクラス名が出力され、続いてコロン、スペース、最後に組み込み関数 str() を使って文字列に変換したインスタンスが出力されます。

9.8 イテレータ (iterator)

すでに気づいているでしょうが、for 文を使うとほとんどの コンテナオブジェクトにわたってループを行うことができます:

for element in [1, 2, 3]:
    print element
for element in (1, 2, 3):
    print element
for key in {'one':1, 'two':2}:
    print key
for char in "123":
    print char
for line in open("myfile.txt"):
    print line

こうしたアクセス方法は明確で、簡潔で、かつ便利なものです。イテレータの使用は Python 全体に普及していて、統一性をもたらしています。背後では、for 文は コンテナオブジェクトの iter() を呼び出しています。この関数は next() メソッドの定義されたイテレータオブジェクトを返します。 next() メソッドは一度コンテナ内の要素に一度に一つづつアクセスします。 コンテナ内にアクセスすべき要素がなくなると、next() は StopIteration 例外を送出し、for ループを終了させます。 実際にどのように動作するかを以下の例に示します:

>>> s = 'abc'
>>> it = iter(s)
>>> it
<iterator object at 0x00A1DB50>
>>> it.next()
'a'
>>> it.next()
'b'
>>> it.next()
'c'
>>> it.next()

Traceback (most recent call last):
  File "<pyshell#6>", line 1, in -toplevel-
    it.next()
StopIteration

イテレータプロトコルの背後にあるメカニズムを一度目にすれば、自作のクラスに
イテレータとしての振る舞いを追加するのは簡単です。__iter__() メソッド
を定義して、next() メソッドを持つオブジェクトを返すようにしてください。
クラス自体で next() を定義している場合、__iter__() では
単に self を返すようにできます:

>>> class Reverse:
    "Iterator for looping over a sequence backwards"
    def __init__(self, data):
        self.data = data
        self.index = len(data)
    def __iter__(self):
        return self
    def next(self):
        if self.index == 0:
            raise StopIteration
        self.index = self.index - 1
        return self.data[self.index]

>>> for char in Reverse('spam'):
    print char

m
a
p
s

9.9 ジェネレータ (generator)

ジェネレータは、イテレータを作成するための簡潔で強力なツールです。 ジェネレータは通常の関数のように書かれますが、何らかのデータを返すときには yield 文を使います。 next() が呼び出されるたびに、 ジェネレータは以前に中断した処理を再開します (ジェネレータは、全てのデータ値と 最後にどの文が実行されたかを記憶しています)。以下の例を見れば、ジェネレータ がとても簡単に作成できることがわかります:

>>> def reverse(data):
    for index in range(len(data)-1, -1, -1):
        yield data[index]

>>> for char in reverse('golf'):
    print char

f
l
o
g

ジェネレータを使ってできることは、前節で記述したクラスに基づいたイテレータを 使えばできます。ジェネレータを使うとコンパクトに記述できるのは、 __iter__() と next() メソッドが自動的に作成されるからです。

ジェネレータのもう一つの重要な機能は、呼び出しごとにローカル変数と実行状態が 自動的に保存されるということです。これにより、self.index や self.data といったクラス変数を使ったアプローチよりも簡単に 関数を書くことができるようになります。

メソッドを自動生成したりプログラムの実行状態を自動保存するほかに、 ジェネレータは終了時に自動的に StopIteration を送出します。 これらの機能を組み合わせると、通常の関数を書くのに比べ、全く苦労する ことなく簡単にイテレータを生成することができます。

... 同じ名前空間を共有しているのです！9.1
例外が一つあります。 モジュールオブジェクトには、秘密の読取り専用の属性 __dict__ があり、モジュールの名前空間を実装するために使われている辞書を返します; __dict__ という名前は属性ですが、グローバルな名前では ありません。この属性を利用すると名前空間の実装に対する抽象化を 侵すことになるので、プログラムを検死するデバッガのような用途に限る べきです。
Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 8. エラーと例外 Up: Python チュートリアル Next: 10. 標準ライブラリの簡単なツアー


10. 標準ライブラリの簡単なツアー

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 9. クラス Up: Python チュートリアル Next: 11. さあ何を？
  • 10.1 オペレーティングシステムへのインタフェース
  • 10.2 ファイルのワイルドカード表記
  • 10.3 コマンドライン引数
  • 10.4 エラー出力のリダイレクトとプログラムの終了
  • 10.5 文字列のパターンマッチング
  • 10.6 数学
  • 10.7 インターネットへのアクセス
  • 10.8 日付と時刻
  • 10.9 データ圧縮
  • 10.10 パフォーマンスの計測
  • 10.11 品質管理
  • 10.12 一揃いあつらえ済み

10. 標準ライブラリの簡単なツアー

10.1 オペレーティングシステムへのインタフェース

os モジュールは、 オペレーティングシステムと対話するための何ダースもの関数を 提供しています:

>>> import os
>>> os.system('time 0:02')
0
>>> os.getcwd()      # 現在の作業ディレクトリを返す
'C:\\Python24'
>>> os.chdir('/server/accesslogs')

"from os import *" ではなく、 "import os" 形式を使う ようにしてください。そうすることで、 動作が大きく異なる組み込み関数 open() が os.open() で隠蔽されるのを避けられます。

組み込み関数 dir() および help() は、 os のような大規模なモジュールで作業をするときに、対話的な 操作上の助けになります:

>>> import os
>>> dir(os)
<returns a list of all module functions>
>>> help(os)
<returns an extensive manual page created from the module's docstrings>

ファイルやディレクトリの日常的な管理作業のために、 より簡単に使える高レベルインタフェースが shutil モジュールで提供されています:

>>> import shutil
>>> shutil.copyfile('data.db', 'archive.db')
>>> shutil.move('/build/executables', 'installdir')

10.2 ファイルのワイルドカード表記

glob モジュールでは、 ディレクトリのワイルドカード検索からファイルのリストを生成する ための関数を提供しています:

>>> import glob
>>> glob.glob('*.py')
['primes.py', 'random.py', 'quote.py']

10.3 コマンドライン引数

広く使われているユーティリティスクリプトでは、しばしばコマンドライン 引数の処理を呼び出します。これらの引数は sys モジュールの argv 属性にリストとして記憶されます。例えば、以下の出力は、 "python demo.py one two three" をコマンドライン上で起動した際に 得られるものです:

>>> import sys
>>> print sys.argv
['demo.py', 'one', 'two', 'three']

getopt モジュールは、sys.argv を Unix の getopt() 関数の 慣習に従って処理します。より強力で柔軟性のあるコマンドライン処理機能は、 optparse モジュールで 提供されています。

10.4 エラー出力のリダイレクトとプログラムの終了

sys モジュールには、 stdin、 stdout、および stderr を表す属性値も 存在します。後者の stderr は、警告やエラーメッセージを出力して、 stdout がリダイレクトされた場合でもそれらが読めるようにする 上で便利です:

>>> sys.stderr.write('Warning, log file not found starting a new one')
Warning, log file not found starting a new one

"sys.exit()" は、スクリプトを終了させるもっとも直接的な方法です。

10.5 文字列のパターンマッチング

re モジュールでは、より高度な文字列処理のための正規表現 (regular expression) を提供しています。正規表現は複雑な一致検索や操作に対して簡潔で最適化 された解決策を与えます:

>>> import re
>>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest')
['foot', 'fell', 'fastest']
>>> re.sub(r'(\b[a-z]+) \1', r'\1', 'cat in the the hat')
'cat in the hat'

最小限の機能だけが必要なら、読みやすくデバッグしやすい文字列メソッドの 方がお勧めです:

>>> 'tea for too'.replace('too', 'two')
'tea for two'

10.6 数学

math モジュールでは、 根底にある浮動小数点演算のための C 言語ライブラリ関数にアクセス する手段を提供しています:

>>> import math
>>> math.cos(math.pi / 4.0)
0.70710678118654757
>>> math.log(1024, 2)
10.0

random モジュールでは、乱数に基づいた要素選択のためのツールを提供しています:

>>> import random
>>> random.choice(['apple', 'pear', 'banana'])
'apple'
>>> random.sample(xrange(100), 10)   # 要素を戻さないサンプリング
[30, 83, 16, 4, 8, 81, 41, 50, 18, 33]
>>> random.random()    # ランダムな浮動小数点数
0.17970987693706186
>>> random.randrange(6)    # range(6) からランダムに選ばれた整数
4

10.7 インターネットへのアクセス

インターネットにアクセスしたり、インターネットプロトコルを処理したり するための数多くのモジュールがあります。その中でも最も単純な二つ のモジュールは、URL を指定してデータを取得するための urllib2 と、メイルを送信するための smtplib です:

>>> import urllib2
>>> for line in urllib2.urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl'):
... if 'EST' in line:      # look for Eastern Standard Time
...     print line

<BR>Nov. 25, 09:43:32 PM EST

>>> import smtplib
>>> server = smtplib.SMTP('localhost')
>>> server.sendmail('soothsayer@tmp.org', 'jceasar@tmp.org',
"""To: jceasar@tmp.org
From: soothsayer@tmp.org

Beware the Ides of March.
""")
>>> server.quit()

10.8 日付と時刻

datetime モジュールは、 日付や時刻を操作するためのクラスを、単純な方法と複雑な方法の両方で 供給しています。日付や時刻に対する算術がサポートされている一方、 実装では出力の書式化や操作のための効率的なデータメンバ抽出に 重点を置いています。 このモジュールでは、タイムゾーンに対応したオブジェクトもサポート しています。

# dates are easily constructed and formatted
>>> from datetime import date
>>> now = date.today()
>>> now
datetime.date(2003, 12, 2)
>>> now.strftime("%m-%d-%y or %d%b %Y is a %A on the %d day of %B")
'12-02-03 or 02Dec 2003 is a Tuesday on the 02 day of December'

# dates support calendar arithmetic
>>> birthday = date(1964, 7, 31)
>>> age = now - birthday
>>> age.days
14368

10.9 データ圧縮

データの書庫化や圧縮で広く使われている形式については、 zlib、 gzip、 bz2、 zipfile、および tarfile と いったモジュールで直接サポートしています。

>>> import zlib
>>> s = 'witch which has which witches wrist watch'
>>> len(s)
41
>>> t = zlib.compress(s)
>>> len(t)
37
>>> zlib.decompress(t)
'witch which has which witches wrist watch'
>>> zlib.crc32(t)
-1438085031

10.10 パフォーマンスの計測

Python ユーザの中には、同じ問題を異なったアプローチで解いた 際の相対的なパフォーマンスについて知りたいという深遠な興味を 抱いている人がいます。Python では、そういった疑問に即座に答える 計測ツールを提供しています。

例えば、引数の入れ替え操作に対して、伝統的なアプローチの代わりに タプルのパックやアンパックを使ってみたい気持ちになるかもしれません。 timeit モジュールを 使うと、伝統的なアプローチのほうが高速であることがすぐに実証 されます:

>>> from timeit import Timer
>>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit()
0.60864915603680925
>>> Timer('a,b = b,a', 'a=1; b=2').timeit()
0.8625194857439773

timeit では高い粒度レベルを提供しているのに対し、 profile や pstats モジュールではより大きなコードブロックにおいて律速となる部分を 判定するためのツールを提供しています。

10.11 品質管理

高い品質のソフトウェアを開発するための一つのアプローチは、全ての関数 に対して開発と同時にテストを書き、開発の過程で頻繁にテストを走らせる というものです。

doctest モジュールでは、 モジュールを検索して、プログラムの docstring に埋め込まれたテストの 評価を行うためのツールを提供しています。テストの作り方は単純で、 典型的な呼び出し例とその結果を docstring にカット& ペーストすると いうものです。この作業は、ユーザに使用例を与えるという意味で ドキュメントの情報を増やすと同時に、ドキュメントに書かれている内容が 正しいかどうか doctest モジュールが確認できるようにしています:

def average(values):
    """Computes the arithmetic mean of a list of numbers.

    >>> print average([20, 30, 70])
    40.0
    """
    return sum(values, 0.0) / len(values)

import doctest
doctest.testmod()   # automatically validate the embedded tests

unittest モジュールは doctest モジュールほど気楽に使えるものではありませんが、 より網羅的なテストセットを別のファイルで管理することができます:

import unittest

class TestStatisticalFunctions(unittest.TestCase):

    def test_average(self):
        self.assertEqual(average([20, 30, 70]), 40.0)
        self.assertEqual(round(average([1, 5, 7]), 1), 4.3)
        self.assertRaises(ZeroDivisionError, average, [])
        self.assertRaises(TypeError, average, 20, 30, 70)

unittest.main() # Calling from the command line invokes all tests

10.12 一揃いあつらえ済み

Python には ``一揃いあつらえ済み (batteries included)'' 哲学が あります。この哲学は、洗練され、安定した機能を持つ Python の膨大な パッケージ群に如実に表れています。例えば:

* The xmlrpclib および SimpleXMLRPCServer モジュールは、遠隔手続き呼び出し (remote procedure call) を全く たいしたことのない作業に変えてしまいます。名前とは違い、XML を扱う ための直接的な知識は必要ありません。

* The email パッケージは、MIME やその他の RFC 2822 に基づくメッセージ文書を含む 電子メイルメッセージを管理するためのライブラリです。 実際にメッセージを送信したり受信したりする smtplib や poplib と違って、email パッケージには (添付文書を 含む) 複雑なメッセージ構造の構築やデコードを行ったり、 インターネット標準のエンコードやヘッダプロトコルの実装を行ったり するための完全なツールセットを備えています。

* xml.dom および xml.sax パッケージでは、 一般的なデータ交換形式である XML を解析するための頑健なサポートを 提供しています。同様に、csv モジュールでは、広く用いられている データベース形式のデータを直接読み書きする機能をサポートしています。 これらのモジュールやパッケージは併用することで、Python アプリケーション と他のツール群との間でのデータ交換を劇的に簡単化します。

* 国際化に関する機能は、 gettext、 locale、および codecs パッケージ といったモジュール群でサポートされています。

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 9. クラス Up: Python チュートリアル Next: 11. さあ何を？


11. さあ何を？

このチュートリアルを読んだことで、おそらく Python を使ってみようと いう関心はますます強くなったことでしょう -- 現実世界の問題を解決 するために、Python を適用してみたくなったはずです。さて、それでは 何をしたらよいのでしょうか？

Python ライブラリリファレンス を読むか、 少なくともざっと読み流すとよいでしょう。ライブラリリファレンスでは、 データ型、関数、そして Python プログラムを書く上で大いに時間の節約 となるモジュールについて、(簡潔ではあるけれども) 完全なリファレンス マニュアルを提供しています。 標準的な Python の配布物には、C 言語と Python の両方のコードが たくさん 収められています; Unix メールボックスを読み出したり、 HTTP を介してドキュメントを取得したり、乱数を生成したり、コマンドライン オプションを解析したり、 CGI プログラムを書いたり、データを圧縮したり、 その他にももっとたくさんのモジュールがあります; ライブラリリファレンス にざっと目を通すだけでも、Python で何ができるかアイデアを得ることが できるでしょう。

主要な Python Web サイトは http://www.python.org/ です; このサイトには、コード、ドキュメント、そして Web のあちこちの Python に関連したページへのポインタがあります。 この Web サイトは世界のあちこちのさまざまな場所、例えばヨーロッパ、 日本、オーストラリアなどでミラーされています。地理的な位置によっては、 メインのサイトよりミラーのほうが速いかもしれません。 非公式なサイトには http://starship.python.net/ があります。 ここには、一群の Python 関連の個人的ホームページがあります; 多くの人がここにダウンロード可能なソフトウェアを置いています。

Python Package Index (PyPI). にあるサードパーティ製モジュール リポジトリに行けば、さらに多くのユーザによって作成された Python モジュール を見つけることができます。

Python に関する質問をしたり、問題を報告するために、 ニュースグループ comp.lang.python に投稿したり、 python-list@python.org のメーリングリストに送信することが できます。ニュースグループとメーリングリストは相互接続されて いるので、どちらかにポストされたメッセージは自動的にもう一方にも 転送されます。 一日に約 120 通程度、 質問を (そしてその解凍)、新機能の提案、新たなモジュールのアナウンス が投稿されています。 投稿する前に、必ず よく出される質問 (Frequently Asked Questions, FAQ とも言います) のリストを確認するか、Python ソースコード配布物の Misc/ ディレクトリを探すようにしてください。 メーリングリストのアーカイブは http://www.python.org/pipermail/ で 入手することができます。 FAQ では、何度も繰り返し現れる質問の多くに答えています。読者の抱えている 問題に対する解答がすでに入っているかもしれません。

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 10. 標準ライブラリの簡単なツアー Up: Python チュートリアル Next: A. 対話入力編集とヒストリ置換


A. 対話入力編集とヒストリ置換

あるバージョンの Python インタプリタでは、Korn シェルや GNU Bash シェルに見られる機能に似た、現在の入力行に対する編集機能や ヒストリ置換機能をサポートしています。 この機能は GNU Readline ライブラリを使って実装されています。 このライブラリは Emacs スタイルと vi スタイルの編集をサポート しています。ライブラリには独自のドキュメントがあり、ここでそれを 繰り返すつもりはありません; とはいえ、基本について簡単に解説する ことにします。ここで述べる対話的な編集とヒストリについては、 Unix 版と CygWin 版のインタプリタでオプションとして利用 することができます。

この章では、Mark Hammond の PythonWin パッケージや、 Python とともに配布される Tk ベースの環境である IDLE にある 編集機能については解説しません。 NT 上の DOS ボックスやその他の DOS および Windows 類で働く コマンド行ヒストリ呼出しもまた別のものです。

A.1 行編集

入力行の編集がサポートされている場合、インタプリタが一次または二次 プロンプトを出力している際にはいつでも有効になっています。現在の行は、 慣例的な Emacs 制御文字を使って編集することができます。 そのうち最も重要なものとして、以下のようなキーがあります: C-A (Control-A) はカーソルを行の先頭へ移動させます。 C-E は末尾へ移動させます。 C-B は逆方向へ一つ移動させます。 C-F は順方向へ移動させます。 Backspace は逆方向に向かって文字を消します。 C-D は順方向に向かって消します。 C-K は順方向に向かって行の残りを kill し (消し) ます 、 C-Y は最後に kill された文字列を再び yank し (取り出し) ます。 C-underscore 最後の変更を元に戻します; これは、繰り返して どんどんさかのぼることができます。

A.2 ヒストリ置換

ヒストリ置換は次のように働きます。入力された行のうち、空行でない 実行された行はすべてヒストリバッファに保存されます。そして、プロンプト が呈示されるときには、ヒストリバッファの最も下の新たな行に移動 します。C-P はヒストリバッファの中を一行だけ上に移動し (戻し) ます。C-N は 1 行だけ下に移動します。ヒストリバッファの どの行も編集することができます。行が編集されると、それを示すために プロンプトの前にアスタリスクが表示されます A.1。 Return キーを押すと現在行がインタプリタへ渡されます。 C-R はインクリメンタルな逆方向サーチ (reverse search) を開始し、 C-S は順方向サーチ (forward search) を開始します。

A.3 キー割り当て

Readline ライブラリのキー割り当て (key binding) やその他のパラメタ は、~/.inputrc という初期化ファイルA.2にコマンドを置くことでカスタマイズできます。 キー割り当ての形式は

key-name: function-name

または

"string": function-name

で、オプションの設定方法は

set option-name value

です。例えば、以下のように設定します:

# vi スタイルの編集を選択する:
set editing-mode vi

# 一行だけを使って編集する:
set horizontal-scroll-mode On

# いくつかのキーを再束縛する:
Meta-h: backward-kill-word
"\C-u": universal-argument
"\C-x\C-r": re-read-init-file

Python では、Tab に対するデフォルトの割り当ては TAB の挿入です。 Readline のデフォルトであるファイル名補完関数ではないので注意して ください。 もし、どうしても Readline のデフォルトを割り当てたいのなら、 ~/.inputrc に

Tab: complete

を入れれば設定を上書きすることができます。 (もちろん、Tab を使って補完を行うのに慣れている場合、この設定を行うと インデントされた継続行を入力しにくくなります。)

変数名とモジュール名の自動的な補完がオプションとして利用できます。 補完をインタプリタの対話モードで有効にするには、 以下の設定をスタートアップファイルに追加します: A.3

import rlcompleter, readline
readline.parse_and_bind('tab: complete')

この設定は、Tab キーを補完関数に束縛します。従って、 Tab キーを二回たたくと補完候補が示されます; 補完機能は Python の文の名前、現在のローカル変数、および利用可能なモジュール名を 検索します。string.a のようなドットで区切られた式については、 最後の "." までの式を評価し、結果として得られたオブジェクトの 属性から補完候補を示します。 __getattr__() メソッドを持ったオブジェクトが式に含まれている 場合、__getattr__() がアプリケーション定義のコードを実行する かもしれないので注意してください。

より良くできたスタートアップファイルは以下例のようになります。 この例では、作成した名前が不要になると削除されるので気をつけてください; これは、スタートアップファイルが対話コマンドと同じ名前空間で実行され ているので、不要な名前を除去して対話環境に副作用を生まないように するためです。import されたモジュールのうち、os のような インタプリタのほとんどのセッションで必要なものについては、残しておくと 便利に思うかもしれません。

# Add auto-completion and a stored history file of commands to your Python
# interactive interpreter. Requires Python 2.0+, readline. Autocomplete is
# bound to the Esc key by default (you can change it - see readline docs).
#
# Store the file in ~/.pystartup, and set an environment variable to point
# to it, e.g. "export PYTHONSTARTUP=/max/home/itamar/.pystartup" in bash.
#
# Note that PYTHONSTARTUP does *not* expand "~", so you have to put in the
# full path to your home directory.

import atexit
import os
import readline
import rlcompleter

historyPath = os.path.expanduser("~/.pyhistory")

def save_history(historyPath=historyPath):
    import readline
    readline.write_history_file(historyPath)

if os.path.exists(historyPath):
    readline.read_history_file(historyPath)

atexit.register(save_history)
del os, atexit, readline, rlcompleter, save_history, historyPath

A.4 解説

この機能は、初期の版のインタプリタに比べれば大きな進歩です; とはいえ、まだいくつかの要望が残されています: 例えば、 行を継続するときに正しいインデントが呈示されたら快適でしょう (パーサは 次の行でインデントトークンが必要かどうかを知っています)。 補完機構がインタプリタのシンボルテーブルを使ってもよいかもしれません。 かっこやクォートなどの対応をチェックする (あるいは指示する) コマンドも 有用でしょう。

... プロンプトの前にアスタリスクが表示されますA.1
訳注: これはデフォルト設定の Readline では現れません。 set mark-modified-lines on という行を ~/.inputrc または 環境変数 INPUTRC が指定するファイルに置くことによって 現れるようになります。
... という初期化ファイルA.2
訳注: このファイル名は 環境変数 INPUTRC がもしあればその指定が優先されます。
... 以下の設定をスタートアップファイルに追加します:A.3
Python は、対話インタプリタを開始する時に PYTHONSTARTUP 環境変数が指定するファイルの内容を実行します。
Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: 11. さあ何を？ Up: Python チュートリアル Next: B. 浮動小数点演算、その問題と制限


B. 浮動小数点演算、その問題と制限

浮動小数点数は、計算機ハードウェアの中では、 基数を 2 とする (2進法の) 分数として表現されています。 例えば、小数

0.125

は、 1/10 + 2/100 + 5/1000 という値を持ちますが、これと同様に、 2 進法の分数

0.001

は 0/2 + 0/4 + 1/8 という値になります。これら二つの分数は同じ値を 持っていますが、ただ一つ、最初の分数は基数 10 で記述されており、 二番目の分数は基数 2 で記述されていることが違います。

残念なことに、ほとんどの小数は 2 進法の分数として正確に表わすことが できません。その結果、一般に、入力した 10 進の浮動小数点数は、 2 進法の浮動小数点数で近似された後、実際にマシンに記憶されます。

最初は基数 10 を使うと問題を簡単に理解できます。分数 1/3 を考えて みましょう。分数 1/3 は、基数 10 の分数として、以下のように近似する ことができます:

0.3

さらに正確な近似は、

0.33

です。さらに正確に近似すると、

0.333

となり、以後同様です。何個桁数を増やして書こうが、結果は決して厳密な 1/3 にはなりません。しかし、少しづつ正確な近似にはなっていくでしょう。

同様に、基数を 2 とした表現で何桁使おうとも、10 進数の 0.1 は 基数を 2 とした分数で正確に表現することはできません。 基数 2 では、1/10 は循環小数 (repeating fraction)

0.0001100110011001100110011001100110011001100110011...

となります。どこか有限の桁で止めると、近似値を得ることになります。 これこそが、以下のような事態:

>>> 0.1
0.10000000000000001

に出くわす理由です。

今日では、ほとんどのマシンでは、0.1 を Python のプロンプトから入力すると 上のような結果を目にします。そうならないかもしれませんが、これは ハードウェアが浮動小数点数を記憶するのに用いているビット数がマシンに よって異なり、Python は単にマシンに 2 進で記憶されている、真の 10 進の 値を近似した値を、されに 10 進で近似して出力するだけだからです。 ほとんどのマシンでは、Python が 0.1 を記憶するために 2 進近似した 真の値を 10 進で表すと、以下のような出力

>>> 0.1
0.1000000000000000055511151231257827021181583404541015625

になるでしょう！ Python プロンプトは、文字列表現を得るために 何に対しても repr() を (非明示的に) 使います。 浮動小数点数の場合、 repr(float) は真の 10 進値を 有効数字 17 桁で丸め、以下のような表示

0.10000000000000001

を行います。

repr(float) が有効数字 17桁 の値を生成するのは、この値 が (ほとんどのマシン上で) 、全ての有限の浮動小数点数 x について eval(repr(x)) == x が成り立つのに十分で、 かつ有効数字 16 桁に丸めると成り立たないからです。

これは 2 進法の浮動小数点の性質です: Python のバグでも、ソースコードのバ グでもなく、浮動小数点演算を扱えるハードウェア上の、すべての言語で同じ 類の現象が発生します (ただし、言語によっては、デフォルトのモードや 全ての出力モードでその差を 表示しない かもしれません)。

Python の組み込みの str() 関数は有効数字 12 桁しか生成 しません。このため、この関数を代わりに使用したいと思うかもしれません。 この関数は eval(str(x)) としたときに x を再現 しないことが多いですが、出力を目で見るには好ましいかもしれません:

>>> print str(0.1)
0.1

現実という考えからは、上の表示は錯覚であると気づくのは重要なことです: マシン内の値は厳密に 1/10 ではなく、単に真のマシン内の 表示される値 を丸めているだけなのです。

まだ驚くべきことがあります。例えば、以下

>>> 0.1
0.10000000000000001

を見て、round() 関数を使って桁を切り捨て、期待する 1 桁に したい誘惑にかられたとします。しかし、結果は依然同じ値です:

>>> round(0.1, 1)
0.10000000000000001

問題は、"0.1" を表すために記憶されている 2 進表現の浮動小数点数の値は、 すでに 1/10 に対する最良の近似になっており、値を再度丸めようとしても これ以上ましにはならないということです: すでに値は、round() で得られる値になっているというわけです。

もう一つの重要なことは、0.1 が正確に 1/10 ではないため、0.1 どうしを 10 回加算すると厳密に 1.0 にはならないこともある、ということです:

>>> sum = 0.0
>>> for i in range(10):
...     sum += 0.1
...
>>> sum
0.99999999999999989

2 進の浮動小数点数に対する算術演算は、このような意外性をたくさん持って います。"0.1" に関する問題は、以下の "表現エラー" の章で詳細に説明します。 2 進法の浮動小数点演算にともなうその他のよく知られた意外な事象に関しては The Perils of Floating Point を参照してください。

究極的にいうと、``容易な答えはありません''。ですが、浮動小数点数の ことを過度に警戒しないでください！ Python の float 型操作における エラーは浮動小数点処理ハードウェアから受けついたものであり、 ほとんどのマシン上では一つの演算あたり高々 2**53 分の 1 です。 この誤差はほとんどの作業で相当以上のものですが、浮動小数点演算は 10 進の演算えはなく、浮動小数点の演算を新たに行うと、新たな 丸め誤差の影響を受けることを心にとどめておいてください。

異常なケースが存在する一方で、普段の浮動小数点演算の利用では、 単に最終的な結果の値を必要な 10 進の桁数に丸めて表示するのなら、 最終的には期待通りの結果を得ることになるでしょう。 こうした操作は普通 str() で事足りますし、よりきめ細かな 制御をしたければ、 Python の % 書式化演算子についての議論を 参照してください: %g 、%f 、および %e といった 書式化コードでは、浮動小数点数を表示用に丸めるための柔軟性のある、 簡単な手段を提供しています。

B.1 表現エラー

この章では、``0.1'' の例について詳細に説明し、このようなケースに 対してどのようにすれば正確な分析を自分で行えるかを示します。 ここでは、 2 進法表現の浮動小数点数についての基礎的な知識があるものとして 話を進めます。

表現エラー は、いくつかの (実際にはほとんどの) 10 進の小数が 2 進法 (基数 2 ) の分数として表現できないことに関係しています。 これは Python (あるいは Perl、 C、 C++、Japa、Fortran 、および その他多く) が期待通りの正確な 10 進数を表示できない主要な理由です:

>>> 0.1
0.10000000000000001

なぜこうなるのでしょうか？ 1/10 は 2 進法の分数で厳密に表現することが できません。今日 (2000年11月) のマシンは、ほとんどすべて IEEE-754 浮動小数点演算を使用しており、ほとんどすべてのプラットフォームでは Python の浮動小数点を IEEE-754 における "倍精度 (double precision)" に対応付けます。754 の double には 53 ビットの精度を持つ数が入るので、 計算機に入力を行おうとすると、可能な限り 0.1 を最も近い値の分数に変換 し、J/2**N の形式にしようと努力します。 J はちょうど 53 ビットの精度の整数です。

 1 / 10 ~= J / (2**N)

を書き直すと、

J ~= 2**N / 10

となります。

J は厳密に 53 ビットの精度を持っている (>= 2**52 だが < 2**53 ) ことを思い出すと、 N として最適な値は 56 になります:

>>> 2L**52
4503599627370496L
>>> 2L**53
9007199254740992L
>>> 2L**56/10
7205759403792793L

すなわち、56 は J をちょうど 53 ビットの精度のままに保つ N の唯一の値です。J の取りえる値はその商を丸めた ものです:

>>> q, r = divmod(2L**56, 10)
>>> r
6L

残りは 10 の半分以上なので、最良の近似は丸め値を一つ増やした (round up) ものになります:

>>> q+1
7205759403792794L

従って、754 倍精度における 1/10 の取りえる最良の近似は 2**56 以上 の値、もしくは

7205759403792794 / 72057594037927936

となります。丸め値を 1 増やしたので、この値は実際には 1/10 より少し小 さいことに注意してください; 丸め値を 1 増やさない場合、商は 1/10 よりもわずかに小さくなります。しかし、どちらにしろ 厳密に 1/10 ではありません！

つまり、計算機は 1/10 を ``理解する'' ことは決してありません: 計算機が理解できるのは、上記のような厳密な分数であり、 754 の倍精度浮動小数点数で得られるもっともよい近似は:

>>> .1 * 2L**56
7205759403792794.0

となります。

この分数に 10**30 を掛ければ、 有効数字 30 桁の十進数の (切り詰められた) 値を見ることができます:

>>> 7205759403792794L * 10L**30 / 2L**56
100000000000000005551115123125L

これは、計算機に記憶されている正確な数値が、10 進数値 0.100000000000000005551115123125 とほぼ等しいことを意味します。 有効数字 17 桁に丸めることで、Python が表示する0.10000000000000001 に なります (そう、得られるかぎり最良の入力あるいは出力値の変換を C ライブラリで行うような、 754 に適合するプラットフォームにおいてです -- 読者の計算機ではそうではないかもしれません！)

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: A. 対話入力編集とヒストリ置換 Up: Python チュートリアル Next: C. 歴史とライセンス


C. 歴史とライセンス

C.1 History of the software

Python was created in the early 1990s by Guido van Rossum at Stichting Mathematisch Centrum (CWI, see http://www.cwi.nl/) in the Netherlands as a successor of a language called ABC. Guido remains Python's principal author, although it includes many contributions from others.

In 1995, Guido continued his work on Python at the Corporation for National Research Initiatives (CNRI, see http://www.cnri.reston.va.us/) in Reston, Virginia where he released several versions of the software.

In May 2000, Guido and the Python core development team moved to BeOpen.com to form the BeOpen PythonLabs team. In October of the same year, the PythonLabs team moved to Digital Creations (now Zope Corporation; see http://www.zope.com/). In 2001, the Python Software Foundation (PSF, see http://www.python.org/psf/) was formed, a non-profit organization created specifically to own Python-related Intellectual Property. Zope Corporation is a sponsoring member of the PSF.

All Python releases are Open Source (see http://www.opensource.org/ for the Open Source Definition). Historically, most, but not all, Python releases have also been GPL-compatible; the table below summarizes the various releases.

Release | Derived from | Year | Owner | GPL compatible?
0.9.0 thru 1.2 | n/a | 1991-1995 | CWI | yes
1.3 thru 1.5.2 | 1.2 | 1995-1999 | CNRI | yes
1.6 | 1.5.2 | 2000 | CNRI | no
2.0 | 1.6 | 2000 | BeOpen.com | no
1.6.1 | 1.6 | 2001 | CNRI | no
2.1 | 2.0+1.6.1 | 2001 | PSF | no
2.0.1 | 2.0+1.6.1 | 2001 | PSF | yes
2.1.1 | 2.1+2.0.1 | 2001 | PSF | yes
2.2 | 2.1.1 | 2001 | PSF | yes
2.1.2 | 2.1.1 | 2002 | PSF | yes
2.1.3 | 2.1.2 | 2002 | PSF | yes
2.2.1 | 2.2 | 2002 | PSF | yes
2.2.2 | 2.2.1 | 2002 | PSF | yes
2.2.3 | 2.2.2 | 2002-2003 | PSF | yes
2.3 | 2.2.2 | 2002-2003 | PSF | yes
2.3.1 | 2.3 | 2002-2003 | PSF | yes
2.3.2 | 2.3.1 | 2003 | PSF | yes

注意: GPL-compatible doesn't mean that we're distributing Python under the GPL. All Python licenses, unlike the GPL, let you distribute a modified version without making your changes open source. The GPL-compatible licenses make it possible to combine Python with other software that is released under the GPL; the others don't.

Thanks to the many outside volunteers who have worked under Guido's direction to make these releases possible.

C.2 Terms and conditions for accessing or otherwise using Python

PSF LICENSE AGREEMENT FOR PYTHON 2.3.3

  1. This LICENSE AGREEMENT is between the Python Software Foundation (``PSF''), and the Individual or Organization (``Licensee'') accessing and otherwise using Python 2.3.3 software in source or binary form and its associated documentation.

  2. Subject to the terms and conditions of this License Agreement, PSF hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python 2.3.3 alone or in any derivative version, provided, however, that PSF's License Agreement and PSF's notice of copyright, i.e., ``Copyright © 2001-2003 Python Software Foundation; All Rights Reserved'' are retained in Python 2.3.3 alone or in any derivative version prepared by Licensee.

  3. In the event Licensee prepares a derivative work that is based on or incorporates Python 2.3.3 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python 2.3.3.

  4. PSF is making Python 2.3.3 available to Licensee on an ``AS IS'' basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.3.3 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 2.3.3 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 2.3.3, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between PSF and Licensee. This License Agreement does not grant permission to use PSF trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party.

  8. By copying, installing or otherwise using Python 2.3.3, Licensee agrees to be bound by the terms and conditions of this License Agreement.

BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0

BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1

  1. This LICENSE AGREEMENT is between BeOpen.com (``BeOpen''), having an office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization (``Licensee'') accessing and otherwise using this software in source or binary form and its associated documentation (``the Software'').

  2. Subject to the terms and conditions of this BeOpen Python License Agreement, BeOpen hereby grants Licensee a non-exclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use the Software alone or in any derivative version, provided, however, that the BeOpen Python License is retained in the Software, alone or in any derivative version prepared by Licensee.

  3. BeOpen is making the Software available to Licensee on an ``AS IS'' basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  5. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  6. This License Agreement shall be governed by and interpreted in all respects by the law of the State of California, excluding conflict of law provisions. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between BeOpen and Licensee. This License Agreement does not grant permission to use BeOpen trademarks or trade names in a trademark sense to endorse or promote products or services of Licensee, or any third party. As an exception, the ``BeOpen Python'' logos available at http://www.pythonlabs.com/logos.html may be used according to the permissions granted on that web page.

  7. By copying, installing or otherwise using the software, Licensee agrees to be bound by the terms and conditions of this License Agreement.

CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1

  1. This LICENSE AGREEMENT is between the Corporation for National Research Initiatives, having an office at 1895 Preston White Drive, Reston, VA 20191 (``CNRI''), and the Individual or Organization (``Licensee'') accessing and otherwise using Python 1.6.1 software in source or binary form and its associated documentation.

  2. Subject to the terms and conditions of this License Agreement, CNRI hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python 1.6.1 alone or in any derivative version, provided, however, that CNRI's License Agreement and CNRI's notice of copyright, i.e., ``Copyright © 1995-2001 Corporation for National Research Initiatives; All Rights Reserved'' are retained in Python 1.6.1 alone or in any derivative version prepared by Licensee. Alternately, in lieu of CNRI's License Agreement, Licensee may substitute the following text (omitting the quotes): ``Python 1.6.1 is made available subject to the terms and conditions in CNRI's License Agreement. This Agreement together with Python 1.6.1 may be located on the Internet using the following unique, persistent identifier (known as a handle): 1895.22/1013. This Agreement may also be obtained from a proxy server on the Internet using the following URL: http://hdl.handle.net/1895.22/1013.''

  3. In the event Licensee prepares a derivative work that is based on or incorporates Python 1.6.1 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python 1.6.1.

  4. CNRI is making Python 1.6.1 available to Licensee on an ``AS IS'' basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  7. This License Agreement shall be governed by the federal intellectual property law of the United States, including without limitation the federal copyright law, and, to the extent such U.S. federal law does not apply, by the law of the Commonwealth of Virginia, excluding Virginia's conflict of law provisions. Notwithstanding the foregoing, with regard to derivative works based on Python 1.6.1 that incorporate non-separable material that was previously distributed under the GNU General Public License (GPL), the law of the Commonwealth of Virginia shall govern this License Agreement only as to issues arising under or with respect to Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between CNRI and Licensee. This License Agreement does not grant permission to use CNRI trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party.

  8. By clicking on the ``ACCEPT'' button where indicated, or by copying, installing or otherwise using Python 1.6.1, Licensee agrees to be bound by the terms and conditions of this License Agreement.

ACCEPT

CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2

Copyright © 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, The Netherlands. All rights reserved.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Stichting Mathematisch Centrum or CWI not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: B. 浮動小数点演算、その問題と制限 Up: Python チュートリアル Next: D. 日本語訳について


D. 日本語訳について

D.1 このドキュメントについて

この文書は、Pythonドキュメント翻訳プロジェクトによる Python Tutorial の日本語訳版です。日本語訳に対する質問や提案などが ありましたら、Pythonドキュメント翻訳プロジェクトのメーリングリスト

http://www.python.jp/mailman/listinfo/python-doc-jp

または、プロジェクトのバグ管理ページ

http://sourceforge.jp/tracker/?atid=116&group_id=11&func=browse

までご報告ください。

D.2 翻訳者一覧 (敬称略)

1.3 和訳: SUZUKI Hisao <suzuki at acm.org> (August 27, 1995)
1.4 和訳: SUZUKI Hisao <suzuki at acm.org> (April 20, 1997)
1.5.1 和訳: SUZUKI Hisao <suzuki at acm.org> (August 23, 1998)
2.1 和訳: SUZUKI Hisao <suzuki at acm.org> (June 10, 2001)
2.2.3 差分和訳: sakito <sakito at s2.xrea.com> (August 10, 2003)
2.2.3 敬体訳: ymasuda <y.masuda at acm.org> (September 5, 2003)
2.3 差分和訳: sakito <sakito at s2.xrea.com> (August 30, 2003)
2.3 敬体訳: ymasuda <y.masuda at acm.org> (November 30, 2003)
2.3.3 差分訳: ymasuda <y.masuda at acm.org> (Devember 25, 2003)

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: C. 歴史とライセンス Up: Python チュートリアル Next: E. 用語集


E. 用語集

>>>
典型的な対話シェルのプロンプトです。インタプリタ上ですぐ実行できる ようなプログラムコード例の中によく書かれています。

...
典型的な対話シェルのプロンプトです。インデントされたコードブロック 内のコードの入力を促す際に出力されます。

__future__
互換性のない新たな機能を現在のインタプリタで有効にするために プログラマが利用できる擬似モジュールです。例えば、式 11/4 は現状では 2 になります。この式を実行しているモジュールで

from __future__ import division

を行って 真の除算操作 (true division) を有効にすると、 式 11/4 は 2.75 になります。実際に __future__ モジュールを import してその変数を評価すれば、新たな機能が初めて追加されたのが いつで、いつデフォルトの機能になる予定かわかります:

>>> import __future__
>>> __future__.division
_Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)

__slots__
新形式のクラス内で、インスタンス属性の記憶に必要な領域を あらかじめ定義しておき、それとひきかえにインスタンス辞書を 排除してメモリの節約を行うための宣言です。これはよく使われる テクニックですが、正しく動作させるのには少々手際を要するので、 例えばメモリが死活問題となるようなアプリケーション内に インスタンスが大量に存在するといった稀なケースを除き、 使わないのがベストです。

BDFL
慈悲ぶかき独裁者 (Benevolent Dictator For Life) の略です。 Python の作者、 Guido van Rossum のことです。

EAFP
「認可をとるより許しを請う方が容易 (easier to ask for forgiveness than permission、マーフィーの法則)」 の略です。 Python で広く使われているコーディングスタイルでは、通常は有効な キーや属性が存在するものと仮定し、その仮定が誤っていた場合に例外を 捕捉します。この簡潔で手早く書けるコーディングスタイルには、 try 文および except 文がたくさん あるのが特徴です。このテクニックは、C のような言語でよく使われている LBYL スタイルと対照的なものです。

GIL
グローバルインタプリタロック (global interpreter lock) を参照してください。

IDLE
Python の組み込み開発環境 (Integrated DeveLopment Environment) です。IDLE は Python の標準的な配布物についてくる基本的な機能の エディタとインタプリタ環境です。初心者に向いている点として、 IDLE はよく洗練され、複数プラットフォームで動作する GUI アプリケーションを実装したい人むけの明解なコード例にもなっています。

LBYL
「ころばぬ先の杖」 (look before you leap) の略です。 このコーディングスタイルでは、呼び出しや検索を行う前に、明示的に 前提条件 (pre-condition) 判定を行います。 EAFP アプローチと対照的で、if 文がたくさん使われる のが特徴的です。

Python3000
テレパシーインタフェースを持ち、後方互換性をもたなくてもよいとされて いる、架空の Python リリースのことです。

Python の悟り (Zen of Python)
Python を理解し利用する上での導きとなる、Python の設計原則と哲学を リストにしたものです。対話プロンプトで ``import this'' とすると、 リストを読めます。

イテレータ (iterator)
一連のデータ列 (stream) を表現するオブジェクトです。 イテレータの next() メソッドを繰り返し呼び出すと、 データ列中の要素を一つづつ返します。後続のデータがなくなると、 データの代わりに StopIteration 例外を送出します。 現時点では、イテレータオブジェクトが全てのオブジェクトを出し尽くすと、 それ以降は next() を何度呼んでも StopIteration を送出します。イテレータは、イテレータオブジェクト自体を返す __iter__() メソッドを実装しなければならなくなっており、 そのため全てのイテレータは他の反復可能オブジェクトを受理できる ほとんどの場所で反復可能で利用できます。 著しい例外は複数の反復を行うようなコードです。(list のような) コンテナオブジェクトでは、iter() 関数にオブジェクトを 渡したり、for ループ内で使うたびに、新たな未使用の イテレータを生成します。 このイテレータをさらに別の場所でイテレータとして使おうとすると、 二段階目のイテレータは使用済みの同じイテレータオブジェクトを返す ため、空のコンテナのように見えます。

インタプリタ形式の (interpreted)
Python はインタプリタ形式の言語であり、コンパイラ言語の対極に位置します。 ここでのインタプリタ言語とは、ソースコードのファイルを、 まず実行可能形式にしてから実行させるといった操作なしに、直接 実行できることを意味します。インタプリタ形式の言語は通常、 コンパイラ形式の言語よりも開発／デバッグのサイクルを持ちます。 対話的 (interactive) も参照してください。

型強制 (coercion)
データをある型から別の型に変換することです。例えば、 int(3.15) は浮動小数点数を整数に型強制し、3 にします. ほとんどの数学的演算には、引数を共通の型に型強制するような規則があります。 例えば、加算 3+4.5 は、整数 3 を 4.5 に加算する前に 浮動小数点数に型強制し、その結果は浮動小数点数 7.5 となります。

旧形式クラス (classic class)
object を継承していないクラス全てを指します。 新形式クラス (new-style class) も参照してください。

グローバルインタプリタロック (global interpreter lock)
Python の実行スレッド間で使われているロックで、一度に一つのスレッド だけが動作するよう保証しています。このロックによって、同時に同じ メモリにアクセスする二つのプロセスは存在しないと保証されているので、 Python を単純な構造にできるのです。インタプリタ全体にロックをかけると、 多重プロセサ計算機における並列性の恩恵と引き換えにインタプリタ の多重スレッド化を簡単に行えます。かつて ``スレッド自由な (free-threaded)'' インタプリタを作ろうと 努力したことがありましたが、広く使われている単一プロセサ の場合にはパフォーマンスが低下するという事態に悩まされました。

ジェネレータ (generator)
イテレータを返す関数です。return の代わりに yield が使われている他は、通常の関数と同じに見えます。ジェネレータ関数は 一つまたはそれ以上の for ループや while ループ を含んでおり、ループの呼び出し側に要素を返す (yield) ように なっています。ジェネレータが返すイテレータを使って関数を実行すると、 関数は yield キーワードで (値を返して) 一旦停止し、 next() を呼んで次の要素を要求するたびに実行を再開します。

辞書 (dictionary)
任意のキーを値に対応付ける連想配列です。dict の使い方は list に似ていますが、ゼロから始まる整数ではなく、 __hash__() 関数を実装している全てのオブジェクトを キーにできます。Perl ではハッシュ (hash) と呼ばれています。

新形式クラス (new-style class)
object から継承したクラス全てを指します。これには list や dict のような全ての組み込み型が含まれます。 __slots__ 、デスクリプタ、プロパティ、 __getattribute__()、クラスメソッド、静的メソッドといった、 Python の新しい精緻な機能を使えるのは新形式のクラスだけです。

整数除算 (integer division)
剰余を考慮しない数学的除算です。例えば、式 11/4 は現状では 2 になりますが、浮動小数点数の除算では 2.75 を返します。 切り捨て除算 (floor division) とも呼ばれます。 二つの整数間で除算を行うと、結果は (端数切捨て関数が適用されて) 常に整数になります。 しかし、被演算子の一方が (float のような) 別の数値型の 場合、演算の結果は共通の型に型強制されます (型強制 (coercion) 参照)。例えば、浮動小数点数で整数を除算すると 結果は浮動小数点になり、場合によっては端数部分を伴います。 // 演算子を / の代わりに使うと、整数除算を 強制できます。__future__ も参照してください。

対話的 (interactive)
Python には対話的インタプリタがあり、何かを試してその結果を直接 見られます。python を引数なしで起動 (場合によっては コンピュータのメインメニューから選んで起動) してください。 対話的インタプリタは新しいアイデアを試したり、モジュールや パッケージの中を調べてみたりする (help(x) を思い出してください) ための強力な方法です。

デスクリプタ (descriptor)
メソッド __get__()、 __set__()、あるいは __delete__() が定義されている 新形式 のオブジェクトです。 あるクラス属性がデスクリプタである場合、その属性を検索すると、 そのデスクリプタ固有に束縛されている動作を呼び出します。通常、 a.b と書くと、a のクラス辞書内でオブジェクト b を検索しますが、b がデスクリプタの場合には、デスクリプタで 定義されたメソッドを呼び出します。 デスクリプタの理解は、 Python を深く理解する上で鍵となります。 というのは、デスクリプタこそが、関数、メソッド、プロパティ、 クラスメソッド、静的メソッド、そしてスーパクラスの参照といった 多くの機能の基盤だからです。

名前空間 (namespace)
変数を記憶している場所です。名前空間は辞書を用いて実装しています。 名前空間には、ローカル、グローバル、組み込み名前空間、そして (メソッド内の) オブジェクトのネストされた名前空間があります。 例えば、関数 __builtin__.open() および os.open() は名前空間で区別します。名前空間はまた、ある関数をどのモジュールが 実装しているかをはっきりさせることで、可読性やメンテナンス性を 与えます。例えば、random.seed() 、あるいは itertools.izip() と書くことで、これらの関数がそれぞれ random モジュールや itertools モジュールで実装されていることがはっきりします。

ネストされたスコープ (nested scope)
ある文が何らかの定義に囲われているとき、定義の外で使われている変数を その文から参照できる機能です。例えば、ある関数が別の関数の中で定義 されている場合、内側の関数は外側の関数中の変数を参照できます。 ネストされたスコープは変数の参照だけができ、変数の代入はできないので 注意してください。変数の代入は、常に最も内側のスコープにある変数に 対する書き込みになります。 対照的に、ローカル変数を使うと、常に最も内側のスコープで値を読み書き します。同様に、グローバル変数を使うと、グローバル名前空間の値を 読み書きします。

バイトコード (byte code)
インタプリタ中の Python プログラムを表す内部表現です。 バイトコードはまた、 .pyc や .pyo ファイルに キャッシュされ、同じファイルを二度目に実行した際により高速に 実行できるようにします (ソースコードはバイトコードにコンパイルされて 保存されます)。このバイトコードは、各々のバイトコードに 対応するサブルーチンを呼び出すような ``仮想計算機 (virtual machine)'' で動作する ``中間言語 (intermediate language)'' といえます。

配列 (sequence)
反復可能なオブジェクト (iterable) 反復可能なオブジェクト (iterable) は、 特殊なメソッド __getitem__() および __len__() を 介して整数インデクスを使った効率的な要素アクセスをサポートします。 組み込み配列型には、list、str、 tuple、 および unicode があります。 dict は __getitem__() と __len__() もサポートしますが、検索の際に任意の 変更不能 (immutable) な キーを使うため、配列というよりもむしろマップ (mapping) とみなされて いるので注意してください。

反復可能オブジェクト (iterable)
コンテナオブジェクトで、コンテナ内のメンバを一つづつ返せる ようになっているものです。反復可能オブジェクトの例には、 (list、str、および tuple といった) 全ての配列型や、dict や file といった 非配列型、あるいは __iter__() や __getitem__() メソッドを実装したクラスのインスタンスが含まれます。 反復可能オブジェクトは for ループ内やその他多くの 配列が必要となる状況 (zip()、 map(), ...) で利用できまnす。反復可能オブジェクトを組み込み関数 iter() の引数として渡すと、オブジェクトに対する イテレータを返します。このイテレータは一連の値を引き渡す際に便利 です。反復可能オブジェクトを使う際には、通常iter() を呼んだり、イテレータオブジェクトを自分で扱う必要はありません。 for 文ではこの操作を自動的に行い、無名の変数を作成して、 ループの間イテレータを記憶します。 イテレータ (iterator)、 配列 (sequence)、および ジェネレータ (generator) も参照してください。

変更可能なオブジェクト (mutable)
変更可能なオブジェクトは、id() を変えることなく値を変更 できます。 変更不能 (immutable) も参照してください。

変更不能なオブジェクト (immutable)
固定の値を持ったオブジェクトです。変更不能なオブジェクトには、 数値、文字列、およびタプル (そしてその他) があります。これらの オブジェクトは値を変えられません。別の値を記憶させる際には、 新たなオブジェクトを作成しなければなりません。変更不能なオブジェクト は、固定値のハッシュ値が必要となる状況で重要な役割を果たします。 辞書におけるキーがその例です。

マップ (mapping)
特殊メソッド __getitem__() を使って、任意のキーに対する検索を サポートする (dict のような) コンテナオブジェクトです。

メタクラス (metaclass)
何らかのクラスを生成するクラスです。クラス定義を行うと、クラス名、 クラス辞書、そして基底クラスからなるリストが生成されます。 メタクラスはこれらの三つを引数として取り、メタクラスを生成する 働きをします。ほとんどのオブジェクト指向プログラム言語には、 メタクラスに対するデフォルトの実装があります。Python の特徴的な点は、 自作のメタクラスを作成できることです。ほとんどのユーザにとって、 このツールはまったく必要のないものですが、必要さえあれば、メタクラスは 強力でエレガントな問題解決手段になります。メタクラスは、属性への アクセスをログに記録したり、システムをスレッド安全にしたり、 オブジェクトの生成の追跡したり、単集合を実装したり、そしてその他 多くのタスクで使われてきています。

リストの内包表現 (list comprehension)
配列内の全ての要素、あるいはサブセットを処理してその結果からなる リストを返させるための、コンパクトなやりかたです。 result = ["0x%02x" % x for x in range(256) if x % 2 == 0] とすると、 0 から 255 までの偶数を 16進数表記 (0x..) した 文字列からなるリストを生成します。 if 節はオプションです。if 節がない場合、 上のケースでは range(256) の全ての要素が処理されます。

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: D. 日本語訳について Up: Python チュートリアル Next: 索引


索引

記号 | _ | a | b | c | d | e | f | g | i | j | k | l | m | n | o | p | r | s | u | z

記号

...
>>>

_ (アンダースコア)

__builtin__ (組み込み モジュール)
__future__
__slots__

A

append() (list のメソッド)

B

BDFL
byte code

C

classic class
coercion
compileall (標準 モジュール)
count() (list のメソッド)

D

descriptor
dictionary
docstrings, [リンク]
documentation strings, [リンク]

E

EAFP
extend() (list のメソッド)

F

file オブジェクト
for 実行文, [リンク]

G

generator
GIL
global interpreter lock

I

IDLE
immutable
index() (list のメソッド)
INPUTRC (environment variable), [リンク]
INPUTRC (環境変数), [リンク]
insert() (list のメソッド)
integer division
interactive
interpreted
iterable
iterator

J

実行文
for, [リンク]

K

環境変数
INPUTRC, [リンク]
PATH, [リンク]
PYTHONPATH, [リンク], [リンク], [リンク], [リンク], [リンク]
環境変数 (続き)
PYTHONSTARTUP, [リンク]
検索
パス, モジュール

L

LBYL
list comprehension

M

mapping
metaclass
method オブジェクト
module
search path
文字列, ドキュメンテーション, [リンク]
モジュール
検索 パス
mutable

N

namespace
nested scope
new-style class

O

オブジェクト
file
method
open() (組み込み関数)

P

パス
モジュール 検索
path
module search
PATH (environment variable), [リンク]
PATH (環境変数), [リンク]
pickle (標準 モジュール)
pop() (list のメソッド)
Python3000
PYTHONPATH (environment variable), [リンク], [リンク], [リンク], [リンク], [リンク]
PYTHONPATH (環境変数), [リンク], [リンク], [リンク], [リンク], [リンク]
PYTHONSTARTUP (environment variable), [リンク]
PYTHONSTARTUP (環境変数), [リンク]

R

readline (組み込み モジュール)
remove() (list のメソッド)
reverse() (list のメソッド)
rlcompleter (標準 モジュール)

S

search
path, module
sequence
sort() (list のメソッド)
string (標準 モジュール)
strings, documentation, [リンク]
sys (標準 モジュール)

U

unicode() (組み込み関数)

Z

Zen of Python

Previous Page Up One Level Next Page Python チュートリアル Contents
Previous: E. 用語集 Up: Python チュートリアル Next: この文書について...


Python ライブラリリファレンス

Guido van Rossum

PythonLabs
Email: docs@python.org

Fred L. Drake, Jr., editor

リリース 2.3.3
平成16年6月28日

日本語訳: Python ドキュメント翻訳プロジェクト

  • 序
  • 目次
  • 1. はじめに
  • 2. 組み込みオブジェクト
    • 2.1 組み込み関数
    • 2.2 非必須組み込み関数 (Non-essential Built-in Functions)
    • 2.3 組み込み型
      • 2.3.1 真値テスト
      • 2.3.2 ブール演算
      • 2.3.3 比較
      • 2.3.4 数値型
      • 2.3.5 イテレータ型
      • 2.3.6 配列型
      • 2.3.7 マップ型
      • 2.3.8 ファイルオブジェクト
      • 2.3.9 他の組み込み型
      • 2.3.10 特殊な属性
    • 2.4 組み込み例外
    • 2.5 組み込み定数
  • 3. Python ランタイム サービス
    • 3.1 sys -- システムパラメータと関数
    • 3.2 gc -- ガベージコレクタ インターフェース
    • 3.3 weakref -- 弱参照
      • 3.3.1 弱参照オブジェクト
      • 3.3.2 例
      • 3.3.3 拡張型における弱参照
    • 3.4 fpectl -- 浮動小数点例外の制御
      • 3.4.1 例
      • 3.4.2 制限と他に考慮すべきこと
    • 3.5 atexit -- 終了ハンドラ
      • 3.5.1 atexit 例
    • 3.6 types -- 組み込み型の名前
    • 3.7 UserDict -- 辞書オブジェクトのためのクラスラッパー
    • 3.8 UserList -- リストオブジェクトのためのクラスラッパー
    • 3.9 UserString -- 文字列オブジェクトのためのクラスラッパー
    • 3.10 operator -- 関数形式の標準演算子
      • 3.10.1 演算子から関数への対応表
    • 3.11 inspect -- 使用中のオブジェクトを調査
      • 3.11.1 型とメンバ
      • 3.11.2 ソース参照
    • 3.12 traceback -- スタックトレースの表示や取り出し
      • 3.12.1 トレースバックの例
    • 3.13 linecache -- テキストラインにランダムアクセスする
    • 3.14 pickle -- Python オブジェクトの整列化
      • 3.14.1 他の Python モジュールとの関係
      • 3.14.2 データストリームの形式
      • 3.14.3 使用法
      • 3.14.4 何を pickle 化したり unpickle 化できるのか?
      • 3.14.5 pickle 化プロトコル
      • 3.14.6 Unpickler をサブクラス化する
      • 3.14.7 例
    • 3.15 cPickle -- より高速な pickle
    • 3.16 copy_reg -- pickleサポート関数を登録する
    • 3.17 shelve -- Python オブジェクトの永続化
      • 3.17.1 制限事項
      • 3.17.2 使用例
    • 3.18 copy -- 浅いコピーおよび深いコピー操作
    • 3.19 marshal -- 内部使用向けの Python オブジェクト整列化
    • 3.20 warnings -- 警告の制御
      • 3.20.1 警告カテゴリ
      • 3.20.2 警告フィルタ
      • 3.20.3 利用可能な関数
    • 3.21 imp -- import内部へアクセスする
      • 3.21.1 例
    • 3.22 pkgutil -- パッケージ拡張ユーティリティ
    • 3.23 code -- インタプリタ基底クラス
      • 3.23.1 対話的なインタプリタオブジェクト
      • 3.23.2 対話的なコンソールオブジェクト
    • 3.24 codeop -- Pythonコードをコンパイルする
    • 3.25 pprint -- データ出力の整然化
      • 3.25.1 PrettyPrinter オブジェクト
    • 3.26 repr -- もう一つのrepr()の実装
      • 3.26.1 Reprオブジェクト
      • 3.26.2 Reprオブジェクトをサブクラス化する
    • 3.27 new -- ランタイム内部オブジェクトの作成
    • 3.28 site -- サイト固有の設定フック
    • 3.29 user -- ユーザー設定のフック
    • 3.30 __builtin__ -- 組み込み関数
    • 3.31 __main__ -- トップレベルのスクリプト環境
    • 3.32 __future__ -- Future ステートメントの定義
  • 4. 文字列処理
    • 4.1 string -- 一般的な文字列操作
    • 4.2 re -- 正規表現操作
      • 4.2.1 正規表現のシンタックス
      • 4.2.2 マッチング vs 検索
      • 4.2.3 モジュール コンテンツ
      • 4.2.4 正規表現オブジェクト
      • 4.2.5 MatchObject オブジェクト
      • 4.2.6 例
    • 4.3 struct -- 文字列データをパックされたバイナリデータとして解釈する
    • 4.4 difflib -- 差異の計算を助ける
      • 4.4.1 SequenceMatcherオブジェクト
      • 4.4.2 SequenceMatcher の例
      • 4.4.3 Differ オブジェクト
      • 4.4.4 Differ の例
    • 4.5 fpformat -- 浮動小数点の変換
    • 4.6 StringIO -- ファイルのように文字列を読み書きする
    • 4.7 cStringIO -- 高速化された StringIO
    • 4.8 textwrap -- テキストの折り返しと詰め込み
    • 4.9 codecs -- codec レジストリと基底クラス
      • 4.9.1 Codec 基底クラス
      • 4.9.2 標準エンコーディング
      • 4.9.3 encodings.idna -- アプリケーションにおける国際化ドメイン名 (IDNA)
    • 4.10 unicodedata -- Unicode データベース
    • 4.11 stringprep -- インターネットのための文字列調製
  • 5. 各種サービス
    • 5.1 pydoc -- ドキュメント生成とオンラインヘルプシステム
    • 5.2 doctest -- ドキュメンテーション文字列に本当のことが書かれているか調べる
      • 5.2.1 通常の利用法
      • 5.2.2 どのドキュメンテーション文字列が検証されるのか?
      • 5.2.3 実行コンテキストとは何か?
      • 5.2.4 例外については?
      • 5.2.5 進んだ使い方
      • 5.2.6 ドキュメンテーション文字列内の例をどうやって認識するのか?
      • 5.2.7 注意事項
      • 5.2.8 提言
    • 5.3 unittest -- 単体テストフレームワーク
      • 5.3.1 基礎的な例
      • 5.3.2 テストの構成
      • 5.3.3 既存テストコードの再利用
      • 5.3.4 クラスと関数
      • 5.3.5 TestCase オブジェクト
      • 5.3.6 TestSuite オブジェクト
      • 5.3.7 TestResultオブジェクト
      • 5.3.8 TestLoader オブジェクト
    • 5.4 test -- Python用回帰テストパッケージ
      • 5.4.1 testパッケージのためのユニットテストを書く
      • 5.4.2 test.regrtestを使ってテストを実行する
      • 5.4.3 test.test_support -- テストのためのユーティリティ関数
    • 5.5 math -- 数学関数
    • 5.6 cmath -- 複素数のための数学関数
    • 5.7 random -- 擬似乱数を生成する
    • 5.8 whrandom -- 擬似乱数生成器
    • 5.9 bisect -- 配列二分法アルゴリズム
      • 5.9.1 使用例
    • 5.10 heapq -- ヒープキューアルゴリズム
      • 5.10.1 理論
    • 5.11 array -- 効率のよい数値配列
    • 5.12 sets -- ユニークな要素の順序なしコレクション
      • 5.12.1 Set オブジェクト
      • 5.12.2 使用例
      • 5.12.3 不変に自動変換するためのプロトコル
    • 5.13 itertools -- 効率的なループ実行のためのイテレータ生成関数
      • 5.13.1 Itertool関数
      • 5.13.2 例
    • 5.14 ConfigParser -- 設定ファイルの構文解析器
      • 5.14.1 RawConfigParser オブジェクト
      • 5.14.2 ConfigParser オブジェクト
    • 5.15 fileinput -- 複数の入力ストリームをまたいだ行の繰り返し処理をサポートする。
    • 5.16 xreadlines -- ファイルの各行に対する効率のよい反復処理
    • 5.17 calendar -- 一般的なカレンダーに関する関数群
    • 5.18 cmd -- 行指向のコマンドインタープリタのサポート
      • 5.18.1 Cmdオブジェクト
    • 5.19 shlex -- 単純な字句解析
      • 5.19.1 モジュールの内容
      • 5.19.2 shlex オブジェクト
      • 5.19.3 解析規則
  • 6. 汎用オペレーティングシステムサービス
    • 6.1 os -- 雑多なオペレーティングシステムインタフェース
      • 6.1.1 プロセスのパラメタ
      • 6.1.2 ファイルオブジェクトの生成
      • 6.1.3 ファイル記述子の操作
      • 6.1.4 ファイルとディレクトリ
      • 6.1.5 プロセス管理
      • 6.1.6 雑多なシステム情報
    • 6.2 os.path -- 共通のパス名操作
    • 6.3 dircache -- キャッシュされたディレクトリ一覧の生成
    • 6.4 stat -- stat() の返す内容を解釈する
    • 6.5 statcache -- os.stat() の最適化
    • 6.6 statvfs -- os.statvfs() で使われる定数群
    • 6.7 filecmp -- ファイルおよびディレクトリの比較
      • 6.7.1 dircmp クラス
    • 6.8 popen2 -- アクセス可能な I/O ストリームを持つ子プロセス生成
      • 6.8.1 Popen3 および Popen4 オブジェクト
      • 6.8.2 フロー制御の問題
    • 6.9 datetime -- 基本的な日付型および時間型
      • 6.9.1 利用可能なデータ型
      • 6.9.2 timedelta オブジェクト
      • 6.9.3 date オブジェクト
      • 6.9.4 datetime オブジェクト
      • 6.9.5 time オブジェクト
      • 6.9.6 tzinfo オブジェクト
      • 6.9.7 strftime() の振る舞い
    • 6.10 time -- 時刻データへのアクセスと変換
    • 6.11 sched -- イベントスケジューラ
      • 6.11.1 スケジューラオブジェクト
    • 6.12 mutex -- 排他制御
      • 6.12.1 mutex オブジェクト
    • 6.13 getpass -- 可搬性のあるパスワード入力機構
    • 6.14 curses -- 文字セル表示のための端末操作
      • 6.14.1 関数
      • 6.14.2 Window オブジェクト
      • 6.14.3 定数
    • 6.15 curses.textpad -- curses プログラムのためのテキスト入力ウィジェット
      • 6.15.1 Textbox オブジェクト
    • 6.16 curses.wrapper -- curses プログラムのための端末ハンドラ
    • 6.17 curses.ascii -- ASCII 文字に関するユーティリティ
    • 6.18 curses.panel -- curses のためのパネルスタック拡張
      • 6.18.1 関数
      • 6.18.2 Panel オブジェクト
    • 6.19 getopt -- コマンドラインオプションのパーザ
    • 6.20 optparse -- 強力なコマンドラインオプション解析器
      • 6.20.1 オプション解析への道
      • 6.20.2 基本的な使い方
      • 6.20.3 進んだ使い方
      • 6.20.4 callback オプション
      • 6.20.5 optparse を拡張する
    • 6.21 tempfile -- 一時的なファイルやディレクトリの生成
    • 6.22 errno -- 標準の errno システムシンボル
    • 6.23 glob -- Unix 形式のパス名のパターン展開
    • 6.24 fnmatch -- Unix ファイル名のパターンマッチ
    • 6.25 shutil -- 高レベルなファイル操作
      • 6.25.1 使用例
    • 6.26 locale -- 国際化サービス
      • 6.26.1 ロケールの背景、詳細、ヒント、助言および補足説明
      • 6.26.2 Python 拡張の作者と、Python を埋め込むようなプログラムに関して
      • 6.26.3 メッセージカタログへのアクセス
    • 6.27 gettext -- 多言語対応に関する国際化サービス
      • 6.27.1 GNU gettext API
      • 6.27.2 クラスに基づいた API
      • 6.27.3 プログラムやモジュールを国際化する
      • 6.27.4 謝辞
    • 6.28 logging -- Python用ロギング機能
      • 6.28.1 Logger オブジェクト
      • 6.28.2 Handler オブジェクト
      • 6.28.3 Formatter オブジェクト
      • 6.28.4 Filter オブジェクト
      • 6.28.5 LogRecord オブジェクト
      • 6.28.6 スレッド安全性
      • 6.28.7 環境設定
      • 6.28.8 Using the logging package
  • 7. オプションのオペレーティングシステムサービス
    • 7.1 signal -- 非同期イベントにハンドラを設定する
      • 7.1.1 例
    • 7.2 socket -- 低レベルネットワークインターフェース
      • 7.2.1 socket オブジェクト
      • 7.2.2 SSL オブジェクト
      • 7.2.3 例
    • 7.3 select -- I/O 処理の完了を待機する
      • 7.3.1 ポーリングオブジェクト
    • 7.4 thread -- マルチスレッドのコントロール
    • 7.5 threading -- 高レベルスレッドインターフェース
      • 7.5.1 Lock オブジェクト
      • 7.5.2 RLock オブジェクト
      • 7.5.3 Condition オブジェクト
      • 7.5.4 Semaphore オブジェクト
      • 7.5.5 Event オブジェクト
      • 7.5.6 Thread オブジェクト
      • 7.5.7 Timer オブジェクト
    • 7.6 dummy_thread -- thread の代替モジュール
    • 7.7 dummy_threading -- threading の代替モジュール
    • 7.8 Queue -- 同期キュークラス
      • 7.8.1 キューオブジェクト
    • 7.9 mmap -- メモリマップファイル
    • 7.10 anydbm -- DBM 形式のデータベースへの汎用アクセスインタフェース
    • 7.11 dbhash -- BSD データベースライブラリへの DBM 形式のインタフェース
      • 7.11.1 データベースオブジェクト
    • 7.12 whichdb -- どのDBMモジュールがデータベースを作ったかを推測する
    • 7.13 bsddb -- Berkeley DB ライブラリへのインタフェース
      • 7.13.1 ハッシュ、BTree、およびレコードオブジェクト
    • 7.14 dumbdbm -- 可搬性のある DBM 実装
      • 7.14.1 Dumbdbm オブジェクト
    • 7.15 zlib -- gzip 互換の圧縮
    • 7.16 gzip -- gzip ファイルのサポート
    • 7.17 bz2 -- bzip2 互換の圧縮ライブラリ
      • 7.17.1 ファイルの圧縮（解凍）
      • 7.17.2 逐次的な圧縮（解凍）
      • 7.17.3 一括圧縮（解凍）
    • 7.18 zipfile -- ZIP アーカイブの処理
      • 7.18.1 ZipFile オブジェクト
      • 7.18.2 PyZipFile オブジェクト
      • 7.18.3 ZipInfo オブジェクト
    • 7.19 tarfile -- tar アーカイブファイルを読み書きする
      • 7.19.1 TarFile オブジェクト
      • 7.19.2 TarInfo オブジェクト
      • 7.19.3 例
    • 7.20 readline -- GNU readline のインタフェース
      • 7.20.1 例
    • 7.21 rlcompleter -- GNU readline向け補完関数
      • 7.21.1 Completerオブジェクト
  • 8. Unix独特のサービス
    • 8.1 posix -- 最も一般的な POSIX システムコール群
      • 8.1.1 ラージファイルのサポート
      • 8.1.2 モジュールの内容
    • 8.2 pwd -- パスワードデータベースへのアクセスを提供する
    • 8.3 grp -- グループデータベースへのアクセス
    • 8.4 crypt -- Unix パスワードをチェックするための関数
    • 8.5 dl -- 共有オブジェクトのC関数の呼び出し
      • 8.5.1 Dlオブジェクト
    • 8.6 dbm -- UNIX dbmのシンプルなインタフェース
    • 8.7 gdbm -- GNU による dbm の再実装
    • 8.8 termios -- POSIX スタイルの端末制御
      • 8.8.1 使用例
    • 8.9 TERMIOS -- termios モジュールで使われる定数
    • 8.10 tty -- 端末制御のための関数群
    • 8.11 pty -- 擬似端末ユーティリティ
    • 8.12 fcntl -- fcntl() および ioctl() システムコール
    • 8.13 pipes -- シェルパイプラインへのインタフェース
      • 8.13.1 テンプレートオブジェクト
    • 8.14 posixfile -- ロック機構をサポートするファイル類似オブジェクト
    • 8.15 resource -- リソース使用状態の情報
      • 8.15.1 リソースの制限
      • 8.15.2 リソースの使用状態
    • 8.16 nis -- Sun の NIS (Yellow Pages) へのインタフェース
    • 8.17 syslog -- Unix syslog ライブラリルーチン群
    • 8.18 commands -- コマンド実行ユーティリティ
  • 9. Pythonデバッガ
    • 9.1 デバッガコマンド
    • 9.2 どのように動作しているか
  • 10. Python プロファイラ
    • 10.1 プロファイラとは
    • 10.2 旧バージョンのプロファイラとの違い
    • 10.3 インスタント・ユーザ・マニュアル
    • 10.4 決定論的プロファイリングとは何か?
    • 10.5 リファレンス・マニュアル
      • 10.5.1 Stats クラス
    • 10.6 制限事項
    • 10.7 キャリブレーション(補正)
    • 10.8 拡張 -- プロファイラの改善
    • 10.9 hotshot -- ハイパフォーマンス・ロギング・プロファイラ
      • 10.9.1 プロファイル・オブジェクト
      • 10.9.2 hotshot データの利用
      • 10.9.3 使用例
    • 10.10 timeit -- 小さなコード断片の実行時間計測
      • 10.10.1 コマンドライン・インターフェース
      • 10.10.2 使用例
  • 11. インターネットプロトコルとその支援
    • 11.1 webbrowser -- 便利なウェブブラウザコントローラー
      • 11.1.1 ブラウザコントローラーオブジェクト
    • 11.2 cgi -- CGI (ゲートウェイインタフェース規格) のサポート
      • 11.2.1 はじめに
      • 11.2.2 cgi モジュールを使う
      • 11.2.3 高レベルインタフェース
      • 11.2.4 古いクラス群
      • 11.2.5 関数
      • 11.2.6 セキュリティへの配慮
      • 11.2.7 CGI スクリプトを Unix システムにインストールする
      • 11.2.8 CGI スクリプトをテストする
      • 11.2.9 CGI スクリプトをデバッグする
      • 11.2.10 よくある問題と解決法
    • 11.3 cgitb -- CGI スクリプトのトレースバック管理機構
    • 11.4 urllib -- URL による任意のリソースへのアクセス
      • 11.4.1 URLopener オブジェクト
      • 11.4.2 使用例
    • 11.5 urllib2 -- URL を開くための拡張可能なライブラリ
      • 11.5.1 Request オブジェクト
      • 11.5.2 OpenerDirector オブジェクト
      • 11.5.3 BaseHandler オブジェクト
      • 11.5.4 HTTPRedirectHandler オブジェクト
      • 11.5.5 ProxyHandler オブジェクト
      • 11.5.6 HTTPPasswordMgr オブジェクト
      • 11.5.7 AbstractBasicAuthHandler オブジェクト
      • 11.5.8 HTTPBasicAuthHandler オブジェクト
      • 11.5.9 ProxyBasicAuthHandler オブジェクト
      • 11.5.10 AbstractDigestAuthHandler オブジェクト
      • 11.5.11 HTTPDigestAuthHandler オブジェクト
      • 11.5.12 ProxyDigestAuthHandler オブジェクト
      • 11.5.13 HTTPHandler オブジェクト
      • 11.5.14 HTTPSHandler オブジェクト
      • 11.5.15 FileHandler オブジェクト
      • 11.5.16 FTPHandler オブジェクト
      • 11.5.17 CacheFTPHandler オブジェクト
      • 11.5.18 GopherHandler オブジェクト
      • 11.5.19 UnknownHandler オブジェクト
      • 11.5.20 例
    • 11.6 httplib -- HTTP プロトコルクライアント
      • 11.6.1 HTTPConnection オブジェクト
      • 11.6.2 HTTPResponse オブジェクト
      • 11.6.3 例
    • 11.7 ftplib -- FTPプロトコルクライアント
      • 11.7.1 FTP オブジェクト
    • 11.8 gopherlib -- gopher プロトコルのクライアント
    • 11.9 poplib -- POP3 プロトコルクライアント
      • 11.9.1 POP3 オブジェクト
      • 11.9.2 POP3 の例
    • 11.10 imaplib -- IMAP4 プロトコルクライアント
      • 11.10.1 IMAP4 オブジェクト
      • 11.10.2 IMAP4 の使用例
    • 11.11 nntplib -- NNTP プロトコルクライアント
      • 11.11.1 NNTP オブジェクト
    • 11.12 smtplib -- SMTP プロトコル クライアント
      • 11.12.1 SMTP オブジェクト
      • 11.12.2 SMTP 使用例
    • 11.13 telnetlib -- Telnet クライアント
      • 11.13.1 Telnet オブジェクト
      • 11.13.2 Telnet Example
    • 11.14 urlparse -- URL を解析して構成要素にする
    • 11.15 SocketServer -- ネットワークサーバ構築のための フレームワーク
    • 11.16 BaseHTTPServer -- 基本的な機能を持つ HTTP サーバ
    • 11.17 SimpleHTTPServer -- 簡潔な HTTP リクエストハンドラ
    • 11.18 CGIHTTPServer -- CGI 実行機能付き HTTP リクエスト処理機構
    • 11.19 Cookie -- HTTPの状態管理
      • 11.19.1 Cookieオブジェクト
      • 11.19.2 Morselオブジェクト
      • 11.19.3 例
    • 11.20 xmlrpclib -- XML-RPC クライアントアクセス
      • 11.20.1 ServerProxy オブジェクト
      • 11.20.2 Boolean オブジェクト
      • 11.20.3 DateTime オブジェクト
      • 11.20.4 Binary オブジェクト
      • 11.20.5 Fault オブジェクト
      • 11.20.6 ProtocolError オブジェクト
      • 11.20.7 補助関数
      • 11.20.8 クライアントのサンプル
    • 11.21 SimpleXMLRPCServer -- 基本的なXML-RPCサーバー
      • 11.21.1 SimpleXMLRPCServer オブジェクト
      • 11.21.2 CGIXMLRPCRequestHandler
    • 11.22 DocXMLRPCServer -- セルフ-ドキュメンティング XML-RPC サーバ
      • 11.22.1 DocXMLRPCServer オブジェクト
      • 11.22.2 DocCGIXMLRPCRequestHandler
    • 11.23 asyncore -- 非同期ソケットハンドラ
      • 11.23.1 asyncoreの例：簡単なHTTPクライアント
    • 11.24 asynchat -- 非同期ソケット コマンド/レスポンス ハンドラ
      • 11.24.1 asynchat - 補助クラスと関数
      • 11.24.2 asynchat 使用例
  • 12. インターネット上のデータの操作
    • 12.1 formatter -- 汎用の出力書式化機構
      • 12.1.1 formatter インタフェース
      • 12.1.2 formatter 実装
      • 12.1.3 writer インタフェース
      • 12.1.4 writer 実装
    • 12.2 email -- 電子メールと MIME 処理のためのパッケージ
      • 12.2.1 電子メールメッセージの表現
      • 12.2.2 電子メールメッセージを解析(パース)する
      • 12.2.3 MIME 文書を生成する
      • 12.2.4 電子メールおよび MIME オブジェクトをゼロから作成する
      • 12.2.5 国際化されたヘッダ
      • 12.2.6 文字セットの表現
      • 12.2.7 エンコーダ
      • 12.2.8 例外クラス
      • 12.2.9 雑用ユーティリティ
      • 12.2.10 イテレータ
      • 12.2.11 (Python 2.2.1 までの) email v1 とのちがい
      • 12.2.12 mimelib との違い
      • 12.2.13 使用例
    • 12.3 mailcap -- mailcap ファイルの操作
    • 12.4 mailbox -- 様々なメールボックス形式の読み出し
      • 12.4.1 Mailbox オブジェクト
    • 12.5 mhlib -- MH のメイルボックスへのアクセス機構
      • 12.5.1 MH オブジェクト
      • 12.5.2 Folder オブジェクト
      • 12.5.3 Message オブジェクト
    • 12.6 mimetools -- MIME メッセージを解析するためのツール
      • 12.6.1 Message オブジェクトの追加メソッド
    • 12.7 mimetypes -- ファイル名を MIME 型へマップする
      • 12.7.1 Mime型 オブジェクト
    • 12.8 MimeWriter -- 汎用 MIME ファイルライター
      • 12.8.1 MimeWriter オブジェクト
    • 12.9 mimify -- 電子メイルメッセージの MIME 処理
    • 12.10 multifile -- 個別の部分を含んだファイル群のサポート
      • 12.10.1 MultiFile オブジェクト
      • 12.10.2 MultiFile の例
    • 12.11 rfc822 -- RFC 2822 準拠のメイルヘッダ読み出し
      • 12.11.1 Message オブジェクト
      • 12.11.2 AddressList オブジェクト
    • 12.12 base64 -- MIME base64 形式データのエンコードおよびデコード
    • 12.13 binascii -- バイナリデータと ASCIIデータとの間での変換
    • 12.14 binhex -- binhex4 形式ファイルのエンコードおよびデコード
      • 12.14.1 注記
    • 12.15 quopri -- MIME quoted-printable 形式データのエンコードおよびデコード
    • 12.16 uu -- uuencode形式のエンコードとデコード
    • 12.17 xdrlib -- XDR データのエンコードおよびデコード
      • 12.17.1 Packer オブジェクト
      • 12.17.2 Unpacker オブジェクト
      • 12.17.3 例外
    • 12.18 netrc -- netrc ファイルの処理
      • 12.18.1 netrc オブジェクト
    • 12.19 robotparser -- robots.txt のためのパーザ
    • 12.20 csv -- CSV ファイルの読み書き
      • 12.20.1 モジュールの内容
      • 12.20.2 Dialect クラスと書式化パラメタ
      • 12.20.3 reader オブジェクト
      • 12.20.4 writer オブジェクト
      • 12.20.5 使用例
  • 13. 構造化マークアップツール
    • 13.1 HTMLParser -- HTML および XHTML のシンプルなパーザ
      • 13.1.1 HTML パーザアプリケーションの例
    • 13.2 sgmllib -- 単純な SGML パーザ
    • 13.3 htmllib -- HTML 文書の解析器
      • 13.3.1 HTMLParser オブジェクト
    • 13.4 htmlentitydefs -- HTML 一般エンティティの定義
    • 13.5 xml.parsers.expat -- Expat を使った高速な XML 解析
      • 13.5.1 XMLParser Objects
      • 13.5.2 ExpatError 例外
      • 13.5.3 例
      • 13.5.4 内容モデルの記述
      • 13.5.5 Expat エラー定数
    • 13.6 xml.dom -- 文書オブジェクトモデル (DOM) API
      • 13.6.1 モジュールの内容
      • 13.6.2 DOM 内のオブジェクト
      • 13.6.3 適合性
    • 13.7 xml.dom.minidom -- 軽量な DOM 実装
      • 13.7.1 DOM オブジェクト
      • 13.7.2 DOM の例
      • 13.7.3 minidom と DOM 標準
    • 13.8 xml.dom.pulldom -- 部分的な DOM ツリー構築のサポート
      • 13.8.1 DOMEventStream オブジェクト
    • 13.9 xml.sax -- SAX2 パーサのサポート
      • 13.9.1 SAXException オブジェクト
    • 13.10 xml.sax.handler -- SAX ハンドラの基底クラス
      • 13.10.1 ContentHandler オブジェクト
      • 13.10.2 DTDHandler オブジェクト
      • 13.10.3 EntityResolver オブジェクト
      • 13.10.4 ErrorHandler オブジェクト
    • 13.11 xml.sax.saxutils -- SAX ユーティリティ
    • 13.12 xml.sax.xmlreader -- XML パーサのインターフェース
      • 13.12.1 XMLReader オブジェクト
      • 13.12.2 IncrementalParser オブジェクト
      • 13.12.3 Locator オブジェクト
      • 13.12.4 InputSource オブジェクト
      • 13.12.5 The Attributes インターフェース
      • 13.12.6 AttributesNS インターフェース
    • 13.13 xmllib -- XML ドキュメントのパーサ
      • 13.13.1 XML 名前空間
  • 14. マルチメディアサービス
    • 14.1 audioop -- 生のオーディオデータの操作
    • 14.2 imageop -- 生の画像データを操作する
    • 14.3 aifc -- AIFFおよびAIFCファイルの読み書き
    • 14.4 sunau -- Sun AUファイルの読み書き
      • 14.4.1 AU_read オブジェクト
      • 14.4.2 AU_write オブジェクト
    • 14.5 wave -- WAVファイルの読み書き
      • 14.5.1 Wave_read オブジェクト
      • 14.5.2 Wave_write オブジェクト
    • 14.6 chunk -- IFFチャンクデータの読み込み
    • 14.7 colorsys -- 色体系間の変換
    • 14.8 rgbimg -- ``SGI RGB''ファイルを読み書きする
    • 14.9 imghdr -- 画像の形式を決定する
    • 14.10 sndhdr -- サウンドファイルの識別
    • 14.11 ossaudiodev -- OSS互換オーディオデバイスへのアクセス
      • 14.11.1 オーディオデバイスオブジェクト
      • 14.11.2 ミキサーデバイスオブジェクト
  • 15. 暗号関連のサービス
    • 15.1 hmac -- メッセージ認証のための鍵付きハッシュ化
    • 15.2 md5 -- MD5 メッセージダイジェストアルゴリズム
    • 15.3 sha -- SHA-1 メッセージダイジェストアルゴリズム
    • 15.4 mpz -- GNU 多倍長整数
    • 15.5 rotor -- エニグマ暗号機のような暗号化と復号化
  • 16. Tkを用いたグラフィカルユーザインターフェイス
    • 16.1 Tkinter -- Tcl/TkへのPythonインターフェイス
      • 16.1.1 Tkinterモジュール
      • 16.1.2 Tkinter Life Preserver
      • 16.1.3 Tcl/Tkに(非常に)さっと目を通す
      • 16.1.4 基本的なTkをTkinterへマッピングする
      • 16.1.5 TkとTkinterはどのように関係なのか
      • 16.1.6 便利なリファレンス
    • 16.2 Tix -- Tkの拡張ウィジェット
      • 16.2.1 Tixを使う
      • 16.2.2 Tixウィジェット
      • 16.2.3 Tixコマンド
    • 16.3 ScrolledText -- スクロールするテキストウィジェット
    • 16.4 turtle -- Tkのためのタートルグラフィックス
      • 16.4.1 PenとRawPenオブジェクト
    • 16.5 Idle
      • 16.5.1 メニュー
      • 16.5.2 基本的な編集とナビゲーション
      • 16.5.3 構文の色づけ
    • 16.6 他のグラフィカルユーザインターフェイスパッケージ
  • 17. 制限実行 (restricted execution)
    • 17.1 rexec -- 制限実行のフレームワーク
      • 17.1.1 RExec オブジェクト
      • 17.1.2 制限された環境を定義する
      • 17.1.3 例
    • 17.2 Bastion -- オブジェクトに対するアクセスの制限
  • 18. Python言語サービス
    • 18.1 parser -- Python解析木にアクセスする
      • 18.1.1 ASTオブジェクトを作成する
      • 18.1.2 ASTオブジェクトを変換する
      • 18.1.3 ASTオブジェクトに対する問い合わせ
      • 18.1.4 例外とエラー処理
      • 18.1.5 ASTオブジェクト
      • 18.1.6 例
    • 18.2 symbol -- Python解析木と共に使われる定数
    • 18.3 token -- Python解析木と共に使われる定数
    • 18.4 keyword -- Pythonキーワードチェック
    • 18.5 tokenize -- Pythonソースのためのトークナイザ
    • 18.6 tabnanny -- あいまいなインデントの検出
    • 18.7 pyclbr -- Python クラスブラウザーサポート
      • 18.7.1 クラス記述オブジェクト
      • 18.7.2 関数記述オブジェクト (Function Descriptor Object)
    • 18.8 py_compile -- Pythonソースファイルのコンパイル
    • 18.9 compileall -- Pythonライブラリをバイトコンパイル
    • 18.10 dis -- Pythonバイトコードの逆アセンブラ
      • 18.10.1 Pythonバイトコード命令
    • 18.11 distutils -- Python モジュールの構築とインストール
  • 19. Python コンパイラパッケージ
    • 19.1 基本的なインターフェイス
    • 19.2 制限
    • 19.3 Python 抽象構文
      • 19.3.1 AST ノード
      • 19.3.2 代入ノード
      • 19.3.3 サンプル
    • 19.4 Visitor を使って AST をわたり歩く
    • 19.5 バイトコード生成
  • 20. SGI IRIX 特有のサービス
    • 20.1 al -- SGIのオーディオ機能
      • 20.1.1 コンフィギュレーションオブジェクト
      • 20.1.2 ポートオブジェクト
    • 20.2 AL -- alモジュールで使われる定数
    • 20.3 cd -- SGIシステムのCD-ROMへのアクセス
      • 20.3.1 プレーヤーオブジェクト
      • 20.3.2 パーザオブジェクト
    • 20.4 fl -- グラフィカルユーザーインターフェースのためのFORMSライブラリ
      • 20.4.1 flモジュールに定義されている関数
      • 20.4.2 フォームオブジェクト
      • 20.4.3 FORMSオブジェクト
    • 20.5 FL -- flモジュールで使用される定数
    • 20.6 flp -- 保存されたFORMSデザインをロードする関数
    • 20.7 fm -- Font Manager インターフェース
    • 20.8 gl -- Graphics Library インターフェース
    • 20.9 DEVICE -- glモジュールで使われる定数
    • 20.10 GL -- glモジュールで使われる定数
    • 20.11 imgfile -- SGI imglib ファイルのサポート
    • 20.12 jpeg -- JPEGファイルの読み書きを行う
  • 21. SunOS 特有のサービス
    • 21.1 sunaudiodev -- Sunオーディオハードウェアへのアクセス
      • 21.1.1 オーディオデバイスオブジェクト
    • 21.2 SUNAUDIODEV -- sunaudiodevで使われる定数
  • 22. MS Windows 特有のサービス
    • 22.1 msvcrt - MS VC++実行時システムの有用なルーチン群
      • 22.1.1 ファイル操作関連
      • 22.1.2 コンソール I/O 関連
      • 22.1.3 その多の関数
    • 22.2 _winreg - Windows レジストリへのアクセス
      • 22.2.1 レジストリハンドルオブジェクト
    • 22.3 winsound -- Windows 用の音声再生インタフェース
  • A. ドキュメント化されていないモジュール
    • A.1 フレームワーク
    • A.2 雑多な有用ユーティリティ
    • A.3 プラットフォーム特有のモジュール
    • A.4 マルチメディア関連
    • A.5 撤廃されたもの
    • A.6 SGI 特有の拡張モジュール
  • B. バグ報告
  • C. 歴史とライセンス
    • C.1 History of the software
    • C.2 Terms and conditions for accessing or otherwise using Python
  • D. 日本語訳について
    • D.1 このドキュメントについて
    • D.2 翻訳者一覧 (敬称略)
  • Module Index
  • 索引
  • この文書について...
Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Up: Python ドキュメントインデクス Next: 序


1. はじめに

この ``Python ライブラリ'' には様々な内容が収録されています。

このライブラリには、数値型やリスト型のような、通常は言語の``核'' をなす部分とみなされるデータ型が含まれています。Python 言語のコア 部分では、これらの型に対してリテラル表現形式を与え、意味づけ上の いくつかの制約を与えていますが、完全にその意味づけを定義している わけではありません。(一方で、言語のコア部分では演算子のスペルや 優先順位のような構文法的な属性を定義しています。) 　 このライブラリにはまた、組み込み関数と例外が納められています -- 組み込み関数および例外は、全ての Python で書かれたコード上で、 import 文を使わずに使うことができるオブジェクトです。 これらの組み込み要素のうちいくつかは言語のコア部分で定義されて いますが、大半は言語コアの意味づけ上不可欠なものではないので ここでしか記述されていません。

とはいえ、このライブラリの大部分に収録されているのはモジュールの コレクションです。このコレクションを細分化する方法はいろいろあります。 あるモジュールは C 言語で書かれ、Python インタプリタに組み 込まれています; 一方別のモジュールは Python で書かれ、ソースコードの 形式で取り込まれます。またあるモジュールは、例えば実行スタックの追跡 結果を出力するといった、Python に非常に特化したインタフェースを提供 し、一方他のモジュールでは、特定のハードウェアにアクセスするといった、 特定のオペレーティングシステムに特化したインタフェースを提供 し、さらに別のモジュールでは WWW (ワールドワイドウェブ) のような特定のアプリケーション分野に特化したインタフェースを 提供しています。モジュールによっては全てのバージョン、全ての 移植版の Python で利用することができたり、背後にあるシステムが サポートしている場合にのみ使えたり、Python をコンパイルして インストールする際に特定の設定オプションを選んだときにのみ 利用できたりします。

このマニュアルの構成は ``内部から外部へ:'' つまり、最初に 組み込みのデータ型を記述し、組み込みの関数および例外、 そして最後に各モジュールといった形になっています。モジュール は関係のあるものでグループ化して一つの章にしています。 章の順番付けや各章内のモジュールの順番付けは、大まかに重要性の 高いものから低いものになっています。

つまり、このマニュアルを最初から読み始め、読み飽き始めた ところで次の章に進めば、Python ライブラリで利用できるモジュールや サポートしているアプリケーション領域の概要をそこそこ理解できる ということです。 もちろん、このマニュアルを小説のように読む必要はありません -- (マニュアルの先頭部分にある) 目次にざっと目を通したり、 (最後尾にある) 索引でお目当ての関数やモジュール、用語を探す ことだってできます。もしランダムな項目について勉強してみたいの なら、ランダムにページを選び (random 参照)、そこから 1, 2 節読むこともできます。このマニュアルの各節をどんな順番で 読むかに関わらず、第 2 章、 ``組み込み型、例外、および 関数'' から始めるとよいでしょう。マニュアルの他の部分は、 この節の内容について知っているものとして書かれているからです。

それでは、ショーの始まりです！

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 目次 Up: Python ライブラリリファレンス Next: 2. 組み込みオブジェクト


2. 組み込みオブジェクト

組み込み例外名、関数名、各種定数名は専用のシンボルテーブル中に存在しています。 シンボル名を参照するときこのシンボルテーブルは最後に参照されるので、 ユーザーが設定したローカルな名前やグローバルな名前によってオーバーライド することができます。 組み込み型については参照しやすいようにここで説明されています。2.1

この章にある表では、オペレータの優先度を昇順に並べて表わしていて、 同じ優先度のオペレータは同じ箱に入れています。同じ優先度の二項演算子は左 から右への結合順序を持っています。(単項演算子は右から左へ結合しますが選択 の余地はないでしょう。) 2.2オペレータの優先順位についての詳細はPython Reference Manualの5章をごらんください。

... 組み込み型については参照しやすいようにここで説明されています。2.1
ほとんどの説明ではそこで発生しうる例外については説明されていません。この マニュアルの将来の版で訂正される予定です。
... の余地はないでしょう。)2.2
訳者註: HTML版では、変換の過程で 表の区切り情報が消えてしまっているので、PS版やPDF版をごらんください。

  • 2.1 組み込み関数
  • 2.2 非必須組み込み関数 (Non-essential Built-in Functions)
  • 2.3 組み込み型
    • 2.3.1 真値テスト
    • 2.3.2 ブール演算
    • 2.3.3 比較
    • 2.3.4 数値型
      • 2.3.4.1 整数型におけるビット文字列演算
    • 2.3.5 イテレータ型
    • 2.3.6 配列型
      • 2.3.6.1 文字列メソッド
      • 2.3.6.2 文字列フォーマット操作
      • 2.3.6.3 XRange 型
      • 2.3.6.4 変更可能な配列型
    • 2.3.7 マップ型
    • 2.3.8 ファイルオブジェクト
    • 2.3.9 他の組み込み型
      • 2.3.9.1 モジュール
      • 2.3.9.2 クラスおよびクラスインスタンス
      • 2.3.9.3 関数
      • 2.3.9.4 メソッド
      • 2.3.9.5 コードオブジェクト
      • 2.3.9.6 型オブジェクト
      • 2.3.9.7 ヌルオブジェクト
      • 2.3.9.8 省略表記オブジェクト
      • 2.3.9.9 ブール値
      • 2.3.9.10 内部オブジェクト
    • 2.3.10 特殊な属性
  • 2.4 組み込み例外
  • 2.5 組み込み定数
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 1. はじめに Up: Python ライブラリリファレンス Next: 2.1 組み込み関数


2.1 組み込み関数

Python インタプリタは数多くの組み込み関数を持っていて、いつでも利用 することができます。それらの関数をアルファベット順に挙げます。

__import__( name[, globals[, locals[, fromlist]]])
この関数は import 文によって呼び出され ます。この関数の主な意義は、同様のインタフェースを持つ関数で この関数を置き換え、import 文の意味を変更できるように することです。これを行う理由とやり方の例については、標準ライブラリ モジュール ihooksおよび rexecを読んで下さい。また、 組み込みモジュール impについても 読んでみて下さい。自分で関数 __import__ を構築する 際に便利な操作が定義されています。

例えば、文 "import spam" は結果として以下の呼び出し: __import__('spam', globals(), locals(), []) になります; 文 "from spam.ham import eggs" は "__import__('spam.ham', globals(), locals(), ['eggs'])" です。 locals() および ['eggs'] が引数で与えられますが、 関数 __import__() は eggs という名のローカル変数 を設定しないので注意してください; この操作はそれ以後の import 文の ために生成されたコードで行われます。(実際、標準の実装では locals 引数を全く使わず、import 文のパッケージ文脈を決定するため だけに globals を使います。)

変数 name が package.module の形式であった場合、 通常、name という名のモジュール ではなく トップレベルの パッケージ (最初のドットまでの名前) が返されます。しかし、 空でない fromlist 引数が与えられていれば、name と名づけられたモジュールが返されます。これは異なる種類の import 文に対して生成されたバイトコードと互換性をもたせるために行われます; "import spam.ham.eggs" とすると、トップレベルのパッケージ spam はインポートする名前空間に置かれなければなりませんが、 "from spam.ham import eggs" とすると、変数 eggs を 見つけるためには spam.ham サブパッケージを使わなくては なりません。この振る舞いを回避するために、getattr() を 使って必要なコンポーネントを展開してください。例えば、 以下のようなヘルパー関数:

def my_import(name):
    mod = __import__(name)
    components = name.split('.')
    for comp in components[1:]:
        mod = getattr(mod, comp)
    return mod

を定義することができます。

abs( x)
数値の絶対値を返します。引数として通常の整数、長整数、浮動小数点数を とることができます。引数が複素数の場合、その大きさ (magnitude) が 返されます

basestring( )
この抽象型は、 str および unicode のスーパクラスです。 この型は呼び出したりインスタンス化したりはできませんが、オブジェクトが str や unicode のインスタンスであるかどうかを調べる際に 利用できます。 isinstance(obj, basestring) は isinstance(obj, (str, unicode)) と同じです。 バージョン2.3 以降で新規追加された 仕様です。

bool( [x])
標準の真値テストを使って、値をブール値に変換します。x が偽なら、False を返します; そうでなければ True を返します。bool はクラスでも あり、int のサブクラスになります。bool クラスは それ以上サブクラス化できません。このクラスのインスタンス はFalse および True　だけです。

バージョン2.2.1 以降で新規追加された 仕様です。

バージョン2.3 以降で変更された 仕様: 引数が与えられなかった場合、この関数は False を返 します。

callable( object)
object 引数が呼び出し可能なオブジェクトの場合、真を返します。 そうでなければ偽を返します。この関数が真を返しても object の呼び出しは失敗する可能性がありますが、偽を返した場合は決して 成功することはありません。クラスは呼び出し可能 (クラスを呼び出すと 新しいインスタンスを返します) なことと、クラスのインスタンスが メソッド __call__() を持つ場合には呼び出しが可能なので 注意してください。

chr( i)
ASCII コードが整数 i となるような文字 1 字からなる文字列を 返します。例えば、chr(97) は文字列 'a' を返します。 この関数は ord() の逆です。引数は [0..255] の両端を含む 範囲内に収まらなければなりません; i が範囲外の値のときには ValueError が送出されます。

classmethod( function)
function のクラスメソッドを返します。

クラスメソッドは、インスタンスメソッドが暗黙の第一引数として インスタンスをとるように、第一引数としてクラスをとります。 クラスメソッドを宣言するには、以下の書きならわしを使います:

class C:
    def f(cls, arg1, arg2, ...): ...
    f = classmethod(f)

このメソッドはクラスで呼び出すこと (例えば C.f() ) も、 インスタンスとして呼び出すこと (例えば C().f()) もできます。 インスタンスはそのクラスが何であるかを除いて無視されます。 クラスメソッドが導出クラスに対して呼び出された場合、 導出されたクラスオブジェクトが暗黙の第一引数として渡されます。

クラスメソッドは C++ や Java における静的メソッドとは異なります。 そのような機能を求めているなら、staticmethod() を参照してくだ さい。 バージョン2.2 以降で新規追加された 仕様です。

cmp( x, y)
二つのオブジェクト x および y を比較し、その結果に従って 整数を返します。戻り値は x < y のときには負、 x == y の時にはゼロ、x > y には 厳密に正の値になります。

compile( string, filename, kind[, flags[, dont_inherit]])
string をコードオブジェクトにコンパイルします。コードオブジェクト は exec 文で実行したり、 eval() を呼び出して 評価することができます。filename 引数はコードを読み出すファイル を指定します; ファイルから読み出されない場合には、認識可能な ある値を渡します (一般的には '<string>' が使われます)。 引数 kind には、この種類のコードをコンパイルしなければ ならないのかを指定します; string が命令文の列からなる場合には 'exec' を、単一の式からなる場合には 'eval' が、 単一の対話命令文からなる場合には 'single' にします (後者の例では、評価する何らかの式が None 以外の場合には その式が出力されます) 。

複数行の命令文をコンパイルする時には、2 つの注意点があります: 行末は単一の改行文字 ('\n') で表さなければなりません。 また、入力行は少なくとも 1 つの改行文字で終端されていなければ なりません。行末が '\r\n' で表現されている場合、 文字列に replace() メソッドを使って '\n' に変換してください。

オプションの引数 flags および dont_inherit (Python 2.2 で新たに追加) は、 string のコンパイル においてどの future 文 (PEP 236 参照) が影響を受けるか を制御します。どちらも省略された場合 (または両方ともゼロの場合)、 コンパイルを呼び出している側のコードで有効になっている future 文 の内容を有効にして string をコンパイルします。 flags が与えられており、かつ dont_inherit が与えられて いない (またはゼロ) の場合、上の場合に加えて flags に指定 された future 文が使われます。dont_inherit がゼロでない整数で flags はその値になります - この関数呼び出しに関係する future 文は無視されます。

future 文はビットで指定され、互いにビット単位の論理和を取ることで 複数の文を指定することができます。ある機能を指定するために必要な ビットフィールドは、__future__ モジュールの _Feature インスタンスにおける compiler_flag 属性で得ることができます。

complex( [real[, imag]])
値 real + imag*j の複素数型数を生成するか、文字列または 数値を複素数型に変換します。最初の引数が文字列の場合、文字列を 複素数として変換します。この場合関数は二つ目の引数無しで呼び出さ なければなりません。二つ目の引数は文字列であってはなりません。 それぞれの引数は (複素数を含む) 任意の数値型をとることができます。 imag が省略された場合、標準の値はゼロで、関数は int 、 long() および float() のような数値型への 変換関数として動作します。 全ての引数が省略された場合、0j を返します。

delattr( object, name)
setattr() の親戚となる関数です。引数はオブジェクトと 文字列です。文字列はオブジェクトの属性のどれか一つの名前でなければ なりません。この関数は与えられた名前の属性を削除しますが、オブジェクト がそれを許す場合に限ります。例えば、 delattr(x, 'foobar') は del x.foobar と等価です。

dict( [mapping-or-sequence])
オプションの場所にある引数か、キーワード引数の集合から、 新しく辞書オブジェクトを初期化して返します。 引数が指定されていなければ、新しい空の辞書を返します。 オプションの場所にある引数がマップ型のオブジェクトの場合、 そのマップ型オブジェクトと同じキーと値を持つ辞書を返します。 それ以外の場合、オプションの場所にある引数は配列型か、 反復をサポートするコンテナ型か、イテレータオブジェクトでなければなりません。 この場合引数中の要素もまた、上に挙げた型のどれかでなくてはならず、 加えて正確に 2 個のオブジェクトを持っていなくてはなりません。 最初の要素は新たな辞書のキーとして、二つ目の要素は辞書の値として 使われます。同じキーが一度以上与えられた場合、新たな辞書中には 最後に与えた値だけが関連付けられます。

キーワード引数が与えられた場合、キーワードとそれに関連付けられた 値が辞書の要素として追加されます。オプションの場所にある オブジェクト内とキーワード引数の両方で同じキーが指定されていた場合、 辞書中にはキーワード引数の設定値の方が残されます。

例えば、以下のコードはどれも、{"one": 2, "two": 3} と同じ辞書を返します:

  • dict({'one': 2, 'two': 3})
  • dict({'one': 2, 'two': 3}.items())
  • dict({'one': 2, 'two': 3}.iteritems())
  • dict(zip(('one', 2), ('two', 3)))
  • dict([['two', 3], ['one', 2]])
  • dict(one=2, two=3)
  • dict([(['one', 'two'][i-2], i) for i in (2, 3)])

バージョン2.2 以降で新規追加された 仕様です。 バージョン2.3 以降で変更された 仕様: キーワード引数から辞書を構築する機能が追加されました

dir( [object])
引数がない場合、現在のローカルシンボルテーブルにある名前のリストを 返します。引数がある場合、そのオブジェクトの有効な属性からなるリスト を返そうと試みます。この情報はオブジェクトの __dict__ 属性が定義されている場合、そこから収集されます。また、 クラスまたは型オブジェクトからも集められます。リストは完全なものに なるとは限りません。 オブジェクトがモジュールオブジェクトの場合、リストにはモジュール属性 の名前も含まれます。 オブジェクトが型オブジェクトやクラスオブジェクトの場合、 リストにはそれらの属性が含まれ、かつそれらの基底クラスの属性も 再帰的にたどられて含まれます。 それ以外の場合には、リストにはオブジェクトの属性名、クラス属性名、 再帰的にたどった基底クラスの属性名が含まれます。 返されるリストはアルファベット順に並べられています。 例えば:

>>> import struct
>>> dir()
['__builtins__', '__doc__', '__name__', 'struct']
>>> dir(struct)
['__doc__', '__name__', 'calcsize', 'error', 'pack', 'unpack']

注意: dir() は第一に対話プロンプトのために提供されているので、 厳密さや一貫性をもって定義された名前のセットよりも、むしろ興味深い名前 のセットを与えようとします。また、この関数の細かい動作はリリース間で 変わる可能性があります。

divmod( a, b)
2 つの (複素数でない) 数値を引数として取り、長除法を行って その商と剰余からなるペアを返します。被演算子が型混合である場合、 2 進算術演算子での規則が適用されます。通常の整数と長整数の場合、 結果は (a / b, a % b) と同じ です。浮動小数点数の場合、結果は (q, a % b) であり、 q は通常 math.floor(a / b) ですが、 そうではなく 1 になることもあります。 いずれにせよ、q * b + a % b は a に非常に近い値になり、 a % b がゼロでない値の場合、その符号は b と同じで、 0 <= abs(a % b) < abs(b) になります。

バージョン2.3 以降で変更された 仕様: 複素数に対する divmod() の使用は廃用されました。

enumerate( iterable)
列挙オブジェクトを返します。iterable は配列型、イテレータ型、 あるいは反復をサポートする他のオブジェクト型でなければなりません。 enumerate() が返すイテレータの next() メソッドは、 (ゼロから始まる) カウント値と、値だけ iterable を反復操作して 得られる、対応するオブジェクトを含むタプルを返します。 enumerate() はインデクス付けされた値の列: (0, seq[0]), (1, seq[1]), (2, seq[2]), ... を得るのに便利です。 バージョン2.3 以降で新規追加された 仕様です。

eval( expression[, globals[, locals]])
引数は文字列とオプションの 2 つの辞書からなります。引数 expression は Python の表現式 (技術的にいうと、条件のリストです) として構文解釈され、 評価されます。このとき辞書 globals および locals はそれぞれ グローバルおよびローカルな名前空間として使われます。 locals 辞書が存在するが、'__builtins__' が欠けている場合、 expression を解析する前に現在のグローバル変数を globals にコピーします。このことから、expression は通常 標準の __builtin__ モジュールへの完全なアクセス を有し、制限された環境が伝播するようになっています。 locals 辞書が省略された場合、標準の値として globals に 設定されます。辞書が両方とも省略された場合、表現式は eval が 呼び出されている環境の下で実行されます。構文エラーは例外として報告されます。

以下に例を示します:

>>> x = 1
>>> print eval('x+1')
2

この関数は (compile() で生成されるような) 任意の コードオブジェクトを実行するために利用することもできます。 この場合、文字列の代わりにコードオブジェクトを渡します。 このコードオブジェクトは引数 kind を 'eval' にして コンパイルされていなければなりません。

ヒント: 文の動的な実行は exec 文でサポートされています。 ファイルからの文の実行は関数 execfile() でサポートされて います。関数 globals() および locals() は それぞれ現在のグローバルおよびローカルな辞書を返すので、 eval() や execfile() で使うことができます。

execfile( filename[, globals[, locals]])
この関数は exec 文に似ていますが、文字列の代わりにファイルに 対して構文解釈を行います。import 文と違って、モジュール管理 機構を使いません -- この関数はファイルを無条件に読み込み、 新たなモジュールを生成しません。2.3

引数は文字列とオプションの 2 つの辞書からなります。file は読み込まれ、(モジュールのように) Python 文の配列として評価されます。 このとき globals および locals がそれぞれグローバル およびローカルな名前空間として使われます。locals 辞書が 省略された場合、標準の値として globals に設定されます。辞書が 両方とも省略された場合、表現式は execfiles が呼び出されている 環境の下で実行されます。戻り値は None です。

警告: 標準では locals は後に述べる関数 locals() のように動作します: 標準の locals 辞書に対する変更を試みては いけません。execfile() の呼び出しが返る時にコードが locals に与える影響を知りたいなら、明示的に loacals 辞書を 渡してください。execfile() は関数のローカルを変更するための 信頼性のある方法として使うことはできません

file( filename[, mode[, bufsize]])
新たなファイルオブジェクト (前の組み込み型の節で説明されています) を返します。最初の 2 つの引数は studio の fopen() と同じです: filename は開きたいファイルの名前で、 mode はファイルをどのようにして開くかを指定します: 読み出しは 'r'、書き込み (ファイルがすでに存在すれば切り詰め られます) は 'w'、追記書き込みは 'a' です (いくつかの Unix システムでは、全て の書き込みが 現在のファイルシーク位置に関係なくファイルの末尾に追加されます) 。

'r+'、'w+'、および 'a+' はファイルを更新 モードで開きます ('w+' はファイルがすでに存在すれば切り詰め るので注意してください) 。バイナリとテキストファイルを区別する システムでは、ファイルをバイナリモードで開くためには 'b' を追加してください (区別しないシステムでは 'b' は無視されます)。 ファイルを開くことができなければ、IOError が送出されます。

標準の fopen() における mode の値に加えて、 'U' または 'rU' を使うことができます。 Python が全改行文字サポートを行っている (標準ではしています)　場合, ファイルがテキストファイルで開かれますが、行末文字として Unix における 慣行である '\n' 、Machintosh における慣行である '\r'、 Windows における慣行である '\r\n' のいずれを使うことも できます。これらの改行文字の外部表現はどれも、Python プログラムからは '\n' に見えます。Python が全改行文字サポートなしで構築 されている場合、mode 'U' は通常のテキストモードと 同様になります。開かれたファイルオブジェクトはまた、newlines と呼ばれる属性を持っており、その値は None (改行が見つから なかった場合)、'\n'、'\r'、 '\r\n'、 または見つかった全ての改行タイプを含むタプルになります。

mode が省略された場合、標準の値は 'r' になります。 移植性を高めるためには、バイナリファイルを開くときには、mode の値に 'b' を追加しなければなりません。(バイナリファイルと テキストファイルを区別なく扱うようなシステムでも、ドキュメンテーション の代わりになるので便利です) オプションの bufsize 引数は、ファイルのために必要とする バッファのサイズを指定します: 0 は非バッファリング、 1 は行単位 バッファリング、その他の正の値は指定した値 (の近似値) のサイズを もつバッファを使用することを意味します。bufsize の値が負の 場合、システムの標準を使います。通常、端末は行単位のバッファリング であり、その他のファイルは完全なバッファリングです。省略された 場合、システムの標準の値が使われます。 2.4

file() コンストラクタは Python 2.2 で新たに追加されました。
以前の関数名である open() は互換性のために残されており、
file() の別名となっています。

filter( function, list)
list のうち、function が真を返すような要素からなる リストを構築します。list は配列か、反復をサポートするコンテナか、 イテレータです。list が文字列型かタプル型の場合、結果も同じ型に なります。function が None の場合、恒等関数を仮定 します。すなわち、list の偽となる要素 (ゼロまたは空) は除去されます。

function が None ではない場合、filter(function, list) は [item for item in list if function(item)] と同等です。 function が None の場合 [item for item in list if item] と同等です。

float( [x])
文字列または数値を浮動小数点数に変換します。引数が文字列の場合、 十進の数または浮動小数点数を含んでいなければなりません。符号が 付いていてもかまいません。また、空白文字中に埋め込まれていても かまいません; これは string.atof(x) と同様の動作 です。それ以外の場合、引数は通常整数、長整数、または浮動小数点 数をとることができ、同じ値の浮動小数点数が (Python の浮動小数点 精度で) 返されます。 引数が指定されなかった場合、0.0 を返します。

注意: 文字列で値を渡す際、背後の C ライブラリによって NaNおよび Infinityが返されるかもしれません。これらの 値を返すような特殊な文字列のセットは完全に C ライブラリに依存しており、 バリエーションがあることが知られています。

getattr( object, name[, default])
指定された object の属性を返します。name は文字列で なくてはなりません。文字列がオブジェクトの属性名の一つであった 場合、戻り値はその属性の値になります。例えば、 getattr(x, 'foobar') は x.foobar と等価です。 指定された属性が存在しない場合、default が与えられている 場合にはしれが返されます。そうでない場合には AttributeError が送出されます。

globals( )
現在のグローバルシンボルテーブルを表す辞書を返します。 常に現在のモジュールの辞書になります (関数またはメソッドの中では それらを定義しているモジュールを指し、この関数を呼び出したモジュール ではありません)。

hasattr( object, name)
引数はオブジェクトと文字列です。文字列がオブジェクトの属性名の一つ であった場合 1 を、そうでない場合 0 を返します (この関数は getattr(object, name) を呼び出し、 例外を送出するかどうかを調べることで実装しています)。

hash( object)
オブジェクトのハッシュ値を (存在すれれば) 返します。ハッシュ値は 整数です。これらは辞書を検索する際に辞書のキーを高速に比較するために 使われます。等しい値となる数値は等しいハッシュ値を持ちます (1 と 1.0 のように型が異なっていてもです)。

help( [object])
組み込みヘルプシステムを起動します (この関数は対話的な使用のための ものです)。引数が与えられていない場合、対話的ヘルプシステムは インタプリタコンソール上で起動します。引数が文字列の場合、文字列は モジュール、関数、クラス、メソッド、キーワード、またはドキュメント の項目名として検索され、ヘルプページがコンソール上に印字されます。 引数が何らかのオブジェクトの場合、そのオブジェクトに関するヘルプ ページが生成されます。 バージョン2.2 以降で新規追加された 仕様です。

hex( x)
(任意のサイズの) 整数 を16進の文字列に変換します。結果は Python で 有効な表現になります。注意: 値は常に符号無しのリテラルになります。 例えば、 32 ビットのマシンでは、hex(-1) は '0xffffffff' になります。同じワードサイズを持つ計算機で評価された場合、この 文字列は -1 になります; 異なるワードサイズの計算機では、巨大な 正の値に折り返されたり、例外 OverflowError を送出 するかもしれません。

id( object)
オブジェクトの '識別値' を返します。この値は整数 (または長整数) で、このオブジェクトの有効期間は一意かつ定数であることが保証されて います。 オブジェクトの有効期間が重ならない 2 つのオブジェクトは 同じ id() 値を持つかもしれません。 (実装に関する注釈: この値はオブジェクトのアドレスです。)

input( [prompt])
eval(raw_input(prompt)) と同じです。 警告: この関数はユーザのエラーに対して安全ではありません! この関数 では、入力は有効な Python の式であると期待しています; 入力が 構文的に正しくない場合、SyntaxError が送出されます。 式を評価する際にエラーが生じた場合、他の例外も送出されるかもしれません。 (一方、この関数は時に、熟練者がすばやくスクリプトを書く際に必要なまさに そのものです)

readline モジュールが読み込まれていれば、input() は精緻な行編集およびヒストリ機能を提供します。

一般的なユーザからの入力のための関数としては raw_input() を使うことを検討してください。

int( [x[, radix]])
文字列または数値を通常の整数に変換します。引数が文字列の場合、 Python 整数として表現可能な十進の数でなければなりません。 符号が付いていてもかまいません。また、空白文字中に埋め込まれていても かまいません。radix 引数は変換の基数を表し、範囲 [2, 36] の 整数またはゼロをとることができます。radix がゼロの場合、文字列の 内容から適切な基数を推測します; 変換は整数リテラルと同じです。 radix が指定されており、x が文字列でない場合、 TypeError が送出されます。 それ以外の場合、引数は通常整数、長整数、または浮動小数点 数をとることができます。浮動小数点数から整数へ変換では (ゼロ方向に) 値を丸めます。 引数が通常整数の範囲を超えている場合、長整数が代わりに返されます。 引数が与えられなかった場合、0 を返します。

isinstance( object, classinfo)
引数 object が引数 classinfo のインスタンスであるか、 (直接または間接的な) サブクラスのインスタンスの場合に真を返します。 また、classinfo が型オブジェクトであり、object がその 型のオブジェクトである場合にも真を返します。object が クラスインスタンスや与えられた型のオブジェクトでない場合、 この関数は常に偽を返します。classinfo をクラスオブジェクト でも型オブジェクトにもせず、クラスや型オブジェクトからなる タプルや、そういったタプルを再帰的に含むタプル (他の配列型は 受理されません) でもかまいません。classinfo がクラス、型、 クラスや型からなるタプル、そういったタプルが再帰構造をとっている タプルのいじれでもない場合、例外 TypeError が送出 されます。 バージョン2.2 以降で変更された 仕様: 型情報をタプルにした形式のサポートが追加されました。

issubclass( class, classinfo)
class が classinfo の (直接または間接的な) サブクラスで ある場合に真を返します。クラスはそのクラス自体のサブクラスと clasinfo はクラスオブジェクトからなるタプルでもよく、 この場合には classinfo のすべてのエントリが調べ られます。その他の場合では、 例外 TypeError が送出されます。 バージョン2.3 以降で変更された 仕様: 型情報からなるタプルへのサポートが追加されました

iter( o[, sentinel])
イテレータオブジェクトを返します。2 つ目の引数があるかどうかで、 最初の引数の解釈は非常に異なります。2 つ目の引数がない場合、 o は反復プロトコル (__iter__() メソッド) か、 配列プロトコル (引数が 0 から開始する __getitem__() メソッド) をサポートする集合オブジェクト でなければなりません。これらのプロトコルが両方ともサポート されていない場合、 TypeError が送出されます。 2 つ目の引数 sentinel が与えられていれば、o は呼び出し可能なオブジェクトでなければなりません。この場合に 生成されるイテレータは、next() を呼ぶ毎に o を引数無し で呼び出します。返された値が sentinel と等しければ、 StopIteration が送出されます。そうでない場合、 戻り値がそのまま返されます。 バージョン2.2 以降で新規追加された 仕様です。

len( s)
オブジェクトの長さ (要素の数) を返します。引数は配列型 (文字列、 タプル、またはリスト) か、マップ型 (辞書) です。

list( [sequence])
sequence の要素と同じ要素をもち、かつ順番も同じなリストを 返します。sequence は配列、反復処理をサポートするコンテナ、 あるいはイテレータオブジェクトです。sequence がすでにリストの 場合、sequence[:] と同様にコピーを作成して返します。 例えば、list('abc') は ['a', 'b', 'c'] および list(1, 2, 3) は [1, 2, 3] を返します。 引数が与えられなかった場合、新しい空のリスト [] を返します。

locals( )
現在のローカルシンボルテーブルを表す辞書を更新して返します。 警告: この辞書の内容は変更してはいけません; 値を変更しても、 インタプリタが使うローカル変数の値には影響しません。

long( [x[, radix]])
文字列または数値を長整数値に変換します。引数が文字列の場合、 Python 整数として表現可能な十進の数でなければなりません。 符号が付いていてもかまいません。また、空白文字中に埋め込まれていても かまいません; これは string.atol(x) と同様の動作です。radix 引数は int() と同じように 解釈され、x が文字列の時だけ与えることができます。 それ以外の場合、引数は通常整数、長整数、または浮動小数点 数をとることができ、同じ値の長整数が返されます。浮動小数点数から 整数へ変換では (ゼロ方向に) 値を丸めます。 引数が与えられなかった場合、0L を返します。

map( function, list, ...)
function を list の全ての要素に適用し、返された 値からなるリストを返します。追加の list 引数を与えた場合、 function はそれらを引数として取らなければならず、関数は そのリストの全ての要素について個別に適用されます; 他のリストより 短いリストがある場合、要素 None で延長されます。function が None の場合、恒等関数であると仮定されます; すなわち、 複数のリスト引数が存在する場合、map() は全てのリスト引数に 対し、対応する要素からなるタプルからなるリストを返します (転置操作の ようなものです)。list 引数はどのような配列型でもかまいません; 結果は常にリストになります。

max( s[, args...])
単一の引数 s の場合、空でない配列 (文字列、タプルまたはリスト) の要素のうち最大のものを返します。1 個よりも引数が多い場合、引数 間で最大のものを返します。

min( s[, args...])
単一の引数 s の場合、空でない配列 (文字列、タプルまたはリスト) の要素のうち最小のものを返します。1 個よりも引数が多い場合、引数 間で最小のものを返します。

object( )
ユーザ定義の属性やメソッドを持たない、新しいオブジェクトを返します。 object() は新スタイルのクラスの、基底クラスです。これは、新ス タイルのクラスのインスタンスに共通のメソッド群を持ちます。 バージョン2.2 以降で新規追加された 仕様です。

バージョン2.3 以降で変更された 仕様: この関数はいかなる引数も受け付けません。 以前は、引数を受理しましたが無視していました。

oct( x)
(任意のサイズの) 整数を 8 進の文字列に変換します。結果は有効な Python の表現形式になります。注意: 値は常に符号無しのリテラルになります。 例えば、 32 ビットのマシンでは、oct(-1) は '037777777777' になります。同じワードサイズを持つ計算機で評価された場合、この 文字列は -1 になります; 異なるワードサイズの計算機では、巨大な 正の値に折り返されたり、例外 OverflowError を送出 するかもしれません。

open( filename[, mode[, bufsize]])
前述の関数 file() の別名です。

ord( c)
1 文字からなる文字列または Unicode 文字の ASCII 値を返します。
例えば、ord('a') は整数 97 を返し、
ord(u'\u2020') は 8224 を返します。この値は
文字列に対する chr() の逆であり、Unicode 文字に対する
unichr() の逆です。

pow( x, y[, z])
x の y 乗を返します; z があれば、 x の y 乗に対する z のモジュロを返します (pow(x, y)% z より効率よく計算 されます) 。引数は数値型でなくてはなりません。型混合の場合、 2 進算術演算における型強制規則が適用されます。通常整数 および長整数の被演算子に対しては、二つ目の引数が負の数でない 限り、結果は (型強制後の)被演算子と同じ型になります; 負の場合、全ての引数は浮動小数点型に変換され、浮動小数点 型の結果が返されます。例えば、 10**2 は 100 を返しますが、 100**-2 は 0.01 を返します。 (最後に述べた機能は Python 2.2 で追加されたものです。 Python 2.1 以前では、双方の引数が整数で二つ目の値が負の 場合、例外が送出されます。) 二つ目の引数が負の場合、 三つめの引数は無視されます。z がある場合、x および y は整数型でなければならず、y は非負 の値でなくてはなりません。(この制限は Python 2.2 で追加 されました。 Python 2.1 以前では、3 つの浮動小数点引数を 持つ pow() は浮動小数点の丸めに関する偶発誤差 により、プラットフォーム依存の結果を返します。)

property( [fget[, fset[, fdel[, doc]]]])
新しい形式のクラス (object から導出されたクラス) における プロパティ属性を返します。

fget は属性値を取得するための関数で、同様に fset は 属性値を設定するための関数です。また、fdel は属性を 削除するための関数です。以下に属性 x を扱う典型的な利用法を示します:

class C(object):
    def getx(self): return self.__x
    def setx(self, value): self.__x = value
    def delx(self): del self.__x
    x = property(getx, setx, delx, "I'm the 'x' property.")

バージョン2.2 以降で新規追加された 仕様です。

range( [start,] stop[, step])
数列を含むリストを生成するための多機能関数です。for ループでよく使われます。引数は通常の整数でなければなりません。 step 引数が無視された場合、標準の値 1 になります。 start 引数が蒸しされた場合標準の値 0 になります。 完全な形式では、通常の整数列 [start, start + step, start + 2 * step, ...] を返します。 step が正の値の場合、最後の要素は stop よりも小さい start + i * step の最大値になります; step が負の値の場合、最後の要素は stop よりも大きい start + i * step の最小値になります。 step はゼロであってはなりません (さもなければ ValueError が送出されます)。以下に例を示します:

>>> range(10)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> range(1, 11)
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> range(0, 30, 5)
[0, 5, 10, 15, 20, 25]
>>> range(0, 10, 3)
[0, 3, 6, 9]
>>> range(0, -10, -1)
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
>>> range(0)
[]
>>> range(1, 0)
[]

raw_input( [prompt])
引数 proompt が存在する場合、末尾の改行を除いて標準出力に出力 されます。次に、この関数は入力から 1 行を読み込んで文字列に変換して (末尾の改行を除いて) 返します。EOF が読み込まれると EOFError が送出されます。以下に例を示します:

>>> s = raw_input('--> ')
--> Monty Python's Flying Circus
>>> s
"Monty Python's Flying Circus"

readline モジュールが読み込まれていれば、input() は精緻な行編集およびヒストリ機能を提供します。

reduce( function, sequence[, initializer])
sequence の要素に対して、配列を単一の値に短縮するような形で 2 つの引数をもつ function を左から右に累積的に適用します。 例えば、reduce(labmda x, y: x+y, [1, 2, 3, 4, 5]) は ((((1+2)+3)+4)+5) を計算します。左引数x は累計の値になり、右引数 y はsequence から取り出した 更新値になります。オプションの initializer が存在する場合、計算の際に配列の先頭に置かれます。また、 配列が空の場合には標準の値になります。initializer が与えられて おらず、sequence が単一の要素しか持っていない場合、 最初の要素が返されます。

reload( module)
すでにインポートされた module を再解釈し、再初期化します。 引数はモジュールオブジェクトでなければならないので、予めインポート に成功していなければなりません。この関数はモジュールのソースコード ファイルを外部エディタで編集して、Python インタプリタから 離れることなく新しいバージョンを試したい際に有効です。 戻り値は (module 引数と同じ) モジュールオブジェクトです。

いくつか補足説明があります:

モジュールは文法的に正しいが、その初期化には失敗した場合、 そのモジュールの最初の import 文はモジュール名を ローカルにはバインドしませんが、(部分的に初期化された) モジュール オブジェクトを sys.modules に記憶します。従って、モジュールを ロードしなおすには、reload() する前にまず import (モジュールの名前を部分的に初期化されたオブジェクトにバインドします) を再度行わなければなりません。

モジュールが再ロードされた再、その辞書 (モジュールのグローバル変数を 含みます) はそのまま残ります。名前の再定義を行うと、以前の定義を 上書きするので、一般的には問題はありません。新たなバージョンのモジュール が古いバージョンで定義された名前を定義していない場合、古い定義が そのまま残ります。 辞書がグローバルテーブルやオブジェクトのキャッシュを維持していれば、 この機能をモジュールを有効性を引き出すために使うことができます -- つまり、 try 文を使えば、必要に応じてテーブルがあるかどうかをテストし、 その初期化を飛ばすことができるのです。

組み込みモジュールや動的にロードされるモジュールを再ロードする ことは、不正なやり方ではありませんが、一般的にそれほど便利では ありません。例外は sys、__main__ および __builtin__ です。 しかしながら、多くの場合、拡張モジュールは 1 度以上初期化される ようには設計されておらず、再ロードされた場合には何らかの理由で 失敗するかもしれません。

一方のモジュールが from ... import ... を使って、オブジェクトを他方のモジュールからインポートしているなら、 他方のモジュールを reload() で呼び出しても、その モジュールからインポートされたオブジェクトを再定義することは できません -- この問題を回避する一つの方法は、from 文を 再度実行することで、もう一つの方法は from 文の代わりに import と限定的な名前 (module.name) を使うことです。

あるモジュールがクラスのインスタンスを生成している場合、その クラスを定義しているモジュールの再ロードはそれらインスタンスの メソッド定義に影響しません -- それらは古いクラス定義を使いつづけ ます。これは導出クラスの場合でも同じです。

repr( object)
オブジェクトの印字可能な表現を含む文字列を返します。これは 型変換で得られる (逆クオートの) 値と同じです。通常の関数として この操作にアクセスできるとたまに便利です。この関数は多くの型について、 eval() に渡されたときに同じ値を持つようなオブジェクトを 表す文字列を生成しようとします。

round( x[, n])
x を少数点以下 n 桁で丸めた浮動小数点数の値を返します。 n が省略されると、標準の値はゼロになります。結果は浮動小数点 数です。値は最も近い 10 のマイナス n の倍数に丸められます。 二つの倍数との距離が等しい場合、ゼロから離れる方向に丸められます (従って、例えば round(0.5) は 1.0 になり、 round(-0.5) は -1.0 になります)。

setattr( object, name, value)
getattr() と対をなす関数です。引数はそれぞれオブジェクト、 文字列、そして任意の値です。文字列はすでに存在する属性の名前でも、 新たな属性の名前でもかまいません。この関数は指定した値を指定した属性に 関連付けますが、指定したオブジェクトにおいて可能な場合に限ります。 例えば、setattr(x, 'foobar', 123) は x.foobar = 123 と等価です。

slice( [start,] stop[, step])
range(start, stop, step) で指定される インデクスの集合を表すスライスオブジェクトを返します。 range(start)スライスオブジェクトを返します。 引数 start および step は標準では None です。 スライスオブジェクトは読み出し専用の属性 start、stop および step を持ち、これらは単に引数で使われた値 (または 標準の値) を返します。これらの値には、その他のはっきりとした機能は ありません; しかしながら、これらの値は Numerical Python およびその他のサードパーティによる拡張 で利用されています。スライスオブジェクトは拡張されたインデクス指定 構文が使われる際にも生成されます。例えば: "a[start:stop:step]" や "a[start:stop, i]" です。

staticmethod( function)
function の静的メソッドを返します。

静的メソッドは暗黙の第一引数を受け取りません。 静的メソッドの宣言は、以下のように書き慣わされます:

class C:
    def f(arg1, arg2, ...): ...
    f = staticmethod(f)

このメソッドはクラスで呼び出すこと (例えば C.f() ) も、 インスタンスとして呼び出すこと (例えば C().f()) もできます。 インスタンスはそのクラスが何であるかを除いて無視されます。

Python における静的メソッドは Java や C++ における静的メソッドと 類似しています。より進んだ概念については、 classmethod() を参照してください。 バージョン2.2 以降で新規追加された 仕様です。

str( [object])
オブジェクトをうまく印字可能な形に表現したものを含む文字列を返します。 文字列に対してはその文字列自体を返します。repr(object) との違いは、str(object) は常に eval() が 受理できるような文字列を返そうと試みるわけではないという点です; この関数の目的は印字可能な文字列を返すところにあります。 引数が与えられなかった場合、空の文字列 '' を返します。

sum( sequence[, start])
start と sequence の要素を左から右へ加算してゆき、 総和を返します。start はデフォルトで 0 です。 sequence の要素は通常は数値で、文字列であってはなりません。 文字列からなる配列をを結合する高速で、正しい方法は ''.join(sequence) です。 sum(range(n), m) は reduce(operator.add, range(n), m) と同等です。 バージョン2.3 以降で新規追加された 仕様です。

super( type[, object-or-type])
type の上位クラスを返します。返された上位クラスオブジェクトが非バ インドの場合、二つめの引数は省略されます。二つめの引数がオブジェクトの場 合、isinstance(obj, type) は真でなくてはなりません。 二つ目の引数が型オブジェクトの場合、issubclass(type2, type) は真でなくてはなりません。 super() は新スタイルのクラスにのみ機能します。

協調する上位クラスのメソッドを呼び出す典型的な利用法を以下に示します:

class C(B):
    def meth(self, arg):
        super(C, self).meth(arg)
バージョン2.2 以降で新規追加された 仕様です。

tuple( [sequence])
sequence の要素と要素が同じで、かつ順番も同じになるタプルを 返します。sequence は配列、反復をサポートするコンテナ、 およびイテレータオブジェクトをとることができます。 sequence がすでにタプルの場合、そのタプルを変更せずに返します。 例えば、tuple('abc') は ('a', 'b', 'c') を返し、 tuple([1, 2, 3]) は (1, 2, 3) を返します。

type( object)
object の型を返します。返される値は型オブジェクト です。標準モジュール typesは、組み込み名を持っていない全ての組み込み型の名前を定義しています。 引数が与えられない場合、新しい空のタプル () を返します。

例えば:

>>> import types
>>> x = 'abc'
>>> if type(x) is str: print "It's a string"
...
It's a string
>>> def f(): pass
...
>>> if type(f) is types.FunctionType: print "It's a function"
...
It's a function

オブジェクトの型のテストには、組み込み関数 isinstance() が推奨されています。

unichr( i)
Unicode におけるコードが整数 i になるような文字 1 文字からなる Unicode 文字列を返します。例えば、unichr(97) は文字列 u'a' を返します。この関数は Unicode 文字列に対する ord() の逆 です。引数は両端を含めて [0..65535] の範囲でなければなりません。 それ以外の値に対しては ValueError が送出されます。 バージョン2.0 以降で新規追加された 仕様です。

unicode( [object[, encoding [, errors]]])
以下のモードのうち一つを使って、object のUnicode 文字列 バージョンを返します:

もし encoding かつ/または errors が与えられていれば、 unicode() は 8 ビットの文字列または文字列バッファになっている オブジェクトを encoding の codec を使ってデコードします。 encoding パラメタはエンコーディング名を与える文字列です; 未知のエンコーディングの場合、LookupError が送出されます。 エラー処理は errors に従って行われます; このパラメタは 入力エンコーディング中で無効な文字の扱い方を指定します。errors が 'strict' (標準の設定です) の場合、エラー発生時には ValueError が送出されます。一方、'ignore' では、 エラーは暗黙のうちに無視されるようになり、'replace' では 公式の置換文字、U+FFFD を使って、デコードできなかった 文字を置き換えます。codecs モジュールについても参照して ください。

オプションのパラメタが与えられていない場合、 unicode() は str() の動作をまねます。ただし、8 ビット文字列ではなく、 Unicode 文字列を返します。もっと詳しくいえば、 object が Unicode 文字列かそのサブクラスなら、デコード処理を一切介する ことなく Unicode 文字列を返すということです。

__unicode__() メソッドを提供しているオブジェクトの場合、 unicode() はこのメソッドを引数なしで呼び出して Unicode 文字列を生成します。それ以外のオブジェクトの場合、 8 ビットの文字列か、オブジェクトのデータ表現 (representation) を呼び出し、その後デフォルトエンコーディングで 'strict' モードの codec を使って Unicode 文字列に変換します。

バージョン2.0 以降で新規追加された 仕様です。 バージョン2.2 以降で変更された 仕様: __unicode__() のサポートが追加されました

vars( [object])

引数無しでは、現在のローカルシンボルテーブルに対応する辞書を 返します。モジュール、クラス、またはクラスインスタンスオブジェクト (またはその他 __dict__ 属性を持つもの) を引数として与えた場合、 そのオブジェクトのシンボルテーブルに対応する辞書を返します。 返される辞書は変更すべきではありません: 変更が対応するシンボルテーブル にもたらす影響は未定義です。2.5

xrange( [start,] stop[, step])
この関数は range() に非常によく似ていますが、リストの代わり に ``xrange オブジェクト'' を返します。このオブジェクトは不透明な 配列型で、対応するリストと同じ値を持ちますが、それらの値全てを 同時に記憶しません。ragne() に対する xrange() の利点は微々たるものです (xrange() は要求に応じて 値を生成するからです) ただし、メモリ量の厳しい計算機で 巨大な範囲の値を使う時や、(ループがよく break で中断 されるといったように) 範囲中の全ての値を使うとは限らない場合は その限りではありません。

zip( seq1, ...)
この関数はタプルのリストを返します。このリストの i 番目のタプルは 各引数の配列中の i 番目の要素を含みます。少なくとも 1 つの 配列が引数に必要で、そうでない場合には TypeError が 送出されます。返されるリストは引数の配列のうち長さが最小のものの 長さに切り詰められます。引数の配列が全て同じ長さの際には、 zip() は初期値引数が None の map() と似ています。引数が単一の配列の場合、1 要素のタプルからなる リストを返します。 バージョン2.0 以降で新規追加された 仕様です。

... 新たなモジュールを生成しません。2.3
この関数は比較利用されない 方なので、将来構文にするかどうかは保証できません。
... 場合、システムの標準の値が使われます。2.4
現状では、setvbuf() を持っていないシステムでは、 バッファサイズを指定しても効果はありません。バッファサイズを指定 するためのインタフェースは setvbuf() を使っては 行われていません。 何らかの I/O が実行された後で呼び出されるとコアダンプすることが あり、どのような場合にそうなるかを決定する信頼性のある方法が ないからです。
... にもたらす影響は未定義です。2.5
現在の実装では、ローカルな値 のバインディングは通常は影響を受けませんが、(モジュールのような) 他のスコープから取り出した値は影響を受けるかもしれません。また この実装は変更されるかもしれません。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2. 組み込みオブジェクト Up: 2. 組み込みオブジェクト Next: 2.2 非必須組み込み関数 (Non-essential Built-in


2.2 非必須組み込み関数 (Non-essential Built-in Functions)

いくつかの組み込み関数は、現代的な Python プログラミングを行う場合には、 必ずしも学習したり、知っていたり、使ったりする必要がなくなりました。 こうした関数は古いバージョンの Python 向け書かれたプログラムとの互換性を 維持するだけの目的で残されています。

Python のプログラマ、教官、学生、そして本の著者は、こうした関数を飛ばしても かまわず、その際に何か重要なことを忘れていると思う必要もありません。

apply( function, args[, keywords])
引数 function は呼び出しができるオブジェクト (ユーザ定義 および組み込みの関数またはメソッド、またはクラスオブジェクト) でなければなりません。args は配列型でなくてはなりません。 function は引数リスト args を使って呼び出されます; 引数の数はタプルの長さになります。オプションの引数 keywords を与える場合、 keywords は文字列のキーを持つ辞書で なければなりません。これは引数リストの最後に追加されるキーワード 引数です。 apply() の呼び出しは、単なる function(args) の呼び出しとは異なります。 というのは、apply() の場合、引数は常に一つだから です。apply() は function(*args, **keywords) を 使うのと等価です。 上のような ``拡張された関数呼び出し構文'' は apply() と全く等価なので、必ずしも apply() を使う必要はありません。
リリース 2.3 以降で撤廃された仕様です。 上で述べられたような拡張呼び出し構文を使って ください。

buffer( object[, offset[, size]])
引数 object を参照する新たなバッファオブジェクトが生成されます。 引数 object は (文字列、アレイ、バッファといった) バッファ 呼び出しインタフェースをサポートするオブジェクトでなければなりません。 返されるバッファオブジェクトは object の先頭 (または offset) からのスライスになります。スライスの末端は object の末端まで (または引数 size で与えられた長さになるまで) です。

coerce( x, y)
二つの数値型の引数を共通の型に変換して、変換後の値からなるタプルを 返します。変換に使われる規則は算術演算における規則と同じです。

intern( string)
string を ``隔離'' された文字列のテーブルに入力し、隔離された 文字列を返します - この文字列は string 自体かコピーです。 隔離された文字列は辞書検索のパフォーマンスを少しだけ向上させるのに 有効です - 辞書中のキーが隔離されており、検索するキーが隔離されて いる場合、(ハッシュ化後の) キーの比較は文字列の比較ではなくポインタ の比較で行うことができるからです。通常、Python プログラム内で 利用されている名前は自動的に隔離され、モジュール、クラス、 またはインスタンス属性を保持するための辞書は隔離されたキーを持って います。 バージョン2.3 以降で変更された 仕様: 隔離された文字列の有効期限は (Python 2.2 またはそれ以前は永続的でしたが) 永続的ではなくなりました; intern() の恩恵を受けるためには、intern() の返す値に対する参照を保持しなければなりません

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.1 組み込み関数 Up: 2. 組み込みオブジェクト Next: 2.3 組み込み型


2.3 組み込み型

以下のセクションでは、インタプリタに組み込まれている標準の型に ついて記述します。これまでの Python の歴史では、組み込み型は オブジェクト指向における継承を行う際に雛型にできないという点で、 ユーザ定義型とは異なっていました。リリース 2.2 からは状況が 変わり始めましたが、目標とするユーザ定義型と組み込み方の一元化は まだまだ完成の域には達していません。

主要な組み込み型は数値型、配列型、マッピング型、ファイルクラス、 インスタンス型、および例外です。

演算によっては、複数の型でサポートされているものがあります; 特に、全てのオブジェクトについて、比較、真値テスト、 (` ...` 形式での) 文字列への変換を行うことができます。 print 使われた場合、最後の文字列への変換 が暗黙のうちに行われます。 (Information on print 文 やその他の文に関する情報は Python リファレンスマニュアル および Python チュートリアル で見つけることができます。)

  • 2.3.1 真値テスト
  • 2.3.2 ブール演算
  • 2.3.3 比較
  • 2.3.4 数値型
    • 2.3.4.1 整数型におけるビット文字列演算
  • 2.3.5 イテレータ型
  • 2.3.6 配列型
    • 2.3.6.1 文字列メソッド
    • 2.3.6.2 文字列フォーマット操作
    • 2.3.6.3 XRange 型
    • 2.3.6.4 変更可能な配列型
  • 2.3.7 マップ型
  • 2.3.8 ファイルオブジェクト
  • 2.3.9 他の組み込み型
    • 2.3.9.1 モジュール
    • 2.3.9.2 クラスおよびクラスインスタンス
    • 2.3.9.3 関数
    • 2.3.9.4 メソッド
    • 2.3.9.5 コードオブジェクト
    • 2.3.9.6 型オブジェクト
    • 2.3.9.7 ヌルオブジェクト
    • 2.3.9.8 省略表記オブジェクト
    • 2.3.9.9 ブール値
    • 2.3.9.10 内部オブジェクト
  • 2.3.10 特殊な属性
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.2 非必須組み込み関数 (Non-essential Built-in Up: 2. 組み込みオブジェクト Next: 2.3.1 真値テスト


2.3.1 真値テスト

どのオブジェクトも if または while 条件文の中や、 以下のブール演算における被演算子として真値テストを行うことができます。 以下の値は偽であると見なされます:

  • None

  • False

  • 数値型におけるゼロ。例えば 0 、 0L 、 0.0 、 0j 。

  • 空の配列型。例えば '' 、 () 、 [] 。

  • 空のマッピング型。例えば {} 。

  • __nonzero__() または __len__() メソッドが 定義されているようなユーザ定義クラスのインスタンスで、それらのメソッド が整数値ゼロまたは bool 値の False を返すとき。 2.6

それ以外の値は全て真であると見なされます -- 従って、ほとんどの型 のオブジェクトは常に真です。

ブール値の結果を返す演算および組み込み関数は、特に注釈のない限り常に 偽値として 0 またはFalse を返し、真値として 1 または True を返します (重要な例外: ブール演算 "or" および "and" は常に被演算子 の中の一つを返します)。

... を返すとき。2.6
これらの特殊なメソッドに関する追加情報は Python リファレンスマニュアルに記載されています。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3 組み込み型 Up: 2.3 組み込み型 Next: 2.3.2 ブール演算


2.3.2 ブール演算

以下にブール演算子を示します。優先度の低いものから順に並んでいます。:

演算 | 結果 | 注釈
x or y | x が偽なら y 、そうでなければ x | (1)
x and y | x が偽なら x 、そうでなければ y | (1)
not x | x が偽なら True 、そうでなければ False | (2)

注釈:

(1)
これらの演算子は、演算を行う上で必要がない限り、二つ目の引数を評価しません。

(2)
"not" は非ブール演算子よりも低い演算優先度なので、 not a == b は not (a == b) と評価され、 a == not b は構文エラーとなります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.1 真値テスト Up: 2.3 組み込み型 Next: 2.3.3 比較


2.3.3 比較

比較演算は全てのオブジェクトでサポートされています。比較演算子は 全て同じ演算優先度を持っています (ブール演算より高い演算優先度です)。 比較は任意の形で連鎖させることができます; 例えば、x < y <= z は x < y および y <= z と等価で、違うのは y が一度だけしか評価 されないということです (どちらの場合でも、 x < y が偽となった場合には z は評価されません) 。

以下のテーブルに比較演算をまとめます:

演算 | 意味 | 注釈
< | より小さい |
<= | 以下 |
> | より大きい |
>= | 以上 |
== | 等しい |
!= | 等しくない | (1)
<> | 等しくない | (1)
is | 同一のオブジェクトである |
is not | 同一のオブジェクトでない |

注釈:

(1)
<> および != は同じ演算子を別の書き方にしたものです。 != のほうが望ましい書き方です; <> は廃止すべき書き方です。

数値型間の比較か文字列間の比較でないかぎり、異なる型のオブジェクトを 比較しても等価になることはありません; これらのオブジェクトの順番付けは 一貫してはいますが任意のものです (従って要素の型が一様でない配列を ソートした結果は一貫したものになります)。 さらに、(例えばファイルオブジェクトのように) 型によっては、 その型の 2 つのオブジェクトの不等性だけの、縮退した比較の概念 しかサポートしないものもあります。繰り返しますが、 そのようなオブジェクトも任意の順番付けをされていますが、 それは一貫したものです。被演算子が複素数の場合、演算子 < 、 <= 、 > および >= は 例外 TypeError を送出します。

あるクラスのインスタンス間の比較は、そのクラスで __cmp__() メソッドが定義されていない限り等しくなりません。 このメソッドを使ってオブジェクトの比較方法に影響を及ぼすための 情報については Python リファレンスマニュアル を参照してください。

実装に関する注釈: 数値型を除き、異なる型のオブジェクトは 型の名前で順番付けされます; 適当な比較をサポートしていないある型の オブジェクトはアドレスによって順番付けされます。

同じ優先度を持つ演算子としてさらに 2 つ、配列型でのみ "in" および "not in" が サポートされています (以下を参照)。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.2 ブール演算 Up: 2.3 組み込み型 Next: 2.3.4 数値型


2.3.4 数値型

4 つの異なる数値型があります: 通常の整数型 、 長整数型 、浮動小数点型 、および 複素数型 です。

さらに、ブール方は通常の整数方のサブタイプです。通常の整数 (単に 整数型 とも呼ばれます) は C では long を 使って実装されており、少なくとも 32 ビットの精度があります。 長整数型には精度の制限がありません。浮動小数点型は C では double を使って実装されています。しかし使っている計算機 が何であるか分からないなら、これらの数値型の精度に関して断言はできません。

複素数型は実数部と虚数部を持ち、それぞれの C では double を 使って実装されています。複素数 z から実数および虚数部を取り出す には、z.real および z.imag を使います。

数値は、数値リテラルや組み込み関数や演算子の戻り値として生成されます。 修飾のない整数リテラル (16 進表現や 8 進表現の値も含みます) は、 通常の整数値を表します。値が通常の整数で表すには大きすぎる場合、 "L" または "l" が末尾につく整数リテラル は長整数型を表します ("L" が望ましいです。というのは "1l" は 11 と非常に紛らわしいからです！) 小数点または 指数表記のある数値リテラルは浮動小数点数を表します。 数値リテラルに "j" または "J" をつけると 実数部がゼロの複素数を表します。複素数の数値リテラルは実数部と 虚数部を足したものです。

Python は型混合の演算を完全にサポートします: ある 2 項演算子が 互いに異なる数値型の被演算子を持つ場合、より ``制限された'' 型の 被演算子は他方の型に合わせて広げられます。ここで通常の整数は 長整数より制限されており、長整数は浮動小数点数より制限されており、 浮動小数点は複素数より制限されています。 型混合の数値間での比較も同じ規則に従います。 2.7コンストラクタ int() 、long() 、float()、 および complex() を使って、特定の型の数を生成することが できます。

全ての数値型（complex は例外）は以下の演算をサポートします。これらの演算は 優先度の低いものから順に並べられています (同じボックスにある演算は 同じ優先度を持っています; 全ての数値演算は比較演算よりも 高い優先度を持っています):

演算 | 結果 | 注釈
x + y | x と y の加算 |
x - y | x と y の減算 |
x * y | x と y の乗算 |
x / y | x と y の除算 | (1)
x % y | x / y の剰余 | (4)
-x | x の符号反転 |
+x | x の符号不変 |
abs(x) | x の絶対値または大きさ |
int(x) | x の通常整数への変換 | (2)
long(x) | x の長整数への変換 | (2)
float(x) | x の浮動小数点数への変換 |
complex(re,im) | 実数部 re 、虚数部 im の複素数。 im のデフォルト値はゼロ。 |
c.conjugate() | 複素数 c の共役複素数 |
divmod(x, y) | (x / y, x % y) からなるペア | (3)
pow(x, y) | x の y 乗 |
x ** y | x の y 乗 |

注釈:

(1)
(通常および長) 整数の割り算では、結果は整数になります。 この場合値は常にマイナス無限大の方向に丸められます: つまり、1/2 は 0、 (-1)/2 は -1、1/(-1) は -1、そして (-1)/(-2) は 0 になります。 被演算子の両方が長整数の場合、計算値に関わらず結果は長整数で返される ので注意してください。

(2)
浮動小数点数から (通常または長) 整数への変換では、C におけるのと同様の 値の丸めまたは切り詰めが行われるかもしれません; きちんと定義された 変換については、math モジュールの floor() および ceil() を参照してください。

(3)
完全な記述については、2.1、``組み込み関数'' を参照してください。

(4)
複素数の切り詰め除算演算子、モジュロ演算子、および divmod()。

リリース 2.3 以降で撤廃された仕様です。 適切であれば、abs() を使って浮動小数点に変換してください。

... 型混合の数値間での比較も同じ規則に従います。2.7
この結果として、リスト [1, 2] は [1.0, 2.0] と等しいと見なされます。タプルの場合も同様です

  • 2.3.4.1 整数型におけるビット文字列演算
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.3 比較 Up: 2.3 組み込み型 Next: 2.3.4.1 整数型におけるビット文字列演算


2.3.5 イテレータ型

バージョン2.2 以降で新規追加された 仕様です。

Python はコンテナの内容にわたって反復処理を行う概念をサポートして います。この概念は 2 つの別々のメソッドを使って実装されています; これらのメソッドはユーザ定義のクラスで反復を行えるようにするために 使われます。後に詳しく述べる配列型はすべて反復処理メソッドを サポートしています。

以下はコンテナオブジェクトに反復処理をサポートさせるために定義しなければ ならないメソッドです:

__iter__( )
イテレータオブジェクトを返します。イテレータオブジェクトは以下で述べる イテレータプロトコルをサポートする必要があります。あるコンテナが 異なる形式の反復処理をサポートする場合、それらの反復処理形式 のイテレータを特定的に要求するようなメソッドを追加することができます (複数の形式での反復処理をサポートするようなオブジェクトとして 木構造の例があります。木構造は幅優先走査と深さ優先走査の両方を サポートします)。 このメソッドは Python/C API において Python オブジェクトを表す 型構造体の tp_iter スロットに対応します。

イテレータオブジェクト自体は以下の 2 のメソッドをサポートする必要 があります。これらのメソッドは 2 つ合わせて イテレータプロトコル を成します:

__iter__( )
イテレータオブジェクト自体を返します。このメソッドはコンテナとイテレータの 両方をfor および in 文で使えるようにするために 必要です。このメソッドは Python/C API において Python オブジェクトを表す 型構造体の tp_iter スロットに対応します。

next( )
コンテナ内の次の要素を返します。もう要素が残っていない場合、 例外 StopIteration を送出します。このメソッドは Python/C API において Python オブジェクトを表す型構造体の tp_iternext スロットに対応します。

Python では、いくつかのイテレータオブジェクトを定義しています。これらは 一般的および特殊化された配列型、辞書型、そして他のさらに特殊化 された形式をサポートします。特殊型であることはイテレータプロトコル の実装が特殊になること以外は重要なことではありません。

このプロトコルの趣旨は、 一度イテレータの next() メソッドが StopIteration 例外を送出した場合、以降の呼び出しでもずっと例外を送出しつづける ところにあります。この特性に従わないような実装は変則であると みなされます (この制限は Python 2.3 で追加されました; Python 2.2 では、この規則に従うと多くのイテレータが変則となります)。

Python におけるジェネレータ (generator) は、イテレータプロトコル を実装する簡便な方法を提供します。コンテナオブジェクトの __iter__() メソッドがジェネレータとして実装されて いれば、メソッドは __iter__() および next() メソッドを提供するイテレータオブジェクト (技術的にはジェネレータ オブジェクト) を自動的に返します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.4.1 整数型におけるビット文字列演算 Up: 2.3 組み込み型 Next: 2.3.6 配列型


2.3.6 配列型

組み込み型には 6 つの配列型があります: 文字列、ユニコード文字列、 リスト、タプル、バッファ、そして xrange オブジェクトです。

文字列リテラルは 'xyzzy'、"frobozz" といったように、 単引用符または二重引用符の中に書かれます。 文字列リテラルについての詳細はは、 Python リファレンスマニュアル の第 2 章を読んで下さい。 Unicode 文字列はほとんど文字列と同じですが、u'abc' 、 u"def" といったように先頭に文字 "u" を付けて 指定します。 リストは [a, b, c] のように要素をコンマで区切り角括弧で 囲って生成します。タプルは a, b, c のようにコンマ演算子で 区切って生成します (角括弧の中には入れません)。 丸括弧で囲っても囲わなくてもかまいませんが、空のタプルは () のように丸括弧で囲わなければなりません。 要素が一つのタプルでは、例えば (d,) のように、要素の後ろに コンマをつけなければなりません。

バッファオブジェクトは Python の構文上では直接サポートされていませんが、 組み込み関数 buffer() で生成することができます。バッファオブジェクトは結合や反復をサポート していません。

xrange オブジェクトは、オブジェクトを生成するための特殊な構文がない 点でバッファに似ていて、関数 xrange()で生成します。 xrange オブジェクトはスライス、結合、反復をサポートせず、 in 、 not in 、min() または max() は効率的ではありません。

ほとんどの配列型は以下の演算操作をサポートします。"in" および "not in" は比較演算とおなじ優先度を持っています。 "+" および "*" は対応する数値演算とおなじ優先度です。 2.8

以下のテーブルは配列型の演算を優先度の低いものから順に挙げたものです (同じボックス内の演算は同じ優先度です)。テーブル内の s および t は同じ型の配列です; n、i および j は整数です:

演算 | 結果 | 注釈
x in s | s のある要素 x と等しい場合 1 、そうでない場合 0 | (1)
x not in s | s のある要素が x と等しい場合 0 、そうでない場合 1 | (1)
s + t | s および t の結合 |
s * n , n * s | s の浅いコピー n 個からなる結合 | (2)
s[i] | s の 0 から数えて i 番目の要素 | (3)
s[i:j] | s の i 番目から j 番目までのスライス | (3), (4)
s[i:j:k] | s の i 番目から j 番目まで、k 毎のスライス | (3), (5)
len(s) | s の長さ |
min(s) | s の最小の要素 |
max(s) | s の最大の要素 |

注釈:

(1)
s が文字列または Unicode 文字列の場合、 演算操作 in および not in は部分文字列の一致テスト と同じように動作します。バージョン 2.3 以前の Python では、 x は長さ 1 の文字列でした。Python 2.3 以降では、x はどの長さでもかまいません。

(2)
n が 0 以下の値の場合、0 として 扱われます (これは s と同じ型の空の配列を表します)。 コピーは浅いコピーなので注意してください; 入れ子になったデータ 構造はコピーされません。これは Python に慣れていないプログラマを よく悩ませます。例えば以下のコードを考えます:

>>> lists = [[]] * 3
>>> lists
[[], [], []]
>>> lists[0].append(3)
>>> lists
[[3], [3], [3]]

上のコードでは、 lists はリスト [[]] (空のリストを唯一の 要素として含んでいるリスト) の3つのコピーを要素とするリストです。 しかし、リスト内の要素に含まれているリストは各コピー間で共有されています。 以下のようにすると、異なるリストを要素とするリストを生成できます:

>>> lists = [[] for i in range(3)]
>>> lists[0].append(3)
>>> lists[1].append(5)
>>> lists[2].append(7)
>>> lists
[[3], [5], [7]]

(3)
i または j が負の数の場合、インデクスは文字列の 末端からの相対インデクスになります: len(s) + i または len(s) + j が代入されます。 しかし -0 は 0 のままなので注意してください。

(4)
s の i から j へのスライスは i <= k < j となるようなインデクス k を持つ要素からなる配列として定義されます。i または j が len(s) よりも大きい場合、len(s) を使います。 i が省略された場合、0 を使います。 j が省略された場合、len(s) を使います。 i が j 以上の場合、スライスは空の配列になります。

(5)
s の i 番目から j 番目まで k 毎の スライスは、0 <= n < abs(i-j) となるような、 インデクスx = i + n*k を持つ要素からなる配列として 定義されます。 i または j len(s) より大きい場合、len(s) を使います。i または j を省略した場合、``最後'' (k の符号に依存)を示す値を使います。k はゼロにできないので 注意してください。

... は対応する数値演算とおなじ優先度です。2.8
パーザが被演算子の型を識別できるようにするために、このような優先度でなければならないのです。

  • 2.3.6.1 文字列メソッド
  • 2.3.6.2 文字列フォーマット操作
  • 2.3.6.3 XRange 型
  • 2.3.6.4 変更可能な配列型
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.5 イテレータ型 Up: 2.3 組み込み型 Next: 2.3.6.1 文字列メソッド


2.3.7 マップ型

mapping オブジェクトは変更不可能な値を任意のオブジェクトに 対応付けます。対応付け事態は変更可能なオブジェクトです。 現在のところは標準のマップ型、dictionary だけです。 辞書のキーにはほとんど任意の値をつかうことができます。使うことが できないのはリスト、辞書、その他の変更可能な型 (オブジェクトの一致 ではなく、その値で比較されるような型) です。 キーに使われた数値型は通常の数値比較規則に従います: 二つの数字を 比較した時等価であれば (例えば 1 と 1.0 のように)、 これらの値はお互いに同じ辞書のエントリを示すために使うことが できます。

辞書は key: value からなるペアを カンマで区切ったリストを波括弧の中に入れて作ります。 例えば: {'jack': 4098, 'sjoerd': 4127} または {4098: 'jack', 4127: 'sjoerd'} です。

以下の操作がマップ型で定義されています (ここで、a および b はマップ型で、k はキー、 v および x は任意の オブジェクトです):

操作 | 結果 | 注釈
len(a) | a 内の要素の数です |
a[k] | キー k を持つa の要素です | (1)
a[k] = v | a[k] を v に設定します |
del a[k] | a から a[k] を削除します | (1)
a.clear() | a から全ての要素を削除します |
a.copy() | a の(浅い)コピーです |
a.has_key(k) | a にキー k があれば True 、 そうでなければ False です |
k in a | a.has_key(k) と同じです | (2)
k not in a | not a.has_key(k) と同じです | (2)
a.items() | a における (key, value) ペアのリストのコピーです | (3)
a.keys() | a におけるキーのリストのコピーです | (3)
a.update(b) | for k in b.keys(): a[k] = b[k] |
a.fromkeys(seq[, value]) | seq からキーを作り、値が value であるような、新しい辞書を作成します | (7)
a.values() | a における値のリストのコピーです | (3)
a.get(k[, x]) | a[k] if k in a, else x | (4)
a.setdefault(k[, x]) | a[k] if k in a, else x (also setting it) | (5)
a.pop(k[, x]) | a[k] if k in a, else x (and remove k) | (8)
a.popitem() | 任意の (key, value) ペアを除去して返します | (6)
a.iteritems() | (key, value) ペアにわたるイテレータを返します | (2), (3)
a.iterkeys() | マップのキー列にわたるイテレータを返します | (2), (3)
a.itervalues() | マップの値列にわたるイテレータを返します | (2), (3)

注釈:

(1)
k がマップ内にない場合、例外 KeyError を 送出します。
(2)
バージョン2.2 以降で新規追加された 仕様です。

(3)
キー及び値はランダムな順番でリストになっています。 途中で辞書を変更せずに items()、 keys()、 values()、 iteritems()、 iterkeys()、 and itervalues() を呼んだ場合、返されるリストは直接対応しています。これにより、 (value, key) のペアを zip() を 使って: "pairs = zip(a.values(), a.keys())" のように生成することができます。iterkeys() および itervalues() メソッドの間でも同じ関係が成り立ちます: "pairs = zip(a.itervalues(), a.iterkeys())" は pairs と同じ値になります。 同じリストを生成するもう一つの方法は "pairs = [(v, k) for (k, v) in a.iteritems()]"です。

(4)
k がマップ中になくても例外を送出せず、代わりに x を返します。x はオプションです; x が与えられて おらず、かつ k がマップ中になければ、 None が返されます。

(5)
setdefault() は get() に似ていますが、 k が見つからなかった場合、x が返されると同時に辞書の k に対する値として挿入されます。

(6)
popitem() は、集合アルゴリズムでよく行われる ような、辞書を取り崩しながらの反復を行うのに便利です。

(7)
fromkeys() は、新しい辞書を返すクラスメソッドです。 value のデフォルト値は None です。 バージョン2.3 以降で新規追加された 仕様です。

(8)
pop() は、デフォルト値が渡されず、かつ、キーが見つからない場合に、 KeyError を送出します。 バージョン2.3 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.6.4 変更可能な配列型 Up: 2.3 組み込み型 Next: 2.3.8 ファイルオブジェクト


2.3.8 ファイルオブジェクト

ファイルオブジェクト は C のstdio パッケージを使って実装されており、 2.1 節の ``組み込み関数'' で解説されている組み込みのコンストラクタ file() で生成することができます。 2.11

ファイルオブジェクトはまた、os.popen() や os.fdopen() 、ソケットオブジェクトの makefile() メソッドのような、他の組み込み関数およびメソッドによっても返されます。

ファイル操作が I/O 関連の理由で失敗した場合例外 IOError が送出されます。この理由には例えば seek() を端末デバイスに 行ったり、読み出し専用で開いたファイルに書き込みを行うといった、 何らかの理由によってそのファイルで定義されていない操作を行った ような場合も含まれます。

ファイルは以下のメソッドを持ちます:

close( )
ファイルを閉じます。閉じられたファイルはそれ以後読み書きすることは できません。ファイルが開かれていることが必要な操作は、ファイルが 閉じられた後はすべて ValueError を送出します。 close を一度以上呼び出してもかまいません。

flush( )
stdio の fflush() のように、内部バッファを フラッシュします。ファイル類似のオブジェクトによっては、この 操作は何も行いません。

fileno( )
背後にある実装系がオペレーティングシステムに I/O 操作を要求するために 用いる、整数の ``ファイル記述子'' を返します。この値は他の用途として、 fcntlモジュールや os.read() やその仲間のような、ファイル記述子を必要とする低レベルのインタフェース で役に立ちます。 注意: ファイル類似のオブジェクトが実際のファイルに関連付けられていない 場合、このメソッドを提供すべきではありません。

isatty( )
ファイルが tty (または類似の) デバイスに接続されている場合 True を返し、そうでない場合 False を返します。 注意: ファイル類似のオブジェクトが実際のファイルに関連付けられていない 場合、このメソッドを実装すべきではありません。

next( )
ファイルオブジェクトはそれ自身がイテレータです。すなわち、 iter(f) は (f が閉じられていない限り) f を返します。for ループ (例えば for line in f: print line) のようにファイルがイテレータとして 使われた場合、next() メソッドが繰り返し呼び出されます。 個のメソッドは次の入力行を返すか、または EOF に到達したときに StopIteration を送出します。ファイル内の各行に対する for ループ (非常によくある操作です) を効率的な方法で 行うために、next() メソッドは隠蔽された先読みバッファ を使います。先読みバッファを使った結果として、(readline() のような) 他のファイルメソッドと next() を組み合わせて使うと うまく動作しません。しかし、seek() を使ってファイル位置 を絶対指定しなおすと、先読みバッファはフラッシュされます。

バージョン2.3 以降で新規追加された 仕様です。

read( [size])
最大で size バイトをファイルから読み込みます (size バイト を取得する前に EOF に到達した場合、それ以下の長さになります) size 引数が負であるか省略された場合、EOF に到達するまでの 全てのデータを読み込みます。読み出されたバイト列は文字列オブジェクト として返されます。直後に EOF に到達した場合、空の文字列が返されます。 (端末のようなある種のファイルでは、 EOF に到達した後でファイルを 読みつづけることにも意味があります。) このメソッドは、size バイトに可能な限り近くデータを取得するために、背後の C 関数 fread() を 1 度以上呼び出すかもしれないので注意してください。 また、非ブロック・モードでは、size パラメータが与えられなくても、 要求されたよりも少ないデータが返される場合があることに注意してください。

readline( [size])
ファイルから一行を読み出します。末尾の改行文字は文字列中に 残されます 2.12(ファイルが改行のない不完全な行の場合には、改行文字がないかも しれませんが) 。引数 size が指定されていて非負の場合、 (末尾の改行を含めて) 読み込む最大のバイト数です。この場合、 不完全な行が返されるかもしれません。空文字列が返されるのは、 直後に EOF に到達した場合 だけ です。 注意: stdio の fgets() と違い、入力中に ヌル文字 ('\0') が含まれていれば、ヌル文字を含んだ 文字列が返されます。

readlines( [sizehint])
readline() を使ってに到達するまで読み出し、EOF 読み出された行を含むリストを返します。オプションの sizehint 引数が存在すれば、EOFまで読み出す代わりに 完全な行を全体で大体 sizehint バイトになるように (おそらく内部バッファサイズを切り詰めて) 読み出します。 ファイル類似のインタフェースを実装しているオブジェクトは、 sizehint を実装できないか効率的に実装できない場合には 無視してもかまいません。

xreadlines( )
個のメソッドは iter(f) と同じ結果を返します。 バージョン2.1 以降で新規追加された 仕様です。
リリース 2.3 以降で撤廃された仕様です。 代わりに for line in file を使ってください。

seek( offset[, whence])
stdio の fseek() と同様に、ファイルの現在位置を 返します。whence 引数はオプションで、標準の値は 0 (絶対位置指定) です; 他に取り得る値は 1 (現在のファイル位置 から相対的に seek する) および 2 (ファイルの末端から相対的に seek する) です。戻り値はありません。ファイルを追記モード (モード 'a' または 'a+') で開いた場合、書き込みを行う までに行ったseek() 操作はすべて元に戻されるので注意してください。 ファイルが追記のみの書き込みモード ('a') で開かれた場合、 このメソッドは実質何も行いませんが、読み込みが可能な追記モード ('a+') で開かれたファイルでは役に立ちます。 ファイルをテキストモード ('t') で開いた場合、 tell() が返すオフセットのみが正しい値になります。 他のオフセット値を使った場合、その振る舞いは未定義です。

全てのファイルオブジェクトが seek できるとは限らないので注意してください。

tell( )
stdio の ftell() と同様、ファイルの現在位置を 返します。

truncate( [size])
ファイルのサイズを切り詰めます。オプションの size が存在 すれば、ファイルは (最大で) 指定されたサイズに切り詰められます。 標準設定のサイズの値は、現在のファイル位置までのファイルサイズです。 現在のファイル位置は変更されません。指定されたサイズがファイルの 現在のサイズを越える場合、その結果はプラットフォーム依存なので 注意してください: 可能性としては、ファイルは変更されないか、 指定されたサイズまでゼロで埋められるか、指定されたサイズまで 未定義の新たな内容で埋められるか、があります。 利用可能な環境: Windows, 多くの Unix 系。

write( str)
文字列をファイルに書き込みます。戻り値はありません。バッファリング によって、flush() または close() が呼び出されるまで 実際にファイル中に文字列が書き込まれないこともあります。

writelines( sequence)
文字列からなる配列をファイルに書き込みます。配列は文字列を生成 する反復可能なオブジェクトなら何でもかまいません。よくあるのは 文字列からなるリストです。戻り値はありません。 (関数の名前は readlines() と対応づけてつけられました; writelines() は行間の区切りを追加しません)

ファイルはイテレータプロトコルをサポートします。各反復操作では file.readline() と同じ結果を返し、反復は readline() メソッドが空文字列を返した際に終了します。

ファイルオブジェクトはまた、多くの興味深い属性を提供します。 これらはファイル類似オブジェクトでは必要ではありませんが、 特定のオブジェクトにとって意味を持たせたいなら実装しなければ なりません。

closed
現在のファイルオブジェクトの状態を示すブール値です。この値は 読み出し専用の属性です; close() メソッドがこの値を 変更します。全てのファイル類似オブジェクトで利用可能とは 限りません。

encoding
このファイルが使っているエンコーディングです。Unicode 文字列が ファイルに書き込まれる際、Unicode 文字列はこのエンコーディングを 使ってバイト文字列に変換されます。さらに、ファイルが端末に 接続されている場合、この属性は端末が使っているとおぼしきエンコーディング (この情報は端末がうまく設定されていない場合には不正確なこともあります) を与えます。この属性は読み出し専用で、すべてのファイル類似オブジェクト にあるとは限りません。またこの値は None のこともあり、 この場合、ファイルはUnicode 文字列の変換のためにシステムのデフォルト エンコーディングを使います。

バージョン2.3 以降で新規追加された 仕様です。

mode
ファイルの I/O モードです。ファイルが組み込み関数 open() で作成された場合、この値は引数 mode の値になります。 この値は読み出し専用の属性で、全てのファイル類似オブジェクトに 存在するとは限りません。

name
ファイルオブジェクトが open() を使って生成された時の ファイルの名前です。そうでなければ、ファイルオブジェクト生成の 起源を示す何らかの文字列になり、"<...>" の形式を とります。この値は読み出し専用の属性で、全てのファイル類似オブジェクトに 存在するとは限りません。

newlines
Python をビルドするとき、-with-universal-newlines オプションが指 定された場合（デフォルト）、この読み出し専用の属性が存在します。一般的な 改行に変換する読み出しモードで開かれたファイルにおいて、この属性はファイ ルの読み出し中に遭遇した改行コードを追跡します。取り得る値は '\ r'、'\n'、'\r\n'、None (不明または、まだ改行 していない）、見つかった全ての改行文字を含むタプルのいずれかです。最後の タプルは、複数の改行慣例に遭遇したことを示します。一般的な改行文字を使う 読み出しモードで開かれていないファイルの場合、この属性の値は None です。

softspace
print 文を使った場合、他の値を出力する前にスペース文字を 出力する必要があるかどうかを示すブール値です。 ファイルオブジェクトをシミュレート仕様とするクラスは書き込み可能な softspace 属性を持たなければならず、この値はゼロに初期化 されなければなりません。この値は Python で実装されているほとんどの クラスで自動的に初期化されます (属性へのアクセス手段を上書きする ようなオブジェクトでは注意が必要です); C で実装された型では、 書き込み可能な softspace 属性を提供しなければなりません。 注意: この属性は print 文を制御するために用いられますが、 print の内部状態を乱さないために、その実装を行うことは できません。

... で生成することができます。2.11
file() は Python 2.2 で新しく追加されました。 古いバージョンの組み込み関数 open() は file() の別名です。
... 残されます2.12
改行を残す利点は、空の文字列が返ると EOF を示し、紛らわしくなくなるからです。また、ファイルの最後の行 が改行で終わっているかそうでない (ありえることです！) か (例えば、ファイルを行単位で読みながらその完全なコピーを作成 した場合には問題になります) を調べることができます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.7 マップ型 Up: 2.3 組み込み型 Next: 2.3.9 他の組み込み型


2.3.9 他の組み込み型

インタプリタはその他の種類のオブジェクトをいくつかサポート します。これらのほとんどは 1 または 2 つの演算だけをサポート します。

  • 2.3.9.1 モジュール
  • 2.3.9.2 クラスおよびクラスインスタンス
  • 2.3.9.3 関数
  • 2.3.9.4 メソッド
  • 2.3.9.5 コードオブジェクト
  • 2.3.9.6 型オブジェクト
  • 2.3.9.7 ヌルオブジェクト
  • 2.3.9.8 省略表記オブジェクト
  • 2.3.9.9 ブール値
  • 2.3.9.10 内部オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.8 ファイルオブジェクト Up: 2.3 組み込み型 Next: 2.3.9.1 モジュール


2.3.10 特殊な属性

実装では、いくつかのオブジェクト型に対して、数個の読み出し専用の特殊な 属性を追加しています。それぞれ:

__dict__
オブジェクトの (書き込み可能な) 属性を保存するために使われる辞書または 他のマップ型オブジェクトです。

__methods__
リリース 2.2 以降で撤廃された仕様です。 オブジェクトの属性からなるリストを取得するには、 組み込み関数 dir() を使ってください。この属性はもう 利用できません。

__members__
リリース 2.2 以降で撤廃された仕様です。 オブジェクトの属性からなるリストを取得するには、 組み込み関数 dir() を使ってください。この属性はもう 利用できません。

__class__
クラスインスタンスが属しているクラスです。

__bases__
クラスオブジェクトの基底クラスからなるタプルです。基底クラスを 持たない場合、空のタプルになります。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.9.10 内部オブジェクト Up: 2.3 組み込み型 Next: 2.4 組み込み例外


2.4 組み込み例外

例外はクラスオブジェクトです。 例外はモジュール exceptions で定義されています。 このモジュールを明示的にインポートする必要はありません: 例外は exceptions モジュールと同様に組み込み名前空間で 与えられます。

注意: 過去の Python のバージョンでは、文字列の例外がサポートされていました。 Python 1.5 よりも新しいバージョンでは、全ての標準的な例外は クラスオブジェクトに変換され、ユーザにも同様にするよう奨励しています。 文字列による例外は PendingDeprecationWarning を 送出するようになります。 将来のバージョンでは、文字列による例外のサポートは削除されます。

同じ値を持つ別々の文字列オブジェクトは異なる例外と見なされます。 これはプログラマに対して、例外処理を指定する際に、 文字列ではなく例外名を使わせるための変更です。組み込み例外の文字列値は 全てその名前となりますが、ユーザ定義の例外やライブラリモジュールで定義される 例外についてもそうするように要求しているわけではありません。

try 文の中で、except 節を使って特定の例外クラスについて記述した場合、その節は 指定した例外クラスから導出されたクラスも扱います (指定した例外 クラスを導出した元のクラスは含みません) サブクラス化の関係にない例外クラスが二つあった場合、それらに同じ 名前を付けたとしても、等しくなることはありません。

以下に列挙した組み込み例外はインタプリタや組み込み関数によって生成 されます。特に注記しないかぎり、これらの例外は エラーの詳しい原因を 示している、 ``関連値 (associated value)'' を持ちます。 この値は文字列または複数の情報 (例えばエラーコードや、エラーコード を説明する文字列) を含むタプルです。この関連値は raise 文の二つ目の引数です。 文字列の例外の場合、関連値自体は except 節 (あった場合) の二つ目の引数として与えた名前を持つ変数に記憶されます。 クラス例外の場合、この値は例外クラスのインスタンスです。 例外が標準のルートクラスである Exception から 導出された場合、関連値は例外インスタンスの args 属性中 に他の属性と同様に置かれます。

ユーザによるコードも組み込み例外を送出することができます。 これは例外処理をテストしたり、インタプリタがある例外を送出する 状況と ``ちょうど同じような'' エラー条件であることを報告させるために 使うことができます。しかし、ユーザが適切でないエラーを送出するよう コードするのを妨げる方法はないので注意してください。

組み込み例外クラスは新たな例外を定義するためにサブクラス化する ことができます; プログラマには、新しい例外を少なくとも Exception 基底クラスから導出するよう勧めます。 例外を定義する上での詳しい情報は、 Python チュートリアル の ``ユーザ定義の例外'' の項目にあります。

以下の例外クラスは他の例外クラスの基底クラスとしてのみ使われます。

exception Exception
例外のルートクラスです。全ての組み込み例外はこのクラスから導出 されています。全てのユーザ定義例外はこのクラスから導出される べきですが、(今のところまだ) それは強制ではありません。 str() をこのクラス (またはほとんどの導出クラス) の インスタンスに適用すると、引数を文字列にしたが返されるか、 インスタンスのコンストラクタが引数なしの場合には空の文字列が返されます。 インスタンスを配列として使うと、コンストラクタに渡された引数にアクセス することができます (古いコードとの互換性のために便利です)。 引数はまた、インスタンスの args 属性として、タプルで 得ることもできます。

exception StandardError
StopIteration および SystemExit 以外の、 全ての組み込み例外の基底クラスです。 StandardError 自体はルートクラス Exception から導出されています。

exception ArithmeticError
算術上の様々なエラーにおいて送出される組み込み例外: OverflowError、ZeroDivisionError、 FloatingPointError の基底クラスです。

exception LookupError
マップ型または配列型に使ったキーやインデクスが無効な値の場合に 送出される例外:IndexError、KeyError の基底クラスです。sys.setdefaultencoding() によって直接送出されることもあります。

exception EnvironmentError
Python システムの外部で起こっているはずの例外: IOError、 OSError の基底クラスです。この型の例外が 2 つの要素を もつタプルで生成された場合、最初の要素はインスタンスの errno 属性で得ることができます (この値はエラー番号と見なされます)。二つめの 要素は strerror 属性です (この値は通常、エラーに関連する メッセージです)。タプル自体は args 属性から得ることもできます。 バージョン1.5.2 以降で新規追加された 仕様です。

EnvironmentError 例外が 3 要素のタプルで生成された場合、 最初の 2 つの要素は上と同様に得ることができる一方、3 つ目の要素は filename 属性で得ることができます。しかしながら、以前の バージョンとの互換性のために、args 属性にはコンストラクタに渡した 最初の 2 つの引数からなる 2 要素のタプルしか含みません。

この例外が 3 つ以外の引数で生成された場合、filename 属性は None になります。この例外が 2 または 3 つ以外の引数で生成 された場合、errno および strerror 属性も None になります。後者のケースでは、args が コンストラクタに与えた引数をそのままタプルの形で含んでいます。

以下の例外は実際に送出される例外です。

exception AssertionError
assert 文が失敗した場合に送出されます。

exception AttributeError
属性の参照や代入が失敗した場合に送出されます。(対照のオブジェクトが 属性の参照や属性の代入をまったくサポートしていない場合には TypeError が送出されます。)

exception EOFError
組み込み関数 (input() または raw_input()) のいずれかで、データを全く読まないうちにファイルの終端 (EOF) に 到達した場合に送出されます。 (注意: ファイルオブジェクトの read() および readline() メソッドの場合、データを読まないうちに EOFにたどり着くと空の文字列 を返します。)

exception FloatingPointError
浮動小数点演算が失敗した場合に送出されます。この例外はどの Python のバージョンでも常に定義されていますが、Python が --with-fpectl オプションをつけた状態に設定されて いるか、pyconfig.h ファイルにシンボル WANT_SIGFPE_HANDLER が定義されている場合にのみ 送出されます。

exception IOError
(print 文、組み込みの open() またはファイル オブジェクトに対するメソッドといった) I/O 操作が、例えば ``ファイルが存在しません'' や ``ディスクの空き領域がありません'' といった I/O に関連した理由で失敗した場合に送出されます。

このクラスは EnvironmentError から導出されています。 この例外クラスのインスタンス属性に関する情報は上記の EnvironmentError に関する議論を参照してください。

exception ImportError
import 文でモジュール定義を見つけられなかった場合や、 from ... import 文で指定した名前をインポート することができなかった場合に送出されます。

exception IndexError
配列のインデクス指定が配列の範囲を超えている場合に送出 されます。(スライスのインデクスは配列の範囲に収まるように暗黙のうちに 調整されます; インデクスが通常の整数でない場合、TypeError が送出されます。)

exception KeyError
マップ型 (辞書型) オブジェクトのキーが、オブジェクトのキー集合内に 見つからなかった場合に送出されます。

exception KeyboardInterrupt
ユーザが割り込みキー (通常は Control-C または Delete キー です) を押した場合に送出されます。割り込みが起きたかどうかはインタプリタ の実行中に定期的に調べられます。 組み込み関数 input() や raw_input() がユーザの 入力を待っている間に割り込みキーを押しても、この例外が送出されます。

exception MemoryError
ある操作中にメモリが不足したが、その状況は (オブジェクトをいくつか 消去することで) まだ復旧可能かもしれない場合に送出されます。 例外に関連づけられた値は、どの種の (内部) 操作がメモリ不足になっている かを示す文字列です。背後にあるメモリ管理アーキテクチャ (C の malloc() 関数) によっては、インタプリタが常にその状況 を完璧に復旧できるとはかぎらないので注意してください; プログラムの 暴走が原因の場合にも、やはり実行スタックの追跡結果を出力 できるようにするために例外が送出されます。

exception NameError
ローカルまたはグローバルの名前が見つからなかった場合に送出されます。 これは非限定の名前のみに適用されます。関連付けられた値は見つからなかった 名前を含むエラーメッセージです。

exception NotImplementedError
この例外は RuntimeError から導出されています。ユーザ定義の 基底クラスにおいて、そのクラスの導出クラスにおいてオーバライドする ことが必要な抽象化メソッドはこの例外を送出しなくてはなりません。 バージョン1.5.2 以降で新規追加された 仕様です。

exception OSError
このクラスは EnvironmentError から導出されており、 主に os モジュールの os.error 例外で使われて います。例外に関連付けられる可能性のある値については、上記の EnvironmentError を参照してください。 バージョン1.5.2 以降で新規追加された 仕様です。

exception OverflowError
算術演算の結果、表現するには大きすぎる値になった場合に送出されます。 これは長整数の演算では起こりません (長整数の演算ではむしろ MemoryError が送出されることになるでしょう)。 C では浮動少数点演算における例外処理の標準化が行われていないので、 ほとんどの浮動少数点演算もチェックされていません。通常の整数では、 オーバフローを起こす全ての演算がチェックされます。例外は左シフトで、 典型的なアプリケーションでは左シフトのオーバフローでは例外を送出する よりもむしろ、オーバフローしたビットを捨てるようにしています。

exception ReferenceError
weakref.proxy() によって生成された弱参照 (weak reference) プロキシを使って、ガーベジコレクションによって処理 された後の参照対象オブジェクトの属性にアクセスした場合に送出されます。 弱参照については weakref モジュールを参照してください。 バージョン2.2 以降で新規追加された 仕様: 以前は weakref.ReferenceError 例外として知られていました。

exception RuntimeError
他のカテゴリに分類できないエラーが検出された場合に送出されます。 関連付けられた値は何が問題だったのかをより詳細に示す文字列です。 (この例外はほとんど過去のバージョンのインタプリタにおける遺物です; この例外はもはやあまり使われることはありません)

exception StopIteration
イテレータの next() メソッドにより、それ以上要素がないことを 知らせるために送出されます。 この例外は、通常のアプリケーションではエラーとはみなされないので、 StandardError ではなく Exception から導出 されています。 バージョン2.2 以降で新規追加された 仕様です。

exception SyntaxError
パーザが構文エラーに遭遇した場合に送出されます。この例外は import 文、exec 文、組み込み関数 evel() や input()、初期化スクリプトの 読み込みや標準入力で (対話的な実行時にも) 起こる可能性があります。

このクラスのインスタンスは、例外の詳細に簡単にアクセスできるように するために、属性 filename、lineno、 offset および text を持ちます。 例外インスタンスに対する str() はメッセージのみを返します。

exception SystemError
インタプリタが内部エラーを発見したが、その状況は全ての望みを 棄てさせるほど深刻ではないように思われる場合に送出されます。 関連づけられた値は (控えめな言い方で) 何がまずいのかを示す文字列です。

Python の作者か、あなたの Python インタプリタを保守している人に このエラーを報告してください。このとき、 Python インタプリタの バージョン (sys.version; Python の対話的セッションを開始した 際にも出力されます)、正確なエラーメッセージ (例外に関連付けられた値) を忘れずに報告してください。 そしてもし可能ならエラーを引き起こしたプログラムのソースコードを 報告してください。

exception SystemExit
この例外は sys.exit() 関数によって送出されます。この例外が 処理されなかった場合、Python インタプリタは終了します; スタックの トレースバックは全く印字されません。関連付けられた値が通常の整数 である場合、システム終了状態を指定しています (exit() 関数に 渡されます); 値が Noneの場合、終了状態はゼロです; (文字列のような) 他の型の場合、そのオブジェクトの値が印字され、終了状態は 1 になります。

この例外のインスタンスは属性 code を持ちます。この値は 終了状態またはエラーメッセージ (標準では None です) に 設定されます。また、この例外は技術的にはエラーではないため、 StandardError からではなく、Exception から 導出されています。

sys.exit() は、後始末のための処理 (try 文の finally 節) が実行されるようにするため、またデバッガが 制御不能になるリスクを冒さずにスクリプトを実行できるようにするために 例外に翻訳されます。即座に終了することが真に強く必要であるとき (例えば、fork() を呼んだ後の子プロセス内) には os._exit() 関数を使うことができます。

exception TypeError
組み込み演算または関数が適切でない型のオブジェクトに対して適用 された際に送出されます。関連付けられる値は型の不整合に関して 詳細を述べた文字列です。

exception UnboundLocalError
関数やメソッド内のローカルな変数に対して参照を行ったが、その変数には 値がバインドされていなかった際に送出されます。NameError のサブクラスです。 バージョン2.0 以降で新規追加された 仕様です。

exception UnicodeError
Unicode に関するエンコードまたはデコードのエラーが発生した際に送出 されます。ValueError のサブクラスです。 バージョン2.0 以降で新規追加された 仕様です。

exception UnicodeEncodeError
Unicode 関連のエラーがエンコード中に発生した際に送出されます。 UnicodeError のサブクラスです。 バージョン2.3 以降で新規追加された 仕様です。

exception UnicodeDecodeError
Unicode 関連のエラーがデコード中に発生した際に送出されます。 UnicodeError のサブクラスです。 バージョン2.3 以降で新規追加された 仕様です。

exception UnicodeTranslateError
Unicode 関連のエラーがコード翻訳に発生した際に送出されます。 UnicodeError のサブクラスです。 バージョン2.3 以降で新規追加された 仕様です。

exception ValueError
組み込み演算や関数が、正しい型だが適切でない値を受け取った場合、 および IndexError のように、より詳細な説明のできない 状況で送出されます。

exception WindowsError
Windows 特有のエラーか、エラー番号が errno 値に対応しない 場合に送出されます。errno および strerror 値は Windows プラットフォーム API の関数、 GetLastError() と FormatMessage() の戻り値から生成されます。 OSError のサブクラスです。 バージョン2.0 以降で新規追加された 仕様です。

exception ZeroDivisionError
除算またモジュロ演算における二つ目の引数がゼロであった場合に 送出されます。関連付けられている値は文字列で、その演算における 被演算子の型を示します。

以下の例外は警告カテゴリとして使われます; 詳細については warnings モジュールを参照してください。

exception Warning
警告カテゴリの基底クラスです。

exception UserWarning
ユーザコードによって生成される警告の基底クラスです。

exception DeprecationWarning
廃用された機能に対する警告の基底クラスです。

exception PendingDeprecationWarning
将来廃用されることになっている機能に対する警告の基底クラスです。

exception SyntaxWarning
曖昧な構文に対する警告の基底クラスです。

exception RuntimeWarning
あいまいなランタイム挙動に対する警告の基底クラスです。

exception FutureWarning
将来意味構成が変わることになっている文の構成に対する警告の基底クラスです。

組み込み例外のクラス階層は以下のようになっています:

    Exception
     +-- SystemExit
     +-- StopIteration
     +-- StandardError
     |    +-- KeyboardInterrupt
     |    +-- ImportError
     |    +-- EnvironmentError
     |    |    +-- IOError
     |    |    +-- OSError
     |    |         +-- WindowsError
     |    +-- EOFError
     |    +-- RuntimeError
     |    |    +-- NotImplementedError
     |    +-- NameError
     |    |    +-- UnboundLocalError
     |    +-- AttributeError
     |    +-- SyntaxError
     |    |    +-- IndentationError
     |    |         +-- TabError
     |    +-- TypeError
     |    +-- AssertionError
     |    +-- LookupError
     |    |    +-- IndexError
     |    |    +-- KeyError
     |    +-- ArithmeticError
     |    |    +-- OverflowError
     |    |    +-- ZeroDivisionError
     |    |    +-- FloatingPointError
     |    +-- ValueError
     |    |    +-- UnicodeError
     |    |        +-- UnicodeEncodeError
     |    |        +-- UnicodeDecodeError
     |    |        +-- UnicodeTranslateError
     |    +-- ReferenceError
     |    +-- SystemError
     |    +-- MemoryError
     +---Warning
      +-- UserWarning
      +-- DeprecationWarning
      +-- PendingDeprecationWarning
      +-- SyntaxWarning
      +-- OverflowWarning
      +-- RuntimeWarning
      +-- FutureWarning
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.10 特殊な属性 Up: 2. 組み込みオブジェクト Next: 2.5 組み込み定数


2.5 組み込み定数

組み込み空間には少しだけ定数があります。以下にそれらの定数を示します:

False
bool 型における、偽を表す値です。 バージョン2.3 以降で新規追加された 仕様です。

True
bool 型における、真を表す値です。 バージョン2.3 以降で新規追加された 仕様です。

None
types.NoneType の唯一の値です。 None は、例えば関数にデフォルトの値が渡されないときのように、 値がないことを表すためにしばしば用いられます。

NotImplemented
``特殊な比較 (rich comparison)'' を行う特殊メソッド (__eq__()、__lt__()、およびその仲間) に対して、 他の型に対しては比較が実装されていないことを示すために返される値です。

Ellipsis
拡張スライス文と同時に用いられる特殊な値です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.4 組み込み例外 Up: 2. 組み込みオブジェクト Next: 3. Python ランタイム サービス


3. Python ランタイム サービス

この章では、PythonインタープリタやPython環境に深く関連する各種の機能を解説します。以下に一覧を示します:

sys | システムパラメータと関数へのアクセス
gc | 循環検出ガベージコレクタのインターフェース。
weakref | 弱参照と弱辞書のサポート。
fpectl | 浮動小数点例外処理の制御。
atexit | 後始末関数の登録と実行。
types | 組み込み型の名前
UserDict | 辞書オブジェクトのためのクラスラッパー。
UserList | リストオブジェクトのためのクラスラッパー。
UserString | 文字列オブジェクトのためのクラスラッパー。
operator | 組み込み関数形式になっている全ての Python の標準演算子。
inspect | 使用中のオブジェクトから、情報とソースコードを取得する。
traceback | スタックトレースの表示や取り出し。
linecache | このモジュールによりテキストファイルの各行にランダムアクセスできます。
pickle | Python オブジェクトからバイトストリームへの変換、およびその逆。
cPickle | pickle の高速バージョンですが、サブクラスはできません。
copy_reg | pickleサポート関数を登録する。
shelve | Python オブジェクトの永続化。
copy | 浅いコピーおよび深いコピー操作。
marshal | Python オブジェクトをバイト列に変換したり、その逆を (異なる拘束条件下で) 行います。
warnings | 警告メッセージを送出したり、その処理方法を制御したり します。
imp | import文の実装へアクセスする。
pkgutil | パッケージの拡張をサポートするユーティリティです。
code | 対話的Pythonインタプリタのための基底クラス。
codeop | (完全ではないかもしれない)Pythonコードをコンパイルする。
pprint | Data pretty printer.
repr | 大きさに制限のある別のrepr()の実装。
new | ランタイム実装オブジェクトの作成のインターフェイス。
site | サイト固有のモジュールを参照する標準の方法。
user | ユーザー設定を参照するための標準的な方法を提供するモジュー ル
__builtin__ | 組み込み関数一式
__main__ | トップレベルスクリプトが実行される環境。
__future__ | Future ステートメントの定義

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.5 組み込み定数 Up: Python ライブラリリファレンス Next: 3.1 sys


3.1 sys -- システムパラメータと関数

このモジュールでは、インタープリタで使用・管理している変数や、インタープ リタの動作に深く関連する関数を定義しています。このモジュールは常に利用可能で す。

argv
Pythonスクリプトに渡されたコマンドライン引数のリスト。argv[0]は スクリプトの名前となりますが、フルパス名かどうかは、オペレーティングシ ステムによって異なります。コマンドライン引数に-cを付けて Pythonを起動した場合、argv[0]は文字列'-c'となります。引 数なしでPythonを起動した場合、argvは長さ0のリストになります。

byteorder
プラットフォームのバイト順を示します。ビッグエンディアン(最上位バ イトが先頭)のプラットフォームでは'big'、リトルエンディアン(最下 位バイトが先頭)では'little'となります。 バージョン2.0 以降で新規追加された 仕様です。

builtin_module_names
コンパイル時にPythonインタープリタに組み込まれた、全てのモジュール名の タプル(この情報は、他の手段では取得することができません。 modules.keys()は、インポートされたモジュールのみのリストを返し ます。)

copyright
Pythonインタープリタの著作権を表示する文字列。

dllhandle
Python DLLのハンドルを示す整数。 利用可能: Windows

displayhook( value)
valueがNone以外の場合、valueをsys.stdoutに 出力して__builtin__._に保存します。

sys.displayhookは、Pythonの対話セッションで入力された式が評価さ れたときに呼び出されます。対話セッションの出力をカスタマイズする場合、 sys.displayhookに引数の数が一つの関数を指定します。

excepthook( type, value, traceback)
指定したトレースバックと例外をsys.stderrに出力します。

例外が発生し、その例外が捕捉されない場合、インタープリタは例外クラス・ 例外インスタンス・トレースバックオブジェクトを引数として sys.excepthookを呼び出します。対話セッション中に発生した場合は プロンプトに戻る直前に呼び出され、Pythonプログラムの実行中に発生した場合 はプログラムの終了直前に呼び出されます。このトップレベルでの例外情報出 力処理をカスタマイズする場合、sys.excepthookに引数の数が三つの 関数を指定します。

__displayhook__
__excepthook__
それぞれ、起動時のdisplayhookとexcepthookの値を保存して います。この値は、displayhookとexcepthookに不正なオブジ ェクトが指定された場合に、元の値に復旧するために使用します。

exc_info( )
この関数は、現在処理中の例外を示す三つの値のタプルを返します。この値 は、現在のスレッド・現在のスタックフレームのものです。現在のスタックフ レームが例外処理中でない場合、例外処理中のスタックフレームが見つかるま で次々とその呼び出し元スタックフレームを調べます。ここで、``例外処理中 ''とは``except節を実行中、または実行した''フレームを指します。どのスタ ックフレームでも、最後に処理した例外の情報のみを参照することができま す。

スタック上で例外が発生していない場合、三つのNoneのタプルを返し ます。例外が発生している場合、(type, value, traceback)を返します。typeは、処理中の例外の型を示します (クラスオブジェクト)。valueは、例外パラメータ (例外に関連する値またはraiseの第二引数。typeが クラスオブジェクトの場合は常にクラスインスタンス)です。traceback は、トレースバックオブジェクトで、例外が発生した時点でのコールスタック をカプセル化したオブジェクトです(リファレンスマニュアル参照)。

exc_clear()が呼び出されると、現在のスレッドで他の例外が発生するか、 又は別の例外を処理中のフレームに実行スタックが復帰するまで、 exc_info()は三つのNoneを返します。

警告: 例外処理中に戻り値のtracebackをローカル変数に代入すると 循環参照が発生し、関数内のローカル変数やトレースバックが参照している全 てのオブジェクトは解放されなくなります。特にトレースバック情報が必要で はなければexctype, value = sys.exc_info()[:2]のように例外型と例 外オブジェクトのみを取得するようにして下さい。もしトレースバックが必要 な場合には、処理終了後にdeleteして下さい。このdeleteは、try ... finally ...で行うと良いでしょう。 注意: Python 2.2 以降では、ガベージコレクションが有効であればこのような 到達不能オブジェクトは自動的に削除されます。しかし、循環参照を作らない ようにしたほうが効率的です。

exc_clear( )
この関数は、現在のスレッドで処理中、又は最後に発生した例外の情報を全てクリア します。この関数を呼び出すと、現在のスレッドで他の例外が発生するか、 又は別の例外を処理中のフレームに実行スタックが復帰するまで、 exc_info()は三つのNoneを返します。

この関数が必要となることは滅多にありません。ロギングやエラー処理などで最後に 発生したエラーの報告を行う場合などに使用します。また、リソースを解放して オブジェクトの終了処理を起動するために使用することもできますが、オブジェクト が実際にされるかどうかは保障の限りではありません。 バージョン2.3 以降で新規追加された 仕様です。

exc_type
exc_value
exc_traceback
リリース 1.5 以降で撤廃された仕様です。 exc_info()を使用してください
これらの変数はグローバル変数なのでスレッド毎の情報を示すことができませ ん。この為、マルチスレッドなプログラムでは安全に参照することはできませ ん。例外処理中でない場合、exc_typeの値はNoneとなり、 exc_valueとexc_tracebackは未定義となります。

exec_prefix

Pythonのプラットフォーム依存なファイルがインストールされているディレク トリ名(サイト固有)。デフォルトでは、この値は'/usr/local'です が、ビルド時にconfigureの--exec-prefix引数で 指定することができます。全ての設定ファイル(pyconfig.hなど)は exec_prefix + '/lib/pythonversion/config'に、共有ライブラ リはexec_prefix + '/lib/pythonversion/lib-dynload'にイン ストールされます(但しversionはversion[:3])。

executable
Pythonインタープリタの実行ファイルの名前を示す文字列。このような名前が 意味を持つシステムでは利用可能。

exit( [arg])
Pythonを終了します。exit()はSystemExitを送出す るので、tryステートメントのfinally節に終了処理を記 述したり、上位レベルで例外を捕捉してexit処理を中断したりすることができ ます。オプション引数argには、終了ステータスとして整数(デフォルト は0）または整数以外の型のオブジェクトを指定することができます。整数を 指定した場合、シェル等は0は``正常終了''、0以外の整数を``異常終了''とし て扱います。多くのシステムでは、有効な終了ステータスは0-127で、これ以 外の値を返した場合の動作は未定義です。システムによっては特定の終了コー ドに個別の意味を持たせている場合がありますが、このような定義は僅かしか ありません。Unixプログラムでは文法エラーの場合には2を、それ以外のエ ラーならば1を返します。argにNoneを指定した場合は、数値の0 を指定した場合と同じです。それ以外のオブジェクトを指定すると、そのオブ ジェクトがsys.stderrに出力され、終了コードをして1を返します。エ ラー発生時にはsys.exit("エラーメッセージ")と書くと、簡単にプロ グラムを終了することができます。

exitfunc
この値はモジュールに存在しませんが、ユーザプログラムでプログラム終了時 に呼び出される終了処理関数として、引数の数が0の関数を設定することがで きます。この関数は、インタープリタ終了時に呼び出されます。 exitfuncに指定することができる終了処理関数は一つだけですので、 複数のクリーンアップ処理が必要な場合はatexitモジュールを使 用してください。 注意: 終了処理関数は、以下の場合には呼び出されません。シグナルでkillされ た場合・Python内部でfatail エラーが発生した場合・os._exit()が呼び 出された場合

getcheckinterval( )
インタプリタの ``チェックインターバル (check interval)'' を 返します; setcheckinterval() を参照してください。 バージョン2.3 以降で新規追加された 仕様です。

getdefaultencoding( )
現在のUnicode処理のデフォルトエンコーディング名を返します。 バージョン2.0 以降で新規追加された 仕様です。

getdlopenflags( )
dlopen()で指定されるフラグを返します。このフラグは dlとDLFCNで定義されています。

利用可能: Unix. バージョン2.2 以降で新規追加された 仕様です。

getfilesystemencoding( )
Unicodeファイル名をシステムのファイル名に変換する際に使用する エンコード名を返します。システムのデフォルトエンコーディングを使用する 場合にはNoneを返します。
  • Windows 9xでは、エンコーディングは ``mbcs'' となります。
  • OS Xでは、エンコーディングは ``utf-8'' となります。
  • Unixでは、エンコーディングはユーザのnl_langinfo(CODESET)の設定となります。 nl_langinfo(CODESET)が失敗するとNoneを返します。
  • Windows NT+では、Unicodeをファイル名として使用することができるので 変換の必要がありません。
バージョン2.3 以降で新規追加された 仕様です。

getrefcount( object)
objectの参照数を返します。objectは(一時的に) getrefcount()からも参照されるため、参照数は予想される数 よりも1多くなります。

getrecursionlimit( )
現在の最大再帰数を返します。最大再帰数は、Pythonインタープリタスタック の最大の深さです。この制限はPythonプログラムが無限に再帰し、Cスタック がオーバーフローしてクラッシュすることを防止するために設けられていま す。この値はsetrecursionlimit()で指定することができます。

_getframe( [depth])
コールスタックからフレームオブジェクトを取得します。オプション引数 depthを指定すると、スタックのトップからdepthだけ下のフレー ムオブジェクトを取得します。depthがコールスタックよりも深けれ ば、ValueErrorが発生します。depthのデフォルト値は0 で、この場合はコールスタックのトップのフレームを返します。

この関数は、内部的な、特殊な用途にのみ利用することができます。

getwindowsversion( )
実行中のWindowsのバージョンを示す、以下の値のタプルを返します： major, minor, build, platform, text。 textは文字列、それ以外の値は整数です。

platformは、以下の値となります:

0 (VER_PLATFORM_WIN32s)
Win32s on Windows 3.1.
1 (VER_PLATFORM_WIN32_WINDOWS)
Windows 95/98/ME
2 (VER_PLATFORM_WIN32_NT)
Windows NT/2000/XP
3 (VER_PLATFORM_WIN32_CE)
Windows CE.

この関数は、Win32 GetVersionEx()関数を呼び出します。詳細は マイクロソフトのドキュメントを参照してください。

利用可能: Windows. バージョン2.3 以降で新規追加された 仕様です。

hexversion
整数にエンコードされたバージョン番号。この値は新バージョン(正規リリー ス以外であっても)ごとにかならず増加します。例えば、Python 1.5.2以降で のみ動作するプログラムでは、以下のようなチェックを行います。

if sys.hexversion >= 0x010502F0:
    # use some advanced feature
    ...
else:
    # use an alternative implementation or warn the user
    ...
"hexversion"はhex()で16進数に変換しなければ値の意味が わかりません。より読みやすいバージョン番号が必要な場合には version_infoを使用してください。 バージョン1.5.2 以降で新規追加された 仕様です。

last_type
last_value
last_traceback
通常は定義されておらず、捕捉されない例外が発生してインタープリタがエ ラーメッセージとトレースバックを出力した場合にのみ設定されます。この値 は、対話セッション中にエラーが発生したとき、デバッグモジュールをロード (例:"import pdb; pdb.pm()"など。詳細は9を参照)して発 生したエラーを調査する場合に利用します。デバッガをロードすると、プログ ラムを再実行せずに情報を取得することができます。

変数の意味は、上のexc_info()の戻り値と同じです。対話セッシ ョンを実行するスレッドは常に一つだけなので、exc_typeのようにス レッドに関する問題は発生しません。

maxint
Pythonの整数型でサポートされる、最大の整数。この値は最低でも2**31-1で す。最大の負数は-maxint-1となります。正負の最大数が非対称です が、これは2の補数計算を行うためです。

maxunicode
Unicode文字の最大のコードポイントを示す整数。この値は、オプション設定 でUnicode文字の保存形式としてUSC-2とUCS-4のいずれを指定したかによって 異なります。

modules
ロード済みモジュールのモジュール名とモジュールオブジェクトの辞書。強制 的にモジュールを再読み込みする場合などに使用します。この辞書からモジ ュールを削除するのは、reload()の呼び出 しと等価ではありません。

path
モジュールを検索するパスを示す文字列のリスト。PYTHONPATH環境 変数と、インストール時に指定したデフォルトパスで初期化されます。

開始時に初期化された後、リストの先頭(path[0])にはPythonインター プリタを起動するために指定したスクリプトのディレクトリが挿入されます。 スクリプトのディレクトリがない(インタープリタで対話セッションで起 動された時や、スクリプトを標準入力から読み込む場合など)場合、 path[0]には空文字列となり、Pythonはカレントディレクトリからモジ ュールの検索を開始します。スクリプトディレクトリは、 PYTHONPATHで指定したディレクトリの前に挿入されますので 注意が必要です。

必要に応じて、プログラム内で自由に変更することができます。

バージョン2.3 以降で変更された 仕様: Unicode 文字列が無視されなくなりました。

platform
プラットフォームを識別する文字列(例: 'sunos5', 'linux1' 等)。pathにプラットフォーム別のサブディレクトリを追加する場 合などに利用します。

prefix
サイト固有の、プラットフォームに依存しないファイルを格納するディレクト リを示す文字列。デフォルトでは'/usr/local'になります。この値は ビルド時にconfigureスクリプトの--prefix引数で 指定する事ができます。Pythonライブラリの主要部分は prefix + '/lib/pythonversion'にインストールされ、プラット フォーム非依存なヘッダファイル(pyconfig.h以外)は prefix + '/include/pythonversion'に格納されます (但しversionはversion[:3])。

ps1
ps2
インタープリタの一次プロンプト、二次プロンプトを指定する文字列。対話 モードで実行中のみ定義され、初期値は'>>> 'と '... 'です。文字列以外のオブジェクトを指定した場合、インタープ リタが対話コマンドを読み込むごとにオブジェクトのstr()を評価 します。この機能は、動的に変化するプロンプトを実装する場合に利用しま す。

setcheckinterval( interval)
インタープリタの``チェック間隔''を示す整数値を指定します。この値はスレ ッドスイッチやシグナルハンドラのチェックを行う周期を決定します。デフォ ルト値は100で、この場合 100 の仮想命令を実行するとチェックを行いま す。この値を大きくすればスレッドを利用するプログラムのパフォーマンスが 向上します。この値が<=0以下の場合、全ての仮想命令を実行するたび にチェックを行い、レスポンス速度と最大になりますがオーバヘッドもまた最 大となります。

setdefaultencoding( name)
現在のUnicode処理のデフォルトエンコーディング名を設定します。 nameに一致するエンコーディングが見つからない場合、 LookupErrorが発生します。この関数は、siteモジ ュールの実装が、sitecustomizeモジュールから使用するためだけに 定義されています。siteから呼び出された後、この関数は sysから削除されます。 バージョン2.0 以降で新規追加された 仕様です。

setdlopenflags( n)
インタープリタが拡張モジュールをロードする時、dlopen()で使 用するフラグを設定します。sys.setdlopenflags(0)とすれば、モジ ュールインポート時にシンボルの遅延解決を行う事ができます。シンボルを拡 張モジュール間で共有する場合には、 sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL)と指定します。 フラグの定義名はdlかDLFCNで定義されています。 DLFCNが存在しない場合、h2pyスクリプトを使って /usr/include/dlfcn.hから生成することができます。

利用可能: Unix. バージョン2.2 以降で新規追加された 仕様です。

setprofile( profilefunc)
システムのプロファイル関数を登録します。プロファイル関数は、 Pythonのソースコードプロファイルを行う関数で、Pythonで記述する ことができます。詳細は10を参照してく ださい。プロファイル関数はトレース関数(settrace()参照)と 似ていますが、ソース行が実行されるごとに呼び出されるのではなく、関数の 呼出しと復帰時のみ呼び出されます(例外が発生している場合でも、復帰時の イベントは発生します)。プロファイル関数はスレッド毎に設定することがで きますが、プロファイラはスレッド間のコンテキスト切り替えを検出すること はできません。従って、マルチスレッド環境でのプロファイルはあまり意味が ありません。setprofileは常にNoneを返します。

setrecursionlimit( limit)
Pythonインタープリタの、スタックの最大の深さをlimitに設定しま す。この制限はPythonプログラムが無限に再帰し、Cスタックがオーバーフ ローしてクラッシュすることを防止するために設けられています。

limitの最大値はプラットフォームによって異なります。深い再帰処理 が必要な場合にはプラットフォームがサポートしている範囲内でより大きな値 を指定することができますが、この値が大きすぎればクラッシュするので注意 が必要です。

settrace( tracefunc)
システムのトレース関数を登録します。トレース関数 はPythonのソースデバッガを実装するために使用することができます。 9.2の``How It Works,''を参照してください。 トレース関数はスレッド毎に設定することができますの で、デバッグを行う全てのスレッドでsettrace()を呼び出し、ト レース関数を登録してください。

stdin
stdout
stderr
インタープリタの標準入力・標準出力・標準エラー出力に対応するファイルオ ブジェクト。stdinはスクリプトの読み込みを除く全ての入力処理で使 用され、input()やraw_input() もstdinから読み込みます。stdout は、printや式の評価結果、input()・ raw_input()のプロンプトの出力先となります。インタープリタの プロンプトは(ほとんど)stderrに出力されます。stdoutと stderrは必ずしも組み込みのファイルオブジェクトである必要はな く、write()メソッドを持つオブジェクトであれば使用することがで きます。stdoutとstderrを別のオブジェクトに置き換えても、 os.popen()・os.system() ・osの exec*()などから起動されたプロセスが使用する標準I/Oストリー ムは変更されません。

__stdin__
__stdout__
__stderr__
それぞれ起動時のstdin・stderr・stdoutの値を保存し ます。終了処理時や、不正なオブジェクトが指定された場合に元の値に復旧す るために使用します。

tracebacklimit
捕捉されない例外が発生した時、出力されるトレースバック情報の最大レベル 数を指定する整数値(デフォルト値は1000)。0以下の値が設定 された場合、トレースバック情報は出力されず例外型と例外値のみが出力さ れます。

version
Pythonインタープリタのバージョンとビルド番号・使用コンパイラなどの情 報を示す文字列で、'バージョン(#ビルド番号, ビルド日付, ビルド時間)[コンパイラ]'となります。先 頭の三文字は、バージョンごとのインストール先ディレクトリ内を識別するた めに使用されます。例:

>>> import sys
>>> sys.version
'1.5.2 (#0 Apr 13 1999, 10:51:12) [MSC 32 bit (Intel)]'

api_version
使用中のインタープリタのC APIバージョン。Pythonと拡張モジュール間の不 整合をデバッグする場合などに利用できます。 バージョン2.3 以降で新規追加された 仕様です。

version_info
バージョン番号を示す５つの値のタプル:major, minor, micro, releaselevel, serial releaselevel以外は 全て整数です。releaselevelの値は、'alpha', 'beta', 'candidate', or 'final'の何れかです。Python 2.0の version_infoは、(2, 0, 0, 'final', 0)となります。 バージョン2.0 以降で新規追加された 仕様です。

warnoptions
この値は、warnings framework内部のみ使用され、変更することはできませ ん。詳細はwarningsを参照してください。

winver
Windowsプラットフォームで、レジストリのキーとなるバージョン番号。 Python DLLの文字列リソース 1000に設定されています。通常、この値は versionの先頭三文字となります。この値は参照専用で、別の値を 設定してもPythonが使用するレジストリキーを変更することはできません。 利用可能: Windows.

参考資料:

siteモジュール:
This describes how to use .pth files to extend sys.path.

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3. Python ランタイム サービス Up: 3. Python ランタイム サービス Next: 3.2 gc


3.2 gc -- ガベージコレクタ インターフェース

gcモジュールは、インタプリタのビルドオプションで循環ガベージコ レクタを有効にした場合のみ使用することができます（デフォルトで有効）。も し無効になっている場合にこのモジュールをインポートすると、 ImportErrorが発生します。

このモジュールは、循環ガベージコレクタの無効化・検出頻度の調整・デバッグ オブションの設定などを行うインターフェースを提供します。また、検出した到 達不能オブジェクトのうち、解放する事ができないオブジェクトを参照する事も できます。循環ガベージコレクタはPyhonの参照カウントを補うためのものです ので、もしプログラム中で循環参照が発生しない事が明らかな場合には検出をす る必要はありません。自動検出は、gc.disable()で停止する事ができま す。メモリリークをデバッグするときには、 gc.set_debug(gc.DEBUG_LEAK)とします。

gcモジュールは、以下の関数を提供しています。

enable( )
自動ガベージコレクションを有効にします。

disable( )
自動ガベージコレクションを無効にします。

isenabled( )
自動ガベージコレクションが有効なら真を返します。

collect( )
全ての検出を行います。全ての世代を検査し、検出した到達不可オブジェクトの 数を返します。

set_debug( flags)
ガベージコレクションのデバッグフラグを設定します。デバッグ情報は sys.stderrに出力されます。デバッグフラグは、下の値の組み合わせ を指定する事ができます。

get_debug( )
現在のデバッグフラグを返します。

get_objects( )
現在、追跡しているオブジェクトのリストを返します。このリストには、戻り値 のリスト自身は含まれていません。 バージョン2.2 以降で新規追加された 仕様です。

set_threshold( threshold0[, threshold1[, threshold2]])
ガベージコレクションの閾値（検出頻度）を指定します。threshold0を0 にすると、検出は行われません。

GCは、オブジェクトを、走査された回数に従って3世代に分類します。新しいオ ブジェクトは最も若い（0世代）に分類されます。もし、そのオブジェク トがガベージコレクションで削除されなければ、次に古い世代に分類されます。 もっとも古い世代は2世代で、この世代に属するオブジェクトは他の世代 に移動しません。ガベージコレクタは、最後に検出を行ってから生成・削除した オブジェクトの数をカウントしており、この数によって検出を開始します。オブ ジェクトの生成数 - 削除数 がthreshold0より大きくなると、検出を開始 します。最初は0世代のオブジェクトのみが検査されます。0世代 の検査がthreshold1回実行されると、1世代のオブジェクトの検 査を行います。同様に、1世代がthreshold2回検査されると、 2世代の検査を行います。

get_threshold( )
現在の検出閾値を、(threshold0, threshold1, threshold2)のタプルで返します。

get_referrers( *objs)
objsで指定したオブジェクトのいずれかを参照しているオブジェクトのリストを 返します。この関数では、ガベージコレクションをサポートしているコンテナの みを返します。他のオブジェクトを参照していても、ガベージコレクションをサ ポートしていない拡張型は含まれません。

尚、戻り値のリストには、すでに参照されなくなっているが、循環参照の一部で まだガベージコレクションで回収されていないオブジェクトも含まれるので注意 が必要です。有効なオブジェクトのみを取得する場合、 get_referrers()の前にcollect()を呼び出してくださ い。 バージョン2.2 以降で新規追加された 仕様です。

get_referents( *objs)
引数で指定したオブジェクトのいずれかから参照されている、全てのオブジェクト のリストを返します。参照先のオブジェクトは、引数で指定したオブジェクトの Cレベルメソッドtp_traverseで取得し、全てのオブジェクトが直接到達 可能な全てのオブジェクトを返すわけではありません。tp_traverseは ガベージコレクションをサポートするオブジェクトのみが実装しており、ここで 取得できるオブジェクトは循環参照の一部となる可能性のあるオブジェクトのみ です。従って、例えば整数オブジェクトが直接到達可能であっても、このオブジェクトは 戻り値には含まれません。 バージョン2.3 以降で新規追加された 仕様です。

以下の変数は読み込み専用です。(変更することはできますが、再バインドする 事はできません。）

garbage
到達不能であることが検出されたが、解放する事ができないオブジェクトのリス ト（回収不能オブジェクト）。デフォルトでは、__del__()メソッドを 持つオブジェクトのみが格納されます。 3.1

__del__()メソッドを持つオブジェクトが循環参照に含まれている場 合、その循環参照全体と、循環参照からのみ到達する事ができるオブジェクトは 回収不能となります。このような場合には、Pythonは安全に__del__() を呼び出す順番を決定する事ができないため、自動的に解放することはできませ ん。もし安全な解放順序がわかるのであれば、garbageリストを参照して 循環参照を破壊する事ができます。循環参照を破壊した後でも、そのオブジェク トはgarbageリストから参照されているため、解放されません。解放する ためには、循環参照を破壊した後、del gc.garbage[:]のように garbageからオブジェクトを削除する必要があります。一般的には __del__()を持つオブジェクトが循環参照の一部とはならないように配 慮し、garbageはそのような循環参照が発生していない事を確認するため に利用する方が良いでしょう。

DEBUG_SAVEALLが設定されている場合、全ての到達不能オブジェクト は解放されずにこのリストに格納されます。

以下はset_debug()に指定することのできる定数です。

DEBUG_STATS
検出中に統計情報を出力します。この情報は、検出頻度を最適化する際に有益で す。

DEBUG_COLLECTABLE
見つかった回収可能オブジェクトの情報を出力します。

DEBUG_UNCOLLECTABLE
見つかった回収不能オブジェクト（到達不能だが、ガベージコレクションで解放 する事ができないオブジェクト）の情報を出力します。回収不能オブジェクト は、garbadeリストに追加されます。

DEBUG_INSTANCES
DEBUG_COLLECTABLEかDEBUG_UNCOLLECTABLEが設定されて いる場合、見つかったインスタンスオブジェクトの情報を出力します。

DEBUG_OBJECTS
DEBUG_COLLECTABLEかDEBUG_UNCOLLECTABLEが設定されて いる場合、見つかったインスタンスオブジェクト以外のオブジェクトの情報を出 力します。

DEBUG_SAVEALL
設定されている場合、全ての到達不能オブジェクトは解放されずに garbageに追加されます。これはプログラムのメモリリークをデバッグす るときに便利です。

DEBUG_LEAK
プログラムのメモリリークをデバッグするときに指定します。 （DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALLと同じ。）

... 持つオブジェクトのみが格納されます。3.1
Python 2.2より前のバージョンでは、__del__()メソッドを 持つオブジェクトだけでなく、全ての到達不能オブジェクトが格納されてい た。）
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.1 sys Up: 3. Python ランタイム サービス Next: 3.3 weakref


3.3 weakref -- 弱参照

バージョン2.1 以降で新規追加された 仕様です。

weakrefモジュールは、Pythonプログラマがオブジェクトへの 弱参照を作成できるようにします。

以下では、用語リファレント (referent) は弱参照が参照するオブジェクトを 意味します。

オブジェクトに対する弱参照は、そのオブジェクトを生かしておくのに 十分な条件にはなりません: あるリファレントに対する参照が弱参照しか 残っていない場合、ガベージコレクション機構は自由にリファレントを破壊し、 そのメモリを別の用途に再利用できます。弱参照の主な用途は、 巨大なオブジェクトを保持するキャッシュやマップ型の実装において、 キャッシュやマップ型にあるという理由だけオブジェクトを存続させたくない 場合です。 例えば、巨大なバイナリ画像のオブジェクトがたくさんあり、 それぞれに名前を関連付けたいとします。 Python の辞書型を使って 名前を画像に対応付けたり画像を名前に対応付けたりすると、 画像オブジェクトは辞書内のキーや値に使われているため存続しつづける ことになります。weakref モジュールが提供している WeakKeyDictionary や WeakValueDictionary クラスは その代用で、対応付けを構築するのに弱参照を使い、キャッシュや マップ型に存在するという理由だけでオブジェクトを存続させないように します。 例えば、もしある画像オブジェクトが WeakValueDictionary の 値になっていた場合、最後に残った画像オブジェクトへの参照を 弱参照マップ型が保持していれば、ガーベジコレクションはこのオブジェクトを 再利用でき、画像オブジェクトに対する弱参照内の対応付けはそのまま 削除されます。

WeakKeyDictionary や WeakValueDictionary は 弱参照を使って実装されていて、キーや値がガーベジコレクションによって回収された ことを弱参照辞書に知らせるような弱参照オブジェクトのコールバック関数を 設定しています。

ほとんどのプログラムが、いずれかの弱参照辞書型を使うだけで必要を満たせるはずです -- 自作の弱参照辞書を直接作成する必要は普通はありません。とはいえ、 弱参照辞書の実装に使われている低水準の機構は、高度な利用を行う際に恩恵を うけられるよう weakref モジュールで公開されています。

すべてのオブジェクトを弱参照できるわけではありません。 弱参照できるオブジェクトは、クラスインスタンス、(Cではなく) Pythonで書かれた関数、 (束縛および非束縛の両方の)メソッドです。弱参照をサポートするために拡張型を簡単に作れます。 詳細については、3.3.3節 ``拡張型における弱参照''を読んでください。

ref( object[, callback])
objectへの弱参照を返します。リファレントがまだ生きているならば、 元のオブジェクトは参照オブジェクトの呼び出しで取り出せす。 リファレントがもはや生きていないならば、参照オブジェクトを呼び出したときに None を返します。 callback を与えた場合、オブジェクトをまさに後始末処理しようとするときに 呼び出します。このとき弱参照オブジェクトはcallback の唯一のパラメタとして 渡されます。リファレントはもはや利用できません。

同じオブジェクトに対してたくさんの弱参照を作れます。 それぞれの弱参照に対して登録されたコールバックは、 もっとも新しく登録されたコールバックからもっとも古いものへと呼び出されます。

コールバックが発生させた例外は標準エラー出力に書き込まれますが、伝搬させられません。 それらはオブジェクトの__del__()メソッドが発生させる例外とまったく同様の 方法で処理されます。

objectがハッシュ可能ならば、弱参照はハッシュ可能です。それらはobjectが 削除された後でもそれらのハッシュ値を保持します。objectが削除されてから初めて hash()が呼び出された場合に、その呼び出しはTypeErrorを発生させます。

弱参照は等価性のテストをサポートしていますが、順序をサポートしていません。 参照がまだ生きているならば、callbackに関係なく二つの参照はそれらの リファレントと同じ等価関係を持ちます。リファレントのどちらか一方が削除された場合、 参照オブジェクトが同じオブジェクトである場合に限り、その参照は等価です。

proxy( object[, callback])
弱参照を使うobjectへのプロキシを返します。弱参照オブジェクトとともに 用いられる明示的な参照外しを要求する代わりに、これはほとんどのコンテキストに おけるプロキシの利用をサポートします。objectが呼び出し可能かどうかに依存して、 返されるオブジェクトはProxyTypeまたはCallableProxyTypeのどちらか一方の 型を持ちます。プロキシオブジェクトはリファレントに関係なくハッシュ可能ではありません。 これによって、それらの基本的な変更可能という性質に関係する多くの問題を避けています。 そして、辞書のキーとしてそれらの利用を妨げます。callbackはref()関数の 同じ名前のパラメータと同じものです。

getweakrefcount( object)
objectを参照する弱参照とプロキシの数を返します。

getweakrefs( object)
objectを参照するすべての弱参照とプロキシオブジェクトのリストを返します。

class WeakKeyDictionary( [dict])
キーを弱く参照するマッピングクラス。もはやキーへの強い参照がなくなったときに、 辞書のエントリは捨てられます。アプリケーションの他の部分が所有するオブジェクトへ 属性を追加することもなく、それらのオブジェクトに追加データを関連づけるために これを使うことができます。これは属性へのアクセスをオーバーライドするオブジェクトに 特に便利です。

注意: 注意: WeakKeyDictionary は Python 辞書型の上に作られているので、 反復処理を行うときにはサイズ変更してはなりません。WeakKeyDictionary の場合、反復処理の最中にプログラムが行った操作が、(ガベージコレクションの副作用として) 「魔法のように」辞書内の要素を消し去ってしまうため、確実なサイズ変更は困難なのです。

class WeakValueDictionary( [dict])
値を弱く参照するマッピングクラス。値への強い参照がもはや存在しなくなったときに、辞書のエントリは捨てられます。

ReferenceType
弱参照オブジェクトのための型オブジェクト。

ProxyType
呼び出し可能でないオブジェクトのプロキシのための型オブジェクト。

CallableProxyType
呼び出し可能なオブジェクトのプロキシのための型オブジェクト。

ProxyTypes
プロキシのためのすべての型オブジェクトを含むシーケンス。これは両方のプロキシ型の名前付けに依存しないで、オブジェクトがプロキシかどうかのテストをより簡単にできます。

exception ReferenceError
プロキシオブジェクトが使われても、元のオブジェクトがガーベジコレクションされてしまっているときに発生する例外。これは標準のReferenceError例外と同じです。

参考資料:

PEP 0205, Weak References
この機能の提案と理論的根拠。初期の実装と他の言語における類似の機能についての情報へのリンクを含んでいます。

  • 3.3.1 弱参照オブジェクト
  • 3.3.2 例
  • 3.3.3 拡張型における弱参照
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.2 gc Up: 3. Python ランタイム サービス Next: 3.3.1 弱参照オブジェクト


3.3.1 弱参照オブジェクト

弱参照オブジェクトは属性あるいはメソッドを持ちません。しかし、リファレントがまだ存在するならば、呼び出すことでそのリファレントを取得できるようにします:

>>> import weakref
>>> class Object:
...     pass
...
>>> o = Object()
>>> r = weakref.ref(o)
>>> o2 = r()
>>> o is o2
True

リファレントがもはや存在しないならば、参照オブジェクトの呼び出しはNoneを返します:

>>> del o, o2
>>> print r()
None

弱参照オブジェクトがまだ生きているかどうかのテストは、式ref() is not Noneを用いて行われます。通常、参照オブジェクトを使う必要があるアプリケーションコードはこのパターンに従います:

# rは弱参照オブジェクト
o = r()
if o is None:
    # リファレントがガーベジコレクトされた
    print "Object has been allocated; can't frobnicate."
else:
    print "Object is still live!"
    o.do_something_useful()

``生存性(liveness)''のテストを個々に行うと、スレッド化されたアプリケーションにおいて競合状態を作り出します。弱参照が呼び出される前に、他のスレッドは弱参照が無効になる原因となり得ます。上で示したイディオムは、シングルスレッド化されたアプリケーションと同じくスレッド化されたアプリケーションにおいて安全です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.3 weakref Up: 3.3 weakref Next: 3.3.2 例


3.3.2 例

この簡単な例では、アプリケーションが以前に参照したオブジェクトを取り出すためにオブジェクトIDを利用する方法を示します。オブジェクトに生きたままであることを強制することなく、オブジェクトのIDは他のデータ構造の中で使えます。しかし、そうする場合は、オブジェクトはまだIDによって取り出せます。

import weakref

_id2obj_dict = weakref.WeakValueDictionary()

def remember(obj):
    oid = id(obj)
    _id2obj_dict[oid] = obj
    return oid

def id2obj(oid):
    return _id2obj_dict[oid]

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.3.1 弱参照オブジェクト Up: 3.3 weakref Next: 3.3.3 拡張型における弱参照


3.3.3 拡張型における弱参照

実装の目的の一つは、弱参照によって恩恵を受けない数のような型のオブジェクトにオーバーヘッドを負わせることなく、どんな型でも弱参照メカニズムに加わることができるようにすることです。

弱く参照可能なオブジェクトに対して、弱参照メカニズムを使うために、拡張はPyObject*フィールドをインスタンス構造に含んでいなければなりません。オブジェクトのコンストラクタによって、それはNULL に初期化しなければなりません。対応する型オブジェクトのtp_weaklistoffsetフィールドをフィールドのオフセットに設定することもしなければなりません。また、Py_TPFLAGS_HAVE_WEAKREFSをtp_flagsスロットへ追加する必要もあります。例えば、インスタンス型は次のような構造に定義されます:

typedef struct {
    PyObject_HEAD
    PyClassObject *in_class;       /* クラスオブジェクト */
    PyObject      *in_dict;        /* 辞書 */
    PyObject      *in_weakreflist; /* 弱参照のリスト */
} PyInstanceObject;

インスタンスに対して静的に宣言される型オブジェクトはこのように定義されます:

PyTypeObject PyInstance_Type = {
    PyObject_HEAD_INIT(&PyType_Type)
    0,
    "module.instance",

    /* 簡単のためにたくさんのものを省略... */

    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_WEAKREFS   /* tp_flags */
    0,                                          /* tp_doc */
    0,                                          /* tp_traverse */
    0,                                          /* tp_clear */
    0,                                          /* tp_richcompare */
    offsetof(PyInstanceObject, in_weakreflist), /* tp_weaklistoffset */
};

型コンストラクタは弱参照リストをNULL に初期化する責任があります:

static PyObject *
instance_new() {
    /* 簡単のために他の初期化を省略 */

    self->in_weakreflist = NULL;

    return (PyObject *) self;
}

さらに一つだけ追加すると、どんな弱参照でも取り除くためには、デストラクタは弱参照マネージャを呼び出す必要があります。オブジェクトの破壊のどんな他の部分が起きる前にこれを行うべきですが、弱参照リストが非NULL である場合はこれが要求されるだけです:

static void
instance_dealloc(PyInstanceObject *inst)
{
    /* 必要なら一時オブジェクトを割り当ててください。
       しかし、まだ破壊しないでください。
     */

    if (inst->in_weakreflist != NULL)
        PyObject_ClearWeakRefs((PyObject *) inst);

    /* 普通にオブジェクトの破壊を進めてください。 */
}
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.3.2 例 Up: 3.3 weakref Next: 3.4 fpectl


3.4 fpectl -- 浮動小数点例外の制御

利用可能な条件: Unix.

ほとんどのコンピュータはいわゆるIEEE-754標準に準拠した浮動小数点演算を実行します。実際のどんなコンピュータでも、浮動小数点演算が普通の浮動小数点数では表せない結果になることがあります。例えば、次を試してください。

>>> import math
>>> math.exp(1000)
inf
>>> math.exp(1000) / math.exp(1000)
nan

(上の例は多くのプラットホームで動作します。DEC Alphaは例外かもしれません。) "Inf"は"infinity(無限)"を意味するIEEE-754における特殊な非数値の値で、"nan"は"not a number(数ではない)"を意味します。ここで留意すべき点は、その計算を行うようにPythonに求めたときに非数値の結果以外に特別なことは何も起きないというです。事実、それはIEEE-754標準に規定されたデフォルトのふるまいで、それで良ければここで読むのを止めてください。

いくつかの環境では、誤った演算がなされたところで例外を発生し、処理を止めることがより良いでしょう。fpectlモジュールはそんな状況で使うためのものです。いくつかのハードウェア製造メーカーの浮動小数点ユニットを制御できるようにします。つまり、IEEE-754例外Division by Zero、OverflowあるいはInvalid Operationが起きたときはいつでもSIGFPEが生成させるように、ユーザが切り替えられるようにします。あなたのpythonシステムを構成しているCコードの中へ挿入される一組のラッパーマクロと協力して、SIGFPEは捕捉され、Python FloatingPointError例外へ変換されます。

fpectlモジュールは次の関数を定義しています。また、所定の例外を発生します:

turnon_sigfpe( )
SIGFPEを生成するように切り替え、適切なシグナルハンドラを設定します。

turnoff_sigfpe( )
浮動小数点例外のデフォルトの処理に再設定します。

exception FloatingPointError
turnon_sigfpe()が実行された後に、IEEE-754例外であるDivision by Zero、OverflowまたはInvalid operationの一つを発生する浮動小数点演算は、次にこの標準Python例外を発生します。

  • 3.4.1 例
  • 3.4.2 制限と他に考慮すべきこと
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.3.3 拡張型における弱参照 Up: 3. Python ランタイム サービス Next: 3.4.1 例


3.4.1 例

以下の例はfpectlモジュールの使用を開始する方法とモジュールのテスト演算について示しています。

>>> import fpectl
>>> import fpetest
>>> fpectl.turnon_sigfpe()
>>> fpetest.test()
overflow        PASS
FloatingPointError: Overflow

div by 0        PASS
FloatingPointError: Division by zero
  [ more output from test elided ]
>>> import math
>>> math.exp(1000)
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
FloatingPointError: in math_1

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.4 fpectl Up: 3.4 fpectl Next: 3.4.2 制限と他に考慮すべきこと


3.4.2 制限と他に考慮すべきこと

特定のプロセッサをIEEE-754浮動小数点エラーを捕らえるように設定することは、現在アーキテクチャごとの基準に基づきカスタムコードを必要とします。あなたの特殊なハードウェアを制御するためにfpectlを修正することもできます。

IEEE-754例外のPython例外への変換には、ラッパーマクロPyFPE_START_PROTECTとPyFPE_END_PROTECTがあなたのコードに適切な方法で挿入されていることが必要です。Python自身はfpectlモジュールをサポートするために修正されていますが、数値解析にとって興味ある多くの他のコードはそうではありません。

fpectlモジュールはスレッドセーフではありません。

参考資料:

このモジュールがどのように動作するのかについてより学習するときに、ソースディストリビューションの中のいくつかのファイルは興味を引くものでしょう。インクルードファイルInclude/pyfpe.hでは、このモジュールの実装について同じ長さで議論されています。Modules/fpetestmodule.cには、いくつかの使い方の例があります。多くの追加の例がObjects/floatobject.cにあります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.4.1 例 Up: 3.4 fpectl Next: 3.5 atexit


3.5 atexit -- 終了ハンドラ

バージョン2.0 以降で新規追加された 仕様です。

atexitモジュールは後始末関数を登録するための一つの関数を定義します。このような登録された関数はインタープリタが終了するときに自動的に実行されます。

注意: プログラムがシグナルで停止させられたとき、Pythonの致命的な内部エラーが検出されたとき、あるいはos._exit()が呼び出されたときには、このモジュールを通して登録された関数は呼び出されません。

これはsys.exitfunc変数がはたす機能の代わりのインターフェイスです。

注意: sys.exitfuncを設定する他のコードとともに使用した場合には、このモジュールが正しく動作しないと思われます。特に、他のコアPythonモジュールはプログラマの知らないところでatexitを自由に使えます。sys.exitfuncを使う著者は、代わりにatexitを使うコードに変換すべきです。sys.exitfuncを設定するコードを変換するもっとも簡単な方法は、atexitをインポートしてsys.exitfuncへ束縛されていた関数を登録することです。

register( func[, *args[, **kargs]])
終了時に実行される関数としてfuncを登録します。すべてのfuncへ渡すオプションの引数を、register()へ引数としてわたさなければなりません。

通常のプログラムの終了時、例えばsys.exit()が呼び出されるとき、あるいは、メインモジュールの実行が完了したときに、登録されたすべての関数は後入先出順に呼び出されます。より低レベルのモジュールは通常より高レベルのモジュールより前にインポートされ、従ってより後で後始末するということが想定されています。

参考資料:

readlineモジュール:
readlineヒストリファイルを読み書きするためのatexitの有用な例。.

  • 3.5.1 atexit 例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.4.2 制限と他に考慮すべきこと Up: 3. Python ランタイム サービス Next: 3.5.1 atexit 例


3.5.1 atexit 例

次の簡単な例では、インポートされたときにモジュールがファイルからカウンタを初期化する方法を示しています。また、プログラムが終了したときにアプリケーションがこのモジュールを明示的に呼び出さなくても、自動的にカウンタの更新された値を保存する方法を示しています。

try:
    _count = int(open("/tmp/counter").read())
except IOError:
    _count = 0

def incrcounter(n):
    global _count
    _count = _count + n

def savecounter():
    open("/tmp/counter", "w").write("%d" % _count)

import atexit
atexit.register(savecounter)

register()に指定した位置パラメータとキーワードパラメータは、 登録した関数を呼び出す際に渡されます。

def goodbye(name, adjective):
    print 'Goodbye, %s, it was %s to meet you.' % (name, adjective)

import atexit
atexit.register(goodbye, 'Donny', 'nice')

# or:
atexit.register(goodbye, adjective='nice', name='Donny')
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.5 atexit Up: 3.5 atexit Next: 3.6 types


3.6 types -- 組み込み型の名前

このモジュールは標準のPythonインタプリタで使われているオブジェクト の型について、名前を定義しています(拡張モジュールで定義されている型を除 く)。このモジュールは以下に列挙している以外の名前をエクスポートしないの で、"from types import *"のように使っても安全です。このモジュールの 将来のバージョンで追加される名前は、"Type"で終わる予定です。

関数での典型的な利用方法は、以下のように引数の型によって異なる動作をする 場合です:

from types import *
def delete(mylist, item):
    if type(item) is IntType:
       del mylist[item]
    else:
       mylist.remove(item)

Python 2.2以降では、int() や str()のような ファクトリ関数は、型の名前となりましたので、typesを使用する 必要はなくなりました。上記のサンプルは、以下のように記述する事が 推奨されています。

def delete(mylist, item):
    if isinstance(item, int):
       del mylist[item]
    else:
       mylist.remove(item)

このモジュールは以下の名前を定義しています。

NoneType
Noneの型です。

TypeType
typeオブジェクトの型です (type()などによって返 されます)。

BooleanType
boolのTrueとFalseの型です。これは組み込み関数の bool()のエイリアスです。

IntType
整数の型です(e.g. 1)。

LongType
長整数の型です(e.g. 1L)。

FloatType
浮動小数点数の型です(e.g. 1.0)。

ComplexType
複素数の型です(e.g. 1.0j)。 Pythonが複素数のサポートなしでコンパイルされていた場合には 定義されません。

StringType
文字列の型です(e.g. 'Spam')。

UnicodeType
Unicode文字列の型です(e.g. u'Spam')。 Pythonがユニコードのサポートなしでコンパイルされていた場合には 定義されません。

TupleType
タプルの型です(e.g. (1, 2, 3, 'Spam'))。

ListType
リストの型です(e.g. [0, 1, 2, 3])。

DictType
辞書の型です(e.g. {'Bacon': 1, 'Ham': 0})。

DictionaryType
DictTypeの別名です。

FunctionType
ユーザー定義の関数またはlambdaの型です。

LambdaType
FunctionTypeの別名です。

GeneratorType
ジェネレータ関数の呼び出しによって生成されたイテレータオブジェクトの型で す。 バージョン2.2 以降で新規追加された 仕様です。

CodeType
compile()関数などによって返されるコード オブジェクトの型です。

ClassType
ユーザー定義のクラスの型です。

InstanceType
ユーザー定義のクラスのインスタンスの型です。

MethodType
ユーザー定義のクラスのインスタンスのメソッドの型です。

UnboundMethodType
MethodTypeの別名です。

BuiltinFunctionType
len() や sys.exit()のような組み込み関数の型です。

BuiltinMethodType
BuiltinFunctionの別名です。

ModuleType
モジュールの型です。

FileType
sys.stdoutのようなopenされたファイルオブジェクトの型です。

XRangeType
xrange()関数によって返されるrangeオブジェ クトの型です。

SliceType
slice()関数によって返されるオブジェクトの 型です。

EllipsisType
Ellipsisの型です。

TracebackType
sys.exc_tracebackに含まれるようなトレースバックオブジェクトの型です。

FrameType
フレームオブジェクトの型です。 トレースバックオブジェクトtbのtb.tb_frameなどです。

BufferType
buffer()関数によって作られるバッファオブ ジェクトの型です。

StringTypes
文字列型のチェックを簡単にするためのStringTypeと UnicodeTypeを含むシーケンスです。 UnicodeTypeは実行中の版のPythonに含まれている場合にだけ含まれるの で、2つの文字列型のシーケンスを使うよりこれを使う方が移植性が高くなります。 例: isinstance(s, types.StringTypes). バージョン2.2 以降で新規追加された 仕様です。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.5.1 atexit 例 Up: 3. Python ランタイム サービス Next: 3.7 UserDict


3.7 UserDict -- 辞書オブジェクトのためのクラスラッパー

注意: このモジュールは後方互換性のためだけに残されています。Python 2.2より前のバージョンのPythonで動作する必要のないコードを書いているのならば、組み込みdict型から直接サブクラス化することを検討してください。

このモジュールは辞書オブジェクトのラッパーとして働くクラスを定義します。独自の辞書に似たクラスのために役に立つ基底クラスで、これを継承し既存のメソッドをオーバーライドしたり、あるいは、新しいものを追加したりすることができます。このような方法で、辞書に新しい振る舞いを追加できます。

最小限のマッピングインターフェイスをすでに持っているクラスのために、モジュールはすべての辞書メソッドを定義しているmixinも定義しています。これによって、shelveモジュールのような辞書の代わりをする必要があるクラスを書くことが非常に簡単になります。

UserDictモジュールはUserDictクラスとDictMixinを定義しています:

class UserDict( [initialdata])
辞書をシミュレートするクラス。インスタンスの内容は通常の辞書に保存され、UserDictインスタンスのdata属性を通してアクセスできます。initialdataが与えられれば、dataはその内容で初期化されます。他の目的のために使えるように、initialdataへの参照が保存されないことがあるということに注意してください。

マッピングのメソッドと演算(節2.3.7を参照)に加えて、UserDictインスタンスは次の属性を提供します:

data
UserDictクラスの内容を保存するために使われる実際の辞書。

class DictMixin( )
__getitem__、__setitem__、__delitem__およびkeys といった最小の辞書インタフェースを既に持っているクラスのために、全ての辞書メソッドを定義する mixin です。

このmixinはスーパークラスとして使われるべきです。上のそれぞれのメソッドを 追加することで、より多くの機能がだんだん追加されます。 例えば、__delitem__ 以外の全てのメソッドを定義すると、使えないのは popとpopitem だけになります。

4 つの基底メソッドに加えて、__contains__、__iter__ およびiteritemsを定義すれば、順次効率化を果たすことができます。

mixin はサブクラスのコンストラクタについて何も知らないので、 __init__() や copy() は定義していません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.6 types Up: 3. Python ランタイム サービス Next: 3.8 UserList


3.8 UserList -- リストオブジェクトのためのクラスラッパー

注意: このモジュールは後方互換性のためだけに残されています。Python 2.2より前のバージョンのPythonで動作する必要のないコードを書いているのならば、組み込みlist型から直接サブクラス化することを検討してください。

このモジュールはリストオブジェクトのラッパーとして働くクラスを定義します。独自のリストに似たクラスのために役に立つ基底クラスで、これを継承し既存のメソッドをオーバーライドしたり、あるいは、新しいものを追加したりすることができます。このような方法で、リストに新しい振る舞いを追加できます。

UserListモジュールはUserListクラスを定義しています:

class UserList( [list])
リストをシミュレートするクラス。インスタンスの内容は通常のリストに保存され、UserListインスタンスのdata属性を通してアクセスできます。インスタンスの内容は最初にlistのコピーに設定されますが、デフォルトでは空リスト[]です。listは通常のPythonリストか、UserList(またはサブクラス)のインスタンスのどちらかです。

変更可能シーケンスのメソッドと演算(節2.3.6を参照)に加えて、UserListインスタンスは次の属性を提供します:

data
UserListクラスの内容を保存するために使われる実際のPythonリストオブジェクト。

サブクラス化の要件: UserListのサブクラスは引数なしか、あるいは一つの引数のどちらかとともに呼び出せるコンストラクタを提供することが期待されます。新しいシーケンスを返すリスト演算は現在の実装クラスのインスタンスを作成しようとします。そのために、データ元として使われるシーケンスオブジェクトである一つのパラメータとともにコンストラクタを呼び出せると想定しています。

導出クラスがこの要求に従いたくないならば、このクラスがサポートしているすべての特殊メソッドはオーバーライドされる必要があります。その場合に提供される必要のあるメソッドについての情報は、ソースを参考にしてください。

バージョン2.0 以降で変更された 仕様: Pythonバージョン1.5.2と1.6では、コンストラクタが引数なしで呼び出し可能であることと変更可能なdata属性を提供するということも要求されます。Pythonの初期のバージョンでは、導出クラスのインスタンスを作成しようとはしません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.7 UserDict Up: 3. Python ランタイム サービス Next: 3.9 UserString


3.9 UserString -- 文字列オブジェクトのためのクラスラッパー

注意: このモジュールのUserStringクラスは後方互換性のためだけに残されています。Python 2.2より前のバージョンのPythonで動作する必要のないコードを書いているのならば、UserStringを使う代わりに組み込みstr型から直接サブクラス化することを検討してください(組み込みのMutableStringと等価なものはありません)。

このモジュールは文字列オブジェクトのラッパーとして働くクラスを定義します。独自の文字列に似たクラスのために役に立つ基底クラスで、これを継承し既存のメソッドをオーバーライドしたり、あるいは、新しいものを追加したりすることができます。このような方法で、文字列に新しい振る舞いを追加できます。

これらのクラスは実際のクラスやユニコードオブジェクトに比べてとても効率が悪いということに注意した方がよいでしょう。これは特にMutableStringに対して当てはまります。

UserStringモジュールは次のクラスを定義しています:

class UserString( [sequence])
文字列またはユニコード文字列オブジェクトをシミュレートするクラス。インスタンスの内容は通常の文字列またはユニコード文字列オブジェクトに保存され、UserStringインスタンスのdata属性を通してアクセスできます。インスタンスの内容は最初にsequenceのコピーに設定されます。sequenceは通常のPython文字列またはユニコード文字列、UserString(またはサブクラス)のインスタンス、あるいは組み込みstr()関数を使って文字列に変換できる任意のシーケンスのいずれかです。

class MutableString( [sequence])
このクラスは上のUserStringから導出され、変更可能になるように文字列を再定義します。変更可能な文字列は辞書のキーとして使うことができません。なぜなら、辞書はキーとして変更不能なオブジェクトを要求するからです。このクラスの主な目的は、辞書のキーとして変更可能なオブジェクトを使うという試みを捕捉するために、継承と__hash__()メソッドを取り除く(オーバーライドする)必要があることを示す教育的な例を提供することです。そうしなければ、非常にエラーになりやすく、突き止めることが困難でしょう。

文字列とユニコードオブジェクトのメソッドと演算(節8、``文字列メソッド''を参照)に加えて、UserStringインスタンスは次の属性を提供します:

data
UserStringクラスの内容を保存するために使われる実際のPython文字列またはユニコードオブジェクト。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.8 UserList Up: 3. Python ランタイム サービス Next: 3.10 operator


3.10 operator -- 関数形式の標準演算子

operator モジュールは、Python 固有の各演算子に対応している C 言語で実装された関数セットを提供します。例えば、 operator.add(x, y) は式 x+y と等価です。関数名は 特殊なクラスメソッドとして扱われます; 便宜上、先頭と末尾の "__" を取り除いたものも提供されています。

これらの関数はそれぞれ、オブジェクトの比較、論理演算、数学演算、 配列操作、および抽象型テストに分類されます。

オブジェクト比較関数は全てのオブジェクトで有効で、関数の名前は サポートする大小比較演算子からとられています:

lt( a, b)
le( a, b)
eq( a, b)
ne( a, b)
ge( a, b)
gt( a, b)
__lt__( a, b)
__le__( a, b)
__eq__( a, b)
__ne__( a, b)
__ge__( a, b)
__gt__( a, b)

これらは  a および b の大小比較を行います。
特に、
lt(a, b) は a < b、
le(a, b) は a <= b、
eq(a, b) は a == b、
ne(a, b) は a != b、
gt(a, b) は a > b、
そして
ge(a, b) は a >= b
と等価です。

組み込み関数 cmp() と違って、これらの関数はどのような 値を返してもよく、ブール代数値として解釈できてもできなくても かまいません。大小比較の詳細については Python リファレンスマニュアル を参照してください。 バージョン2.2 以降で新規追加された 仕様です。

論理演算もまた全てのオブジェクトに対して適用することができ、 真値テスト、同一性テストおよびブール演算をサポートします:

not_( o)
__not__( o)

not o の結果を返します。(オブジェクトのインスタンス には __not__() メソッドは適用されないので注意してください; この操作を定義しているのはインタプリタコアだけです。結果は __nonzero__() および __len__() メソッドによって 影響されます。)

truth( o)
o が真の場合 True を返し、そうでない場合 False を返します。この関数はboolのコンストラクタ呼び出しと同等です。

is_( a, b)
a is b を返します。オブジェクトの同一性をテストします。

is_not( a, b)
a is not b を返します。オブジェクトの同一性をテストします。

演算子で最も多いのは数学演算およびビット単位の演算です:

abs( o)
__abs__( o)
o の絶対値を返します。

add( a, b)
__add__( a, b)
数値 a および b について a + b を 返します。

and_( a, b)
__and__( a, b)
a と b の論理積を返します。

div( a, b)
__div__( a, b)
__future__.division が有効でない場合には a / b を返します。``古い(classic)'' 除算としても知られています。

floordiv( a, b)
__floordiv__( a, b)
a // b を返します。 バージョン2.2 以降で新規追加された 仕様です。

inv( o)
invert( o)
__inv__( o)
__invert__( o)
o のビット単位反転を返します。~o と 同じです。Python 2.0 では名前 invert() および __invert__() が追加されました。

lshift( a, b)
__lshift__( a, b)
a の b ビット左シフトを返します。

mod( a, b)
__mod__( a, b)
a % b を返します。

mul( a, b)
__mul__( a, b)
数値 a および b について a * b を返します。

neg( o)
__neg__( o)
o の符号反転を返します。

or_( a, b)
__or__( a, b)
a と b の論理和を返します。

pos( o)
__pos__( o)
o の符号非反転を返します。

pow( a, b)
__pow__( a, b)
数値 a および b について a ** b を返します。 バージョン2.3 以降で新規追加された 仕様です。

rshift( a, b)
__rshift__( a, b)
a の b ビット右シフトを返します。

sub( a, b)
__sub__( a, b)
a - b を返します。

truediv( a, b)
__truediv__( a, b)
__future__.division が有効な場合 a / b を返します。除算としても知られています。 バージョン2.2 以降で新規追加された 仕様です。

xor( a, b)
__xor__( a, b)
a および b の排他的論理和を返します

配列を扱う演算子には以下のようなものがあります:

concat( a, b)
__concat__( a, b)
配列 a および b について a + b を返します。

contains( a, b)
__contains__( a, b)
b in a を調べた結果を返します。 演算子が反転しているので注意してください。関数名 __contains__() は Python 2.0 で追加されました。

countOf( a, b)
a の中に b が出現する回数を返します。

delitem( a, b)
__delitem__( a, b)
a でインデクスが b の要素を削除します。

delslice( a, b, c)
__delslice__( a, b, c)
a でインデクスが b から c-1 のスライス要素を 削除します。

getitem( a, b)
__getitem__( a, b)
a でインデクスが b の要素を削除します。 Return the value of a at index b.

getslice( a, b, c)
__getslice__( a, b, c)
a でインデクスが b から c-1 のスライス要素を 返します。

indexOf( a, b)
a で最初に b が出現する場所のインデクスを返します。

repeat( a, b)
__repeat__( a, b)
配列 a と整数 b について a * b を返します。

sequenceIncludes( ...)
リリース 2.0 以降で撤廃された仕様です。 contains() を使ってください。
contains() の別名です。

setitem( a, b, c)
__setitem__( a, b, c)
a でインデクスが b の要素の値を c に設定します。

setslice( a, b, c, v)
__setslice__( a, b, c, v)
a でインデクスが b から c-1 のスライス要素の 値を配列 v に設定します。

operator モジュールでは、オブジェクトの型を調べるための 述語演算子も定義しています。注意: これらの関数が返す結果について 誤って理解しないよう注意してください; インスタンスオブジェクトに 対して常に信頼できる値を返すのは isCallable() だけです。例えば以下のようになります:

>>> class C:
...     pass
...
>>> import operator
>>> o = C()
>>> operator.isMappingType(o)
True

isCallable( o)
リリース 2.0 以降で撤廃された仕様です。 callable() を使ってください。
オブジェクト o を関数のように呼び出すことができる場合真を 返し、それ以外の場合 false を返します。関数、バインドおよび非バインド メソッド、クラスオブジェクト、および __call__() メソッド をサポートするインスタンスオブジェクトは真を返します。

isMappingType( o)
オブジェクト o がマップ型インタフェースをサポートする場合に 真を返します。辞書および全てのインスタンスオブジェクトに対しては、 この値は真になります。警告: インタフェース自体が誤った定義に なっているため、あるインスタンスが完全なマップ型プロトコルを備えて いるかを調べる信頼性のある方法は存在しません。このため、この関数 によるテストはさほど便利ではありません。

isNumberType( o)
オブジェクト o が数値を表現している場合に真を返します。 C で実装された全ての数値型、およびそれらのインスタンスオブジェクト 全て対して、この値は真になります。警告: インタフェース自体が 誤った定義になっているため、あるインスタンスが完全な数値型の インタフェースをサポートしているかを調べる信頼性のある方法は存在 しません。このため、この関数によるテストはさほど便利ではありません。

isSequenceType( o)
o が配列プロトコルをサポートする場合に真を返します。 配列メソッドを C で定義している全てのオブジェクトに対して、この値 は真になります。 警告: インタフェース自体が 誤った定義になっているため、あるインスタンスが完全な配列型の インタフェースをサポートしているかを調べる信頼性のある方法は存在 しません。このため、この関数によるテストはさほど便利ではありません。

例: 0 から 256 までの序数を文字に対応付ける 辞書を構築します。

>>> import operator
>>> d = {}
>>> keys = range(256)
>>> vals = map(chr, keys)
>>> map(operator.setitem, [d]*len(keys), keys, vals)

  • 3.10.1 演算子から関数への対応表
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.9 UserString Up: 3. Python ランタイム サービス Next: 3.10.1 演算子から関数への対応表


3.10.1 演算子から関数への対応表

下のテーブルでは、個々の抽象的な操作が、どのように Python 構文上の 各演算子や operator モジュールの関数に対応しているか を示しています。

操作 | 構文 | 関数
加算 | a + b | add(a, b)
結合 | seq1 + seq2 | concat(seq1, seq2)
包含テスト | o in seq | contains(seq, o)
除算 | a / b | __future__.division が無効な場合の div(a, b) #
除算 | a / b | __future__.division が有効な場合の truediv(a, b) #
除算 | a // b | floordiv(a, b)
論理積 | a & b | and_(a, b)
排他的論理和 | a ^ b | xor(a, b)
ビット反転 | ~ a | invert(a)
論理和 | a | b | or_(a, b)
べき乗 | a ** b | pow(a, b)
インデクス指定の代入 | o[k] = v | setitem(o, k, v)
インデクス指定の削除 | del o[k] | delitem(o, k)
インデクス指定 | o[k] | getitem(o, k)
左シフト | a << b | lshift(a, b)
剰余 | a % b | mod(a, b)
積算 | a * b | mul(a, b)
(算術)否 | - a | neg(a)
(論理)否 | not a | not_(a)
右シフト | a >> b | rshift(a, b)
配列の反復 | seq * i | repeat(seq, i)
スライス指定の代入 | seq[i:j] = values | setslice(seq, i, j, values)
スライス指定の削除 | del seq[i:j] | delslice(seq, i, j)
スライス指定 | seq[i:j] | getslice(seq, i, j)
文字列書式化 | s % o | mod(s, o)
減算 | a - b | sub(a, b)
真値テスト | o | truth(o)
順序付け | a < b | lt(a, b)
順序付け | a <= b | le(a, b)
等価性 | a == b | eq(a, b)
不等性 | a != b | ne(a, b)
順序付け | a >= b | ge(a, b)
順序付け | a > b | gt(a, b)

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.10 operator Up: 3.10 operator Next: 3.11 inspect


3.11 inspect -- 使用中のオブジェクトを調査

バージョン2.1 以降で新規追加された 仕様です。

inspectは、モジュール・クラス・メソッド・関数・トレースバック・ フレームオブジェクト・コードオブジェクトなどのオブジェクトから情報を取得 する関数を定義しており、クラスの内容を調べる、メソッドのソースコードを取 得する、関数の引数リストを取得して整形する、トレースバックから必要な情報 だけを取得して表示する、などの処理を行う場合に利用します。

このモジュールの機能は、型チェック・ソースコードの取得・クラス／関数から 情報を取得・インタープリタのスタック情報の調査、の4種類に分類する事がで きます。

  • 3.11.1 型とメンバ
  • 3.11.2 ソース参照
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.10.1 演算子から関数への対応表 Up: 3. Python ランタイム サービス Next: 3.11.1 型とメンバ


3.11.1 型とメンバ

getmembers()は、クラスやモジュールなどのオブジェクトからメンバを取得します。 名前が``is''で始まる 11 個の関数は、getmembers()の2番目の引数として利用する事ができますし、以下のような特殊属性を参照できるかどうか調べる時にも使えます。

Type | Attribute | Description | Notes
module | __doc__ | ドキュメント文字列 |
 | __file__ | ファイル名(組み込みモジュールには存在しない |
class | __doc__ | ドキュメント文字列 |
 | __module__ | クラスを定義しているモジュールの名前 |
method | __doc__ | ドキュメント文字列 |
 | __name__ | メソッドが定義された時の名前 |
 | im_class | メソッドを呼び出すために必要なクラスオブジェクト | (1)
 | im_func | メソッドを実装している関数オブジェクト |
 | im_self | メソッドに結合しているインスタンス、またはNone |
function | __doc__ | ドキュメント文字列 |
 | __name__ | 関数が定義された時の名前 |
 | func_code | 関数をコンパイルしたバイトコードを格納するコード オブジェクト |
 | func_defaults | 引数のデフォルト値のタプル |
 | func_doc | (__doc__と同じ) |
 | func_globals | 関数を定義した時のグローバル名前空間 |
 | func_name | (__name__と同じ) |
traceback | tb_frame | このレベルのフレームオブジェクト |
 | tb_lasti | 最後に実行しようとしたバイトコード中のインストラク ションを示すインデックス。 |
 | tb_lineno | 現在のPythonソースコードの行番号 |
 | tb_next | このオブジェクトの内側(このレベルから呼び出された) のトレースバックオブジェクト |
frame | f_back | 外側 (このフレームを呼び出した)のフレームオブジ ェクト |
 | f_builtins | このフレームで参照している組み込み名前空間 |
 | f_code | このフレームで実行しているコードオブジェクト |
 | f_exc_traceback | このフレームで例外が発生した場合にはトレー スバックオブジェクト。それ以外ならNone |
 | f_exc_type | このフレームで例外が発生した場合には例外型。それ 以外ならNone |
 | f_exc_value | このフレームで例外が発生した場合には例外の値。 それ以外ならNone |
 | f_globals | このフレームで参照しているグローバル名前空間 |
 | f_lasti | 最後に実行しようとしたバイトコードのインデックス。 |
 | f_lineno | 現在のPythonソースコードの行番号 |
 | f_locals | このフレームで参照しているローカル名前空間 |
 | f_restricted | 制限実行モードなら1、それ以外なら0 |
 | f_trace | このフレームのトレース関数、またはNone |
code | co_argcount | 引数の数(*、**引数は含まない) |
 | co_code | コンパイルされたバイトコードそのままの文字列 |
 | co_consts | バイトコード中で使用している定数のタプル |
 | co_filename | コードオブジェクトを生成したファイルのファイル名 |
 | co_firstlineno | Pythonソースコードの先頭行 |
 | co_flags | 以下の値の組み合わせ: 1=optimized | 2=newlocals | 4=*arg | 8=**arg |
 | co_lnotab | 文字列にエンコードした、行番号->バイトコード インデックスへの変換表 |
 | co_name | コードオブジェクトが定義されたときの名前 |
 | co_names | ローカル変数名のタプル |
 | co_nlocals | ローカル変数の数 |
 | co_stacksize | 必要な仮想機械のスタックスペース |
 | co_varnames | 引数名とローカル変数名のタプル |
builtin | __doc__ | ドキュメント文字列 |
 | __name__ | 関数、メソッドの元々の名前 |
 | __self__ | メソッドが結合しているインスタンス、またはNone |

Note:

(1)
バージョン2.2 以降で変更された 仕様: im_class 従来、メソッドを定義しているクラスを参 照するために使用していた

getmembers( object[, predicate])
オブジェクトの全メンバを、(名前, 値)の組み合わせのリストで返します。リ ストはメンバ名でソートされています。predicateが指定されている場 合、predicateの戻り値が真となる値のみを返します。

getmoduleinfo( path)
pathで指定したファイルがモジュールであればそのモジュールがPython でどのように解釈されるかを示す(name, suffix, mode, mtype)のタプルを返し、モジュールでなければ Noneを返します。nameはパッケージ名を含まないモジュール 名、suffixはファイル名からモジュール名を除いた残りの部分(ドット による拡張子とは限らない)、modeはopen()で指定されるフ ァイルモード('r'または'rb')、mtypeは impで定義している整定数のいずれかが指定されます。モジュール タイプに付いてはimpを参照してください。

getmodulename( path)
pathで指定したファイルの、パッケージ名を含まないモジュール名を返 します。この処理は、インタープリタがモジュールを検索する時と同じアルゴ リズムで行われます。ファイルがこのアルゴリズムで見つからない場合には Noneが返ります。

ismodule( object)
オブジェクトがモジュールの場合は真を返します。

isclass( object)
オブジェクトがクラスの場合は真を返します。

ismethod( object)
オブジェクトがメソッドの場合は真を返します。

isfunction( object)
オブジェクトがPythonの関数、または無名(lambda)関数の場合は真を返します。

istraceback( object)
オブジェクトがトレースバックの場合は真を返します。

isframe( object)
オブジェクトがフレームの場合は真を返します。

iscode( object)
オブジェクトがコードの場合は真を返します。

isbuiltin( object)
オブジェクトが組み込み関数の場合は真を返します。

isroutine( object)
オブジェクトがユーザ定義か組み込みの関数・メソッドの場合は真を返します。

ismethoddescriptor( object)
オブジェクトがメソッドデスクリプタの場合に真を返しますが、 ismethod()、isclass() または isfunction() が真の場合には真を返しません。

この機能は Python 2.2 から新たに追加されたもので、例えば int.__add__ は真 になります。 このテストをパスするオブジェクトは __get__ 属性を持ちますが __set__ 属性を持ちません。しかしそれ以上に属性のセットには様々なものがあります。 __name__ は通常見分けることが可能ですし、__doc__ も時には可能です。

デスクリプタを使って実装されたメソッドで、上記のいずれかのテストもパスして いるものは、 ismethoddescriptor() では偽を返します。これは単に 他のテストの方がもっと確実だからです - 例えば、ismethod() をパス したオブジェクトは im_func 属性 (など) を持っていると期待できます。

isdatadescriptor( object)
オブジェクトがデータデスクリプタの場合に真を返します。

データデスクリプタは __get__ および __set__ 属性の両方を持ちます。 データデスクリプタの例は (Python 上で定義された) プロパティや (C で定義された) getset やメンバです。通常、データデスクリプタは __name__ や __doc__ 属性を持ちます (プロパティ、 getset 、メンバは両方の属性を持っています) が、保証されているわけではありません。 バージョン2.3 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.11 inspect Up: 3.11 inspect Next: 3.11.2 ソース参照


3.11.2 ソース参照

getdoc( object)
オブジェクトのドキュメンテーション文字列を取得します。タブはスペースに 展開されます。コードブロックに合わせてインデントされているdocstringを 整形するため、２行目以降では行頭の空白は削除されます。

getcomments( object)
オブジェクトがクラス・関数・メソッドの何れかの場合は、オブジェクトの ソースコードの直後にあるコメント行（複数行）を、単一の文字列として返し ます。オブジェクトがモジュールの場合、ソースファイルの先頭にあるコメン トを返します。

getfile( object)
オブジェクトを定義している（テキストまたはバイナリの）ファイルの名前を 返します。オブジェクトが組み込みモジュール・クラス・関数の場合は TypeError例外が発生します。

getmodule( object)
オブジェクトを定義しているモジュールを推測します。

getsourcefile( object)
オブジェクトを定義しているPythonソースファイルの名前を返します。オブジ ェクトが組み込みモジュール・クラス・関数の場合は、 TypeError例外が発生します。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.11.1 型とメンバ Up: 3.11 inspect Next: 3.12 traceback


3.12 traceback -- スタックトレースの表示や取り出し

このモジュールはPythonプログラムのスタックトレースを抽出し、書式を整え、表示するための標準インターフェースを提供します。モジュールがスタックトレースを表示するとき、Pythonインタープリタの動作を正確に模倣します。インタープリタの``ラッパー''の場合のように、プログラムの制御の元でスタックとレースを表示したいと思ったときに役に立ちます。

モジュールはtracebackオブジェクトを使います -- これは変数sys.exc_traceback(非推奨)とsys.last_tracebackに保存され、sys.exc_info()から三番目の項目として返されるオブジェクト型です。

モジュールは次の関数を定義します:

print_tb( traceback[, limit[, file]])
tracebackからlimitまでスタックトレース項目を出力します。limitが省略されるかNoneの場合は、すべての項目が表示されます。fileが省略されるかNoneの場合は、sys.stderrへ出力されます。それ以外の場合は、出力を受けるためのオープンしたファイルまたはファイルに類似したオブジェクトであるべきです。

print_exception( type, value, traceback[, limit[, file]])
例外情報とtracebackからlimitまでスタックトレース項目をfileへ出力します。これは次のようにすることでprint_tb()とは異なります: (1) tracebackがNoneでない場合は、ヘッダ"Traceback (most recent call last):"を出力します。 (2) スタックトレースの後に例外typeとvalueを出力します。 (3) typeがSyntaxErrorであり、valueが適切な形式の場合は、エラーのおおよその位置を示すカレットを付けて構文エラーが起きた行を出力します。

print_exc( [limit[, file]])
これはprint_exception(sys.exc_type, sys.exc_value, sys.exc_traceback, limit, file)のための省略表現です。(非推奨の変数を使う代わりにスレッドセーフな方法で同じ情報を引き出すために、実際にはsys.exc_info()を使います。)

print_last( [limit[, file]])
これはprint_exception(sys.last_type, sys.last_value, sys.last_traceback, limit, file)の省略表現です。

print_stack( [f[, limit[, file]]])
この関数は呼び出された時点からのスタックトレースを出力します。オプションのf引数は代わりの最初のスタックフレームを指定するために使えます。print_exception()に付いて言えば、オプションのlimitとfile引数は同じ意味を持ちます。

extract_tb( traceback[, limit])
トレースバックオブジェクトtracebackからlimitまで取り出された``前処理済み''スタックトレース項目のリストを返します。スタックトレースの代わりの書式設定を行うために役に立ちます。limitが省略されるかNoneの場合は、すべての項目が取り出されます。``前処理済み''スタックトレース項目とは四つの部分からなる(filename, line number, function name, text)で、スタックトレースに対して通常出力される情報を表しています。textは前と後ろに付いている空白を取り除いた文字列です。ソースが使えない場合はNoneです。

extract_stack( [f[, limit]])
現在のスタックフレームから生のトレースバックを取り出します。戻り値はextract_tb()と同じ形式です。print_stack()について言えば、オプションのfとlimit引数は同じ意味を持ちます。

format_list( list)
extract_tb()またはextract_stack()が返すタプルのリストが与えられると、出力の準備を整えた文字列のリストを返します。結果として生じるリストの中の各文字列は、引数リストの中の同じインデックスの要素に対応します。各文字列は末尾に改行が付いています。その上、ソーステキスト行がNoneでないそれらの要素に対しては、文字列は内部に改行を含んでいるかもしれません。

format_exception_only( type, value)
トレースバックの例外部分の書式を設定します。引数はsys.last_typeとsys.last_valueのような例外の型と値です。戻り値はそれぞれが改行で終わっている文字列のリストです。通常、リストは一つの文字列を含んでいます。しかし、SyntaxError例外に対しては、(出力されるときに)構文エラーが起きた場所についての詳細な情報を示す行をいくつか含んでいます。どの例外が起きたのかを示すメッセージは、常にリストの最後の文字列です。

format_exception( type, value, tb[, limit])
スタックトレースと例外情報の書式を設定します。引数はprint_exception()の対応する引数と同じ意味を持ちます。戻り値は文字列のリストで、それぞれの文字列は改行で終わり、そのいくつかは内部に改行を含みます。これらの行が連結されて出力される場合は、厳密にprint_exception()と同じテキストが出力されます。

format_tb( tb[, limit])
format_list(extract_tb(tb, limit))の省略表現。

format_stack( [f[, limit]])
format_list(extract_stack(f, limit))の省略表現。

tb_lineno( tb)
この関数はトレースバックオブジェクトに設定された現在の行番号をかえします。この関数は必要でした。なぜなら、-OフラグがPythonへ渡されたとき、Pythonの2.3より前のバージョンではtb.tb_linenoが正しく更新されなかったからです。この関数は2.3以降のバージョンでは役に立ちません。

  • 3.12.1 トレースバックの例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.11.2 ソース参照 Up: 3. Python ランタイム サービス Next: 3.12.1 トレースバックの例


3.12.1 トレースバックの例

この簡単な例では基本的なread-eval-printループを実装います。それは標準的なPythonの対話インタープリタループに似ていますが、Pythonのものより便利ではありません。インタープリタループのより完全な実装については、codeモジュールを参照してください。

import sys, traceback

def run_user_code(envdir):
    source = raw_input(">>> ")
    try:
        exec source in envdir
    except:
        print "Exception in user code:"
        print '-'*60
        traceback.print_exc(file=sys.stdout)
        print '-'*60

envdir = {}
while 1:
    run_user_code(envdir)
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.12 traceback Up: 3.12 traceback Next: 3.13 linecache


3.13 linecache -- テキストラインにランダムアクセスする

linecache モジュールは、キャッシュ (一つのファイルから何行も読んでおくのが一般的です)を使って、 内部で最適化を図りつつ、任意のファイルの任意の行を取得するのを可能にします。

このモジュールは traceback モジュールで、インクルードしたソースを フォーマットされたトレースバックで復元するのに使われています。

linecache モジュールでは次の関数が定義されています:

getline( filename, lineno)
filename という名前のファイルから lineno 行目を取得します。 この関数は決して例外を投げません -- エラーの際には '' を返します。 (行末の改行文字は、見つかった行に含まれます。)

filename という名前のファイルが見つからなかった場合、 モジュールの 、つまり、 sys.path で そのファイルを探します。

clearcache( )
キャッシュをクリアします。 それまでに getline() を使って読み込んだファイルの行が必要でなくなったら、 この関数を使ってください。

checkcache( )
キャッシュが有効かチェックします。 キャッシュしたファイルにディスク上で変更があったかもしれなくて、更新が必要な ときにこの関数を使ってください。

サンプル:

>>> import linecache
>>> linecache.getline('/etc/passwd', 4)
'sys:x:3:3:sys:/dev:/bin/sh\n'
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.12.1 トレースバックの例 Up: 3. Python ランタイム サービス Next: 3.14 pickle


3.14 pickle -- Python オブジェクトの整列化

pickle モジュールでは、Python オブジェクトデータ構造を 直列化 (serialize) したり非直列化 (de-serialize) するための 基礎的ですが強力なアルゴリズムを実装しています。 ``Pickle 化 (Pickling)'' は Python のオブジェクト階層をバイト ストリームに変換する過程を指します。``非 Pickle 化 (unpickling)'' はその逆の操作で、バイトストリームをオブジェクト階層に戻すように 変換します。Pickle 化 (及び非 Pickle 化) は、別名 ``直列化 (serialization)'' や ``整列化 (marshalling)'' 3.2 、``平坦化 (flattening)'' として知られていますが、 ここでは混乱を避けるため、用語として ``Pickle 化'' および ``非 Pickle 化'' を使います。

このドキュメントでは pickle モジュールおよび cPickle モジュールの両方について記述します。

... (marshalling)''3.2
marshal モジュールと間違えないように注意 してください

  • 3.14.1 他の Python モジュールとの関係
  • 3.14.2 データストリームの形式
  • 3.14.3 使用法
  • 3.14.4 何を pickle 化したり unpickle 化できるのか?
  • 3.14.5 pickle 化プロトコル
    • 3.14.5.1 通常のクラスインスタンスの pickle 化および unpickle 化
    • 3.14.5.2 拡張型の pickle 化および unpickle 化
    • 3.14.5.3 外部オブジェクトの pickle 化および unpickle 化
  • 3.14.6 Unpickler をサブクラス化する
  • 3.14.7 例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.13 linecache Up: 3. Python ランタイム サービス Next: 3.14.1 他の Python モジュールとの関係


3.14.1 他の Python モジュールとの関係

pickle モジュールには cPickle と呼ばれる 最適化のなされた親類モジュールがあります。名前が示すように、 cPickle は C で書かれており、このため pickle より 1000 倍くらいまで高速になる可能性があります。しかしながら cPickle では Pickler() および Unpickler() クラスのサブクラス化をサポートしていません。 これは cPickle では、これらは関数であってクラスでは ないからです。ほとんどのアプリケーションではこの機能は 不要であり、cPickle の持つ高いパフォーマンスの 恩恵を受けることができます。その他の点では、二つのモジュールに おけるインタフェースはほとんど同じです; このマニュアルでは 共通のインタフェースを記述しており、必要に応じてモジュール間 の相違について指摘します。以下の議論では、pickle と cPickle の総称として ``pickle'' という用語を使う ことにします。

これら二つのモジュールが生成するデータストリームは相互交換 できることが保証されています。

Python には marshal と呼ばれるより原始的な直列化モジュール がありますが、一般的に Python オブジェクトを直列化する方法としては pickle を選ぶべきです。marshal は基本的に .pyc ファイルをサポートするために存在しています。

pickle モジュールはいくつかの点で marshal と明確に異なります:

  • pickle モジュールでは、同じオブジェクトが再度直列化 されることのないよう、すでに直列化されたオブジェクトについて追跡 情報を保持します。marshal はこれを行いません。

    この機能は再帰的オブジェクトと共有オブジェクトの両方に重要な 関わりをもっています。再帰的オブジェクトとは自分自身に対する 参照を持っているオブジェクトです。再帰的オブジェクトは marshal で扱うことができず、実際、再帰的オブジェクトを marshal 化しようと すると Python インタプリタをクラッシュさせてしまいます。 共有オブジェクトは、直列化しようとするオブジェクト階層の異なる 複数の場所で同じオブジェクトに対する参照が存在する場合に生じます。 共有オブジェクトを共有のままにしておくことは、変更可能なオブジェクト の場合には非常に重要です。

  • marshal はユーザ定義クラスやそのインスタンスを 直列化するために使うことができません。pickle は クラスインスタンスを透過的に保存したり復元したりすることができますが、 クラス定義をインポートすることが可能で、かつオブジェクトが保存 された際と同じモジュールで定義されていなければなりません。

  • marshal の直列化フォーマットは Python の異なる バージョンで可搬性があることを保証していません。marshal の本来の仕事は .pyc ファイルのサポートなので、Python を実装する人々には、必要に応じて直列化フォーマットを以前の バージョンと互換性のないものに変更する権限が残されています。 pickle 直列化フォーマットには、全ての Python リリース 間で以前のバージョンとの互換性が保証されています。

pickle モジュールは誤りを含む、あるいは悪意を持って 構築されたデータに対して安全にはされていません。信用できない、 あるいは認証されていないデータ源から受信したデータを逆 pickle 化 しないでください。

直列化は永続化 (persisitence) よりも原始的な概念です; pickle はファイルオブジェクトを読み書きしますが、永続化 されたオブジェクトの名前付け問題や、(より複雑な) オブジェクトに 対する競合アクセスの問題を扱いません。pickle モジュール は複雑なオブジェクトをバイトストリームに変換することができ、 バイトストリームを変換前と同じ内部構造をオブジェクトに変換する ことができます。このバイトストリームの最も明白な用途は ファイルへの書き込みですが、その他にもネットワークを介して送信 したり、データベースに記録したりすることができます。 モジュール shelve はオブジェクトを DBM 形式の データベースファイル上で pickle 化したり unpickle 化したりする ための単純なインタフェースを提供しています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.14 pickle Up: 3.14 pickle Next: 3.14.2 データストリームの形式


3.14.2 データストリームの形式

pickle が使うデータ形式は Python 特有です。そうする ことで、XDRのような 外部の標準が持つ制限 (例えば XDR ではポインタの共有を表現できません) を課せられることがないという利点があります; しかしこれは Python で書かれていないプログラムが pickle 化された Python オブジェクトを 再構築できない可能性があることを意味します。

標準では、pickle データ形式では印字可能な ASCII 表現を 使います。これはバイナリ表現よりも少しかさばるデータになります。 印字可能な ASCII の利用 (とその他の pickle 表現形式が 持つ特徴) の大きな利点は、デバッグやリカバリを目的とした場合に、 pickle 化されたファイルを標準的なテキストエディタで読めるという ことです。

現在、pickle化に使われるプロトコルは、以下の 3 種類です。

  • バージョン 0 のプロトコルは、最初の ASCII プロトコルで、以前のバージョンのPython と後方互換です。

  • バージョン 1 のプロトコルは、古いバイナリ形式で、以前のバージョンの Python と後方互換です。

  • バージョン 2 のプロトコルは、Python 2.3 で導入されました。新しいスタイルのクラスを、より効率よく piclke 化します。

詳細は PEP 307 を参照してください。

protocol を指定しない場合、プロトコル 0 が使われます。protocol に負値か HIGHEST_PROTOCOL を指定すると、有効なプロトコルの内、もっとも高いバージョンのものが使われます。

バージョン2.3 以降で変更された 仕様: bin パラメータは非推奨で、後方互換性のためだけに提供されています。代わりに protocol を使うべきです。

Pickler コンストラクタや dump() および dumps() の引数 bin の値を真に設定することで、少しだけ効率の高いバイナリ 形式を選ぶこともできます。 protocol version >= 1 であるとき、バイナリ形式を使用するからです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.14.1 他の Python モジュールとの関係 Up: 3.14 pickle Next: 3.14.3 使用法


3.14.3 使用法

オブジェクト階層を直列化するには、まず pickler を生成し、続いてpickler の dump() メソッドを呼び出します。データストリームから非直列化 するには、まず unpickler を生成し、続いて unpicklerの load() メ ソッドを呼び出します。pickle モジュールでは以下の定数を提供して います:

HIGHEST_PROTOCOL
有効なプロトコルのうち、最も大きいバージョン。この値は、protocol として渡せます。 バージョン2.3 以降で新規追加された 仕様です。

この手続きを便利にするために、pickle モジュールでは以下の関数を 提供しています:

dump( object, file[, protocol[, bin]])
すでに開かれているファイルオブジェクト file に、object を pickle 化したものを表現する文字列を書き込みます。 Pickler(file, protocol, bin).dump(object) と同じです。

protocol を指定しない場合、プロトコル 0 が使われます。protocol に負値か HIGHEST_PROTOCOL を指定すると、有効なプロトコルの内、もっとも高いバージョンのものが使われます。

バージョン2.3 以降で変更された 仕様: bin パラメータは非推奨で、後方互換性のためだけに提供されています。代わりに protocol を使うべきです。

オプションの bin 引数が真の場合、バイナリ pickle 化形式が使われ ます; そうでない場合 (より低効率の) テキスト pickle 化形式が使われます (以前のバージョンとの互換性のため、こちらが標準になっています)。

file は、単一の文字列引数を受理する write() メソッド を持たなければなりません。従って、 file としては、書き込みのために 開かれたファイルオブジェクト、 StringIO オブジェクト、 その他前述のインタフェースに適合する他のカスタムオブジェクトをとることが できます。

load( file)
すでに開かれているファイルオブジェクト file から文字列を読み出し、 読み出された文字列を pickle 化されたデータ列として解釈して、もとの オブジェクト階層を再構築して返します。Unpickler(file).load() と同じです。

file は、整数引数をとる read() メソッドと、引数の必要 ない readline() メソッドを持たなければなりません。 これらのメソッドは両方とも文字列を返さなければなりません。 従って、 file としては、読み出しのために 開かれたファイルオブジェクト、 StringIO オブジェクト、 その他前述のインタフェースに適合する他のカスタムオブジェクトをとることが できます。

この関数はデータ列の書き込まれているモードがバイナリかそうでないかを 自動的に判断します。

dumps( object[, protocol[, bin]])
object の pickle 化された表現を、ファイルに書き込む代わりに 文字列で返します。

protocol を指定しない場合、プロトコル 0 が使われます。protocol に負値か HIGHEST_PROTOCOL を指定すると、有効なプロトコルの内、もっとも高いバージョンのものが使われます。

バージョン2.3 以降で変更された 仕様: bin パラメータは非推奨で、後方互換性のためだけに提供されています。代わりに protocol を使うべきです。

オプションの bin 引数が真の場合、バイナリの pickle 形式が使われます; そうでない場合、(より低効率の) テキストの pickle 形式が使われます (こちらが標準の設定です)。

loads( string)
pickle 化されたオブジェクト階層を文字列から読み出します。 文字列中で pickle 化されたオブジェクト表現よりも後に続く文字列 は無視されます。

pickle モジュールでは、以下の 3 つの例外も定義しています:

exception PickleError
下で定義されている他の例外で共通の基底クラスです。Exception を継承しています。

exception PicklingError
この例外は unpickle 不可能なオブジェクトが dump() メソッドに 渡された場合に送出されます。

exception UnpicklingError
この例外は、オブジェクトを unpickle 化する際に問題が発生した場合に 送出されます。 unpickle 化中には AttributeError、 EOFError、 ImportError、および IndexError といった他の例外 (これだけとは限りません) も発生する可能性があるので 注意してください。

pickle モジュールでは、2 つの呼び出し可能オブジェクト 3.3として、Pickler および Unpickler を提供しています:

class Pickler( file[, protocol[, bin]])
pickle 化されたオブジェクトのデータ列を書き込むためのファイル類似の オブジェクトを引数にとります。

protocol を指定しない場合、プロトコル 0 が使われます。protocol に負値か HIGHEST_PROTOCOL を指定すると、有効なプロトコルの内、もっとも高いバージョンのものが使われます。

バージョン2.3 以降で変更された 仕様: bin パラメータは非推奨で、後方互換性のためだけに提供されています。代わりに protocol を使うべきです。

オプションの bin を真にすると、 pickler により高効率のバイナリ pickle 形式を使うように指示します。 そうでない場合、ASCII 形式が使われます (こちらの方が標準です)。

file は単一の文字列引数を受理する write() メソッドを 持たなければなりません。従って、 file としては、書き込みのために 開かれたファイルオブジェクト、 StringIO オブジェクト、 その他前述のインタフェースに適合する他のカスタムオブジェクトをとることが できます。

Pickler オブジェクトでは、一つ (または二つ) の public なメソッド を定義しています:

dump( object)
コンストラクタで与えられた、すでに開かれているファイルオブジェクトに object の pickle 化された表現を書き込みます。コンストラクタに渡された bin フラグの値に応じて、バイナリおよびASCII 形式が使われます。

clear_memo( )
picller の ``メモ'' を消去します。メモとは、共有オブジェクトまたは 再帰的なオブジェクトが値ではなく参照で記憶されるようにするために、 pickler がこれまでどのオブジェクトに遭遇してきたかを記憶するデータ 構造です。このメソッドは pickler を再利用する際に便利です。

注意: Python 2.3 以前では、clear_memo() は cPickle で生成された pickler でのみ利用可能でした。pickle モジュール では、pickler は memo と呼ばれる Python 辞書型のインスタンス 変数を持ちます。従って、pickler モジュールにおける pickler のメモを消去は、以下のようにしてできます:

mypickler.memo.clear()

以前のバージョンの Python での動作をサポートする必要のないコードでは、 単に clear_memo() を使ってください。

同じ Pickler のインスタンスに対し、 dump() メソッドを 複数回呼び出すことは可能です。この呼び出しは、対応する Unpickler インスタンスで同じ回数だけ load() を呼び出す操作に対応します。 同じオブジェクトが dump() を複数回呼び出して pickle 化された 場合、load() は全て同じオブジェクトに対して参照を行います 3.4。 。

Unpickler オブジェクトは以下のように定義されています:

class Unpickler( file)
pickle データ列を読み出すためのファイル類似のオブジェクトを引数に 取ります。このクラスはデータ列がバイナリモードかどうかを自動的に 判別します。従って、Pickler のファクトリメソッドのような フラグを必要としません。

file は、整数引数を取る read() メソッド、および引数を 持たない readline() メソッドの、 2 つのメソッドを持ちます。 両方のメソッドとも文字列を返します。従って、 file としては、 読み出しのために開かれたファイルオブジェクト、 StringIO オブジェクト、その他前述のインタフェースに適合する他のカスタム オブジェクトをとることができます。

Unpickler オブジェクトは 1 つ (または 2 つ) の public な メソッドを持っています:

load( )
コンストラクタで渡されたファイルオブジェクトからオブジェクトの pickle 化表現 を読み出し、中に収められている再構築されたオブジェクト階層を返します。

noload( )
load() に似ていますが、実際には何もオブジェクトを生成 しないという点が違います。この関数は第一に pickle 化データ列中で参照されている、``永続化 id'' と呼ばれている 値を検索する上で便利です。 詳細は以下の 3.14.5 を参照してください。

注意: noload() メソッドは現在 cPickle モジュールで生成された Unpickler オブジェクトのみで 利用可能です。pickle モジュールの Unpickler には、 noload() メソッドがありません。

... つの呼び出し可能オブジェクト3.3
pickleでは、これらの呼び出し可能オブジェクトはクラスであり、 サブクラス化してその動作をカスタマイズすることができます。しかし、 cPickle モジュールでは、これらの呼び出し可能オブジェクト はファクトリ関数であり、サブクラス化することができません。 サブクラスを作成する共通の理由の一つは、どのオブジェクトを実際に unpickle するかを制御することです。詳細については 3.14.6 を参照してください。
... は全て同じオブジェクトに対して参照を行います3.4
警告: これは、複数のオブジェクトを pickle 化する際に、オブジェクト やそれらの一部に対する変更を妨げないようにするための仕様です。 あるオブジェクトに変更を加えて、その後同じ Pickler を使って 再度 pickle 化しようとしても、そのオブジェクトは pickle 化しなおされ ません -- そのオブジェクトに対する参照が pickle 化され、Unpickler は変更された値ではなく、元の値を返します。これには 2 つの問題点 : (1) 変更の検出、そして (2) 最小限の変更を整列化すること、があります。 ガーベジコレクションもまた問題になります。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.14.2 データストリームの形式 Up: 3.14 pickle Next: 3.14.4 何を pickle 化したり


3.14.4 何を pickle 化したり unpickle 化できるのか?

以下の型は pickle 化できます:

  • None、 True、および False

  • 整数、長整数、浮動小数点数、複素数

  • 通常文字列および Unicode 文字列

  • pickle 化可能なオブジェクトからなるタプル、リスト、および辞書

  • モジュールのトップレベルで定義されている関数

  • モジュールのトップレベルで定義されている組込み関数

  • モジュールのトップレベルで定義されているクラス

  • __dict__ または __setstate__() を pickle 化 できる上記クラスのインスタンス (詳細は 3.14.5 節を 参照してください)

pickle 化できないオブジェクトを pickle 化しようとすると、 PicklingError 例外が送出されます; この例外が起きた 場合、背後のファイルには未知の長さのバイト列が書き込まれて しまいます。

(組み込みおよびユーザ定義の) 関数は、値ではなく ``完全記述された'' 参照名として pickle 化されるので注意してください。これは、 関数の定義されているモジュールの名前と一緒と併せ、関数名 だけが pickle 化されることを意味します。 関数のコードや関数の属性は何も pickle 化されません。 従って、定義しているモジュールは unpickle 化環境で import 可能で なければならず、そのモジュールには指定されたオブジェクトが含まれて いなければなりません。そうでない場合、例外が送出されます 3.5 。

クラスも同様に名前参照で pickle 化されるので、unpickle 化環境には 同じ制限が課せられます。クラス中のコードやデータは何も pickle 化 されないので、以下の例ではクラス属性 attr が unpickle 化環境 で復元されないことに注意してください:

class Foo:
    attr = 'a class attr'

picklestring = pickle.dumps(Foo)

pickle 化可能な関数やクラスがモジュールのトップレベルで定義されて いなければならないのはこれらの制限のためです。

同様に、クラスのインスタンスが pickle 化された際、そのクラスの コードおよびデータはオブジェクトと一緒に pickle 化されることは ありません。インスタンスのデータのみが pickle 化されます。 この仕様は、クラス内のバグを修正したりメソッドを追加した後でも、 そのクラスの以前のバージョンで作られたオブジェクトを読み出せるように 意図的に行われています。あるクラスの多くのバージョンで使われる ような長命なオブジェクトを作ろうと計画しているなら、 そのクラスの __setstate__() メソッドによって適切な変換が 行われるようにオブジェクトのバージョン番号を入れておくとよいかも しれません。

... いなければなりません。そうでない場合、例外が送出されます3.5
送出される例外は ImportError や AttributeError になるはずですが、他の例外も 起こりえます
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.14.3 使用法 Up: 3.14 pickle Next: 3.14.5 pickle 化プロトコル


3.14.5 pickle 化プロトコル

この節では pickler/unpickler と直列化対象のオブジェクトとの間の インタフェースを定義する ``pickle 化プロトコル'' について記述します。 このプロトコルは自分のオブジェクトがどのように直列化されたり非直列化 されたりするかを定義し、カスタマイズし、制御するための標準的な方法を 提供します。この節での記述は、unpickle 化環境を不信な pickle 化データ に対して安全にするために使う特殊なカスタマイズ化についてはカバー していません; 詳細は 3.14.6 を参照してください。

  • 3.14.5.1 通常のクラスインスタンスの pickle 化および unpickle 化
  • 3.14.5.2 拡張型の pickle 化および unpickle 化
  • 3.14.5.3 外部オブジェクトの pickle 化および unpickle 化
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.14.4 何を pickle 化したり Up: 3.14 pickle Next: 3.14.5.1 通常のクラスインスタンスの pickle 化および


3.14.6 Unpickler をサブクラス化する

デフォルトでは、逆 pickle 化は pickle 化されたデータ中に見つかった クラスを import することになります。自前の unpickler をカスタマイズ することで、何が unpickle 化されて、どのメソッドが呼び出されるか を厳密に制御することはできます。しかし不運なことに、厳密に なにを行うべきかはpickle と cPickle のどちらを使うかで異なります 3.10。

pickle モジュールでは、Unpickler からサブクラスを 導出し、load_global() メソッドを上書きする必要があります。 load_global() は pickle データ列から最初の 2 行を読まなければ ならず、ここで最初の行はそのクラスを含むモジュールの名前、2 行目は そのインスタンスのクラス名になるはずです。 次にこのメソッドは、例えばモジュールをインポートして属性を掘り起こす などしてクラスを探し、発見されたものを unpickler のスタックに置きます。 その後、このクラスは空のクラスの __class__ 属性に代入する 方法で、クラスの __init__() を使わずにインスタンスを魔法のように 生成します。 あなたの作業は (もしその作業を受け入れるなら)、unpickler のスタックの 上に push された load_global() を、unpickle しても安全だと 考えられる何らかのクラスの既知の安全なバージョンにすることです。 あるいは全てのインスタンスに対して unpickling を許可したくないなら エラーを送出してください。このからくりがハックのように 思えるなら、あなたは間違っていません。このからくりを動かすには、 ソースコードを参照してください。

cPickle では事情は多少すっきりしていますが、十分という わけではありません。何を unpickle 化するかを制御するには、 unpickler の find_global 属性を関数か None に 設定します。属性が None の場合、インスタンスを unpickle しようとする試みは全て UnpicklingError を送出します。 属性が関数の場合、この関数はモジュール名またはクラス名を 受理し、対応するクラスオブジェクトを返さなくてはなりません。 このクラスが行わなくてはならないのは、クラスの探索、必要な import のやり直しです。そしてそのクラスのインスタンスが unpickle 化されるのを防ぐためにエラーを送出することもできます。

以上の話から言えることは、アプリケーションが unpickle 化する 文字列の発信元については非常に高い注意をはらわなくてはならないと いうことです。

... のどちらを使うかで異なります3.10
注意してください: ここで記述されている機構は内部の属性とメソッドを 使っており、これらはPython の将来のバージョンで変更される対象に なっています。われわれは将来、この挙動を制御するための、 pickle および cPickle の両方で動作する、 共通のインタフェースを提供するつもりです。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.14.5.3 外部オブジェクトの pickle 化および Up: 3.14 pickle Next: 3.14.7 例


3.14.7 例

以下にあるクラスについてどうやって picklle 化の振る舞いを変更 するかのれいを示します。TextReader クラスはファイルを開き、 readline() メソッドが呼ばれるたびに行番号と行の内容を 返します。TextReader インスタンスが pickle 化された場合、 ファイルオブジェクト 以外の 全ての属性が保存されます。 インスタンスが unpickle 化された際、ファイルは再度開かれ、 以前のファイル位置から読み出しを再開します。上記の動作を 実装するために、__setstat__() および __getstate__() メソッドが使われています。

class TextReader:
    """Print and number lines in a text file."""
    def __init__(self, file):
        self.file = file
        self.fh = open(file)
        self.lineno = 0

    def readline(self):
        self.lineno = self.lineno + 1
        line = self.fh.readline()
        if not line:
            return None
        if line.endswith("\n"):
            line = line[:-1]
        return "%d: %s" % (self.lineno, line)

    def __getstate__(self):
        odict = self.__dict__.copy() # copy the dict since we change it
        del odict['fh']              # remove filehandle entry
        return odict

    def __setstate__(self,dict):
        fh = open(dict['file'])      # reopen file
        count = dict['lineno']       # read from file...
        while count:                 # until line count is restored
            fh.readline()
            count = count - 1
        self.__dict__.update(dict)   # update attributes
        self.fh = fh                 # save the file object

使用例は以下のようになるでしょう:

>>> import TextReader
>>> obj = TextReader.TextReader("TextReader.py")
>>> obj.readline()
'1: #!/usr/local/bin/python'
>>> # (more invocations of obj.readline() here)
... obj.readline()
'7: class TextReader:'
>>> import pickle
>>> pickle.dump(obj,open('save.p','w'))

pickle が Python プロセス間でうまく働くことを見たい なら、先に進む前に他の Python セッションを開始してください。 以下の振る舞いは同じプロセスでも新たなプロセスでも起こります。

>>> import pickle
>>> reader = pickle.load(open('save.p'))
>>> reader.readline()
'8:     "Print and number lines in a text file."'

参考資料:

copy_regモジュール:
拡張型を登録するための Pickle インタフェース構成機構。.

shelveモジュール:
オブジェクトのインデクス付きデータベース; pickle を使います。.

copyモジュール:
オブジェクトの浅いコピーおよび深いコピー。.

marshalモジュール:
高いパフォーマンスを持つ組み込み型整列化機構。.

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.14.6 Unpickler をサブクラス化する Up: 3.14 pickle Next: 3.15 cPickle


3.15 cPickle -- より高速な pickle

cPickle モジュールは Python オブジェクトの直列化および 非直列化をサポートし、pickle モジュールとほとんど同じインタフェースと機能を提供します。 いくつか相違点がありますが、最も重要な違いはパフォーマンスと サブクラス化が可能かどうかです。

第一に、cPickle は C で実装されているため、pickle よりも最大で 1000 倍高速です。第二に、cPickle モジュール 内では、呼び出し可能オブジェクト Pickler() および Unpickler() は関数で、クラスではありません。 つまり、pickle 化や unpickle 化を行うカスタムのサブクラスを 導出することができないということです。 多くのアプリケーションではこの機能は不要なので、cPickle モジュールによる大きなパフォーマンス向上の恩恵を受けられるはず です。pickle と cPickle で作られた pickle データ列は同じなので、既存の pickle データに対して pickle と cPickle を互換に使用することができます 3.11。

cPickle と pickle の API 間には他にも些細な相違が ありますが、ほとんどのアプリケーションで互換性があります。 より詳細なドキュメンテーションは pickle のドキュメント にあり、そこでドキュメント化されている相違点について挙げています。

... を互換に使用することができます3.11
pickle データ形式は実際には小規模なスタック指向のプログラム 言語であり、またあるオブジェクトをエンコードする際に多少の自由度が あるため、二つのモジュールが同じ入力オブジェクトに対して異なる データ列を生成することもあります。しかし、常に互いに他のデータ列 を読み出せることが保証されています。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.14.7 例 Up: 3. Python ランタイム サービス Next: 3.16 copy_reg


3.16 copy_reg -- pickleサポート関数を登録する

copy_regモジュールはpickleとcPickleモジュールに対するサポートを提供します。その上、copyモジュールは将来これをつかう可能性が高いです。クラスでないオブジェクトコンストラクタについての設定情報を提供します。このようなコンストラクタはファクトリ関数か、またはクラスインスタンスでしょう。

constructor( object)
objectを有効なコンストラクタであると宣言します。objectが呼び出し可能でなければ(そして、それゆえコンストラクタとして有効でないならば)、TypeErrorを発生します。

pickle( type, function[, constructor])
functionが型typeのオブジェクトに対する``リダクション''関数として使うことを宣言します。typeは``標準的な''クラスオブジェクトであってはいけません。(標準的なクラスは異なった扱われ方をします。詳細は、pickleモジュールのドキュメンテーションを参照してください。) functionは文字列または二ないし三つの要素を含むタプルです。

オプションのconstructorパラメータが与えられた場合は、ピクルス化時にfunctionが返した引数のタプルとともによびだされたときにオブジェクトを再構築するために使われ得る呼び出し可能オブジェクトです。objectがクラスであるか、またはconstructorが呼び出し可能でない場合に、TypeErrorを発生します。

functionとconstructorの求められるインターフェイスについての詳細は、pickleモジュールを参照してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.15 cPickle Up: 3. Python ランタイム サービス Next: 3.17 shelve


3.17 shelve -- Python オブジェクトの永続化

``シェルフ (shelf, 棚)'' は辞書に似た永続性を持つオブジェクトです。 ``dbm'' データベースとの違いは、シェルフの値 (キーではありません！) は実質上どんな Python オブジェクトにも -- pickle モジュール が扱えるなら何でも -- できるということです。これにはほとんどの クラスインスタンス、再帰的なデータ型、沢山の共有されたサブオブジェクト を含むオブジェクトが含まれます。キーは通常の文字列です。

open( filename[,flag='c'[,protocol=None[,writeback=False[,binary=None]]]])
永続的な辞書を開きます。指定された filename は、根底にある データベースの基本ファイル名となります。副作用として、filename には拡張子がつけられる場合があり、ひとつ以上のファイルが生成される 可能性もあります。デフォルトでは、根底にあるデータベースファイルは 読み書き可能なように開かれます。オプションの flag パラメタ は anydbm.open における flag パラメタと同様に 解釈されます。

デフォルトでは、値を整列化する際にはバージョン 0 の pickle 化が 用いられます。pickle 化プロトコルのバージョンは protocol パラメタで指定することができます。 バージョン2.3 以降で変更された 仕様: protocol パラメタが追加されました。binary パラメタは撤廃され、 以前のバージョンとの互換性のためにのみ提供されています

デフォルトでは、永続的な辞書の可変エントリに対する変更をおこなっても、 自動的にファイルには書き戻されません。オプションの writeback パラメタが True に設定されていれば、アクセスされたすべての エントリはメモリ上にキャッシュされ、ファイルを閉じる際に書き戻されます; この機能は永続的な辞書上の可変の要素に対する変更を容易にしますが、 多数のエントリがアクセスされた場合、膨大な量のメモリがキャッシュの ために消費され、アクセスされた全てのエントリを書き戻す (アクセスされた エントリが可変であるか、あるいは実際に変更されたかを決定する方法は 存在しないのです) ために、ファイルを閉じる操作を非常に低速にしてしまいます。

shelve オブジェクトは辞書がサポートする全てのメソッドをサポートしています。 これにより、辞書ベースのスクリプトから永続的な記憶媒体を必要とする スクリプトに容易に移行できるようになります。

  • 3.17.1 制限事項
  • 3.17.2 使用例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.16 copy_reg Up: 3. Python ランタイム サービス Next: 3.17.1 制限事項


3.17.1 制限事項

  • どのデータベースパッケージが使われるか (例えば dbm、 gdbm、bsddb) は、どのインタフェースが 利用可能かに依存します。従って、データベースを dbm を使って直接開く方法は安全ではありません。データベースはまた、 dbm が使われた場合 (不幸なことに) その制約に縛られます -- これはデータベースに 記録されたオブジェクト (の pickle 化された表現) はかなり小さく なければならず、キー衝突が生じた場合に、稀にデータベースを更新 することができなくなるということを意味します。

  • 実装に依存して、永続化した辞書を閉じるときには、変更がディスクに 書き込まれるかもしれないし、必ずしも書き込まれないかもしれません。 Shelf クラスの __del__ メソッドは close メソッドを呼び出すので、プログラマは通常この作業を明示的に行う必要は ありません。

  • shelve モジュールは、シェルフに置かれたオブジェクトの 並列した 読み出し/書き込みアクセスをサポートしません (複数の同時読み出しアクセスは安全です)。あるプログラムが書き込み ために開かれたシェルフを持っているとき、他のプログラムは そのシェルフを読み書きのために開いてはいけません。この問題を 解決するために Unix のファイルロック機構を使うことができますが、 この機構は Unix のバージョン間で異なり、使われている データベースの実装について知識が必要となります。

class Shelf( dict[, protocol=None[, writeback=False[, binary=None]]])
UserDict.DictMixin のサブクラスで、pickle 化された値を dict オブジェクトに保存します。

デフォルトでは、値を整列化する際にはバージョン 0 の pickle 化が 用いられます。pickle 化プロトコルのバージョンは protocol パラメタで指定することができます。pickle 化プロトコルについては pickle のドキュメントを参照してください。 バージョン2.3 以降で変更された 仕様: protocol パラメタが追加されました。binary パラメタは撤廃され、 以前のバージョンとの互換性のためにのみ提供されています

writeback パラメタが True に設定されていれば、アクセスされたすべての エントリはメモリ上にキャッシュされ、ファイルを閉じる際に書き戻されます; この機能により、可変のエントリに対して自然な操作が可能になりますが、 さらに多くのメモリを消費し、辞書をファイルと同期して閉じる際に長い時間が かかるようになります。

class BsdDbShelf( dict[, protocol=None[, writeback=False[, binary=None]]])
Shelf のサブクラスで、first、next、 previous、 last および set_location メソッドを公開しています。これらのメソッドは bsddb モジュールでは 利用可能ですが、他のデータベースモジュールでは利用できません。 コンストラクタに渡された dict オブジェクトは上記のメソッドを サポートしていなくてはなりません。通常は、bsddb.hashopen、 bsddb.btopen または bsddb.rnopen のいずれか を呼び出して得られるオブジェクトが条件を満たしています。オプションの protocol、 writeback、および binary パラメタは Shelf クラスにおけるパラメタと同様に解釈されます。

class DbfilenameShelf( filename[, flag='c'[, protocol=None[, writeback=False[, binary=None]]]])
Shelf のサブクラスで、辞書様オブジェクトの代わりに filename を受理します。根底にあるファイルは anydbm.open を使って開かれます。デフォルトでは、 ファイルは読み書き可能な状態で開かれます。オプションの flag パラメタは open 関数におけるパラメタと同様に解釈されます。 オプションの protocol、 writeback、および binary パラメタは Shelf クラスにおけるパラメタと同様に解釈されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.17 shelve Up: 3.17 shelve Next: 3.17.2 使用例


3.17.2 使用例

インタフェースは以下のコードに集約されています (key は文字列で、 data は任意のオブジェクトです):

import shelve

d = shelve.open(filename) # open -- file may get suffix added by low-level
                          # library

d[key] = data   # store data at key (overwrites old data if
                # using an existing key)
data = d[key]   # retrieve a COPY of data at key (raise KeyError if no
                # such key)
del d[key]      # delete data stored at key (raises KeyError
                # if no such key)
flag = d.has_key(key)   # true if the key exists
list = d.keys() # a list of all existing keys (slow!)

# as d was opened WITHOUT writeback=True, beware:
d['xx'] = range(4)  # this works as expected, but...
d['xx'].append(5)   # *this doesn't!* -- d['xx'] is STILL range(4)!!!
# having opened d without writeback=True, you need to code carefully:
temp = d['xx']      # extracts the copy
temp.append(5)      # mutates the copy
d['xx'] = temp      # stores the copy right back, to persist it
# or, d=shelve.open(filename,writeback=True) would let you just code
# d['xx'].append(5) and have it work as expected, BUT it would also
# consume more memory and make the d.close() operation slower.

d.close()       # close it

参考資料:

anydbmモジュール:
dbm スタイルのデータベースに対する汎用インタフェース。.
bsddbモジュール:
BSD db データベースインタフェース。.
dbhashモジュール:
bsddb をラップする薄いレイヤで、他のデータベースモジュールのように関数 open を提供しています。.
dbmモジュール:
標準の Unix データベースインタフェース。.
dumbdbmモジュール:
dbm インタフェースの移植性のある実装。.
gdbmモジュール:
dbm インタフェースに基づいた GNU データベースインタフェース。.
pickleモジュール:
shelve によって使われるオブジェクト整列化機構。.
cPickleモジュール:
pickle の高速版。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.17.1 制限事項 Up: 3.17 shelve Next: 3.18 copy


3.18 copy -- 浅いコピーおよび深いコピー操作

このモジュールでは汎用の (浅い／深い) コピー操作を提供しています。

以下にインタフェースをまとめます:

import copy

x = copy.copy(y)        # make a shallow copy of y
x = copy.deepcopy(y)    # make a deep copy of y
このモジュール固有のエラーに対しては、copy.error が送出されます。

浅い (shllow) コピーと深い (deep) コピーの違いが関係するのは、 複合オブジェクト (リストやクラスインスタンスのような他のオブジェクトを 含むオブジェクト) だけです:

  • 浅いコピー (shallow copy) は新たな複合オブジェクトを作成し、 その後 (可能な限り) 元のオブジェクト中に見つかったオブジェクトに対する 参照 を挿入します。

  • 深いコピー (deep copy) は新たな複合オブジェクトを作成し、 その後元のオブジェクト中に見つかったオブジェクトの コピー を挿入します。

深いコピー操作には、しばしば浅いコピー操作の時には存在しない 2 つの 問題がついてまわります:

  • 再帰的なオブジェクト (直接、間接に関わらず、自分自身に対する参照 を持つ複合オブジェクト) は再帰ループを引き起こします。

  • 深いコピーでは、何もかも をコピーするため、例えば複数の コピー間で共有されるべき管理データ構造までも、余分にコピー してしまいます。

deepcopy() 関数では、これらの問題を以下のようにして 回避しています:

  • 現在のコピー過程ですでにコピーされたオブジェクトからなる、 ``メモ'' 辞書を 保持します; かつ

  • ユーザ定義のクラスでコピー操作やコピーされる内容の集合を上書きできる ようにします。

現在のバージョンでは、モジュール、クラス、関数、メソッド、スタック追跡、 スタック構造、ファイル、ソケット、ウィンドウ、アレイ、その他これらに 類似の型をコピーしません。

クラスでは、pickle 化を制御するためのインタフェース: __getinitargs__()、 __getstate__()、 および __setstate__() と同じインタフェースをコピーの制御に使うことが できます。これらのメソッドに関する情報は pickleモジュールの記述を 参照してください。copy モジュールは pickle 用関数登録モジュール copy_reg を使いません。

クラス独自のコピー実装を定義するために、特殊メソッド __copy__() および __deepcopy__() を定義することができます。前者は 浅いコピー操作を実装するために使われます; 追加の引数はありません。 後者は深いコピー操作を実現するために呼び出されます; この関数には 単一の引数としてメモ辞書が渡されます。__deepcopy__() の実装で、内容のオブジェクトに対して深いコピーを生成する必要がある場合、 deepcopy() を呼び出し、最初の引数にそのオブジェクトを、 メモ辞書を二つ目の引数に与えなければなりません。

参考資料:

pickleモジュール:
オブジェクト状態の取得と復元をサポートするために 使われる特殊メソッドについて議論されています。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.17.2 使用例 Up: 3. Python ランタイム サービス Next: 3.19 marshal


3.19 marshal -- 内部使用向けの Python オブジェクト整列化

このモジュールには Python 値をバイナリ形式で読み書きできるような関数 が含まれています。このバイナリ形式は Python 特有のものですが、 マシンアーキテクチャ非依存のものです (つまり、Python の値を PC 上で ファイルに書き込み、Sun に転送し、そこで読み戻すことができます)。 バイナリ形式の詳細がドキュメントされていないのは故意によるもの です; この形式は (稀にしかないことですが) Python のバージョン間で 変更される可能性があるからです。3.12

このモジュールは汎用の ``永続化 (persistence)'' モジュールでは ありません。汎用的な永続化や、RPC 呼び出しを通じたPython オブジェクト の転送については、モジュール pickle および shelve を参照してください。marshal モジュールは主に、 ``擬似コンパイルされた (pseudo-compiled)'' コードの .pyc ファイル への読み書きをサポートするために存在します。従って、 Python のメンテナ は、必要が生じれば marshal 形式を後方互換性のないものに変更する権利を 有しています。Python オブジェクトを直列化および非直列化したい場合には、 pickle モジュールを使ってください。

+

警告: + The marshal module is not intended to be secure against + erroneous or maliciously constructed data. Never unmarshal data + received from an untrusted or unauthenticated source. +
+
警告: marshalモジュールは、誤ったデータや悪意を持って作成されたデータ に対する安全性を考慮していません。信頼できない、もしくは認証されていない 出所からのデータを非直列化してはなりません。

全ての Python オブジェクト型がサポートされているわけではありません; 一般的には、どの起動中の Python 上に存在するかに依存しないオブジェクト だけがこのモジュールで読み書きできます。以下の型: None、整数、長整数、浮動小数点数、文字列、Unicode オブジェクト、 タプル、リスト、辞書、タプルとして解釈されるコードオブジェクト、 がサポートされています。リストと辞書は含まれている要素もサポート されている型であるもののみサポートされています; 再帰的なリストおよび 辞書は書き込んではなりません (無限ループを引き起こしてしまいます)。

補足説明: C 言語の long int が (DEC Alpha のように) 32 ビットよりも長いビット長を持つ場合、32 ビットよりも長い Python 整数を作成することが可能です。そのような整数が整列化された後、 C 言語の long int のビット長が 32 ビットしかないマシン上で 読み戻された場合、通常整数の代わりにPython 長整数が返されます。 型は異なりますが、数値は同じです。(この動作は Python 2.2 で新たに 追加されたものです。それ以前のバージョンでは、値のうち最小桁から 32 ビット以外の情報は失われ、警告メッセージが出力されます。)

文字列を操作する関数と同様に、ファイルの読み書きを行う関数が 提供されています。

このモジュールでは以下の関数を定義しています:

dump( value, file)
開かれたファイルに値を書き込みます。値はサポートされている型で なくてはなりません。ファイルは sys.stdout か、 open() や posix.popen() が返すようなファイル オブジェクトでなくてはなりません。またファイルはバイナリモード ('wb' または 'w+b') で開かれていなければ なりません。

値 (または値のオブジェクトに含まれるオブジェクト) がサポートされて いない型の場合、ValueError 例外が送出されます -- が、同時にごみのデータがファイルに書き込まれます。このオブジェクトは load() で適切に読み出されることはないはずです。

load( file)
開かれたファイルから値を一つ読んで返します。有効な値が読み出せなかった 場合、EOFError、ValueError、または TypeError を送出します。ファイルはバイナリモード ('rb' または 'r+b') で開かれたファイルオブジェクトでなければ なりません. 警告: サポートされない型を含むオブジェクトが dump() で 整列化されている場合、load() は整列化不能な値を None で置き換えます。

dumps( value)
dump(value, file) でファイルに書き込まれるような 文字列を返します。値はサポートされている型でなければなりません。値が サポートされていない型 (またはサポートされていない型のオブジェクト を含むような) オブジェクトの場合、ValueError 例外が 送出されます。

loads( string)
データ文字列を値に変換します。有効な値が見つからなかった場合、 EOFError、 ValueError、または TypeError が送出されます。 文字列中の他の文字は無視されます。

... 変更される可能性があるからです。3.12
このモジュールの名前は (特に) Modula-3 の設計者の間で使われて いた用語の一つに由来しています。彼らはデータを自己充足的な形式 で輸送する操作に ``整列化 (marshalling)'' という用語を使いました。 厳密に言えば、``整列させる (to marshal)'' とは、あるデータを (例えば RPC バッファのように) 内部表現形式から外部表現形式に変換する ことを意味し、``非整列化 (unmarshalling)'' とはその逆を意味します。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.18 copy Up: 3. Python ランタイム サービス Next: 3.20 warnings


3.20 warnings -- 警告の制御

バージョン2.1 以降で新規追加された 仕様です。

警告メッセージは一般に、ユーザに警告しておいた方がよいような状況下に プログラムが置かれているが、その状況は (通常は) 例外を送出したり そのプログラムを終了させるほどの正当な理由がないといった状況で 発されます。例えば、プログラムが古いモジュールを使っている場合 には警告を発したくなるかもしれません。

Python プログラマは、このモジュールの warn() 関数を 使うことで警告を発することができます。(C 言語のプログラマは PyErr_Warn() を使います; 詳細は Python/C API Reference Manual を参照してください)。

警告メッセージは通常 sys.stderr に出力されますが、その処理 方法は、全ての警告に対する無視する処理から警告を例外に変更する 処理まで、柔軟に変更することができます。警告の処理方法は 警告カテゴリ (以下参照)、警告メッセージテキスト、そして警告を 発したソースコード上の場所に基づいて変更することができます。 ソースコード上の同じ場所に対して特定の警告が繰り返された場合、 通常は抑制されます。

警告制御には 2 つの段階 (stage) があります: 第一に、警告が発される たびに、メッセージを出力すべきかどうか決定が行われます; 次に、 メッセージを出力するなら、メッセージはユーザによって設定が可能なフック を使って書式化され印字されます。

警告メッセージを出力するかどうかの決定は、警告フィルタによって制御 されます。警告フィルタは一致規則 (matching rule)と動作からなる配列です。 filterwarnings() を呼び出して一致規則をフィルタに追加する ことができ、resetwarnings() を呼び出してフィルタを標準 設定の状態にリセットすることができます。

警告メッセージの印字は showwarning() を呼び出して行うことが でき、この関数は上書きすることができます; この関数の標準の実装では、 formatwarning() を呼び出して警告メッセージを書式化しますが、 この関数についても自作の実装を使うことができます。

  • 3.20.1 警告カテゴリ
  • 3.20.2 警告フィルタ
  • 3.20.3 利用可能な関数
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.19 marshal Up: 3. Python ランタイム サービス Next: 3.20.1 警告カテゴリ


3.20.1 警告カテゴリ

警告カテゴリを表現する組み込み例外は数多くあります。このカテゴリ化は 警告をグループごとフィルタする上で便利です。現在以下の警告カテゴリ クラスが定義されています:

クラス | 記述
Warning | 全ての警告カテゴリクラスの基底クラスです。 Exception のサブクラスです。
UserWarning | warn() の標準のカテゴリです。
DeprecationWarning | その機能が廃用化されていることを示す 警告カテゴリの基底クラスです。
SyntaxWarning | その文法機能があいまいであることを示す警告 カテゴリの基底クラスです。
RuntimeWarning | その実行時システム機能があいまいであることを 示す警告カテゴリの基底クラスです。
FutureWarning | その構文の意味付けが将来変更される予定である ことを示す警告カテゴリの基底クラスです。

これらは技術的には組み込み例外ですが、概念的には警告メカニズムに 属しているのでここで記述されています。

標準の警告カテゴリをユーザの作成したコード上でサブクラス化することで、 さらに別の警告カテゴリを定義することができます。 警告カテゴリは常に Warning クラスのサブクラスでなければ なりません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.20 warnings Up: 3.20 warnings Next: 3.20.2 警告フィルタ


3.20.2 警告フィルタ

警告フィルタは、ある警告を無視すべきか、表示すべきか、あるいは (例外を送出する) エラーにするべきかを制御します。

概念的には、警告フィルタは複数のフィルタ仕様からなる順番付けられた リストを維持しています; 何らかの特定の警告が生じると、フィルタ仕様の 一致するものが見つかるまで、リスト中の各フィルタとの照合が行われます; 一致したフィルタ仕様がその警告の処理方法を決定します。 フィルタの各エントリは (action, message, category, module, lineno) からなるタプルです。ここで:

  • action は以下の文字列のうちの一つです:

    値 | 処理方法
    "error" | 一致した警告を例外に変えます
    "ignore" | 一致した警告を決して出力しません
    "always" | 一致した警告を常に出力します
    "default" | 一致した警告のうち、警告の原因になった ソースコード上の場所ごとに、最初の警告のみ出力します。
    "module" | 一致した警告のうち、警告の原因になった モジュールごとに、最初の警告のみ出力します。
    "once" | 一致した警告のうち、警告の原因になった 場所にかかわらず最初の警告のみ出力します。

  • message は正規表現を含む文字列で、メッセージはこの パタンに一致しなければなりません (照合時には常に大小文字の区別を しないようにコンパイルされます)。

  • category はクラス (Warning のサブクラス) です。 警告クラスはこのクラスのサブクラスに一致しなければなりません。

  • module は正規表現を含む文字列で、モジュール名はこのパタン に一致しなければなりません (照合時には常に大小文字の区別を しないようにコンパイルされます)。

  • lineno 整数で、警告が発生した場所の行番号に一致しなければ なりません、すべての行に一致する場合には 0 になります。

Warning クラスは組み込みの Exception クラスから 導出されているので、警告をエラーに変えるには単に category(message) を raise します。

警告フィルタは Python インタプリタのコマンドラインに渡される -W オプションで初期化されます。インタプリタは -W オプションに渡される全ての引数を sys.warnoptions; に変換せずに保存します; warnings モジュールは最初に import された際にこれらの引数を解釈します (無効なオプションはsys.stderr にメッセージを出力した後 無視されます)。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.20.1 警告カテゴリ Up: 3.20 warnings Next: 3.20.3 利用可能な関数


3.20.3 利用可能な関数

warn( message[, category[, stacklevel]])
警告を発するか、無視するか、あるいは例外を送出します。 category 引数が与えられた場合、警告カテゴリクラスでなければ なりません (上を参照してください); 標準の値は UserWarning です。message を Warning インスタンスで代用する こともできますが、この場合 category は無視され、 message.__class__ が使われ、メッセージ文は str(message) になります。発された例外が前述した警告フィルタによってエラーに 変更された場合、この関数は例外を送出します。引数 stacklevel は Python でラッパ関数を書く際に利用することができます。例えば:

def deprecation(message):
    warnings.warn(message, DeprecationWarning, stacklevel=2)

こうすることで、警告が参照するソースコード部分を、 deprecation() 自身ではなく deprecation() を 呼び出した側にできます (というのも、前者の場合は警告メッセージ の目的を台無しにしてしまうからです)。

warn_explicit( message, category, filename, lineno[, module[, registry]])
warn() の機能に対する低レベルのインタフェースで、 メッセージ、警告カテゴリ、ファイル名および行番号、そしてオプションの モジュール名およびレジストリ情報 (モジュールの __warningregistry__ 辞書) を明示的に渡します。 モジュール名は標準で .py が取り去られたファイル名になります; レジストリが渡されなかった場合、警告が抑制されることはありません。 message は文字列のとき、category は Warning のサブクラスでなければなりません。また message は Warning のインスタンスであってもよく、この場合 category は無視されます。

showwarning( message, category, filename, lineno[, file])
警告をファイルに書き込みます。標準の実装では、 formatwarning(message, category, filename, lineno) を呼び出し、返された文字列を file に書き込み ます。file は標準では sys.stderr です。 この関数は warnings.showwarning に別の実装を代入して 置き換えることができます。

formatwarning( message, category, filename, lineno)
警告を通常の方法で書式化します。返される文字列内には改行が埋め込まれて いる可能性があり、かつ文字列は改行で終端されています。

filterwarnings( action[, message[, category[, module[, lineno[, append]]]]])
警告フィルタのリストにエントリを一つ挿入します。標準ではエントリは 先頭に挿入されます; append が真ならば、末尾に挿入されます。 この関数は引数の型をチェックし、message および module の正規表現をコンパイルしてから、これらをタプルにして警告フィルタ の先頭に挿入します。従って、以前に挿入されたエントリと後で挿入 されたエントリの両方が特定の警告に合致した場合、後者が前者の エントリを上書きします。引数が省略されると、標準では全てにマッチ する値に設定されます。

resetwarnings( )
警告フィルタをリセットします。これにより、-W コマンドライン オプションによるものを含め、filterwarnings の呼び出しによる 影響はすべて無効化されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.20.2 警告フィルタ Up: 3.20 warnings Next: 3.21 imp


3.21 imp -- import内部へアクセスする

このモジュールはimport文を実装するために使われているメカニズムへのインターフェイスを提供します。次の定数と関数が定義されています:

get_magic( )
バイトコンパイルされたコードファイル(.pycファイル)を認識するために使われるマジック文字列値を返します。(この値はPythonの各バージョンで異なります。)

get_suffixes( )
三つ組みのリストを返します。それぞれはモジュールの特定の型を説明しています。各三つ組みは形式(suffix, mode, type)を持ちます。ここで、suffixは探すファイル名を作るためにモジュール名に追加する文字列です。そのファイルをオープンするために、modeは組み込みopen()関数へ渡されるモード文字列です(これはテキストファイル対しては'r'、バイナリファイルに対しては'rb'となります)。typeはファイル型で、以下で説明する値PY_SOURCE、PY_COMPILED、あるいは、C_EXTENSIONの一つを取ります。

find_module( name[, path])
検索パスpath上でモジュールnameを見つけようとします。pathがディレクトリ名のリストならば、上のget_suffixes()が返す拡張子のいずれかを伴ったファイルを各ディレクトリの中で検索します。リスト内の有効でない名前は黙って無視されます(しかし、すべてのリスト項目は文字列でなければならない)。pathが省略されるかNoneならば、sys.pathのディレクトリ名のリストが検索されます。しかし、最初にいくつか特別な場所を検索します。所定の名前(C_BUILTIN)をもつ組み込みモジュールを見つけようとします。それから、フリーズされたモジュール(PY_FROZEN)、同様にいくつかのシステムと他の場所がみられます(Macでは、リソース(PY_RESOURCE)を探します。Windowsでは、特定のファイルを指すレジストリの中を見ます)。

検索が成功すれば、戻り値は三つ組み(file, pathname, description)です。ここで、fileは先頭に位置を合わされたオープンファイルオブジェクトで、pathnameは見つかったファイルのパス名です。そして、descriptionはget_suffixes()が返すリストに含まれているような三つ組みで、見つかったモジュールの種類を説明しています。モジュールがファイルの中にあるならば、返されたfileはNoneで、filenameは空文字列、descriptionタプルはその拡張子とモードに対して空文字列を含みます。モジュール型は上の括弧の中に示されます。検索が失敗すれば、ImportErrorが発生します。他の例外は引数または環境に問題があることを示唆します。

この関数は階層的なモジュール名(ドットを含んだ名前)を扱いません。P.M、すなわち、パッケージPのサブモジュールMを見つけるためには、パッケージPを見つけてロードするためにfind_module()とload_module()を使い、それからP.__path__に設定されたpath引数とともにfind_module()を使ってください。P自身がドット名のときは、このレシピを再帰的に適用してください。

load_module( name, file, filename, description)
find_module()を使って(あるいは、互換性のある結果を作り出す検索を行って)以前見つけたモジュールをロードします。この関数はモジュールをインポートするという以上のことを行います: モジュールが既にインポートされているならば、reload()と同じです!。name引数は(これがパッケージのサブモジュールならばパッケージ名を含む)完全なモジュール名を示します。file引数はオープンしたファイルで、filenameは対応するファイル名です。モジュールがファイルからロードされようとしていないとき、これらはそれぞれNoneと''であっても構いません。get_suffixes()が返すようにdescription引数はタプルで、どの種類のモジュールがロードされなければならないかを説明するものです。

ロードが成功したならば、戻り値はモジュールオブジェクトです。そうでなければ、例外(たいていはImportError)が発生します。

重要: file引数がNoneでなければ、例外が発生した時でさえ呼び出し側にはそれを閉じる責任があります。これを行うには、try ... finally文をつかうことが最も良いです。

new_module( name)
nameという名前の新しい空モジュールオブジェクトを返します。このオブジェクトはsys.modulesに挿入されません。

lock_held( )
現在インポートロックが維持されているならば、Trueを返します。そうでなければ、Falseを返します。スレッドのないプラットホームでは、常にFalseを返します。

スレッドのあるプラットホームでは、インポートが完了するまでインポートを実行するスレッドは内部ロックを維持します。このロックは元のインポートが完了するまで他のスレッドがインポートすることを阻止します。言い換えると、元のスレッドがそのインポート(および、もしあるならば、それによって引き起こされるインポート)の途中で構築した不完全なモジュールオブジェクトを、他のスレッドが見られないようにします。

acquire_lock( )
実行中のスレッドでインタープリタのインポートロックを取得します。スレッドセーフ なインポートフックでは、インポート時にこのロックを取得します。 スレッドのないプラットホームではこの関数は何もしません。 バージョン2.3 以降で新規追加された 仕様です。

release_lock( )
インタープリタのインポートロックを解放します。 スレッドのないプラットホームではこの関数は何もしません。 バージョン2.3 以降で新規追加された 仕様です。

整数値をもつ次の定数はこのモジュールの中で定義されており、find_module()の検索結果を表すために使われます。

PY_SOURCE
ソースファイルとしてモジュールが発見された。

PY_COMPILED
コンパイルされたコードオブジェクトファイルとしてモジュールが発見された。

C_EXTENSION
動的にロード可能な共有ライブラリとしてモジュールが発見された。

PY_RESOURCE
モジュールがMacintoshリソースとして発見された。この値はMacintoshでのみ返される。

PKG_DIRECTORY
パッケージディレクトリとしてモジュールが発見された。

C_BUILTIN
モジュールが組み込みモジュールとして発見された。

PY_FROZEN
モジュールがフリーズされたモジュールとして発見された(init_frozen()を参照)。

次の定数と関数は旧式のものです。それらの機能はfind_module()やload_module()を使って利用できます。後方互換性のために残されています:

SEARCH_ERROR
使われていません。

init_builtin( name)
nameという名前の組み込みモジュールを初期化し、そのモジュールオブジェクトを返します。モジュールが既に初期化されている場合は、再度初期化されます。いくつかのモジュールは二度初期化することができません。 -- これを再び初期化しようとすると、ImportError例外が発生します。nameという名前の組み込みモジュールがない場合は、Noneを返します。

init_frozen( name)
nameという名前のフリーズされたモジュールを初期化し、モジュールオブジェクトを返します。モジュールが既に初期化されている場合は、再度初期化されます。nameという名前のフリーズされたモジュールがない場合は、Noneを返します。(フリーズされたモジュールはPythonで書かれたモジュールで、そのコンパイルされたバイトコードオブジェクトがPythonのfreezeユーティリティを使ってカスタムビルトPythonインタープリタへ組み込まれています。差し当たり、Tools/freeze/を参照してください。)

is_builtin( name)
nameという名前の再度初期化できる組み込みモジュールがある場合は、1を返します。nameという名前の再度初期化できない組み込みモジュールがある場合は、-1を返します(init_builtin()を参照してください)。nameという名前の組み込みモジュールがない場合は、0を返します。

is_frozen( name)
nameという名前のフリーズされたモジュール(init_frozen()を参照)がある場合は、Trueを返します。または、そのようなモジュールがない場合は、Falseを返します。

load_compiled( name, pathname, file)
バイトコンパイルされたコードファイルとして実装されているモジュールをロードして初期化し、そのモジュールオブジェクトを返します。モジュールが既に初期化されている場合は、再度初期化されます。name引数はモジュールオブジェクトを作ったり、アクセスするために使います。pathname引数はバイトコンパイルされたコードファイルを指します。file引数はバイトコンパイルされたコードファイルで、バイナリモードでオープンされ、先頭からアクセスされます。現在は、ユーザ定義のファイルをエミュレートするクラスではなく、実際のファイルオブジェクトでなければなりません。

load_dynamic( name, pathname[, file])
動的ロード可能な共有ライブラリとして実装されているモジュールをロードして初期化します。モジュールが既に初期化されている場合は、再度初期化します。いくつかのモジュールではそれができずに、例外を発生するかもしれません。pathname引数は共有ライブラリを指していなければなりません。name引数は初期化関数の名前を作るために使われます。共有ライブラリの"initname()"という名前の外部C関数が呼び出されます。オプションのfile引数は無視されます。(注意: 共有ライブラリはシステムに大きく依存します。また、すべてのシステムがそれをサポートしているわけではありません。)

load_source( name, pathname, file)
Pythonソースファイルとして実装されているモジュールをロードして初期化し、モジュールオブジェクトを返します。モジュールが既に初期化されている場合は、再度初期化します。name引数はモジュールオブジェクトを作成したり、アクセスしたりするために使われます。pathname引数はソースファイルを指します。file引数はソースファイルで、テキストとして読み込むためにオープンされ、先頭からアクセスされます。現在は、ユーザ定義のファイルをエミュレートするクラスではなく、実際のファイルオブジェクトでなければなりません。(拡張子.pycまたは.pyoをもつ)正しく対応するバイトコンパイルされたファイルが存在する場合は、与えられたソースファイルを構文解析する代わりにそれが使われることに注意してください。

  • 3.21.1 例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.20.3 利用可能な関数 Up: 3. Python ランタイム サービス Next: 3.21.1 例


3.21.1 例

次の関数はPython 1.4までの標準import文(階層的なモジュール名がない)をエミュレートします。(この実装はそのバージョンでは動作しないでしょう。なぜなら、find_module()は拡張されており、またload_module()が1.4で追加されているからです。)

import imp
import sys

def __import__(name, globals=None, locals=None, fromlist=None):
    # Fast path: see if the module has already been imported.
    try:
        return sys.modules[name]
    except KeyError:
        pass

    # If any of the following calls raises an exception,
    # there's a problem we can't handle -- let the caller handle it.

    fp, pathname, description = imp.find_module(name)

    try:
        return imp.load_module(name, fp, pathname, description)
    finally:
        # Since we may exit via an exception, close fp explicitly.
        if fp:
            fp.close()

階層的なモジュール名を実装し、reload()関数を含むより完全な例はモジュールkneeにあります。kneeモジュールはPythonのソースディストリビューションの中のDemo/imputil/にあります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.21 imp Up: 3.21 imp Next: 3.22 pkgutil


3.22 pkgutil -- パッケージ拡張ユーティリティ

バージョン2.3 以降で新規追加された 仕様です。

警告: これは実験的なモジュールです。将来廃止されたり、Python 2.3 beta 1 の バージョンとはまったく別のものに書き変えられる可能性があります。

このモジュールは次の単一の関数を提供します。

extend_path( path, name)
パッケージを構成するモジュールのサーチパスを拡張します。 パッケージの __init__.py で次のように書くことを意図したもので す。

from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

上記はパッケージの __path__ に sys.path の全ディレクトリ のサブディレクトリとしてパッケージ名と同じ名前を追加します。これは1つ の論理的なパッケージの異なる部品を複数のディレクトリに分けて配布したい ときに役立ちます。

同時に *.pkg の * の部分が name 引数に指定された文 字列に一致するファイルの検索もおこないます。この機能は import で始まる特別な行がないことを除き *.pth ファイルに似ています (site の項を参照)。*.pkg は重複のチェックを除き、信 頼できるものとして扱われます。*.pkg ファイルの中に見つかったエ ントリはファイルシステム上に実在するか否かを問わず、そのまますべてパス に追加されます。(このような仕様です。)

入力パスがリストでない場合(フリーズされたパッケージのとき)は何もせずに リターンします。入力パスが変更されていなければ、アイテムを末尾に追加し ただけのコピーを返します。

sys.path はシーケンスであることが前提になっています。 sys.path の要素の内、実在するディレクトリを指す(ユニコードまた は8ビットの)文字列となっていないものは無視されます。ファイル名として使っ たときにエラーが発生する sys.path のユニコード要素がある場合、 この関数(os.path.isdir() を実行している行)で例外が発生する 可能性があります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.21.1 例 Up: 3. Python ランタイム サービス Next: 3.23 code


3.23 code -- インタプリタ基底クラス

codeモジュールはread-eval-print(読み込み-評価-表示)ループをPythonで実装するための機能を提供します。対話的なインタプリタプロンプトを提供するアプリケーションを作るために使える二つのクラスと便利な関数が含まれています。

class InteractiveInterpreter( [locals])
このクラスは構文解析とインタプリタ状態(ユーザの名前空間)を取り扱います。入力バッファリングやプロンプト出力、または入力ファイル指定を扱いません(ファイル名は常に明示的に渡されます)。オプションのlocals引数はその中でコードが実行される辞書を指定します。その初期値は、キー'__name__'が'__console__'に設定され、キー'__doc__'がNoneに設定された新しく作られた辞書です。

class InteractiveConsole( [locals[, filename]])
対話的なPythonインタプリタの振る舞いを厳密にエミュレートします。このクラスはInteractiveInterpreterを元に作られていて、通常のsys.ps1とsys.ps2をつかったプロンプト出力と入力バッファリングが追加されています。

interact( [banner[, readfunc[, local]]])
read-eval-printループを実行するための便利な関数。これはInteractiveConsoleの新しいインスタンスを作り、readfuncが与えられた場合はraw_input()メソッドとして使われるように設定します。localが与えられた場合は、インタプリタループのデフォルト名前空間として使うためにInteractiveConsoleコンストラクタへ渡されます。そして、インスタンスのinteract()メソッドは見出しとして使うために渡されるbannerを受け取り実行されます。コンソールオブジェクトは使われた後捨てられます。

compile_command( source[, filename[, symbol]])
この関数はPythonのインタプリタメインループ(別名、read-eval-printループ)をエミュレートしようとするプログラムにとって役に立ちます。扱いにくい部分は、ユーザが(完全なコマンドや構文エラーではなく)さらにテキストを入力すれば完全になりうる不完全なコマンドを入力したときを決定することです。この関数はほとんどの場合に実際のインタプリタメインループと同じ決定を行います。

sourceはソース文字列です。filenameはオプションのソースが読み出されたファイル名で、デフォルトで'<input>'です。symbolはオプションの文法の開始記号で、'single' (デフォルト)または'eval'のどちらかにすべきです。

コマンドが完全で有効ならば、コードオブジェクトを返します(compile(source, filename, symbol)と同じ)。コマンドが完全でないならば、Noneを返します。コマンドが完全で構文エラーを含む場合は、SyntaxErrorを発生させます。または、コマンドが無効なリテラルを含む場合は、OverflowErrorもしくはValueErrorを発生させます。

  • 3.23.1 対話的なインタプリタオブジェクト
  • 3.23.2 対話的なコンソールオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.22 pkgutil Up: 3. Python ランタイム サービス Next: 3.23.1 対話的なインタプリタオブジェクト


3.23.1 対話的なインタプリタオブジェクト

runsource( source[, filename[, symbol]])
インタプリタ内のあるソースをコンパイルし実行します。引数はcompile_command()のものと同じです。filenameのデフォルトは'<input>'で、symbolは'single'です。あるいくつかのことが起きる可能性があります:

  • 入力はが正しくない。compile_command()が例外(SyntaxErrorかOverflowError)を起こした場合。showsyntaxerror()メソッドの呼び出によって、構文トレースバックが表示されるでしょう。runsource()はFalseを返します。

  • 入力が完全でなく、さらに入力が必要。compile_command()がNoneを返した場合。runsource()はTrueを返します。

  • 入力が完全。compile_command()がコードオブジェクトを返した場合。(SystemExitを除く実行時例外も処理する)runcode()を呼び出すことによって、コードは実行されます。runsource()はFalseを返します。

次の行を要求するためにsys.ps1かsys.ps2のどちらを使うかを決定するために、戻り値を利用できます。

runcode( code)
コードオブジェクトを実行します。例外が生じたときは、トレースバックを表示するためにshowtraceback()が呼び出されます。伝わることが許されているSystemExitを除くすべての例外が捉えられます。

KeyboardInterruptについての注意。このコードの他の場所でこの例外が生じる可能性がありますし、常に捕らえることができるとは限りません。呼び出し側はそれを処理するために準備しておくべきです。

showsyntaxerror( [filename])
起きたばかりの構文エラーを表示します。複数の構文エラーに対して一つあるのではないため、これはスタックトレースを表示しません。filenameが与えられた場合は、Pythonのパーサが与えるデフォルトのファイル名の代わりに例外の中へ入れられます。なぜなら、文字列から読み込んでいるときはパーサは常に'<string>'を使うからです。出力はwrite()メソッドによって書き込まれます。

showtraceback( )
起きたばかりの例外を表示します。スタックの最初の項目を取り除きます。なぜなら、それはインタプリタオブジェクトの実装の内部にあるからです。出力はwrite()メソッドによて書き込まれます。

write( data)
文字列を標準エラーストリーム(sys.stderr)へ書き込みます。必要に応じて適切な出力処理を提供するために、導出クラスはこれをオーバーライドすべきです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.23 code Up: 3.23 code Next: 3.23.2 対話的なコンソールオブジェクト


3.23.2 対話的なコンソールオブジェクト

InteractiveConsoleクラスはInteractiveInterpreterのサブクラスです。以下の追加メソッドだけでなく、インタプリタオブジェクトのすべてのメソッドも提供します。

interact( [banner])
対話的なPythonコンソールをそっくりにエミュレートします。オプションのbanner引数は最初のやりとりの前に表示するバナーを指定します。デフォルトでは、標準Pythonインタプリタが表示するものと同じようなバナーを表示します。それに続けて、実際のインタプリタと混乱しないように(とても似ているから!)括弧の中にコンソールオブジェクトのクラス名を表示します。

push( line)
ソーステキストの一行をインタプリタへ送ります。その行の末尾に改行がついていてはいけません。内部に改行を持っているかもしれません。その行はバッファへ追加され、ソースとして連結された内容が渡されインタプリタのrunsource()メソッドが呼び出されます。コマンドが実行されたか、有効であることをこれが示している場合は、バッファはリセットされます。そうでなければ、コマンドが不完全で、その行が付加された後のままバッファは残されます。さらに入力が必要ならば、戻り値はTrueです。その行がある方法で処理されたならば、Falseです(これはrunsource()と同じです)。

resetbuffer( )
入力バッファから処理されていないソーステキストを取り除きます。

raw_input( [prompt])
プロンプトを書き込み、一行を読み込みます。返る行は末尾に改行を含みません。ユーザがEOFキーシーケンスを入力したときは、EOFErrorを発生させます。基本実装では、組み込み関数raw_input()を使います。サブクラスはこれを異なる実装と置き換えるかもしれません。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.23.1 対話的なインタプリタオブジェクト Up: 3.23 code Next: 3.24 codeop


3.24 codeop -- Pythonコードをコンパイルする

codeモジュールで行われているようなPythonのread-eval-printループをエミュレートするユーティリティをcodeopモジュールは提供します。結果的に、直接モジュールを使いたいとは思わないかもしれません。あなたのプログラムにこのようなループを含めたい場合は、代わりにcodeモジュールを使うことをおそらく望むでしょう。

この仕事には二つの部分があります:

  1. 入力の一行がPythonの文として完全であるかどうかを見分けられること: 簡単に言えば、次が`>>> 'か、あるいは`... 'かどうかを見分けます。
  2. どのfuture文をユーザが入力したのかを覚えていること。したがって、実質的にそれに続く入力をこれらとともにコンパイルすることができます。

codeopモジュールはこうしたことのそれぞれを行う方法とそれら両方を行う方法を提供します。

前者は実行するには:

compile_command( source[, filename[, symbol]])
Pythonコードの文字列であるべきsourceをコンパイルしてみて、sourceが有効なPythonコードの場合はコードオブジェクトを返します。このような場合、コードオブジェクトのファイル名属性は、デフォルトで'<input>'であるfilenameでしょう。sourceが有効なPythonコードではないが、有効なPythonコードの接頭語である場合には、Noneを返します。

sourceに問題がある場合は、例外を発生させます。無効なPython構文がある場合は、SyntaxErrorを発生させます。また、無効なリテラルがある場合は、OverflowErrorまたはValueErrorを発生させます。

symbol引数はsourceが文としてコンパイルされるか('single'、デフォルト)、または式としてコンパイルされたかどうかを決定します('eval')。他のどんな値もValueErrorを発生させる原因となります。

警告: ソースの終わりに達する前に、成功した結果をもってパーサは構文解析を止めることが(できそうではなく)できます。このような場合、後ろに続く記号はエラーとならずに無視されます。例えば、改行が後ろに付くバックスラッシュには不定のゴミが付いているかもしれません。パーサのAPIがより良くなればすぐに、これは修正されるでしょう。

class Compile( )
このクラスのインスタンスは組み込み関数compile()とシグネチャが一致する__call__()メソッドを持っていますが、インスタンスが__future__文を含むプログラムテキストをコンパイルする場合は、インスタンスは有効なその文とともに続くすべてのプログラムテキストを'覚えていて'コンパイルするという違いがあります。

class CommandCompiler( )
このクラスのインスタンスはcompile_command()とシグネチャが一致する__call__()メソッドを持っています。インスタンスが__future__文を含むプログラムテキストをコンパイルする場合に、インスタンスは有効なその文とともにそれに続くすべてのプログラムテキストを'覚えていて'コンパイルするという違いがあります。

バージョン間の互換性についての注意: CompileとCommandCompilerはPython 2.2で導入されました。2.2のfuture-tracking機能を有効にするだけでなく、2.1とPythonのより以前のバージョンとの互換性も保ちたい場合は、次のようにかくことができます

try:
    from codeop import CommandCompiler
    compile_command = CommandCompiler()
    del CommandCompiler
except ImportError:
    from codeop import compile_command

これは影響の小さい変更ですが、あなたのプログラムにおそらく望まれないグローバル状態を導入します。または、次のように書くこともできます:

try:
    from codeop import CommandCompiler
except ImportError:
    def CommandCompiler():
        from codeop import compile_command
        return compile_command

そして、新たなコンパイラオブジェクトが必要となるたびにCommandCompilerを呼び出します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.23.2 対話的なコンソールオブジェクト Up: 3. Python ランタイム サービス Next: 3.25 pprint


3.25 pprint -- データ出力の整然化

pprintモジュールを使うと、Pythonの任意のデータ構造をインタープ リタへの入力で使われる形式にして``pretty-print''できます。 フォーマット化された構造の中にPythonの基本的なタイプではないオブジェクト があるなら、表示できないかもしれません。 Pythonの定数として表現できない多くの組み込みオブジェクトと同様、ファイ ル、ソケット、クラスあるいはインスタンスのようなオブジェクトが含まれてい た場合は出力できません。

可能であればオブジェクトをフォーマット化して1行に出力しますが、与えられ た幅に合わないなら複数行に分けて出力します。 無理に幅を設定したいなら、PrettyPrinterオブジェクトを作成して明 示してください。

pprintモジュールには1つのクラスが定義されています：

class PrettyPrinter( ...)
PrettyPrinterインスタンスを作ります。 このコンストラクタにはいくつかのキーワードパラメータを設定できます。

streamキーワードで出力ストリームを設定できます；このストリームに対 して呼び出されるメソッドはファイルプロトコルのwrite()メソッドだ けです。 もし設定されなければ、PrettyPrinterはsys.stdoutを使用しま す。 さらに3つのパラメータで出力フォーマットをコントロールできます。 そのキーワードはindent、depthとwidthです。

再帰的なレベルごとに加えるインデントの量はindentで設定できます；デ フォルト値は1です。 他の値にすると出力が少しおかしく見えますが、ネスト化されたところが見分け 易くなります。

出力されるレベルはdepthで設定できます； 出力されるデータ構造が深いなら、指定以上の深いレベルのものは"..."で 置き換えられて表示されます。 デフォルトでは、オブジェクトの深さを制限しません。

widthパラメータを使うと、出力する幅を望みの文字数に設定できます； デフォルトでは80文字です。 もし指定した幅にフォーマットできない場合は、できるだけ近づけます。

>>> import pprint, sys
>>> stuff = sys.path[:]
>>> stuff.insert(0, stuff[:])
>>> pp = pprint.PrettyPrinter(indent=4)
>>> pp.pprint(stuff)
[   [   '',
        '/usr/local/lib/python1.5',
        '/usr/local/lib/python1.5/test',
        '/usr/local/lib/python1.5/sunos5',
        '/usr/local/lib/python1.5/sharedmodules',
        '/usr/local/lib/python1.5/tkinter'],
    '',
    '/usr/local/lib/python1.5',
    '/usr/local/lib/python1.5/test',
    '/usr/local/lib/python1.5/sunos5',
    '/usr/local/lib/python1.5/sharedmodules',
    '/usr/local/lib/python1.5/tkinter']
>>>
>>> import parser
>>> tup = parser.ast2tuple(
...     parser.suite(open('pprint.py').read()))[1][1][1]
>>> pp = pprint.PrettyPrinter(depth=6)
>>> pp.pprint(tup)
(266, (267, (307, (287, (288, (...))))))

PrettyPrinterクラスにはいくつかの派生する関数が提供されていま す：

pformat( object)
objectをフォーマット化して文字列として返します。 フォーマット化にはデフォルトのパラメータが使用されます。

pprint( object[, stream])
objectをフォーマット化してstreamに出力し、最後に改行します。 streamが省略されたら、sys.stdoutに出力します。 これは対話型のインタープリタ上で、求める値をprintする代わりに 使用できます。 フォーマット化にはデフォルトのパラメータが使用されます。

>>> stuff = sys.path[:]
>>> stuff.insert(0, stuff)
>>> pprint.pprint(stuff)
[<Recursion on list with id=869440>,
 '',
 '/usr/local/lib/python1.5',
 '/usr/local/lib/python1.5/test',
 '/usr/local/lib/python1.5/sunos5',
 '/usr/local/lib/python1.5/sharedmodules',
 '/usr/local/lib/python1.5/tkinter']

isreadable( object)
objectをフォーマット化して出力できる（``readable''）か、あるいは eval()を使って値を再構成できるかを返しま す。 再帰的なオブジェクトに対しては常にfalseを返します。

>>> pprint.isreadable(stuff)
False

isrecursive( object)
objectが再帰的な表現かどうかを返します。

さらにもう1つ、関数が定義されています：

saferepr( object)
objectの文字列表現を、再帰的なデータ構造から保護した形式で返しま す。 もしobjectの文字列表現が再帰的な要素を持っているなら、再帰的な参照 は"<Recursion on typename with id=number>"で表示されま す。 出力は他と違ってフォーマット化されません。

>>> pprint.saferepr(stuff)
"[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.5', '/usr/loca
l/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python
1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter']"

  • 3.25.1 PrettyPrinter オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.24 codeop Up: 3. Python ランタイム サービス Next: 3.25.1 PrettyPrinter オブジェクト


3.25.1 PrettyPrinter オブジェクト

PrettyPrinterインスタンスには以下のメソッドがあります：

pformat( object)
objectのフォーマット化した表現を返します。 これはPrettyPrinterのコンストラクタに渡されたオプションを考慮し てフォーマット化されます。

pprint( object)
objectのフォーマット化した表現を指定したストリームに出力し、最後に 改行します。

以下のメソッドは、対応する同じ名前の関数と同じ機能を持っています。 以下のメソッドをインスタンスに対して使うと、新たにPrettyPrinter オブジェクトを作る必要がないのでちょっぴり効果的です。

isreadable( object)
objectをフォーマット化して出力できる（``readable''）か、あるいは eval()を使って値を再構成できるかを返しま す。 これは再帰的なオブジェクトに対してfalseを返すことに注意して下さい。 もしPrettyPrinterのdepthパラメータが設定されていて、オブ ジェクトのレベルが設定よりも深かったら、falseを返します。

isrecursive( object)
オブジェクトが再帰的な表現かどうかを返します。

このメソッドをフックとして、サブクラスがオブジェクトを文字列に変換する方 法を修正するのが可能になっています。 デフォルトの実装では、内部でsaferepr()を呼び出しています。

format( object, context, maxlevels, level)
3つの値を返します：objectをフォーマット化して文字列にしたもの、そ の結果が読み込み可能かどうかを示すフラグ、再帰が含まれているかどうかを示 すフラグ。

最初の引数は表示するオブジェクトです。 2つめの引数はオブジェクトのid()をキーとして含むディクショナリ で、オブジェクトを含んでいる現在の（直接、間接にobjectのコンテナと して表示に影響を与える）環境です。 ディクショナリcontextの中でどのオブジェクトが表示されたか表示する 必要があるなら、3つめの返り値はtrueになります。 format()メソッドの再帰呼び出しではこのディクショナリのコンテナ に対してさらにエントリを加えます。 3つめの引数maxlevelsで再帰呼び出しのレベルを設定します； もし制限しないなら、0にします。 この引数は再帰呼び出しでそのまま渡されます。 4つめの引数levelで現在のレベルを設定します； 再帰呼び出しでは、現在の呼び出しより小さい値が渡されます。 バージョン2.3 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.25 pprint Up: 3.25 pprint Next: 3.26 repr


3.26 repr -- もう一つのrepr()の実装

reprモジュールは結果の文字列の大きさを制限したオブジェクト表現を作り出すための方法を提供します。これはPythonデバッガで使われていますが、他の状況でも同じように役に立つかもしれません。

このモジュールはクラスとインスタンス、それに関数を提供します:

class Repr( )
組み込みクラスrepr()によく似た関数を実装するために役に立つ書式化サービスを提供します。過度に長い表現を作り出さないように、異なるオブジェクト型に対する大きさの制限が追加されます。

aRepr
これは下で説明されるrepr()関数を提供するために使われるReprのインスタンスです。このオブジェクトの属性を変更すると、repr()とPythonデバッガが使うサイズ制限に影響します。

repr( obj)
これはaReprのrepr()メソッドです。同じ名前の組み込み関数が返す文字列と似ていますが、最大サイズに制限のある文字列を返します。

  • 3.26.1 Reprオブジェクト
  • 3.26.2 Reprオブジェクトをサブクラス化する
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.25.1 PrettyPrinter オブジェクト Up: 3. Python ランタイム サービス Next: 3.26.1 Reprオブジェクト


3.26.1 Reprオブジェクト

Reprインスタンスは様々なオブジェクト型の表現にサイズ制限を与えるために使えるいくつかのメンバーと、特定のオブジェクト型を書式化するメソッドを提供します。

maxlevel
再帰的な表現を作る場合の深さ制限。デフォルトは6です。

maxdict
maxlist
maxtuple
指定されたオブジェクト型に対するエントリ表現の数についての制限。maxdictに対するデフォルトは4で、その他に対しては6です。

maxlong
長整数の表現のおける文字数の最大値。中央の数字が抜け落ちます。デフォルトは40です。

maxstring
文字列の表現における文字数の制限。文字列の``通常の''表現は文字の材料だということに注意してください: 表現にエスケープシーケンスが必要とされる場合は、表現が短縮されたときにこれらはマングルされます。デフォルトは30です。

maxother
この制限はReprオブジェクトに利用できる特定の書式化メソッドがないオブジェクト型のサイズをコントロールするために使われます。maxstringと同じようなやり方で適用されます。デフォルトは20です。

repr( obj)
インスタンスが強制する書式化を使う組み込みrepr()と等価なもの。

repr1( obj, level)
repr()が使う再帰的な実装。これはどの書式化メソッドを呼び出すかを決定するためにobjの型を使い、それをobjとlevelに渡します。再帰呼び出しにおいてlevelの値に対してlevel - 1を与える再帰的な書式化を実行するために、型に固有のメソッドはrepr1()を呼び出します。

repr_type( obj, level)
型名に基づく名前をもつメソッドとして、特定の型に対する書式化メソッドは実装されます。メソッド名では、typeはstring.join(string.split(type(obj).__name__, '_'))に置き換えられます。これらのメソッドへのディスパッチはrepr1()によって処理されます。再帰的に値の書式を整える必要がある型固有のメソッドは、"self.repr1(subobj, level - 1)"を呼び出します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.26 repr Up: 3.26 repr Next: 3.26.2 Reprオブジェクトをサブクラス化する


3.26.2 Reprオブジェクトをサブクラス化する

更なる組み込みオブジェクト型へのサポートを追加するためや、すでにサポートされている型の扱いを変更するために、Repr.repr1()による動的なディスパッチを使ってReprをサブクラス化することができます。この例はファイルオブジェクトのための特別なサポートを追加する方法を示しています:

import repr
import sys

class MyRepr(repr.Repr):
    def repr_file(self, obj, level):
        if obj.name in ['<stdin>', '<stdout>', '<stderr>']:
            return obj.name
        else:
            return `obj`

aRepr = MyRepr()
print aRepr.repr(sys.stdin)          # prints '<stdin>'
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.26.1 Reprオブジェクト Up: 3.26 repr Next: 3.27 new


3.27 new -- ランタイム内部オブジェクトの作成

newモジュールはインタプリタオブジェクト作成関数へのインターフェイスを与えます。新しいオブジェクトを``魔法を使ったように''作り出す必要がある、通常の作成関数が使えないときに、これは主にマーシャル型関数で使われます。このモジュールはインタプリタへの低レベルインターフェイスを提供します。したがって、このモジュールを使うときには注意しなければなりません。

newモジュールは次の関数を定義しています:

instance( class[, dict])
この関数は__init__()コンストラクタを呼び出さずに辞書dictをもつclassのインスタンスを作り出します。dictが省略されるか、Noneである場合は、新しいインスタンスのために新しい空の辞書が作られます。オブジェクトがいつもと同じ状態であるという保証はないことに注意してください。

instancemethod( function, instance, class)
この関数はinstanceに束縛されたメソッドオブジェクトか、あるいはinstanceがNoneの場合に束縛されていないメソッドオブジェクトを返します。functionは呼び出し可能でなければなりません。

function( code, globals[, name[, argdefs]])
与えられたコードとグローバル変数をもつ(Python)関数を返します。nameを与えるならば、文字列かNoneでなければならない。文字列の場合は、関数は与えられた名前をもつ。そうでなければ、関数名はcode.co_nameから取られる。argdefsを与える場合はタプルでなければならず、パラメータのデフォルト値を決めるために使われます。

code( argcount, nlocals, stacksize, flags, codestring, constants, names, varnames, filename, name, firstlineno, lnotab)
この関数はPyCode_New()というC関数へのインターフェイスです。

module( name)
この関数はnameという名前の新しいモジュールオブジェクトを返します。nameは文字列でなければならない。

classobj( name, baseclasses, dict)
この関数は新しいクラスオブジェクトを返します。そのクラスオブジェクトは(クラスのタプルであるべき)baseclassesから派生し、名前空間dictを持ち、nameという名前です。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.26.2 Reprオブジェクトをサブクラス化する Up: 3. Python ランタイム サービス Next: 3.28 site


3.28 site -- サイト固有の設定フック

このモジュールは初期化中に自動的にインポートされます。

Pythonの初期のバージョンでは(1.5a3を含むそれまでは)、サイト固有のモジュールを使う必要のあるスクリプトやモジュールは"import site"をコードの先頭付近に置いていました。もはやこれは必要ありません。

これはサイト固有のパスをモジュール検索パスへ付け加えます。

前部と後部からなる最大で四つまでのディレクトリを作成することから始めます。前部には、sys.prefixとsys.exec_prefixを使用します。空の前部は省略されます。後部には、(MacintoshやWindowsでは)空文字列を使用し、(Unixでは)最初にlib/python2.3/site-packagesを使ってからlib/site-pythonを使います。別個の前部-後部の組み合わせのそれぞれに対して、それが存在するディレクトリを参照しているかどうかを調べ、もしそうならばsys.pathへ追加します。そして、設定ファイルを新しく追加されたパスからも検索します。

パス設定ファイルはpackage.pthという形式の名前をもつファイルです。その内容はsys.pathに追加される追加項目(一行に一つ)です。存在しない項目はsys.pathへは決して追加されませんが、項目が(ファイルではなく)ディレクトリを参照しているかどうかはチェックされません。項目がsys.pathへ二回以上追加されることはありません。空行と#で始まる行は読み飛ばされます。importで始まる行は実行されます。

例えば、sys.prefixとsys.exec_prefixが/usr/localに設定されていると仮定します。そのときPython 2.3.3 ライブラリは/usr/local/lib/python2.3にインストールされています(ここで、sys.versionの最初の三文字だけがインストールパス名を作るために使われます)。ここにはサブディレクトリ/usr/local/lib/python2.3/site-packagesがあり、その中に三つのサブディレクトリfoo、barおよびspamと二つのパス設定ファイルfoo.pthとbar.pthをもつと仮定します。foo.pthには以下のものが記載されていると想定してください:

# foo package configuration

foo
bar
bletch

また、bar.pthには:

# bar package configuration

bar

が記載されているとします。そのとき、次のディレクトリがsys.pathへこの順番んで追加されます:

/usr/local/lib/python2.3/site-packages/bar
/usr/local/lib/python2.3/site-packages/foo

bletchは存在しないため省略されるということに注意してください。barディレクトリはfooディレクトリの前に来ます。なぜなら、bar.pthがアルファベット順でfoo.pthの前に来るからです。また、spamはどちらのパス設定ファイルにも記載されていないため、省略されます。

これらのパス操作の後に、sitecustomizeという名前のモジュールをインポートしようします。そのモジュールは任意のサイト固有のカスタマイゼーションを行うことができます。ImportError例外が発生してこのインポートに失敗した場合は、何も表示せずに無視されます。

いくつかの非Unixシステムでは、sys.prefixとsys.exec_prefixは空で、パス操作は省略されます。しかし、sitecustomizeのインポートはそのときでも試みられます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.27 new Up: 3. Python ランタイム サービス Next: 3.29 user


3.29 user -- ユーザー設定のフック

ポリシーとして、Pythonは起動時にユーザー毎の設定を行うコードを実行することは しません(ただし対話型セッションで環境変数PYTHONSTARTUPが設定されて いた場合にはそのスクリプトを実行します。)。

しかしながら、プログラムやサイトによっては、プログラムが要求した時に ユーザーごとの設定ファイルを実行できると便利なこともあります。このモジュー ルはそのような機構を実装しています。この機構を利用したいプログラムでは、 以下の文を実行してください。

import user

userモジュールはユーザーのホームディレクトリの .pythonrc.pyファイルを探し、オープンできるならグローバル名前空間 で実行します(execfile()を利用します)。 この段階で発生したエラーはcatchされません。userモジュー ルをimportしたプログラムに影響します。ホームディレクトリは環境変数 HOMEが仮定されていますが、もし設定されていなければカレントディ レクトリが使われます。

ユーザーの.pythonrc.pyではPythonのバージョンに従って異なる動作を 行うためにsys.versionのテストを行うことが 考えられます。

ユーザーへの警告: .pythonrc.pyファイルに書く内容には慎重になって ください。どのプログラムが利用しているかわからない状況で、標準のモジュール や関数のふるまいを替えることはおすすめできません。

この機構を使おうとするプログラマへの提案: あなたのパッケージ向けのオプションをユーザーが設定できるようにするシンプ ルな方法は、.pythonrc.pyファイルで変数を定義して、あなたのプログ ラムでテストする方法です。たとえば、spamモジュールで メッセージ出力のレベルを替える user.spam_verbose変数を参照するに は以下のようにします:

import user
try:
    verbose = user.spam_verbose  # ユーザーの設定値
except AttributeError:
    verbose = 0                  # デフォルト値

大規模な設定の必要があるプログラムではプログラムごとの設定ファイルを作る といいです。

セキュリティやプライバシーに配慮するプログラムではこのモジュールをimport しないでください。このモジュールを使うと、ユーザーは .pythonrc.pyに任意のコードを書くことで簡単に侵入することができて しまいます。

汎用のモジュールではこのモジュールをimportしないでください。 importしたプログラムの動作にも影響してしまいます。

参考資料:

siteモジュール:
サイト毎のカスタマイズを行う機構.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.28 site Up: 3. Python ランタイム サービス Next: 3.30 __builtin__


3.30 __builtin__ -- 組み込み関数

このモジュールはPythonの全ての「組み込み」識別子を直接アクセスするための ものです。例えば __builtin__.open はopen()関数のための 全ての組み込み関数を表示します。 第2.1節, ``組み込み関数''も参照してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.29 user Up: 3. Python ランタイム サービス Next: 3.31 __main__


3.31 __main__ -- トップレベルのスクリプト環境

このモジュールはPythonインタプリタのメインプログラムがコマンドを実行す る際の環境をあらわしています。このモジュールを利用することで、通常は無 名のこの環境にアクセスすることができます。実行されるコマンドは標準入力、 スクリプトファイルあるいは対話環境での入力プロンプトから入力されます。 この環境はPythonスクリプトをメインプログラムとして実行される際によく使 われる``条件付きスクリプト''の一節が実行される環境です。

if __name__ == "__main__":
    main()
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.30 __builtin__ Up: 3. Python ランタイム サービス Next: 3.32 __future__


3.32 __future__ -- Future ステートメントの定義

__future__ は実際にモジュールであり、3つの役割があります。

  • import ステートメントを解析する既存のツールを混乱させるのを避け、 そのステートメントがインポートしようとしているモジュールを見つけ られるようにするため。

  • 2.1 以前のリリースで future ステートメントが実行されれば、最低でも ランタイム例外を投げるようにするため。 (__future__ はインポートできません。というのも、2.1 以前 にはそういう名前のモジュールはなかったからです。)

  • いつ互換でない変化が導入され、いつ強制的になる - あるいは、 なった - のか文書化するため。 これは実行できる形式で書かれたドキュメントでなので、__future__ をインポートし、その中身を調べるようプログラムすれば確かめられます。

__future__.py の各ステートメントは次のような形をしています:

FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease ","
                        CompilerFlag ")"

ここで、普通は、OptionalRelease は MandatoryRelease より小さく、2つとも sys.version_info と同じフォーマットの5つのタプルからなります。

    (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
     PY_MINOR_VERSION, # the 1; an int
     PY_MICRO_VERSION, # the 0; an int
     PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
     PY_RELEASE_SERIAL # the 3; an int
    )

OptionalRelease はその機能が導入された最初のリリースを記録します。

まだ時期が来ていない MandatoryRelease の場合、MandatoryRelease は その機能が言語の一部となるリリースを記します。

その他の場合、MandatoryRelease はその機能がいつ言語の一部になったのかを 記録します。 そのリリースから、あるいはそれ以降のリリースでは、この機能を使う際に future ステートメントは必要ではありませんが、future ステートメントを 使い続けても構いません。

MandatoryRelease は None になるかもしれません。つまり、予定された機能が 破棄されたということです。

_Feature クラスのインスタンスには対応する2つのメソッド、 getOptionalRelease() と getMandatoryRelease() があります。

CompilerFlag は動的にコンパイルされるコードでその機能を有効にするために、 組み込み関数 compile() の第4引数に渡されなければならない (ビットフィールド)フラグです。 このフラグは _Future インスタンスの compilier_flag 属性に 保存されています。

__future__ で解説されている機能のうち、削除されたものはまだ ありません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.31 __main__ Up: 3. Python ランタイム サービス Next: 4. 文字列処理


4. 文字列処理

この章で解説されているモジュールは文字列を操作するさまざまな処理を提供し ます。以下に概要を示します。

string | 一般的な文字列操作
re | Perl 風の式シンタックスを用いた 正規表現検索とマッチ操作。
struct | 文字列データをパックされたバイナリデータとして解釈します。
difflib | オブジェクト同士の違いを計算する
fpformat | 浮動小数点をフォーマットする汎用関数。
StringIO | ファイルのように文字列を読み書きする。
cStringIO | StringIOを高速にしたものだが、サブクラス化はできない。
textwrap | テキストの折り返しと詰め込み
codecs | データやストリームをエンコード・デコードする
encodings.idna | 国際化ドメイン名実装
unicodedata | Access the Unicode Database.
stringprep | RFC 3453 による文字列調製

stringオブジェクトのメソッドについては、8節の ``文字列型のメソッド''もごらんください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.32 __future__ Up: Python ライブラリリファレンス Next: 4.1 string


4.1 string -- 一般的な文字列操作

このモジュールは、文字クラスのチェックに役立つ定数と、文字列を扱う関数を 定義しています。正規表現を使った関数については reモジュールを参照してください。

このモジュールで定義される定数は以下のとおりです。

ascii_letters
後述の ascii_lowercase とascii_uppercase を合わ せたもの。この値はロケールに依存しません。

ascii_lowercase
小文字 'abcdefghijklmnopqrstuvwxyz'。この値はロケールに依存せ ず、変更されません。

ascii_uppercase
大文字 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'。この値はロケールに依存せ ず、変更されません。

digits
文字列 '0123456789'。

hexdigits
文字列 '0123456789abcdefABCDEF'。

letters
後述の lowercase と uppercase を合わせた文字列。 具体的な値はロケールに依存し、locale.setlocale() が呼ばれたと きに更新されます。

lowercase
小文字として扱われる文字全てを含む文字列。 ほとんどのシステムにおいて、 これは文字列 'abcdefghijklmnopqrstuvwxyz' です。 この定義を 変更してはいけません -- upper() と swapcase() に対する影響が定義されていないからです。具体的な値はロケールに依存し、 locale.setlocale() が呼ばれたときに更新されます。

octdigits
文字列 '01234567'。

punctuation
"C" ロケールにおいて、句読点として扱われる ASCII 文字の文字列。

printable
印刷可能な文字で構成される文字列。これは digits、 letters、punctuation、whitespace を組 み合わせたもの。

uppercase
大文字として扱われる文字全てを含む文字列。 ほとんどのシステムにおいて、 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' です。 この定義を変更してはいけま せん -- lower() と swapcase() に対する影響が 定義されていないからです。 具体的な値はロケールに依存し、 locale.setlocale() が呼ばれたと きに更新されます。

whitespace
空白扱いの文字全てを含む文字列。ほとんどのシステムにおいて、これはスペ ース、タブ、改行、リターン、改頁、垂直タブです。この定義を変更しないこ と -- strip() と split() に対する影響が定義され ていないからです。

このモジュールで提供されるほとんどの関数は、string オブジェクトと Unicode オブジェクトのメソッドでも定義されています。詳細は ``String メソ ッド'' (8 ) を参照のこと。このモジュールで定義される 関数は以下のとおりです。

atof( s)
リリース 2.0 以降で撤廃された仕様です。 組み込み関数 float() を使いましょう。
文 字列を浮動 小数点型の数値に変換します。文字列は Python の浮動小数点リ テ ラルの文法に 従っている必要があります。先頭に符号（"+" また は "-"）が付く のは構いません。この関数は、組み込み関数 float() に文字列が渡された場合と同じよう にふるまいます。

注意: 文字列が渡されたとき、内在する C ライブラリによって NaNや Infinityが返されることがあります。 これ らの値に変換される文字列がどれであるかは、完全に C ライブラリに 依存す るので、ライブラリによって異なることが知られています。

atoi( s[, base])
リリース 2.0 以降で撤廃された仕様です。 組み込み関数 int() を使いましょう。
文字 列 s を、base を基数とする整数に変換します。 文字列は１ 桁以上の 数字で構成されている必要があります。先頭に符号（"+" ま たは "-"） が付くのは構いません。base のデフォルト値は 10。 これが 0 の場合 は、（符号を省いた後の）先頭文字によってデフォルト値 が決定します。 "0x" か "0X" なら 16、"0" なら 8、その 他の場合は 10 が 基数になります。 base が 16 の場合、先頭の "0x" や "0X" は常に受け付け られますが、必須ではありません。 この関数は、組み込み関数 int() に 文字列が渡されたときと同 じようにふるまいます。（注意: より柔軟な数値リテラ ル解釈が必要であれ ば、組み込み関数 eval() を使いましょう）

atol( s[, base])
リリース 2.0 以降で撤廃された仕様です。 組み込み関数 long() を使ういましょう。
文字列 s を、 base を基数とする long 整数に変換します。 文字列は１桁以 上の数字で構成されている必要があります。先頭に符号（ "+" または "-"）が付くのは構いません。 引数 base は atoi() の 場合と同じ意味。 基数が 0 の場合を除いて、文字 列末尾の "l" や "L" は認めらません。base が与えられ ないときと、この値に 10 が指定されたとき、この関数は組み込み関数 long() に文字列が渡されたときと同じように ふるまいます。

capitalize( word)
先頭文字だけ大文字にした word のコピーを返します。

capwords( s)
引数で与えられた文字列をsplit() で単語に分割し、 capitalize() で各単語の先頭文字を大文字化し、それを join() で連結します。 この関数は連続した空白文字を、スペー ス1つに置換し、先頭と末尾の空白を削除することに注意しましょう。

expandtabs( s[, tabsize])
タブを展開、すなわちタブを1つ以上のスペースに置換します。スペースの 個数は現在のコラム位置とタブ幅によって決定されます。コラム位置は文字列 中 に改行が出現する度に、0 にリセットされます。この関数は、改行以外の 非表 示文字やエスケープシーケンスを理解しません。タブ幅のデフォルト値 は 8 です。

find( s, sub[, start[,end]])
s[start:end] の中で、部分文字列 sub が 完全に含まれるもののうち、最初に見つかった位置を s のインデック スで返す。見つからなかった場合は -1 を返す。 start と end のデフォルト値、および、負数が与えられた場合の 解釈はスライ スと同じ。

rfind( s, sub[, start[, end]])
find() と同じですが、最後に見つかったもののインデックスを返 します。

index( s, sub[, start[, end]])
find() と同じですが、部分文字列が見つからなかったときに ValueError を発生させます。

rindex( s, sub[, start[, end]])
rfind() と同じですが、部分文字列が見つからなかったときに ValueError を発生させます。

count( s, sub[, start[, end]])
s[start:end] の中で、部分文字列 sub が （重ならずに）出現する回数を返します。start と end のデフォ ルト値、および、負数が与えられた場合の 解釈はスライスと同じです。

lower( s)
大文字を小文字に変換した、s のコピーを返します。

maketrans( from, to)
translate() と regex.compile() に渡して、 from に含まれる各文字を、to の同じ位置にある文字に置換する ような変換テーブルを返します。from と to は同じ長さでな ければいけません。

警告: lowercase と uppercase から得られる文字 列を、引数にしてはいけません。ロケールによっては、これらは長さが異なる。 大文字小文字の変換には、常に lower() と upper() を使いましょう。

split( s[, sep[, maxsplit]])
文字列 s に含まれる単語を、リストにして返します。 第 2 引数 sep が指定されなかった場合と None が指定された場合 には、 各単語は任意の空白（スペース、タブ、改行、リターン、改頁）で 区切られ ます。第 2 引数 sep が指定され、かつ、それが None でなけ れば、その文字列が単語の区切りになる。返されるリストの要素数は、文字列 内で重複しない区切り文字列の数より、1個多くなります。 第 3 引数 maxsplit のデフォルト値は 0。 この引数が 0 以外の場合、多くとも maxsplit 箇所で区切り、残りの文字列は、リストの最後の要素として 返されます（したがって、リストは多くとも maxsplit+1 個の 要素を持ちます）。

splitfields( s[, sep[, maxsplit]])
この関数は split() と同じようにふるまいます（昔は
split() は引数1つの場合でのみ使われ、
splitfields() は引数2つの場合でのみ使われていました）。

join( words[, sep])
単語のリストまたはタプルの要素を、sep を間に入れて連結します。 sep のデフォルト値はスペース1個。 "string.join(string.split(s, sep), sep)" は、常 に s です。

joinfields( words[, sep])
この関数は join() と同じふるまいをします（昔は、 join() は引数1つの場合でのみ使われ、joinfields() は引数2つの場合でのみ使われていました）。 オブジェクトには joinfields() メソッドがないことに注意してください。 join() メソッドを使いましょう。

lstrip( s[, chars])
先頭の文字を取り除いた文字列のコピーを返します。chars が与えられない場合や、chars の値が None の場合、先頭の空白を取り除きます。chars が与えられ、その値が None でない場合、このメソッドを呼んだ文字列から、chars に含まれる文字を取り除きます。 chars は文字列でなくてはいけません。 バージョン2.2.3 以降で変更された 仕様: chars パラメータを追加。 初期の 2.2 バージョンでは、versionschars パラメータを渡せない

rstrip( s[, chars])
末尾の文字を取り除いた文字列のコピーを返します。chars が与えられない場合や、chars の値が None の場合、末尾の空白を取り除きます。chars が与えられ、その値が None でない場合、このメソッドを呼んだ文字列から、chars に含まれる文字を取り除きます。 chars は文字列でなくてはいけません。 バージョン2.2.3 以降で変更された 仕様: chars パラメータを追加。 初期の 2.2 バージョンでは、versionschars パラメータを渡せない

strip( s[, chars])
先頭と末尾の文字を取り除いた文字列のコピーを返します。chars が与えられない場合や、chars の値が None の場合、先頭と末尾の空白を取り除きます。chars が与えられ、その値が None でない場合、このメソッドを呼んだ文字列から、chars に含まれる文字を取り除きます。 chars は文字列でなくてはいけません。 バージョン2.2.3 以降で変更された 仕様: chars パラメータを追加。 初期の 2.2 バージョンでは、versionschars パラメータを渡せない

swapcase( s)
s の大文字と小文字を入れ替えたものを返します。

translate( s, table[, deletechars])
s の中から、（もし指定されていれば）deletechars に含まれる 文字を削除し、table を使って文字を入れ替えたものを返します。 table は 256 文字からなる文字列で、各文字の位置が、置換前の文字 コードに対応します。

upper( s)
s に含まれる小文字を大文字に置換して返します。

ljust( s, width)
rjust( s, width)
center( s, width)
これらの関数は、与えられた文字列幅の中で、それぞれ左寄せ、右寄せ、中央 寄せします。これらが返す文字列は、少なくとも width 文字分の長さが あり、s の右側、左側、または両側がスペースで埋まっている。文字列 が切られることはない。

zfill( s, width)
数値文字列の左側を、与えられた幅に達するまで 0 で埋めます。符号で始まる 場合も、正しく処理されます。

replace( str, old, new[, maxreplace])
s 内の部分文字列 old を全て new に置換したものを返し ます。 maxreplace が指定された場合、最初に見つかった maxreplace 個分だけ置換します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4. 文字列処理 Up: 4. 文字列処理 Next: 4.2 re


4.2 re -- 正規表現操作

このモジュールは、Perl で見られるものと同様な正規表現マッチング操作を 提供します。正規表現のパターン文字列にヌルバイトを含むことはできませんが、 \number 記法を使って、ヌルバイトを指定することはできます。 パターンおよび検索される文字列の両方で、 8ビット文字列と同じ様に Unicode 文字列を 使うことができます。 re モジュールはいつでも利用できます。

正規表現では、特殊な形式を表したり、特殊な文字の特別な意味を呼び出さずに その特殊な文字を使うことができるようにするために、バックスラッシュ文字 ("\") を使います。このことは、Python の、文字列リテラルの 同一文字は同一目的で使用するということと矛盾します；例えば、 文字通りのバックスラッシュとマッチするには、パターン文字列として '\\\\' と書かなければなりません、というのは、正規表現は "\\" でなければならず、各バックスラッシュは、正規な Python 文字列リテラル内では "\\" と表現しなければならないからです。

これは、正規表現パターンに Python の raw string 記法を使うことで 解決されます；"r"を前に付けた文字列リテラル内では、 バックスラッシュは、特別な風には全く処理されません。ですから、 r"\n" は "\" と "n"を含む2文字の文字列であり、 一方 "\n" は、改行を含む一文字文字列です。 Python コード中では、パターンは、 ふつう、この raw string 記法を使って表現されます。

参考資料:

Mastering Regular Expressions 詳説 正規表現
Jeffrey Friedl 著、O'Reilly 刊の正規表現に関する本です。 この本の第2版ではPyhonについては触れていませんが、 良い正規表現パターンの書き方を非常に詳細に説明しています。

  • 4.2.1 正規表現のシンタックス
  • 4.2.2 マッチング vs 検索
  • 4.2.3 モジュール コンテンツ
  • 4.2.4 正規表現オブジェクト
  • 4.2.5 MatchObject オブジェクト
  • 4.2.6 例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.1 string Up: 4. 文字列処理 Next: 4.2.1 正規表現のシンタックス


4.2.1 正規表現のシンタックス

正規表現(すなわち RE)は、それとマッチする文字列の集合を指定します； このモジュールの関数によって、特別な文字列が与えられた正規表現と マッチするかどうか（あるいは与えられた正規表現が特別な文字列と マッチするかどうか、これは結局同じことになりますが）を検査できます。

正規表現は、連結して新しい正規表現を作ることができます； もし A と B が、ともに正規表現であれば、 AB も正規表現です。一般的には、もし文字列 p が A とマッチし、 別の文字列 q が B とマッチすれば、文字列 pqは AB にマッチ します。ただし、この状況が成り立つのは A や B が 優先度の低い演算や A と B との間の境界条件、あるいは 番号付けされたグループ参照を含まない場合だけです。 かくして、ここで述べるような、より簡単でプリミティブな正規表現から、 複雑な正規表現を容易に構築することができます、 正規表現に関する理論と実装の詳細については、上記の Friedl 本か、コンパイラー構造に関する大抵の教科書を調べて下さい。

以下で正規表現の形式に関する簡単な説明をしておきます。より詳細な情報や よりやさしい説明に関しては、http://www.python.org/doc/howto/からアクセスできる正規表現ハウツウを調べて下さい。

正規表現には、特殊文字と通常文字の両方を含めることができます。 "A"、 "a"、あるいは "0"のような 殆どの通常文字は、もっとも簡単な正規表現です；それらは、単純にそれら 自身とマッチします。通常文字を連結することもできますので、 last は文字列 'last'とマッチします。(このセクションの 残りでは、RE を普通引用符なしで この特殊な形式で書き、 マッチされる文字列は、'単一引用符内'に書きます。)

"|" や "("のようないくつかの文字は特殊文字です。 特殊文字は通常文字クラスを表すか、あるいは通常文字に関する 正規表現がどのように解釈されるかに影響します。

特殊文字は：

"."
(ドット。) デフォールトのモードでは、これは改行以外の 任意の文字とマッチします。もしDOTALL フラグが指定されていれば、 これは、改行も含むすべての文字とマッチします。

"^"
(キャレット。) 文字列の先頭と マッチし、MULTILINE モードでは、各改行の直後と マッチします。

"$"
文字列の末尾、あるいは文字列の末尾の改行の 直前とマッチします。 fooは、'foo' と'foobar' の両方とマッチし、 一方、正規表現 foo$は、'foo' だけとマッチします。 もっと興味深いことは、'foo1\nfoo2\n' で foo.$を検索すると、 普通は 'foo2' とマッチするのですが、 MULTILINEモードでは 'foo1' とマッチします。

"*"
結果の RE は、 前にある RE を、0 回以上できるだけ多く繰り返したものと マッチするようになります。ab* は、 'a'、'ab'、あるいは 'a' に任意個数の'b' を続けたものとマッチします。

"+"
結果の RE は、 前にある RE を、1 回以上繰り返したものと マッチするようになります。ab+ は、'a' に非ゼロ個の 'b' が 続いたものとマッチします；これは、'a' だけとはマッチしません。

"?"
結果の RE は、 前にある RE を、0 回か 1回繰り返したものとマッチするようになります。 ab? は、'a' あるいは 'ab' とマッチします。

*?, +?, ??
"*"、 "+"、および "?" 修飾子は、すべて 欲張り(greedy)です； それらはできるだけ多くのテキストとマッチします。時にはこの動作が 望ましくない場合があります； もし RE <.*> を、 '<H1>title</H1>'とマッチさせると、これは、全文字列とマッチし、 '<H1>'だけとはマッチしません。"?"を修飾子の後に追加すると、 控え目な(non-greedy) あるいは 最小 風のマッチをするようになります； できるだけ 少ない 文字とマッチします。前の式で .*?を使うと、 '<H1>' だけとマッチします。

{m}
前にある RE の m 回の正確なコピーとマッチすべきであることを指定 します；マッチ回数が少なければ、RE 全体ではマッチしません。例えば、 a{6} は、正確に 6個の "a" 文字とマッチしますが、 5個ではマッチしません。

{m,n}
結果の RE は、前にある RE を、 m回からn 回まで繰り返したもので、 できるだけ多く繰り返したものとマッチするように、マッチします。 例えば、a{3,5}は、3個から 5個の "a" 文字とマッチします。 mを省略するとマッチ回数の下限として0を指定した事になり、 n を省略することは、上限が無限であることを指定します； a{4,}b は aaaabや、千個の "a" 文字に bが 続いたものとマッチしますが、aaabとはマッチしません。 コンマは省略できません、そうでないと修飾子が上で述べた形式と混同されてしまうからです。

{m,n}?
結果の RE は、前にある RE の m回からn 回まで繰り返したもので、できるだけ少なく 繰り返したものとマッチするように、マッチします。これは、前の修飾子の 控え目バージョンです。 例えば、 6文字 文字列 'aaaaaa'では、a{3,5} は、5個の "a" 文字とマッチしますが、a{3,5}? は3個の文字と マッチするだけです。

"\"
特殊文字をエスケープする( "*"や "?"等のような文字との マッチをできるようにする)か、あるいは、特殊シーケンスの合図です; 特殊シーケンスは後で議論します。

もしパターンを表現するのに raw string を使用していないのであれば、 Python も、バックスラッシュを文字列リテラルでのエスケープシーケンスとして 使っていることを覚えていて下さい；もしエスケープシーケンスを Python の構文解析器が認識して処理しなければ、そのバックスラッシュと それに続く文字は、結果の文字列にそのまま含まれます。しかし、もし Python が 結果のシーケンスを認識するのであれば、バックスラッシュを 2回 繰り返さなければ いけません。このことは複雑で理解しにくいので、 最も簡単な表現以外は、 すべて raw string を使うことをぜひ勧めます。

[]
文字の集合を指定するのに使用します。文字は個々に リストするか、文字の範囲を、2つの文字と"-"でそれらを分離 して指定することができます。特殊文字は集合内では有効ではありません。 例えば、[akm$]は、文字 "a"、"k"、 "m"、あるいは "$"のどれかとマッチします； [a-z] は、任意の小文字と、[a-zA-Z0-9] は、 任意の文字や数字とマッチします。 (以下で定義する) \w や\Sのような 文字クラスも、範囲に含めることができます。もし文字集合に "]" や "-" を含めたいのなら、その前にバックスラッシュを 付けるか、それを最初の文字として指定します。たとえば、パターン []] は ']' とマッチします。

範囲内にない文字とは、その集合の補集合をとることで マッチすることができます。これは、集合の最初の文字として "^" を含めることで表すことができます； 他の場所にある "^"は、単純に "^"文字とマッチするだけです。例えば、 [^5] は、 "5"以外の任意の文字とマッチし、 [^^] は、 "^" 以外の任意の文字とマッチします。

"|"
A|B は、ここで A と B は任意の RE ですが、 A か B のどちらかとマッチする正規表現を作成します。任意個数の RE を、 こういう風に "|" で分離することができます。これはグループ (以下参照) 内部でも同様に使えます。検査対象文字列をスキャンする中で、 "|" で分離された RE は左から右への順に検査されます。 一つでも完全にマッチしたパターンがあれば、そのパターン枝が受理されます。 このことは、もし A がマッチすれば、たとえB によるマッチが 全体としてより長いマッチになったとしても、B を決して検査しないことを 意味します。 言いかえると、"|" 演算子は決して貪欲 (greedy) ではありません。 文字通りの "|"とマッチするには、\| を使うか、 あるいはそれを [|] のように文字クラス内に入れます。

(...)
丸括弧の中にどのような正規表現があってもマッチし、 またグループの先頭と末尾を表します；グループの中身は、マッチが 実行された後に検索され、後述する \number 特殊シーケンス付きの文字列内で、後でマッチされます。 文字通りの "(" や ")"とマッチするには、 \( あるいは \) を 使うか、それらを文字クラス内に入れます： [(] [)]。

(?...)
これは拡張記法です( "(" に続く"?"は他には意味がありません)。 "?"の後の最初の文字が、この構造の意味とこれ以上の シンタックスがどういうものであるかを決定します。 拡張記法は普通新しいグループを作成しません； (?P<name>...)がこの規則の唯一の例外です。 以下に現在サポートされている拡張記法を示します。

(?iLmsux)
( 集合 "i"、"L"、 "m"、 "s"、"u"、"x" から1文字以上)。グループは空文字列ともマッチします；文字は、 正規表現全体の対応するフラグ (re.I、 re.L、 re.M、 re.S、 re.U、 re.X ) を設定します。 これはもしflag 引数をcompile() 関数に渡さずに、そのフラグを正規表現の一 部として含めたいならば 役に立ちます。

(?x) フラグは、式が構文解析される 方法を変更することに注意して下さい。 これは式文字列内の最初か、あるいは1つ以上の空白文字の後で使うべきです。 もしこのフラグの前に非空白文字があると、その結果は未定義です。

(?:...)
正規表現の丸括弧の非グループ化バージョンです。 どのような正規表現が丸括弧内にあってもマッチしますが、 グループによってマッチされたサブ文字列は、 マッチを実行したあと検索されることも、あるいは後でパターンで 参照されることも できません。

(?P<name>...)
正規表現の丸括弧と同様ですが、 グループによってマッチされたサブ文字列は、記号グループ名 nameを介してアクセスできます。グループ名は、正しい Python 識別子でなければならず、各グループ名は、正規表現内で一度だけ定義され なければなりません。記号グループは、グループに名前が付けられていない場合のように、 番号付けされたグループでもあります。そこで上の例で 'id'という名前がついた グループは、番号グループ 1 として参照することもできます。

たとえば、もしパターンが (?P<id>[a-zA-Z_]\w*)であれば、このグループは、 マッチオブジェクトのメソッドへの引数に、 m.group('id') あるいは m.end('id')のような名前で、 またパターンテキスト内(例えば、 (?P=id)) や 置換テキスト内( \g<id>のように) で名前で参照することができます。

(?P=name)
前に name と名前付けされたグループに マッチした、いかなるテキストにもマッチします。

(?#...)
コメントです；括弧の内容は 単純に無視されます。

(?=...)
もし ...が次に続くものとマッチすればマッチしますが、 文字列をまったく消費しません。これは先読みアサーション(lookahead assertion)と呼ばれます。 例えば、Isaac (?=Asimov) は、'Isaac 'に 'Asimov'が続く場合だけ、'Isaac 'とマッチします。

(?!...)
もし ... が次に続くものとマッチしなければマッチします。 これは否定先読みアサーション(negative lookahead assertion)です。例えば、 Isaac (?!Asimov)は、'Isaac ' に 'Asimov'が続かない場合のみマッチします。

(?<=...)
もし文字列内の現在位置の前に、 現在位置で終わる ... とのマッチがあれば、マッチします。 これは 肯定後読みアサーション(positive lookbehind assertion)と呼ばれます。 (?<=abc)def は、"abcdef" にマッチを見つけます、 というのは後読みが3文字をバックアップして、含まれているパターンと マッチするかどうか検査するからです。含まれるパターンは、 固定長の文字列にのみマッチしなければなりません、ということは、 abc や a|b は許されますが、 a* や a{3,4} は許されないことを意味します。 肯定後読みアサーションで始まるパターンは、検索される文字列の 先頭とは決してマッチしないことに注意して下さい； 多分、match() 関数よりは search()関数を使いたいでしょう：

>>> import re
>>> m = re.search('(?<=abc)def', 'abcdef')
>>> m.group(0)
'def'

この例ではハイフンに続く単語を探します：

>>> m = re.search('(?<=-)\w+', 'spam-egg')
>>> m.group(0)
'egg'

(?<!...)
もし文字列内の現在位置の前に ...との マッチがないならば、マッチします。これは 否定後読みアサーション(negative lookbehind assertion)と呼ばれます。 肯定後読みアサーションと同様に、含まれるパターンは固定長さの文字列だけに マッチしなければいけません。否定後読みアサーションで始まるパターンは、 検索される文字列の先頭とマッチすることができます。

特殊シーケンスは "\" と以下のリストにある文字から 構成されます。もしリストにあるのが通常文字でないならば、結果の RE は 2番目の文字とマッチします。例えば、 \$ は文字 "$"とマッチします。

\number
同じ番号のグループの中身とマッチします。 グループは1から始まる番号をつけられます。例えば、 (.+) \1 は、'the the' あるいは '55 55'とマッチしますが、 'the end'とはマッチしません(グループの後のスペースに注意して下さい)。 この特殊シーケンスは最初の 99 グループのうちの一つとマッチするのに使うことが できるだけです。もし numberの最初の桁が 0 である、すなわち numberが 3 桁の8進数であれば、それはグループのマッチとは解釈されず、 8進数値 number を持つ文字として解釈されます。 文字クラスの "["と "]"の中の数値エスケープは、文字として 扱われます。

\A
文字列の先頭だけにマッチします。

\b
空文字列とマッチしますが、単語の先頭か末尾の時だけです。 単語は英数字あるいは下線文字の並んだものとして定義されていますので、単語の末尾は 空白あるいは非英数字、非下線文字によって表されます。 \b は、\w と \Wの間の境界として定義されているので、 英数字であると見なされる文字の正確な集合は、UNICODEとLOCALEフラグの 値に依存することに注意して下さい。 文字の範囲の中では、\b は、 Python の文字列リテラルと互換性を持たせるために、 後退(backspace)文字を表します。

\B
空文字列とマッチしますが、それが単語の先頭あるいは末尾に ない時だけです。これは \bのちょうど反対ですので、 LOCALE とUNICODEの設定にも影響されます。

\d
任意の十進数とマッチします；これは 集合 [0-9] と同じ意味です。

\D
任意の非数字文字とマッチします；これは 集合 [^0-9]と同じ意味です。

\s
任意の空白文字とマッチします；これは 集合 [ \t\n\r\f\v]と同じ意味です。

\S
任意の非空白文字とマッチします；これは 集合 [^ \t\n\r\f\v] と同じ意味です。

\w
LOCALE とUNICODE フラグが 指定されていない時は、任意の英数文字および下線とマッチします；これは、集合 [a-zA-Z0-9_]と同じ意味です。LOCALEが設定されていると、 集合 [0-9_] プラス 現在のロケール用に英数字として定義されている任意の 文字とマッチします。 もし UNICODE が設定されていれば、 文字 [0-9_] プラス Unicode 文字特性データベースで英数字として分類されて いるものとマッチします。

\W
LOCALEと UNICODE フラグが 指定されていない時、任意の非英数文字とマッチします；これは 集合 [^a-zA-Z0-9_]と同じ意味です。 LOCALEが指定されていると、 集合 [0-9_]になく、 現在のロケールで英数字として定義されていない任意の文字とマッチします。 もし UNICODEがセットされていれば、これは [0-9_] および Unicode 文字特性データベースで 英数字として表されている文字以外のものとマッチします。

\Z
文字列の末尾とのみマッチします。

Python 文字列リテラルによってサポートされている標準エスケープの ほとんども、正規表現パーザに認識されます：

\a      \b      \f      \n
\r      \t      \v      \x
\\

8進エスケープは制限された形式で含まれています：もし第1桁が 0 であるか、もし8進3桁であれば、それは8進エスケープとみなされます。 そうでなければ、それはグループ参照です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.2 re Up: 4.2 re Next: 4.2.2 マッチング vs 検索


4.2.2 マッチング vs 検索

Python は、正規表現に基づく、2つの異なるプリミティブな操作を 提供しています：マッチと検索です。もしあなたが Perl の記号に慣れているのであれば、 検索操作があなたの求めるものです。 search() 関数と、 コンパイルされた正規表現オブジェクトでの 対応するメソッドを見て下さい。

マッチは、"^"で始まる正規表現を使うと、検索とは 異なるかもしれないことに注意して下さい： "^" は文字列の先頭でのみ、あるいは MULTILINE モードでは改行の直後ともマッチします。 ``マッチ'' 操作は 、もしそのパターンが、モードに拘らず文字列の先頭とマッチ するか、あるいは改行がその前にあるかどうかに拘らず、省略可能な pos 引数によって 与えられる先頭位置でマッチする場合のみ成功します。

re.compile("a").match("ba", 1)           # 成功
re.compile("^a").search("ba", 1)         # 失敗； 'a' は先頭にない
re.compile("^a").search("\na", 1)        # 失敗； 'a' は先頭にない
re.compile("^a", re.M).search("\na", 1)  # 成功
re.compile("^a", re.M).search("ba", 1)   # 失敗； \n が前にない

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.2.1 正規表現のシンタックス Up: 4.2 re Next: 4.2.3 モジュール コンテンツ


4.2.3 モジュール コンテンツ

このモジュールは以下の関数および定数、それに例外を定義しています：

compile( pattern[, flags])
正規表現パターンを正規表現オブジェクトにコンパイルします。 このオブジェクトは、以下で述べる match() と search() メソッドを使って、マッチングに使うことが できます。

式の動作は、flagsの値を指定することで加減することが できます。値は以下の変数を、ビットごとの OR ( | 演算子)を 使って組み合わせることができます。

シーケンス

prog = re.compile(pat)
result = prog.match(str)

は、

result = re.match(pat, str)

と同じ意味ですが、compile() を使うバージョンの方が、 その式を一つのプログラムで何回も使う時にはより効率的です。

I
IGNORECASE
大文字・小文字を区別しないマッチングを実行します； [A-Z]のような式は、 小文字にもマッチします。これは現在のロケールには 影響されません。

L
LOCALE
\w、 \W、 \bおよび \B を、現在のロケールに従わさせます。

M
MULTILINE
指定されると、パターン文字 "^" は、 文字列の先頭および各行の先頭(各改行の直後)とマッチします；そして パターン文字 "$" は文字列の末尾および各行の末尾 (改行の直前)とマッチします。デフォールトでは、 "^" は、 文字列の先頭とだけマッチし、 "$"は、文字列の末尾および文字列の末尾の 改行の直前(がもしあれば)とマッチします。

S
DOTALL
特殊文字 "." を、改行をを含む任意の文字と、とにかくマッチ させます；このフラグがなければ、"." は、改行 以外の 任意の文字とマッチします。

U
UNICODE
\w、 \W、 \b および \B を、Unicode 文字特性データベースに従わさせます。 バージョン2.0 以降で新規追加された 仕様です。

X
VERBOSE
このフラグによって、より見やすく正規表現を書くことができます。 パターン内の空白は、文字クラス内にあるか、エスケープされていない バックスラッシュが前にある時以外は無視されます。 また、行に、文字クラス内にもなく、エスケープされていない バックスラッシュが前にもない "#" がある時は、 そのような "#"の左端から その行の末尾までが無視されます。

search( pattern, string[, flags])
string全体を走査して、正規表現 pattern がマッチを発生する 位置を探して、対応する MatchObject インスタンスを返します。 もし文字列内に、そのパターンとマッチする位置がないならば、 None を返します； これは、文字列内のある点で長さゼロのマッチ を探すこととは異なることに注意して下さい。

match( pattern, string[, flags])
もし string の先頭で0 個以上の文字が正規表現 pattern と マッチすれば、対応する MatchObject インスタンスを返します。 もし文字列がパターンとマッチしなければ、 None を返します； これは長さゼロのマッチとは異なることに 注意して下さい。

注意: もし string のどこかにマッチを位置付けたいのであれば、 代わりに search() を使って下さい。

split( pattern, string[, maxsplit = 0])
stringを、 patternがあるたびに分割します。もし 括弧のキャプチャが patternで使われていれば、パターン内の すべてのグループのテキストも結果のリストの一部として返されます。 maxsplit がゼロでなければ、高々 maxsplit個の分割が 発生し、文字列の残りは、リストの最終要素として返されます。 (非互換性ノート：オリジナルの Python 1.5 リリースでは、 maxsplitは無視されていました。これはその後のリリースでは 修正されました。)

>>> re.split('\W+', 'Words, words, words.')
['Words', 'words', 'words', '']
>>> re.split('(\W+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '']
>>> re.split('\W+', 'Words, words, words.', 1)
['Words', 'words, words.']

この関数は、古い regsub.split() とregsub.splitx()の 機能を結合して拡張したものです。

findall( pattern, string)
string 内の patternの重複しないマッチのすべての リストを返します。もしパターンにグループが1つ以上あれば、 グループのリストを返します；これは、もしパターンにグループが 1つ以上あれば、タプルのリストとなります。他にマッチがなければ、 空のマッチも結果に入ります。 バージョン1.5.2 以降で新規追加された 仕様です。

finditer( pattern, string)
string 内の RE patternの重複しないマッチのすべての イテレータを返します。各マッチごとに、イテレータはマッチ オブジェクトを返します。他にマッチがなければ、 空のマッチも結果に入ります。 バージョン2.2 以降で新規追加された 仕様です。

sub( pattern, repl, string[, count])
string 内で、 patternと重複しないマッチの内、一番左にあるものを 置換 repl で置換して得られた文字列を返します。もしパターンが 見つからなければ、string を変更せずに返します。 repl は文字列でも関数でも構いません；もしそれが文字列であれば、 それにある任意のバックスラッシュエスケープは処理されます。すなわち、 "\n" は単一の改行文字に変換され、"\r"は、 行送りコードに変換されます、等々。 "\j" のような未知のエスケープはそのままにされます。 "\6"のような後方参照(backreference)は、パターンのグループ 6 とマッチ したサブ文字列で置換されます。 例えば：

>>> re.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*\(\s*\):',
...        r'static PyObject*\npy_\1(void)\n{',
...        'def myfunc():')
'static PyObject*\npy_myfunc(void)\n{'

もし repl が関数であれば、重複しない patternが発生する たびにその関数が呼ばれます。この関数は一つのマッチオブジェクト 引数を取り、置換文字列を返します。例えば：

>>> def dashrepl(matchobj):
....    if matchobj.group(0) == '-': return ' '
....    else: return '-'
>>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
'pro--gram files'

パターンは、文字列でも RE でも構いません；もし正規表現フラグを指定する 必要があれば、RE オブジェクトを使うか、パターンに埋込み修飾子を使わ なければなりません；たとえば、"sub("(?i)b+", "x", "bbbb BBBB")" は 'x x' を返します。

省略可能な引数 count は、置換されるパターンの出現回数の 最大値です；count は非負の整数でなければなりません。 もし省略されるかゼロであれば、出現したものがすべて置換されます。 パターンのマッチが空であれば、以前のマッチと隣合わせでない時だけ 置換されますので、"sub('x*', '-', 'abc')" は '-a-b-c-' を 返します。

上で述べた文字エスケープや後方参照の他に、 "\g<name>" は、 (?P<name>...) のシンタックスで定義されているように、 "name" という名前のグループとマッチしたサブ文字列を 使います。"\g<number>" は対応するグループ番号を使います； それゆえ "\g<2>" は "\2"と同じ意味ですが、 "\g<2>0" のような置換でもあいまいではありません。 "\20" は、 グループ 20 への参照として解釈されますが、グループ 2 にリテラル文字 "0" が続いたものへの参照としては解釈されません。 後方参照 "\g<0>" は、 RE とマッチするサブ文字列全体を置き換えます。

subn( pattern, repl, string[, count])
sub() と同じ操作を行いますが、タプル (new_string、 number_of_subs_made)を返します。

escape( string)
バックスラッシュにすべての非英数字をつけたstringを返します；これは もし、その中に正規表現のメタ文字を持つかもしれない任意のリテラル文字列と マッチしたいとき、役に立ちます。

exception error
ここでの関数の一つに渡された文字列が、正しい正規表現ではない時 (例えば、その括弧が対になっていなかった)、あるいはコンパイルや マッチングの間になんらかのエラーが発生したとき、発生する例外です。 たとえ文字列がパターンとマッチしなくても、 決してエラーではありません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.2.2 マッチング vs 検索 Up: 4.2 re Next: 4.2.4 正規表現オブジェクト


4.2.4 正規表現オブジェクト

コンパイルされた正規表現オブジェクトは、以下のメソッドと属性をサポート します：

match( string[, pos[, endpos]])
もし stringの先頭の 0 個以上の文字がこの正規表現とマッチすれば、 対応する MatchObject インスタンスを返します。 もし文字列がパタンーとマッチしなければ、None を返します； これは長さゼロのマッチとは異なることに 注意して下さい。

注意: もしマッチを string のどこかに位置付けたければ、 代わりに search() を使って下さい。

省略可能な第2のパラメータ posは、文字列内の検索を始めるインデッスクを 与えます；デフォールトでは 0 です。これは、文字列のスライシングと 完全に同じ意味だというわけではありません；'^' パターン文字は、 文字列の実際の先頭と改行の直後とマッチしますが、 それが必ずしも検索が開始するインデックスであるわけでは ないからです。

省略可能なパラメータ endposは、どこまで文字列が検索されるかを 制限します；あたかもその文字列が endpos 文字長であるかのように しますので、 pos から endpos - 1 までの文字が、 マッチのために検索されます。もし endpos が posより小さければ、 マッチは見つかりませんが、そうでなくて、もしrx がコンパイルされた 正規表現オブジェクトであれば、 rx.match(string, 0, 50) は rx.match(string[:50], 0)と同じ意味になります。

search( string[, pos[, endpos]])
string全体を走査して、この正規表現がマッチする位置を探して、 対応する MatchObject インスタンスを返します。もし文字列内に パターンとマッチする位置がないならば、None を返します； これは文字列内のある点で長さゼロのマッチを探すこととは異なることに 注意して下さい。

省略可能な pos と endpos パラメータは、 match() メソッドのものと同じ意味を持ちます。

split( string[, maxsplit = 0])
split() 関数と同様で、コンパイルしたパターンを使います。

findall( string)
findall() 関数と同様で、コンパイルしたパターンを使います。

finditer( string)
finditer() 関数と同様で、コンパイルしたパターンを使います。

sub( repl, string[, count = 0])
sub() 関数と同様で、コンパイルしたパターンを使います。

subn( repl, string[, count = 0])
subn() 関数と同様で、コンパイルしたパターンを使います。

flags
flags 引数は、RE オブジェクトがコンパイルされたとき使われ、 もし flags が何も提供されなければ 0 です。

groupindex
(?P<id>)で定義された任意の記号グループ名の、グループ番号 への辞書マッピングです。もし記号グループが パターン内で何も使われていなければ、辞書は空です。

pattern
RE オブジェクトがそれからコンパイルされたパターン文字列です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.2.3 モジュール コンテンツ Up: 4.2 re Next: 4.2.5 MatchObject オブジェクト


4.2.5 MatchObject オブジェクト

MatchObject インスタンスは以下のメソッドと属性を サポートします：

expand( template)
テンプレート文字列 template に、sub() メソッドがするような バックスラッシュ置換をして得られる文字列を返します。 "\n"のようなエスケープは適当な文字に変換され、数値の後方参照 ("\1"、 "\2") と名前付きの後方参照 ("\g<1>"、 "\g<name>") は、対応するグループの 内容で置き換えられます。

group( [group1, ...])
マッチした1個以上のサブグループを返します。もし引数で一つであれば、 その結果は一つの文字列です；複数の引数があれば、その結果は、 引数ごとに一項目を持つタプルです。引数がなければ、 group1 はデフォールトでゼロです(マッチしたものすべてが 返されます)。 もし groupN 引数がゼロであれば、対応する戻り値は、マッチ する文字列全体です；もしそれが範囲 [1..99] 内であれば、それは、対応する 丸括弧つきグループとマッチする文字列です。もしグループ番号が負であるか、 あるいはパターンで定義されたグループの数より大きければ、 IndexError 例外が発生します。もしグループがマッチしなかった パターンの一部に含まれていれば、対応する結果は None です。 もしグループが、複数回マッチしたパターンの一部に 含まれていれば、 最後のマッチが返されます。

もし正規表現が (?P<name>...) シンタックスを使うならば、 groupN引数は、それらのグループ名によってグループを識別する文字列であっても 構いません。もし文字列引数がパターンのグループ名として使われていないもので あれば、IndexError 例外が発生します。

適度に複雑な例題：

m = re.match(r"(?P<int>\d+)\.(\d*)", '3.14')

このマッチを実行したあとでは、m.group(1) は m.group('int') と同じく、'3' であり、そしてm.group(2) は '14' です。

groups( [default])
1からどれだけ多くであろうがパターン内にあるグループ数までの、 マッチの、すべてのサブグループを含むタプルを返します。 default 引数は、マッチに加わらなかったグループ用に使われます； それはデフォールトでは None です。 (非互換性ノート：オリジナルの Python 1.5 リリースでは、たとえタプルが一要素長で あっても、その代わりに文字列を返すことはありません。(1.5.1 以降の)後のバージョンでは、 そのような場合には、シングルトンタプルが返されます。)

groupdict( [default])
すべての 名前つきのサブグループを含む、マッチの、 サブグループ名でキー付けされた辞書を返します。 default 引数はマッチに加わらなかったグループ用に 使われます；それはデフォールトでは Noneです。

start( [group])
end( [group])
groupとマッチしたサブ文字列の先頭と末尾のインデックスを 返します；group は、デフォールトでは (マッチしたサブ文字列 全体を意味する）ゼロです。 group が存在してもマッチに寄与しなかった場合は、 -1 を返します。マッチオブジェクト m および マッチに寄与しなかったグループ gがあって、 グループ g とマッチしたサブ文字列 ( m.group(g)と同じ意味ですが) は、

m.string[m.start(g):m.end(g)]

です。 もし groupがヌル文字列とマッチすれば、 m.start(group)が m.end(group) と等しくなろことに 注意して下さい。例えば、 m = re.search('b(c?)', 'cba') の後では、m.start(0)は 1 で、 m.end(0) は 2 であり、 m.start(1) と m.end(1) はともに 2 であり、 m.start(2) は IndexError例外を発生します。

span( [group])
MatchObject m については、 2-タプル (m.start(group)、 m.end(group))を 返します。もし group がマッチに寄与しなかったら、これは (-1, -1) です。また group はデフォールトでゼロです。

pos
RegexObject の search() あるいは match() メソッドに渡された posの値です。 これは RE エンジンがマッチを探し始める位置の文字列のインデックスです。

endpos
RegexObject の search() あるいは match() メソッドに渡された endposの値です。 これは RE エンジンがそれ以上は進まない位置の文字列のインデックスです。

lastindex
最後にマッチした取り込みグループの整数インデックスです。もしどのグループも 全くマッチしなければ None です。

lastgroup
最後にマッチした取り込みグループの名前です。もしグループに名前がないか、 あるいはどのグループも全くマッチしなければ None です。

re
その match()あるいは search() メソッドが、この MatchObject インスタンスを生成した正規表現オブジェクトです。

string
match() あるいは search()に渡された文字列です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.2.4 正規表現オブジェクト Up: 4.2 re Next: 4.2.6 例


4.2.6 例

scanf()をシミュレートする

Python には現在のところ、scanf()に相当するものがありません。 正規表現は、 scanf()のフォーマット文字列よりも、一般的に より強力であり、また冗長でもあります。以下の表に、 scanf() のフォーマットトークンと正規表現の 大体同等な対応付けを示します。

scanf() トークン | 正規表現
%c | .
%5c | .{5}
%d | [-+]?\d+
%e, %E, %f, %g | [-+]?(\d+(\.\d*)?|\d*\.\d+)([eE][-+]?\d+)?
%i | [-+]?(0[xX][\dA-Fa-f]+|0[0-7]*|\d+)
%o | 0[0-7]*
%s | \S+
%u | \d+
%x, %X | 0[xX][\dA-Fa-f]+

    /usr/sbin/sendmail - 0 errors, 4 warnings

のような文字列からファイル名と数値を抽出するには、

    %s - %d errors, %d warnings

のように scanf()フォーマットを使うでしょう。 それと同等な正規表現は

    (\S+) - (\d+) errors, (\d+) warnings

再帰を避ける

エンジンに大量の再帰を要求するような正規表現を作成すると、 maximum recursion limit exceeded(最大再帰制限を超過した) というメッセージを持つ RuntimeError 例外に出くわすかもしれません。たとえば、

>>> import re
>>> s = "Begin" + 1000 * 'a very long string' + 'end'
>>> re.match('Begin (\w| )*? end', s).end()
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
  File "/usr/local/lib/python2.3/sre.py", line 132, in match
    return _compile(pattern, flags).match(string)
RuntimeError: maximum recursion limit exceeded

再帰を避けるように正規表現を組みなおせることはよくあります。

Python 2.3 からは、再帰を避けるために *? パターンの利用が 特別扱いされるようになりました。したがって、上の正規表現は Begin [a-zA-Z0-9_ ]*?end に書き直すことで再帰を防ぐことが できます。それ以上の恩恵として、そのような正規表現は、 再帰的な同等のものよりもより速く動作します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.2.5 MatchObject オブジェクト Up: 4.2 re Next: 4.3 struct


4.3 struct -- 文字列データをパックされたバイナリデータとして解釈する

このモジュールは、 Python の値と Python 上で文字列データとして表される C の構造体データとの間の変換を実現します。このモジュールでは、C 構造体の レイアウトおよび Python の値との間で行いたい変換をコンパクトに表現する ために、フォーマット文字列 を使います。 このモジュールは特に、ファイルに保存されたり、ネットワーク接続を経由 したバイナリデータを扱うときに使われます。

このモジュールは以下の例外と関数を定義しています:

exception error
様々な状況で送出された例外です; 引数は何が問題かを記述する文字列 です。

pack( fmt, v1, v2, ...)
値 v1, v2, ... が与えられたフォーマット で含まれる文字列データを返します。引数は指定したフォーマットが要求する 型と正確に一致していなければなりません。

unpack( fmt, string)
(おそらく pack(fmt, ...) でパックされた) 文字列 データを、与えられた書式に従ってアンパックします。値が一つしかない場合を 含め、結果はタプルで返されます。文字列データにはフォーマットが要求する だけのデータが正確に含まれていなければなりません (len(string) が calcsize(fmt) と一致しなければ なりません)。

calcsize( fmt)
与えられたフォーマットに対応する構造体のサイズ (すなわち文字列データの サイズ) を返します。

フォーマット文字 (format character) は以下の意味を持っています; C と Python の間の変換では、値は正確に以下に指定された型でなくては なりません:

フォーマット | C での型 | Python | 備考
x | pad byte | no value |
c | char | 長さ 1 の文字列 |
b | signed char | 整数型 (integer) |
B | unsigned char | 整数型 |
h | short | 整数型 |
H | unsigned short | 整数型 |
i | int | 整数型 |
I | unsigned int | long 整数型 |
l | long | 整数型 |
L | unsigned long | long 整数型 |
q | long long | long 整数型 | (1)
Q | unsigned long long | long 整数型 | (1)
f | float | 浮動小数点型 |
d | double | 浮動小数点型 |
s | char[] | 文字列 |
p | char[] | 文字列 |
P | void * | 整数型 |

注意事項:

(1)
フォーマット文字 "q" および "Q" は、 プラットフォームの C コンパイラが C の long long 型、 Windows では __int64 をサポートする場合にのみ、 プラットフォームネイティブの値との変換を行うモードだけで利用することが できます。

バージョン2.2 以降で新規追加された 仕様です。

フォーマット文字の前に整数をつけ、繰り返し回数 (count) を指定することが できます。 例えば、フォーマット文字列 '4h' は 'hhhh' と全く同じ 意味です。

フォーマット文字間の空白文字は無視されます; count とフォーマット 文字の間にはスペースを入れてはいけません。

フォーマット文字 "s" では、count は文字列のサイズと して扱われます。他のフォーマット文字のように繰り返し回数ではありません; 例えば、'10c' が 10 個のキャラクタを表すのに対して、 '10s' は 10 バイトの長さを持った 1 個 の文字列です。文字列をパックする際には、 指定した長さにフィットするように、必要に応じて切り詰められたりヌル文字 で穴埋めされたりします。また特殊なケースとして、('0c' が 0 個の キャラクタを表すのに対して) '0s' は 1 個の空文字列を意味します。

フォーマット文字 "p" は "Pascal 文字列 (pascal string)" をコードします。Pascal 文字列は固定長のバイト列に収められた短い可変長の 文字列です。count は実際に文字列データ中に収められる全体の長さ です。このデータの先頭の 1 バイトには文字列の長さか255 のうち、小さい 方の数が収められます。その後に文字列のバイトデータが続きます。 pack() に渡された Pascal 文字列の長さが長すぎた (count-1 よりも長い) 場合、先頭の count-1 バイトが書き込まれます。文字列が count-1 よりも短い場合、指定した count バイトに達するまでの残りの 部分はヌルで埋められます。unpack() では、フォーマット文字 "p" は指定された count バイトだけデータを読み込みますが、 返される文字列は決して 255 文字を超えることはないので注意してください。

フォーマット文字 "I"、 "L"、 "q" および "Q" では、返される値は Python long 整数です。

フォーマット文字 "P" では、返される値は Python 整数型または long 整数型で、これはポインタの値を Python での整数にキャストする際に、 値を保持するために必要なサイズに依存します。 NULL ポインタは常に Python 整数型の 0 になります。 ポインタ型のサイズを持った値をパックする際には、Python 整数型 および long 整数型オブジェクトを使うことができます。例えば、 Alpha および Merced プロセッサは 64 bit のポインタ値を使いますが、これは ポインタを保持するために Python long 整数型が使われることを意味します; 32 bit ポインタを使う他のプラットフォームでは Python 整数型が使われ ます。

デフォルトでは、C では数値はマシンのネイティブ (native) の形式 およびバイトオーダ (byte order) で表され、適切にアラインメント (alignment) するために、必要に応じて数バイトのパディングを行ってスキップします (これは C コンパイラが用いるルールに従います)。

これに代わって、フォーマット文字列の最初の文字を使って、バイトオーダや サイズ、アラインメントを指定することができます。指定できる文字を 以下のテーブルに示します:

文字 | バイトオーダ | サイズおよびアラインメント
@ | ネイティブ | ネイティブ
= | ネイティブ | 標準
< | リトルエンディアン | 標準
> | ビッグエンディアン | 標準
! | ネットワークバイトオーダ (= ビッグエンディアン) | 標準

フォーマット文字列の最初の文字が上のいずれかでない場合、"@" であるとみなされます。

ネイティブのバイトオーダはビッグエンディアンかリトルエンディアンで、 ホスト計算機に依存します。例えば、Motorola および Sun のプロセッサは ビッグエンディアンです; Intel および DEC のプロセッサはリトルエンディアン です。

ネイティブのサイズおよびアラインメントは C コンパイラの sizeof 式で決定されます。ネイティブのサイズおよびアラインメントは大抵ネイティブ のバイトオーダと同時に使われます。

標準のサイズおよびアラインメントは以下のようになります: どの型に対しても、 アラインメントは必要ありません (ので、パディングを使う必要があります); short は 2 バイトです; int と long は 4 バイトです; long long (Windows では __int64) は 8 バイトです; float と double は順に 32-bit あるいは 64-bit の IEEE 浮動小数点数です。

"@" と "=" の違いに注意してください: 両方とも ネイティブのバイトオーダですが、後者のバイトサイズやバイトオーダは 標準のものに合わせてあります。

"!" 表記法はネットワークバイトオーダがビッグエンディアンか リトルエンディアンか忘れちゃったという熱意に乏しい人向けに用意されて います。

バイトオーダに関して、「(強制的にバイトスワップを行う)ネイティブの逆」 を指定する方法はありません; "<" または ">" のうち ふさわしい方を選んでください。

"P" フォーマット文字はネイティブバイトオーダでのみ利用可能 です (デフォルトのネットワークバイトオーダに設定するか、"@" バイトオーダ指定文字を指定しなければなりません)。 "=" を指定 した場合、ホスト計算機のバイトオーダに基づいてリトルエンディアンと ビッグエンディアンのどちらを使うかを決めます。struct モジュールはこの 設定をネイティブのオーダ設定として解釈しないので、"P" を 使うことはできません。

以下に例を示します (この例は全てビッグエンディアンのマシンで、 ネイティブのバイトオーダ、サイズおよびアラインメントの場合です):

>>> from struct import *
>>> pack('hhl', 1, 2, 3)
'\x00\x01\x00\x02\x00\x00\x00\x03'
>>> unpack('hhl', '\x00\x01\x00\x02\x00\x00\x00\x03')
(1, 2, 3)
>>> calcsize('hhl')
8

ヒント: 特定の型によるアラインメント要求に従うように構造体の末端を そろえるには、count をゼロにした特定の型でフォーマットを終端します。 例えば、フォーマット 'llh0l' は、 long 型が 4 バイトを境界と してそろえられていると仮定して、末端に 2 バイトをパディングします。 この機能は変換対象がネイティブのサイズおよびアラインメントの場合 にのみ働きます; 標準に型サイズおよびアラインメントの設定ではいかなる アラインメントも行いません。

参考資料:

arrayモジュール:
一様なデータ型からなるバイナリ記録データのパック.
xdrlibモジュール:
XDR データのパックおよびアンパック。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.2.6 例 Up: 4. 文字列処理 Next: 4.4 difflib


4.4 difflib -- 差異の計算を助ける

バージョン2.1 以降で新規追加された 仕様です。

class SequenceMatcher
柔軟性のあるクラスで、ハッシュ化できる要素の連続であれば、 どんな型のものであっても比較可能です。基礎的なアルゴリズムは 可塑的なものであり、1980年代の後半に発表されたRatcliffとObershelp によるアルゴリズム、大げさに名づけられた``ゲシュタルトパターン マッチング''よりはもう少し良さそうなものです。その考え方は、 ``junk''要素を含まない最も長いマッチ列を探すことです（Ratcliffと Obershelpのアルゴリズムではjunkを示しません）。このアイデアは、 下位のマッチ列から左または右に伸びる列の断片に対して再帰的に あてはまります。これは小さな文字列に対して効率良いものでは ありませんが、人間の目からみて「良く見える」ようにマッチする 傾向があります。

タイミング: 基本的なRatcliff-Obershelpアルゴリズムは、 予想の3乗、最悪の場合でも2乗となります。SequenceMatcher オブジェクトは、最悪のケースに比べて4倍、予想される挙動は、 シーケンスの中にどのくらいの要素があるのか（最良なのは一列の場合）、 というややこしい状況に依存しています。

class Differ
テキスト行からなるシーケンスを比較するクラスです。人が読むことの できる差異を作成します。DifferクラスはSequenceMatcher クラスを利用します。これらは、列からなるシーケンスを比較し、 （ほぼ）同一の列内の文字を比較します。

Differクラスによる差異の各行は、2文字のコードではじめられます。

コード 意味
'- ' 列は文字列1にのみ存在する
'+ ' 列は文字列2にのみ存在する
' ' 列は両方の文字列で同一
'? ' 列は入力文字列のどちらにも存在しない

'? 'で始まる列は線内の差異に注意を向けようとします。その差異は、 入力されたシーケンスのどちらにも存在しません。シーケンスが タブ文字を含むとき、これらのラインは判別しづらいものになる ことがあります。

context_diff( a, b[, fromfile[, tofile [, fromfiledate[, tofiledate[, n [, lineterm]]]]]])

a と b (文字列のリスト) を比較し、差異 (差異のある行を生成するジェネレータ) を、diff のコンテクスト形式で返します。

コンテクスト形式は、変更があった行に前後数行を加えてある、コンパクトな表 現方法です。変更箇所は、変更前/変更後に分けて表します。コンテクスト（変 更箇所前後の行）の行数は n で指定し、デフォルト値は 3 です。

デフォルトでは、diff の制御行 (*** や -- を含む行) の最 後には、改行文字が付加されます。この場合、入出力共、行末に改行文字を持つ ので、file.readlines() で得た入力から生成した差異を、 file.writelines() に渡す場合に便利です。行末に改行文字を持た ない入力に対しては、出力でも改行文字を付加しないように lineterm 引 数に "" を渡してください。

diff コンテクスト形式は、通常、ヘッダにファイル名と変更時刻を持ってい ます。この情報は、文字列 fromfile、tofile、fromfiledate、 tofiledate で指定できます。変更時刻の書式は、通常、 time.ctime() の戻り値と同じものを使います。指定しなかった場合 のデフォルト値は、空文字列です。

Tools/scripts/diff.py は、この関数のコマンドラインのフロントエンド（インターフェイス）になっています。

バージョン2.3 以降で新規追加された 仕様です。

get_close_matches( word, possibilities[, n[, cutoff]])
最も「十分」なマッチのリストを返します。wordは、なるべく マッチして欲しい（一般的には文字列の）シーケンスです。 possibilitiesはwordにマッチさせる（一般的には文字列） シーケンスのリストです。

オプションの引数n（デフォルトでは3）はメソッドの返す マッチの最大数です。n は 0 より大きくなければなりません。

オプションの引数 cutoff （デフォルトでは 0.6）は、 [0, 1]の間となるfloatの値です。可能性として、少なくとも word が無視されたのと同様の数値にはなりません。

可能性のある、（少なくとも n に比べて）最もよいマッチはリストに よって返され、同一性を表す数値に応じて最も近いものから順に格納されます。

>>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])
['apple', 'ape']
>>> import keyword
>>> get_close_matches('wheel', keyword.kwlist)
['while']
>>> get_close_matches('apple', keyword.kwlist)
[]
>>> get_close_matches('accept', keyword.kwlist)
['except']

ndiff( a, b[, linejunk[, charjunk]])
a と b （文字列からなるリスト）を比較し、Differ オブジェクト形式の差異（解析器は差異のある列）を返します。

オプションのパラメータ linejunk と charjunk は、filter 機能のためのキーワードです（使わないときは空にする）。

linejunk: string型の引数ひとつを受け取る関数で、文字列が junkか否かによってtrueを（違うときにはtrueを）返します。Python 2.3以降、デフォルトでは（None）になります。それまでは、 モジュールレべルの関数IS_LINE_JUNK()であり、それは 少なくともひとつのシャープ記号（"#"）をのぞく、可視の キャラクタを含まない行をフィルタリングします。 Python 2.3では、下位にあるSequenceMatcherクラスが、 雑音となるくらい頻繁に登場する列であるか否かを、動的に分析します。 これは、バージョン2.3以前でのデフォルト値よりうまく動作します。

charjunk: 長さ1の文字を受け取る関数です。デフォルトでは、 モジュールレべルの関数 IS_CHARACTER_JUNK()であり、これは空白文字列 （空白またはタブ、注：改行文字をこれに含めるのは悪いアイデア！）を フィルタリングします。

Tools/scripts/ndiff.py は、この関数のコマンドラインのフロント エンド（インターフェイス）です。

>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
...              'ore\ntree\nemu\n'.splitlines(1))
>>> print ''.join(diff),
- one
?  ^
+ ore
?  ^
- two
- three
?  -
+ tree
+ emu

restore( sequence, which)
差異を生成したシーケンスのひとつを返します。

与えられるsequenceは Differ.compare() または ndiff()によって生成され、ファイル1または2（引数 whichで指定される）によって元の列に復元され、行頭の プレフィクスが取りのぞかれます。

例:

>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
...              'ore\ntree\nemu\n'.splitlines(1))
>>> diff = list(diff) # materialize the generated delta into a list
>>> print ''.join(restore(diff, 1)),
one
two
three
>>> print ''.join(restore(diff, 2)),
ore
tree
emu

unified_diff( a, b[, fromfile[, tofile [, fromfiledate[, tofiledate[, n [, lineterm]]]]]])

a と b (共に文字列のリスト) を比較し、diff の unified 形式 で、差異 (差分行を生成するジェネレータ) を返します。

unified 形式は変更があった行に前後数行を加えた、コンパクトな表現方法で す。変更箇所は (変更前/変更後を分離したブロックではなく) インライン・ス タイルで表されます。コンテクスト（変更箇所前後の行）の行数は、n で 指定し、デフォルト値は 3 です。

デフォルトでは、diff の制御行 (--、+++、@@ を含 む行) は行末で改行します。この場合、入出力共、行末に改行文字を持つので、 file.readlines() で得た入力を処理して生成した差異を、 file.writelines() に渡す場合に便利です。

行末に改行文字を持たない入力には、出力も同じように改行なしになるように、lineterm 引数を "" にセットしてください

diff コンテクスト形式は、通常、ヘッダにファイル名と変更時刻を持ってい ます。 この情報は、文字列 fromfile、tofile、 fromfiledate、tofiledate で指定できます。変更時刻の書式は、 通常、time.ctime() の戻り値と同じものを使います。 指定しなかっ た場合のデフォルト値は、空文字列です。

Tools/scripts/diff.py は、この関数のコマンドラインのフロントエ ンド（インターフェイス）です。

バージョン2.3 以降で新規追加された 仕様です。

IS_LINE_JUNK( line)
無視できる列のときtrueを返します。列 line が空白、または "#"" ひとつのときには無視できます。それ以外の時には 無視できません。ndiff() の引数linkjunkとして デフォルトで使用されます。 ndiff()のlinejunkはPython 2.3以前のものです。

IS_CHARACTER_JUNK( ch)
無視できる文字のときtrueを返します。文字 ch が空白、または タブ文字のときには無視できます。それ以外の時には無視できません。 ndiff() の引数charjunkとしてデフォルトで使用されます。

参考資料:

Pattern Matching: The Gestalt Approach （パターン マッチング: 全体アプローチ）
John W. Ratcliff と D. E. Metzener による同一性アルゴリズムに関する議論。 Dr. Dobb's Journal 1988年7月号掲載。

  • 4.4.1 SequenceMatcherオブジェクト
  • 4.4.2 SequenceMatcher の例
  • 4.4.3 Differ オブジェクト
  • 4.4.4 Differ の例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.3 struct Up: 4. 文字列処理 Next: 4.4.1 SequenceMatcherオブジェクト


4.4.1 SequenceMatcherオブジェクト

The SequenceMatcher クラスには、以下のようなコンストラクタがあります。:

class SequenceMatcher( [isjunk[, a[, b]]])
オプションの引数 isjunk は、（デフォルトの） None またはsequenceエレメントが与えられた場合にtrueを返し、エレメントが ``junk''の場合に限り無視される、ひとつの引数をもった関数である 必要があります。 b に None が渡されるのは、lambda x: 0; が渡されるのと同じことです。言い換えると、どんな要素も無視されません。 例えば以下のような引数を渡すことで、空白とタブ文字を無視して キャラクタの列を比較します。

lambda x: x in " \t"

オプションの引数 a と b は、比較される文字列です。 デフォルトで、それらは空の文字列で、文字列の要素はハッシュ化できます。

SequenceMatcher オブジェクトは以下のメソッドを持ちます。

set_seqs( a, b)
比較される2つの文字列を設定します。

SequenceMatcher オブジェクトは2つ目の文字列についての詳細な情報を 算定し、保管します。そのため、ひとつの文字列をいくつもの文字列と比較する場合、 まず set_seq2() を使って文字列を設定しておき、別の文字列をひとつづつ 比較するために、繰り返し set_seq() を呼び出します。

set_seq1( a)
比較を行うひとつ目の文字列を設定します。比較される2つ目の文字列は 変更されません。

set_seq2( b)
比較を行う2つめ目のシーケンスを設定します。比較されるひとつ目の シーケンスは変更されません。

find_longest_match( alo, ahi, blo, bhi)
a[alo:ahi] とb[blo: bhi]の中から、最長のマッチ列を探します。

isjunkが省略されたかNoneの時、get_longest_match() はa[i:i+k] がb[j: j+k]と等しいような(i, j, k)を 返します。その値はalo <= i <= i+k <= ahiかつblo <= j <= j+k <= bhiとなります。(i', j', k')でも、 同じようになります。さらにk >= k', i <= i' がi == i', j <= j'でも同様です。 言い換えると、いくつものマッチ列すべてのうち、a内で最初に 始まるものを返します。そしてそのa内で最初のマッチ列すべての うちb内で最初に始まるものを返します。

>>> s = SequenceMatcher(None, " abcd", "abcd abcd")
>>> s.find_longest_match(0, 5, 0, 9)
(0, 4, 5)

引数isjunkが与えられている場合、上記の通り、はじめに再長の マッチ列を判定します。ブロック内にjunk要素が見当たらないような 追加条件の際はこれに該当しません。次にそのマッチ列を、その両側の junk要素にマッチするよう、できる限り広げていきます。そのため結果 となる列は、探している列のたまたま直前にあった同一のjunk以外の junkにはマッチしません。

以下は前と同じサンプルですが、空白をjunkとみなしています。これは ' abcd'が2つ目の列の末尾にある' abcd'にマッチしない ようにしています。代わりに'abcd'にはマッチします。そして 2つ目の文字列中、一番左の'abcd'にマッチします。

>>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")
>>> s.find_longest_match(0, 5, 0, 9)
(1, 0, 4)

どんな列にもマッチしない時は、(alo, blo, 0)を 返します。

get_matching_blocks( )
マッチしたシーケンス中で個別にマッチしたシーケンスをあらわす、 3つの値のリストを返します。それぞれの値は(i, j, n)という形式であらわされ、a[i:i+n] == b[j:j+n]いう関係を意味します。3つの値は iとjの間で単調に増加します。

最後のタプルはダミーで、(len(a), len(b), 0)という 値を持ちます。これはn==0である唯一のタプルです。

>>> s = SequenceMatcher(None, "abxcd", "abcd")
>>> s.get_matching_blocks()
[(0, 0, 2), (3, 2, 2), (5, 4, 0)]

get_opcodes( )
aをbにするための方法を記述する5つのタプルを返します。それぞれの タプルは(tag, i1, i2, j1, j2) という形式であらわされます。最初のタプルはi1 == j1 == 0であり、i1はその前にあるタプルのi2と同じ値です。 同様にj1は前のj2と同じ値になります。

tagの値は文字列であり、次のような意味です。

値 | 意味
'replace' | a[i1:i2]はb[ j1:j2]に置き換えられる
'delete' | a[i1:i2] は削除される。 この時、j1 == j2である
'insert' | b[j1:j2] がa [i1:i1]に挿入される。 この時i1 == i2である。
'equal' | a[i1:i2] == b[j1:j2] (下位の文字列は同一)

例:

>>> a = "qabxcd"
>>> b = "abycdf"
>>> s = SequenceMatcher(None, a, b)
>>> for tag, i1, i2, j1, j2 in s.get_opcodes():
...    print ("%7s a[%d:%d] (%s) b[%d:%d] (%s)" %
...           (tag, i1, i2, a[i1:i2], j1, j2, b[j1:j2]))
 delete a[0:1] (q) b[0:0] ()
  equal a[1:3] (ab) b[0:2] (ab)
replace a[3:4] (x) b[2:3] (y)
  equal a[4:6] (cd) b[3:5] (cd)
 insert a[6:6] () b[5:6] (f)

get_grouped_opcodes( [n])
最大 n 行までのコンテクストを含むグループを生成するような、ジェネレータを返します。

このメソッドは、get_opcodes() で返されるグループの中から、似 たような差異のかたまりに分け、間に挟まっている変更の無い部分を省きます。

グループは get_opcodes() と同じ書式で返されます。

バージョン2.3 以降で新規追加された 仕様です。

ratio( )
[0, 1]の範囲の浮動小数点で、シーケンスの同一性を測る値を返します。

Tが2つのシーケンスそれぞれがもつ要素の総数だと仮定し、Mをマッチした 数とすると、この値は2.0*M/Tであらわされます。もしシーケンスがまったく 同じ場合、値は1.0となり、まったく異なる場合には0.0となります。

このメソッドはget_matching_blocks()またはget_opcodes()が まだ呼び出されていない場合には非常にコストが高く、この時より限定された 機能をもったquick_ratio()もしくはreal_quick_ratio()を 最初に試してみることができます。

quick_ratio( )
ratio()で測定する同一性をより素早く、限定された形で測ります。

このメソッドはratio()より限定されており、これを超えるとは 見なされませんが、高速に実行します。

real_quick_ratio( )
ratio()で測定する同一性を非常に素早く測ります。

このメソッドはratio()より限定されており、これを 超えるとは見なされませんが、ratio()や quick_ratio()より高速に実行します。

この文字列全体のマッチ率を返す3つのメソッドは、異なる近似値に基づく 異なる結果を返します。とはいえ、quick_ratio()と real_quick_ratio()は、常にratio()より大きな値を示します。

>>> s = SequenceMatcher(None, "abcd", "bcde")
>>> s.ratio()
0.75
>>> s.quick_ratio()
0.75
>>> s.real_quick_ratio()
1.0

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.4 difflib Up: 4.4 difflib Next: 4.4.2 SequenceMatcher の例


4.4.2 SequenceMatcher の例

この例は2つの文字列を比較します。空白を``junk''とします。

>>> s = SequenceMatcher(lambda x: x == " ",
...                     "private Thread currentThread;",
...                     "private volatile Thread currentThread;")

ratio() は、[0, 1] の範囲の値を返し、シーケンスの同一性を測ります。 経験によると、ratio() の値が0.6を超えると、シーケンスがよく似て いることを示します。

>>> print round(s.ratio(), 3)
0.866

シーケンスのどこがマッチしているかにだけ興味のある時には get_matching_blocks() が手軽でしょう。

>>> for block in s.get_matching_blocks():
...     print "a[%d] and b[%d] match for %d elements" % block
a[0] and b[0] match for 8 elements
a[8] and b[17] match for 6 elements
a[14] and b[23] match for 15 elements
a[29] and b[38] match for 0 elements

注意:最後のタプルは、get_matching_blocks()が常にダミーで あることで返されるものです。 (len(a), len(b), 0) であり、これは最後のタプルの要素（マッチするようその数）がゼロとなる 唯一のケースです。

はじめのシーケンスがどのようにして2番目のものになるのかを知るには、 get_opcodes() を使います。

>>> for opcode in s.get_opcodes():
...     print "%6s a[%d:%d] b[%d:%d]" % opcode
 equal a[0:8] b[0:8]
insert a[8:8] b[8:17]
 equal a[8:14] b[17:23]
 equal a[14:29] b[23:38]

See also the function get_close_matches() in this module, which shows how simple code building on SequenceMatcher can be used to do useful work. SequenceMatcher を使った、シンプルで使えるコードを知るには、 このモジュールの関数 get_close_matches() を参照してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.4.1 SequenceMatcherオブジェクト Up: 4.4 difflib Next: 4.4.3 Differ オブジェクト


4.4.3 Differ オブジェクト

Differオブジェクトによって抽出された差分は、最小単位の 差分を見ても問題なく抽出されます。反対に、最小の差分の場合にはこれとは 反対のように見えます。それらが、どこれも可能ときに同期するからです。 時折、思いがけなく100ページもの部分にマッチします。隣接するマッチ列の 同期するポイントを制限することで、より長い差異を算出する再帰的なコスト での、局所性の概念を制限します。

Differは、以下のようなコンストラクタを持ちます。

class Differ( [linejunk[, charjunk]])
オプションのパラメータlinejunkとcharjunkはfilter関数の ために指定します（もしくはNoneを指定）。

linejunk:ひとつの文字列引数を受け取れるべき関数です。 文字列がjunkのときにtrueを返します。デフォルトでは、None であり、どんな行であってもjunkとは見なされません。

charjunk: この関数は（長さ1の）文字列を引数として受け取り、文字列が junkであるときにtrueを返します。デフォルトはNoneであり、どんな文字列も junkとは見なされません。

Differオブジェクトは、以下のひとつのメソッドによって使われます （違いを生成します）。

compare( a, b)
文字列からなる2つのシーケンスを比較し、差異（を表す文字列からなる シーケンス）を生成します。

Each sequence must contain individual single-line strings ending with newlines. Such sequences can be obtained from the readlines() method of file-like objects. The delta generated also consists of newline-terminated strings, ready to be printed as-is via the writelines() method of a file-like object. それぞれのシーケンスは、改行文字によって終了する、独立したひと連なりの 文字列でなければなりません。そのようなシーケンスは、ファイル形式オブジェクトの readline()メソッドによって得ることができます。（得られる）差異は 改行文字で終了する文字列として得られ、ファイル形式オブジェクトのwriteline() メソッドによって出力できる形になっています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.4.2 SequenceMatcher の例 Up: 4.4 difflib Next: 4.4.4 Differ の例


4.4.4 Differ の例

この例では2つのテキストを比較します。初めに、改行文字で終了する独立した 1行の連続した（ファイル形式オブジェクトのreadlines()メソッドに よって得られるような）テキストを用意します。

>>> text1 = '''  1. Beautiful is better than ugly.
...   2. Explicit is better than implicit.
...   3. Simple is better than complex.
...   4. Complex is better than complicated.
... '''.splitlines(1)
>>> len(text1)
4
>>> text1[0][-1]
'\n'
>>> text2 = '''  1. Beautiful is better than ugly.
...   3.   Simple is better than complex.
...   4. Complicated is better than complex.
...   5. Flat is better than nested.
... '''.splitlines(1)

次にDifferオブジェクトをインスタンス化します。

>>> d = Differ()

注意：Differオブジェクトをインスタンス化するとき、 ``junk.''である列と文字をフィルタリングす関数を渡すことができます。 詳細はDiffer()コンストラクタを参照してください。

最後に、2つを比較します。

>>> result = list(d.compare(text1, text2))

resultは文字列のリストなので、pretty-printしてみましょう。

>>> from pprint import pprint
>>> pprint(result)
['    1. Beautiful is better than ugly.\n',
 '-   2. Explicit is better than implicit.\n',
 '-   3. Simple is better than complex.\n',
 '+   3.   Simple is better than complex.\n',
 '?     ++                                \n',
 '-   4. Complex is better than complicated.\n',
 '?            ^                     ---- ^  \n',
 '+   4. Complicated is better than complex.\n',
 '?           ++++ ^                      ^  \n',
 '+   5. Flat is better than nested.\n']

これは、複数行の文字列として、次のように出力されます。

>>> import sys
>>> sys.stdout.writelines(result)
    1. Beautiful is better than ugly.
-   2. Explicit is better than implicit.
-   3. Simple is better than complex.
+   3.   Simple is better than complex.
?     ++
-   4. Complex is better than complicated.
?            ^                     ---- ^
+   4. Complicated is better than complex.
?           ++++ ^                      ^
+   5. Flat is better than nested.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.4.3 Differ オブジェクト Up: 4.4 difflib Next: 4.5 fpformat


4.5 fpformat -- 浮動小数点の変換

注意: This module is unneeded: everything here could be done via the % string interpolation operator.

fpformat モジュールは浮動小数点数の表示を 100% 純粋に Python だけで 行うための関数を定義しています。 注意: このモジュールは必要ありません: このモジュールのすべてのことは、 % を使って、文字列の補間演算により可能です。

fpformat モジュールは次にあげる関数と例外を定義しています。

fix( x, digs)

x を [-]ddd.ddd の形にフォーマットします。 小数点の後ろに digs 桁と、小数点の前に少なくとも1桁です。 vardigs <= 0 の場合、小数点以下は切り捨てられます。

x は数字か数字を表した文字列です。

digs は整数です。

返り値は文字列です。

sci( x, digs)

x を [-]d.dddE[+-]ddd の形にフォーマットします。 小数点の後ろに digs 桁と、小数点の前に1桁だけです。

vardigs <= 0 の場合、1桁だけ残され、小数点以下は切り捨てられます。

x は実数か実数を表した文字列です。

digs は整数です。

返り値は文字列です。

exception NotANumber

fix() や sci() にパラメータとして渡された文字列 x が 数字として認識できなかった場合、例外が発生します。 標準の例外が文字列の場合、この例外は ValueError のサブクラスです。 例外値は、例外を発生させた不適切にフォーマットされた文字列です。

例:

>>> import fpformat
>>> fpformat.fix(1.23, 1)
'1.2'
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.4.4 Differ の例 Up: 4. 文字列処理 Next: 4.6 StringIO


4.6 StringIO -- ファイルのように文字列を読み書きする

このモジュールは、(メモリファイルとしても知られている) 文字列のバッファに対して読み書きを行うファイルのようなクラス、 StringIO 、を実装しています。

操作方法についてはファイルオブジェクトの説明を参照してください(セクション 2.3.8)。

class StringIO( [buffer])
StringIO オブジェクトを作る際に、コンストラクターに文字列を渡すこと で初期化することができます。 文字列を渡さない場合、最初は StringIO はカラです。

StringIO オブジェクトはユニコードも 8-bit の文字列も受け付けますが、 この2つを混ぜることには少し注意が必要です。 この2つが一緒に使われると、 getvalue() が呼ばれたときに、 (8th ビットを使っている)7-bit ASCII に解釈できない 8-bit の文字列は、 UnicodeError を引き起こします。

次にあげる StringIO オブジェクトのメソッドには特別な説明が必要です:

getvalue( )

StringIO オブジェクトの close() メソッドが呼ばれる前ならいつでも、 ``file'' の中身全体を返します。 ユニコードと 8-bit の文字列を混ぜることの説明は、上の注意を参照してください。 この2つの文字コードを混ぜると、このメソッドは UnicodeError を 引き起こすかもしれません。

close( )
メモリバッファを解放します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.5 fpformat Up: 4. 文字列処理 Next: 4.7 cStringIO


4.7 cStringIO -- 高速化された StringIO

cStringIO モジュールは StringIO モジュールと同様の インターフェースを提供しています。 StringIO.StringIO オブジェクトを酷使する場合、 このモジュールにある StringIO() 関数をかわりに使うと効果的です。

このモジュールは、ビルトイン型のオブジェクトを返すファクトリー関数を提供しているので、 サブクラス化して自分用の物を作ることはできません。 そうした場合には、オリジナルの StringIO モジュールを使ってください。

StringIO モジュールで実装されているメモリファイルとは異なり、 このモジュールで提供されているものは、プレイン ASCII 文字列にエンコードできない ユニコードを受け付けることができません。

また、引数に文字列を指定してStringIO()呼び出すと読み出し専用のオブジェクト が生成されますが、この場合 cStringIO.StringIO() では write()メソッドを持たない オブジェクトを生成します。

次にあげるデータオブジェクトも提供されています:

InputType
文字列をパラメーターに渡して StringIO を呼んだときに作られるオブジェクトの オブジェクト型。

OutputType
パラメーターを渡さすに StringIO を呼んだときに返されるオブジェクトの オブジェクト型。

このモジュールには C API もあります。詳しくはこのモジュールのソースを参照してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.6 StringIO Up: 4. 文字列処理 Next: 4.8 textwrap


4.8 textwrap -- テキストの折り返しと詰め込み

バージョン2.3 以降で新規追加された 仕様です。

textwrapモジュールでは、二つの簡易関数wrap()と fill()、そして作業のすべてを行うクラスTextWrapper とユーティリティ関数 dedent() を提供しています。 単に一つや二つのテキスト文字列の折り返しまたは詰め込みを行っている ならば、簡易関数で十分間に合います。そうでなければ、 効率のためにTextWrapperのインスタンスを使った方が良いでしょう。

wrap( text[, width[, ...]])
text(文字列)内の段落を一つだけ折り返しを行います。したがって、すべての行が高々width文字の長さになります。最後に改行が付かない出力行のリストを返します。

オプションのキーワード引数は、以下で説明するTextWrapperのインスタンス属性に対応しています。widthはデフォルトで70です。

fill( text[, width[, ...]])
text内の段落を一つだけ折り返しを行い、折り返しが行われた段落を含む一つの文字列を返します。fill()は
"\n".join(wrap(text, ...))
の省略表現です。

特に、fill()はwrap()とまったく同じ名前のキーワード引数を受け取ります。

wrap()とfill()の両方ともがTextWrapperインスタンスを作成し、その一つのメソッドを呼び出すことで機能します。そのインスタンスは再利用されません。したがって、たくさんのテキスト文字列を折り返し/詰め込みを行うアプリケーションのためには、あなた自身のTextWrapperオブジェクトを作成することでさらに効率が良くなるでしょう。

追加のユーティリティ関数である dedent() は、不要な 空白をテキストの左側に持つ文字列からインデントを取り去ります。

dedent( text)
text の各行に対し、左側から一様に取り去ることができるような空白 を除去します。

この関数は通常、三重引用符で囲われた文字列をスクリーン/その他の 左端にそろえ、なおかつソースコード中でのインデントされた形式を 損なわないようにするために使われます。

以下に例を示します:

def test():
    # end first line with \ to avoid the empty line!
    s = '''\
    hello
      world
    '''
    print repr(s)          # prints '    hello\n      world\n    '
    print repr(dedent(s))  # prints 'hello\n  world\n'

class TextWrapper( ...)
TextWrapperコンストラクタはたくさんのオプションのキーワード引数を受け取ります。それぞれの引数は一つのインスタンス属性に対応します。したがって、例えば、
wrapper = TextWrapper(initial_indent="* ")
は
wrapper = TextWrapper()
wrapper.initial_indent = "* "
と同じです。

あなたは同じTextWrapperオブジェクトを何回も再利用できます。また、使用中にインスタンス属性へ代入することでそのオプションのどれでも変更できます。

TextWrapperインスタンス属性(とコンストラクタのキーワード引数)は以下の通りです:

width
(デフォルト: 70) 折り返しが行われる行の最大の長さ。入力行にwidthより長い単一の語が無い限り、TextWrapperはwidth文字より長い出力行が無いことを保証します。

expand_tabs
(デフォルト: True) もし真ならば、そのときはtext内のすべてのタブ文字はtextのexpand_tabs()メソッドを用いて空白に展開されます。

replace_whitespace
(デフォルト: True) もし真ならば、タブ展開の後に残る(string.whitespaceに定義された)空白文字のそれぞれが一つの空白と置き換えられます。注意: expand_tabsが偽でreplace_whitespaceが真ならば、各タブ文字は一つの空白に置き換えられます。それはタブ展開と同じではありません。

initial_indent
(デフォルト: '') 折り返しが行われる出力の一行目の先頭に付けられる文字列。一行目の折り返しの長さになるまで含められます。

subsequent_indent
(デフォルト: '') 一行目以外の折り返しが行われる出力のすべての行の先頭に付けられる文字列。一行目以外の各行が折り返しの長さまで含められます。

fix_sentence_endings
(デフォルト: False) もし真ならば、TextWrapperは文の終わりを見つけようとし、確実に文がちょうど二つの空白で常に区切られているようにします。これは一般的に固定スペースフォントのテキストに対して望ましいです。しかし、文の検出アルゴリズムは完全ではありません: 文の終わりには、後ろに空白がある"."、"!"または"?"の中の一つ、ことによると"""あるいは"'"が付随する小文字があると仮定しています。これに伴う一つの問題は

[...] Dr. Frankenstein's monster [...]

の``Dr.''と

[...] See Spot. See Spot run [...]

の``Spot.''の間の差異を検出できないアルゴリズムです。

fix_sentence_endingsはデフォルトで偽です。

文検出アルゴリズムは``小文字''の定義のためにstring.lowercaseに依存し、同一行の文を区切るためにピリオドの後に二つの空白を使う慣習に依存しているため、英文テキストに限定されたものです。

break_long_words
(デフォルト: True) もし真ならば、そのときwidthより長い行が確実にないようにするために、widthより長い語は切られます。偽ならば、長い語は切られないでしょう。そして、widthより長い行があるかもしれません。(widthを超える分を最小にするために、長い語は単独で一行に置かれるでしょう。)

TextWrapperはモジュールレベルの簡易関数に類似した二つの公開メソッドも提供します:

wrap( text)
text(文字列)内の段落を一つだけ折り返しを行います。したがって、すべての行は高々width文字です。すべてのラッピングオプションはTextWrapperインスタンスのインスタンス属性から取られています。最後に改行の無い出力された行のリストを返します。

fill( text)
text内の段落を一つだけ折り返しを行い、折り返しが行われた段落を含む一つの文字列を返します。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.7 cStringIO Up: 4. 文字列処理 Next: 4.9 codecs


4.9 codecs -- codec レジストリと基底クラス

このモジュールでは、標準のPython codec（エンコーダとデコーダ）の基底クラスを定義し、 codec およびエラー処理の検索手順を管理している、 内部的な Python codec レジストリ に対するアクセス手段を提供しています。

codecs では以下の関数を定義しています:

register( search_function)
codec 検索関数を登録します。検索関数は第 1 引数にアルファベットの小文字 から成るエンコーディング名を取り、関数のタプル (encoder, decoder, stream_reader,stream_writer) を返すことに なっています。戻り値の関数が取る引数は以下の通りです。

encoder と decoder: これらは、Codec インスタンスの encode()とdecode() (Codec Interface 参照) と同じインターフェイスを 持つ関数、またはメソッドでなければなりません。 これらの関数・メソッドは状態なし (stateless) モードで動作しなければなりません。

stream_reader と stream_writer: これらは次のようなインター フェイスを持つファクトリ関数でなければなりません。

factory(stream, errors='strict')

これらのファクトリ関数は、それぞれの基底クラスである StreamWriter と StreamReader で定義されているインターフェイスを 提供するオブジェクトを返さなければいけません。ストリーム codecs は状態を保持することができます。

errors が取り得る値は、'strict' (エンコーディングエラーの際に例外を発生)、 'replace' (奇形データを "?"等の適切な文字で置換)、 'ignore' (奇形データを無視し何も通知せずに処理を継続)、 'xmlcharrefreplace'' (適切な XML 文字参照で置換 (エンコーディングのみ))、 および 'backslashreplace' (バックスラッシュによるエスケープシーケンス (エンコーディングのみ)) と、register_error() で定義されたその他の エラーハンドル名になります。

検索関数が与えられたエンコーディングを見つけられなかった場合には、 Noneを返すべきです。

lookup( encoding)
Python codec レジストリから codec タプルを探し、上の項目で定義された関数 のタプルを返します。

最初に、レジストリのキャッシュから encoding を探します。見つからなければ、 登録されている検索関数のリストから探します。見つからなければ、 LookupError が発生し、見つかれば codec のタプルがキャッシュ に保存され、それを呼び出し側に返します。

さまざまな codec へのアクセスを簡便化するために、このモジュールは次に挙 げるような関数を提供します。これらは codec の検索に lookup() を使います。

getencoder( encoding)
encoding で指定された codec を検索し、エンコーダ関数を返します。

encoding が見つからなければ LookupError が発生します。

getdecoder( encoding)
encoding で指定された codec を検索し、デコーダ関数を返します。

encoding が見つからなければ LookupError が発生します。

getreader( encoding)
encoding で指定された codec を検索し、StreamReader クラス、またはファク トリ関数を返します。

encoding が見つからなければ LookupError が発生します。

getwriter( encoding)
encoding で指定された codec を検索し、StreamWriter クラス、またはファク トリ関数を返します。

encoding が見つからなければ LookupError が発生します。

register_error( name, error_handler)
エラー処理関数 error_handler を名前 name で登録します。 エンコード中およびデコード中にエラーが発生した場合、 name が errors パラメタとして指定されていれば error_handler が呼び出されます。

error_handler はエラーの場所に関する情報の入った UnicodeEncodeError インスタンスとともに呼び出されます。 エラー処理関数はこの例外を送出するか、別の例外を送出するか、または 入力のエンコードができなかった部分の代替文字列、およびどこからエンコードを 再開するかを指定するタプルを返さなければなりません。 エンコーダは代替文字列をエンコードし、元の入力の指定された場所から エンコードを再開します。負の位置は入力文字列の末端からの相対位置と して扱われます。返された位置が境界の外側にある場合には IndexError が送出されます。

デコードと翻訳は同様に働きますが、UnicodeDecodeError または UnicodeTranslateError がハンドラに渡される点が 異なります。また、エラーハンドラから得られた置換文字列が出力に直接 置かれる点も異なります。

lookup_error( name)
既に、名前name 以下に登録されているエラー処理関数を返します。

エラー処理関数が見つからなければ LookupError が発生します。

strict_errors( exception)
strict エラー処理を実装しています。

replace_errors( exception)
replace エラー処理を実装しています。

ignore_errors( exception)
ignore エラー処理を実装しています。

xmlcharrefreplace_errors_errors( exception)
xmlcharrefreplace エラー処理を実装しています。

backslashreplace_errors_errors( exception)
backslashreplace エラー処理を実装しています。

エンコードされたファイルやストリームの処理を簡便化するため、, このモジュ ールは次のようなユーティリティ関数を定義しています。

open( filename, mode[, encoding[, errors[, buffering]]])
指定された mode でエンコードされたファイルを開き、 透過なエンコード・デ コードを提供するような、ラップされた版のファイルオブジェクトを返します。

注意: ラップされた版は、その codec で定義されたフォーマットのオブジェク トのみ受け付けます。多くの組み込み codec において Unicode オブジェクト です。出力も codec に依存し、通常は Unicode オブジェクトです。

encoding は、ファイルに使われるエンコーディングを指定します。

errors を指定して、エラー処理を定義することもできます。デフォルト では 'strict' で、エンコード時にエラーがあれば ValueError が発生します。

buffering は、組み込み関数 open() と同じです。デフォル トでは、ラインバッファです。

EncodedFile( file, input[, output[, errors]])
ラップされた版のファイルオブジェクトを返し、このオブジェクトは透過なエン コード変換を提供します。

ラップされたファイルに書かれた文字列は、与えられた input エンコー ディングに従って変換され、output エンコーディングを使ってファイル に文字列として書き込まれます。中間エンコーディングは、通常 Unicode ですが、指 定された codecs に依存します。

output が与えられなければ、input がデフォルトになります。

errors を与えて、エラー処理を定義することもできます。デフォルト では 'strict' で、エンコード時にエラーがあれば ValueError が発生します。

このモジュールは以下のような定数を定義します。プラットフォーム依存なファ イルを読み書きするのに役立ちます。

BOM
BOM_BE
BOM_LE
BOM_UTF8
BOM_UTF16
BOM_UTF16_BE
BOM_UTF16_LE
BOM_UTF32
BOM_UTF32_BE
BOM_UTF32_LE
ここで定義された定数は、様々なエンコーディングの Unicode の バイト・オー ダー・マーク (BOM) で、UTF-16 と UTF-32 におけるデータストリームやファイ ルストリームのバイトオーダーを指定したり、UTF-8 におけるUnicode signature として使われます。BOM_UTF16 は BOM_UTF16_BE と BOM_UTF16_LE のいずれかで、プラッ トフォームのネイティブ・バイトオーダーに依存します。BOM は BOM_UTF16のエイリアスです。同様に BOM_LEは BOM_UTF16_LEの、BOM_BE は BOM_UTF16_BE のエイリアスです。他は UTF-8 と UTF-32 エンコーディングの BOM を表します。

参考資料:

http://sourceforge.net/projects/python-codecs/
Python で使う、 アジア文字用の codec のサポートに取り組む SourceForge のプロジェクト。 この文書の執筆時点では開発の初期段階です。 -- ダウンロード可能なファイ ルについては、プロジェクトの FTP エリア を見てください。

  • 4.9.1 Codec 基底クラス
    • 4.9.1.1 Codec オブジェクト
    • 4.9.1.2 StreamWriter オブジェクト
    • 4.9.1.3 StreamReader オブジェクト
    • 4.9.1.4 StreamReaderWriter オブジェクト
    • 4.9.1.5 StreamRecoder オブジェクト
  • 4.9.2 標準エンコーディング
  • 4.9.3 encodings.idna -- アプリケーションにおける国際化ドメイン名 (IDNA)
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.8 textwrap Up: 4. 文字列処理 Next: 4.9.1 Codec 基底クラス


4.9.1 Codec 基底クラス

codecs は、インターフェイスを定義し、自前の Python 用 codec を、簡単に書くのに使える基底クラス群を定義してあります。

各 codec は、Python の codec として使えるように、4つのインターフェイスを 定義しなければなりません。状態なしエンコーダ、状態なしデコーダ、ストリー ムリーダ、ストリームライタです。ストリームリーダとライタは、通常、状態な しエンコーダとデコーダを再利用して、ファイル・プロトコルを実装します。

Codec クラスは、状態なしエンコーダ・デコーダのインターフェイスを 定義します。

エラー処理を簡便化し、安定させるために、encode() メソッドと decode() メソッドは、errors 文字列引数を提供することで、 異なるエラー処理の仕組みを実装してもかまいません。以下の文字列は全ての標 準 Python codec で定義および実装されています。

Value | Meaning
'strict' | UnicodeError (または、そのサブクラス)を 発生 - これがデフォルト。
'ignore' | その文字を無視し、次の文字から変換を再開
'replace' | 適当な文字で置換 - Python の組み込み Unicode codec のデコード時には公 式の U+FFFD REPLACEMENT CHARACTER を、エンコード時 には '?' を使う
'xmlcharrefreplace' | 適切な XML 文字参照で置換(エンコードのみ)
'backslashreplace' | バックスラッシュつきのエスケープシーケンス で置換(エンコードのみ)

受け付ける値は、register_error を使って追加できます。

  • 4.9.1.1 Codec オブジェクト
  • 4.9.1.2 StreamWriter オブジェクト
  • 4.9.1.3 StreamReader オブジェクト
  • 4.9.1.4 StreamReaderWriter オブジェクト
  • 4.9.1.5 StreamRecoder オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.9 codecs Up: 4.9 codecs Next: 4.9.1.1 Codec オブジェクト


4.9.2 標準エンコーディング

Python には数多くの codec が組み込みで付属します。これらは C 言語の 関数、対応付けを行うテーブルの両方で提供されています。以下のテーブル では codec と、いくつかの良く知られている別名と、エンコーディング が使われる言語を列挙します。別名のリスト、言語のリストともしらみつぶしに 網羅されているわけではありません。大文字と小文字、またはアンダースコア の代りにハイフンにしただけの綴りも有効な別名です。

多くの文字セットは同じ言語をサポートしています。これらの文字セットは 個々の文字 (例えば、EURO SIGN がサポートされているかどうか) や、 文字のコード部分への割り付けが異なります。特に欧州言語では、 典型的に以下の変種が存在します:

  • ISO 8859 コードセット
  • Microsoft Windows コードページで、8859 コード形式から導出されて いるが、制御文字を追加のグラフィック文字と置き換えたもの
  • IBM EBCDIC コードページ
  • ASCII 互換の IBM PC コードページ

Codec | 別名 | 言語
ascii | 646, us-ascii | イギリス
cp037 | IBM037, IBM039 | イギリス
cp424 | EBCDIC-CP-HE, IBM424 | ヘブライ
cp437 | 437, IBM437 | イギリス
cp500 | EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500 | 西ヨーロッパ
cp737 |  | ギリシャ
cp775 | IBM775 | バルト沿岸国
cp850 | 850, IBM850 | 西ヨーロッパ
cp852 | 852, IBM852 | 中央および東ヨーロッパ
cp855 | 855, IBM855 | ブルガリア、ベラルーシ、マケドニア、ロシア、セルビア
cp856 |  | ヘブライ
cp857 | 857, IBM857 | トルコ
cp860 | 860, IBM860 | ポルトガル
cp861 | 861, CP-IS, IBM861 | アイスランド
cp862 | 862, IBM862 | ヘブライ
cp863 | 863, IBM863 | カナダ
cp864 | IBM864 | アラビア
cp865 | 865, IBM865 | デンマーク、ノルウェー
cp869 | 869, CP-GR, IBM869 | ギリシャ
cp874 |  | タイ
cp875 |  | ギリシャ
cp1006 |  | Urdu
cp1026 | ibm1026 | トルコ
cp1140 | ibm1140 | 西ヨーロッパ
cp1250 | windows-1250 | 中央および東ヨーロッパ
cp1251 | windows-1251 | ブルガリア、ベラルーシ、マケドニア、ロシア、セルビア
cp1252 | windows-1252 | 西ヨーロッパ
cp1253 | windows-1253 | ギリシャ
cp1254 | windows-1254 | トルコ
cp1255 | windows-1255 | ヘブライ
cp1256 | windows1256 | アラビア
cp1257 | windows-1257 | バルト沿岸国
cp1258 | windows-1258 | ベトナム
latin_1 | iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1 | 西ヨーロッパ
iso8859_2 | iso-8859-2, latin2, L2 | 中央および東ヨーロッパ
iso8859_3 | iso-8859-3, latin3, L3 | エスペラント、マルタ
iso8859_4 | iso-8859-4, latin4, L4 | バルト沿岸国
iso8859_5 | iso-8859-5, cyrillic | ブルガリア、ベラルーシ、マケドニア、ロシア、セルビア
iso8859_6 | iso-8859-6, arabic | アラビア
iso8859_7 | iso-8859-7, greek, greek8 | ギリシャ
iso8859_8 | iso-8859-8, hebrew | ヘブライ
iso8859_9 | iso-8859-9, latin5, L5 | トルコ
iso8859_10 | iso-8859-10, latin6, L6 | 北欧
iso8859_13 | iso-8859-13 | バルト沿岸国
iso8859_14 | iso-8859-14, latin8, L8 | ケルト
iso8859_15 | iso-8859-15 | 西ヨーロッパ
koi8_r |  | ロシア
koi8_u |  | ウクライナ
mac_cyrillic | maccyrillic | ブルガリア、ベラルーシ、マケドニア、ロシア、セルビア
mac_greek | macgreek | ギリシャ
mac_iceland | maciceland | アイスランド
mac_latin2 | maclatin2, maccentraleurope | 中央および東ヨーロッパ
mac_roman | macroman | 西ヨーロッパ
mac_turkish | macturkish | トルコ
utf_16 | U16, utf16 | 全ての言語
utf_16_be | UTF-16BE | 全ての言語 (BMP only)
utf_16_le | UTF-16LE | 全ての言語 (BMP only)
utf_7 | U7 | 全ての言語
utf_8 | U8, UTF, utf8 | 全ての言語

数多くの codec は Python 特有なので、それらの codec 名は Python の外では無意味なものとなります。これらの codec のいくつかは Unicode 文字列からバイト文字列への変換を行わず、むしろ単一の 引数をもつ全写像関数はエンコーディングとみなすことができるという Python codec の性質を利用しています。

以下に列挙した codec では、``エンコード'' 方向の結果は常にバイト文字列 方向です。``デコード'' 方向の結果はテーブル内の被演算子型として列挙 されています。

Codec | 別名 | 被演算子の型 | 目的
base64_codec | base64, base-64 | byte string | 被演算子を MIME base64 に変換します
hex_codec | hex | byte string | 被演算子をバイトあたり 2 桁の 16 進数の表現に変換します
idna |  | Unicode string | RFC 3490 を実装しています。 バージョン2.3 以降で新規追加された 仕様です。 encodings.idna も参照してください
mbcs | dbcs | Unicode string | Windows のみ: 被演算子を ANSI コードページ (CP_ACP) に従ってエンコードします
palmos |  | Unicode string | PalmOS 3.5 のエンコーディングです
punycode |  | Unicode string | RFC 3492 を実装しています。 バージョン2.3 以降で新規追加された 仕様です。
quopri_codec | quopri, quoted-printable, quotedprintable | byte string | 被演算子を MIME quoted printable 形式に変換します
raw_unicode_escape |  | Unicode string | Python ソースコードにおける raw Unicode リテラルとして 適切な文字列を生成します。
rot_13 | rot13 | byte string | 被演算子のシーザー暗号 (Caesar-cypher) を返します
string_escape |  | byte string | Python ソースコードにおける文字列リテラルとして適切な 文字列を生成します。
undefined |  | any | 全ての変換に対して例外を送出します。 バイト列と Unicode 文字列との間で自動的な型強制をおこないたくない 時にシステムエンコーディングとして使うことができます。
unicode_escape |  | Unicode string | Python ソースコードにおける Unicode リテラルとして適切な 文字列を生成します。
unicode_internal |  | Unicode string | 被演算子の内部表現を返します。
uu_codec | uu | byte string | 被演算子を uuencode を用いて変換します。
zlib_codec | zip, zlib | byte string | 被演算子を gzip を用いて圧縮します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.9.1.5 StreamRecoder オブジェクト Up: 4.9 codecs Next: 4.9.3 encodings.idna


4.9.3 encodings.idna -- アプリケーションにおける国際化ドメイン名 (IDNA)

バージョン2.3 以降で新規追加された 仕様です。

このモジュールでは RFC 3490 (アプリケーションにおける国際化 ドメイン名, IDNA: Internationalized Domain Names in Applications) および RFC 3492 (Nameprep: 国際化ドメイン名 (IDN) の ための stringprep プロファイル) を実装しています。 このモジュールは punycode エンコーディングおよび stringprep の上に構築されています。

これらの RFC はともに、ドメイン名における非 ASCII 文字をサポートする ためのプロトコルを定義しています。 (``www.Alliancefrançaise.nu'' のような) 非 ASCII 文字を含む ドメイン名は ASCIIと互換性のあるエンコーディング (ACE、 ``www.xn-alliancefranaise-npb.nu'' のような形式) に変換されます。 ドメイン名の ACE 形式は、DNS クエリ、HTTP Host: フィールド などといった、プロトコルが任意の文字を使うことができない 全ての場所で用いられます。 この変換はアプリケーション内で行われます; 可能ならユーザからは 不可視となります: アプリケーションは Unicode ドメインラベルを ワイヤ上に載せる際に IDNA に、 ACE ドメインラベルを ユーザに提供する前に Unicode に、それぞれ透過的に変換しなければ なりません。

Python ではこの変換をいくつかの方法でサポートします: idna codec は Unicode と ACE 間の変換を行います。さらに、 socket モジュールは Unicode ホスト名を ACE に透過的に 変換するため、アプリケーションはホスト名を socket モジュールに渡す際にホスト名の変換に煩わされることがありません。 その上で、ホスト名を関数パラメタとして持つ、httplib や ftplib のようなモジュールでは Unicode ホスト名を 受理します (httplib でもまた、Host: フィールドにある IDNA ホスト名を、フィールド全体を送信する場合に透過的に送信 します)。

(逆引きなどによって) ワイヤ越しにホスト名を受信する際、Unicode への自動変換は行われません: こうしたホスト名をユーザに提供 したいアプリケーションでは、Unicode にデコードしてやる必要が あります。

encodings.idna ではまた、nameprep 手続きを実装しています。 nameprep はホスト名に対してある正規化を行って、国際化ドメイン名の 大小文字非区別を達成するとともに、類似の文字を一元化します。 nameprep 関数は必要なら直接使うこともできます。

nameprep( label)
label を nameprep したバージョンを返します。現在の実装では クエリ文字列を仮定しているので、 AllowUnassigned は真です。 true.

ToASCII( label)
RFC 3490 で指定されているようにして、ラベルを ASCIIに変換します。 UseSTD3ASCIIRules は偽であると仮定します。

ToUnicode( label)
RFC 3490 で指定されているようにして、ラベルを Unicode に変換します。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.9.2 標準エンコーディング Up: 4.9 codecs Next: 4.10 unicodedata


4.10 unicodedata -- Unicode データベース

このモジュールは、全ての Unicode 文字の属性を定義している Unicode 文字データベースへのアクセスを提供します。このデータベース内のデータは、ftp://ftp.unicode.org/ で公開されている UnicodeData.txt ファイルのバージョン 3.2.0 に基づいています。

このモジュールは、UnicodeData ファイルフォーマット 3.2.0 （http://www.unicode.org/Public/UNIDATA/UnicodeData.html を参照）で定義されているものと、同じ名前と記号を使います。このモジュールで定義されている関数は、以下のとおりです。

lookup( name)
名前に対応する文字を探します。その名前の文字が見つ かった場合、 その Unicode 文字が返されます。見つからなかった場合には、KeyError を発生させます。

name( unichr[, default])
Unicode 文字 unichr に付いている名前を、文字列で返します。名前が定義されていない場合には default が返されますが、この引数が与えられていなければ ValueError を発生させます。

decimal( unichr[, default])
Unicode 文字 unichr に割り当てられている十進数を、整数で返します。この値が定義されていない場合には default が返されますが、この引数が与えられていなければ ValueError を発生させます。

digit( unichr[, default])
Unicode 文字 unichr に割り当てられている二進数を、整数で返します。この値が定義されていない場合には default が返されますが、この引数が与えられていなければ ValueError を発生させます。

numeric( unichr[, default])
Unicode 文字 unichr に割り当てられている数値を、float 型で返します。 この値が定義されていない場合には default が返されますが、この引 数が与えられていなければ ValueError を発生させます。

category( unichr)
Unicode 文字 unichr に割り当てられた、汎用カテゴリを返します。

bidirectional( unichr)
Unicode 文字 unichr に割り当てられた、双方向カテゴリを返します。そのような値が定義されていない場合、空の文字列が返されます。

combining( unichr)
Unicode 文字 unichr に割り当てられた正規結合クラスを返します。結合クラス定義されていない場合、0 が返されます。

mirrored( unichr)
Unicode 文字 unichr に割り当てられた、鏡像化のプロパティを返します。 その文字が双方向テキスト内で鏡像化された文字である場合には 1 を、それ以外の場合には 0 を返します。

decomposition( unichr)
Unicode 文字 unichr に割り当てられた、文字分解マッピングを、文字列型で返します。そのようなマッピングが定義されていない場合、空の文字列が返されます。

normalize( form, unistr)

Unicode 文字列 unistr の正規形 form を返します。 form の有効な値は、'NFC'、'NFKC'、'NFD'、'NFKD' です。

Unicode 規格は標準等価性 (canonical equivalence) と 互換等価性 (compatibility equivalence) に基づいて、様々な Unicode文字列の正規形を定義します。Unicode では、複数の方法で表現できる文字があります。たとえば、文字 U+00C7 (LATIN CAPITAL LETTER C WITH CEDILLA) は、U+0043 (LATIN CAPITAL LETTER C) U+0327 (COMBINING CEDILLA) というシーケンスとしても表現できます。

各文字には、2つの正規形があり、それぞれ 正規形 C と 正規形 D といいます。正規形 D (NFD) は標準分解 (canonical decomposition) としても知られており、各文字を分解された形に変換します。正規形 C (NFC) は標準分解を適用した後、結合済文字を再構成します。

互換等価性に基づいて、2つの正規形が加えられています。Unicode では、一般に他の文字との統合がサポートされている文字があります。たとえば、U+2160 (ROMAN NUMERAL ONE) は事実上 U+0049 (LATIN CAPITAL LETTER I) と同じものです。しかし、Unicode では、既存の文字集合 (たとえば gb2312) との互換性のために、これがサポートされています。

正規形 KD (NFKD) は、互換分解 (compatibility decomposition) を適用します。すなわち、すべての互換文字を、等価な文字で置換します。 正規形 KC (NFKC) は、互換分解を適用してから、標準分解を適用します。

バージョン2.3 以降で新規追加された 仕様です。

更に、本モジュールは以下の定数を公開します。

unidata_version
このモジュールで使われている Unicode データベースのバージョン。

バージョン2.3 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.9.3 encodings.idna Up: 4. 文字列処理 Next: 4.11 stringprep


4.11 stringprep -- インターネットのための文字列調製

(ホスト名のような) インターネット上にある存在に識別名をつける際、 しばしば識別名間の ``等価性'' 比較を行う必要があります。 厳密には、例えば大小文字の区別をするかしないかいったように、 比較をどのように行うかはアプリケーションの領域に依存します。 また、例えば ``印字可能な'' 文字で構成された識別名だけを許可すると いったように、可能な識別名を制限することも必要となるかもしれません。

RFC 3454 では、インターネットプロトコル上で Unicode 文字列を ``調製 (prepare)'' するためのプロシジャを定義しています。文字列は 通信路に載せられる前に調製プロシジャで処理され、その結果ある正規化 された形式になります。RFC ではあるテーブルの集合を定義しており、 それらはプロファイルにまとめられています。各プロファイルでは、どの テーブルを使い、stringprep プロシジャのどのオプション部分が プロファイルの一部になっているかを定義しています。 stringprep プロファイルの一つの例は nameprep で、 国際化されたドメイン名に使われます。

stringprep は RFC 3453 のテーブルを公開しているに 過ぎません。これらのテーブルは辞書やリストとして表　現するには バリエーションが大きすぎるので、このモジュールでは Unicode 文字データベースを内部的に利用しています。モジュールソースコード 自体は mkstringprep.py ユーティリティを使って生成されました。

その結果、これらのテーブルはデータ構造体ではなく、関数として 公開されています。RFC には 2 種類のテーブル: 集合およびマップ、 が存在します。集合については、stringprep は ``特性関数 (characteristic function)'' 、すなわち引数が 集合の一部である場合に真を返す関数を提供します。マップに対しては、 マップ関数: キーが与えられると、それに関連付けられた値を返す関数、 を提供します。以下はこのモジュールで利用可能な全ての関数を列挙した ものです。

in_table_a1( code)
code がテーブル A.1 (Unicode 3.2 における未割り当てコード点: unassigned code point) かどうか判定します。

in_table_b1( code)
code がテーブル B.1 (一般には何にも対応付けられていない: commonly mapped to nothing) かどうか判定します。

map_table_b2( code)
テーブル B.2 (NFKC で用いられる大小文字の対応付け) に従って、 code に対応付けられた値を返します。

map_table_b3( code)
テーブル B.3 (正規化を伴わない大小文字の対応付け) に従って、 code に対応付けられた値を返します。

in_table_c11( code)
code がテーブル C.1.1 (ASCII スペース文字) かどうか判定します。

in_table_c12( code)
code がテーブル C.1.2 (非 ASCII スペース文字) かどうか判定します。

in_table_c11_c12( code)
code がテーブル C.1 (スペース文字、C.1.1 および C.1.2 の和集合) かどうか判定します。

in_table_c21( code)
code がテーブル C.2.1 (ASCII 制御文字) かどうか判定します。

in_table_c22( code)
code がテーブル C.2.2 (非 ASCII 制御文字) かどうか判定します。

in_table_c21_c22( code)
code がテーブル C.2 (制御文字、C.2.1 および C.2.2 の和集合) かどうか判定します。

in_table_c3( code)
code がテーブル C.3 (プライベート利用) かどうか判定します。

in_table_c4( code)
code がテーブル C.4 (非文字コード点: non-character code points) かどうか判定します。

in_table_c5( code)
code がテーブル C.5 (サロゲーションコード) かどうか判定します。

in_table_c6( code)
code がテーブル C.6 (平文:plain text として不適切) かどうか 判定します。

in_table_c7( code)
code がテーブル C.7 (標準表現:canonical representation として不適切) かどうか判定します。

in_table_c8( code)
code がテーブル C.8 (表示プロパティの変更または撤廃) か どうか判定します。

in_table_c9( code)
code がテーブル C.9 (タグ文字) かどうか判定します。

in_table_d1( code)
code がテーブル D.1 (双方向プロパティ ``R'' または ``AL'' を持つ文字) かどうか判定します。

in_table_d2( code)
code がテーブル D.2 (双方向プロパティ ``L'' を持つ文字) かどうか判定します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.10 unicodedata Up: 4. 文字列処理 Next: 5. 各種サービス


5. 各種サービス

この章では、Pythonのすべてのバージョンで利用可能な各種サービスについて説明します。 以下に概要を示します。

pydoc | ドキュメント生成とオンラインヘルプシステム
doctest | ドキュメンテーション文字列内の例を検証するためのフレームワーク。
unittest | 単体テストフレームワーク
test | Python用テストスイートを含む回帰テストパッケージ。
test.test_support | Python 回帰テストのサポート
math | 数学関数(sin() など)。
cmath | 複素数のための数学関数です。
random | よく知られている様々な分布をもつ擬似乱数を生成する。
whrandom | 浮動少数点数の擬似乱数生成器。
bisect | バイナリサーチ用の配列二分法アルゴリズム。
heapq | ヒープキュー (別名優先度キュー) アルゴリズム。
array | Efficient arrays of uniformly typed numeric values.
sets | ユニークな要素の集合の実装
itertools | 効率的なループ実行のためのイテレータ生成関数。
ConfigParser | Configuration file parser.
fileinput | Perlのような複数の入力ストリームをまたいだ行の繰り返し処理をサポートする (その場で保存する機能つき)。
xreadlines | ファイルの各行に対する効率のよい反復処理。
calendar | Unix の cal プログラム相当の機能を含んだカレン ダーに関する関数群
cmd | 行指向のコマンドインタープリタを構築
shlex | Unix シェル類似の言語に対する単純な字句解析。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.11 stringprep Up: Python ライブラリリファレンス Next: 5.1 pydoc


5.1 pydoc -- ドキュメント生成とオンラインヘルプシステム

バージョン2.1 以降で新規追加された 仕様です。

pydocモジュールは、Pythonモジュールから自動的にドキュメントを生成します。 生成されたドキュメントをテキスト形式でコンソールに表示したり、 Web browserにサーバとして提供したり、HTMLファイルとして保存したりできます。

組み込み関数のhelp()を使うことで、対話型のインタプリタから オンラインヘルプを起動することができます。コンソール用のテキスト形式の ドキュメントをつくるのにオンラインヘルプではpydocを使っています。 pydocをPythonインタプリタからはなく、オペレーティングシステムの コマンドプロンプトから起動した場合でも、同じテキスト形式のドキュメントを見ることができます。 例えば、以下をshellから実行すると

pydoc sys

sysモジュールのドキュメントを、Unix のmanコマンドの ような形式で表示させることができます。 pydocの引数として与えることができるのは、関数名・モジュール名・パッケージ名、 また、モジュールやパッケージ内のモジュールに含まれるクラス・メソッド・関数への ドット"."形式での参照です。 pydocへの引数がパスと解釈されるような場合で(オペレーティングシステムの パス区切り記号を含む場合です。例えばUnixならば "/"(スラッシュ)含む場合になります)、 さらに、そのパスがPythonのソースファイルを指しているなら、そのファイルに対する ドキュメントが生成されます。

引数の前に -wフラグを指定すると、コンソールにテキストを表示させる かわりにカレントディレクトリにHTMLドキュメントを生成します。

引数の前に -kフラグを指定すると、引数をキーワードとして 利用可能な全てのモジュールの概要を検索します。 検索のやりかたは、Unixのmanコマンドと同様です。 モジュールの概要というのは、モジュールのドキュメントの一行目のことです。

また、pydocを使うことでローカルマシンに Web browserから 閲覧可能なドキュメントを提供するHTTPサーバーを起動することもできます。 pydoc -p 1234とすると、HTTPサーバーをポート1234に起動します。 これで、お好きなWeb browserを使ってhttp://localhost:1234/から ドキュメントを見ることができます。

pydocでドキュメントを生成する場合、その時点での環境とパス情報に基づいて モジュールがどこにあるのか決定されます。 そのため、pydoc spamを実行した場合につくられる ドキュメントは、Pythonインタプリタを起動して"import spam"と入力したときに 読み込まれるモジュールに対するドキュメントになります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5. 各種サービス Up: 5. 各種サービス Next: 5.2 doctest


5.2 doctest -- ドキュメンテーション文字列に本当のことが書かれているか調べる

doctest モジュールは、モジュールのドキュメンテーション文字列 (docstring) から、対話的 Python セッションのように見えるテキストを探しだし、これらのセッションを実際に実行して、そこに書かれている通りに動作するか検証します。以下に小さな、しかし完全な例を示します:

"""
This is module example.

Example supplies one function, factorial.  For example,

>>> factorial(5)
120
"""

def factorial(n):
    """Return the factorial of n, an exact integer >= 0.

    If the result is small enough to fit in an int, return an int.
    Else return a long.

    >>> [factorial(n) for n in range(6)]
    [1, 1, 2, 6, 24, 120]
    >>> [factorial(long(n)) for n in range(6)]
    [1, 1, 2, 6, 24, 120]
    >>> factorial(30)
    265252859812191058636308480000000L
    >>> factorial(30L)
    265252859812191058636308480000000L
    >>> factorial(-1)
    Traceback (most recent call last):
        ...
    ValueError: n must be >= 0

    Factorials of floats are OK, but the float must be an exact integer:
    >>> factorial(30.1)
    Traceback (most recent call last):
        ...
    ValueError: n must be exact integer
    >>> factorial(30.0)
    265252859812191058636308480000000L

    It must also not be ridiculously large:
    >>> factorial(1e100)
    Traceback (most recent call last):
        ...
    OverflowError: n too large
    """

    import math
    if not n >= 0:
        raise ValueError("n must be >= 0")
    if math.floor(n) != n:
        raise ValueError("n must be exact integer")
    if n+1 == n:  # catch a value like 1e300
        raise OverflowError("n too large")
    result = 1
    factor = 2
    while factor <= n:
        try:
            result *= factor
        except OverflowError:
            result *= long(factor)
        factor += 1
    return result

def _test():
    import doctest, example
    return doctest.testmod(example)

if __name__ == "__main__":
    _test()

example.py をコマンドラインから直接実行すると、 doctest はその魔法を働かせます:

$ python example.py
$

出力は何もありません！ しかしこれが正常で、全ての例が正しく動作する ことを意味しています。 スクリプトに -v を与えると、doctest は何を行おうとしているのかを記録した詳細なログを出力し、 最後にまとめを出力します:

$ python example.py -v
Running example.__doc__
Trying: factorial(5)
Expecting: 120
ok
0 of 1 examples failed in example.__doc__
Running example.factorial.__doc__
Trying: [factorial(n) for n in range(6)]
Expecting: [1, 1, 2, 6, 24, 120]
ok
Trying: [factorial(long(n)) for n in range(6)]
Expecting: [1, 1, 2, 6, 24, 120]
ok
Trying: factorial(30)
Expecting: 265252859812191058636308480000000L
ok

And so on, eventually ending with:

Trying: factorial(1e100)
Expecting:
Traceback (most recent call last):
    ...
OverflowError: n too large
ok
0 of 8 examples failed in example.factorial.__doc__
2 items passed all tests:
   1 tests in example
   8 tests in example.factorial
9 tests in 2 items.
9 passed and 0 failed.
Test passed.
$

これが、doctest を使って生産性の向上を目指す上で知っておく 必要があることの全てです！ さあやってみましょう。doctest.py 内のドキュメンテーション 文字列には doctest の全ての側面についての詳細な情報が入っており、 ここではより重要な点をカバーするだけにします。

  • 5.2.1 通常の利用法
  • 5.2.2 どのドキュメンテーション文字列が検証されるのか?
  • 5.2.3 実行コンテキストとは何か?
  • 5.2.4 例外については?
  • 5.2.5 進んだ使い方
  • 5.2.6 ドキュメンテーション文字列内の例をどうやって認識するのか?
  • 5.2.7 注意事項
  • 5.2.8 提言
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.1 pydoc Up: 5. 各種サービス Next: 5.2.1 通常の利用法


5.2.1 通常の利用法

通常の利用法では、各モジュール M の最後を、以下:

def _test():
    import doctest, M           # replace M with your module's name
    return doctest.testmod(M)   # ditto

if __name__ == "__main__":
    _test()

のようにして締めくくります。

もしテスト対象のモジュールがメインモジュールであるなら、 testmod() に M を指定する必要はありません; この場合、実行中のモジュールがテストされます。

次に、モジュールをスクリプトとして走らせ、ドキュメンテーション文字列 を実行して検証します:

python M.py

ドキュメンテーション文字列に書かれた例の実行が失敗しない限り、何も 表示されません。失敗すると、失敗した例と、その原因が (場合によっては複数) 標準出力に印字され、出力の最後の行が 'Test failed.' と なります。

一方、-v スイッチをつけて走らせると:

python M.py -v

実行を試みた全ての例について詳細に報告し、最後に各種まとめをおこなった 内容が標準出力に印字されます。

verbose=1 を testmod() に渡せば、 詳細報告 (verbose) モードを強制することができます。また、 verbose=0 とすれば禁止することができます。 どちらの場合にも、testmod() は sys.argv 上のスイッチ を調べません。

いずれの場合も、testmod() は整数 2 要素、 (f, t) からなるタプルを返し、f が失敗した ドキュメンテーション文字列内の例、t が実行を試みた例の総数となります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.2 doctest Up: 5.2 doctest Next: 5.2.2 どのドキュメンテーション文字列が検証されるのか?


5.2.2 どのドキュメンテーション文字列が検証されるのか?

全ての詳細は docstring.py のドキュメンテーション文字列を 参照してください。混乱させる ようなことはありません: モジュールのドキュメンテーション文字列、 全ての関数、クラスおよびメソッドのドキュメンテーション文字列が 検索されます。オプションとして、テスタはプライベートな名前を もつオブジェクトに添付されたドキュメンテーション文字列を除外 することができます。モジュールに import されたオブジェクトは 検索されません。

加えて、 M.__test__ が存在し、 "真の値を持つ" 場合、 この値は辞書で、辞書の各エントリは (文字列の) 名前を 関数オブジェクト、クラスオブジェクト、または文字列に対応付けて いなくてはなりません。M.__test__ から得られた関数および クラスオブジェクトのドキュメンテーション文字列は、その名前が プライベートなものでも検索され、文字列の場合にはそれが ドキュメンテーション文字列であるかのように直接検索を行います。 出力においては、M.__test__ におけるキー K は、

  <name of M>.__test__.K

のように表示されます。

検索中に見つかったクラスも同様に再帰的に検索が行われ、 クラスに含まれているメソッドおよびネストされたクラスについて ドキュメンテーション文字列のテストが行われます。 M 内のグローバル変数から到達したプライベートな名前は オプションでスキップされますが、M.__test__ から到達した 名前は全て検索されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.2.1 通常の利用法 Up: 5.2 doctest Next: 5.2.3 実行コンテキストとは何か?


5.2.3 実行コンテキストとは何か?

デフォルトでは、testmod がテストを行うべきドキュメン テーション文字列を見つけるたびに、M のグローバルを コピーして 使うため、モジュール上でテストを動作させても モジュールの実際のグローバル 変数を変更することはありません。このため、M 内でテストを 行った際に痕跡が残り (left behind crumbs)、偶発的に別のテストが 作動することはないはずです。すなわち、例では M 内の トップレベルで定義されたどんな名前も、ドキュメンテーション文字列 が動作する以前に定義された名前も自由に使うことができます。

testmod() に globs=your_dict を渡すことで、 自前の辞書を実行コンテキストとして使うこともできます。 おそらくこの値は M.__dict__ を他の import されたモジュール 由来のグローバル変数とマージしたものになるでしょう。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.2.2 どのドキュメンテーション文字列が検証されるのか? Up: 5.2 doctest Next: 5.2.4 例外については?


5.2.4 例外については?

例で生成される出力がトレースバックのみである限り問題ありません。 例えば:

>>> [1, 2, 3].remove(42)
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
ValueError: list.remove(x): x not in list
>>>

例外型と値だけが比較される (詳しくはトレースバックの最後の行だけ) が 比較されるので注意してください。途中の様々な ``File'' 行は (例の中のドキュメンテーション値に明示的に追加しない限り) 放っておかれます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.2.3 実行コンテキストとは何か? Up: 5.2 doctest Next: 5.2.5 進んだ使い方


5.2.5 進んだ使い方

doctest をどのように動作させるかを制御する、いくつかのモジュール レベルの関数が利用できます。

debug( module, name)
doctest を含む単一のドキュメンテーション文字列をデバッグします。

デバッグしたいドキュメンテーション文字列の入った module (またはドットで区切ったモジュール名) と、(モジュール内の) デバッグしたいドキュメンテーション文字列を持つオブジェクトの name を指定してください。

doctest の例が展開され (testsource() 関数を参照してください)、 一次ファイルに書き込まれます。次に Python デバッガ pdb がこのファイルに対して起動されます。 バージョン2.3 以降で新規追加された 仕様です。

testmod( )
この関数は doctest への基本的なインタフェース提供します。 この関数は Tester のローカルなインスタンスを生成し、 このクラスの適切なメソッドを動作させ、結果をグローバルな Tester インスタンスである master に統合します。

testmod() が提供するよりも細かい制御を行うには、 Tester のインスタンスを自作のポリシで作成するか、 master のメソッドを直接呼び出します。詳細は Tester.__doc__ を参照してください。

testsource( module, name)
doctest の例をドキュメンテーション文字列から展開します。

展開したいテストの入った module (またはドットで区切られた モジュールの名前) と、展開したいテストの入った docstring を 持つオブジェクトの (モジュール内の) name を与えます。

doctest 内の例は Python コードの入った文字列として返されます。 例中での予想される出力のブロックは Python のコメントに変換 されます。 バージョン2.3 以降で新規追加された 仕様です。

DocTestSuite( [module])
モジュールにおける doctest のテストプログラムを unittest.TestSuite に変換します。

返される TestSuite は unittest フレームワークで動作する ためのもので、モジュール内の各 doctest を走らせます。 doctest のいずれかが失敗すると、生成された unittest が失敗し、 該当するテストを含むファイルと (時に近似の) 行番号を表示する DocTestTestFailure 例外が送出されます。

オプションの module 引数はテストするモジュールを与えます。 この値はモジュールオブジェクトか (場合によってはドットで区切られた) モジュール名となります。指定されていなければ、この関数を呼び出している モジュールが使われます。

unittest モジュールが TestSuite を 利用する数多くの方法のうちの一つを使った例を以下に示します:

    import unittest
    import doctest
    import my_module_with_doctests

    suite = doctest.DocTestSuite(my_module_with_doctests)
    runner = unittest.TextTestRunner()
    runner.run(suite)

バージョン2.3 以降で新規追加された 仕様です。 警告: この関数は現在のところ M.__test__ を検索せず、 その検索テクニックはあらゆる点で testmod() と合致しません。 将来のバージョンではこれら二つを収斂させる予定です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.2.4 例外については? Up: 5.2 doctest Next: 5.2.6 ドキュメンテーション文字列内の例をどうやって認識するのか?


5.2.6 ドキュメンテーション文字列内の例をどうやって認識するのか?

ほとんどの場合、対話コンソールセッション上でのコピー／ペーストはうまく 動作します -- 先頭部の空白が厳密に一貫性があるようにしてください (きちんとやるのが面倒ならタブとスペースを混在させることはできますが、 doctest はあなたにとってのタブがどういう意味を持つのかを推測 するようなことはしません)。

>>> # comments are ignored
>>> x = 12
>>> x
12
>>> if x == 13:
...     print "yes"
... else:
...     print "no"
...     print "NO"
...     print "NO!!!"
...
no
NO
NO!!!
>>>

出力結果例 (expected output) は、コードを含む最後の '>>> ' or '... ' 行の直下に続きます。 また、出力結果例 (がある場合) は、次の '>>> ' 行か、全て空白文字の行まで続きます。

細目事項:

  • 出力結果例には、全て空白の行が入っていては なりません。そのような行は出力結果例の終了を表すと見なされるからです。

  • stdout への出力は取り込まれますが、stderr は取り込まれません (例外 発生時のトレースバックは別の方法で取り込まれます)。

  • 対話セッションにおいて、バックスラッシュを用いて次の行に続ける場合や、 その他の理由でバックスラッシュを用いる場合、ドキュメンテーション文字列内 ではバックスラッシュを二重にしておく必要があります。これは、単に例を 記述しているのが文字列内であり、バックスラッシュをそのままにしておく ためにはエスケープする必要があるからです。例えば以下のように:

    >>> if "yes" == \\
...     "y" +   \\
...     "es":
...     print 'yes'
yes

  • 開始カラムはどこでもかまいません:

      >>> assert "Easy!"
        >>> import math
            >>> math.floor(1.9)
            1.0
    出力結果例の先頭部にある空白文字列は、出力をトリガしている '>>> ' 行の先頭にある空白文字列と同じだけはぎとられます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.2.5 進んだ使い方 Up: 5.2 doctest Next: 5.2.7 注意事項


5.2.7 注意事項

  1. doctest は出力結果例が厳密に一致するように厳しく要求します。 1 文字でも一致しないと、テストは失敗します。このため、Python が出力に 関して何を保証していて、何を保証していないかを正確に知っていないと 幾度か混乱させられることでしょう。 例えば、辞書を出力する際、Python はキーと値のペアが常に特定の順番で 並ぶよう保証してはいません。従って、以下のようなテスト

    >>> foo()
{"Hermione": "hippogryph", "Harry": "broomstick"}
>>>

    は脆弱です! 回避法としては、

    >>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}
True
>>>

    としてください。別のやり方としては、

    >>> d = foo().items()
>>> d.sort()
>>> d
[('Harry', 'broomstick'), ('Hermione', 'hippogryph')]

    のようにします。

    他のやり方もありますが、自分で考えてみてください。

    もう一つのよくない発想は、

    >>> id(1.0) # certain to fail some of the time
7948648
>>>

    のようなオブジェクトアドレスの埋め込みです。

    Python は浮動小数点の書式化をプラットフォームの C ライブラリにゆだねて おり、C ライブラリはこの点においてプラットフォーム間で非常に違いが大きい ので、浮動小数点数もまたプラットフォーム間での微妙な出力の違いの原因となり ます。

    >>> 1./7  # risky
0.14285714285714285
>>> print 1./7 # safer
0.142857142857
>>> print round(1./7, 6) # much safer
0.142857

    I/2.**J の形式になる数値は全てのプラットフォームで 安全であり、私はしばしば doctest の例にはその形式の数値を 使っています:

    >>> 3./4  # utterly safe
0.75

    単純な分数は人が理解し易いこともあり、よりよいドキュメント記述に なります。

  2. 一度だけしか実行してはならないコードには気をつけてください。

    一度だけしか実行してはならないようなモジュールレベルのコードが あるなら、_test() のフールプルーフ性の高い定義は

    def _test():
    import doctest, sys
    doctest.testmod()

    のようになります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.2.6 ドキュメンテーション文字列内の例をどうやって認識するのか? Up: 5.2 doctest Next: 5.2.8 提言


5.2.8 提言

doctst の最初の言葉が "doc" になっていますが、この言葉、すなわち ドキュメントを最新に保つこと: こそが、作者が doctest を書いた理由です。 たまたま doctest はテスト環境として面白いユニットになっていますが、 それが第一目的なわけではありません。

docstring の例は注意深く作成してください。これには学習を必要とする 一種の芸術が存在します -- 最初はすんなりできないでしょう。 例というものはドキュメントに紛れ無しの価値を与えます。よい例は しばしばいくつもの言葉に値します。可能なら、通常の場合の例、境界条件的な 場合の例、興味深い微妙な例を示し、そして送出されうる例外各々について の例を示してください。おそらく境界条件的な例や微妙な例を対話シェル でテストしていることでしょう: doctest ではこうしたセッションを 取り込み、かつ今後ずっと設計通りに動作するよう検証する作業を 可能な限り簡単にしたいと思っています。

注意深くやれば、例はユーザにとってはあまり意味のないものになるかも しれませんが、歳を経るにつれて、あるいは "状況が変わった" 際に 何度も何度も正しく動作させるためにかかることになる時間を節約する 形で見返りは選られます。私は今でも、自分の doctest で処理した例が "たいした事のない" 変更を行った際にうまく動作しなくなることに 驚いています。

網羅的なテストや、ドキュメントに対する付加価値のまったくない退屈な例の テストについては、__test__ 辞書の方に定義してください。 __test__ はそのための辞書です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.2.7 注意事項 Up: 5.2 doctest Next: 5.3 unittest


5.3 unittest -- 単体テストフレームワーク

バージョン2.1 以降で新規追加された 仕様です。

このPython単体テストフレームワーク は``PyUnit''とも呼ばれ、Kent Beck と Erich GammaによるJUnitのPython版です。JUnitはまたKentのSmalltalk用テスト フレームワークのJava版で、どちらもそれぞれの言語で業界標準の単体テストフ レームワークとなっています。

PyUnitでは、テストの自動化・初期設定と終了処理の共有・テストの分類・テス ト実行と結果レポートの分離などの機能を提供しており、unittestの クラスを使って簡単にたくさんのテストを開発できるようになっています。

PyUnitでは、テストを以下のような構成で開発します。

Fixture

test fixture(テスト設備)とは、テスト実行のために必要な準備や終了処 理を指します。例:テスト用データベースの作成・ディレクトリ・サーバプロセ スの起動など。

テストケース

テストケースはテストの最小単位で、各入力に対する結果をチェックしま す。PyUnitでは、TestCaseを基底クラスとしてテストケースを作成しま す。

テストスイート

テストスイートはテストケースとテストスイートの集まりで、同時に実行 しなければならないテストをまとめる場合に使用します。

テストランナー

テストランナーはテストの実行と結果表示を管理するコンポーネントで す。ランナーはグラフィカルインターフェースでもテキストインターフェースで も良いですし、何も表示せずにテスト結果を示す値を返すだけの場合もありま す。

PyUnitでは、テストケースとfixtureを、TestCaseクラスと FunctionTestCaseクラスで提供しています。TestCaseクラスは 新規にテストを作成する場合に使用し、FunctionTestCaseは既存のテス トをPyUnitに組み込む場合に使用します。fixtureの設定処理と終了処理は、 TestCaseではsetUp()メソッドとtearDown()をオー バーライドして記述し、classFunctionTestCaseでは初期設定・終了処理を行 う既存の関数をコンストラクタで指定します。テスト実行時、まずfixtureの初 期設定が最初に実行されます。初期設定が正常終了した場合、テスト実行後には テスト結果に関わらず終了処理が実行されます。TestCaseの各インスタ ンスが実行するテストは一つだけで、fixtureは各テストごとに新しく作成され ます。

テストスイートはTestSuiteクラスで実装されており、複数のテストと テストスイートをまとめる事ができます。テストスイートを実行すると、スイー トと子スイートに追加されている全てのテストが実行されます。

テストランナーはrun()メソッドを持つオブジェクトで、 run()は引数としてTestCaseかTestSuiteオブジェク トを受け取り、テスト結果をTestResultオブジェクトで戻します。 PyUnitではデフォルトでテスト結果を標準エラーに出力する TextTestRunnerをサンプルとして実装しています。これ以外のランナー (グラフィックインターフェース用など)を実装する場合でも、特定のクラスから 派生する必要はありません。

参考資料:

PyUnit Web Site
The source for further information on PyUnit.
Simple Smalltalk Testing: With Patterns
Kent Beck's original paper on testing frameworks using the pattern shared by unittest.

  • 5.3.1 基礎的な例
  • 5.3.2 テストの構成
  • 5.3.3 既存テストコードの再利用
  • 5.3.4 クラスと関数
  • 5.3.5 TestCase オブジェクト
  • 5.3.6 TestSuite オブジェクト
  • 5.3.7 TestResultオブジェクト
  • 5.3.8 TestLoader オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.2.8 提言 Up: 5. 各種サービス Next: 5.3.1 基礎的な例


5.3.1 基礎的な例

unittestモジュールには、テストの開発や実行の為の優れたツールが 用意されており、この節では、その一部を紹介します。ほとんどのユーザとって は、ここで紹介するツールだけで十分でしょう。

以下は、randomモジュールの三つの関数をテストするスクリプトです。

import random
import unittest

class TestSequenceFunctions(unittest.TestCase):

    def setUp(self):
        self.seq = range(10)

    def testshuffle(self):
        # make sure the shuffled sequence does not lose any elements
        random.shuffle(self.seq)
        self.seq.sort()
        self.assertEqual(self.seq, range(10))

    def testchoice(self):
        element = random.choice(self.seq)
        self.assert_(element in self.seq)

    def testsample(self):
        self.assertRaises(ValueError, random.sample, self.seq, 20)
        for element in random.sample(self.seq, 5):
            self.assert_(element in self.seq)

if __name__ == '__main__':
    unittest.main()

テストケースは、unittest.TestCaseのサブクラスとして作成します。メ ソッド名がtestで始まる三つのメソッドがテストです。テストランナー はこの命名規約によってテストを行うメソッドを検索します。

これらのテスト内では、予定の結果が得られていることを確かめるために assertEqual()を、条件のチェックにassert_()を、例外が発 生する事を確認するためにassertRaises()をそれぞれ呼び出していま す。assert文の代わりにこれらのメソッドを使用すると、テストラン ナーでテスト結果を集計してレポートを作成する事ができます。

setUp()メソッドが定義されている場合、テストランナーは各テストを 実行する前にsetUp()メソッドを呼び出します。同様に、 tearDown()メソッドが定義されている場合は各テストの実行後に呼び 出します。上のサンプルでは、それぞれのテスト用に新しいシーケンスを作成するため にsetUp()を使用しています。

サンプルの末尾が、簡単なテストの実行方法です。unittest.main()は、 テストスクリプトのコマンドライン用インターフェースです。コマンドラインか ら起動された場合、上記のスクリプトから以下のような結果が出力されます:

...
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK

簡略化した結果を出力したり、コマンドライン以外からも起動する等のより細かい 制御が必要であれば、unittest.main()を使用せずに別の方法でテストを 実行します。例えば、上記サンプルの最後の2行は以下のように書くことができ ます:

suite = unittest.TestSuite()
suite.addTest(unittest.makeSuite(TestSequenceFunctions))
unittest.TextTestRunner(verbosity=2).run(suite)

変更後のスクリプトをインタープリタや別のスクリプトから実行すると、以下の 出力が得られます:

testchoice (__main__.TestSequenceFunctions) ... ok
testsample (__main__.TestSequenceFunctions) ... ok
testshuffle (__main__.TestSequenceFunctions) ... ok

----------------------------------------------------------------------
Ran 3 tests in 0.110s

OK

以上がunittestモジュールでよく使われる機能で、ほとんどのテスト ではこれだけでも十分です。基礎となる概念や全ての機能については以降の章を 参照してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.3 unittest Up: 5.3 unittest Next: 5.3.2 テストの構成


5.3.2 テストの構成

単体テストの基礎となる構築要素は、テストケース -- セットアップと 正しさのチェックを行う、独立したシナリオ -- です。PyUnitでは、テスト ケースはunittestモジュールのTestCaseクラスのインスタ ンスで示します。テストケースを作成するにはTestCaseのサブクラスを 記述するか、またはFunctionTestCaseを使用します。

TestCaseから派生したクラスのインスタンスは、このオブジェクトだけ で一件のテストと初期設定・終了処理を行います。

TestCaseインスタンスは外部から完全に独立し、単独で実行する事も、 他の任意のテストと一緒に実行する事もできなければなりません。

以下のように、runTest()をオーバライドし、必要なテスト処理を記述するだけで簡単 なテストケースを書くことができます:

import unittest

class DefaultWidgetSizeTestCase(unittest.TestCase):
    def runTest(self):
        widget = Widget("The widget")
        self.failUnless(widget.size() == (50,50), 'incorrect default size')

何らかのテストを行う場合、ベースクラスTestCaseの assert*() か fail*()メソッドを使用してください。テスト ケース実行時、テストが失敗すると例外が送出され、テストフレームワークはテ スト結果をfailureとします。assert*() とfail*()以 外からの例外が発生した場合、テスト結果はerrorsとなります。

テストの実行方法については後述とし、まずはテストケースインスタンスの作成 方法を示します。テストケースインスタンスは、以下のように引数なしでコンス トラクタを呼び出して作成します。

testCase = DefaultWidgetSizeTestCase()

似たようなテストを数多く行う場合、同じ環境設定処理を何度も必要となりま す。例えば上記のようなWidgetのテストが100種類も必要な場合、それぞれのサ ブクラスで``Widget''オブジェクトを生成する処理を記述するのは好ましくあり ません。

このような場合、初期化処理はsetUp()メソッドに切り出し、テスト実 行時にテストフレームワークが自動的に実行するようにすることができます:

import unittest

class SimpleWidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget("The widget")

class DefaultWidgetSizeTestCase(SimpleWidgetTestCase):
    def runTest(self):
        self.failUnless(self.widget.size() == (50,50),
                        'incorrect default size')

class WidgetResizeTestCase(SimpleWidgetTestCase):
    def runTest(self):
        self.widget.resize(100,150)
        self.failUnless(self.widget.size() == (100,150),
                        'wrong size after resize')

テスト中にsetUp()メソッドで例外が発生した場合、テストフレーム ワークはテストを実行することができないとみなし、runTest()を実行 しません。

同様に、終了処理をtearDown()メソッドに記述すると、 runTest()メソッド終了後に実行されます:

import unittest

class SimpleWidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget("The widget")

    def tearDown(self):
        self.widget.dispose()
        self.widget = None

setUp()が正常終了した場合、runTest()の結果に関わり無く tearDown()が実行されます。

このような、テストを実行する環境をfixtureと呼びます。

JUnitでは、多数の小さなテストケースを同じテスト環境で実行する場合、全て のテストについてDefaultWidgetSizeTestCaseのような SimpleWidgetTestCaseのサブクラスを作成する必要があります。これは 時間のかかる、うんざりする作業ですので、PyUnitではより簡単なメカニズムを 用意しています:

import unittest

class WidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget("The widget")

    def tearDown(self):
        self.widget.dispose()
        self.widget = None

    def testDefaultSize(self):
        self.failUnless(self.widget.size() == (50,50),
                        'incorrect default size')

    def testResize(self):
        self.widget.resize(100,150)
        self.failUnless(self.widget.size() == (100,150),
                        'wrong size after resize')

この例ではrunTest()がありませんが、二つのテストメソッドを定義し ています。このクラスのインスタンスはtest*()メソッドのどちらか一 方の実行と、self.widgetの生成・解放を行います。この場合、テスト ケースインスタンス生成時に、コンストラクタの引数として実行するメソッド名 を指定します:

defaultSizeTestCase = WidgetTestCase("testDefaultSize")
resizeTestCase = WidgetTestCase("testResize")

PyUnitではテストスイートによってテストケースインスタンスをテスト 対象の機能によってグループ化することができます。テストスイート は、unittestのTestSuiteクラスで作成します。

widgetTestSuite = unittest.TestSuite()
widgetTestSuite.addTest(WidgetTestCase("testDefaultSize"))
widgetTestSuite.addTest(WidgetTestCase("testResize"))

各テストモジュールで、テストケースを組み込んだテストスイートオブジェクト を作成する呼び出し可能オブジェクトを用意しておくと、テストの実行や参照が 容易になります:

def suite():
    suite = unittest.TestSuite()
    suite.addTest(WidgetTestCase("testDefaultSize"))
    suite.addTest(WidgetTestCase("testResize"))
    return suite

または:

class WidgetTestSuite(unittest.TestSuite):
    def __init__(self):
        unittest.TestSuite.__init__(self,map(WidgetTestCase,
                                              ("testDefaultSize",
                                               "testResize")))

(小心者は前者を使うべし)

一般的に、TestCaseのサブクラスには良く似た名前のテスト関数が複数 定義されます。そこでunittestモジュールには、テストケースクラ スの全テストケースを使ってテストスイートを作成するmakeSuite() 関数を用意しています。

suite = unittest.makeSuite(WidgetTestCase,'test')

makeSuite()でテストスイートを作成した場合、テストケースの実行 順序はテストケース関数名をcmp()組み込み関数でソートした順番と なります。

システム全体のテストを行う場合など、テストスイートをさらにグループ化した い場合がありますが、このような場合、TestSuiteインスタンスには TestSuiteと同じようにTestSuiteを追加する事ができます。

suite1 = module1.TheTestSuite()
suite2 = module2.TheTestSuite()
alltests = unittest.TestSuite((suite1, suite2))

テストケースやテストスイートは (widget.py のような) テスト対象のモジュール内にも記述すできますが、テストは (widgettests.py のような) 独立したモジュールに置いた方が 以下のような点で有利です:

  • テストモジュールだけをコマンドラインから実行することができる。
  • テストコードと出荷するコードを分離する事ができる。
  • テストコードを、テスト対象のコードに合わせて修正する誘惑に駆られにくい。
  • テストコードは、テスト対象コードほど頻繁に更新されない。
  • テストコードをより簡単にリファクタリングすることができる。
  • Cで書いたモジュールのテストは、どっちにしろ独立したモジュールとなる。
  • テスト戦略を変更した場合でも、ソースコードを変更する必要がない。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.3.1 基礎的な例 Up: 5.3 unittest Next: 5.3.3 既存テストコードの再利用


5.3.3 既存テストコードの再利用

既存のテストコードが有るとき、このテストをPyUnitで実行しようとする為に古 いテスト関数をいちいちTestCaseクラスのサブクラスに変換するのは大 変です。

このような場合は、TestCaseのサブクラスである FunctionTestCaseクラスを使い、既存のテスト関数をラップします。初 期設定と終了処理をラップする事もできます。

以下のテストコードがあった場合:

def testSomething():
    something = makeSomething()
    assert something.name is not None
    # ...

テストケースインスタンスは次のように作成します:

testcase = unittest.FunctionTestCase(testSomething)

初期設定、終了処理が必要な場合は、次のように指定します:

testcase = unittest.FunctionTestCase(testSomething,
                                     setUp=makeSomethingDB,
                                     tearDown=deleteSomethingDB)

注意: PyUnitはAssertionErrorによるテストの失敗検出もサポート していますが、推奨されません。将来のバージョンでは、 AssertionErrorは別の目的に使用される可能性が有ります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.3.2 テストの構成 Up: 5.3 unittest Next: 5.3.4 クラスと関数


5.3.4 クラスと関数

class TestCase( )
TestCaseクラスのインスタンスは、テストの最小実行単位を示しま す。このクラスをベースクラスとして使用し、必要なテストを具象サブクラス に実装します。TestCaseクラスでは、テストランナーがテストを実行 するためのインターフェースと、各種のチェックやテスト失敗をレポートする ためのメソッドを実装しています。

class FunctionTestCase( testFunc[, setUp[, tearDown[, description]]])
このクラスではTestCaseインターフェースの内、テストランナーがテ ストを実行するためのインターフェースだけを実装しており、テスト結果のチ ェックやレポートに関するメソッドは実装していません。既存のテストコード をunittestによるテストフレームワークに組み込むために使用し ます。

class TestSuite( [tests])
このクラスは、個々のテストケースやテストスイートの集約を示します。通常 のテストケースと同じようにテストランナーで実行すると、テストスイート内 の全てのテストケースとテストスイートを実行します。テストケース・テスト スイートを追加するためのメソッドを用意しています。testsには、ス イートに追加するテストのシーケンスを指定する事ができます。

class TestLoader( )
モジュールまたはTestCaseクラスから、指定した条件に従ってテスト をロードし、TestSuiteにラップして返します。モジュールからテス トをロードする場合、全てのTestCase派生クラスを抽出し、名前が "test"で始まる全てのメソッドのインスタンスを作成します。

defaultTestLoader
TestLoaderのインスタンスで、共用する事ができます。 TestLoaderをカスタマイズする必要がなければ、新しい TestLoaderオブジェクトを作らずにこのインスタンスを使用します。

class TextTestRunner( [stream[, descriptions[, verbosity]]])
実行結果を標準結果に出力する、単純なテストランナー。いくつかの設定項目 がありますが、非常に単純です。グラフィカルなテスト実行アプリケーション では、独自のテストランナーを作成してください。

main( [module[, defaultTest[, argv[, testRunner[, testRunner]]]]])
テストを実行するためのコマンドラインプログラム。この関数を使えば、次の ように簡単に実行可能なテストモジュールを作成する事ができます。

if __name__ == '__main__':
    unittest.main()

場合によっては、doctest モジュールを使って書かれた 既存のテストがあります。その場合、モジュールは 既存のテストコードから unittest.TestSuite インスタンスを 自動的に構築できる DocTestSuite クラスを提供します。 バージョン2.3 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.3.3 既存テストコードの再利用 Up: 5.3 unittest Next: 5.3.5 TestCase オブジェクト


5.3.5 TestCase オブジェクト

TestCaseクラスのインスタンスは個別のテストをあらわすオブジェクト ですが、TestCaseの具象サブクラスには複数のテストを定義する事がで きます -- 具象サブクラスは、特定のfixture(テスト設備)を示している、と考 えてください。fixtureは、それぞれのテストケースごとに作成・解放されま す。

TestCaseインスタンスには、次の3種類のメソッドがあります:テストを 実行するためのメソッド・条件のチェックやテスト失敗のレポートのためのメソ ッド・テストの情報収集に使用する問い合わせメソッド。

テストを実行するためのメソッドを以下に示します:

setUp( )
テストを実行する直前に、fixtureを作成する為に呼び出されます。このメソ ッドを実行中に例外が発生した場合、テストの失敗ではなくエラーとされま す。デフォルトの実装では何も行いません。

tearDown( )
テストを実行し、結果を記録した直後に呼び出されます。テスト実行中に例外 が発生しても呼び出されますので、内部状態に注意して処理を行ってくださ い。メソッドを実行中に例外が発生した場合、テストの失敗ではなくエラーと みなされます。このメソッドは、setUp()が正常終了した場合にはテ ストメソッドの実行結果に関わり無く呼び出されます。デフォルトの実装では 何も行いません。

run( [result])
テストを実行し、テスト結果をresultに指定されたテスト結果オブジェ クトに収集します。resultがNoneか省略された場合、一時的な結果オブ ジェクトを生成して使用しますが呼び出し元には渡されません。このメソッド は、TestCaseインスタンスの呼び出しと等価です。

debug( )
テスト結果を収集せずにテストを実行します。例外が呼び出し元に通知される ため、テストをデバッガで実行することができます。

テスト結果のチェックとレポートには、以下のメソッドを使用してください。

assert_( expr[, msg])
failUnless( expr[, msg])
exprが偽の場合、テスト失敗を通知します。msgにはエラーの説 明を指定するか、またはNoneを指定してください。

assertEqual( first, second[, msg])
failUnlessEqual( first, second[, msg])
firstとsecondexprが等しくない場合、テスト失敗を通知 します。エラー内容はmsgに指定された値か、またはNoneとなり ます。failUnlessEqual()ではmsgのデフォルト値は firstとsecondを含んだ文字列となりますので、 failUnless()の第一引数に比較の結果を指定するよりも便利です。

assertNotEqual( first, second[, msg])
failIfEqual( first, second[, msg])
firstとsecondexprが等しい場合、テスト失敗を通知しま す。エラー内容はmsgに指定された値か、またはNoneとなりま す。failUnlessEqual()ではmsgのデフォルト値はfirst とsecondを含んだ文字列となりますので、failUnless()の第 一引数に比較の結果を指定するよりも便利です。

assertAlmostEqual( first, second[, places[, msg]])
failUnlessAlmostEqual( first, second[, places[, msg]])
first と second を places で与えた少数位で値を丸めて差分を計算し、 ゼロと比較することで、近似的に等価であるかどうかをテストします。 指定少数位の比較というものは指定有効桁数の比較ではないので注意してください。 値の比較結果が等しくなかった場合、テストは失敗し、msg で与えた 説明か、None を返します。

assertNotAlmostEqual( first, second[, places[, msg]])
failIfAlmostEqual( first, second[, places[, msg]])
first と second を places で与えた少数位で値を丸めて差分を計算し、 ゼロと比較することで、近似的に等価でないかどうかをテストします。 指定少数位の比較というものは指定有効桁数の比較ではないので注意してください。 値の比較結果が等しかった場合、テストは失敗し、msg で与えた 説明か、None を返します。

assertRaises( exception, callable, ...)
failUnlessRaises( exception, callable, ...)
callableを呼び出し、発生した例外をテストします。 assertRaises()には、任意の位置パラメータとキーワードパラメー タを指定する事ができます。exceptionで指定した例外が発生した場合 はテスト成功とし、それ以外の例外が発生するか例外が発生しない場合にテス ト失敗となります。複数の例外を指定する場合には、例外クラスのタプルを exceptionに指定します。

failIf( expr[, msg])
failIf()はfailUnless()の逆で、exprが真の場合、 テスト失敗を通知します。エラー内容はmsgに指定された値か、または Noneとなります。

fail( [msg])
無条件にテスト失敗を通知します。エラー内容はmsgに指定された値 か、またはNoneとなります。

failureException
test()メソッドが送出する例外を指定するクラス属性。テストフ レームワークで追加情報を持つ等の特殊な例外を使用する場合、この例外のサ ブクラスとして作成します。この属性の初期値はAssertionError です。

テストフレームワークは、テスト情報を収集するために以下のメソッドを使用し ます:

countTestCases( )
テストオブジェクトに含まれるテストの数を返します。TestCaseイン スタンスは常に1を返します。TestSuiteクラスでは1 以上を返します。

defaultTestResult( )
オブジェクトが実行するテストの、デフォルトのテスト結果オブジェクトの型 を返します。

id( )
テストケースを特定する文字列を返します。通常、idはモジュール名・ クラス名を含む、テストメソッドのフルネームを指定します。

shortDescription( )
テストの説明を一行分、または説明がない場合にはNoneを返します。 デフォルトでは、テストメソッドのdocstringの先頭の一行、または Noneを返します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.3.4 クラスと関数 Up: 5.3 unittest Next: 5.3.6 TestSuite オブジェクト


5.3.6 TestSuite オブジェクト

TestSuiteオブジェクトはTestCaseとよく似た動作をします が、実際のテストは実装せず、一まとめにに実行するテストのグループをまとめ るために使用します。TestSuiteには以下のメソッドが追加されていま す:

addTest( test)
TestCase又はTestSuiteのインスタンスをスイートに追加し ます。

addTests( tests)
シーケンスtestに含まれる全てのTestCase又は TestSuiteのインスタンスをスイートに追加します。

run()メソッドはTestCaseのrun()メソッドと若干異 なります:

run( result)
スイート内のテストを実行し、結果をresultで指定した結果オブジェク トに収集します。TestCase.run()と異なり、 TestSuite.run()では必ず結果オブジェクトを指定する必要がありま す。

通常、TestSuiteのrun()メソッドはTestRunnerが起 動するため、ユーザが直接実行する必要はありません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.3.5 TestCase オブジェクト Up: 5.3 unittest Next: 5.3.7 TestResultオブジェクト


5.3.7 TestResultオブジェクト

TestResultは、複数のテスト結果を記録します。TestCaseクラ スとTestSuiteクラスのテスト結果を正しく記録しますので、テスト開 発者が独自にテスト結果を管理する処理を開発する必要はありません。

unittestを利用したテストフレームワークでは、 TestRunner.run()が返すTestResultインスタンスを参照し、 テスト結果をレポートします。

TestResultインスタンスは、テストの実行件数と、テスト中に発生した 失敗・エラーの情報を(testcase, traceback)のタプルで保 持します。tracebackは例外のトレースバック情報をフォーマットした文 字列です。

以下の属性は、テストの実行結果を検査する際に使用することができます:

errors
テスト中に発生した例外の内、テスト失敗ではなくエラーとなった例外の情報 のリスト。リストの要素は、TestCaseと例外のトレースバック情報を フォーマットした文字列の組となります。 バージョン2.2 以降で変更された 仕様: sys.exc_info()の結果ではなく、フォーマットしたトレースバッ クを保存

failures
テスト中に発生した失敗の情報のリスト。リストの要素は、TestCase と例外のトレースバック情報をフォーマットした文字列の組となります。 バージョン2.2 以降で変更された 仕様: sys.exc_info()の結果ではなく、フォーマット したトレースバックを保存

testsRun
開始したテストの数。

wasSuccessful( )
これまでに実行したテストが全て成功していればTrueを、それ以外ならFalse を返す。

以下のメソッドは内部データ管理用のメソッドですが、対話的にテスト結果をレ ポートするテストツールを開発する場合などにはサブクラスで拡張することがで きます。

startTest( test)
testを実行する直前に呼び出されます。

stopTest( test)
testの実行直後に、テスト結果に関わらず呼び出されます。

addError( test, err)
テスト実行中に、テストの失敗以外の例外が発生した場合に呼び出されます。 errはsys.exc_info()が返すタプル(type, value, traceback)です。

addFailure( test, err)
テストが失敗した場合に呼び出されます。errは sys.exc_info()が返すタプル(type, value, traceback)です。

addSuccess( test)
テストが失敗しなかった場合に呼び出されます。testには、テストケー スオブジェクトが指定されます。

TestResultオブジェクトには、さらにもう一つのメソッドがあります:

stop( )
テスト中断のシグナルを送ります。このメソッドが呼び出されると、テストラ ンナーは以降のテスト実行を中止し、呼び出し元に復帰します。 TextTestRunnerではキーボードからの割り込みでテストを中断するた めにこのメソッドを使用しており、独自のランナーを実装する場合にも同じよ うに使用することができます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.3.6 TestSuite オブジェクト Up: 5.3 unittest Next: 5.3.8 TestLoader オブジェクト


5.3.8 TestLoader オブジェクト

TestLoaderクラスは、クラスやモジュールからテストスイートを作成す るために使用します。通常はこのクラスのインスタンスを作成する必要はなく、 unittestモジュールのモジュール属性defaultTestLoaderを 共用インスタンスとして使用することができます。

TestLoader オブジェクトには以下のメソッドがあります:

loadTestsFromTestCase( testCaseClass)
TestCaseの派生クラスtestCaseClassに含まれる全テスト ケースのスイートを返します。

loadTestsFromModule( module)
指定したモジュールに含まれる全テストケースのスイートを返します。このメ ソッドはmodule内のTestCase派生クラスを検索し、見つかった クラスのテストメソッドごとにクラスのインスタンスを作成します。

警告: Testcaseクラスを基底クラスとしてクラス階層を構築する とfixtureや補助的な関数をうまく共用することができますが、基底クラスに 直接インスタンス化できないテストメソッドがあると、この loadTestsFromModuleを使うことができません。この場合でも、 fixtureが全て別々で定義がサブクラスにある場合は使用することができま す。

loadTestsFromName( name[, module])
文字列で指定される全テストケースを含むスイートを返します。

nameには``ドット修飾名''でモジュールかテストケースクラス、または TestCaseかTestSuiteのインスタンスを返す呼び出し可能オ ブジェクトを指定します。例えばSampleTestsモジュールに TestCaseから派生したSampleTestCaseクラスがあり、 SampleTestCaseにはテストメソッドtest_one()・ test_two()・test_three()があるとします。この場合、 nameに'SampleTests.SampleTestCase'と指定すると、 SampleTestCaseの三つのテストメソッドを実行するテストスイートが 作成されます。'SampleTests.SampleTestCase.test_two'と指定すれ ば、test_two()だけを実行するテストスイートが作成されます。イ ンポートされていないモジュールやパッケージ名を含んだ名前を指定した場合 は自動的にインポートされます。

また、moduleを指定した場合、module内のnameを取得しま す。

loadTestsFromNames( names[, module])
loadTestsFromName()と同じですが、名前を一つだけ指定するのでは なく、複数の名前のシーケンスを指定する事ができます。戻り値は names中の名前で指定されるテスト全てを含むテストスイートです。

getTestCaseNames( testCaseClass)
testCaseClass中の全てのメソッド名を含むソート済みシーケンスを返 します。

以下の属性は、サブクラス化またはインスタンスの属性値を変更してTestLoaderをカスタマイズする場合に使用します。

testMethodPrefix
テストメソッドの名前と判断されるメソッド名の接頭語を示す文字列。デフォ ルト値は'test'です。

sortTestMethodsUsing
getTestCaseNames()でメソッド名をソートする際に使用する比較関 数。デフォルト値は組み込み関数cmp()です。Noneを指定 するとソートを行いません。

suiteClass
テストのリストからテストスイートを構築する呼び出し可能オブジェクト。メ ソッドを持つ必要はありません。デフォルト値はTestSuiteです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.3.7 TestResultオブジェクト Up: 5.3 unittest Next: 5.4 test


5.4 test -- Python用回帰テストパッケージ

test パッケージには、Python 用の全ての回帰テストと、 test.test_supportおよびtest.regrtest モジュール が入っています。test.test_support はテストを充実させる ために使い、test.regtest はテストスイートを駆動するのに 使います。

testパッケージ内の各モジュールのうち、名前が"test_"で始まるものは、特定のモジュールや機能に対するテストスイートです。 新しいテストはすべてunittestモジュールを使って書くように してください; 必ずしもunittest を使う必要はないのですが、 unittest はテストをより柔軟にし、メンテナンスをより簡単に します。古いテストのいくつかはdoctest を利用しており、 ``伝統的な'' テスト形式になっています。これらのテスト形式をカバー する予定はありません。

参考資料:

unittestモジュール:
PyUnit 回帰テストを書く。.
doctestモジュール:
ドキュメンテーション文字列に埋め込まれたテスト。.

  • 5.4.1 testパッケージのためのユニットテストを書く
  • 5.4.2 test.regrtestを使ってテストを実行する
  • 5.4.3 test.test_support -- テストのためのユーティリティ関数
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.3.8 TestLoader オブジェクト Up: 5. 各種サービス Next: 5.4.1 testパッケージのためのユニットテストを書く


5.4.1 testパッケージのためのユニットテストを書く

test パッケージ用のテストを書く場合、unittest モジュールを使い、以下のいくつかのガイドラインに従うよう推奨します。 一つは、テストモジュールの名前と同様、すべてのテストメソッドの 名前を"'test_'"で始めることです。これはテスト駆動プログラムに そのメソッドをテストメソッドとして認識させるためです。 また、テストメソッドにはドキュメンテーション文字列を入れるべきでは ありません。 テストメソッドのドキュメント記述には、 ("# True あるいは False だけを返すテスト関数" のような) コメントを使ってください。 これは、ドキュメンテーション文字列が存在する場合にはその内容が出力 されるため、どのテストを実行しているのかをいちいち表示しなくするためです。

以下のような基本的な決まり文句を使います:

import unittest
from test import test_support

class MyTestCase1(unittest.TestCase):

    # Only use setUp() and tearDown() if necessary

    def setUp(self):
        ... code to execute in preparation for tests ...

    def tearDown(self):
        ... code to execute to clean up after tests ...

    def test_feature_one(self):
        # Test feature one.
        ... testing code ...

    def test_feature_two(self):
        # Test feature two.
        ... testing code ...

    ... more test methods ...

class MyTestCase2(unittest.TestCase):
    ... same structure as MyTestCase1 ...

... more test classes ...

def test_main():
    test_support.run_unittest(MyTestCase1,
                              MyTestCase2,
                              ... list other tests ...
                             )

if __name__ == '__main__':
    test_main()

この定型的なコードによって、テストスイートをregrtest.py から起動できると同時に、スクリプト自体からも実行できるようになります。

回帰テストの目的はコードの分解です。 そのためには以下のいくつかのガイドラインに従ってください:

  • テストスイートはすべてのクラス、関数および定数を用いるべきです。 これは外部に公開される外部APIだけでなく"非公開"コードも含んでいます。
  • ホワイトボックス・テスト (テストを書くときに対象のコードをすぐ テストする) を推奨します。ブラックボックス・テスト (最終的に公開された ユーザーインターフェイスだけをテストする) は、すべての境界条件と 極端条件を確実にテストするには完全ではありません。
  • 無効な値を含み、すべての取りうる値を確実にテストするように してください。そうすることで、全ての有効な値を受理するだけでなく、 不適切な値を正しく処理することも確認できます。
  • できる限り多くのコード経路を網羅してください。分岐が生じる テストし、入力を調整して、コードの全体に渡って取りえる限りの個々の 処理経路を確実にたどらせるようにしてください。
  • テスト対象のコードにどんなバグが発見された場合でも、明示的な テスト追加するようにしてください。そうすることで、将来コードを変更した 際にエラーが再発しないようにできます。
  • (一時ファイルをすべて閉じたり削除したりするといった) テストの 後始末を必ず行ってください。
  • import するモジュールをできるかぎり少なくし、可能な限り 早期に import を行ってください。そうすることで、てテストの外部依存性を 最小限にし、モジュールの import による副作用から生じる変則的な動作を 最小限にできます。
  • コードの再利用を最大限に行うようにしてください。時として、 テストの多様性はどんな型の入力を受け取るかの違いまで小さくなります。 例えば以下のように、入力が指定されたサブクラスで基底テストクラスを サブクラス化して、コードの複製を最小化します:
    class TestFuncAcceptsSequences(unittest.TestCase):

    func = mySuperWhammyFunction

    def test_func(self):
        self.func(self.arg)

class AcceptLists(TestFuncAcceptsSequences):
    arg = [1,2,3]

class AcceptStrings(TestFuncAcceptsSequences):
    arg = 'abc'

class AcceptTuples(TestFuncAcceptsSequences):
    arg = (1,2,3)

参考資料:

Test Driven Development
コードより前にテストを書く 方法論に関する Kent Beck の著書

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.4 test Up: 5.4 test Next: 5.4.2 test.regrtestを使ってテストを実行する


5.4.2 test.regrtestを使ってテストを実行する

test.regrtest を使うと Python の回帰テストスイートを駆動 できます。スクリプトを単独で実行すると、自動的にtest パッケージ内のすべての回帰テストを実行し始めます。パッケージ内の 名前が"test_"で始まる全モジュールを見つけ、それをインポートし、 もしあるなら関数 test_main を実行してテストを行います。 実行するテストの名前もスクリプトに渡される可能性もあります。 単一の回帰テストを指定 (python regrtest.py test_spam.py) すると、 出力を最小限にします。テストが成功したかあるいは失敗したかだけを出力 するので、出力は最小限になります。

直接 test.regrtest を実行すると、テストに利用するリソースを 設定できます。これを行うには、-u コマンドラインオプションを使います。すべてのリソースを使うには、 python regrtest.py -uall を実行します。 -u のオプションに all を指定すると、 すべてのリソースを有効にします。(よくある場合ですが) 何か一つを除く 全てが必要な場合、カンマで区切った不要なリソースのリストを all の後に並べます。 コマンドpython regrtest.py -uall,-audio,-largefile とすると、audio と largefile リソースを除く 全てのリソースを使ってtest.regrtest を実行します。 すべてのリソースのリストと追加のコマンドラインオプションを出力 するには、python regrtest.py -h を実行 してください。

テストを実行しようとするプラットフォームによっては、回帰テストを 実行する別の方法があります。 Unix では、Python をビルドしたトップレベルディレクトリで make test を実行できます。 Windows上では、PCBuild ディレクトリから rt.bat を 実行すると、すべての回帰テストを実行します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.4.1 testパッケージのためのユニットテストを書く Up: 5.4 test Next: 5.4.3 test.test_support


5.4.3 test.test_support -- テストのためのユーティリティ関数

test.test_support モジュールでは、 Python の回帰テストに対する サポートを提供しています。

このモジュールは次の例外を定義しています:

exception TestFailed
テストが失敗したとき送出される例外です。

exception TestSkipped
TestFailedのサブクラスです。 テストがスキップされたとき送出されます。 テスト時に (ネットワーク接続のような) 必要なリソースが利用 できないときに送出されます。

exception ResourceDenied
TestSkippedのサブクラスです。 (ネットワーク接続のような)リソースが利用できないとき送出されます。 requires関数によって送出されます。

test.test_support モジュールでは、以下の定数を定義しています:

verbose
冗長な出力が有効な場合はTrue です。 実行中のテストについてのより詳細な情報が欲しいときにチェックします。 verbose は test.regrtest によって設定されます。

have_unicode
ユニコードサポートが利用可能ならばTrue になります。

is_jython
実行中のインタプリタが Jython ならばTrue になります。

TESTFN
一時ファイルを作成するパスに設定されます。 作成した一時ファイルは全て閉じ、unlink (削除) せねばなりません。

test.test_support モジュールでは、以下の関数を定義しています:

forget( module_name)
モジュール名module_nameをsys.modulesから取り除き、 モジュールのバイトコンパイル済みファイルを全て削除します。

is_resource_enabled( resource)
resource が有効で利用可能ならばTrueを返します。 利用可能なリソースのリストは、test.regrtestがテストを 実行している間のみ設定されます。

requires( resource[, msg])
resource が利用できなければ、ResourceDeniedを 送出します。その場合、msgは ResourceDenied の引数に なります。__name__ が "__main__" である関数にから 呼び出された場合には常に真を返します。 テストをtest.regrtest から実行するときに使われます。

findfile( filename)
filenameという名前のファイルへのパスを返します。 一致するものが見つからなければ、filename 自体を返します。 filename 自体もファイルへのパスでありえるので、 filename が返っても失敗ではありません。

run_unittest( *classes)
渡された unittest.TestCase サブクラスを実行します。 この関数は名前が "test_" で始まるメソッドを探して、 テストを個別に実行します。 この方法をテストの実行方法として推奨しています。

run_suite( suite[, testclass=None])
unittest.TestSuite のインスタンス suiteを実行します。 オプション引数testclass はテストスイート内のテストクラスの 一つを受け取り、指定するとテストスイートが存在する場所についてさらに 詳細な情報を出力します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.4.2 test.regrtestを使ってテストを実行する Up: 5.4 test Next: 5.5 math


5.5 math -- 数学関数

このモジュールはいつでも利用できます。標準 C で定義されている数学関数に アクセスすることができます。

これらの関数で複素数を使うことはできません。複素数に対応する必要がある ならば、 cmath モジュールにある同じ名前の関数を使ってくだ さい。ほとんどのユーザーは複素数を理解するのに必要なだけの数学を勉強し たくないので、複素数に対応した関数と対応していない関数の区別がされてい ます。これらの関数では複素数が利用できないため、引数に複素数を渡される と、複素数の結果が返えるのではなく例外が発生します。その結果、プログラ マは、そもそもどういった理由で例外がスローされたのかに早い段階で気づく 事ができます。5.1

このモジュールでは次の関数が用意されています。 特に明示的に指定されていなければ、戻り値は全て浮動小数点数となります:

acos( x)
x の逆余弦を返します。

asin( x)
x の逆余弦を返します。

atan( x)
x 逆余弦を返します。

atan2( y, x)
atan(y / x) の逆正接を返します。

ceil( x)
x 以上の最も小さい整数をfloat型で返します。

cos( x)
x の余弦を返します。

cosh( x)
x の双曲線余弦を返します。

degrees( x)
角 x をラジアンから度数に変換します。

exp( x)
e**x を返します。

fabs( x)
x の絶対値を返します。

floor( x)
x 以下の最も大きい整数をfloat型で返します。

fmod( x, y)
プラットフォームの C ライブラリで定義されている fmod(x, y) を返します。 Python の x % y という式が同じ結果を返さないかもしれないことに注意してください。

frexp( x)
x の仮数と指数を (m, e)のペアとして返します。 x == m * 2**e というように、mはfloat型でeはint型です。 x がゼロの場合は、 (0.0, 0)を返し、それ以外の場合は、 0.5 <= abs(m) < 1 です。

hypot( x, y)
ユークリッド距離(sqrt(x*x + y*y))を返します。

ldexp( x, i)
x * (2**i) を返します。

log( x[, base])
x の自然対数を返します。 base を底とした x の対数を返します。base を省略した場合 x の自然対数を返します。 バージョン2.3 以降で変更された 仕様: base argument added

log10( x)
x の10を底とした対数を返します。

modf( x)
xの小数部分と整数部分を返します。 両方の結果は xの符号を受け継ぎます。 整数部はfloat型で返されます。

pow( x, y)
x**yを返します。

radians( x)
角 x を度数からラジアンに変換します。

sin( x)
xの正弦を返します。

sinh( x)
xの双曲線正弦を返します。

sqrt( x)
x の平方根を返します。

tan( x)
x の正接を返します。

tanh( x)
x の双曲線正接を返します。

frexp()と modf() は C のものとは異なった呼び出し/返し パターンを持っていることに注意してください。引数を1つだけ受け取り、1組のペアに なった値を返すので、2つ目の戻り値を`出力引数'(Python にそのようなものはありません) 経由で返したりはしません。

このモジュールでは2つの数学定数も定義されています。

pi
数学定数 pi。

e
数学定数 e。

注意: math モジュールは、ほとんどが実行プラットフォームにおける C 言語の数学ライブラリ関数に対する薄いラッパでできています。 例外的な場合での挙動は、 C 言語標準ではおおさっぱにしか定義されておらず、 さらに Python は数学関数におけるエラー報告機能の挙動をプラットフォームの C 実装から受け継いでいます。その結果として、エラーの際 (およびなんらか の引数がとにかく例外的であると考えられる場合) に送出される特定の例外に ついては、プラットフォーム間やリリースバージョン間を通じて有意なものと なっていません。例えば、 math.log(0) が -Inf を返すか ValueError または OverflowError を送出するかは不定であり、 math.log(0) が OverflowError を送出する場合において math.log(0L) が ValueError を送出するときもあります。

参考資料:

cmathモジュール:
これらの多くの関数の複素数版。.

... 事ができます。5.1
訳注：例外が発生しないで、計算結果が返えってし まうと、計算結果がおかしい事から、原因が複素数を渡したせいである事に プログラマが気づくのがおくれる可能性があります。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.4.3 test.test_support Up: 5. 各種サービス Next: 5.6 cmath


5.6 cmath -- 複素数のための数学関数

このモジュールは常に利用することができます。このモジュールでは、 複素数のための数学関数群へのアクセス手段を提供します。 以下が提供されている関数群です:

acos( x)
x の逆余弦 (arc cosine) を返します。 この関数には二つの branch cut があります: 一つは 1 から右側に実数軸に沿って ∞へと延びていて、 下から連続しています。 もう一つは -1 から左側に実数軸に沿って -∞へと延びていて、 上から連続しています。

acosh( x)
x の逆双極線余弦を返します。 branch cut が一つあり、1 の左側に実数軸に沿って -∞へと 延びていて、上から連続しています。

asin( x)
x の逆正弦を返します。 acos() と同じ branch cut を持ちます。

asinh( x)
x の双極正弦を返します。 2 つの brnch cut があり、±1j の左から ±-∞j に延びており、両方とも上で連続しています。 これらの branch cut は将来のリリースで修正されるべきバグとみなされて います。 正しい branch cut は虚数軸に沿って延びており、一つは 1j から ∞j までで右から連続、もう一方は -1j から下って -∞j までで、左から連続です。

atan( x)
x の逆正接を返します。 2 つの branch cut があります: 一つは 1j から虚数軸に沿って ∞j へと延びており、 左で連続です。もう一方は -1j から虚数軸に沿って -∞j までで、左で連続です。 (この仕様は上の branch cut が反対側から連続になるように変更されるかも しれません)。

atanh( x)
x の双極逆正接を返します。 2 つの branch cut があります: 一つは 1 から実数軸に沿って ∞までで、上で連続です。 もう一方は -1 から実数軸に沿って -∞までで、 上で連続です。 (この仕様は左側の branch cut が反対側から連続になるように変更されるかも しれません)。

cos( x)
x の余弦を返します。

cosh( x)
x の双極線余弦を返します。

exp( x)
指数値 e**x を返します。

log( x)
x の自然対数を返します。 branch cut を一つもち、0 から負の実数軸に沿って -∞に 延びており、上で連続しています。

log10( x)
x の底 10 対数を返します。 log() と同じbranch cut を持ちます。

sin( x)
x の正弦を返します。

sinh( x)
x の双曲線正弦を返します。

sqrt( x)
x の平方根を返します。 log() と同じ branch cut を持ちます。

tan( x)
x の正接を返します。

tanh( x)
x の双曲線正接を返します。

このモジュールではまた、以下の数学上の定数も定義しています:

pi
数学上の定数 pi で、実数です。

e
数学上の定数 e で、実数です。

提供される関数の選択は mathと同様 ですが、全く同じではないので注意してください。二つのモジュールに しているのは、ユーザによっては複素数には興味がなく、おそらく 複素数とは何かすら知らないからです。そういった人たちはむしろ、 math.sqrt(-1) が複素数を返すよりも例外を送出するほうを 好みます。また、cmath で定義されている関数は常に、 たとえ答えを実数として表現することができる (虚数部分がゼロの複素数) の場合でも、複素数を返すので注意してください。

branch cut に関する注釈: branch cut をもつ曲線上では、与えられた関数は 連続でありえなくなります。これらは多くの複素関数における必然的な 特性です。複素関数を計算する必要がある場合、これらの branch cut に 関して理解しているものと仮定しています。悟りに至るために何らかの (到底基礎的とはいえない) 複素数に関する書をひもといてください。 数値計算を目的とした branch cut の正しい選択方法についての情報としては、 以下がよい参考文献となります:

参考資料:

Kahan, W: Branch cuts for complex elementary functions; or, Much ado about nothings's sign bit. In Iserles, A., and Powell, M. (eds.), The state of the art in numerical analysis. Clarendon Press (1987) pp165-211.

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.5 math Up: 5. 各種サービス Next: 5.7 random


5.7 random -- 擬似乱数を生成する

このモジュールでは様々な分布をもつ擬似乱数生成器を実装しています。 整数用では、ある値域内の数の選択を一様にします。 配列用には、配列からのランダムな要素の一様な選択、リストの要素の順列をランダムに置き換える関数、順列を入れ替えずにランダムに取り出す関数があります。

実数用としては、一様分布、正規分布 (ガウス分布)、 対数正規分布、負の指数分布、ガンマおよびベータ分布を計算する 関数があります。 角度分布の生成用には、von Mises 分布が利用可能です。

ほとんど全てのモジュール関数は基礎となる関数 random() に依存 します。この関数は半開区間 [0.0, 1.0) の値域を持つ一様な浮動小数点数を生 成します。Python は中心となる乱数生成器として Mersenne Twister を使いま す。これは 53 ビットの浮動小数点を生成し、周期が 2**19937-1、本体は C で実装されていて、高速でスレッドセーフです。Mersenne Twister は、現存す る中で、最も大規模にテストされた乱数生成器のひとつです。しかし、完全に決 定論的であるため、この乱数生成器は全ての目的に合致しているわけではなく、 暗号化の目的には全く向いていません。

このモジュールで提供されている関数は、実際には random.Random クラスの隠蔽されたインスタンスのメソッドにバインドされています。 内部状態を共有しない生成器を取得するため、自分で Random のインスタンスを生成することができます。異なる Random のインスタンスを各スレッド毎に生成し、jumpahead() メソッドを使うことで各々のスレッドにおいて生成された乱数配列が 重複しないようにすれば、マルチスレッドプログラムを作成する上で 特に便利になります。

自分で考案した基本乱数生成器を使いたいなら、クラス Random を
サブクラス化することもできます: この場合、メソッド random()、
send()、getstate()、setstate()、および
jumpahead() をオーバライドしてください。

サブクラス化の例として、random モジュールは WichmannHill クラスを提供します。このクラスは Python だけで書かれた代替生成器を実装し ています。このクラスは、乱数生成器に Wichmann-Hill 法を使っていた古いバ ージョンの Python から得られた結果を再現するための、後方互換の手段になり ます。 バージョン2.3 以降で変更された 仕様: MersenneTwister を Wichmann-Hill の代わりに使う

保守関数:

seed( [x])
基本乱数生成器を初期化します。 オプション引数 x はハッシュ可能な任意のオブジェクトを とり得ます。x が省略されるか None の場合、現在のシステム 時間が使われます; 現在のシステム時間はモジュールが最初にインポート された時に乱数生成器を初期化するためにも使われます。 x が None でも、整数でも長整数でもない場合、 hash(x) が代わりに使われます。 x が整数または長整数の場合、x が直接使われます。

getstate( )
乱数生成器の現在の内部状態を記憶したオブジェクトを返します。 このオブジェクトを setstate() に渡して内部状態を 復帰することができます。 バージョン2.1 以降で新規追加された 仕様です。

setstate( state)
state は予め getstate() を呼び出して得ておかなくては なりません。setstate() は setstate() が呼び出 された時の乱数生成器の内部状態を復帰します。 バージョン2.1 以降で新規追加された 仕様です。

jumpahead( n)
内部状態を、現在の状態から、非常に離れているであろう状態に変更します。 n は非負の整数です。 これはマルチスレッドのプログラムが複数の Random クラス のインスタンスと結合されている場合に非常に便利です: setstate() や seed() は全てのインスタンスを同じ内部状態にするのに 使うことができ、その後 jumpahead() を使って各インスタンスの 内部状態を引き離すことができます。 バージョン2.1 以降で新規追加された 仕様です。 バージョン2.3 以降で変更された 仕様: n ステップ先の特定の状態になるのではなく、 jumpahead(n) は何ステップも離れているであろう別の状態にする

整数用の関数:

randrange( [start,] stop[, step])
range(start、stop、step) の要素から ランダムに選ばれた要素を返します。この関数は choice(range(start, stop, step)) と等価ですが、実際には range オブジェクトを生成しません。 バージョン1.5.2 以降で新規追加された 仕様です。

randint( a, b)
a <= N <= b であるような ランダムな整数 N を返します。

配列用の関数:

choice( seq)
空でない配列 seq からランダムに要素を返します。

shuffle( x[, random])
配列 x を直接変更によって混ぜます。 オプションの引数 random は、値域が [0.0, 1.0) のランダムな 浮動小数点数を返すような引数を持たない関数です; 標準では、 この関数は random() です。

かなり小さい len(x) であっても、x の順列は ほとんどの乱数生成器の周期よりも大きくなるので注意してください; このことは長い配列に対してはほとんどの順列は生成されないことを 意味します。

sample( population, k)
母集団の配列から選ばれた長さ k の一意な要素からなるリスト を返します。値の置換を行わないランダムサンプリングに用いられます。 バージョン2.3 以降で新規追加された 仕様です。

母集団自体を変更せずに、母集団内の要素を含む新たなリストを返します。返さ れたリストは選択された順に並んでいるので、このリストの部分スライスもラン ダムなサンプルになります。これにより、くじの当選者を1等賞と2等賞（の部分 スライス）に分けるといったことも可能です。母集団の要素はハッシュ可能でな くても、ユニークでなくても、かまいません。母集団が繰り返しを含む場合、返 されたリストの各要素はサンプルから選択可能な要素になります。整数の並びか らサンプルを選ぶには、引数に xrange を使いましょう。特に、巨 大な母集団からサンプルを取るとき、速度と空間効率が上がります。 sample(xrange(10000000), 60)

以下の関数は特殊な実数値分布を生成します。関数パラメタは 対応する分布の公式において、数学的な慣行に従って使われている 変数から取られた名前がつけられています; これらの公式のほとんどは 多くの統計学のテキストに載っています。

random( )
値域 [0.0, 1.0) の次のランダムな浮動小数点数を返します。

uniform( a, b)
a <= N <= b であるような ランダムな実数 N を返します。

betavariate( alpha, beta)
ベータ分布です。引数の満たすべき条件は Beta distribution. Conditions on the parameters are alpha > -1 および beta > -1 です。 0 から 1 の値を返します。

cunifvariate( mean, arc)
円形一様分布です。mean は平均角度で、arc は平均角を 中心とした分布の範囲です。値は両方ともラジアンで表され、0 から pi の値をとることができます。返される値の範囲は mean - arc/2 から mean + arc/2 になりますが、 0 から pi の間に正規化されます。

リリース 2.3 以降で撤廃された仕様です。 (mean + arc * (random.random() - 0.5)) % math.pi を代わりに使ってください。

expovariate( lambd)
指数分布です。lambd は平均にしたい値で 1.0 を割ったものです。 (このパラメタは ``lambda'' と呼ぶべきなのですが、Python の予約語 なので使えません。) 返される値の範囲は 0 から正の無限大です。

gammavariate( alpha, beta)
ガンマ分布です。 (ガンマ関数 ではありません ！) 引数の満たすべき条件は alpha > 0 および beta > 0 です。

gauss( mu, sigma)
ガウス分布です。mu は平均であり、 sigma は 標準偏差です。この関数は後で定義する関数 normalvariate() より少しだけ高速です。

lognormvariate( mu, sigma)
対数正規分布です。この分布を自然対数を用いた分布にした場合、 平均 mu で標準偏差 sigma の正規分布になるでしょう。 mu は任意の値を取ることができ、 sigma はゼロより 大きくなければなりません。

normalvariate( mu, sigma)
正規分布です、mu は平均で、sigma は標準偏差です。

vonmisesvariate( mu, kappa)
mu は平均の角度で、0 から 2*pi までのラジアンで 表されます。kappa は濃度パラメタで、ゼロまたはそれ以上 でなければなりません。kappa がゼロに等しい場合、 この分布は範囲 0 から 2*pi の一様でランダムな角度の 分布に退化します。

paretovariate( alpha)
パレート分布です。alpha は形状パラメタです。

weibullvariate( alpha, beta)
ワイブル分布です。alpha はスケールパラメタで、 beta は形状パラメタです。

代替の乱数生成器

class WichmannHill( [seed])
乱数生成器として Wichmann-Hill アルゴリズムを実装するクラスです。 Random クラスと同じメソッド全てと、下で説明する whseed メソッドを持ちます。このクラスは、Python だけで実装されているので、スレ ッドセーフではなく、呼び出しと呼び出しの間にロックが必要です。また、周期 が 6,953,607,871,644 と短く、独立した2つの乱数列が重複しないように注意が 必要です。

whseed( [x])
これは obsolete で、バージョン 2.1 以前の Python と、ビット・レベルの互 換性のために提供されてます。詳細は seed を参照してください。 whseed は、引数に与えた整数が異なっても、内部状態が異なること を保障しません。取り得る内部状態の個数が 2**24 以下になる場合もあります。

参考資料:

M. Matsumoto and T. Nishimura, ``Mersenne Twister: A 623-dimensionally equidistributed uniform pseudorandom number generator'', ACM Transactions on Modeling and Computer Simulation Vol. 8, No. 1, January pp.3-30 1998.

Wichmann, B. A. & Hill, I. D., ``Algorithm AS 183: An efficient and portable pseudo-random number generator'', Applied Statistics 31 (1982) 188-190.

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.6 cmath Up: 5. 各種サービス Next: 5.8 whrandom


5.8 whrandom -- 擬似乱数生成器

リリース 2.1 以降で撤廃された仕様です。 random を代りに使ってください。

注意: Python 2.1 以前のリリースでは、このモジュールは random モジュールの実装における一部でした。 現在はもう使われていません。このモジュールを直接使わないで ください; 代わりに random を使ってください。 This module was an implementation detail of the

このモジュールは Wichmann-Hill による擬似乱数生成器クラスを実装します。 このクラスはまた、 whrandom と名づけられています。 whrandom クラスのインスタンスは 節で記述されている乱数生成器インタフェース (Random Number Generator インタフェース) に準拠しています。 このモジュールではまた、Wichmann-Hill アルゴリズムに特有の 以下のメソッドを提供しています:

seed( [x, y, z])
整数 x、y、z から乱数生成器を初期化します。 このモジュールが最初に取り込まれたときに、乱数は現在の時刻から 取り出された値で初期化されます。 x、y、および z が省略されるか 0 の場合、 乱数のシードは現在のシステム時刻から計算されます。引数のうち 3 つ全てではなく、1 または 2 個だけが 0 の場合、ゼロ に鳴っている値は 1 に置き換えられます。このことにより、一見して 異なるシード値が同じ値になってしまい、乱数生成器から生成される 擬似乱数列もこれに対応します。

choice( seq)
空でない配列 seq からランダムに要素を選んで返します。

randint( a, b)
a<=N<=b であるような整数の乱数 N を返します。

random( )
範囲 [0.0 ... 1.0) から次の浮動小数点数の乱数 N を返します。

seed( x, y, z)
整数 x、y、z から乱数生成器を初期化します。 このモジュールが最初にインポートされた際、乱数は現在の時刻から 取り出された値で初期化されます。

uniform( a, b)
a<=N<b であるようなランダムな実数 N を返します。

whrandom モジュールがインポートされた時、whrandom クラスのインスタンスも生成され、このインスタンスのメソッドを モジュールレベルで利用できるようにします。従って、 N = whrandom.random() を以下のコード:

generator = whrandom.whrandom()
N = generator.random()

のように書くこともできます。

乱数生成器の別々のインスタンスを使った場合、擬似乱数の配列 は独立になるので注意してください。

参考資料:

randomモジュール:
Generators for various random distributions and documentation for the Random Number Generator interface.

Wichmann, B. A. & Hill, I. D., ``Algorithm AS 183: An efficient and portable pseudo-random number generator'', Applied Statistics 31 (1982) 188-190.

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.7 random Up: 5. 各種サービス Next: 5.9 bisect


5.9 bisect -- 配列二分法アルゴリズム

このモジュールは、挿入の度にリストをソートすることなく、リストをソートされた 順序に保つことをサポートします。 大量の比較操作を伴うような、アイテムがたくさんあるリストでは、より一般的な アプローチに比べて、パフォーマンスが向上します。

動作に基本的な二分法アルゴリズムを使っているので、bisect と呼ばれています。 ソースコードはこのアルゴリズムの実例として一番役に立つかもしれません (境界条件はすでに正しいです!)。

次の関数が用意されています。

bisect_left( list, item[, lo[, hi]])

ソートされた順序を保ったまま item を list に挿入するのに適した 挿入点を探し当てます。 リストの中から検索する部分集合を指定するには、パラメーターの lo と hi を使います。 デフォルトでは、リスト全体が使われます。 item がすでに list に含まれている場合、挿入点はどのエントリー よりも前(左)になります。 戻り値は、list.inser() の第一引数として使うのに適しています。 list はすでにソートされているものとします。 バージョン2.1 以降で新規追加された 仕様です。

bisect_right( list, item[, lo[, hi]])
bisect_left() と似ていますが、list に含まれる item のうち、どのエントリーよりも後ろ(右)にくるような挿入点を返します。 バージョン2.1 以降で新規追加された 仕様です。 。

bisect( ...)
bisect_right() のエイリアス。

insort_left( list, item[, lo[, hi]])
item を list にソートされた順序で(ソートされたまま)挿入します。 これは、 list.insert(bisect.bisect_left(list, item, lo, hi), item) と同等です。 list はすでにソートされているものとします。 バージョン2.1 以降で新規追加された 仕様です。

insort_right( list, item[, lo[, hi]])
insort_left() と似ていますが、list に含まれる item のうち、どのエントリーよりも後ろに item を挿入します。 バージョン2.1 以降で新規追加された 仕様です。

insort( ...)
insort_right() のエイリアス。

  • 5.9.1 使用例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.8 whrandom Up: 5. 各種サービス Next: 5.9.1 使用例


5.9.1 使用例

一般には、bisect() 関数は数値データを分類するのに役に立ちます。 この例では、bisect() を使って、(たとえば)順序のついた数値の区切り点 の集合に基づいて、試験全体の成績の文字を調べます。 区切り点は 85 以上は `A'、 75..84 は `B'、などです。

>>> grades = "FEDCBA"
>>> breakpoints = [30, 44, 66, 75, 85]
>>> from bisect import bisect
>>> def grade(total):
...           return grades[bisect(breakpoints, total)]
...
>>> grade(66)
'C'
>>> map(grade, [33, 99, 77, 44, 12, 88])
['E', 'A', 'B', 'D', 'F', 'A']

bisect モジュールは Queue モジュールと一緒に使って、優先順序つき待ち行列を実装 することができます。 (Fredrik Lundh の好意による例です):

import Queue, bisect

class PriorityQueue(Queue.Queue):
    def _put(self, item):
        bisect.insort(self.queue, item)

# 使い方
queue = PriorityQueue(0)
queue.put((2, "second"))
queue.put((1, "first"))
queue.put((3, "third"))
priority, value = queue.get()
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.9 bisect Up: 5.9 bisect Next: 5.10 heapq


5.10 heapq -- ヒープキューアルゴリズム

バージョン2.3 以降で新規追加された 仕様です。

このモジュールではヒープキューアルゴリズムの一実装を提供しています。 優先度キューアルゴリズムとしても知られています。

ヒープとは、全ての k に対して、ゼロから要素を数えて いった際に、 heap[k] <= heap[2*k+1] かつ heap[k] <= heap[2*k+2] となる配列です。比較のために、存在しない要素は無限大として扱われます。 ヒープの興味深い属性は heap[0] が常に最小の要素に なることです。

以下の API は教科書におけるヒープアルゴリズムとは 2 つの側面で異なって います: (a) ゼロベースのインデクス化を行っています。これにより、 ノードに対するインデクスとその子ノードのインデクスの関係がやや明瞭で なくなりますが、Python はゼロベースのインデクス化を使っているので よりしっくりきます。(b) われわれの pop メソッドは最大の要素ではなく 最小の要素 (教科書では "min heap:最小ヒープ" と呼ばれています; 教科書では並べ替えをインプレースで行うのに適した "max heap:最大ヒープ" が一般的です)。

これらの 2 点によって、ユーザに戸惑いを与えることなく、ヒープを通常の Python リストとして見ることができます: heap[0] が最小の 要素となり、 heap.sort() はヒープを不変なままに保ちます!

ヒープを作成するには、[] に初期化されたリストを使うか、 heapify() を用いて要素の入ったリストを変換します。

以下の関数が提供されています:

heappush( heap, item)
item を heap に push します。ヒープを不変に保ちます。

heappop( heap)
pop を行い、heap から最初の要素を返します。ヒープは不変に 保たれます。ヒープが空の場合、IndexError が送出されます。

heapify( x)
リスト x をインプレース処理し、線形時間でヒープに変換します。

heapreplace( heap, item)
heap から最小の要素を pop して返し、新たに item を push します。ヒープのサイズは変更されません。 ヒープが空の場合、 IndexError が送出されます。 この関数は heappop() に次いで heappush() を送出するよりも効率的で、固定サイズのヒープを用いている場合には より適しています。返される値は item よりも大きくなるかも しれないので気をつけてください! これにより、このルーチンの合理的な 利用法が制限されています。

使用例を以下に示します:

>>> from heapq import heappush, heappop
>>> heap = []
>>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
>>> for item in data:
...     heappush(heap, item)
...
>>> sorted = []
>>> while heap:
...     sorted.append(heappop(heap))
...
>>> print sorted
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> data.sort()
>>> print data == sorted
True
>>>

  • 5.10.1 理論
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.9.1 使用例 Up: 5. 各種サービス Next: 5.10.1 理論


5.10.1 理論

(説明は Fran輟is Pinard によるものです。このモジュールの Python コード は Kevin O'Connor の貢献によるものです。)

ヒープとは、全ての k について、要素を 0 から数えたときに、 a[k] <= a[2*k+1] かつ a[k] <= a[2*k+2] となる配列です。 比較のために、存在しない要素を無限大と考えます。 ヒープの興味深い属性は heap[0] が常に最小の要素に なることです。

上記の奇妙な不変式は、勝ち抜き戦判定の際に効率的なメモリ表現を行う ためのものです。 以下の番号は a[k] ではなく k とします:

                                   0

                  1                                 2

          3               4                5               6

      7       8       9       10      11      12      13      14

    15 16   17 18   19 20   21 22   23 24   25 26   27 28   29 30

上の木構造では、各セル k は 2*k+1 および 2*k+2 を最大値としています。 スポーツに見られるような通常の 2 つ組勝ち抜き戦では、各セルはその 下にある二つのセルに対する勝者となっていて、個々のセルの勝者を 追跡していくことにより、そのセルに対する全ての相手を見ることが できます。しかしながら、このような勝ち抜き戦を使う計算機 アプリケーションの多くでは、勝歴を追跡する必要はりません。 メモリ効率をより高めるために、勝者が上位に進級した際、 下のレベルから持ってきて置き換えることにすると、あるセルと その下位にある二つのセルは異なる三つの要素を含み、かつ 上位のセルは二つの下位のセルに対して "勝者と" なります。

このヒープ不変式が常に守られれば、インデクス 0 は明らかに 最勝者となります。最勝者の要素を除去し、"次の" 勝者を見つける ための最も単純なアルゴリズム的手法は、ある敗者要素 (ここでは上図の セル 30 とします) を 0 の場所に持っていき、この新しい 0 を 濾過するようにしてツリーを下らせて値を交換してゆきます。不変関係が 再構築されるまでこれを続けます。この操作は明らかに、ツリー内の 全ての要素数に対して対数的な計算量となります。全ての要素について 繰り返すと、 O(n log n) のソート(並べ替え)になります。

このソートの良い点は、新たに挿入する要素が、その最に取り出す 0 番目の 要素よりも "良い値" でない限り、ソートを行っている最中に新たな要素を 効率的に追加できるというところです。

この性質は、シミュレーション的な状況で、ツリーで全ての入力 イベントを保持し、"勝者となる状況" を最小のスケジュール時刻にする ような場合に特に便利です。あるイベントが他のイベント群の実行を スケジュールする際、それらは未来にスケジュールされることになるので、 それらのイベント群を容易にヒープに積むことができます。 すなわち、ヒープはスケジューラを実装する上で良いデータ構造で あるといえます (私は MIDI シーケンサで使っているものです :-).

これまでスケジューラを実装するための様々なデータ構造が広範に 研究されています。ヒープは十分高速で、速度もおおむね一定であり、 最悪の場合でも平均的な速度とさほど変わらないため良いデータ構造と いえます。しかし、最悪の場合がひどい速度になることを除き、 たいていでより効率の高い他のデータ構造表現も存在します。

ヒープはまた、巨大なディスクのソートでも非常に有用です。 おそらくご存知のように、巨大なソートを行うと、複数の "ラン (run)" (予めソートされた配列で、そのサイズは通常 CPU メモリの量に関係 しています) が生成され、続いて統合処理 (merging) がこれらのランを 判定します。この統合処理はしばしば非常に巧妙に組織されています 5.2。 重要なのは、最初のソートが可能な限り長いランを生成することです。 勝ち抜き戦はこれを行うための良い方法です。もし利用可能な全ての メモリを使って勝ち抜き戦を行い、要素を置換および濾過処理して 現在のランに収めれば、ランダムな入力に対してメモリの二倍の サイズのランを生成することになり、大体順序づけがなされている入力に 対してはもっと高い効率になります。

さらに、ディスク上の 0 番目の要素を出力して、現在の勝ち抜き戦に (最後に出力した値に "勝って" しまうために) 収められない入力を得た なら、ヒープには収まらないため、ヒープのサイズは減少します。 解放されたメモリは二つ目のヒープを段階的に構築するために巧妙に再利用 することができ、この二つ目のヒープは最初のヒープが崩壊していく のと同じ速度で成長します。最初のヒープが完全に消滅したら、 ヒープを切り替えて新たなランを開始します。なんと巧妙で 効率的なのでしょう！

一言で言うと、ヒープは知って得するメモリ構造です。 私はいくつかのアプリケーションでヒープを使っていて、 `ヒープ' モジュールを常備するのはいい事だと考えています。 :-)

... 判定します。この統合処理はしばしば非常に巧妙に組織されています5.2
現在使われているディスクバランス化アルゴリズムは、最近は もはや巧妙というよりも目障りであり、このためにディスクに対するシーク 機能が重要になっています。巨大な容量を持つテープのようにシーク不能な デバイスでは、事情は全く異なり、個々のテープ上の移動が可能な限り 効率的に行われるように非常に巧妙な処理を (相当前もって) 行わねば なりません (すなわち、もっとも統合処理の "進行" に関係があります)。 テープによっては逆方向に読むことさえでき、巻き戻しに時間を取られる のを避けるために使うこともできます。正直、本当に良いテープソート は見ていて素晴らしく驚異的なものです！ソートというのは常に偉大な 芸術なのです！:-)
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.10 heapq Up: 5.10 heapq Next: 5.11 array


5.11 array -- 効率のよい数値配列

このモジュールは基本的な値(文字、整数、浮動小数点数)の配列を効率よく表現できる新しいオブジェクト型を定義します。配列はシーケンス型であり、格納されるオブジェクトの型に制限があることを除けば、リストとまったく同じように振る舞います。オブジェクト生成時に一文字の型コードを用いて型を指定します。次の型コードが定義されています:

型コード | Cの型 | Pythonの型 | 最小サイズ(バイト単位)
'c' | char | 文字(str型) | 1
'b' | signed char | int型 | 1
'B' | unsigned char | int型 | 1
'u' | Py_UNICODE | Unicode文字(unicode型) | 2
'h' | signed short | int型 | 2
'H' | unsigned short | int型 | 2
'i' | signed int | int型 | 2
'I' | unsigned int | long型 | 2
'l' | signed long | int型 | 4
'L' | unsigned long | long型 | 4
'f' | float | float型 | 4
'd' | double | float型 | 8

値の実際の表現はマシンアーキテクチャ(厳密に言うとCの実装)によって決まります。itemsize属性から実際のサイズが得られます。Pythonの通常の整数型ではCのunsigned (long)整数の最大範囲を表せないため、'L'と'I'要素として格納される値はPythonの長整数として表されます。

モジュールは次の型を定義します:

array( typecode[, initializer])
要素のデータ型がtypecodeに限定される新しい配列を返します。オプションの値initializerをわたすと初期値になりますが、リストまたは文字列でなければなりません。新しい配列に初期要素を追加するために、リストまたは文字列はその配列のfromlist()、fromstring()あるいはfromunicode()メソッド(以下を参照して下さい)へ渡されます。

ArrayType
もはや使われないarrayの別名。

配列オブジェクトは、添字付け、スライス、連結および反復といった通常のシーケンス演算をサポートします。スライス代入を使うとき、代入される値は同じ方コードの配列オブジェクトでなければなりません。他すべての場合には、TypeErrorが発生します。配列オブジェクトはバッファインターフェイスを実装しており、バッファオブジェクトがサポートされるところではどこでも使われます。

次のデータアイテムとメソッドもサポートされます:

typecode
配列を作るときに使われる型コード文字です。

itemsize
内部表現における1つの配列要素のバイト単位の長さです。

append( x)
値xをもつ新しい要素を配列の末尾に追加します。

buffer_info( )
配列の内容を保持するのに使われているバッファの現在のメモリアドレスと要素の長さを与えるタプル(address, length)を返します。array.buffer_info()[1] * array.itemsizeで、バイト単位のメモリバッファの大きさを計算できます。メモリアドレスを必要とする、例えばioctl()操作のような低レベルな(そして、本質的に危険な)I/Oインタフェースを使って作業する場合に、ときどき便利です。その配列が存在し、長さを変える演算が行われない限り、返される数は有効です。

注意: CあるいはC++で書かれたコードから配列オブジェクトを使う(この情報を効率的に使うたった一つの方法)ときは、配列オブジェクトがサポートするバッファインターフェイスを使う方がより理にかなっています。このメソッドは後方互換性のために保守されており、新しいコードでの使用は避けるべきです。バッファインターフェイスはPython/C APIリファレンスマニュアルで文書化されています。

byteswap( )
配列のすべての要素に対して``バイトスワップ''(リトルエンディアンとビッグエンディアンの変換)を行います。これは大きさが1、2、4および8バイトである値に対してのみサポートされます。値の他の型に対しては、RuntimeErrorが発生します。異なるバイトオーダーをもつマシンで書かれたファイルからデータを読み込むときに役に立ちます。

count( x)
配列中のxの出現回数を返す。

extend( a)
aから配列の末尾へ配列要素を追加します。二つの配列は全く同じ型コードを持っていなければなりません。そうでなければ、TypeErrorが発生します。

fromfile( f, n)
ファイルオブジェクトfから(マシン依存のデータ形式そのままで)n個の要素を読み込み、それらを配列の末尾に追加します。n個の要素を読めなかったときはEOFErrorが発生しますが、そのときでも利用可能な要素は配列に追加されます。fは実際の組み込みファイルオブジェクトでなければなりません。read()メソッドをもつ他のものは動作しないでしょう。

fromlist( list)
リストから要素を追加します。型エラーが発生した場合に配列が変更されないことを除いて、"for x in list: a.append(x)"と同等です。

fromstring( s)
文字列から要素を追加します。(まるでファイルからfromfile()メソッドを使って読み込んだかのように)マシン依存のデータの配列として文字列を解釈しています。

fromunicode( s)
与えられたユニコード文字列からのデータで、この配列を拡張します。配列は型'u'の配列でなければなりません。そうでなければ、ValueErrorが発生します。他の型の配列にユニコードデータを追加するには、"array.fromstring(ustr.decode(enc))"を使ってください。

index( x)
配列の中でxが初めて現れるインデックスである、もっとも小さいiを返します。

insert( i, x)
配列の位置iの前に値xをもつ新しい要素を挿入します。 iが負数の場合、配列の末尾からの相対位置として扱います。

pop( [i])
配列からインデックスiの要素を取り除き、それを返します。デフォルトで最後の要素を取り除いて返すようすするために、オプションの引数の既定値は-1です。

read( f, n)
リリース 1.5.1 以降で撤廃された仕様です。 fromfile()メソッドを使ってください。
ファイルオブジェクトfから(マシン依存のデータ形式そのままで)n個の要素を読み込んで、 それらを配列の末尾に追加します。n個より少ない要素しか読めなかった場合にはEOFErrorが発生しますが、そのときでも利用可能な要素は配列に追加されます。fは実際の組み込みファイルオブジェクトでなければなりません。read()をもつ他のものは動作しないでしょう。

remove( x)
配列から最初に現れるxを取り除きます。

reverse( )
配列の要素の順番を逆にします。

tofile( f)
ファイルオブジェクトfにすべての要素を(マシン依存のデータ形式そのままで)書き込みます。

tolist( )
配列を同じ要素を持つ普通のリストに変換します。

tostring( )
配列をマシン依存のデータの配列に変換し、文字列表現(tofile()メソッドによってファイルに書き込まれるものと同じバイトシーケンス)を返します。

tounicode( )
配列をユニコード文字列に変換します。配列は型'u'の配列でなければなりません。そうでないならば、ValueErrorが発生します。他の型の配列からユニコード文字列を得るには、array.tostring().decode(enc)を使ってください。

write( f)
リリース 1.5.1 以降で撤廃された仕様です。 tofile()メソッドを使ってください。
ファイルオブジェクトfに、全ての要素を(マシン依存のデータ形式そのままで)書き込みます。

配列オブジェクトが表示される、あるいは文字列に変換されるとき、array(typecode, initializer)というように表現されます。配列が空ならば、initializerは省略されます。そうではなくtypecodeが'c'ならば、それは文字列になります。さもなければ、数字のリストになります。array()関数がfrom array import arrayである限り、文字列は逆クォーテーション(``)を用いて同じデータ型と値を持つ配列に逆変換できることが保証されています。例:

array('l')
array('c', 'hello world')
array('u', u'hello \textbackslash u2641')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14])

参考資料:

structモジュール:
異なる種類のバイナリデータをパックおよびアンパックします。.
xdrlibモジュール:
遠隔手続き呼び出しシステムで使われるExternal Data Representation (XDR)データをパックおよびアンパックします。.
The Numerical Python Manual
Numeric Python拡張(NumPy)は、別の配列型を定義しています。Numerical Pythonについてのこれ以上の情報は、http://numpy.sourceforge.net/を参照してください。(NumPyマニュアルのPDFバージョンはhttp://numpy.sourceforge.net/numdoc/numdoc.pdfで手に入ります。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.10.1 理論 Up: 5. 各種サービス Next: 5.12 sets


5.12 sets -- ユニークな要素の順序なしコレクション

バージョン2.3 以降で新規追加された 仕様です。

setsモジュールは、ユニークな要素の順序なしコレクションを構築し、 操作するためのクラスを提供します。 帰属関係のテストやシーケンスから重複を取り除いたり、 積集合・和集合・差集合・対称差集合のような標準的な数学操作などを含みます。

他のコレクションのように、x in set, len(set), for x in setをサポートします。 順序なしコレクションは、挿入の順序や要素位置を記録しません。 従って、インデックス・スライス・他のシーケンス的な振舞いをサポートしません。

ほとんどの集合のアプリケーションは、__hash__()を除いて すべての集合のメソッドを提供するSetクラスを使用します。 ハッシュを要求する高度なアプリケーションについては、 ImmutableSetクラスが__hash__()メソッドを加えているが、 集合の内容を変更するメソッドは省略されます。 SetとImmutableSetは、 何が集合(isinstance(obj, BaseSet))であるか決めるのに役立つ 抽象クラスBaseSetから派生します。

集合クラスは辞書を使用して実装されます。 その結果、集合はリストや辞書のような変更可能な要素を含むことができません。 しかしそれらは、タプルやImmutableSetのインスタンスのような 不変コレクションを含むことができます。 集合の集合の実装中の便宜については、内部集合が自動的に変更不可能な形式に 変換されます。 例えば、Set([Set(['dog'])])はSet([ImmutableSet(['dog'])])へ 変換されます。

class Set( [iterable])
新しい空のSetオブジェクトを構築します。 もしオプションiterableが与えられたら、イタレータから得られた 要素を備えた集合として更新します。 iterable中の全ての要素は、変更不可能であるか、 または5.12.3で記述されたプロトコルを使って 変更不可能なものに変換可能であるべきです。

class ImmutableSet( [iterable])
新しい空のImmutableSetオブジェクトを構築します。 もしオプションiterableが与えられたら、イタレータから得られた 要素を備えた集合として更新します。 iterable中の全ての要素は、変更不可能であるか、 または5.12.3で記述されたプロトコルを使って 変更不可能なものに変換可能であるべきです。

ImmutableSetオブジェクトは__hash__()メソッドを備えているので、 集合要素または辞書キーとして使用することができます。 ImmutableSetオブジェクトは要素を加えたり取り除いたりするメソッドを 持っていません。したがって、コンストラクタが呼ばれたとき要素はすべて 知られていなければなりません。

  • 5.12.1 Set オブジェクト
  • 5.12.2 使用例
  • 5.12.3 不変に自動変換するためのプロトコル
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.11 array Up: 5. 各種サービス Next: 5.12.1 Set オブジェクト


5.12.1 Set オブジェクト

SetとImmutableSetのインスタンスはともに、 以下の操作を備えています:

演算 | 等価な演算 | 結果
len(s) |  | 集合sの濃度 (cardinality)
x in s |  | xがsに帰属しているかテストする
x not in s |  | xがsに帰属して否ないかテストする
s.issubset(t) | s <= t | sのすべての要素がtにあるかテストする
s.issuperset(t) | s >= t | tのすべての要素がsにあるかテストする
s.union(t) | s | t | sとtの両方の要素からなる新しい集合
s.intersection(t) | s & t | sとtで共通する要素からなる新しい集合
s.difference(t) | s - t | sにあるがtにない要素からなる新しい集合
s.symmetric_difference(t) | s ^ t | sとtのどちらか一方に属する要素からなる集合
s.copy() |  | sの浅いコピーからなる集合

演算子を使わない書き方である union()、 intersection()、 difference()、およびsymmetric_difference() は任意の イテレート可能オブジェクトを引数として受け取るのに対し、演算子を使った 書き方の方では引数は集合型でなければならないので注意してください。 これはエラーの元となるSet('abc') & 'cbs' のような書き方を 排除し、より可読性のあるSet('abc').intersection('cbs') を選ばせるための仕様です。 バージョン2.3.1 以降で変更された 仕様: 以前は全ての引数が集合型でなければなりませんでした。

加えて、SetとImmutableSet は集合間の比較をサポートしています。 二つの集合は、各々の集合のすべての要素が他方に含まれて (各々が他方の 部分集合) いる場合、かつその場合に限り等価になります。 ある集合は、他方の集合の真の部分集合 (proper subset、部分集合で あるが非等価) である場合、かつその場合に限り、他方の集合より小さくなります。 ある集合は、他方の集合の真の上位集合 (proper superset、上位集合で あるが非等価) である場合、かつその場合に限り、他方の集合より大きくなります。

部分集合比較やと等値比較では、完全な順序決定関数を一般化できません。 たとえば、互いに素な 2 つの集合は等しくありませんし、互いの部 分集合でもないので、a<b、 a==b、 a>b はすべて False を返します。 したがって集合は __cmp__ メソッドを実装しません。

集合は一部の順序（部分集合の関係）を定義するだけなので、集合のリストにおいて list.sort() メソッドの出力は未定義です。

以下はImmutableSetで利用可能であるがSetにはない操作です:

演算 | 結果
hash(s) | s のハッシュ値を返す

以下はSetで利用可能であるがImmutableSetにはない操作です:

演算 | 等価な演算 | 結果
s.union_update(t) | s |= t | tを加えた要素からなる集合sを返します
s.intersection_update(t) | s &= t | tでも見つかった要素だけを持つ集合sを返します
s.difference_update(t) | s -= t | tにあった要素を取り除いた後の集合sを返します
s.symmetric_difference_update(t) | s ^= t | sとtのどちらか一方に属する要素からなる集合 sを返します
s.add(x) |  | 要素xを集合sに加えます
s.remove(x) |  | 要素xを集合sから取り除きます; x がなければ KeyError を送出します
s.discard(x) |  | 要素xが存在すれば、集合sから取り除きます
s.pop() |  | sから要素を取り除き、それを返します; 集合が空なら KeyError を送出します
s.clear() |  | 集合sからすべての要素を取り除きます

演算子を使わない書き方である union_update()、 intersection_update()、difference_update()、 およびsymmetric_difference_update() は任意の イテレート可能オブジェクトを引数として受け取るので注意してください。 バージョン2.3.1 以降で変更された 仕様: 以前は全ての引数が集合型でなければなりませんでした。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.12 sets Up: 5.12 sets Next: 5.12.2 使用例


5.12.2 使用例

>>> from sets import Set
>>> engineers = Set(['John', 'Jane', 'Jack', 'Janice'])
>>> programmers = Set(['Jack', 'Sam', 'Susan', 'Janice'])
>>> managers = Set(['Jane', 'Jack', 'Susan', 'Zack'])
>>> employees = engineers | programmers | managers           # union
>>> engineering_management = engineers & managers            # intersection
>>> fulltime_management = managers - engineers - programmers # difference
>>> engineers.add('Marvin')                                  # add element
>>> print engineers
Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])
>>> employees.issuperset(engineers)           # superset test
False
>>> employees.union_update(engineers)         # update from another set
>>> employees.issuperset(engineers)
True
>>> for group in [engineers, programmers, managers, employees]:
...     group.discard('Susan')                # unconditionally remove element
...     print group
...
Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])
Set(['Janice', 'Jack', 'Sam'])
Set(['Jane', 'Zack', 'Jack'])
Set(['Jack', 'Sam', 'Jane', 'Marvin', 'Janice', 'John', 'Zack'])

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.12.1 Set オブジェクト Up: 5.12 sets Next: 5.12.3 不変に自動変換するためのプロトコル


5.12.3 不変に自動変換するためのプロトコル

集合は変更不可能な要素だけを含むことできます。 都合上、変更可能なSetオブジェクトは、集合要素として加えられる前に、 自動的にImmutableSetへコピーします。 そのメカニズムはハッシュ可能な要素を常に加えることですが、 もしハッシュ不可能な場合は、その要素は変更不可能な等価物を返す __as_immutable__()メソッドを持っているかどうかチェックされます。

Setオブジェクトは、ImmutableSetのインスタンスを返す __as_immutable()__メソッドを持っているので、集合の集合を構築 することが可能です。

集合内のメンバーであることをチェックするために、 要素をハッシュする必要がある__contains__()メソッドと remove()メソッドが、同様のメカニズムを必要としています。 これらのメソッドは要素がハッシュできるかチェックします。 もし出来なければ-__hash__(),__eq__(),__ne__() のための一時的なメソッドを備えたクラスによってラップされた要素を返すメソッド- __as_temporarily_immutable__()メソッドをチェックします。

代理メカニズムは、オリジナルの可変オブジェクトから分かれたコピーを 組み上げる手間を助けてくれます。

Setオブジェクトは、新しいクラス_TemporarilyImmutableSet によってラップされたSetオブジェクトを返す、 __as_temporarily_immutable__()メソッドを実装します。

ハッシュ可能を与えるための2つのメカニズムは通常ユーザーに見えません。 しかしながら、マルチスレッド環境下においては、 _TemporarilyImmutableSetによって一時的にラップされたものを 持っているスレッドがあるときに、もう一つのスレッドが集合を更新することで、 衝突を発生させることができます。 言いかえれば、変更可能な集合の集合はスレッドセーフではありません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.12.2 使用例 Up: 5.12 sets Next: 5.13 itertools


5.13 itertools -- 効率的なループ実行のためのイテレータ生成関数

バージョン2.3 以降で新規追加された 仕様です。

このモジュールではイテレータを構築する部品を実装しています。プログラム言 語HaskellとSMLからアイデアを得ていますが、Pythonに適した形に修正されてい ます。

このモジュールは、高速でメモリ効率に優れ、単独でも組み合わせても使用する ことのできるツールを標準化したものです。標準化により、多数の個人が、それ ぞれの好みと命名規約で、それぞれ少しだけ異なる実装を行う為に発生する可読 性と信頼性の問題を軽減する事ができます。

ここで定義したツールは簡単に組み合わせて使用することができるようになって おり、アプリケーション固有のツールを簡潔かつ効率的に作成する事ができます。

例えば、SMLの作表ツールtabulate(f)はf(0), f(1), ...のシー ケンスを作成します。このツールボックスではimap()と count()を用意しており、この二つを組み合わせて imap(f, count())とすれば同じ結果を得る事ができます。

同様に、operatorモジュールの高速な関数とも一緒に使用すること ができるようになっています。

他にこのモジュールに追加したい基本的な構築部品があれば、開発者に提案して ください。

イテレータを使用すると、Pythonで書いてもCで書いてもリストを使用した同じ 処理よりメモリ効率がよく、高速となります。これはデータをメモリ上に``在庫 ''しておくのではなく、必要に応じて作成する注文生産方式を採用しているため です。

イテレータによるパフォーマンス上のメリットは、要素の数が増えるにつれてよ り明確になります。一定以上の要素を持つリストでは、メモリキャッシュのパフ ォーマンスに対する影響が大きく、実行速度が低下します。

参考資料:

The Standard ML Basis Library, The Standard ML Basis Library.

Haskell, A Purely Functional Language, Definition of Haskell and the Standard Libraries.

  • 5.13.1 Itertool関数
  • 5.13.2 例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.12.3 不変に自動変換するためのプロトコル Up: 5. 各種サービス Next: 5.13.1 Itertool関数


5.13.1 Itertool関数

以下の関数は全て、イテレータを作成して返します。無限長のストリームのイテ レータを返す関数もあり、この場合にはストリームを中断するような関数かルー プ処理から使用しなければなりません。

chain( *iterables)
先頭のiterableの全要素を返し、次に2番目のiterableの全要素…と全 iterableの要素を返すイテレータを作成します。連続したシーケンスを、一つ のシーケンスとして扱う場合に使用します。この関数は以下のスクリプトと同 等です：

     def chain(*iterables):
         for it in iterables:
             for element in it:
                 yield element

count( [n])
nで始まる、連続した整数を返すイテレータを作成します。n を 指定しなかった場合、デフォルト値はゼロです。現在、 Pythonの長整数はサポートしていません。imap()で連続したデー タを生成する場合やizip()でシーケンスに番号を追加する場合な どに引数として使用することができます。この関数は以下のスクリプトと同等 です：

     def count(n=0):
         while True:
             yield n
             n += 1

count()はオーバーフローのチェックを行いません。このため、 sys.maxintを超えると負の値を返します。この動作は将来変更されま す。

cycle( iterable)
iterableから要素を取得し、同時にそのコピーを保存するイテレータを作成し ます。iterableの全要素を返すと、セーブされたコピーから要素を返し、これ を無限に繰り返します。この関数は以下のスクリプトと同等です：

     def cycle(iterable):
         saved = []
         for element in iterable:
             yield element
             saved.append(element)
         while saved:
             for element in saved:
                   yield element

cycleはこのツールキットの中で唯一、大きなメモリ領域を使用し ます。使用するメモリ量はiterableの大きさに依存します。

dropwhile( predicate, iterable)
predicateが真である限りは要素を無視し、その後は全ての要素を返すイテ レータを作成します。このイテレータは、predicateが真の間は全く要 素を返さないため、最初の要素を返すまでに長い時間がかかる場合がありま す。この関数は以下のスクリプトと同等です：

     def dropwhile(predicate, iterable):
         iterable = iter(iterable)
         for x in iterable:
             if not predicate(x):
                 yield x
                 break
         for x in iterable:
             yield x

ifilter( predicate, iterable)
predicateがTrueとなる要素だけを返すイテレータを作成します。 predicateがNoneの場合、値が真であるアイテムだけを返しま す。この関数は以下のスクリプトと同等です：

     def ifilter(predicate, iterable):
         if predicate is None:
             predicate = bool
         for x in iterable:
             if predicate(x):
                 yield x

ifilterfalse( predicate, iterable)
predicateがFalseとなる要素だけを返すイテレータを作成します。 predicateがNoneの場合、値が偽であるアイテムだけを返しま す。この関数は以下のスクリプトと同等です：

     def ifilterfalse(predicate, iterable):
         if predicate is None:
             predicate = bool
         for x in iterable:
             if not predicate(x):
                 yield x

imap( function, *iterables)
iterablesの要素を引数としてfuntionを呼び出すイテレータを作成します。 functionがNoneの場合、引数のタプルを返します。 map()と似ていますが、最短のiterableの末尾まで到達した後は Noneを補って処理を続行するのではなく、終了します。これは、 map()に無限長のイテレータを指定するのは多くの場合誤りですが (全出力が評価されてしまうため)、imap()の場合には一般的で役 に立つ方法であるためです。この関数は以下のスクリプトと同等です：

     def imap(function, *iterables):
         iterables = map(iter, iterables)
         while True:
             args = [i.next() for i in iterables]
             if function is None:
                 yield tuple(args)
             else:
                 yield function(*args)

islice( iterable, [start,] stop [, step])
iterableから要素を選択して返すイテレータを作成します。startが0以 外であれば、iterableの先頭要素はstartに達するまでスキップします。以 降、stepが1以下なら連続した要素を返し、1以上なら指定された値分の 要素をスキップします。stopがNoneであれば、無限に、もしく はiterableの全要素を返すまで値を返します。None以外ならイテレー タは指定された要素位置で停止します。通常のスライスと異なり、 start、stop、stepに負の値を指定する事はできません。 配列化されたデータから関連するデータを取得する場合（複数行からなるレ ポートで、三行ごとに名前が指定されている場合など）に使用します。この関 数は以下のスクリプトと同等です：
     def islice(iterable, *args):
         s = slice(*args)
         next, stop, step = s.start or 0, s.stop, s.step or 1
         for cnt, element in enumerate(iterable):
             if cnt < next:
                 continue
             if stop is not None and cnt >= stop:
                 break
             yield element
             next += step

izip( *iterables)
各iterableの要素をまとめるイテレータを作成します。zip()に似 ていますが、リストではなくイテレータを返します。複数のイテレート可能オ ブジェクトに対して、同じ繰り返し処理を同時に行う場合に使用します。この 関数は以下のスクリプトと同等です：

     def izip(*iterables):
         iterables = map(iter, iterables)
         while iterables:
             result = [i.next() for i in iterables]
             yield tuple(result)

バージョン2.3.1 以降で変更された 仕様: イテレート可能オブジェクトを指定しない場合、TypeError 例外を送出する代わりに長さゼロのイテレータを返します。

repeat( object[, times])
繰り返しobjectを返すイテレータを作成します。timesを指定し ない場合、無限に値を返し続けます。imap()で常に同じオブジェク トを関数の引数として指定する場合に使用します。また、izip() で作成するタプルの全要素に常に同じオブジェクトを指定する場合にも使用す ることもできます。この関数は以下のスクリプトと同等です：

     def repeat(object, times=None):
         if times is None:
             while True:
                 yield object
         else:
             for i in xrange(times):
                 yield object

starmap( function, iterable)
iterablesの要素を引数としてfuntionを呼び出すイテレータを作成します。 functionの引数が単一のiterableにタプルとして格納されている場合(``zip済 み'')、imap()の代わりに使用します。imap()と starmap()ではfunctionの呼び出し方法が異なり、 imap()はfunction(a,b)、starmap()では function(*c)のように呼び出します。この関数は以下のスクリプトと 同等です：

     def starmap(function, iterable):
         iterable = iter(iterable)
         while True:
             yield function(*iterable.next())

takewhile( predicate, iterable)
predicateが真である限りiterableから要素を返すイテレータを作成します。 この関数は以下のスクリプトと同等です：

     def takewhile(predicate, iterable):
         for x in iterable:
             x = iterable.next()
             if predicate(x):
                 yield x
             else:
                 break

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.13 itertools Up: 5.13 itertools Next: 5.13.2 例


5.13.2 例

以下に各ツールの一般的な使い方と、ツールの組み合わせの例を示します。

>>> amounts = [120.15, 764.05, 823.14]
>>> for checknum, amount in izip(count(1200), amounts):
...     print 'Check %d is for $%.2f' % (checknum, amount)
...
Check 1200 is for $120.15
Check 1201 is for $764.05
Check 1202 is for $823.14

>>> import operator
>>> for cube in imap(operator.pow, xrange(1,4), repeat(3)):
...    print cube
...
1
8
27

>>> reportlines = ['EuroPython', 'Roster', '', 'alex', '', 'laura',
                  '', 'martin', '', 'walter', '', 'samuele']
>>> for name in islice(reportlines, 3, None, 2):
...    print name.title()
...
Alex
Laura
Martin
Walter
Samuele

この節では、itertools を組み合わせてより強力な itertools を作り出す enumerate()とiteritems()の非常に効率的な実装はPython に含まれていますが、ここでは高レベルなツールを基本的な部品から作成する例 として取り上げています。

def take(n, seq):
    return list(islice(seq, n))

def enumerate(iterable):
    return izip(count(), iterable)

def tabulate(function):
    "Return function(0), function(1), ..."
    return imap(function, count())

def iteritems(mapping):
    return izip(mapping.iterkeys(), mapping.itervalues())

def nth(iterable, n):
    "Returns the nth item"
    return list(islice(iterable, n, n+1))

def all(seq, pred=bool):
    "Returns True if pred(x) is True for every element in the iterable"
    return False not in imap(pred, seq)

def any(seq, pred=bool):
    "Returns True if pred(x) is True at least one element in the iterable"
    return True in imap(pred, seq)

def no(seq, pred=bool):
    "Returns True if pred(x) is False for every element in the iterable"
    return True not in imap(pred, seq)

def quantify(seq, pred=bool):
    "Count how many times the predicate is True in the sequence"
    return sum(imap(pred, seq))

def padnone(seq):
    "Returns the sequence elements and then returns None indefinitely"
    return chain(seq, repeat(None))

def ncycles(seq, n):
    "Returns the sequence elements n times"
    return chain(*repeat(seq, n))

def dotproduct(vec1, vec2):
    return sum(imap(operator.mul, vec1, vec2))

def window(seq, n=2):
    "Returns a sliding window (of width n) over data from the iterable"
    "   s -> (s0,s1,...s[n-1]), (s1,s2,...,sn), ...                   "
    it = iter(seq)
    result = tuple(islice(it, n))
    if len(result) == n:
        yield result
    for elem in it:
        result = result[1:] + (elem,)
        yield result

def tee(iterable):
    "Return two independent iterators from a single iterable"
    def gen(next, data={}, cnt=[0]):
        dpop = data.pop
        for i in count():
            if i == cnt[0]:
                item = data[i] = next()
                cnt[0] += 1
            else:
                item = dpop(i)
            yield item
    next = iter(iterable).next
    return (gen(next), gen(next))
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.13.1 Itertool関数 Up: 5.13 itertools Next: 5.14 ConfigParser


5.14 ConfigParser -- 設定ファイルの構文解析器

このモジュールでは， ConfigParserクラスを定義しています。 ConfigParser クラスは，Microsoft Windows の INI ファイルに 見られるような構造をもつ，基礎的な設定ファイルを実装しています． このモジュールを使って，エンドユーザーが簡単にカスタマイズできるような Python プログラムを書くことができます。

警告: このライブラリでは、Windowsのレジストリ用に拡張された INI 文法はサポート していません。

設定ファイルは 1 つ以上のセクションからなり、セクションは "[section]" ヘッダとそれに続くRFC 822 形式の "name: value" エントリからなっています。 "name=value" という形式も使えます。 値の先頭にある空白文字は削除されるので注意してください． オプションの値には，同じセクションか DEFAULT セクションに ある値を参照するような書式化文字列を含めることができます． 初期化時や検索時に別のデフォルト値を与えることもできます． "#"か";" ではじまる行は無視され，コメントを書く ために利用できます。

例:

[My Section]
foodir: %(dir)s/whatever
dir=frob

この場合"%(dir)s"は変数"dir" (この場合は"frob")に展開さ れます。 参照の展開は必要に応じて実行されます。

デフォルト値は ConfigParserのコンストラクタに辞書として渡すことで設定できます。 追加の(他の値をオーバーライドする)デフォルト値はget()メソッドに 渡すことができます。

class RawConfigParser( [defaults])
基本的な設定オブジェクトです。 defaultsが与えられた場合、オブジェクト に固有のデフォルト値がその値で初期化されます。 このクラスは値の置換をサポートしません。 バージョン2.3 以降で新規追加された 仕様です。

class ConfigParser( [defaults])

RawConfigParserの派生クラスで値の置換を実装しており、 get()メソッドとitems()メソッドに省略可能な引数を追加し ています。 defaultsに含まれる値は"%()s"による値の置換に 適当なものである必要があります。 __name__は組み込みのデフォルト値で、セクション名が含まれるので defaultsで設定してもオーバーライドされます。

class SafeConfigParser( [defaults])

ConfigParserの派生クラスでより安全な値の置換を実装しています。 この実装のはより予測可能性が高くなっています。 新規に書くアプリケーションでは、古いバージョンのPythonと互換性を持たせる 必要がない限り、このバージョンを利用することが望ましいです。 バージョン2.3 以降で新規追加された 仕様です。

exception NoSectionError
指定したセクションが見つからなかった時に起きる例外です。

exception DuplicateSectionError

同じ名前をもつセクションが複数見つかった時や、すでに存在する セクション名に対して add_section() が呼び出された際に 起きる例外です。

exception NoOptionError
指定したオプションが指定したセクションに存在しなかった時に起きる例外です。

exception InterpolationError
文字列の置換中に問題が起きた時に発生する例外の基底クラスです。

exception InterpolationDepthError
InterpolationErrorの派生クラスで、文字列の置換回数が MAX_INTERPOLATION_DEPTHを越えたために完了しなかった場合に 発生する例外です。

exception InterpolationMissingOptionError
InterpolationErrorの派生クラスで、値が参照しているオプションが 見つからない場合に発生する例外です。

exception InterpolationSyntaxError
InterpolationErrorの派生クラスで、指定された構文で値を置換 することができなかった場合に発生する例外です。 バージョン2.3 以降で新規追加された 仕様です。

exception MissingSectionHeaderError
セクションヘッダを持たないファイルを構文解析しようとした時に起きる例外です。

exception ParsingError
ファイルの構文解析中にエラーが起きた場合に発生する例外です。

MAX_INTERPOLATION_DEPTH
rawが偽だった場合のget()による再帰的な文字列置換の繰り返 しの最大値です。ConfigParserクラスだけに関係します。

参考資料:

shlexモジュール:
Unix のシェルに似た，アプリケーションの設定ファイル 用フォーマットとして使えるもう一つの小型言語です． .

  • 5.14.1 RawConfigParser オブジェクト
  • 5.14.2 ConfigParser オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.13.2 例 Up: 5. 各種サービス Next: 5.14.1 RawConfigParser オブジェクト


5.14.1 RawConfigParser オブジェクト

RawConfigParserクラスのインスタンスは以下のメソッドを持ちます:

defaults( )
インスタンス全体で使われるデフォルト値の辞書を返します。

sections( )
利用可能なセクションのリストを返します。DEFAULTはこのリストに含まれ ません。

add_section( section)
sectionという名前のセクションをインスタンスに追加します。 同名のセク ションが存在した場合、DuplicateSectionErrorが発生 します。

has_section( section)
指定したセクションがコンフィグレーションファイルに存在するかを返します。 DEFAULTセクションは存在するとみなされません。

options( section)
sectionで指定したセクションで利用できるオプションのリストを返し ます。

has_option( section, option)
与えられたセクションが存在してかつオプションが与えられていれば1を返し、 そうでなければ 0 を返します。 バージョン1.6 以降で新規追加された 仕様です。

read( filenames)
ファイル名のリストを読んで解析します。 もしfilenamesが文字列かユニコード文字列なら、1つのファイル名として 扱われます。filenamesで指定されたファイルが開けない場合、そのファイ ルは無視されます。この挙動は設定ファイルが置かれる可能性のある場所(例えば、 カレントディレクトリ、ホームディレクトリ、システム全体の設定を行うディ レクトリ)を設定して、そこに存在する設定ファイルを読むことを想定して設計 されています。 設定ファイルが存在しなかった場合、ConfigParser のインスタンスは 空のデータセットを持ちます。初期値の設定ファイルを先に読み込んでおく 必要があるアプリケーションでは、readfp())を read()の前に呼び出すことでそのような動作を実現できます:

import ConfigParser, os

config = ConfigParser.ConfigParser()
config.readfp(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])

readfp( fp[, filename])
fpで与えられるファイルかファイルのようなオブジェクトを読み込んで構 文解析します(readline()メソッドだけを使います)。もし filenameが省略されてfpがname属性を持っていれば filenameの代わりに使われます。ファイル名の初期値は"<???>"です。

get( section, option)
sectionのoption変数を取得します。

getint( section, option)
sectionのoptionを整数として評価する関数です。

getfloat( section, option)
sectionのoptionを浮動小数点数として評価する関数です。

getboolean( section, option)
指定した section の option 値をブール値に型強制する 便宜メソッドです。option として受理できる値は、真 (True) としては "1"、 "yes"、 "true"、 "on" 、偽 (False) としては "0"、 "no"、 "false"、 "off" です。 これらの文字列値に対しては大文字小文字の区別をしません。 その他の値の場合には ValueError を送出します。

items( section)
与えられたsectionのそれぞれのオプションについて (name, value)ペアのリストを返します。

set( section, option, value)
与えられたセクションが存在していれば、オプションを指定された値に設定しま す。セクションが存在しなければNoSectionErrorが発生します。 バージョン1.6 以降で新規追加された 仕様です。

write( fileobject)
設定を文字列表現に変換してファイルオブジェクトに書き出します。この 文字列表現はread()で読み込むことができます。 バージョン1.6 以降で新規追加された 仕様です。

remove_option( section, option)
指定されたsectionから指定されたoptionを削除します。 セクションが存在しなければ、NoSectionError を起こします。 存在するオプションを削除した時は1、そうでない時は0を返します。 バージョン1.6 以降で新規追加された 仕様です。

remove_section( section)
指定されたsectionを設定から削除します。 もし指定されたセクションが存在すればTrue、そうでなければ Falseを返します。

optionxform( option)

入力ファイル中に見つかったオプション名か， クライアントコードから渡されたオプション名 option を， 内部で利用する形式に変換します。デフォルトではoptionを 全て小文字に変換した名前が返されます。サブルクラスではこの関数をオーバー ライドすることでこの振舞いを替えることができます。たとえば、このメソッ ドをstr()に設定することで大小文字の差を区別するように 変更することができます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.14 ConfigParser Up: 5.14 ConfigParser Next: 5.14.2 ConfigParser オブジェクト


5.14.2 ConfigParser オブジェクト

ConfigParserクラスはRawConfigParserのインターフェースを いくつかのメソッドについて拡張し、省略可能な引数を追加しています。

get( section, option[, raw[, vars]])
sectionのoption変数を取得します。 rawが真でない時には、全ての"%"置換は コンストラクタに渡されたデフォルト値か、vars が与えられていれば それを元にして展開されてから返されます。

items( section[, raw[, vars]])
指定したsection 内の各オプションに対して、 (name, value) のペアからなるリストを返します。 省略可能な引数はget()メソッドと同じ意味を持ちます。 バージョン2.3 以降で新規追加された 仕様です。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.14.1 RawConfigParser オブジェクト Up: 5.14 ConfigParser Next: 5.15 fileinput


5.15 fileinput -- 複数の入力ストリームをまたいだ行の繰り返し処理をサポートする。

このモジュールは標準入力やファイルの並びにまたがるループを素早く書くため のヘルパークラスと関数を提供しています。

典型的な使い方は以下の通りです:

import fileinput
for line in fileinput.input():
    process(line)

このプログラムはsys.argv[1:]に含まれる全てのファイルをまたいで繰 り返します。もし該当するものがなければ、sys.stdinがデフォルトとし て扱われます。ファイル名として'-'が与えられた場合も、 sys.stdinに置き換えられます。別のファイル名リストを使いたい時には、 input()の最初の引数にリストを与えます。単一ファイル名の文字列 も受け付けます。

全てのファイルはテキストモードでオープンされます。オープン中あるいは読み 込み中にI/Oエラーが発生した場合には、IOErrorが発生します。

sys.stdinが2回以上使われた場合は、2回目以降は行を返しません。 ただしインタラクティブに利用している時や明示的にリセット (sys.stdin.seek(0))を使う)を行った場合はその限りではありません。

空のファイルは開いた後すぐ閉じられます。 空のファイルはファイル名リストの最後にある場合にしか外部に影響を与えませ ん。

ファイルの最後が改行文字で終っていない場合には、最後に改行文字を追加して 返します。

以下の関数がこのモジュールの基本的なインタフェースです:

input( [files[, inplace[, backup]]])

FileInputクラスのインスタンスを作ります。生成されたインスタンス は、このモジュールの関数群が利用するグローバルな状態として利用されます。 この関数への引数はFileInputクラスのコンストラクタへ渡されます。

以下の関数はinput()関数によって作られたグローバルな状態を利用 します。アクティブな状態が無い場合には、RuntimeErrorが発生し ます。

filename( )

現在読み込み中のファイル名を返します。一行目が読み込まれる前は Noneを返します。

lineno( )
最後に読み込まれた行の、累積した行番号を返します。1行目が読み込まれる前 は0を返します。最後のファイルの最終行が読み込まれた後には、その 行の行番号を返します。

filelineno( )

現在のファイル中での行番号を返します。1行目が読み込まれる前は0を 返します。最後のファイルの最終行が読み込まれた後には、その 行のファイル中での行番号を返します。

isfirstline( )
最後に読み込まれた行がファイルの1行目ならTrue、そうでなければFalseを返します。

isstdin( )
最後に読み込まれた行がsys.stdinから読まれていればTrue、そうでなけ ればFalseを返します。

nextfile( )

現在のファイルを閉じます。次の繰り返しでは(存在すれば)次のファイルの最初 の行が読み込まれます。閉じたファイルの読み込まれなかった行は、累積の行 数にカウントされません。ファイル名は次のファイルの最初の行が読み込まれ るまで変更されません。最初の行の読み込みが行われるまでは、この関数は呼 び出されても何もしませんので、最初のファイルをスキップするために利用す ることはできません。最後のファイルの最終行が読み込まれた後にも、この関 数は呼び出されても何もしません。

close( )
シーケンスを閉じます。

このモジュールのシーケンスの振舞いを実装しているクラスの サブクラスを作ることもできます。

class FileInput( [files[, inplace[, backup]]])
FileInputクラスはモジュールの関数に対応するメソッド filename()、lineno()、fileline()、 isfirstline()、isstdin()、nextfile()、 close()を実装しています。それに加えて、次の入力行を返す readline()メソッドと、シーケンスの振舞 いの実装をしている__getitem__()メソッドがあります。 シーケンスはシーケンシャルに読み込むことしかできません。つまりランダムア クセスとreadline()を混在させることはできません。

その場で保存するオプション機能:

キーワード引数 inplace=1 が input()か FileInputクラスのコンストラクタに渡された場合には、 入力ファイルはバックアップファイルに移動され、標準出力が入力ファイルに設 定されます(バックアップファイルと同じ名前のファイルが既に存在していた 場合には、警告無しに置き替えられます)。 これによって入力ファイルをその場で書き替えるフィルタを書くことができます。 キーワード引数backup='.<拡張子>'も与えられていれば、バック アップファイルの拡張子を決めることができます。デフォルトでは '.bak'になっています。出力先のファイルが閉じられればバックアップ ファイルは消されます。その場で保存する機能は、標準入力を読み込んでいる間 は無効にされます。

警告: 現在の実装はMS-DOSの8+3ファイルシステムでは動作しません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.14.2 ConfigParser オブジェクト Up: 5. 各種サービス Next: 5.16 xreadlines


5.16 xreadlines -- ファイルの各行に対する効率のよい反復処理

バージョン2.1 以降で新規追加された 仕様です。

リリース 2.3 以降で撤廃された仕様です。 for line in file を代わりに使ってください。

このモジュールでは、あるファイル内の各行に対して効率的に反復を行える ような新たなオブジェクト型を定義します。xreadline オブジェクトは for 文や関数 filter() で必要とされるような、 0 から始まる単純かつ順序正しいインデクス付けを実装した配列型 です。

つまり、以下のコード

import xreadlines, sys

for line in xreadlines.xreadlines(sys.stdin):
    pass

は、

while 1:
    lines = sys.stdin.readlines(8*1024)
    if not lines: break
    for line in lines:
        pass

とだいたい同じ速度とメモリ消費になります。ただし前者は for 文のままなのでより明快です。

xreadlines( fileobj)
fileobj の内容にわたって反復を行うような、新しい xreadlines オブジェクトを返します。fileobj は、引数 sizehint を サポートする readlines() メソッドを持っていなければなりません。 注意: readlines() メソッドばデータをバッファするので、ファイル オブジェクトを非バッファリングに設定しても無視されます。

xreadlines オブジェクト s は以下の配列操作をサポートします:

操作 | 結果
s[i] | s の i 行目

i の値が 0 から始まる連続した数でない場合、 このコードは 例外RuntimeError を送出します。

ファイルの最後の行が読み出された後、このコードは例外 IndexError を送出します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.15 fileinput Up: 5. 各種サービス Next: 5.17 calendar


5.17 calendar -- 一般的なカレンダーに関する関数群

このモジュールはUnixのcalプログラムのようなカレンダー出力を 行い、それに加えてカレンダーに関する有益な関数群を提供します。標準ではこ れらのカレンダーは（ヨーロッパの慣例に従って）月曜日を週の始まりとし、日 曜日を最後の日としています。 setfirstweekday()を用いることで、日曜日(6)や他の曜日を週の始 まりに設定することができます。日付を表す引数は整数値で与えます。

このモジュールで提供する関数のほとんどは datetime に依存しており、 過去も未来も現代のグレゴリオ暦を利用します。この方式はDershowitzとReingold の書籍「Calendrical Calculations」にあるproleptic Gregorian暦に一致しており、 同書では全ての計算の基礎となる暦としています。

setfirstweekday( weekday)
週の最初の曜日(0は月曜日, 6は日曜日)を設定します。定数 MONDAY, TUESDAY, WEDNESDAY,THURSDAY, FRIDAY, SATURDAY及びSUNDAY は便宜上提供されています。 例えば、日曜日を週の開始日に設定するとき:

import calendar
calendar.setfirstweekday(calendar.SUNDAY)
バージョン2.0 以降で新規追加された 仕様です。

firstweekday( )
現在設定されている週の最初の曜日を返します。 バージョン2.0 以降で新規追加された 仕様です。

isleap( year)
yearが閏年なら1を、そうでなければ0を返します。

leapdays( y1, y2)
範囲(y1...y2)指定された期間の閏年の回数を返します。 ここでy1やy2は年を表します。 バージョン2.0 以降で変更された 仕様: Python 1.5.2では、この関数は世紀をまたがった範囲では動作 しません。

weekday( year, month, day)
year(1970-...), month (1-12), day(1-31)で与えられた日の曜日(0は月曜日)を 返します。

monthrange( year, month)
yearとmonthで指定された月の一日の曜日と日数を返します。

monthcalendar( year, month)
月のカレンダーを行列で返します。各行が週を表し、月の範囲外の日は0になり ます。 それぞれの週はsetfirstweekday()で設定をしていない限り月曜日か ら始まります。

prmonth( theyear, themonth[, w[, l]])
month()関数によって返される月のカレンダーを出力します。

month( theyear, themonth[, w[, l]])
月のカレンダーを複数行の文字列で返します。wにより日の列幅を変える ことができ、それらはセンタリングされます。lにより各週の表示される 行数を変えることができます。週の最初の曜日は setfirstweekday()関数の設定に依存します。 バージョン2.0 以降で新規追加された 仕様です。

prcal( year[, w[, l[c]]])
calendar()関数で返される一年間のカレンダーを出力します。

calendar( year[, w[, l[c]]])
3列からなる一年間のカレンダーを複数行の文字列で返します。任意の引数 w,l, 及びcはそれぞれ、日付列の表示幅、各週の行数及び 月と月の間のスペースの数を変更するためのものです。週の最初の曜日は setfirstweekday()関数の設定に依存します。出力されるカレンダー の起点となる年はプラットフォームに依存します。 バージョン2.0 以降で新規追加された 仕様です。

timegm( tuple)
関連はありませんが便利な関数で、timeモジュールの gmtime()関数の戻値のような時間のタプルを受け取り、 1970年を 起点とし、POSIX規格のエンコードによるUnixのタイムスタンプに相当する 値を返します。実際、time.gmtime()とtimegm()は反対 の動作をします。 バージョン2.0 以降で新規追加された 仕様です。

参考資料:

timeモジュール:
低レベルの時間に関連した関数群。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.16 xreadlines Up: 5. 各種サービス Next: 5.18 cmd


5.18 cmd -- 行指向のコマンドインタープリタのサポート

Cmdクラスでは、行指向のコマンドインタープリタを書くための簡単なフレームワークを提供します。テスト用の仕掛けや管理ツール、そして、後により洗練されたインターフェイスでラップするプロトタイプとして、こうしたインタープリタはよく役に立ちます。

class Cmd( [completekey],[stdin],[stdout])
Cmdインスタンス、あるいはサブクラスのインスタンスは、行指向のインタープリタ・フレームワークです。Cmd自身をインスタンス化することはありません。むしろ、Cmdのメソッドを継承したり、 アクションメソッドをカプセル化するために、あなたが自分で定義するインタープリタクラスのスーパークラスとしての便利です。

オプション引数 completekey は、補完キーのreadline名です。デフォルトはTabです。completekeyがNoneでなく、readlineが利用できるならば、コマンド補完は自動的に行われます。

! The optional arguments stdin and stdout specify the ! input and output file objects that the Cmd instance or subclass ! instance will use for input and output. If not specified, they ! will default to sys.stdin and sys.stdout. ! オプション引数 stdinとstdoutには、Cmd インスタンス又はサブクラスのインスタンスが入出力に使用するファイルオブジェクトを指定します。省略時にはsys.stdin と sys.stdout を使用します。

バージョン2.3 以降で変更された 仕様: 引数 stdin と stdout を追加

  • 5.18.1 Cmdオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.17 calendar Up: 5. 各種サービス Next: 5.18.1 Cmdオブジェクト


5.18.1 Cmdオブジェクト

Cmdインスタンスは、次のメソッドを持ちます:

cmdloop( [intro])
プロンプトを繰り返し出し、入力を受け取り、受け取った入力から取り去った先頭の語を解析し、その行の残りを引数としてアクションメソッドへディスパッチします。

オプションの引数は、最初のプロンプトの前に表示されるバナーあるいは紹介用の文字列です(これはクラスメンバintroをオーバーライドします)。

readlineモジュールがロードされているなら、入力は自動的にbashのような履歴リスト編集機能を受け継ぎます(例えば、Control-Pは直前のコマンドへのスクロールバック、Control-Nは次のものへ進む、Control-Fはカーソルを右へ非破壊的に進める、Control-Bはカーソルを非破壊的に左へ移動させる等)。

入力のファイル終端は、文字列'EOF'として渡されます。

メソッドdo_foo()を持っている場合に限って、インタープリタのインスタンスはコマンド名"foo"を認識します。特別な場合として、文字"?"で始まる行はメソッドdo_help()へディスパッチします。他の特別な場合として、文字"!"で始まる行はメソッドdo_shell()へディスパッチします(このようなメソッドが定義されている場合)。

補完が有効になっているなら、コマンドの補完が自動的に行われます。また、コマンド引数の補完は、引数text、line、begidx、およびendidxと共にcomplete_foo()を呼び出すことによって行われます。textは、我々がマッチしようとしている文字列の先頭の語です。返されるマッチは全てそれで始まっていなければなりません。lineは始めの空白を除いた現在の入力行です。begidxとendidxは先頭のテキストの始まりと終わりのインデックスで、引数の位置に依存した異なる補完を提供するのに使えます。

Cmdのすべてのサブクラスは、定義済みのdo_help()を継承します。このメソッドは、(引数'bar'と共に呼ばれたとすると)対応するメソッドhelp_bar()を呼び出します。引数がなければ、do_help()は、すべての利用可能なヘルプ見出し(すなわち、対応するhelp_*()メソッドを持つすべてのコマンド)をリストアップします。また、文書化されていないコマンドでも、すべてリストアップします。

onecmd( str)
プロンプトに答えてタイプしたかのように引数を解釈実行します。これをオーバーライドすることがあるかもしれませんが、通常は必要ないでしょう。便利な実行フックについては、precmd()とpostcmd()メソッドを参照してください。戻り値は、インタープリタによるコマンドの解釈実行をやめるかどうかを示すフラグです。

emptyline( )
プロンプトに空行が入力されたときに呼び出されるメソッド。このメソッドがオーバーライドされていないなら、最後に入力された空行でないコマンドが繰り返されます。

default( line)
コマンドの先頭の語が認識されないときに、入力行に対して呼び出されます。このメソッドがオーバーライドされていないなら、エラーメッセージを表示して戻ります。

completedefault( text, line, begidx, endidx)
利用可能なコマンド固有のcomplete_*()が存在しないときに、入力行を補完するために呼び出されるメソッド。デフォルトでは、空行を返します。

precmd( line)
コマンド行lineが解釈実行される直前、しかし入力プロンプトが作られ表示された後に実行されるフックメソッド。このメソッドはCmd内のスタブであって、サブクラスでオーバーライドされるために存在します。戻り値はonecmd()メソッドが実行するコマンドとして使われます。precmd()の実装では、コマンドを書き換えるかもしれないし、あるいは単に変更していないlineを返すかもしれません。

postcmd( stop, line)
コマンドディスパッチが終わった直後に実行されるフックメソッド。このメソッドはCmd内のスタブで、サブクラスでオーバーライドされるために存在します。lineは実行されたコマンド行で、stopはpostcmd()の呼び出しの後に実行を停止するかどうかを示すフラグです。これはonecmd()メソッドの戻り値です。このメソッドの戻り値は、stopに対応する内部フラグの新しい値として使われます。偽を返すと、実行を続けます。

preloop( )
cmdloop()が呼び出されたときに一度だけ実行されるフックメソッド。このメソッドはCmd内のスタブであって、サブクラスでオーバーライドされるために存在します。

postloop( )
cmdloop()が戻る直前に一度だけ実行されるフックメソッド。このメソッドはCmd内のスタブであって、サブクラスでオーバーライドされるために存在します。

Cmdのサブクラスのインスタンスは、公開されたインスタンス変数をいくつか持っています:

prompt
入力を求めるために表示されるプロンプト。

identchars
コマンドの先頭の語として受け入れられる文字の文字列。

lastcmd
最後の空でないコマンドプリフィックス。

intro
紹介またはバナーとして表示される文字列。cmdloop()メソッドに引数を与えるために、オーバーライドされるかもしれません。

doc_header
ヘルプの出力に文書化されたコマンドの部分がある場合に表示するヘッダ。

misc_header
ヘルプの出力にその他のヘルプ見出しがある(すなわち、do_*()メソッドに対応していないhelp_*()メソッドが存在する)場合に表示するヘッダ。

undoc_header
ヘルプの出力に文書化されていないコマンドの部分がある(すなわち、対応するhelp_*()メソッドを持たないdo_*()メソッドが存在する)場合に表示するヘッダ。

ruler
ヘルプメッセージのヘッダの下に、区切り行を表示するために使われる文字。空のときは、ルーラ行が表示されません。デフォルトでは、"="です。

use_rawinput
フラグ、デフォルトでは真。真ならば、cmdloop()はプロンプトを表示して次のコマンド読み込むためにraw_input()を使います。偽ならば、sys.stdout.write()とsys.stdin.readline()が使われます。(これが意味するのは、readlineをimportすることによって、それをサポートするシステム上では、インタープリタが自動的にEmacs形式の行編集とコマンド履歴のキーストロークをサポートするということです。)

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.18 cmd Up: 5.18 cmd Next: 5.19 shlex


5.19 shlex -- 単純な字句解析

バージョン1.5.2 以降で新規追加された 仕様です。

shlex クラスは Unix シェルを思わせる単純な構文に 対する字句解析器を簡単に書けるようにします。このクラスはしばしば、 Python アプリケーションのための実行制御ファイルのような、 小規模言語を書く上で便利です。

参考資料:

ConfigParserモジュール:
Windows .ini ファイルに似た設定ファイルのパーザ。.

  • 5.19.1 モジュールの内容
  • 5.19.2 shlex オブジェクト
  • 5.19.3 解析規則
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.18.1 Cmdオブジェクト Up: 5. 各種サービス Next: 5.19.1 モジュールの内容


5.19.1 モジュールの内容

shlex モジュールは以下の関数を定義します。

split( s[, comments=False])
シェル類似の文法を使って、文字列 s を分割します。comments が False の場合、受理した文字列内のコメントを解析しません (shlex インスタンスの commenters メンバの値を空文字列に します)。 この関数は POSIX モードで動作します。 バージョン2.3 以降で新規追加された 仕様です。

shlex モジュールは以下のクラスを定義します。

class shlex( [instream=sys.stdin[, infile=None[, posix=False]]])
shlex クラスとサブクラスのインスタンスは、字句解析器オブジェクトです。 初期化引数を与えると、どこから文字を読み込むかを指定できます。指定先は read() メソッドと readline() メソッドを持つファイル/ス トリーム類似オブジェクトか、文字列でなくてはいけません（文字列が受理され るようになったのは Python 2.3 以降）。引数が与えられなければ、 sys.stdin から入力を受け付けます。第 2 引数は、ファイル名を表す文 字列で、 infile メンバの値の初期値を決定します。instream 引数が省略された場合や、この値が sys.stdin である場合、第2引数の デフォルト値は ``stdin'' になります。posix 引数は Python 2.3 で導 入されました。これは動作モードを定義します。posix が真でない場合 （デフォルト）、shlex インスタンスは互換モードで動作します。 POSIX モードで動作中、shlex は、できる限り POSIX シェルの 解析規則に似せようとします。 5.19.2 を参照のこと。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.19 shlex Up: 5.19 shlex Next: 5.19.2 shlex オブジェクト


5.19.2 shlex オブジェクト

shlex インスタンスは以下のメソッドを持っています:

get_token( )
トークンを一つ返します。トークンが push_token() で 使ってスタックに積まれていた場合、トークンをスタックからポップ します。そうでない場合、トークンを一つ入力ストリームから読み出します。 読み出し即時にファイル終了子に遭遇した場合、self.eof (非 POSIX モードでは空文字列 ('')、POSIX モードでは None) が返されます。

push_token( str)
トークンスタックに引数文字列をスタックします。

read_token( )
生 (raw) のトークンを読み出します。プッシュバックスタックを無視し、 かつソースリクエストを解釈しません (通常これは便利なエントリポイント ではありません。完全性のためにここで記述されています)。

sourcehook( filename)
shlex がソースリクエスト (下の source を参照して ください) を検出した際、このメソッドはその後に続くトークンを 引数として渡され、ファイル名と開かれたファイル類似オブジェクトからなる タプルを返すとされています。

通常、このメソッドはまず引数から何らかのクオートを剥ぎ取ります。 処理後の引数が絶対パス名であった場合か、以前に有効になったソースリクエスト が存在しない場合か、以前のソースが (sys.stdin のような) ストリームであった場合、この結果はそのままにされます。そうでない 場合で、処理後の引数が相対パス名の場合、ソースインクルードスタックに ある直前のファイル名からディレクトリ部分が取り出され、相対パスの 前の部分に追加されます (この動作は C 言語プリプロセッサにおける #include "file.h" の扱いと同様です) 。

これらの操作の結果はファイル名として扱われ、タプルの最初の要素 として返されます。同時にこのファイル名で open() を呼び出した 結果が二つ目の要素になります (注意: インスタンス初期化のときとは 引数の並びが逆になっています！)

このフックはディレクトリサーチパスや、ファイル拡張子の追加、その他の 名前空間に関するハックを実装できるようにするために公開されています。 `close' フックに対応するものはありませんが、shlex インスタンスは ソースリクエストされている入力ストリームが EOF を返した時には close() を呼び出します。

ソーススタックをより明示的に操作するには、push_source() および pop_source() メソッドを使ってください。

push_source( stream[, filename])
入力ソースストリームを入力スタックにプッシュします。ファイル名 引数が指定された場合、以後のエラーメッセージ中で利用することが できます。sourcehook メソッドが内部で使用しているのと 同じメソッドです。 バージョン2.1 以降で新規追加された 仕様です。

pop_source( )
最後にプッシュされた入力ソースを入力スタックからポップします。 字句解析器がスタック上の入力ストリームの EOF に到達した際に 利用するメソッドと同じです。 バージョン2.1 以降で新規追加された 仕様です。

error_leader( [file[, line]])
このメソッドはエラーメッセージの論述部分を Unix C コンパイラ エラーラベルの形式で生成します; この書式は '"%s", line %d: ' で、"%s" は現在のソースファイル名 で置き換えられ、"%d" は現在の入力行番号で置き換えられます (オプションの引数を使ってこれらを上書きすることもできます)。

このやり方は、shlex のユーザに対して、Emacs やその他の Unix ツール群が解釈できる一般的な書式でのメッセージを生成する ことを推奨するために提供されています。

shlex サブクラスのインスタンスは、字句解析を制御したり、 デバッグに使えるような public なインスタンス変数を持っています:

commenters
コメントの開始として認識される文字列です。コメントの開始から行末 までのすべてのキャラクタ文字は無視されます。 標準では単に "#" が入っています。

wordchars
複数文字からなるトークンを構成するためにバッファに蓄積していく ような文字からなる文字列です。標準では、全ての ASCII 英数字 およびアンダースコアが入っています。

whitespace
空白と見なされ、読み飛ばされる文字群です。空白はトークンの境界を 作ります。標準では、スペース、タブ、改行 (linefeed) および 復帰 (carriage-return) が入っています。

escape
エスケープ文字と見なされる文字群です。これは POSIX モードでのみ使われ、デフォルトでは "\" だけが入っています。 バージョン2.3 以降で新規追加された 仕様です。

quotes
文字列引用符と見なされる文字群です。トークンを構成する際、 同じクオートが再び出現するまで文字をバッファに蓄積します (すなわち、異なるクオート形式はシェル中で互いに保護し合う 関係にあります)。標準では、ASCII 単引用符および二重引用符 が入っています。

escapedquotes
quotes のうち、escape で定義されたエスケープ文字を解釈 する文字群です。これは POSIX モードでのみ使われ、デフォルトでは """ だけが入っています。 バージョン2.3 以降で新規追加された 仕様です。

whitespace_split
この値が True であれば、トークンは空白文字でのみで分割されます。たとえば shlex がシェル引数と同じ方法で、コマンドラインを解析するのに便利です。 バージョン2.3 以降で新規追加された 仕様です。

infile
現在の入力ファイル名です。クラスのインスタンス化時に初期設定 されるか、その後のソースリクエストでスタックされます。 エラーメッセージを構成する際にこの値を調べると便利なことがあります。

instream
shlex インスタンスが文字を読み出している入力ストリームです。

source
このメンバ変数は標準で None を取ります。この値に文字列を 代入すると、その文字列は多くのシェルにおける "source" キーワード に似た、字句解析レベルでのインクルード要求として認識されます。すなわち、 その直後に現れるトークンをファイル名として新たなストリームを開き、 そのストリームを入力として、EOF に到達するまで読み込まれます。 新たなストリームの EOF に到達した時点で close() が呼び出され、 入力は元の入力ストリームに戻されます。ソースリクエストは任意のレベル の深さまでスタックしてかまいません。

debug
このメンバ変数が数値で、かつ1 またはそれ以上の値の場合、 shlex インスタンスは動作に関する冗長な進捗報告を出力 します。この出力を使いたいなら、モジュールのソースコードを読めば 詳細を学ぶことができます。

lineno
ソース行番号 (遭遇した改行の数に 1 を加えたもの) です。

token
トークンバッファです。例外を捕捉した際にこの値を調べると便利なことが あります。

eof
ファイルの終端を決定するのに使われるトークンです。非 POSIX モードでは 空文字列 ('') 、POSIX モードでは None が入ります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.19.1 モジュールの内容 Up: 5.19 shlex Next: 5.19.3 解析規則


5.19.3 解析規則

非 POSIX モードで動作中の shlex は以下の規則に従おうとします。

  • ワード内の引用符を認識しない (Do"Not"Separate は単一ワード Do"Not"Separate として解析されます)
  • エスケープ文字を認識しない
  • 引用符で囲まれた文字列は、引用符内の全ての文字リテラルを保持する
  • 閉じ引用符でワードを区切る ("Do"Separate は、"Do" と Separate であると解析されます)
  • whitespace_split が False の場合、wordchar、 whitespace または quote として宣言されていない全ての文字を、単一の 文字トークンとして返す。True の場合、shlex は空白文 字でのみ単語を区切る。
  • 空文字列 ('') で EOF を送出する
  • 引用符に囲んであっても、空文字列を解析しない

POSIX モードで動作中の shlex は以下の解析規則に従おうとします。

  • 引用符を取り除き、引用符で単語を分解しない ("Do"Not"Separate" は単一ワード DoNotSeparate として解析されます)
  • 引用符で囲まれないエスケープ文字群 ("\" など) は直後に続く文字のリテラル値を保持する
  • escapedquotes でない引用符文字 ("'" など) で囲 まれている全ての文字のリテラル値を保持する
  • 引用符に囲まれた escapedquotes に含まれる文字 (""" など) は、escape に含まれる文字を除き、 全ての文字のリテラル値を保持する。エスケープ文字群は使用中の引用符、 または、そのエスケープ文字自身が直後にある場合のみ、特殊な機能を保 持する。他の場合にはエスケープ文字は普通の文字とみなされる。
  • None で EOF を送出する
  • 引用符に囲まれた空文字列 ('') を許す

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.19.2 shlex オブジェクト Up: 5.19 shlex Next: 6. 汎用オペレーティングシステムサービス


6. 汎用オペレーティングシステムサービス

本章に記述されたモジュールは、ファイルの取り扱いや時間計測のような(ほ ぼ)すべてのオペレーティングシステムで利用可能な機能にインターフェー スを提供します。これらのインターフェースは、UnixもしくはCのインター フェースを基に作られますが、ほとんどの他のシステムで同様に利用可能です。 概要を以下に記述します。

os | 雑多なオペレーティングシステムインタフェース。
os.path | 共通のパス名操作。
dircache | キャッシュメカニズムを備えたディレクトリ一覧生成。
stat | os.stat()、os.lstat() および os.fstat() の返す内容を解釈するためのユーティリティ群。
statcache | ファイルの stat を調べ、その結果を記憶します。
statvfs | os.statvfs() の返す値を解釈するために使われる定数群。
filecmp | ファイル群を効率的に比較します。
popen2 | アクセス可能な I/O ストリームを持つ子プロセス生成。
datetime | 基本的な日付型および時間型。
time | 時刻データへのアクセスと変換
sched | 一般的な目的のためのイベントスケジューラ
mutex | 排他制御のためのロックとキュー
getpass | ポータブルなパスワードとユーザーIDの検索
curses | 可搬性のある端末操作を提供する curses ライブラリへの インタフェース．
curses.textpad | curses ウィンドウ内での Emacs ライクな入力編集機能。
curses.wrapper | curses プログラムのための端末設定ラッパ。
curses.ascii | ASCII 文字に関する定数および集合帰属関数。
curses.panel | curses ウィンドウに深さの概念を追加するパネルスタック拡張。
getopt | ポータブルなコマンドラインオプションのパーザ。長短の両方 の形式をサポートします。
optparse | 強力で柔軟、拡張性があり簡単に利用できるコマンドライン解析ライブラリ
tempfile | 一時的なファイルやディレクトリを生成。
errno | 標準の errno システムシンボル。
glob | Unix シェル形式のパス名のパターン展開。
fnmatch | Unix シェル形式のファイル名のパターンマッチ。
shutil | コピーを含む高レベルなファイル操作。
locale | 国際化サービス。
gettext | 多言語対応に関する国際化サービス。
logging | PEP 282 に基づくPython 用のロギングモジュール。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 5.19.3 解析規則 Up: Python ライブラリリファレンス Next: 6.1 os


6.1 os -- 雑多なオペレーティングシステムインタフェース

このモジュールでは、オペレーティングシステム依存の機能を利用する方法 として、posix や nt といったオペレーティング システム依存の組み込みモジュールを import するよりも可搬性の高い 手段を提供しています。

このモジュールは、mac や posix のような、 オペレーティングシステム依存の組み込みモジュールから関数やデータを 検索して、見つかったものを取り出し (export) ます。Python における 組み込みのオペレーティングシステム依存モジュールは、同じ機能を 利用することができる限り、同じインタフェースを使います; たとえば、 os.stat(path) は path についての stat 情報を (たまたま POSIX インタフェースに起源する) 同じ書式で返します。

特定のオペレーティングシステム固有の拡張も os を介して 利用することができますが、これらの利用はもちろん、可搬性を脅かします！

最初の os の import 以後、os を介した関数の 利用は、オペレーティングシステム依存組み込みモジュールにおける関数の 直接利用に比べてパフォーマンス上のペナルティは 全くありません。 従って、osを利用しない理由は 存在しません !

os モジュールには多くの関数とデータ値が入っています。 以下の項目と、その後に続くサブセクションは os モジュールから 直接利用できます。

exception error
関数がシステム関連のエラー(引数の型違いや他のありがちなエラーではない) を返した場合この例外が発生します。これは OSError とし て知られる組み込み例外でもあります。付属する値は errno から とった数値のエラーコードと、エラーコードに対応する、C 関数 perror() により出力されるのと同じ文字列からなるペアです。 背後のオペレーティングシステムで定義されているエラーコード名が収め られている errnoを参照してください。

例外がクラスの場合、この例外は二つの属性、errno と strerror を持ちます。前者の属性は C の errno 変数 の値、後者は strerror() による対応するエラーメッセージ の値を持ちます。(chdir() や unlink() のような) ファイルシステム上のパスを含む例外に対しては、この例外インスタンス は 3 つめの属性、filename を持ち、関数に渡されたファイル名 となります。

name
import されているオペレーティング・システム依存モジュールの名前です。 現在次の名前が登録されています: 'posix', 'nt' 、 'dos' 、 'mac' 、 'os2' 、 'ce' 、 'java' 、 'riscos' 。

path
posixpath や macpath のように、システムごとに対応 付けられているパス名操作のためのシステム依存の標準モジュールです。 すなわち、正しく import が行われるかぎり、 os.path.split(file) は posixpath.split(file) と等価でありながらより汎用性があります。このモジュール自体が import 可能なモジュールでもあるので注意してください。: os.path として直接 import してもかまいません。

  • 6.1.1 プロセスのパラメタ
  • 6.1.2 ファイルオブジェクトの生成
  • 6.1.3 ファイル記述子の操作
  • 6.1.4 ファイルとディレクトリ
  • 6.1.5 プロセス管理
  • 6.1.6 雑多なシステム情報
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6. 汎用オペレーティングシステムサービス Up: 6. 汎用オペレーティングシステムサービス Next: 6.1.1 プロセスのパラメタ


6.1.1 プロセスのパラメタ

これらの関数とデータ要素は、現在のプロセスおよびユーザに対する情報 提供および操作のための機能を提供しています。

environ
環境変数の値を表すマップ型オブジェクトです。例えば、 environ['HOME'] は( いくつかのプラットフォーム上での) あなたの ホームディレクトリへのパスです。これは C の getenv("HOME") と 等価です。

プラットフォーム上で putenv() がサポートされている場合、この マップ型オブジェクトは環境変数に対するクエリと同様に変更するために使うこ ともできます。putenv() はマップ型オブジェクトが修正される時に、 自動的に呼ばれることになります。

注意: FreeBSD と Mac OS X を含むいつくかのプラットフォームでは、 environ の値を変更するとメモリリークの原因になる場合があります。 システムの putenv に関するドキュメントを参照してください。

putenv() が提供されていない場合、このマッピングオブジェクト を適切なプロセス生成機能に渡して、子プロセスが修正された環境変数 を利用するようにできます。

chdir( path)
getcwd( )
これらの関数は、``ファイルとディレクトリ'' (6.1.4 節) で 説明されています。

ctermid( )
プロセスの制御端末に対応するファイル名を返します。 利用できる環境: Unix。

getegid( )
現在のプロセスの実行グループ id を返します。この id は 現在のプロセスで実行されているファイルの `set id' ビットに 対応します。 利用できる環境: Unix。

geteuid( )
現在のプロセスの実行ユーザ id を返します。 利用できる環境: Unix。

getgid( )
現在のプロセスの実際のグループ id を返します。 利用できる環境: Unix。

getgroups( )
現在のプロセスに関連づけられた従属グループ id のリストを返します。 利用できる環境: Unix。

getlogin( )
現在のプロセスの制御端末にログインしているユーザ名を返します。ほとんどの 場合、ユーザが誰かを知りたいときには環境変数 LOGNAME を、現在有 効になっているユーザ名を知りたいときには pwd.getpwuid(os.getuid())[0] を使うほうが便利です。 利用できる環境: Unix。

getpgrp( )
現在のプロセス・グループの id を返します。 利用できる環境: Unix。

getpid( )
現在のプロセス id を返します。 利用できる環境: Unix, Windows.。

getppid( )
親プロセスの id を返します。 利用できる環境: Unix。

getuid( )
現在のプロセスのユーザ id を返します。 利用できる環境: Unix。

getenv( varname[, value])
環境変数 varname が存在する場合にはその値を返し、存在しない 場合には value を返します。value のデフォルト値は None です。 利用できる環境: Unix互換環境、Windows。

putenv( varname, value)
varname と名づけられた環境変数の値を文字列 value に 設定します。このような環境変数への変更は、os.system() 、 popen() 、 fork() および execv() により起動された子プロセスに影響します。 利用できる環境: 主な Unix互換環境、Windows。

注意: FreeBSD と Mac OS X を含むいつくかのプラットフォームでは、 environ の値を変更するとメモリリークの原因になる場合があります。 システムの putenv に関するドキュメントを参照してください。

putenv() がサポートされている場合、 os.environ
の要素に対する代入を行うと自動的に putenv() を呼び出します;
しかし、putenv() の呼び出しは os.environ を更新しない
ので、実際には os.environ の要素に代入する方が望ましい操作です。

setegid( egid)
現在のプロセスに有効なグループIDをセットします。 利用できる環境: Unix。

seteuid( euid)
現在のプロセスに有効なユーザIDをセットします。 利用できる環境: Unix。

setgid( gid)
現在のプロセスにグループ id をセットします。 利用できる環境: Unix。

setgroups( groups)
現在のグループに関連付けられた従属グループ id のリストを groups に設定します。groups はシーケンス型でなくてはならず、 各要素はグループを特定する整数でなくてはなりません。この操作は 通常、スーパユーザしか利用できません。 Availability: Unix. バージョン2.2 以降で新規追加された 仕様です。

setpgrp( )
システムコール setpgrp() または setpgrp(0, 0) のどちらかのバージョンのうち、 (実装されていれば) 実装されている方を呼び出します。 機能については Unix マニュアルを参照してください。 利用できる環境: Unix

setpgid( pid, pgrp)
システムコール setpgid() を呼び出して、 pid の id をもつプロセスのプロセスグループ id を pgrp に設定します。 利用できる環境: Unix

setreuid( ruid, euid)
現在のプロセスに対して実際のユーザ id および実行ユーザ id を 設定します。 利用できる環境: Unix

setregid( rgid, egid)
現在のプロセスに対して実際のグループ id および実行ユーザ id を 設定します。 利用できる環境: Unix

setsid( )
システムコール setsid() を呼び出します。機能については Unix マニュアルを参照してください。 利用できる環境: Unix

setuid( uid)
現在のプロセスのユーザ id を設定します。 利用できる環境: Unix

strerror( code)
エラーコード code に対応するエラーメッセージを返します。 利用できる環境: Unix、Windows

umask( mask)
現在の数値 umask を設定し、以前の umask 値を返します。 利用できる環境: Unix、Windows

uname( )
現在のオペレーティングシステムを特定する情報の入った 5 要素のタプル を返します。このタプルには 5 つの文字列: (sysname, nodename, release, version, machine) が入っています。 システムによっては、ノード名を 8 文字、または先頭の要素だけに 切り詰めます; ホスト名を取得する方法としては、 socket.gethostname() を使う方がよいでしょう、あるいは socket.gethostbyaddr(socket.gethostname()) でもかまいません。 利用できる環境: Unix互換環境

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.1 os Up: 6.1 os Next: 6.1.2 ファイルオブジェクトの生成


6.1.2 ファイルオブジェクトの生成

以下の関数は新しいファイルオブジェクトを作成します。

fdopen( fd[, mode[, bufsize]])
ファイル記述子 fd に接続している、開かれた ファイルオブジェクトを返します。引数 mode および bufsize は、組み込み関数 open() における対応する引数と同じ意味を持ちます。 利用できる環境: Macintosh、 Unix、Windows

popen( command[, mode[, bufsize]])
command への、または command からのパイプ入出力を開きます。 戻り値はパイプに接続されている開かれたファイルオブジェクトで、 mode が 'r' (標準の設定です) または 'w' かに よって読み出しまたは書き込みを行うことができます。 引数 bufsize は、組み込み関数 open() における対応する引数と同じ意味を持ちます。 command の終了ステータス (wait() で指定された書式でコード化 されています) は、close() メソッドの戻り値として取得することが できます。例外は終了ステータスがゼロ (すなわちエラーなしで終了) の 場合で、このときには None を返します。 利用できる環境: Unix、Windows

バージョン2.0 以降で変更された 仕様: この関数は、Pythonの初期のバージョンでは、 Windows環境下で信頼できない動作をしていました。これはWindowsに付属 して提供されるライブラリの _popen() 関数を利用したことに よるものです。新しいバージョンの Python では、Windows 付属のライブラリ にある壊れた実装を利用しません

tmpfile( )
更新モード("w+b")で開かれた新しいファイルオブジェクトを返します。 このファイルはディレクトリエントリ登録に関連付けられておらず、 このファイルに対するファイル記述子がなくなると自動的に削除されます。 利用できる環境: Unix、Windows

以下の popen() の変種はどれも、bufsize が指定されている場合には I/O パイプのバッファサイズを表します。 mode を指定する場合には、文字列 'b' または 't' でなければなりません; これは、Windows でファイルをバイナリモードで開くか テキストモードで開くかを決めるために必要です。 mode の標準の 設定値は't' です。

以下のメソッドは子プロセスからリターンコードを取得できるようには していません。入出力ストリームを制御し、かつ終了コードの取得も 行える唯一の方法は、 popen2 モジュールの Popen3 と Popen4 クラスを利用する事です。これらは Unix上でのみ利用可能です。

これらの関数の利用に関係して起きうるデッドロック状態についての議論は、 ``フロー制御問題'' (section 6.8.2) を参照してください。

popen2( cmd[, mode[, bufsize]])
cmd を子プロセスとして実行します。ファイル・オブジェクト (child_stdin, child_stdout) を返します。 利用できる環境: Unix、Windows バージョン2.0 以降で新規追加された 仕様です。

popen3( cmd[, mode[, bufsize]])
cmd を子プロセスとして実行します。ファイルオブジェクト (child_stdin, child_stdout, child_stderr) を 返します。 利用できる環境: Unix、Windows バージョン2.0 以降で新規追加された 仕様です。

popen4( cmd[, mode[, bufsize]])
cmd を子プロセスとして実行します。ファイルオブジェクト (child_stdin, child_stdout_and_stderr) を返します。 利用できる環境: Unix、Windows バージョン2.0 以降で新規追加された 仕様です。

上記の機能は popen2 モジュール内の同じ名前の関数 を使っても実現できますが、これらの関数の戻り値は異なる順序を持ってい ます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.1.1 プロセスのパラメタ Up: 6.1 os Next: 6.1.3 ファイル記述子の操作


6.1.3 ファイル記述子の操作

これらの関数は、ファイル記述子を使って参照されている I/Oストリームを操作します。

close( fd)
ファイルディスクリプタ fd を閉じます。 利用できる環境: Macintosh、 Unix、 Windows

注:この関数は低レベルの I/O のためのもので、open() や
pipe() が返すファイル記述子に対して適用しなければ
なりません。組み込み関数 open() や popen() 、
fdopen() の返す ``ファイルオブジェクト'' を閉じるには、
オブジェクトの close() メソッドを使ってください。

dup( fd)
ファイル記述子 fd の複製を返します。 利用できる環境: Macintosh、 Unix、 Windows.

dup2( fd, fd2)
ファイル記述子を fd から fd2 に複製し、必要なら後者の 記述子を前もって閉じておきます。 利用できる環境: Unix、Windows

fdatasync( fd)
ファイル記述子 fd を持つファイルのディスクへの書き込みを 強制します。メタデータの更新は強制しません。 利用できる環境: Unix

fpathconf( fd, name)
開いているファイルに関連したシステム設定情報 (system configuration information) を返します。 name には取得したい設定名を指定します; これは定義済みのシステム固有値名の文字列で、多くの標準 (POSIX.1、 Unix 95、 Unix 98 その他) で定義されています。 プラットフォームによっては別の名前も定義しています。 ホストオペレーティングシステムの関知する名前は pathconf_names 辞書で与えられています。このマップオブジェクトに入っていない設定 変数については、 name に整数を渡してもかまいません。 利用できる環境: Unix

もし name が文字列でかつ不明である場合、 ValueError を送出します。name の指定値がホストシステムでサポートされておらず、 pathconf_names にも入っていない場合、errno.EINVAL をエラー番号として OSError を送出します。

fstat( fd)
stat() のようにファイル記述子 fd の状態を返します。 利用できる環境: Unix、Windows

fstatvfs( fd)
statvfs() のように、ファイル記述子 fd に関連 づけられたファイルが入っているファイルシステムに関する情報を返します。 利用できる環境: Unix

fsync( fd)
ファイル記述子 fd を持つファイルのディスクへの書き込みを強制します。 Unixでは、ネイティブの fsync() 関数を、Windows では MS _commit() 関数を呼び出します。

Python のファイルオブジェクト f を使う場合、f の内部バッファ を確実にディスクに書き込むために、まず f.flush() を実行し、 それから os.fsync(f.fileno()) してください。 利用できる環境: Unix、2.2.3 以降では Windows も。

ftruncate( fd, length)
ファイル記述子 fd に対応するファイルを、サイズが最大で length バイトになるように切り詰めます。 利用できる環境: Unix。

isatty( fd)
ファイル記述子 fd が開いていて、tty(のような)装置に接 続されている場合、1 を返します。そうでない場合は 0 を返 します。 利用できる環境: Unix

lseek( fd, pos, how)
ファイル記述子 fd の現在の位置を pos に設定します。 pos の意味は how で修飾されます: ファイルの先頭からの相対には 0 を設定します; 現在の位置からの相対には1 を設定します; ファイルの末尾からの相対には 2 を設定します。 利用できる環境:Macintosh、 Unix、Windows。

open( file, flags[, mode])
ファイル file を開き、flag に従って様々なフラグを 設定し、可能なら mode に従ってファイルモードを設定します。 mode の標準の設定値は 0777 (8進表現) で、先に 現在の umask を使ってマスクを掛けます。新たに開かれたファイルの のファイル記述子を返します。利用できる環境:Macintosh、Unix、Windows。 フラグとファイルモードの値についての詳細は C ランタイムのドキュメントを 参照してください; (O_RDONLY や O_WRONLY のような) フラグ定数はこのモジュールでも定義されています (以下を参照してください)。

この関数は低レベルの I/O のためのものです。通常の利用では、 read() や write() (やその他多くの) メソッドを持つ ``ファイルオブジェクト'' を返す、組み込み関数 open() を 使ってください。, which returns a ``file

openpty( )
新しい擬似端末のペアを開きます。ファイル記述子のペア (master, slave) を返し、それぞれ pty および tty を表します。(少しだけ) より可搬性のあるアプローチとしては、 ptyモジュールを使ってください。 利用できる環境: いくつかの Unix風システム。

pipe( )
パイプを作成します。ファイル記述子のペア (r, w) を返し、それぞれ読み出し、書き込み用に使うことができます。 利用できる環境: Unix、Windows。

read( fd, n)
ファイル記述子 fd から最大で n バイト読み出します。 読み出されたバイト列の入った文字列を返します。fd が参照して いるファイルの終端に達した場合、空の文字列が返されます。 利用できる環境:Macintosh、Unix、Windows。

注:この関数は低レベルの I/O のためのもので、open() や
pipe() が返すファイル記述子に対して適用しなければ
なりません。組み込み関数 open() や popen() 、
fdopen() の返す ``ファイルオブジェクト'' 、あるいは
sys.stdin から読み出すには、オブジェクトの read()
メソッドを使ってください。

tcgetpgrp( fd)
fd (open() が返す開かれたファイル記述子) で与えられる端末に関連付けられたプロセスグループを返します。 利用できる環境: Unix。

tcsetpgrp( fd, pg)
fd (open() が返す開かれたファイル記述子) で与えられる端末に関連付けられたプロセスグループを pg に設定します。 利用できる環境: Unix。

ttyname( fd)
ファイル記述子 fd に関連付けられている端末デバイスを特定する 文字列を返します。fd が端末に関連付けられていない場合、 例外が送出されます。利用できる環境: Unix。

write( fd, str)
ファイル記述子 fd に文字列 str を書き込みます。 実際に書き込まれたバイト数を返します。 利用できる環境:Macintosh、 Unix、Windows。

注:この関数は低レベルの I/O のためのもので、open() や
pipe() が返すファイル記述子に対して適用しなければ
なりません。組み込み関数 open() や popen() 、
fdopen() の返す ``ファイルオブジェクト'' 、あるいは
sys.stdout、sys.stderr に書き込むには、オブジェクトの
write()
メソッドを使ってください。

以下のデータ要素は open() 関数の flags 引数を 構築するために利用することができます。

O_RDONLY
O_WRONLY
O_RDWR
O_NDELAY
O_NONBLOCK
O_APPEND
O_DSYNC
O_RSYNC
O_SYNC
O_NOCTTY
O_CREAT
O_EXCL
O_TRUNC

open() 関数の flag 引数のためのオプションフラグです。 これらの値はビット単位 OR を取ることができます。 利用できる環境:Macintosh、 Unix、Windows。

O_BINARY
open() 関数の flag 引数のためのオプションフラグです。 この値は上に列挙したフラグとビット単位 OR を取ることができます。 利用できる環境:Macintosh、Windows。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.1.2 ファイルオブジェクトの生成 Up: 6.1 os Next: 6.1.4 ファイルとディレクトリ


6.1.4 ファイルとディレクトリ

access( path, mode)
実 uid/gid を使って path に対するアクセスが可能か調べます。 ほとんどのオペレーティングシステムは実行 uid/gid を使うため、 このルーチンは suid/sgid 環境において、プログラムを起動した ユーザが path に対するアクセス権をもっているかを調べる ために使われます。path が存在するかどうかを調べるには mode を F_OK にします。ファイル操作許可 (permission) を調べるために R_OK、 W_OK、X_OK から一つまたはそれ以上のフラグと OR をとることもできます。 アクセスが許可されている場合 1 を、そうでない場合 0 を返します。詳細は access(2) のマニュアルページを参照して ください。利用できる環境:Macintosh、Windows。

F_OK
access() の mode に渡すための値で、 path が存在するかどうかを調べます。

R_OK
access() の mode に渡すための値で、 path が読み出し可能かどうかを調べます。

W_OK
access() の mode に渡すための値で、 path が書き込み可能かどうかを調べます。

X_OK
access() の mode に渡すための値で、 path が実行可能かどうかを調べます。

chdir( path)
現在の作業ディレクトリ (current working directory) を path に 設定します。利用できる環境:Macintosh、 Unix、Windows。

getcwd( )
現在の作業ディレクトリを表現する文字列を返します。 利用できる環境: Macintosh、 Unix、Windows。

chroot( path)
現在のプロセスに対してルートディレクトリを path に変更します。 利用できる環境: Unix。 バージョン2.2 以降で新規追加された 仕様です。

chmod( path, mode)
path のモードを数値 mode に変更します。 mode は、(stat モジュールで定義されている) 以下の値のいずれかを取り得ます:
  • S_ISUID
  • S_ISGID
  • S_ENFMT
  • S_ISVTX
  • S_IREAD
  • S_IWRITE
  • S_IEXEC
  • S_IRWXU
  • S_IRUSR
  • S_IWUSR
  • S_IXUSR
  • S_IRWXG
  • S_IRGRP
  • S_IWGRP
  • S_IXGRP
  • S_IRWXO
  • S_IROTH
  • S_IWOTH
  • S_IXOTH
利用できる環境: Unix、Windows。

chown( path, uid, gid)
path の所有者 (owner) id とグループ id を、数値 uid および gid に変更します。 利用できる環境: Unix。

link( src, dst)
src を指しているハードリンク dst を作成します。 利用できる環境: Unix。

listdir( path)
ディレクトリ内のエントリ名が入ったリストを返します。 リスト内の順番は不定です。特殊エントリ '.' および '..' は、それらがディレクトリに入っていてもリストには含められません。 バージョン2.3 以降で変更された 仕様: Windows NT/2k/XP と Unix では、path が Unicode オ ブジェクトの場合、Unicode オブジェクトのリストが返されます。 利用できる環境: Macintosh、 Unix、Windows。

lstat( path)
stat() に似ていますが、シンボリックリンクをたどりません。 利用できる環境: Unix。

mkfifo( path[, mode])
数値で指定されたモード mode を持つ FIFO (名前付きパイプ) を path に作成します。mode の標準の値は 0666 (8進) です。現在の umask 値が前もって mode からマスクされます。 利用できる環境: Unix。

FIFO は通常のファイルのようにアクセスできるパイプです。FIFO は (例えば os.unlink() を使って) 削除されるまで 存在しつづけます。一般的に、FIFO は ``クライアント'' と ``サーバ'' 形式のプロセス間でランデブーを行うために使われます: このとき、 サーバは FIFO を読み出し用に開き、クライアントは書き込み用に 開きます。mkfifo() は FIFO を開かない -- 単にランデブー ポイントを作成するだけ -- なので注意してください。

mknod( path[, mode=0600, device])
filename という名前で、ファイルシステム・ノード (ファイル、デバイス特殊 ファイル、または、名前つきパイプ) を作ります 。mode は、作ろうとす るノードの使用権限とタイプを、S_IFREG、S_IFCHR、S_IFBLK、S_IFIFO (これら の定数は stat で使用可能) のいずれかと（ビット OR で）組み合わ せて指定します。S_IFCHR と S_IFBLK を指定すると、device は新しく作 られたデバイス特殊ファイルを (おそらく os.makedev() を使って) 定義し、指定しなかった場合には無視します。 バージョン2.3 以降で新規追加された 仕様です。

major( device)
生のデバイス番号から、デバイスのメジャー番号を取り出します。 バージョン2.3 以降で新規追加された 仕様です。

minor( device)
生のデバイス番号から、デバイスのマイナー番号を取り出します。 バージョン2.3 以降で新規追加された 仕様です。

makedev( major, minor)
major と minor から、新しく生のデバイス番号を作ります。 バージョン2.3 以降で新規追加された 仕様です。

mkdir( path[, mode])
数値で指定されたモード mode をもつディレクトリ path を作成します。mode の標準の値は 0777 (8進)です。 システムによっては、 mode は無視されます。利用の際には、 現在の umask 値が前もってマスクされます。 利用できる環境:Macintosh、 Unix、Windows。

makedirs( path[, mode])
再帰的なディレクトリ作成関数です。 mkdir() に似て いますが、末端 (leaf) となるディレクトリを作成するために必要な 中間の全てのディレクトリを作成します。末端ディレクトリが すでに存在する場合や、作成ができなかった場合には error 例外を送出します。mode の標準の値は 0777 (8進)です。 (Windows システムにのみ関係することですが、Universal Naming Convention パスは、`\\host\path' という書式のパスです） バージョン1.5.2 以降で新規追加された 仕様です。

pathconf( path, name)
指定されたファイルに関係するシステム設定情報を返します。 varname には取得したい設定名を指定します; これは定義済みのシステム固有値名の文字列で、多くの標準 (POSIX.1、 Unix 95、 Unix 98 その他) で定義されています。 プラットフォームによっては別の名前も定義しています。 ホストオペレーティングシステムの関知する名前は pathconf_names 辞書で与えられています。このマップ型オブジェクトに入っていない設定 変数については、 name に整数を渡してもかまいません。 利用できる環境: Unix

もし name が文字列でかつ不明である場合、 ValueError を送出します。name の指定値がホストシステムでサポートされておらず、 pathconf_names にも入っていない場合、errno.EINVAL をエラー番号として OSError を送出します。

pathconf_names
pathconf() および fpathconf() が受理する システム設定名を、ホストオペレーティングシステムで定義されている 整数値に対応付けている辞書です。この辞書はシステムでどの 設定名が定義されているかを決定するために利用できます。 利用できる環境: Unix。

readlink( path)
シンボリックリンクが指しているパスを表す文字列を返します。 返される値は絶対パスにも、相対パスにもなり得ます; 相対 パスの場合、 os.path.join(os.path.dirname(path), result) を使って絶対パスに変換することができます。 利用できる環境: Unix。

remove( path)
ファイル path を削除します。path がディレクトリの 場合、OSError が送出されます; ディレクトリの削除については rmdir() を参照してください。この関数は下で述べられている unlink() 関数と同一です。Windows では、使用中のファイル を削除しようと試みると例外を送出します; Unixでは、ディレクトリ エントリは削除されますが、記憶装置上にアロケーションされたファイル領域は 元のファイルが使われなくなるまで残されます。 利用できる環境: Macintosh、 Unix、Windows。

removedirs( path)
再帰的なディレクトリ削除関数です。rmdir() と同じように 動作しますが、末端ディレクトリがうまく削除できるかぎり、パスを 構成する要素の右端となるディレクトリを刈り込んでゆき、指定したパス 全体が削除されるかエラーが送出されるまで続けます (このエラーは通常、 指定したディレクトリの親ディレクトリが空でないことを意味するだけ なので無視されます)。末端のディレクトリがうまく削除できない 場合には error を送出します。 バージョン1.5.2 以降で新規追加された 仕様です。

rename( src, dst)
ファイルまたはディレクトリ src を dst に名前変更します。 dst がディレクトリの場合、OSError が送出 されます。 Unixでは、 dst が存在し、かつファイルの場合、 ユーザの権限があるかぎり暗黙のうちに元のファイルが削除されます。 この操作はいくつかの Unix 系において、src と dst が異なるファイルシステム上にあると失敗することがあります。 ファイル名の変更が成功する場合、この操作は原子的 (atomic) 操作 となります (これは POSIX 要求仕様です) Windows では、 dst が既に存在する場合には、たとえファイルの場合でも OSError が送出されます; これは dst が既に 存在するファイル名の場合、名前変更の原子的操作を実装する手段が ないからです。利用できる環境:Macintosh、 Unix、Windows。

renames( old, new)
再帰的にディレクトリやファイル名を変更する関数です。 rename() のように動作しますが、新たなパス名を持つ ファイルを配置するために必要な途中のディレクトリ構造をまず作成 しようと試みます。 名前変更の後、元のファイル名のパス要素は removedirs() を使って右側から順に枝刈りされてゆきます。 注意：この関数はコピー元の末端のディレクトリまたはファイルを削除する 権限がない場合には失敗します。 バージョン1.5.2 以降で新規追加された 仕様です。

rmdir( path)
ディレクトリ path を削除します。 利用できる環境:Macintosh、 Unix、Windows。

stat( path)
与えられた path に対して stat() システムコールを 実行します。戻り値はオブジェクトで、その属性が stat 構造体の 以下に挙げる各メンバ: st_mode (保護モードビット)、 st_ino (i ノード番号)、 st_dev (デバイス)、 st_nlink (ハードリンク数)、 st_uid (所有者のユーザ ID)、 st_gid (所有者のグループ ID)、 st_size (ファイルのバイトサイズ)、 st_atime (最終アクセス時刻)、 st_mtime (最終更新時刻)、 st_ctime (最終更新またはメタデータ変更時刻)、 となっています。

バージョン2.3 以降で変更された 仕様: もし stat_float_times が真を返す場合、時間値は浮動小数点で秒を計ります。ファイルシステムがサポートしていれば、秒の小数点以下の桁も含めて返されます。 Mac OS では、時間は常に浮動小数点です。詳細な説明は stat_float_times を参照してください

(Linux のような) Unix システムでは、以下の属性: st_blocks (ファイル用にアロケーションされているブロック数)、 st_blksize (ファイルシステムのブロックサイズ)、 st_rdev (i ノードデバイスの場合、デバイスの形式)、 も利用可能なときがあります。

Mac OS システムでは、以下の属性: st_rsize、 st_creator、 st_type、 も利用可能なときがあります。

RISCOS システムでは、以下の属性: st_ftype (file type)、 st_attrs (attributes)、 st_obtype (object type)、 も利用可能なときがあります。

後方互換性のために、stat() の戻り値は少なくとも 10 個の 整数からなるタプルとしてアクセスすることができます。このタプルは もっとも重要な (かつ可搬性のある) stat 構造体のメンバを 与えており、以下の順番、 st_mode、 st_ino、 st_dev、 st_nlink、 st_uid、 st_gid、 st_size、 st_atime、 st_mtime、 st_ctime、 に並んでいます。

実装によっては、この後ろにさらに値が付け加えられていることもあります。 Mac OS では、時刻の値は Mac OS の他の時刻表現値と同じように浮動小数点数 なので注意してください。 標準モジュール statでは、 stat 構造体から情報を引き出す上で便利な関数や定数を定義して います。(Windows では、いくつかのデータ要素はダミーの値が埋められて います。) 利用できる環境: Macintosh、 Unix、Windows。

バージョン2.2 以降で変更された 仕様: 返されたオブジェクトの属性としてのアクセス機能を追加しました

stat_float_times( [newvalue])
stat_result がタイムスタンプに浮動小数点オブジェクトを使うかどう かを決定します。newvalue が真の場合、以後の stat() 呼び出しは浮動小数点 を返し、偽の場合には整数を返します。newvalue が省略された場合、現在の設 定どおりの戻り値になります。

古いバージョンの Python と互換性を保つため、stat_result にタプル としてアクセスすると、常に整数が返されます。また、Python 2.2 との互換性 のため、タイムスタンプにフィールド名を指定してアクセスすると、整数で返さ れす。タイムスタンプの秒を小数点以下の精度で求めたいアプリケーションは、 タイムスタンプを浮動小数点型にするために、この関数を使うことができます。 実際に、小数点以下の桁に 0 以外の数値が得られるかどうかは、システムに依 存します。

将来リリースされる Python は、この設定のデフォルト値を変更するでしょう。 浮動小数点型のタイムスタンプを扱えないアプリケーションは、この関数を使っ て、その機能を停止させることができます。

この設定の変更は、プログラムの起動時に、 __main__ モジュールの中でのみ行うことを推奨します。 ライブラリは決して、この設定を変更するべきではありません。 浮動小数点型のタイムスタンプを処理すると、不正確な動作をするようなライブ ラリを使う場合、ライブラリが修正されるまで、浮動小数点型を返す機能を停止 させておくべきです。

statvfs( path)
与えられた path に対して statvfs() システムコールを 実行します。戻り値はオブジェクトで、その属性は与えられたパスが収め られているファイルシステムについて記述したものです。かく属性は statvfs 構造体のメンバ: f_frsize、 f_blocks、 f_bfree、 f_bavail、 f_files、 f_ffree、 f_favail、 f_flag、 f_namemax、 に対応します。利用できる環境: Unix。

後方互換性のために、戻り値は上の順にそれぞれ対応する属性値が並んだ タプルとしてアクセスすることもできます。 標準モジュール statvfsでは、 配列としてアクセスする場合に、statvfs 構造体から情報を 引き出す上便利な関数や定数を定義しています; これは 属性として各フィールドにアクセスできないバージョンの Python で 動作する必要のあるコードを書く際に便利です。 バージョン2.2 以降で変更された 仕様: 返されたオブジェクトの属性としてのアクセス機能を追加しました

symlink( src, dst)
src を指しているシンボリックリンクを dst に作成します。 利用できる環境: Unix。

tempnam( [dir[, prefix]])
一時ファイル (temporary file) を生成する上でファイル名として相応しい 一意なパス名を返します。この値は一時的なディレクトリエントリ を表す絶対パスで、dir ディレクトリの下か、dir が省略 されたり None の場合には一時ファイルを置くための共通の ディレクトリの下になります。prefix が与えられており、かつ None でない場合、ファイル名の先頭につけられる短い 接頭辞になります。アプリケーションは tempnam() が返したパス名を使って正しくファイルを生成し、生成したファイルを 管理する責任があります; 一時ファイルの自動消去機能は提供されて いません。 警告: tempnam() を使うと、symlink 攻撃に対して脆弱 になります; 代りにtmpfile() を使うよう検討してください。 利用できる環境: Unix、Windows。

tmpnam( )
一時ファイル (temporary file) を生成する上でファイル名として相応しい 一意なパス名を返します。この値は一時ファイルを置くための共通の ディレクトリ下の一時的なディレクトリエントリを表す絶対パスです。 アプリケーションは tmpnam() が返したパス名を使って正しくファイルを生成し、生成したファイルを 管理する責任があります; 一時ファイルの自動消去機能は提供されて いません。

警告: tmpnam() を使うと、symlink 攻撃に対して脆弱 になります; 代りにtmpfile() を使うよう検討してください。 利用できる環境: Unix、Windows。 この関数はおそらく Windows では使うべきではないでしょう; Micorosoft の tmpnam() 実装では、常に現在のドライブの ルートディレクトリ下のファイル名を生成しますが、これは一般的には テンポラリファイルを置く場所としてはひどい場所です (アクセス権限によっては、この名前をつかってファイルを開くことすら できないかもしれません)。

TMP_MAX
tmpnam() がテンポラリ名を再利用し始めるまでに生成できる 一意な名前の最大数です。

unlink( path)
ファイル path を削除します。remove() と同じです; unlink() の名前は伝統的な Unix の関数名です。 利用できる環境: Macintosh、 Unix、Windows。

utime( path, times)
path で指定されたファイルに最終アクセス時刻および最終修正時刻 を設定します。times が None の場合、ファイルの最終 アクセス時刻および最終更新時刻は現在の時刻になります。そうでない 場合、 times は 2 要素のタプルで、(atime, mtime) の形式をとらなくてはなりません。これらはそれぞれアクセス時刻および修正時刻 を設定するために使われます。 バージョン2.0 以降で変更された 仕様: times として None をサポートするように しました 利用できる環境:Macintosh、 Unix、Windows。

walk( top[, topdown=True [, onerror=None]])
walk() は、ディレクトリツリー以下のファイル名を、ツリーを トップダウンとボトムアップの両方向に歩行することで生成します。 ディレクトリ top を根に持つディレクトリツリーに含まれる、 各ディレクトリ(top 自身を含む) から、タプル (dirpath, dirnames, filenames) を生成します。

dirpath は文字列で、ディレクトリへのパスです。dirnames は dirpath 内のサブディレクトリ名のリスト ('.' と '..' は除く）です。filenames は dirpath 内の非ディレクトリ・ファ イル名のリストです。このリスト内の名前には、ファイル名までのパスが含まれ ないことに、注意してください。dirpath 内のファイルやディレクトリへ の (top からたどった) フルパスを得るには、 os.path.join(dirpath, name) してください。

オプション引数 topdown が真であるか、指定されなかった場合、各ディ レクトリからタプルを生成した後で、サブディレクトリからタプルを生成します。 (ディレクトリはトップダウンで生成)。topdown が偽の場合、ディレクト リに対応するタプルは、そのディレクトリ以下の全てのサブディレクトリに対応 するタプルの後で (ボトムアップで) 生成されます

topdown が真のとき、呼び出し側は dirnames リストを、インプレ ースで (たとえば、del やスライスを使った代入で) 変更でき、 walk() はdirnames に残っているサブディレクトリ内のみを 再帰します。これにより、検索を省略したり、特定の訪問順序を強制したり、呼 び出し側が walk() を再開する前に、呼び出し側が作った、または 名前を変更したディレクトリを、walk() に知らせたりすることがで きます。topdown が偽のときに dirnames を変更しても効果はあり ません。ボトムアップモードでは dirnames 自身が生成される前に dirnames内のディレクトリの情報が生成されるからです。

デフォルトでは、os.listdir() 呼び出しから送出されたエラーは 無視されます。オプションの引数 onerror を指定するなら、 この値は関数でなければなりません; この関数は単一の引数として、 os.error インスタンスを伴って呼び出されます。この関数では エラーを報告して歩行を続けたり、例外を送出して歩行を中断したり できます。ファイル名は例外オブジェクトの filename 属性として 取得できることに注意してください。

注意: 相対パスを渡した場合、walk() の回復の間でカレント作業ディレク トリを変更しないでください。walk() はカレントディレクトリを変 更しませんし、呼び出し側もカレントディレクトリを変更しないと仮定していま す。

注意: シンボリックリンクをサポートするシステムでは、サブディレクトリへのリンク が dirnames リストに含まれますが、walk() はそのリンクを たどりません (シンボリックリンクをたどると、無限ループに陥りやすくなりま す)。リンクされたディレクトリをたどるには、 os.path.islink(path) でリンク先ディレクトリを確認し、各ディ レクトリに対して walk(path) を実行するとよいでしょう。

以下の例では、最初のディレクトリ以下にある各ディレクトリに含まれる、非ディレクトリファイルのバイト数を表示します。ただし、CVS サブディレクトリより下を見に行きません。

import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/email'):
    print root, "consumes",
    print sum([getsize(join(root, name)) for name in files]),
    print "bytes in", len(files), "non-directory files"
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS directories

次の例では、ツリーをボトムアップで歩行することが不可欠になります; rmdir() はディレクトリが空になる前に削除させないからです:

import os
from os.path import join
# Delete everything reachable from the directory named in 'top'.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
for root, dirs, files in os.walk(top, topdown=False):
    for name in files:
        os.remove(join(root, name))
    for name in dirs:
        os.rmdir(join(root, name))

バージョン2.3 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.1.3 ファイル記述子の操作 Up: 6.1 os Next: 6.1.5 プロセス管理


6.1.5 プロセス管理

プロセスを生成したり管理するために、以下の関数を利用することができます。

様々な exec*() 関数が、プロセス内にロードされた新たな プログラムに与えるための引数からなるリストをとります。どの場合でも、 新たなプログラムに渡されるリストの最初の引数は、ユーザがコマンドライン で入力する引数ではなく、プログラム自身の名前になります。 C プログラマにとっては、これはプログラムの main() に 渡される argv[0] になります。例えば、 "os.execv('/bin/echo', ['foo', 'bar'])" は、標準出力に "bar" を出力します; "foo" は無視されたかのように見える ことでしょう。

abort( )
SIGABRT シグナルを現在のプロセスに対して生成します。 Unixでは、標準設定の動作はコアダンプの生成です; Windows では、 プロセスは即座に終了コード 3 を返します。 signal.signal() を使って SIGABRT に対する シグナルハンドラを設定しているプログラムは異なる挙動を示すので 注意してください。

利用できる環境: Unix、Windows。

execl( path, arg0, arg1, ...)
execle( path, arg0, arg1, ..., env)
execlp( file, arg0, arg1, ...)
execlpe( file, arg0, arg1, ..., env)
execv( path, args)
execve( path, args, env)
execvp( file, args)
execvpe( file, args, env)

これらの関数はすべて、現在のプロセスを置き換える形で新たな プログラムを実行します; 現在のプロセスは戻り値を返しません。 Unixでは、新たに実行される実行コードは現在のプロセス内に ロードされ、呼び出し側と同じプロセス ID を持つことになります。 エラーは OSError 例外として報告されます。

"l" および "v" のついた exec*() 関数は、コマンドライン引数をどのように渡すかが異なります。 "l" 型は、コードを書くときにパラメタ数が決まっている場合 に、おそらくもっとも簡単に利用できます。個々のパラメタは単に execl*() 関数の追加パラメタとなります。"v" 型は、 パラメタの数が可変の時に便利で、リストかタプルの引数が args パラメタとして渡されます。どちらの場合も、子プロセスに渡す引数は 動作させようとしているコマンドの名前から始まらなくてはなりません。

末尾近くに "p" をもつ型 (execlp()、 execlpe()、 execvp()、 および execvpe()) は、プログラム file を探すために 環境変数 PATH を利用します。環境変数が (次の段で述べる exec*e() 型関数で) 置き換えられる場合、環境変数は PATH を決定する上の情報源として使われます。 その他の型、execl()、 execle()、 execv()、 および execve() では、実行 コードを探すために PATH を使いません。 path には適切に設定された絶対パスまたは相対パスが 入っていなくてはなりません。

execle()、 execlpe()、 execve()、
および execvpe() (全て末尾に"e" がついていること
に注意してください) では、env パラメタは新たなプロセスで利用
される環境変数を定義するためのマップ型でなくてはなりません;
execl()、execlp()、 execv()、
および execvp() では、全て新たなプロセスは現在のプロセス
の環境を引き継ぎます。利用できる環境: Unix、Windows。

_exit( n)
終了ステータス n でシステムを終了します。このとき クリーンアップハンドラの呼び出しや、標準入出力バッファの フラッシュなどは行いません。利用できる環境: Unix、Windows。

注意: システムを終了する標準的な方法は sys.exit(n) です。_exit() は通常、 fork() された後の子プロセス でのみ使われます。

以下の終了コードは必須ではありませんが _exit() と共に使うこと ができます。一般に、 メールサーバの外部コマンド配送プログラムのような、 Python で書かれたシステムプログラムに使います。

EX_OK
エラーが起きなかったことを表す終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_USAGE
誤った個数の引数が渡されたときなど、コマンドが間違って使われたことを表す 終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_DATAERR
入力データが間違っていたことを表す終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_NOINPUT
入力ファイルが存在しなかった、または、読み込み不可だったことを表す終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_NOUSER
指定されたユーザが存在しなかったことを表す終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_NOHOST
指定されたホストが存在しなかったことを表す終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_UNAVAILABLE
要求されたサービスが利用できないことを表す終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_SOFTWARE
内部ソフトウェアエラーが検出されたことを表す終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_OSERR
fork できない、pipe の作成ができないなど、オペレーティング・システム・エ ラーが検出されたことを表す終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_OSFILE
システムファイルが存在しなかった、開けなかった、あるいはその他のエラーが 起きたことを表す終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_CANTCREAT
ユーザには作成できない出力ファイルを指定したことを表す終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_IOERR
ファイルの I/O を行っている途中にエラーが発生したときの終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_TEMPFAIL
一時的な失敗が発生したことを表す終了コード。これは、再試行可能な操作の途 中に、ネットワークに接続できないというような、実際にはエラーではないかも 知れないことを意味します。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_PROTOCOL
プロトコル交換が不正、不適切、または理解不能なことを表す終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_NOPERM
操作を行うために十分な許可がなかった（ファイルシステムの問題を除く）こと を表す終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_CONFIG
設定エラーが起こったことを表す終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

EX_NOTFOUND
``an entry was not found'' のようなことを表す終了コード。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

fork( )
子プロセスを fork します。子プロセスでは 0 が返り、 親プロセスでは子プロセスの id が返ります。 利用できる環境: Unix。

forkpty( )
子プロセスを fork します。このとき新しい擬似端末 (psheudo-terminal) を子プロセスの制御端末として使います。 親プロセスでは (pid, fd) からなるペアが返り、fd は擬似端末の マスタ側 (master end) のファイル記述子となります。可搬性のある アプローチを取るためには、pty モジュールを利用してください。 利用できる環境: いくつかの Unix系。

kill( pid, sig)
プロセス pid をシグナル sig で kill します。 ホストプラットフォームで利用可能なシグナルを特定する定数は signal モジュールで定義されています。 利用できる環境: Unix。

killpg( pgid, sig)
プロセスグループ pgid をシグナル sig 付きで kill する。 利用できる環境: Unix。 バージョン2.3 以降で新規追加された 仕様です。

nice( increment)
プロセスの ``nice 値'' に increment を加えます。新たな nice 値を返します。利用できる環境: Unix。

plock( op)
プログラムのセグメント (program segment) をメモリ内でロックします。 op (<sys/lock.h> で定義されています) にはどのセグメントを ロックするかを指定します。利用できる環境: Unix。

popen( ...)
popen2( ...)
popen3( ...)
popen4( ...)
子プロセスを起動し、子プロセスとの通信のために開かれたパイプを返します。 これらの関数は 6.1.2 節で記述されています。

spawnl( mode, path, ...)
spawnle( mode, path, ..., env)
spawnlp( mode, file, ...)
spawnlpe( mode, file, ..., env)
spawnv( mode, path, args)
spawnve( mode, path, args, env)
spawnvp( mode, file, args)
spawnvpe( mode, file, args, env)
新たなプロセス内でプログラム path を実行します。 mode が P_NOWAIT の場合、この関数は 新たなプロセスのプロセス ID となります。; mode が P_WAIT の場合、子プロセスが正常に終了するとその終了コードが返ります。そうでない 場合にはプロセスを kill したシグナル signal に対して -signal が返ります。Windows では、プロセス ID は 実際にはプロセスハンドル値になります。

"l" および "v" のついた spawn*() 関数は、コマンドライン引数をどのように渡すかが異なります。 "l" 型は、コードを書くときにパラメタ数が決まっている場合 に、おそらくもっとも簡単に利用できます。個々のパラメタは単に spawnl*() 関数の追加パラメタとなります。"v" 型は、 パラメタの数が可変の時に便利で、リストかタプルの引数が args パラメタとして渡されます。どちらの場合も、子プロセスに渡す引数は 動作させようとしているコマンドの名前から始まらなくてはなりません。

末尾近くに "p" をもつ型 (spawnlp()、 spawnlpe()、 spawnvp()、 および spawnvpe()) は、プログラム file を探すために 環境変数 PATH を利用します。環境変数が (次の段で述べる spawn*e() 型関数で) 置き換えられる場合、環境変数は PATH を決定する上の情報源として使われます。 その他の型、spawnl()、 spawnle()、 spawnv()、 および spawnve() では、実行 コードを探すために PATH を使いません。 path には適切に設定された絶対パスまたは相対パスが 入っていなくてはなりません。

spawnle()、 spawnlpe()、 spawnve()、
および spawnvpe() (全て末尾に"e" がついていること
に注意してください) では、env パラメタは新たなプロセスで利用
される環境変数を定義するためのマップ型でなくてはなりません;
spawnl()、spawnlp()、 spawnv()、
および spawnvp() では、全て新たなプロセスは現在のプロセス
の環境を引き継ぎます。

例えば、以下の spawnlp() および spawnvpe() 呼び出し:

import os
os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')

L = ['cp', 'index.html', '/dev/null']
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)

は等価です。利用できる環境: Unix、Windows。

spawnlp()、spawnlpe()、 spawnvp() および spawnvpe() は Windows では利用できません。 バージョン1.6 以降で新規追加された 仕様です。

P_NOWAIT
P_NOWAITO
spawn*() 関数ファミリに対する mode パラメタ として取れる値です。この値のいずれかを mode として与えた場合、 spawn*() 関数は新たなプロセスが生成されるとすぐに、 プロセスの ID を戻り値として返ります。 利用できる環境: Unix、Windows。 バージョン1.6 以降で新規追加された 仕様です。

P_WAIT
spawn*() 関数ファミリに対する mode パラメタ として取れる値です。この値を mode として与えた場合、 spawn*() 関数は新たなプロセスを起動して完了するまで返らず、 プロセスがうまく終了した場合には終了コードを、シグナルによってプロセス が kill された場合には -signal を返します。 利用できる環境: Unix、Windows。 バージョン1.6 以降で新規追加された 仕様です。

P_DETACH
P_OVERLAY
spawn*() 関数ファミリに対する mode パラメタ として取れる値です。これらの値は上の値よりもやや可搬性において劣って います。P_DETACH は P_NOWAIT に似ていますが、 新たなプロセスは呼び出しプロセスのコンソールから切り離され (detach) ます。P_OVERLAY が使われた場合、現在のプロセスは 置き換えられます; 従ってspawn*() は返りません。 利用できる環境: Windows。 バージョン1.6 以降で新規追加された 仕様です。

startfile( path)
ファイルを関連付けられたアプリケーションを使って「スタート」します。 この動作は、 Windows の Explorer 上でのファイルをダブルクリックや、 コマンドプロンプト (interactive command shell) 上での ファイル名を start 命令の引数としての実行と同様です: ファイルは拡張子が関連付けされているアプリケーション (が存在する場合) を使って開かれます。

startfile() は関連付けされたアプリケーションが起動すると 同時に返ります。アプリケーションが閉じるまで待機させるためのオプション はなく、アプリケーションの終了状態を取得する方法もありません。 path 引数は現在のディレクトリからの相対で表します。 絶対パスを利用したいなら、最初の文字はスラッシュ ("/") ではないので注意してください; もし最初の文字がスラッシュ なら、システムの背後にある Win32 ShellExecute() 関数は 動作しません。os.path.normpath() 関数を使って、Win32 用に 正しくコード化されたパスになるようにしてください。 利用できる環境:Windows。 バージョン2.0 以降で新規追加された 仕様です。

system( command)
サブシェル内でコマンド (文字列) を実行します。この関数は 標準 C 関数 system() を使って実装されており、 system() と同じ制限があります。 posix.environ、 sys.stdin 等に対する変更を行っても、 実行されるコマンドの環境には反映されません。

Unixでは、戻り値はプロセスの終了ステータスで、wait() で定義されている書式にコード化されています。 POSIX は system() 関数の戻り値の意味について定義して いないので、Python の system における戻り値はシステム依存と なることに注意してください。

Windows では、戻り値は command を実行した後にシステムシェルから 返される値で、Windows の環境変数 COMSPEC となります: command.com ベースのシステム (Windows 95, 98 および ME) では、この値は常に 0 です; cmd.exe ベースのシステム (Windows NT, 2000 および XP) では、この値は実行したコマンドの終了 ステータスです; ネイティブでないシェルを使っているシステムについては、 使っているシェルのドキュメントを参照してください。

利用できる環境: Unix、Windows。

times( )
(プロセスまたはその他の) 積算時間を秒で表す浮動小数点数からなる、 5 要素のタプルを返します。タプルの要素は、ユーザ時間 (user time)、 システム時間 (system time)、子プロセスのユーザ時間、子プロセスの システム時間、そして過去のある固定時点からの経過時間で、この順に 並んでいます。Unix マニュアルページ times(2) または 対応する Windows プラットフォーム API ドキュメントを参照してください。 利用できる環境: Unix、Windows。

wait( )
子プロセスの実行完了を待機し、子プロセスの pid と終了コードインジケータ -- 16 ビットの数で、下位バイトがプロセスを kill したシグナル番号、上位バイト が終了ステータス (シグナル番号がゼロの場合) -- の入ったタプルを 返します; コアダンプファイルが生成された場合、下位バイトの最上桁ビットが 立てられます。 利用できる環境: Unix。

waitpid( pid, options)
プロセス id pid で与えられた子プロセスの完了を待機し、 子プロセスのプロセス id と(wait() と同様にコード化された) 終了ステータスインジケータからなるタプルを返します。 この関数の動作は options によって影響されます。通常の操作では 0 にします。利用できる環境: Unix。

pid が 0 よりも大きい場合、 waitpid() は特定のプロセスのステータス情報を要求します。pid が 0 の場合、現在のプロセスグループ内の任意の子プロセスの状態 に対する要求です。pid が -1 の場合、現在のプロセス の任意の子プロセスに対する要求です。pid が -1 よりも 小さい場合、プロセスグループ -pid (すなわち pid の 絶対値) 内の任意のプロセスに対する要求です。

WNOHANG
子プロセス状態がすぐに取得できなかった場合にハングアップしてしまわ ないようにするための waitpid() のオプションです。利用できる環境: Unix。

以下の関数はsystem()、 wait()、 あるいはwaitpid() が返すプロセス状態コード を引数にとります。これらの関数はプロセスの配置を決めるために 利用することができます。

WIFSTOPPED( status)
プロセスが停止された (stop) 場合に真を返します。 利用できる環境: Unix。

WIFSIGNALED( status)
プロセスがシグナルによって終了した (exit) 場合に真を返します。 利用できる環境: Unix。

WIFEXITED( status)
プロセスが exit(2) システムコールで終了した場合に 真を返します。利用できる環境: Unix。

WEXITSTATUS( status)
WIFEXITED(status) が真の場合、exit(2) システム コールに渡された整数パラメタを返します。そうでない場合、 返される値には意味がありません。 利用できる環境: Unix。

WSTOPSIG( status)
プロセスを停止させたシグナル番号を返します。 利用できる環境: Unix。

WTERMSIG( status)
プロセスを終了させたシグナル番号を返します。利用できる環境: Unix

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.1.4 ファイルとディレクトリ Up: 6.1 os Next: 6.1.6 雑多なシステム情報


6.1.6 雑多なシステム情報

confstr( name)
文字列形式によるシステム設定値 (system configuration value)を返します。 name には取得したい設定名を指定します; この値は 定義済みのシステム値名を表す文字列にすることができます; 名前は 多くの標準 (POSIX.1、 Unix 95、 Unix 98 その他) で定義されています。 ホストオペレーティングシステムの関知する名前は confstr_names 辞書で与えられています。 このマップ型オブジェクトに入っていない設定 変数については、 name に整数を渡してもかまいません。 利用できる環境: Unix。

name に指定された設定値が定義されていない場合、空文字列を返します。

もし name が文字列でかつ不明である場合、 ValueError を送出します。name の指定値がホストシステムでサポートされておらず、 confstr_names にも入っていない場合、errno.EINVAL をエラー番号として OSError を送出します。

confstr_names
confstr() が受理する名前を、ホストオペレーティングシステムで 定義されている整数値に対応付けている辞書です。 この辞書はシステムでどの 設定名が定義されているかを決定するために利用できます。 利用できる環境: Unix。

getloadavg( )
過去 1 分、5 分、15分間で、システムで走っているキューの平均プロセス数を 返します。平均負荷が得られない場合には OSError を送出します。 バージョン2.3 以降で新規追加された 仕様です。

sysconf( name)
整数値のシステム設定値を返します。 name で指定された設定値が定義されていない場合、-1 が返されます。name に関するコメントとしては、confstr() で述べた内容が同様に当てはまります; 既知の設定名についての情報を 与える辞書は sysconf_names で与えられています。 利用できる環境: Unix。

sysconf_names
sysconf() が受理する名前を、ホストオペレーティングシステムで 定義されている整数値に対応付けている辞書です。 この辞書はシステムでどの設定名が定義されているかを決定するために 利用できます。利用できる環境: Unix。

以下のデータ値はパス名編集操作をサポートするために利用されます。 これらの値は全てのプラットフォームで定義されています。

パス名に対する高レベルの操作は os.path モジュールで 定義されています。

curdir
現在のディレクトリ参照するためにオペレーティングシステムで使われる 文字列定数です。 例: POSIX では '.' 、Machintosh では':' 。 os.path からも利用できます。

pardir
親ディレクトリを参照するためにオペレーティングシステムで使われる 文字列定数です。 例: POSIX では '..' 、Machintosh では'::' 。 os.path からも利用できます。

sep
パス名を要素に分割するためにオペレーティングシステムで利用されている 文字で、例えば POSIX では "/" で、Machintosh では ":" です。しかし、このことを知っているだけではパス名を 解析したり、パス名同士を結合したりするには不十分です -- こうした操作には os.path.split() や os.path.join() を使ってください-- が、たまに便利なこともあります。 os.path からも利用できます。

altsep
文字パス名を要素に分割する際にオペレーティングシステムで利用されるもう 一つの文字で、分割文字が一つしかない場合には None になります。 この値は sep がバックスラッシュとなっている DOS や Windows システムでは "/" に設定されています。 os.path からも利用できます。

extsep
ベースのファイル名と拡張子を分ける文字。 たとえば、os.py では "." です。 os.path からも利用できます。 バージョン2.2 以降で新規追加された 仕様です。

pathsep
(PATH のような) サーチパス内の要素を分割するために オペレーティングシステムが慣習的に用いる文字で、POSIX における ":" や DOS および Windows における ";" に相当します。 os.path からも利用できます。

defpath
exec*p*() や spawn*p*() において、環境変数辞書内に 'PATH' キーがない場合に使われる標準設定のサーチパスです。 os.path からも利用できます。

linesep
現在のプラットフォーム上で行を分割 (あるいは終端) するために用いられ ている文字列です。この値は例えば POSIX での'\n' や MacOS での '\r' のように、単一の文字にもなりますし、例えば DOS や Windows での '\r\n' のように複数の文字列にもなります。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.1.5 プロセス管理 Up: 6.1 os Next: 6.2 os.path


6.2 os.path -- 共通のパス名操作

このモジュールには、パス名を操作する便利な関数が定義されています。

警告: これらの関数の多くはWindowsの一律命名規則（UNCパス名）を正しく サポートしていません。splitunc()とismount()は正し くUNCパス名を操作できます。

abspath( path)
pathの標準化された絶対パスを返します。 たいていのプラットフォームでは、 normpath(join(os.getcwd(), path))と同じ結果になります。 バージョン1.5.2 以降で新規追加された 仕様です。

basename( path)
パス名pathの末尾のファイル名を返します。 これはsplit(path)で返されるペアの２番目の要素です。 この関数が返す値はUnixの basenameとは異なります； Unixのbasenameは'/foo/bar/'に対して 'bar'を返しますが、basename()は空文字列('') を返します。

commonprefix( list)
パスのlistの中の共通する最長のプレフィックスを（パス名の１文字１文 字を判断して）返します。 もしlistが空なら、空文字列('')を返します。 これは一度に１文字を扱うため、不正なパスを返すことがあるかもしれませんの で注意して下さい。

dirname( path)
パスpathのディレクトリ名を返します。 これはsplit(path)で返されるペアの最初の要素です。

exists( path)
pathが存在するなら、Trueを返します。

expanduser( path)
与えられた引数の最初の"~"または"~user"を、userの ホームディレクトリのパスに置き換えて返します。 最初が"~"なら、環境変数のHOMEの値に置き換えられます； "~user"なら、ビルトインモジュール pwdを使ってパスワードディレクトリから該当 するものを検索します。 もし置き換えに失敗したり、引数のパスがチルダで始まっていなかったら、パス をそのまま返します。 Macintoshではpathをそのまま返します。

expandvars( path)
引数のパスを環境変数に展開して返します。 引数の中の"$name"または"${name}"の文字列が 環境変数のnameに置き換えられます。 不正な変数名や存在しない変数名の場合には変換されず、そのまま返します。 Macintoshではpathをそのまま返します。

getatime( path)
pathに最後にアクセスした時刻を、エポック（timeモジュール を参照）からの経過時間を示す秒数で返します。 ファイルが存在しなかったりアクセスできない場合はos.errorを発 生します。 バージョン2.3 以降で変更された 仕様: os.stat_float_times()がTrueを返す場合、戻り値は 浮動小数点値となります。 バージョン1.5.2 以降で新規追加された 仕様です。

getmtime( path)
pathの最終更新時刻を、エポック（timeモジュールを参照） からの経過時間を示す秒数で返します。 ファイルが存在しなかったりアクセスできない場合はos.errorを発 生します。 バージョン2.3 以降で変更された 仕様: os.stat_float_times()がTrueを返す場合、戻り値は 浮動小数点値となります。 バージョン1.5.2 以降で新規追加された 仕様です。

getctime( path)
システムによって、ファイルの最終変更時刻 (Unix のような システム) や 作成時刻 (Windows のようなシステム) をシステムの ctime で返します。 戻り値はエポック（timeモジュールを参照）からの経過秒数を 示す数値です。 ファイルが存在しなかったりアクセスできない場合はos.errorを発 生します。 バージョン2.3 以降で新規追加された 仕様です。

getsize( path)
ファイルpathのサイズをバイト数で返します。 ファイルが存在しなかったりアクセスできない場合はos.errorを発 生します。 バージョン1.5.2 以降で新規追加された 仕様です。

isabs( path)
pathが絶対パス（スラッシュで始まる）なら、Trueを返します。

isfile( path)
pathが存在する正しいファイルなら、Trueを返します。 シンボリックリンクの場合にはその実体をチェックするので、同じパスに対して islink()とisfile()の両方がTrueを返すことがあ ります。

isdir( path)
pathが存在するなら、Trueを返します。 シンボリックリンクの場合にはその実体をチェックするので、同じパスに対して islink()とisfile()の両方がTrueを返すことがあ ります。

islink( path)
pathがシンボリックリンクなら、Trueを返します。 シンボリックリンクがサポートされていないプラットフォームでは、常に Falseを返します。

ismount( path)
パス名pathがマウントポイントmount point（ファイルシステムの 中で異なるファイルシステムがマウントされているところ）なら、True を返します： この関数はpathの親ディレクトリであるpath/..が pathと異なるデバイス上にあるか、あるいはpath/..と pathが同じデバイス上の同じi-nodeを指しているかをチェックします-- これによって全てのUnixとPOSIX標準でマウントポイントが検出できま す。

join( path1[, path2[, ...]])
パスに１つあるいはそれ以上のパスの要素をうまく結合します。 付け加える要素に絶対パスがあれば、それより前の要素は全て破棄され、以降の 要素を結合します。 戻り値はpath1と省略可能なpath2以降を結合したもので、 path2が空文字列でないなら、ディレクトリの区切り文字(os.sep) が各要素の間に挿入されます。 Windowsでは各ドライブに対してカレントディレクトリがあるので、 os.path.join("c:", "foo")によって、 c:\\fooではなく、ドライブC:上の カレントディレクトリからの相対パス（c:foo）が返されます。

normcase( path)
パス名の大文字、小文字をシステムの標準にします。 Unixではそのまま返します。大文字、小文字を区別しないファイルシステム ではパス名を小文字に変換します。 Windowsでは、スラッシュをバックスラッシュに変換します。

normpath( path)
パス名を標準化します。 余分な区切り文字や上位レベル参照を削除します。例えば、A//B、 A/./B、A/foo/../Bは全てA/Bになります。 大文字、小文字は標準化しません（それにはnormcase()を使って下 さい）。 Windowsでは、スラッシュをバックスラッシュに変換します。

realpath( path)
パスの中のシンボリックリンクを取り除いて、標準化したパスを返します。 利用可能：Unix。 バージョン2.2 以降で新規追加された 仕様です。

samefile( path1, path2)
２つの引数であるパス名が同じファイルあるいはディレクトリを指していれば（ 同じデバイスナンバーとi-nodeナンバーで示されていれば）、Trueを返 します。 どちらかのパス名でos.stat()の呼び出しに失敗した場合には、例外 が発生します。 利用可能：Macintosh、Unix

sameopenfile( fp1, fp2)
fp1とfp2が同じファイルオブジェクトを指していたら、 Trueを返します。 ２つのファイルオブジェクトが異なるファイルディスクリプタを示すこともあり ます。 利用可能：Macintosh、Unix

samestat( stat1, stat2)
statタプルstat1とstat2が同じファイルを指していたら、 Trueを返します。 これらのタプルはfstat()、lstat()や stat()で返されたものでかまいません。 この関数は、samefile()とsameopenfile()で使われるの と同様なものを背後に実装しています。 利用可能：Macintosh、Unix

split( path)
パス名pathを(headとtail)のペアに分割します。 tailはパスの構成要素の末尾で、headはそれより前の部分です。 tailはスラッシュを含みません；もしpathの最後にスラッシュがあ れば、tailは空文字列になります。 もしpathにスラッシュがなければ、headは空文字列になります。 pathが空文字列なら、headとtailのどちらも空文字列になり ます。 headの末尾のスラッシュは、headがルートディレクトリ（１つ以上 のスラッシュのみ）でない限り、取り除かれます。 ほとんど全ての場合、join(head, tail)の結果が pathと等しくなります（ただ１つの例外は、複数のスラッシュが headとtailを分けている時です）。

splitdrive( path)
パス名pathを(drive,tail)のペアに分割します。 driveはドライブ名か、空文字列です。 ドライブ名を使用しないシステムでは、driveは常に空文字列です。 全ての場合にdrive + tailはpathと等しくなりま す。 バージョン1.3 以降で新規追加された 仕様です。

splitext( path)
パス名pathを(root, ext)のペアにします。 root + ext == pathになります。 extは空文字列か１つのピリオドで始まり、多くても１つのピリオドを含 みます。

walk( path, visit, arg)
pathをルートとする各ディレクトリに対して（もしpathがディレク トリならpathも含みます）、(arg, dirname, names)を引数として関数visitを呼び出します。 引数dirnameは訪れたディレクトリを示し、引数namesはそのディレ クトリ内のファイルのリスト（os.listdir(dirname)で得られる） です。 関数visitによってnamesを変更して、dirname以下の対象と なるディレクトリのセットを変更することもできます。例えば、あるディレクト リツリーだけ関数を適用しないなど。 （namesで参照されるオブジェクトは、delあるいはスライスを 使って正しく変更しなければなりません。）

注意: ディレクトリへのシンボリックリンクはサブディレクトリとして扱われないの で、walk()による操作対象とはされません。 ディレクトリへのシンボリックリンクを操作対象とするには、 os.path.islink(file)とos.path.isdir(file) で識別して、walk()で必要な操作を実行しなければなりません。

注意: 新たに追加されたos.walk() ジェネレータを 使用すれば、同じ処理をより簡単に行う事ができます。

supports_unicode_filenames
任意のユニコード文字列を（ファイルシステムの制限内で） ファイルネームに使うことが可能で、os.listdirがユニコード文字列の 引数に対してユニコードを返すなら、真を返します。 バージョン2.3 以降で新規追加された 仕様です。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.1.6 雑多なシステム情報 Up: 6. 汎用オペレーティングシステムサービス Next: 6.3 dircache


6.3 dircache -- キャッシュされたディレクトリ一覧の生成

durcache モジュールはキャッシュされた情報を使って ディレクトリ一覧を読み出すための関数を定義しています。 キャッシュはディレクトリの mtime に応じて無効化されます。 さらに、一覧中のディレクトリにスラッシュ ('/') を追加することで ディレクトリであると分かるようにするための関数も定義しています。

dircache モジュールは以下の関数を定義しています:

listdir( path)
os.listdir() によって得た path のディレクトリ一覧を 返します。path を変えない限り、以降の listdir() を呼び出してもディレクトリ構造を読み込みなおすことはしないので 注意してください。

返されるリストは読み出し専用であると見なされるので注意してください (おそらく将来のバージョンではタプルを返すように変更されるはず ? です)。

opendir( path)
listdir() と同じです。以前のバージョンとの互換性のために 定義されています。

annotate( head, list)
list を head の相対パスからなるリストとして、 各パスがディレクトリを指す場合には "/" をパス名の後ろ に追加したものに置き換えます。

>>> import dircache
>>> a=dircache.listdir('/')
>>> a=a[:] # Copy the return value so we can change 'a'
>>> a
['bin', 'boot', 'cdrom', 'dev', 'etc', 'floppy', 'home', 'initrd', 'lib', 'lost+
found', 'mnt', 'proc', 'root', 'sbin', 'tmp', 'usr', 'var', 'vmlinuz']
>>> dircache.annotate('/', a)
>>> a
['bin/', 'boot/', 'cdrom/', 'dev/', 'etc/', 'floppy/', 'home/', 'initrd/', 'lib/
', 'lost+found/', 'mnt/', 'proc/', 'root/', 'sbin/', 'tmp/', 'usr/', 'var/', 'vm
linuz']
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.2 os.path Up: 6. 汎用オペレーティングシステムサービス Next: 6.4 stat


6.4 stat -- stat() の返す内容を解釈する

stat モジュールでは、os.stat()、
os.lstat() および os.fstat() (存在すれば) の返す
内容を解釈するための定数や関数を定義しています。stat()、
fstat()、および lstat() の関数呼び出しについての
完全な記述はシステムのドキュメントを参照してください。

stat モジュールでは、特殊なファイル型を判別するための以下の 関数を定義しています:

S_ISDIR( mode)
ファイルのモードがディレクトリの場合にゼロでない値を返します。

S_ISCHR( mode)
ファイルのモードがキャラクタ型の特殊デバイスファイルの場合にゼロでない値を返します。

S_ISBLK( mode)
ファイルのモードがブロック型の特殊デバイスファイルの場合にゼロでない値を返します。

S_ISREG( mode)
ファイルのモードが通常ファイルの場合にゼロでない値を返します。

S_ISFIFO( mode)
ファイルのモードが FIFO (名前つきパイプ) の場合にゼロでない値を返します。

S_ISLNK( mode)
ファイルのモードがシンボリックリンクの場合にゼロでない値を返します。

S_ISSOCK( mode)
ファイルのモードがソケットの場合にゼロでない値を返します。

より一般的なファイルのモードを操作するための二つの関数が定義されています:

S_IMODE( mode)
os.chmod() で設定することのできる一部のファイルモード -- すなわち、ファイルの許可ビット (permission bits) に加え、 (サポートされているシステムでは) スティッキービット (sticky bit)、 実行グループ ID 設定 (set-group-id) および 実行ユーザ ID 設定 (set-user-id) ビット -- を返します。

S_IFMT( mode)
ファイルの形式を記述しているファイルモードの一部 (上記の S_IS*() 関数で使われます) を返します。

通常、ファイルの形式を調べる場合には os.path.is*() 関数 を使うことになります; ここで挙げた関数は同じファイルに対して 複数のテストを同時に行いたいが、stat() システムコール を何度も呼び出してオーバヘッドが生じるのを避けたい場合に便利です。 これらはまた、ブロック型およびキャラクタ型デバイスに対するテスト のように、os.path で扱うことのできないファイルの 情報を調べる際にも便利です。

以下の全ての変数は、os.stat()、 os.fstat()、または os.lstat() が返す 10 要素のタプルにおけるインデクスを単に シンボル定数化したものです。

ST_MODE
I ノードの保護モード。

ST_INO
I ノード番号。

ST_DEV
I ノードが存在するデバイス。

ST_NLINK
該当する I ノードへのリンク数。

ST_UID
ファイルの所持者のユーザ ID。

ST_GID
ファイルの所持者のグループ ID。

ST_SIZE
通常ファイルではバイトサイズ; いくつかの特殊ファイルでは処理待ちの データ量。

ST_ATIME
最後にアクセスした時刻。

ST_MTIME
最後に変更された時刻。

ST_CTIME
最後に状態が変更された時刻 (詳細についてはマニュアルページを参照してください)。

``ファイルサイズ'' の解釈はファイルの型によって異なります。 通常のファイルの場合、サイズはファイルの大きさをバイトで表した ものです。ほとんどの Unix 系 (特に Linux) における FIFO やソケット の場合、``サイズ'' は os.stat()、 os.fstat()、 あるいは os.lstat() を呼び出した時点で読み出し待ちであった データのバイト数になります; この値は時に有用で、特に上記の特殊なファイル を非ブロックモードで開いた後にポーリングを行いたいといった場合に 便利です。他のキャラクタ型およびブロック型デバイスにおけるサイズ フィーるの意味はさらに異なっていて、背後のシステムコールの実装に よります。

例を以下に示します:

import os, sys
from stat import *

def walktree(top, callback):
    '''recursively descend the directory tree rooted at top,
       calling the callback function for each regular file'''

    for f in os.listdir(top):
        pathname = os.path.join(top, f)
        mode = os.stat(pathname)[ST_MODE]
        if S_ISDIR(mode):
            # It's a directory, recurse into it
            walktree(pathname, callback)
        elif S_ISREG(mode):
            # It's a file, call the callback function
            callback(pathname)
        else:
            # Unknown file type, print a message
            print 'Skipping %s' % pathname

def visitfile(file):
    print 'visiting', file

if __name__ == '__main__':
    walktree(sys.argv[1], visitfile)
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.3 dircache Up: 6. 汎用オペレーティングシステムサービス Next: 6.5 statcache


6.5 statcache -- os.stat() の最適化

リリース 2.2 以降で撤廃された仕様です。 キャッシュを使わずに os.stat() を直接 使ってください; キャッシュはそれを使うアプリケーションに非常に高い レベルの脆弱性をもたらし、キャッシュ管理のサポートを追加する ことでアプリケーションのソースコードを難解にしてしまいます。

statcache モジュールは os.stat() を最後に呼び出 した際の値を記憶することによる最適化機能を提供します。

statcache モジュールでは以下の関数を定義しています:

stat( path)
このモジュールの主要なエントリポイントです。

os.stat() と同じですが、将来同じ呼び出しが行われた ときの為に結果を記憶しておきます。

その他の関数はキャッシュやその一部を消去するために用いられます。

reset( )
キャッシュを消去します: これまでの全ての stat() 呼び出し による結果を忘却します。

forget( path)
stat(path) のキャッシュが存在すれば、それを忘却します。

forget_prefix( prefix)
prefix で始まる path に対する stat(path) の結果をすべて忘却します。

forget_dir( prefix)
prefix で始まる path に対する stat(path) の結果を、stat(prefix) も含めてすべて忘却します。

forget_except_prefix( prefix)
forget_prefix() に似ていますが、prefix で 始まらない 全ての path について忘却します。

以下に例を示します:

>>> import os, statcache
>>> statcache.stat('.')
(16893, 2049, 772, 18, 1000, 1000, 2048, 929609777, 929609777, 929609777)
>>> os.stat('.')
(16893, 2049, 772, 18, 1000, 1000, 2048, 929609777, 929609777, 929609777)
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.4 stat Up: 6. 汎用オペレーティングシステムサービス Next: 6.6 statvfs


6.6 statvfs -- os.statvfs() で使われる定数群

statvfs モジュールでは、os.statvfs() の返す値 を解釈するための定数を定義しています。os.statvfs() は ``マジックナンバ'' を記憶せずにタプルを生成して返します。 このモジュールで定義されている各定数は os.statvfs() が 返すタプルにおいて、特定の情報が収められている各エントリへの インデクス です。

F_BSIZE
選択されているファイルシステムのブロックサイズです。

F_FRSIZE
ファイルシステムの基本ブロックサイズです。

F_BLOCKS
ブロック数の総計です。

F_BFREE
空きブロック数の総計です。

F_BAVAIL
非スーパユーザが利用できる空きブロック数です。

F_FILES
ファイルノード数の総計です。

F_FFREE
空きファイルノード数の総計です。

F_FAVAIL
非スーパユーザが利用できる空きノード数です。

F_FLAG
フラグで、システム依存です: statvfs() マニュアルページを 参照してください。

F_NAMEMAX
ファイル名の最大長です。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.5 statcache Up: 6. 汎用オペレーティングシステムサービス Next: 6.7 filecmp


6.7 filecmp -- ファイルおよびディレクトリの比較

filecmp モジュールでは、ファイルおよびディレクトリを 比較するため、様々な時間／正確性のトレードオフに関するオプションを 備えた関数を定義しています。

filecmp モジュールでは以下の関数を定義しています:

cmp( f1, f2[, shallow[, use_statcache]])
名前が f1 および f2 のファイルを比較し、二つのファイルが 同じらしければ True を返し、そうでなければ false を 返します。

shallow が与えられておりかつ偽でなければ、os.stat() の返すシグネチャが一致するファイルは同じであると見なされます。 バージョン2.3 以降で変更された 仕様: use_statcache は廃止され、指定しても無視されます。

この関数で比較されたファイルは os.stat() シグネチャが 変更されるまで再び比較されることはありません。use_statcache を真にすると、キャッシュ無効化機構を失敗させます -- そのため、 statcache のキャッシュから古いファイル stat 値が 使われます。

可搬性と効率のために、個の関数は外部プログラムを一切呼び出さないので 注意してください。

cmpfiles( dir1, dir2, common[, shallow[, use_statcache]])
ファイル名からなる 3つのリスト: match、mismatch、 errors を返します。match には双方のディレクトリで 一致したファイルのリストが含まれ、mismatch にはそうでない ファイル名のリストが入ります。そして errors は比較されなかった ファイルが列挙されます。ファイルによっては、ユーザにそのファイル を読む権限がなかったり、比較を完了することができなかった場合以外 のその他諸々の理由により、 errors に列挙されることがあります。

引数 common は両方のディレクトリにあるファイルのリストです。 引数 shallow および use_statcache はその意味も標準 の設定も filecmp.cmp() と同じです。

例:

>>> import filecmp
>>> filecmp.cmp('libundoc.tex', 'libundoc.tex')
True
>>> filecmp.cmp('libundoc.tex', 'lib.tex')
False

  • 6.7.1 dircmp クラス
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.6 statvfs Up: 6. 汎用オペレーティングシステムサービス Next: 6.7.1 dircmp クラス


6.7.1 dircmp クラス

dircmp のインスタンスは以下のコンストラクタで生成されます:

class dircmp( a, b[, ignore[, hide]])
ディレクトリ a および b を比較するための新しいディレクトリ 比較オブジェクトを生成します。ignore は比較の際に無視する ファイル名のリストで、標準の設定では ['RCS', 'CVS', 'tags'] です。hide は表示しない名前のリストで、標準の設定では [os.curdir, os.pardir] です。

dircmp クラスは以下のメソッドを提供しています:

report( )
a および b の間の比較結果を (sys.stdout に) 出力します。

report_partial_closure( )
a および b およびそれらの直下にある共通のサブディレクトリ 間での比較結果を出力します。

report_full_closure( )
a および b およびそれらの共通のサブディレクトリ間での 比較結果を (再帰的に比較して) 出力します。

dircmp は、比較しているディレクトリツリーに関する様々な 種類の情報を取得するために使えるような、多くの興味深い属性を提供 しています。

__getattr__() フックを経由すると、全ての属性を のろのろと計算するため、速度上のペナルティを受けないのは 計算処理の軽い属性を使ったときだけなので注意してください。

left_list
a にあるファイルおよびサブディレクトリです。 hide および ignore でフィルタされています。

right_list
b にあるファイルおよびサブディレクトリです。 hide および ignore でフィルタされています。

common
a および b の両方にあるファイルおよびサブディレクトリです。

left_only
a だけにあるファイルおよびサブディレクトリです。

right_only
b だけにあるファイルおよびサブディレクトリです。

common_dirs
a および b の両方にあるサブディレクトリです。

common_files
a および b の両方にあるファイルです。

common_funny
a および b の両方にあり、ディレクトリ間で タイプが異なるか、os.stat() がエラーを報告するような 名前です。

same_files
a および b 両方にあり、一致するファイルです。

diff_files
a および b 両方にあるが、一致しないファイルです。

funny_files
a および b 両方にあるが、比較されなかったファイルです。

subdirs
common_dirs のファイル名を dircmp オブジェクトに 対応付けた辞書です。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.7 filecmp Up: 6.7 filecmp Next: 6.8 popen2


6.8 popen2 -- アクセス可能な I/O ストリームを持つ子プロセス生成

利用可能な条件: Unix, Windows.

このモジュールにより、Unix および Windows でプロセスを起動し、 その入力／出力／エラー出力パイプに接続し、そのリターンコード を取得することができます。

Python 2.0 から、この機能は os モジュールにある 関数を使って得ることができるので注意してください。 os にある関数はこのモジュールにおけるファクトリ関数 と同じ名前を持ちますが、戻り値に関する取り決めは os の関数の方がより直感的です。

このモジュールで提供されている第一のインタフェースは 3 つの ファクトリ関数です。これらの関数のいずれも、bufsize を 指定した場合、 I/O パイプのバッファサイズを決定します。 mode を指定する場合、文字列'b' または 't' でなければなりません; Windows では、ファイルオブジェクトを バイナリあるいはテキストモードのどちらで開くかを決めなければ なりません。mode の標準の値は 't' です。

子プロセスからのリターンコードを取得するには、Popen3 および Popen4 クラスの poll() あるいは wait() メソッドを使うしかありません; これらの機能は Unixでしか利用できません。この情報は popen2()、 popen3()、および popen4() 関数、 あるいは os モジュールにおける同等の関数の 使用によっては得ることができません。

popen2( cmd[, bufsize[, mode]])
cmd をサブプロセスとして実行します。ファイルオブジェクト (child_stdout, child_stdin) を返します。

popen3( cmd[, bufsize[, mode]])
cmd をサブプロセスとして実行します。ファイルオブジェクト (child_stdout, child_stdin, child_stderr) を返します。

popen4( cmd[, bufsize[, mode]])
cmd をサブプロセスとして実行します。ファイルオブジェクト (child_stdout_and_stderr, child_stdin). バージョン2.0 以降で新規追加された 仕様です。

Unixでは、ファクトリ関数によって返されるオブジェクトを定義している クラスも利用することができます。これらのオブジェクトは Windows 実装 で使われていないため、そのプラットフォーム上で使うことはできません。

class Popen3( cmd[, capturestderr[, bufsize]])
このクラスは子プロセスを表現します。通常、 Popen3 インスタンスは上で述べた popen2() および popen3() ファクトリ関数を使って生成されます。

Popen3 オブジェクトを生成するためにいずれかのヘルパー関数を 使っていないのなら、cmd パラメタは子プロセスで実行する シェルコマンドになります。capturestderr フラグが真であれば、 このオブジェクトが子プロセスの標準エラー出力を捕獲しなければならない ことを意味します。標準の値は偽です。bufsize パラメタが存在 する場合、子プロセスへの／からの I/O バッファのサイズを指定します。

class Popen4( cmd[, bufsize])
Popen3 に似ていますが、標準エラー出力を標準出力と同じファイル オブジェクトで捕獲します。このオブジェクトは通常 popen4() で 生成されます。 バージョン2.0 以降で新規追加された 仕様です。

  • 6.8.1 Popen3 および Popen4 オブジェクト
  • 6.8.2 フロー制御の問題
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.7.1 dircmp クラス Up: 6. 汎用オペレーティングシステムサービス Next: 6.8.1 Popen3 および Popen4


6.8.1 Popen3 および Popen4 オブジェクト

Popen3 および Popen4 クラスのインスタンスは以下の メソッドを持ちます:

poll( )
子プロセスがまだ終了していない際には -1 を、そうでない場合には リターンコードを返します。

wait( )
子プロセスの状態コード出力を待機して返します。状態コードでは 子プロセスのリターンコードと、プロセスが exit() によって 終了したか、あるいはシグナルによって死んだかについての情報を 符号化しています。状態コードの解釈を助けるための関数は os モジュールで定義されています; 6.1.5 節の W*() 関数ファミリを 参照してください。

以下の属性も利用可能です:

fromchild
子プロセスからの出力を提供するファイルオブジェクトです。 Poepn4 インスタンスの場合、この値は標準出力と標準 エラー出力の両方を提供するオブジェクトになります。

tochild
子プロセスへの入力を提供するファイルオブジェクトです。

childerr
コンストラクタに capturestderr を渡した際には子プロセスからの 標準エラーを提供するファイルオブジェクトで、そうでない場合 None になります。 Popen4 インスタンスでは、この値は常に None になります。

pid
子プロセスのプロセス番号です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.8 popen2 Up: 6.8 popen2 Next: 6.8.2 フロー制御の問題


6.8.2 フロー制御の問題

何らかの形式でプロセス間通信を利用している際には常に、制御フローに ついて注意深く考える必要があります。これはこのモジュール (あるいは os モジュールにおける等価な機能) で生成される ファイルオブジェクトの場合にもあてはまります。

親プロセスが子プロセスの標準出力を読み出している一方で、子プロセスが 大量のデータを標準エラー出力に書き込んでいる場合、この子プロセスから 出力を読み出そうとするとデッドロックが発生します。 同様の状況は読み書きの他の組み合わせでも生じます。本質的な要因は、 一方のプロセスが別の プロセスでブロック型の読み出しをしている際に、_PC_PIPE_BUF バイトを超えるデータがブロック型の入出力を行うプロセスによって書き込ま れることにあります。

こうした状況を扱うには幾つかのやりかたがあります。

多くの場合、もっとも単純なアプリケーションに対する変更は、 親プロセスで以下のようなモデル:

import popen2

r, w, e = popen2.popen3('python slave.py')
e.readlines()
r.readlines()
r.close()
e.close()
w.close()

に従うようにし、子プロセスで以下:

import os
import sys

# note that each of these print statements
# writes a single long string

print >>sys.stderr, 400 * 'this is a test\n'
os.close(sys.stderr.fileno())
print >>sys.stdout, 400 * 'this is another test\n'

のようなコードにすることでしょう。

とりわけ、sys.stderr は全てのデータを書き込んた後に閉じ られなければならないということに注意してください。さもなければ、 readlines() は返ってきません。また、 sys.stderr.close() が stderr を閉じないように os.close() を使わなければならないことにも注意してください。 (そうでなく、sys.stderr に関連付けると、暗黙のうちに閉じられて しまうので、それ以降のエラーが出力されません)。

より一般的なアプローチををサポートする必要があるアプリケーションでは、 パイプ経由の I/O を select() ループでまとめるか、 個々の popen*() 関数や Popen* クラスが提供する各々のファイルに対して、個別のスレッドを使って 読み出しを行います。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.8.1 Popen3 および Popen4 Up: 6.8 popen2 Next: 6.9 datetime


6.9 datetime -- 基本的な日付型および時間型

バージョン2.3 以降で新規追加された 仕様です。

datetime モジュールでは、日付や時間データを簡単な方法と 複雑な方法の両方で操作するためのクラスを提供しています。 日付や時刻を対象にした四則演算がサポートされている一方で、 このモジュールの実装では出力の書式化や操作を目的とした データメンバの効率的な取り出しに焦点を絞っています。

日付および時刻オブジェクトには、``naive'' および ``aware'' の 2種類があります。この区別はオブジェクトがタイムゾーン や夏時間、あるいはその他のアルゴリズム的、政治的な理由に よる時刻の修正に関する何らかの表記をもつかどうかによるものです。 特定の数字がメートルか、マイルか、質量を表すかといったことが プログラムの問題であるように、 naive な datetime オブジェクトが標準世界時 (UTC: Coordinated Universal time) を表現するか、ローカルの時刻を表現するか、 ありは他のいずれかのタイムゾーンにおける時刻を表現するかは 純粋にプログラムの問題となります。 naive な datetime オブジェクトは、 現実世界のいくつかの側面を無視するという犠牲のもとに、 理解しやすく、かつ利用しやすくなっています。

より多くの情報を必要とするアプリケーションのために、 datetime および time オブジェクトはオプションの タイムゾーン情報メンバ、tzinfo を持っています。このメンバ には抽象クラス tzinfo のサブクラスのインスタンスが入って います。tzinfo オブジェクトは UTC 時刻からのオフセット、 タイムゾーン名、夏時間が有効になっているかどうか、といった情報 を記憶しています。 datetime モジュールでは具体的な tsinfo クラスを 提供していないので注意してください。必要な詳細仕様を備えた タイムゾーン機能を提供するのはアプリケーションの責任です。 世界各国における時刻の修正に関する法則は合理的というよりも政治的な ものであり、全てのアプリケーションに適した標準というものが 存在しないのです。

datetime モジュールでは以下の定数を公開しています:

MINYEAR
date や datetime オブジェクトで許されている、 年を表現する最小の数字です。MINYEAR は 1 です。

MAXYEAR
date や datetime オブジェクトで許されている、 年を表現する最大の数字です。MAXYEAR は 9999 です。

参考資料:

calendarモジュール:
汎用のカレンダー関連関数。.
timeモジュール:
時刻へのアクセスと変換。.

  • 6.9.1 利用可能なデータ型
  • 6.9.2 timedelta オブジェクト
  • 6.9.3 date オブジェクト
  • 6.9.4 datetime オブジェクト
  • 6.9.5 time オブジェクト
  • 6.9.6 tzinfo オブジェクト
  • 6.9.7 strftime() の振る舞い
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.8.2 フロー制御の問題 Up: 6. 汎用オペレーティングシステムサービス Next: 6.9.1 利用可能なデータ型


6.9.1 利用可能なデータ型

class date
理想化された naive な日付表現で、実質的には、これまでもこれからも 現在のグレゴリ暦 (Gregorian calender) であると仮定しています。 属性: year、 month、および day。

class time
理想化された時刻表現で、あらゆる特定の日における影響から独立 しており、毎日厳密に 24*60*60 秒であると仮定します ("うるう秒: leap seconds" の概念はありません)。 属性: hour、 minute、second、 microsecond、 および tzinfo。

class datetime
日付と時刻を組み合わせたもの。 属性: year、 month、 day、 hour、 minute、 second、 microsecond、および tzinfo。

class timedelta
date、time、あるいは datetime クラスの 二つのインスタンス間の時間差をマイクロ秒精度で表す経過時間値です。

class tzinfo
タイムゾーン情報オブジェクトの抽象基底クラスです。 datetime および time クラスで用いられ、 カスタマイズ可能な時刻修正の概念 (たとえばタイムゾーンや 夏時間の計算）を提供します。

これらの型のオブジェクトは変更不可能 (immutable) です。

date 型のオブジェクトは常に naive です。

time や datetime 型のオブジェクト d は naive にも aware にもできます。d は d.tzinfo が None でなく、かつ d.tzinfo.utcoffset(d) が None を返さない場合に aware となります。d.tzinfo が None の場合や、d.tzinfo は None では ないが d.tzinfo.utcoffset(d) が None を 返す場合には、d は naive となります。

naive なオブジェクトと aware なオブジェクトの区別は timedelta オブジェクトにはあてはまりません。

サブクラスの関係は以下のようになります:

object
    timedelta
    tzinfo
    time
    date
        datetime

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.9 datetime Up: 6.9 datetime Next: 6.9.2 timedelta オブジェクト


6.9.2 timedelta オブジェクト

timedelta オブジェクトは経過時間、すなわち二つの日付 や時刻間の差を表します。

class timedelta( days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)

全ての引数がオプションです。引数は整数、長整数、浮動小数点数に することができ、正でも負でもかまいません。

days、seconds および microseconds のみが 内部に記憶されます。引数は以下のようにして変換されます:

  • 1 ミリ秒は 1000 マイクロ秒に変換されます。
  • 1 分は 60 秒に変換されます。
  • 1 時間は 3600 秒に変換されます。
  • 1 週間は 7 日に変換されます。

その後、日、秒、マイクロ秒は値が一意に表されるように、

  • 0 <= microseconds < 1000000
  • 0 <= seconds < 3600*24 (一日中の秒数)
  • -999999999 <= days <= 999999999

で正規化されます。

引数のいずれかが浮動小数点であり、小数のマイクロ秒が存在する場合、 小数のマイクロ秒は全ての引数から一度取り置かれ、それらの和は 最も近いマイクロ秒に丸められます。浮動小数点の引数がない場合、 値の変換と正規化の過程は厳密な (失われる情報がない) ものとなります。

日の値を正規化した結果、指定された範囲の外側になった場合には、 OverflowError が送出されます。

負の値を正規化すると、一見混乱するような値になります。 例えば、

>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)

クラス属性を以下に示します:

min
最小の値を表す timedelta オブジェクトで、 timedelta(-999999999) です。

max
最大の値を表す timedelta オブジェクトで、 timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999) です。

resolution
timedelta オブジェクトが等しくならない最小の 時間差で、timedelta(microseconds=1) です。

正規化のために、timedelta.max >-timedelta.min となるので注意してください。-timedelta.max は timedelta オブジェクトとして表現することができません。

以下に (読み出し専用の) インスタンス属性を示します:

属性 | 値
days | 両端値を含む -999999999 から 999999999 の間
seconds | 両端値を含む 0 から 86399 の間
microseconds | 両端値を含む 0 から 999999 の間

サポートされている操作を以下に示します:

演算 | 結果
t1 = t2 + t3 | t2 と t3 を加算します。演算後、 t1-t2 == t3 および t1-t3 == t2 は 真になります。 (1)
t1 = t2 - t3 | t2 と t3 の差分です。演算後、 t1 == t2 - t3 および t2 == t1 + t3 は 真になります。 (1)
t1 = t2 * i or t1 = i * t2 | 整数や長整数による乗算です。演算後、 t1 // i == t2 は i != 0 であれば真となります。
 | 一般的に、 t1 * i == t1 * (i-1) + t1 は真となります。(1)
t1 = t2 // i | 端数を切り捨てて除算され、剰余 (がある場合) は捨てられます。(3)
+t1 | 同じ値を持つtimedelta オブジェクトを返します。(2)
-t1 | timedelta(-t1.days, -t1.seconds, -t1.microseconds)、および t1* -1 と同じです。 (1)(4)
abs(t) | t.days >= 0 のときには +t 、t.days < 0 の ときには -t となります。(2)
注釈:

(1)
この操作は厳密ですが、オーバフローするかもしれません。

(2)
この操作は厳密であり、オーバフローしないはずです。

(3)
0 による除算は ZeroDivisionError を送出します。

(4)
-timedelta.max は timedelta オブジェクトで表現することができません。

上に列挙した操作に加えて、timedelta オブジェクトは date および datetime オブジェクトとの間で 加減算をサポートしています (下を参照してください)。

timedelta オブジェクト間の比較はサポートされており、 より小さい経過時間を表す timedelta オブジェクトが より小さい timedelta と見なされます。 型混合の比較がデフォルトのオブジェクトアドレス比較となってしまう のを抑止するために、timedelta オブジェクトと異なる型の オブジェクトが比較されると、比較演算子が == または != でないかぎり TypeError が送出されます。 後者の場合、それぞれ False または True を返します。

timedelta オブジェクトはハッシュ可能 (辞書のキーとして利用可能) であり、効率的な pickle 化をサポートします、また、ブール演算コンテキスト では、 timedelta オブジェクトは timedelta(0) に等しくない 場合かつそのときに限り真となります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.9.1 利用可能なデータ型 Up: 6.9 datetime Next: 6.9.3 date オブジェクト


6.9.3 date オブジェクト

date オブジェクトは日付 (年、月、および日) を表します。 日付は理想的なカレンダー、すなわち現在のグレゴリ暦を過去と未来の 両方向に無限に延長したもので表されます。1 年の 1 月 1 日は日番号 1、 1 年 1 月 2 日は日番号 2、となっていきます。この暦法は、 全ての計算における基本カレンダーである、 Dershowitz と Reingold の書籍 Calendrical Calculations における "予期的グレゴリ (proleptic Gregorian)" 暦の定義に一致します。

class date( year, month, day)
全ての引数が必要です。引数は整数でも長整数でもよく、以下の範囲に 入らなければなりません:

  • MINYEAR <= year <= MAXYEAR
  • 1 <= month <= 12
  • 1 <= day <= 指定された月と年における日数

範囲を超えた引数を与えた場合、ValueError が送出 されます。

他のコンストラクタ、および全てのクラスメソッドを以下に示します:

today( )
現在のローカルな日付を返します。 date.fromtimestamp(time.time()) と等価です。

fromtimestamp( timestamp)
time.time() が返すような POSIX タイムスタンプ に対応する、ローカルな日付を返します。 タイムスタンプがプラットフォームにおける C 関数 localtime() でサポートされている範囲を超えている場合には ValueError を送出することがあります。 この値はよく 1970 年から 2038 年に制限されていることがあります。 うるう秒がタイムスタンプの概念に含まれている非 POSIX システム では、fromtimestamp() はうるう秒を無視します。

fromordinal( ordinal)
予期的グレゴリ暦順序に対応する日付を表し、1 年 1 月 1 日が序数 1 となります。1 <= ordinal <= date.max.toordinal() でない場合、ValueError が送出されます。 任意の日付 d に対し、 date.fromordinal(d.toordinal()) == d となります。

以下にクラス属性を示します:

min
表現できる最も古い日付で、date(MINYEAR, 1, 1) です。

max
表現できる最も新しい日付で、 date(MAXYEAR, 12, 31) です。

resolution
等しくない日付オブジェクト間の最小の差で、 timedelta(days=1) です。

以下に (読み出し専用の) インスタンス属性を示します:

year
両端値を含む MINYEAR から MAXYEAR までの値です。

month
両端値を含む 1 から 12 までの値です。

day
1 から与えられた月と年における日数までの値です。

サポートされている操作を以下に示します:

演算 | 結果
date2 = date1 + timedelta | date2 はから date1 から timedelta.days 日 移動した日付です。 (1)
date2 = date1 - timedelta | date2 + timedelta == date1 であるような日付 date2 を計算します。 (2)
timedelta = date1 - date2 | (3)
date1<date2 | date1 が時刻として date2 よりも前を表す場合に、 date1 はdate2 よりも小さいと見なされます。 (4)

注釈:

(1)
date2 は timedelta.days > 0 の場合進む方向に、 timedelta.days < 0 の場合戻る方向に移動します。 演算後は、date2 - date1 == timedelta.days となります。 timedelta.seconds および timedelta.microseconds は無視されます。 date2.year が MINYEAR になってしまったり、 MAXYEAR より大きくなってしまう場合には OverflowError が送出されます。

(2)
この操作は date1 + (-timedelta) と等価ではありません。なぜならば、 date1 - timedeltaがオーバフローしない場合でも、-timedelta 単体が オーバフローする可能性があるからです。 timedelta.seconds および timedelta.microseconds は無視されます。

(3)
この演算は厳密で、オーバフローしません。timedelta.seconds および timedelta.microseconds は 0 で、演算後には date2 + timedelta == date1 となります。

(4)
別の言い方をすると、date1.toordinal() < date2.toordinal() であり、かつそのときに限り date1 < date2 となります。 型混合の比較がデフォルトのオブジェクトアドレス比較となってしまう のを抑止するために、timedelta オブジェクトと異なる型の オブジェクトが比較されると TypeError が送出されます。 しかしながら、被比較演算子のもう一方が timetuple 属性を 持つ場合には NotImplemented が返されます。 このフックにより、他種の日付オブジェクトに型混合比較を実装する チャンスを与えています。 そうでない場合、timedelta オブジェクトと異なる型の オブジェクトが比較されると、比較演算子が == または != でないかぎり TypeError が送出されます。 後者の場合、それぞれ False または True を返します。

date オブジェクトは辞書のキーとして用いることができます。 ブール演算コンテキストでは、全ての date オブジェクトは 真であるとみなされます。

以下にインスタンスメソッドを示します:

replace( year, month, day)
キーワード引数で指定されたデータメンバが置き換えられることを 除き、同じ値を持つ date オブジェクトを返します。 例えば、d == date(2002, 12, 31) とすると、 d.replace(day=26) == date(2000, 12, 26) となります。

timetuple( )
time.localtime() が返す形式のtime.struct_time を返します。 時間、分、および秒は 0 で、DST フラグは -1 になります。 d.timetuple() は time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), d.toordinal() - date(d.year, 1, 1).toordinal() + 1, -1)) と等価です。

toordinal( )
予測的グレゴリ暦における日付序数を返します。 1 年の 1 月 1 日が 序数 1 となります。任意の date オブジェクト d に ついて、 date.fromordinal(d.toordinal()) == d となります。

weekday( )
月曜日を 0、日曜日を 6 として、曜日を整数で返します。 例えば、 date(2002, 12, 4).weekday() == 2 であり、水曜日を示します。 isoweekday() も参照してください。

isoweekday( )
月曜日を 1、日曜日を 7 として、曜日を整数で返します。 例えば、 date(2002, 12, 4).weekday() == 3 であり、水曜日を示します。 weekday()、isocalendar() も参照してください。

isocalendar( )
3 要素のタプル (ISO 年、ISO 週番号、ISO 曜日) を返します。

ISO カレンダーはグレゴリ暦の変種として広く用いられています。 細かい説明については http://www.phys.uu.nl/~vgent/calendar/isocalendar.htmを参照してください。

ISO 年は完全な週が 52 または 53 週あり、週は月曜から始まって日曜に 終わります。ISO 年でのある年における最初の週は、その年の木曜日を含む 最初の (グレゴリ暦での) 週となります。この週は週番号 1 と呼ばれ、 この木曜日での ISO 年はグレゴリ暦における年と等しくなります。

例えば、2004 年は木曜日から始まるため、ISO 年の最初の週は 2003 年 12 月 29 日、月曜日から始まり、2004 年 1 月 4 日、日曜日に 終わります。従って、 date(2003, 12, 29).isocalendar() == (2004, 1, 1) であり、かつ date(2004, 1, 4).isocalendar() == (2004, 1, 7) となります。

isoformat( )
ISO 8601 形式、'YYYY-MM-DD' の日付を表す文字列を返します。 例えば、 date(2002, 12, 4).isoformat() == '2002-12-04' となります。

__str__( )
date オブジェクト d において、 str(d) は d.isoformat() と等価です。

ctime( )
日付を表す文字列を、例えば date(2002, 12, 4).ctime() == 'Wed Dec 4 00:00:00 2002' のようにして返します。 ネイティブの C 関数 ctime() (time.ctime() はこの関数を呼び出しますが、 date.ctime() は呼び出しません) が C 標準に準拠 しているプラットフォームでは、 d.ctime() は time.ctime(time.mktime(d.timetuple())) と等価です。

strftime( format)
明示的な書式化文字列で制御された、日付を表現する文字列を返します。 時間、分、秒を表す書式化コードは値 0 になります。 strftime() のふるまいについてのセクションを参照して ください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.9.2 timedelta オブジェクト Up: 6.9 datetime Next: 6.9.4 datetime オブジェクト


6.9.4 datetime オブジェクト

datetime オブジェクトは date オブジェクトおよび time オブジェクトの全ての情報が入っている単一のオブジェクト です。date オブジェクトと同様に、datetime は 現在のグレゴリ暦が両方向に延長されているものと仮定します; また、time オブジェクトと同様に、datetime は 毎日が厳密に 3600*24 秒であると仮定します。

以下にコンストラクタを示します:

class datetime( year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None)
年、月、および日の引数は必須です。tzinfo は None または tzinfo クラスのサブクラスのインスタンス にすることができます。残りの引数は整数または長整数で、 以下のような範囲に入ります:

  • MINYEAR <= year <= MAXYEAR
  • 1 <= month <= 12
  • 1 <= day <= 与えられた年と月における日数
  • 0 <= hour < 24
  • 0 <= minute < 60
  • 0 <= second < 60
  • 0 <= microsecond < 1000000

引数がこれらの範囲外にある場合、 ValueError が送出されます。

その他のコンストラクタ、およびクラスメソッドを以下に示します:

today( )
現在のローカルな datetime を tzinfo が None であるものとして返します。 これは datetime.fromtimestamp(time.time()) と等価です。 now()、 fromtimestamp() も参照してください。

now(tz=None)( )
現在のローカルな日付および時刻を返します。オプションの引数 tz が None であるか指定されていない場合、この メソッドは today() と同様ですが、可能ならば time.time() タイムスタンプを通じて得ることができる より高い精度で時刻を提供します (例えば、プラットフォームが C 関数 gettimeofday() をサポートする場合には可能なことがあります)。

そうでない場合、tz はクラス tzinfo のサブクラスの インスタンスでなければならず、現在の日付および時刻は tz のタイムゾーンに変換されます。この場合、結果は tz.fromutc(datetime.utcnow().replace(tzinfo=tz)) と等価になります。 today(), utcnow() も参照してください。

utcnow( )
現在の UTC における日付と時刻を、 tzinfo が None で あるものとして返します。このメソッドは now() に似ていますが、 現在の UTC における日付と時刻を naive な datetime オブジェクト として返します。now() も参照してください。

fromtimestamp( timestamp, tz=None)
time.time() が返すような、POSIX タイムスタンプに 対応するローカルな日付と時刻を返します。 オプションの引数 tz が None であるか、指定されて いない場合、タイムスタンプはプラットフォームのローカルな日付および 時刻に変換され、返される datetime オブジェクトは naive なものになります。

そうでない場合、 tz はクラス tzinfo のサブクラスの インスタンスでなければならず、現在の日付および時刻は tz のタイムゾーンに変換されます。この場合、結果は tz.fromutc(datetime.utcfromtimestamp(timestamp).replace(tzinfo=tz)) と等価になります。

タイムスタンプがプラットフォームの C 関数 localtime() や gmtime() でサポートされている範囲を超えた場合、 fromtimestamp() は ValueError を送出する ことがあります。この範囲はよく 1970 年から 2038 年に制限されて います。 うるう秒がタイムスタンプの概念に含まれている非 POSIX システム では、fromtimestamp() はうるう秒を無視します。 このため、秒の異なる二つのタイムスタンプが同一の datetime オブジェクトとなることが起こり得ます。 utcfromtimestamp() も参照してください。

utcfromtimestamp( timestamp)
time.time() が返すような POSIX タイムスタンプ に対応する、UTC での datetime オブジェクトを返します。 タイムスタンプがプラットフォームにおける C 関数 localtime() でサポートされている範囲を超えている場合には ValueError を送出することがあります。 この値はよく 1970 年から 2038 年に制限されていることがあります。 fromtimestamp() も参照してください。

fromordinal( ordinal)
1 年 1 月 1 日を序数 1 とする予測的グレゴリ暦序数に対応する datetime オブジェクトを返します。 1 <= ordinal <= datetime.max.toordinal() でないかぎり ValueError が送出されます。結果として返される オブジェクトの時間、分、秒、およびマイクロ秒はすべて 0 となり、 tzinfo は None となります。

combine( date, time)
与えられた date オブジェクトと同じデータメンバを持ち、 時刻と tzinfo メンバが与えられた time オブジェクト と等しい、新たな datetime オブジェクトを返します。 任意の datetime オブジェクト d について、 d == datetime.combine(d.date(), d.timetz()) となります。date が datetime オブジェクトの場合、 その時刻と tzinfo は無視されます。

以下にクラス属性を示します:

min
表現できる最も古い datetime で、 datetime(MINYEAR, 1, 1, tzinfo=None) です。

max
表現できる最も新しい datetime で、 datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None) です。

resolution
等しくない datetime オブジェクト間の最小の差で、 timedelta(microseconds=1) です。

以下に (読み出し専用の) インスタンス属性を示します:

year
両端値を含む MINYEAR から MAXYEAR までの値です。

month
両端値を含む 1 から 12 までの値です。

day
1 から与えられた月と年における日数までの値です。

hour
range(24) 内の値です。

minute
range(60) 内の値です。

second
range(60) 内の値です。

microsecond
range(1000000) 内の値です。

tzinfo
datetime コンストラクタに tzinfo 引数として 与えられたオブジェクトになり、何も渡されなかった場合には None になります。

以下にサポートされている演算を示します:

演算 | 結果
datetime2 = datetime1 + timedelta | (1)
datetime2 = datetime1 - timedelta | (2)
timedelta = datetime1 - datetime2 | (3)
datetime1 < datetime2 | datetime を datetime と比較します。 (4)

(1)

datetime2 は datetime1 から時間 timedelta 移動したもので、 timedelta.days > 0 の場合進む方向に、 timedelta.days < 0 の場合戻る方向に移動します。 結果は入力の datetime と同じ tzinfo を持ち、 演算後には datetime2 - datetime1 == timedelta となります。 datetime2.year が MINYEAR よりも小さいか、 MAXYEAR より大きい場合には OverflowError が送出されます。 入力が aware なオブジェクトの場合でもタイムゾーン修正は全く行われ ません。

(2)
datetime2 + timedelta == datetime1 となるような datetime2 を 計算します。ちなみに、結果は入力の datetime と同じ tzinfo メンバを持ち、入力が aware でもタイムゾーン修正は全く行われ ません。 この操作は date1 + (-timedelta) と等価ではありません。なぜならば、 date1 - timedeltaがオーバフローしない場合でも、-timedelta 単体が オーバフローする可能性があるからです。

(3)
datetime から datetime の減算は両方の被演算子が naive であるか、両方とも aware である場合にのみ定義されています 片方が aware でもう一方が naive の場合、 TypeError が送出されます。

両方とも naive か、両方とも aware で同じ tzinfo メンバ を持つ場合、tzinfo メンバは無視され、結果は datetime2 + t == datetime1 であるような timedelta オブジェクト t となります。 この場合タイムゾーン修正は全く行われません。

両方が aware で異なる tzinfo メンバを持つ場合、 a-b は a および b をまず naive な UTC datetime オブジェクトに変換したかのようにして行います。演算結果は 決してオーバフローを起こさないことを除き、 (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset()) と同じになります。

(4)
datetime1 が時刻として datetime2 よりも前を表す場合に、 datetime1 はdatetime2 よりも小さいと見なされます。

被演算子の片方が naive でもう一方が aware の場合、 TypeError が送出されます。両方の被演算子が aware で、 同じ tzinfo メンバを持つ場合、共通の tzinfo メンバは無視され、基本の datetime 間の比較が行われます。 両方の被演算子が aware で異なる tzinfo メンバを持つ 場合、被演算子はまず (self.utcoffset() で得られる) UTC オフセット で修正されます。 注意: 型混合の比較がデフォルトのオブジェクトアドレス比較となってしまう のを抑止するために、被演算子のもう一方が datatime オブジェクトと 異なる型のオブジェクトの場合には TypeError が送出されます。 しかしながら、被比較演算子のもう一方が timetuple 属性を 持つ場合には NotImplemented が返されます。 このフックにより、他種の日付オブジェクトに型混合比較を実装する チャンスを与えています。 そうでない場合、datetime オブジェクトと異なる型の オブジェクトが比較されると、比較演算子が == または != でないかぎり TypeError が送出されます。 後者の場合、それぞれ False または True を返します。

datetime オブジェクトは辞書のキーとして用いることができます。 ブール演算コンテキストでは、全ての datetime オブジェクトは 真であるとみなされます。

インスタンスメソッドを以下に示します:

date( )
同じ年、月、日の date オブジェクトを返します。

time( )
同じ時、分、秒、マイクロ秒を持つ time オブジェクトを返します。 tzinfo は None です。timetz() も参照 してください。

timetz( )
同じ時、分、秒、マイクロ秒、および tzinfo メンバを持つ time オブジェクトを返します。 time() メソッドも参照してください。

replace( year=, month=, day=, hour=, minute=, second=, microsecond=, tzinfo=)
キーワード引数で指定したメンバの値を除き、同じ値をもつ datetime オブジェクトを返します。 メンバに対する変換を行わずに aware な datetime オブジェクトから naive な datetime オブジェクトを生成するために、 tzinfo=None を指定することもできます。

astimezone( tz)
datetime オブジェクトを返します。返されるオブジェクトは 新たな tzinfo メンバ tz を持ちます。tz は日付および時刻を調整して、オブジェクトが self と同じ UTC 時刻を持つが、tz におけるローカルな時刻を表すようにします。

tz は tzinfo のサブクラスのインスタンスでなければ ならず、インスタンスの utcoffset() および dst() メソッドは None を返してはなりません。self は aware でなくてはなりません (self.tzinfo が None であってはならず、かつ self.utcoffset() は None を返してはなりません)。

self.tzinfo が tz の場合、 self.astimezone(tz) は self に等しくなります: 日付および時刻データメンバに対する調整は行われません。 そうでない場合、結果はタイムゾーン tz におけるローカル時刻で、 self と同じ UTC 時刻を表すようになります: astz = dt.astimezone(tz) とした後、 astz - astz.utcoffset() は通常 dt - dt.utcoffset() と同じ日付および時刻 データメンバを持ちます。 tzinfo クラスに関する議論では、夏時間 (Daylight Saving time) の遷移境界では上の等価性が成り立たないことを説明しています (tz が標準時と夏時間の両方をモデル化している場合のみの問題です)。

単にタイムゾーンオブジェクト tz を datetime オブジェクト dt に追加したいだけで、日付や時刻データメンバへの調整 を行わないのなら、dt.replace(tzinfo=tz) を使って ください。 単に aware な datetime オブジェクト dt からタイムゾーン オブジェクトを除去したいだけで、日付や時刻データメンバの変換を 行わないのなら、dt.replace(tzinfo=None) を使ってください。

デフォルトの tzinfo.fromutc() メソッドを tzinfo のサブクラスで上書きして、astimezone() が返す結果に 影響を及ぼすことができます。エラーの場合を無視すると、 astimezone() は以下のように動作します:

  def astimezone(self, tz):
      if self.tzinfo is tz:
          return self
      # Convert self to UTC, and attach the new time zone object.
      utc = (self - self.utcoffset()).replace(tzinfo=tz)
      # Convert from UTC to tz's local time.
      return tz.fromutc(utc)

utcoffset( )
tzinfo が None の場合、None を返し、 そうでない場合には self.tzinfo.utcoffset(self) を返します。後者の式が None か、1 日以下の大きさを持つ 経過時間を表す timedelta オブジェクトのいずれかを返さない 場合には例外を送出します。

dst( )
tzinfo が None の場合、None を返し、 そうでない場合には self.tzinfo.dst(self) を返します。後者の式が None か、1 日以下の大きさを持つ 経過時間を表す timedelta オブジェクトのいずれかを返さない 場合には例外を送出します。

tzname( )
tzinfo が None の場合、None を返し、 そうでない場合には self.tzinfo.tzname(self) を返します。後者の式が None か文字列オブジェクトのいずれか を返さない場合には例外を送出します。

timetuple( )
time.localtime() が返す形式の time.struct_time を返します。 d.timetuple() は time.struct_time((d.year, d.month, d.day, d.hour, d.minute, d.second, d.weekday(), d.toordinal() - date(d.year, 1, 1).toordinal() + 1, dst)) と等価です。 返されるタプルの tm_isdst フラグは dst() メソッドに 従って設定されます: tzinfo が None か dst() が None を返す場合、 tm_isdst は -1 に設定されます; そうでない場合、 dst() がゼロでない値を返すと、tm_isdst は 1 となります; それ以外の場合には tm_isdst は0 に設定 されます。

utctimetuple( )
datetime インスタンス d が naive の場合、このメソッドは d.timetuple() と同じであり、d.dst() の返す内容に かかわらず tm_isdst が 0 に強制される点だけが異なります。 DST が UTC 時刻に影響を及ぼすことは決してありません。

d が aware の場合、d から d.utcoffset() が差し 引かれて UTC 時刻に正規化され、正規化された時刻の time.struct_time を返します。tm_isdst は 0 に強制されます。 d.year が MINYEAR や MAXUEAR で、UTC への修正の結果 表現可能な年の境界を越えた場合には、戻り値の tm_year メンバは MINYEAR-1 または MAXYEAR+1 になることがあります。

toordinal( )
予測的グレゴリ暦における日付序数を返します。 self.date().toordinal() と同じです。

weekday( )
月曜日を 0、日曜日を 6 として、曜日を整数で返します。 self.date().weekday() と同じです。 isoweekday() も参照してください。

isoweekday( )
月曜日を 1、日曜日を 7 として、曜日を整数で返します。 self.date().isoweekday() と等価です。 weekday()、 isocalendar() も参照してください。

isocalendar( )
3 要素のタプル (ISO 年、ISO 週番号、ISO 曜日) を返します。 self.date().isocalendar() と等価です。

isoformat( sep='T')
日付と時刻を ISO 8601 形式、すなわち YYYY-MM-DDTHH:MM:SS.mmmmmm か、 microsecond が 0 の場合には YYYY-MM-DDTHH:MM:SS で表した文字列を返します。 utcoffset() が None を返さない場合、 UTC からのオフセットを時間と分を表した (符号付きの) 6 文字からなる 文字列が追加されます: すなわち、 YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM となるか、 microsecond が ゼロの場合には YYYY-MM-DDTHH:MM:SS+HH:MM となります。 オプションの引数 sep (デフォルトでは 'T' です) は 1 文字のセパレータで、結果の文字列の日付と時刻の間に置かれます。 例えば、

>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     def utcoffset(self, dt): return timedelta(minutes=-399)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
となります。

__str__( )
datetime オブジェクト d において、 str(d) は d.isoformat(' ') と等価です。

ctime( )
日付を表す文字列を、例えば datetime(2002, 12, 4, 20, 30, 40).ctime() == 'Wed Dec 4 20:30:40 2002' のようにして返します。 ネイティブの C 関数 ctime() (time.ctime() はこの関数を呼び出しますが、 datetime.ctime() は呼び出しません) が C 標準に準拠 しているプラットフォームでは、 d.ctime() は time.ctime(time.mktime(d.timetuple())) と等価です。

strftime( format)
明示的な書式化文字列で制御された、日付を表現する文字列を返します。 strftime() のふるまいについてのセクションを参照して ください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.9.3 date オブジェクト Up: 6.9 datetime Next: 6.9.5 time オブジェクト


6.9.5 time オブジェクト

time オブジェクトは (ローカルの) 日中時刻を表現します。 この時刻表現は特定の日の影響を受けず、tzinfo オブジェクト を介した修正の対象となります。

class time( hour=0, minute=0, second=0, microsecond=0, tzinfo=None)
全ての引数はオプションです。tzinfo は None または tzinfo クラスのサブクラスのインスタンス にすることができます。残りの引数は整数または長整数で、 以下のような範囲に入ります:

  • 0 <= hour < 24
  • 0 <= minute < 60
  • 0 <= second < 60
  • 0 <= microsecond < 1000000.

引数がこれらの範囲外にある場合、 ValueError が送出されます。

以下にクラス属性を示します:

min
表現できる最も古い datetime で、 time(0, 0, 0, 0) です。 The earliest representable time, time(0, 0, 0, 0).

max
表現できる最も新しい datetime で、 time(23, 59, 59, 999999, tzinfo=None) です。

resolution
等しくない datetime オブジェクト間の最小の差で、 timedelta(microseconds=1) ですが、time オブジェクト間の四則演算はサポートされて いないので注意してください。

以下に (読み出し専用の) インスタンス属性を示します:

hour
range(24) 内の値です。

minute
range(60) 内の値です。

second
range(60) 内の値です。

microsecond
range(1000000) 内の値です。

tzinfo
time コンストラクタに tzinfo 引数として 与えられたオブジェクトになり、何も渡されなかった場合には None になります。

以下にサポートされている操作を示します:

  • time と time の比較では、a が時刻として b よりも前を表す場合に a は b よりも小さいと見なされます。 被演算子の片方が naive でもう一方が aware の場合、 TypeError が送出されます。両方の被演算子が aware で、 同じ tzinfo メンバを持つ場合、共通の tzinfo メンバは無視され、基本の datetime 間の比較が行われます。 両方の被演算子が aware で異なる tzinfo メンバを持つ 場合、被演算子はまず (self.utcoffset() で得られる) UTC オフセット で修正されます。 型混合の比較がデフォルトのオブジェクトアドレス比較となってしまう のを抑止するために、time オブジェクトが他の型のオブジェクトと 比較された場合、比較演算子が == または != でないかぎり TypeError が送出されます。 後者の場合、それぞれ False または True を返します。

  • ハッシュ化、辞書のキーとしての利用

  • 効率的な pickle 化

  • ブール演算コンテキストでは、time オブジェクトは、 分に変換し、utfoffset() (None を返した場合には 0) を差し引いて変換した後の結果がゼロでない場合、かつその ときに限って真とみなされます。

以下にインスタンスメソッドを示します:

replace( ()
hour=, minute=, second=, microsecond=, tzinfo=) キーワード引数で指定したメンバの値を除き、同じ値をもつ time オブジェクトを返します。 メンバに対する変換を行わずに aware な datetime オブジェクトから naive な time オブジェクトを生成するために、 tzinfo=None を指定することもできます。

isoformat( )
日付と時刻を ISO 8601 形式、すなわち HH:MM:SS.mmmmmm か、 microsecond が 0 の場合には HH:MM:SS で表した文字列を返します。 utcoffset() が None を返さない場合、 UTC からのオフセットを時間と分を表した (符号付きの) 6 文字からなる 文字列が追加されます: すなわち、 HH:MM:SS.mmmmmm+HH:MM となるか、 microsecond が 0 の場合には HH:MM:SS+HH:MM となります。

__str__( )
time オブジェクト t において、 str(t) は t.isoformat() と等価です。

strftime( format)
明示的な書式化文字列で制御された、日付を表現する文字列を返します。 strftime() のふるまいについてのセクションを参照して ください。

utcoffset( )
tzinfo が None の場合、None を返し、 そうでない場合には self.tzinfo.utcoffset(None) を返します。後者の式が None か、1 日以下の大きさを持つ 経過時間を表す timedelta オブジェクトのいずれかを返さない 場合には例外を送出します。

dst( )
tzinfo が None の場合、None を返し、 そうでない場合には self.tzinfo.dst(None) を返します。後者の式が None か、1 日以下の大きさを持つ 経過時間を表す timedelta オブジェクトのいずれかを返さない 場合には例外を送出します。

tzname( )
tzinfo が None の場合、None を返し、 そうでない場合には self.tzinfo.tzname(None) を返します。後者の式が None か文字列オブジェクトのいずれか を返さない場合には例外を送出します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.9.4 datetime オブジェクト Up: 6.9 datetime Next: 6.9.6 tzinfo オブジェクト


6.9.6 tzinfo オブジェクト

tzinfo は抽象基底クラスです。つまり、このクラスは直接 インスタンス化して利用しません。具体的なサブクラスを導出し、 (少なくとも) 利用したい datetime のメソッドが必要と する tzinfo の標準メソッドを実装してやる必要があります。 datetime モジュールでは、tzinfo の具体的な サブクラスは何ら提供していません。

tzinfo (の具体的なサブクラス) のインスタンスは datetime および time オブジェクトのコンストラクタに 渡すことができます。 後者のオブジェクトでは、データメンバをローカル時刻におけるものとして 見ており、tzinfo オブジェクトはローカル時刻の UTC からの オフセット、タイムゾーンの名前、DST オフセットを、渡された 日付および時刻オブジェクトからの相対で示すためのメソッドを 提供します。

pickle 化についての特殊な要求事項: tzinfo のサブクラスは 引数なしで呼び出すことのできる __init__ メソッドを持たねば なりません。そうでなければ、pickle 化することはできますがおそらく unpickle 化することはできないでしょう。これは技術的な側面からの 要求であり、将来緩和されるかもしれません。

tzinfo の具体的なサブクラスでは、以下のメソッドを 実装する必要があります。厳密にどのメソッドが必要なのかは、 aware な datetime オブジェクトがこのサブクラスの インスタンスをどのように使うかに依存します。不確かならば、 単に全てを実装してください。

utcoffset( self, dt)
ローカル時間の UTC からのオフセットを、UTC から東向きを正とした分で 返します。ローカル時間が UTC の西側にある場合、この値は負になります。 このメソッドは UTC からのオフセットの総計を返すように意図されている ので注意してください; 例えば、 tzinfo オブジェクトが タイムゾーンと DST 修正の両方を表現する場合、utcoffset() はそれらの合計を返さなければなりません。UTC オフセットが未知である 場合、None を返してください。そうでない場合には、 返される値は -1439 から 1439 の両端を含む値 (1440 = 24*60 ; つまり、オフセットの大きさは 1 日より短くなくてはなりません) が分で指定された timedelta オブジェクトでなければなりません。 ほとんどの utcoffset() 実装は、おそらく以下の二つのうちの一つに 似たものになるでしょう:

    return CONSTANT                 # fixed-offset class
    return CONSTANT + self.dst(dt)  # daylight-aware class

utcoffset() が None を返さない場合、 dst() も None を返してはなりません。

utcoffset() のデフォルトの実装は NotImplementedError を送出します。

dst( self, dt)
夏時間 (DST) 修正を、UTC から東向きを正とした分で 返します。DST 情報が未知の場合、None が返されます。 DST が有効でない場合には timedelta(0) を返します。 DST が有効の場合、オフセットは timedelta オブジェクト で返します (詳細はutcoffset() を参照してください)。 DST オフセットが利用可能な場合、この値は utcoffset() が返すUTC からのオフセットには既に加算されているため、 DST を個別に取得する必要がない限り dst() を使って 問い合わせる必要はないので注意してください。 例えば、datetime.timetuple() は tzinfo メンバ の dst() メソッドを呼んで tm_isdst フラグが セットされているかどうか判断し、tzinfo.fromutc() は dst() タイムゾーンを移動する際に DST による変更 があるかどうかを調べます。

標準および夏時間の両方をモデル化している tzinfo サブクラスの インスタンス tz は以下の式:

tz.utcoffset(dt) - tz.dst(dt)

が、dt.tzinfo==tz 全ての datetime オブジェクト dt について常に同じ結果を返さなければならないという点で、 一貫性を持っていなければなりません。 正常に実装された tzinfo のサブクラスでは、この式は タイムゾーンにおける "標準オフセット (standard offset)" を表し、 特定の日や時刻の事情ではなく地理的な位置にのみ依存していなくては なりません。datetime.astimezone() の実装はこの事実に 依存していますが、違反を検出することができません; 正しく実装するのはプログラマの責任です。tzinfo の サブクラスでこれを保証することができない場合、tzinfo.fromutc() の実装をオーバライドして、astimezone() に関わらず 正しく動作するようにしてもかまいません。

ほとんどの dst() 実装は、おそらく以下の二つのうちの一つに 似たものになるでしょう:

    return timedelta(0)   # a fixed-offset class:  doesn't account for DST

  or

    # Code to set dston and dstoff to the time zone's DST transition
    # times based on the input dt.year, and expressed in standard local
    # time.  Then

    if dston <= dt.replace(tzinfo=None) < dstoff:
        return timedelta(hours=1)
    else:
        return timedelta(0)

デフォルトの dst() 実装は NotImplementedError を送出します。

tzname( self, dt)
datetime オブジェクト dt に対応するタイムゾーン名 を文字列で返します。 datetime モジュールでは文字列名について何も定義しておらず、 特に何かを意味するといった要求仕様もまったくありません。 例えば、"GMT"、"UTC"、 "-500"、 "-5:00"、 "EDT"、 "US/Eastern"、 "America/New York" は全て有効な応答となります。 文字列名が未知の場合には None を返してください。 tzinfo のサブクラスでは、 特に、tzinfo クラスが夏時間について記述している場合のように、 渡された dt の特定の値によって異なった名前を返したい 場合があるため、文字列値ではなくメソッドとなっていることに注意してください。

デフォルトの tzname() 実装は NotImplementedError を送出します。

以下のメソッドは datetime や time オブジェクトにおいて、 同名のメソッドが呼び出された際に応じて呼び出されます。datetime オブジェクトは自身を引数としてメソッドに渡し、time オブジェクトは 引数として None をメソッドに渡します。従って、tzinfo の サブクラスにおけるメソッドは引数 dt が None の場合と、 datetime の場合を受理するように用意しなければなりません。

None が渡された場合、最良の応答方法を決めるのはクラス設計者次第 です。例えば、このクラスが tzinfo プロトコルと関係をもたない ということを表明させたければ、None が適切です。 標準時のオフセットを見つける他の手段がない場合には、 標準 UTC オフセットを返すために utcoffset(None) を使うともっと便利かもしれません。

datetime オブジェクトが datetime メソッド の応答として返された場合、dt.tzinfo は self と同じオブジェクトになります。ユーザが直接 tzinfo メソッド を呼び出さないかぎり、tzinfo メソッドは dt.tzinfo と self が同じであることに依存します。 その結果 tzinfo メソッドは dt がローカル時間であると 解釈するので、他のタイムゾーンでのオブジェクトの振る舞いについて 心配する必要がありません。

fromutc( self, dt)
デフォルトの datetime.astimezone() 実装で呼び出されます。 datetime.astimezone() から呼ばれた場合、dt.tzinfo は self であり、 dt の日付および時刻データメンバは UTC 時刻を表しているものとして見えます。fromutc() の目的は、self のローカル時刻に等しい datetime オブジェクト を返すことにより日付と時刻データメンバを修正することにあります。

ほとんどの tzinfo サブクラスではデフォルトの fromutc() 実装を問題なく継承できます。デフォルトの実装は、固定オフセットのタイムゾーン や、標準時と夏時間の両方について記述しているタイムゾーン、そして DST 移行時刻が年によって異なる場合でさえ、扱えるくらい強力なものです。 デフォルトの fromutc() 実装が全ての場合に対して正しく 扱うことができないような例は、標準時の (UTCからの) オフセットが 引数として渡された特定の日や時刻に依存するもので、これは政治的な理由に よって起きることがあります。 デフォルトの astimezone() や fromutc() の実装は、 結果が標準時オフセットの変化にまたがる何時間かの中にある場合、 期待通りの結果を生成しないかもしれません。

エラーの場合のためのコードを除き、デフォルトの fromutc() の 実装は以下のように動作します:

  def fromutc(self, dt):
      # raise ValueError error if dt.tzinfo is not self
      dtoff = dt.utcoffset()
      dtdst = dt.dst()
      # raise ValueError if dtoff is None or dtdst is None
      delta = dtoff - dtdst  # this is self's standard offset
      if delta:
          dt += delta   # convert to standard local time
          dtdst = dt.dst()
          # raise ValueError if dtdst is None
      if dtdst:
          return dt + dtdst
      else:
          return dt

以下に tzinfo クラスの使用例を示します:

from datetime import tzinfo, timedelta, datetime

ZERO = timedelta(0)
HOUR = timedelta(hours=1)

# A UTC class.

class UTC(tzinfo):
    """UTC"""

    def utcoffset(self, dt):
        return ZERO

    def tzname(self, dt):
        return "UTC"

    def dst(self, dt):
        return ZERO

utc = UTC()

# A class building tzinfo objects for fixed-offset time zones.
# Note that FixedOffset(0, "UTC") is a different way to build a
# UTC tzinfo object.

class FixedOffset(tzinfo):
    """Fixed offset in minutes east from UTC."""

    def __init__(self, offset, name):
        self.__offset = timedelta(minutes = offset)
        self.__name = name

    def utcoffset(self, dt):
        return self.__offset

    def tzname(self, dt):
        return self.__name

    def dst(self, dt):
        return ZERO

# A class capturing the platform's idea of local time.

import time as _time

STDOFFSET = timedelta(seconds = -_time.timezone)
if _time.daylight:
    DSTOFFSET = timedelta(seconds = -_time.altzone)
else:
    DSTOFFSET = STDOFFSET

DSTDIFF = DSTOFFSET - STDOFFSET

class LocalTimezone(tzinfo):

    def utcoffset(self, dt):
        if self._isdst(dt):
            return DSTOFFSET
        else:
            return STDOFFSET

    def dst(self, dt):
        if self._isdst(dt):
            return DSTDIFF
        else:
            return ZERO

    def tzname(self, dt):
        return _time.tzname[self._isdst(dt)]

    def _isdst(self, dt):
        tt = (dt.year, dt.month, dt.day,
              dt.hour, dt.minute, dt.second,
              dt.weekday(), 0, -1)
        stamp = _time.mktime(tt)
        tt = _time.localtime(stamp)
        return tt.tm_isdst > 0

Local = LocalTimezone()

# A complete implementation of current DST rules for major US time zones.

def first_sunday_on_or_after(dt):
    days_to_go = 6 - dt.weekday()
    if days_to_go:
        dt += timedelta(days_to_go)
    return dt

# In the US, DST starts at 2am (standard time) on the first Sunday in April.
DSTSTART = datetime(1, 4, 1, 2)
# and ends at 2am (DST time; 1am standard time) on the last Sunday of Oct.
# which is the first Sunday on or after Oct 25.
DSTEND = datetime(1, 10, 25, 1)

class USTimeZone(tzinfo):

    def __init__(self, hours, reprname, stdname, dstname):
        self.stdoffset = timedelta(hours=hours)
        self.reprname = reprname
        self.stdname = stdname
        self.dstname = dstname

    def __repr__(self):
        return self.reprname

    def tzname(self, dt):
        if self.dst(dt):
            return self.dstname
        else:
            return self.stdname

    def utcoffset(self, dt):
        return self.stdoffset + self.dst(dt)

    def dst(self, dt):
        if dt is None or dt.tzinfo is None:
            # An exception may be sensible here, in one or both cases.
            # It depends on how you want to treat them.  The default
            # fromutc() implementation (called by the default astimezone()
            # implementation) passes a datetime with dt.tzinfo is self.
            return ZERO
        assert dt.tzinfo is self

        # Find first Sunday in April & the last in October.
        start = first_sunday_on_or_after(DSTSTART.replace(year=dt.year))
        end = first_sunday_on_or_after(DSTEND.replace(year=dt.year))

        # Can't compare naive to aware objects, so strip the timezone from
        # dt first.
        if start <= dt.replace(tzinfo=None) < end:
            return HOUR
        else:
            return ZERO

Eastern  = USTimeZone(-5, "Eastern",  "EST", "EDT")
Central  = USTimeZone(-6, "Central",  "CST", "CDT")
Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
Pacific  = USTimeZone(-8, "Pacific",  "PST", "PDT")
Download as text (original file name: tzinfo-examples.py).

標準時間 (standard time) および夏時間 (daylight time) の両方を 記述している tzinfo のサブクラスでは、回避不能の難解な問題が年に 2 度あるので注意してください。具体的な例として、東部アメリカ時刻 (US Eastern, UTC -5000) を考えます。EDT は 4 月の最初の日曜日 の 1:59 (EST) 以後に開始し、10 月の最後の日曜日の 1:59 (EDT) に 終了します:

    UTC   3:MM  4:MM  5:MM  6:MM  7:MM  8:MM
    EST  22:MM 23:MM  0:MM  1:MM  2:MM  3:MM
    EDT  23:MM  0:MM  1:MM  2:MM  3:MM  4:MM

  start  22:MM 23:MM  0:MM  1:MM  3:MM  4:MM

    end  23:MM  0:MM  1:MM  1:MM  2:MM  3:MM

DST の開始の際 ("start" の並び) ローカルの壁時計は 1:59 から 3:00 に飛びます。この日は 2:MM の形式をとる時刻は実際には無意味と なります。従って、astimezone(Eastern) は DST が開始する 日には hour==2 となる結果を返すことはありません。 astimezone() がこのことを保証するようにするには、 tzinfo.dst() メソッドは "失われた時間" (東部時刻における 2:MM) が夏時間に存在することを考えなければなりません。

DST が終了する際 ("end" の並び) では、問題はさらに悪化します: 1 時間の間、ローカルの壁時計ではっきりと時刻をいえなくなります: それは夏時間の最後の 1 時間です。東部時刻では、その日の UTC での 5:MM に夏時間は終了します。ローカルの壁時計は 1:59 (夏時間) から 1:00 (標準時) に再び巻き戻されます。ローカルの時刻に おける 1:MM はあいまいになります。astimezone() は二つの UTC 時刻を同じローカルの時刻に対応付けることで ローカルの時計の振る舞いをまねます。 東部時刻の例では、5:MM および 6:MM の形式をとる UTC 時刻は 両方とも、東部時刻に変換された際に 1:MM に対応づけられます。 astimezone() がこのことを保証するようにするには、 tzinfo.dst() は "繰り返された時間" が標準時に存在する ことを考慮しなければなりません。このことは、例えばタイムゾーンの標準の ローカルな時刻に DST への切り替え時刻を表現することで簡単に設定する ことができます。

このようなあいまいさを許容できないアプリケーションは、 ハイブリッドな tzinfo サブクラスを使って問題を回避しなければ なりません; UTC や、他のオフセットが固定された tzinfo の サブクラス (EST (-5 時間の固定オフセット) のみを表すクラスや、 EDT (-4 時間の固定オフセット) のみを表すクラス) を使う限り、あいまいさは 発生しません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.9.5 time オブジェクト Up: 6.9 datetime Next: 6.9.7 strftime() の振る舞い


6.9.7 strftime() の振る舞い

date、 datetime、および time オブジェクトは全て、明示的な書式化文字列でコントロールして 時刻表現文字列を生成するための strftime(format) メソッドを サポートしています。大雑把にいうと、d.strftime(fmt) は time モジュールの time.strftime(fmt, d.timetuple()) のように動作します。ただし全てのオブジェクトが timetuple() メソッドをサポートしているわけではありません。

time オブジェクトでは、年、月、日の値がないため、それらの 書式化コードを使うことができません。無理矢理使った場合、 年は 1900 に置き換えられ、月と日は 0 に置き換え られます。

date オブジェクトでは、時、分、秒の値がないため、 それらの書式化コードを使うことができません。無理矢理使った場合、 これらの値は 0 に置き換えられます。

naive オブジェクトでは、書式化コード %z および %Z は空文字列に置き換えられます。

aware オブジェクトでは以下のようになります:

%z
utcoffset() は +HHMM あるいは -HHMM の形式をもった 5 文字の文字列に変換されます。HH は UTC オフセット時間を与える 2 桁の文字列で、MM は UTC オフセット分を与える 2 桁の文字列です。 例えば、utcoffset() が timedelta(hours=-3, minutes=-30) を返した場合、%z は文字列 '-0330' に置き換わります。

%Z
tzname() が None を返した場合、%Z は 空文字列に置き換わります。そうでない場合、%Z は返された 値に置き換わりますが、これは文字列でなければなりません。

Python はプラットフォームの C ライブラリから strftime() 関数を呼び出し、プラットフォーム間のバリエーションはよくあることなので、 サポートされている書式化コードの全セットはプラットフォーム間で異なります。 Python の time モジュールのドキュメントでは、C 標準 (1989 年版) が要求する書式化コードをリストしており、これらのコードは 標準 C 準拠の実装がなされたプラットフォームでは全て動作します。 1999 年版の C 標準では書式化コードが追加されているので注意してください。

strftime() が正しく動作する年の厳密な範囲はプラットフォーム 間で異なります。プラットフォームに関わらず、1900 年以前の年は 使うことができません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.9.6 tzinfo オブジェクト Up: 6.9 datetime Next: 6.10 time


6.10 time -- 時刻データへのアクセスと変換

このモジュールでは、時刻に関するさまざまな関数を提供します。ほとんどの 関数が利用可能ですが、全ての関数が全てのプラットフォームで利用可能な わけではありません。 このモジュールで定義されているほとんどの関数は、プラットフォーム上の 同名の C ライブラリ関数を呼び出します。これらの関数に対する意味付け はプラットフォーム間で異なるため、プラットフォーム提供のドキュメント を読んでおくと便利でしょう。

まずいくつかの用語の説明と慣習について整理します。

  • エポック(epoch)は、 時刻の計測がはじまった時点のことです。その年の 1 月 1 日の午前 0 時に ``エポックからの経過時間'' が 0 になるように設定されます。Unixでは エポックは 1970 年です。エポックがどうなっているかを知るには、 gmtime(0) の値を見るとよいでしょう。

  • このモジュールの中の関数は、エポック以前あるいは遠い未来の日付や時刻を 扱うことができません。将来カットオフ（関数が正しく日付や時刻を扱えなく なる）が起きる時点は、C ライブラリによって決まります。 Unixではカットオフは通常 2038 です。

  • 2000年問題 (Y2K):Python はプラットフォームの C ライブラリに依存して います。C ライブラリは日付および時刻をエポックからの経過秒で表現する ので、一般的に 2000 年問題を持ちません。 時刻を表現するstruct_time（下記を参照してください）を入力として受け取る関数 は一般的に 4 桁表記の西暦年を要求します。以前のバージョンとの互換性の ために、モジュール変数 accept2dyear がゼロでない整数の場合、 2 桁の西暦年をサポートします。この変数の初期値は環境変数 PYTHONY2K が空文字列のとき 1 に設定されます。空文字列 でない文字列が設定されている場合、0 に設定されます。こうして、 PYTHONY2K を空文字列でない文字列に設定することで、西暦年の入力が すべて 4 桁の西暦年でなければならないようにすることができます。 2桁の西暦年が入力された場合には、POSIX または X/Open 標準に従って変換 されます: 69-99 の西暦年は 1969-1999 となり、0-68 の西暦年は 2000-2068 に なります。100-1899 は常に不正な値になります。この仕様は Python 1.5.2(a2) から新たに追加された機能であることに注意してください; それ以前のバージョン、すなわち Python 1.5.1 および 1.5.2a1 では、1900 以下の年に対して 1900 を足します。

  • UTCは協定世界時 (Coordinated Universal Time) のことです (以前はグリニッジ標準時 または GMTとして知られていました)。 UTC の 頭文字の並びは誤りではなく、英仏の妥協によるものです。

  • DST は夏時間 (Daylight Saving Time) のことで、一年のうち部分的に 1 時間 タイムゾーンを修正することです。DST のルールは不可思議で (局所的な法律 で定められています)、年ごとに変わることもあります。 C ライブラリはローカルルールを記したテーブルを持っており (柔軟に対応 するため、たいていはシステムファイルから読み込まれます)、この点に関して は唯一の真実の知識の源です。

  • 多くの現時刻を返す関数 (real-time functions) の精度は、値や引数を表現 するのに使う単位から想像されるよりも低いかも知れません。 例えば、ほとんどの Unix システムで、クロックの一刹那 (ticks) の 精度は 1 秒 の 50 から 100 分の 1 に過ぎません。また、Mac では時刻は 秒きっかりのとき以外正確ではありません。

  • 反対に、time() および sleep() は Unix の 同等の関数よりましな精度を持っています: 時刻は浮動小数点で表され、 time() は可能なかぎり最も正確な時刻を (Unix の gettimeofday() があればそれを使って) 返します。また sleep() にはゼロでない端数を与えることができます (Unix の select() があれば、それを使って実装しています)。

  • gmtime()、localtime()、strptime() が返す時刻値、 および asctime()、mktime()、 strftime() に与える時刻値はどちらも 9 つの整数からなる 配列です。

    Index | Attribute | Values
    0 | tm_year | (例えば 1993)
    1 | tm_mon | [1,12] の間の数
    2 | tm_mday | [1,31] の間の数
    3 | tm_hour | [0,23] の間の数
    4 | tm_min | [0,59] の間の数
    5 | tm_sec | [0,61] の間の数 strftime() の説明にある (1) を読んで下さい
    6 | tm_wday | [0,6] の間の数、月曜が 0 になります
    7 | tm_yday | [1,366] の間の数
    8 | tm_isdst | 0, 1 または -1; 以下を参照してください

    C の構造体と違って、月の値が 0-11 でなく 1-12 であることに注意してくだ さい。西暦年の値は上の ''2000年問題 (Y2K) '' で述べたように扱われます。 夏時間フラグを -1 にして mktime() に渡すと、たいてい は正確な夏時間の状態を実現します。

    struct_time を引数とする関数に正しくない長さのstruct_timeや 要素の型が正しくないstruct_timeを与えた場合には、TypeError が送出されます。

    バージョン2.2 以降で変更された 仕様: 時刻値の配列はタプルからstruct_timeに変更され、 それぞれのフィールドに属性名がつけられました。

このモジュールでは以下の関数とデータ型を定義します:

accept2dyear
2 桁の西暦年を使えるかを指定するブール型の値です。標準では真ですが、 環境変数 PYTHONY2K が空文字列でない値に設定されている場合には 偽になります。実行時に変更することもできます。

altzone
ローカルの夏時間タイムゾーンにおける UTC からの時刻オフセットで、西に 行くほど増加する秒で表した値です (ほとんどの西ヨーロッパでは負になり、 アメリカでは正、イギリスではゼロになります) 。 daylight がゼロでないときのみ使用してください。

asctime( [t])
gmtime() や localtime() が返す時刻を表現する タプル又は struct_timeを、'Sun Jun 20 23:21:05 1993' といった書式の 24 文字 の文字列に変換します。t が与えられていない場合には、 localtime() が返す現在の時刻が使われます。 asctime() はロケール情報を使いません。 注意: 同名の C の関数と違って、末尾には改行文字はありません。 バージョン2.1 以降で変更された 仕様: tuple を省略できるようになりました。

clock( )
Unixでは、現在のプロセッサ時間秒を浮動小数点数で返します。 時刻の精度および ``プロセッサ時間 (processor time)'' の定義そのものは同じ 名前の C 関数に依存します。いずれにせよ、この関数は Python の ベンチマークPython や 計時アルゴリズムに使われています。

Windows では、最初にこの関数が呼び出されてからの経過時間を wall-clock 秒で返します。この関数は Win32 関数 QueryPerformanceCounter() に基づいていて、その精度 は通常 1 マイクロ秒以下です。

ctime( [secs])
エポックからの経過秒数で表現された時刻を、ローカルの時刻を表現 する文字列に変換します。secs が与えられていない場合、 time() が返す値が現在の時刻として使われます。 ctime(secs) は asctime(localtime(secs)) と同じです。ctime() はロケール情報を使いません。 バージョン2.1 以降で変更された 仕様: secs を省略できるようになりました。

daylight
DST タイムゾーンが定義されている場合ゼロでない値になります。

gmtime( [secs])
エポックからの経過時間で表現された時刻を、UTC におけるstruct_time に変換します。このとき dst フラグは常にゼロとして扱われます。 secs が与えられていない場合、time() が返す値が 現在の時刻として使われます。秒の端数は無視されます。struct_time のレイアウトについては上を参照してください。 バージョン2.1 以降で変更された 仕様: secs を省略できるようになりました

localtime( [secs])
gmtime() に似ていますが、ローカルタイムに変換します。 現在の時刻に DST が適用される場合、 dst フラグは 1 に設定 されます。 バージョン2.1 以降で変更された 仕様: secs を省略できるようになりました。

mktime( t)
localtime() の逆を行う関数です。引数は struct_timeか 完全な 9 つの要素 全てに値の入ったタプル (dst フラグも必要です; 現在の時刻に DST が 適用されるか不明の場合には -1 を使ってください) で、 UTC ではなく ローカルの 時刻を指定します。 time() との互換性のために浮動小数点数の値を返します。 入力の値が正しい時刻で表現できない場合、例外OverflowError または ValueError が送出されます (どちらが送出されるかは Python および その下にある C ライブラリのどちらにとって無効な値が 入力されたかで決まります) 。この関数で生成できる最も昔の時刻値は プラットフォームに依存します。

sleep( secs)
与えられた秒数の間実行を停止します。より精度の高い実行停止時間を指定 するために、引数は浮動小数点にしてもかまいません。何らかのシステム シグナルがキャッチされた場合、それに続いてシグナル処理ルーチンが実行 され、 sleep() を停止してしまいます。従って実際の実行停止 時間は要求した時間よりも短くなるかもしれません。また、システムが 他の処理をスケジューリングするために、実行停止時間が要求した時間よりも 多少長い時間になることもあります。

strftime( format[, t])
gmtime() や localtime() が返す時刻値タプル 又はstruct_timeを、 format で指定した文字列形式に変換します。 t が与えられていない場合、localtime() が返す 現在の時刻が使われます。format は文字列でなくてはなりません。 バージョン2.1 以降で変更された 仕様: t を省略できるようになりました。

format 文字列には以下の指示語 (directive) を埋め込むことが できます。これらはフィールド長や精度のオプションを付けずに表され、 strftime() の結果の対応する文字列と入れ替えられます:

Directive | Meaning | Notes
%a | ロケールにおける省略形の曜日名。
%A | ロケールにおける省略なしの曜日名。
%b | ロケールにおける省略形の月名。
%B | ロケールにおける省略なしの月名。
%c | ロケールにおける適切な日付および時刻表現。
%d | 月の始めから何日目かを表す 10 進数 [01,31]。
%H | (24 時間計での) 時を表す 10 進数 [00,23]。
%I | (12 時間計での) 時を表す 10 進数 [01,12]。
%j | 年の初めから何日目かを表す 10 進数 [001,366]。
%m | 月を表す 10 進数 [01,12]。
%M | 分を表す 10 進数 [00,59]。
%p | ロケールにおける AM または PM に対応する文字列。
%S | 秒を表す 10 進数 [00,61]。 | (1)
%U | 年の初めから何週目か (日曜を週の始まりとします)を表す 10 進数 [00,53]。年が明けてから最初の日曜日までの全ての 曜日は 0 週目に属すると見なされます。
%w | 曜日を表す 10 進数 [0(日曜日),6]。
%W | 年の初めから何週目か (日曜を週の始まりとします)を表す 10 進数 [00,53]。年が明けてから最初の月曜日までの全ての 曜日は 0 週目に属すると見なされます。
%x | ロケールにおける適切な日付の表現。
%X | ロケールにおける適切な時刻の表現。
%y | 上 2 桁なしの西暦年を表す 10 進数 [00,99]。
%Y | 上 2 桁付きの西暦年を表す 10 進数。
%Z | タイムゾーンの名前 (タイムゾーンがない場合には空文字列)。
%% 文字 "%" 自体の表現。

注意:

(1)
値の幅は間違いなく 0 to 61 です; これはうるう秒と、 （ごく稀ですが）2 重のうるう秒のためのものです。

以下に RFC 2822 インターネット電子メール標準で定義されている日付 表現と互換の書式の例を示します。 6.1

>>> from time import gmtime, strftime
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
'Thu, 28 Jun 2001 14:17:15 +0000'

いくつかのプラットフォームではさらにいくつかの指示語がサポートされて いますが、標準 ANSI C で意味のある値はここで列挙したものだけです。

いくつかのプラットフォームでは、フィールドの幅や精度を指定する オプションが以下のように指示語の先頭の文字 "%" の直後に 付けられるようになっていました; この機能も移植性はありません。 フィールドの幅は通常 2 ですが、%j は例外で 3 です。

strptime( string[, format])
時刻を表現する文字列をフォーマットに従って解釈します。返される値は gmtime() や localtime() が返すようなstruct_time です。format パラメタは strftime() で使うものと 同じ指示語を使います; このパラメタの値はデフォルトでは "%a %b %d %H:%M:%S %Y" で、ctime() が 返すフォーマットに一致します。 string が format に従って解釈できなかった場合、 例外 ValueError が送出されます。 解析しようとする文字列が解析後に余分なデータを持っていた場合、 ValueError が送出されます。欠落したデータはデフォルトの 値で埋められ、その値は (1900, 1, 1, 0, 0, 0, 0, 1, -1) です。

%Z 指示語へのサポートは tzname に収められている値と daylight が真かどうかで決められます。このため、常に既知の (かつ夏時間でないと考えられている) UTC や GMT を認識する時意外は プラットフォーム固有の動作になります。

struct_time
gmtime()、localtime() および strptime() が返す時刻値配列のタイプです。 バージョン2.2 以降で新規追加された 仕様です。

time( )
時刻を浮動小数点数で返します。単位は UTC におけるエポックからの秒数です。 時刻は常に浮動小数点で返されますが、全てのシステムが 1 秒より高い精度で 時刻を提供するとは限らないので注意してください。この関数が返す値は通常 減少していくことはありませんが、この関数を 2 回呼び出し、呼び出しの間に システムクロックの時刻を巻き戻して設定した場合には、以前の呼び出しよりも 低い値が返ることもあります。

timezone
(DST でない) ローカルタイムゾーンの UTC からの時刻オフセットで、西に 行くほど増加する秒で表した値です (ほとんどの西ヨーロッパでは負になり、 アメリカでは正、イギリスではゼロになります) 。

tzname
二つの文字列からなるタプルです。最初の要素は DST でないローカルの タイムゾーン名です。ふたつめの要素は DST のタイムゾーンです。 DST のタイムゾーンが定義されていない場合。二つ目の文字列を使うべきでは ありません。

tzset( )
ライブラリで使われている時刻変換規則をリセットします。 どのように行われるかは、環境変数 TZ で指定されます。 バージョン2.3 以降で新規追加された 仕様です。

利用できるシステム: Unix。

注意: 多くの場合、環境変数 TZ を変更すると、tzset を 呼ばない限り localtime のような関数の出力に影響を 及ぼすため、値が信頼できなくなってしまいます。

TZ 環境変数には空白文字を含めてはなりません。

環境変数 TZ の標準的な書式は以下です: (分かりやすいように空白を入れています)

std offset [dst [offset] [,start[/time], end[/time]
]]

各値は以下のようになっています:

std and dst
三文字またはそれ以上の英数字で、タイムゾーンの略称を与えます。 この値は time.tzname になります。

offset
オフセットは形式: ± hh[:mm[:ss]] をとります。 この表現は、UTC 時刻にするためにローカルな時間に加算する必要の ある時間値を示します。'-' が先頭につく場合、そのタイムゾーンは 本子午線 (Prime Meridian) より東側にあります; それ以外の場合は 本子午線の西側です。オフセットが dst の後ろに続かない場合、 夏時間は標準時より一時間先行しているものと仮定します。

start[/time],end[/time]
いつ DST に移動し、DST から戻ってくるかを示します。開始および終了 日時の形式は以下のいずれかです:

Jn
ユリウス日 (Julian day) n (1 <= n <= 365) を表します。 うるう日は計算に含められないため、2 月 28 日は常に 59 で、 3 月 1 日は 60 になります。

n
ゼロから始まるユリウス日 (0 <= n <= 365) です。うるう日は 計算に含められるため、2 月 29 日を参照することができます。

Mm.n.d
m 月の第 n 週における d 番目の日 (0 <= d <= 6, 1 <= n <= 5, 1 <= m <= 12) を表します。週 5 は月における最終週の d 番目の日を表し、 第 4 週か第 5 週のどちらかになります。週 1 は日 d が最初に 現れる日を指します。日 0 は日曜日です。

時間はオフセットと同じで、先頭に符号 ('-' や '+') を付けてはいけない ところが違います。時刻が指定されていなければ、デフォルトの値 02:00:00 になります。

>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'02:07:36 05/08/03 EDT'
>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'16:08:12 05/08/03 AEST'

多くの Unix システム (*BSD, Linux, Solaris, および Darwin を含む) では、システムの zoneinfo (tzfile(5)) データベース を使ったほうが、タイムゾーンごとの規則を指定する上で便利です。 これを行うには、必要なタイムゾーンデータファイルへのパスを システムの 'zoneinfo' タイムゾーンデータベースからの相対で表した値 を環境変数 TZ に設定します。システムの 'zoneinfo' は 通常/usr/share/zoneinfo にあります。例えば、 'US/Eastern'、 'Australia/Melbourne'、 'Egypt' ないし 'Europe/Amsterdam' と指定します。

>>> os.environ['TZ'] = 'US/Eastern'
>>> time.tzset()
>>> time.tzname
('EST', 'EDT')
>>> os.environ['TZ'] = 'Egypt'
>>> time.tzset()
>>> time.tzname
('EET', 'EEST')

参考資料:

localeモジュール:
国際化サービス。ロケールの設定は time モジュールのいくつかの関数が返す値に影響をおよぼすことがあります。.
calendarモジュール:
一般的なカレンダー関連の関数。 timegm() はこのモジュールの gmtime() の逆の操作を行います。.

... 表現と互換の書式の例を示します。6.1
現在では %Z の利用は推奨されていません。しかし ここで実現したい時間及び分オフセットへの展開を行ってくれる %Z エスケープは全ての ANSI C ライブラリでサポートされているわけではありません。 また、オリジナルの 1982 年に提出された RFC 822 標準は西暦年の表現を 2 桁 と要求しています(%Y でなく%y )。しかし実際には 2000 年になるだいぶ 以前から 4 桁の西暦年表現に移行しています。4 桁の西暦年表現は RFC 2822 に おいて義務付けられ、伴って RFC 822 での取り決めは撤廃されました。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.9.7 strftime() の振る舞い Up: 6. 汎用オペレーティングシステムサービス Next: 6.11 sched


6.11 sched -- イベントスケジューラ

schedモジュールは一般的な目的のためのイベントスケジューラを 実装するクラスを定義します:

class scheduler( timefunc, delayfunc)
schedulerクラスはイベントをスケジュールするための一般的な インターフェースを定義します。それは``外部世界''を実際に扱うための 2つの関数を必要とします -- timefuncは引数なしで呼出し可能で あるべきで、そして数(それは``time''です, どんな単位でもかまいません) を返すようにします。delayfuncは1つの引数(timefuncの出力 と互換)で呼出し可能であり、その時間だけ遅延しなければいけません。 各々のイベントが、マルチスレッドアプリケーションの中で他のスレッドが 実行する機会の許可を実行した後に、delayfuncは引数0で呼 ばれるでしょう。

例:

>>> import sched, time
>>> s=sched.scheduler(time.time, time.sleep)
>>> def print_time(): print "From print_time", time.time()
...
>>> def print_some_times():
...     print time.time()
...     s.enter(5, 1, print_time, ())
...     s.enter(10, 1, print_time, ())
...     s.run()
...     print time.time()
...
>>> print_some_times()
930343690.257
From print_time 930343695.274
From print_time 930343700.273
930343700.276

  • 6.11.1 スケジューラオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.10 time Up: 6. 汎用オペレーティングシステムサービス Next: 6.11.1 スケジューラオブジェクト


6.11.1 スケジューラオブジェクト

schedulerインスタンスは以下のメソッドを持っています:

enterabs( time, priority, action, argument)
新しいイベントをスケジュールします。引数timeは、 コンストラクタへ渡されたtimefuncの戻り値と互換な数値型で なければいけません。 同じtimeによってスケジュールされたイベントは、 それらのpriorityによって実行されるでしょう。

イベントを実行することは、action(*argument)を 実行することを意味します。 argumentはactionのためのパラメータを保持するシーケンスで なければいけません。

戻り値は、イベントのキャンセル後に使われるかもしれないイベントです (cancel()を見よ)。

enter( delay, priority, action, argument)
時間単位以上のdelayでイベントをスケジュールします。 そのとき、その他の関連時間、その他の引数、効果、戻り値は、 enterabs()に対するものと同じです。

cancel( event)
キューからイベントを消去します。 もしeventがキューにある現在のイベントでないならば、 このメソッドはRuntimeErrorを送出します。

empty( )
もしイベントキューが空ならば、Trueを返します。

run( )
すべてのスケジュールされたイベントを実行します。 この関数は次のイベントを(コンストラクタへ渡された関数 delayfuncを使うことで)待ち、そしてそれを実行し、 イベントがスケジュールされなくなるまで同じことを繰り返します。

actionあるいはdelayfuncは例外を投げることができます。 いずれの場合も、スケジューラは一貫した状態を維持し、例外を伝播するでしょう。 例外がactionによって投げられる場合、イベントはrun()への 呼出しを未来に行なわないでしょう。

イベントのシーケンスが、次イベントの前に、利用可能時間より実行時間が長いと、 スケジューラは単に遅れることになるでしょう。 イベントが落ちることはありません; 呼出しコードはもはや適切でないキャンセルイベントに対して責任があります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.11 sched Up: 6.11 sched Next: 6.12 mutex


6.12 mutex -- 排他制御

mutexモジュールはロックの獲得と解除を通して排他制御を 可能にするクラスを定義します。 スレッドやマルチタスクを必要と(あるいは意味)しませんが、 それらの目的に有益となることでしょう。

mutexモジュールは以下のクラスを定義します:

class mutex( )
新しい(ロックされてない)mutexを作ります。

mutexは状態を2つ持ちます -- ``ロック''ビットとキューです。 mutexがロックされていないとき、キューは空です。 mutexがロックされているとき、キューは空、 あるいはロックを獲得するために待っている関数(またはメソッド) を示すペア(function, argument)を収容しています。 キューが空でないときにmutexが解除されると、 最初のキュー登録が削除されてそのfunction(argument)が 呼び出れ、それが今はロックを持ちます。

もちろんマルチスレッドの意味は全くなく、 一度ロックを取得すると関数が呼ばれるので、 lock()による風変わりなインターフェースとなりえます。

  • 6.12.1 mutex オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.11.1 スケジューラオブジェクト Up: 6. 汎用オペレーティングシステムサービス Next: 6.12.1 mutex オブジェクト


6.12.1 mutex オブジェクト

mutex は以下のメソッドを持ちます:

test( )
mutexがロックされたか調べます。

testandset( )
``アトミック'' Test-and-Set命令です。 セットされていないならばロックを得てTrueを返し、 そうでないならばFalseを返します。

lock( function, argument)
mutexがロックされていなければ、 function(argument)を実行します。 この場合にはそのmutexがロックされて、関数と引数をキューに置きます。 function(argument) が実行されたときの説明は、 unlockを見てください。

unlock( )
もしキューが空ならば、mutexを解除します。 一方、空でないならば、キューの最初の要素を実行します。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.12 mutex Up: 6.12 mutex Next: 6.13 getpass


6.13 getpass -- 可搬性のあるパスワード入力機構

The getpass module provides two functions: getpassモジュールは二つの機能を提供します:

getpass( [prompt])
エコーなしでユーザーにパスワードを入力させるプロンプト。 ユーザーはpromptの文字列をプロンプトに使えます、 デフォルトは'Password:'です。

利用できるシステム: Machintosh, Unix, Windows

getuser( )
ユーザーの ``ログイン名''を返します。 　有効性:Unix、Windows

この関数は環境変数LOGNAME USER LNAME USERNAMEの順序でチェックして、最初の空ではない文字列が設定された値を返します。 もし、なにも設定されていない場合はpwdモジュールが提供するシステム上のパスワードデータベースから返します。それ以外は、例外が上がります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.12.1 mutex オブジェクト Up: 6. 汎用オペレーティングシステムサービス Next: 6.14 curses


6.14 curses -- 文字セル表示のための端末操作

バージョン1.6 以降で変更された 仕様: ncurses ライブラリのサポートを追加し、パッケージに変換しました

curses モジュールは、可搬性のある端末操作を行うための デファクトスタンダードである、curses ライブラリへのインタフェースを 提供します。

Unix 環境では curses は非常に広く用いられていますが、DOS、OS2、 そしておそらく他のシステムのバージョンも利用することができます。 この拡張モジュールは Linux および BSD 系の Unixで動作する オープンソースの curses ライブラリである ncurses の API に 合致するように設計されています。

参考資料:

curses.asciiモジュール:
ロケール設定に関わらず ASCII 文字を 扱うためのユーティリティ。.
curses.panelモジュール:
curses ウィンドウにデプス機能を追加する パネルスタック拡張。.
curses.textpadモジュール:
Emacs ライクなキーバインディング をサポートする編集可能な curses 用テキストウィジェット。.
curses.wrapperモジュール:
アプリケーションの起動時および終了時に 適切な端末のセットアップとリセットを確実に行うための関数。.
Curses Programming with Python
Andrew Kuchling および Eric Raymond によって書かれた、curses を Python で使うためのチュートリアルです。 Python Web サイトで入手できます。

Python ソースコードの Demo/curses/ ディレクトリには、 このモジュールで提供されている curses バインディングを使ったプログラム 例がいくつか収められています。

  • 6.14.1 関数
  • 6.14.2 Window オブジェクト
  • 6.14.3 定数
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.13 getpass Up: 6. 汎用オペレーティングシステムサービス Next: 6.14.1 関数


6.14.1 関数

curses モジュールでは以下の例外を定義しています:

exception error
curses ライブラリ関数がエラーを返した際に送出される例外です。

注意: 関数やメソッドにおけるオプションの引数 x および y がある場合、標準の値は常に現在のカーソルになります。 オプションの attr がある場合、標準の値は A_NORMAL です。

curses では以下の関数を定義しています:

baudrate( )
端末の出力速度をビット／秒で返します。ソフトウェア端末エミュレータ の場合、これは固定の高い値を持つことになります。この関数は 歴史的な理由で入れられています; かつては、この関数は時間遅延を 生成するための出力ループを書くために用いられたり、行速度 に応じてインタフェースを切り替えたりするために用いられたり していました。

beep( )
注意を促す短い音を鳴らします。

can_change_color( )
端末に表示される色をプログラマが変更できるか否かによって、 真または偽を返します。

cbreak( )
cbreak モードに入ります。cbreak モード (``rare'' モードと呼ばれる こともあります) では、通常の tty 行バッファリングはオフにされ、 文字を一文字一文字読むことができます。ただし、raw モードとは異なり、 特殊文字 (割り込み:interrupt、終了:quit、一時停止:suspend、および フロー制御) については、tty ドライバおよび呼び出し側のプログラムに 対する通常の効果をもっています。まず raw() を呼び出し、 次いで cbreak() を呼び出すと、端末を cbreak モード にします。

color_content( color_number)
色 color_number の赤、緑、および青 (RGB) 要素の強度を返します。 color_number は 0 から COLORS の間でなければ なりません。与えられた色の R、G、B、の値からなる三要素のタプルが 返されます。この値は 0 (その成分はない) から 1000 (その成分の最大強度) の範囲をとります。

color_pair( color_number)
指定された色の表示テキストにおける属性値を返します。 属性値は A_STANDOUT、 A_REVERSE、 およびその他の A_* 属性と組み合わせられています。 pair_number() はこの関数の逆です。

curs_set( visibility)
カーソルの状態を設定します。visibility は 0、1、または 2 に 設定され、それぞれ不可視、通常、または非常に可視、を意味します。 要求された可視属性を端末がサポートしている場合、以前のカーソル 状態が返されます; そうでなければ例外が送出されます。多くの端末では、 ``可視 (通常)'' モードは下線カーソルで、``非常に可視'' モードは ブロックカーソルです。

def_prog_mode( )
現在の端末属性を、稼動中のプログラムが curses を使う際のモードである ``プログラム'' モードとして保存します。(このモードの反対は、プログラム が curses を使わない ``シェル'' モードです。) その後 reset_prog_mode() を呼ぶとこのモードを復旧します。

def_shell_mode( )
現在の端末属性を、稼動中のプログラムが curses を使っていないときのモード である ``シェル'' モードとして保存します。(このモードの反対は、 プログラムが curses 機能を利用している ``プログラム'' モードです。) その後 reset_shell_mode() を呼ぶとこのモードを復旧します。

delay_output( ms)
出力に ms ミリ秒の一時停止を入れます。

doupdate( )
物理スクリーン (physical screen) を更新します。curses ライブラリは、 現在の物理スクリーンの内容と、次の状態として要求されている仮想スクリーン をそれぞれ表す、2 つのデータ構造を保持しています。doupdate() は更新を適用し、物理スクリーンを仮想スクリーンに一致させます。

仮想スクリーンは addstr() のような書き込み操作をウィンドウに
行った後に noutrefresh() を呼び出して更新することができます。
通常の refresh() 呼び出しは、単に noutrefresh()
を呼んだ後に doupdate() を呼ぶだけです; 複数のウィンドウを
更新しなければならない場合、全てのウィンドウに対して
noutrefresh() を呼び出した後、一度だけ doupdate()
を呼ぶことで、パフォーマンスを向上させることができ、おそらくスクリーン
のちらつきも押さえることができます。

echo( )
echo モードに入ります。 echo モードでは、各文字入力はスクリーン上に 入力された通りにエコーバックされます。

endwin( )
ライブラリの非初期化を行い、端末を通常の状態に戻します。

erasechar( )
ユーザの現在の消去文字 (erase character) 設定を返します。 Unix オペレーティングシステムでは、この値は curses プログラムが 制御している端末の属性であり、curses ライブラリ自体では設定 されません。

filter( )
filter() ルーチンを使う場合、initscr() を 呼ぶ前に呼び出さなくてはなりません。この手順のもたらす効果は以下の 通りです: まず二つの関数の呼び出しの間は、LINES は 1 に設定されます; clear、cup、cud、cud1、cuu1、cuu、vpa は無効化されます; home 文字列 は cr の値に設定されます。これにより、カーソルは現在の行に制限される ので、スクリーンの更新も同様に制限されます。 この関数は、スクリーンの他の部分に影響を及ぼさずに文字単位の行編集を 行う場合に利用できます。

flash( )
スクリーンをフラッシュ(flash) します。すなわち、画面を色反転 (reverse-video) にして、短時間でもとにもどします。人によっては、 beep() で生成される可聴な注意音よりも、このような ``可視ベル(visible bell)'' を好みます。

flushinp( )
全ての入力バッファをフラッシュします。この関数は、ユーザによって すでに入力されているが、まだプログラムによって処理されていない 全ての先行入力文字 (typeahead) を捨て去ります。

getmouse( )
getch() が KEY_MOUSE を返してマウスイベントを 通知した後、この関数を呼んで待ち行列 (queue) 上に置かれている マウスイベントを取得しなければなりません。イベントは (id, x, y, z, bstate) の 5 要素のタプルで表現されています。 id は複数のデバイスを区別するための ID 値で、 x、 y、z はイベントの座標値です (現在 z は使われていません)。 bstate は整数値で、 その各ビットはイベントのタイプを示す値に設定されています。 この値は以下に示す定数のうち一つまたはそれ以上のビット単位 OR になっています。以下の定数のn は 1 から 4 のボタン番号を 示します: BUTTONn_PRESSED, BUTTONn_RELEASED, BUTTONn_CLICKED, BUTTONn_DOUBLE_CLICKED, BUTTONn_TRIPLE_CLICKED, BUTTON_SHIFT, BUTTON_CTRL, BUTTON_ALT.

getsyx( )
仮想スクリーンにおける現在のカーソル位置を y および x の順で返します。 leaveok が真に設定されていれば、 -1、-1 が返されます。

getwin( file)
以前の putwin() 呼び出しでファイルに保存されている、 ウィンドウ関連データを読み出します。次に、このルーチンは そのデータを使って新たなウィンドウを生成し初期化して、 その新規ウィンドウオブジェクトを返します。

has_colors( )
端末が色表示を行える場合には真を返します。そうでない場合には偽を 返します。

has_ic( )
端末が文字の挿入／削除機能を持つ場合に真を返します。 この関数は、最近の端末エミュレータがどれもこの機能を持っているのと同じく、 歴史的な理由だけのために含められています。

has_il( )
端末が行の挿入／削除機能を持つか、領域単位のスクロールによって 機能をシミュレートできる場合に真を返します。 この関数は、最近の端末エミュレータがどれもこの機能を持っているのと同じく、 歴史的な理由だけのために含められています。

has_key( ch)
キー値 ch をとり、現在の端末タイプがその値のキーを認識できる 場合に真を返します。

halfdelay( tenths)
半遅延モード、すなわち cbreak モードに似た、ユーザが打鍵した文字 がすぐにプログラムで利用できるようになるモードで使われます。 しかしながら、何も入力されなかった場合、 tenths 十秒後に 例外が送出されます。tenths の値は 1 から 255 の間でなければ なりません。半遅延モードから抜けるには nocbreak() を使います。

init_color( color_number, r, g, b)
色の定義を変更します。変更したい色番号と、その後に 3 つ組みの RGB 値 (赤、緑、青の成分の大きさ) をとります。color_number の値は 0 から COLORS の間でなければなりません。 r、g、b の値は 0 から 1000 の 間でなければなりません。 init_color() を使うと、 スクリーン上でカラーが使用されている部分は全て新しい設定に 即時変更されます。この関数はほとんどの端末で何も行いません; can_change_color() が 1 を返す場合にのみ 動作します。

init_pair( pair_number, fg, bg)
色ペアの定義を変更します。3 つの引数: 変更したい色ペア、前景色の 色番号、背景色の色番号、をとります。pair_number は 1 から COLOR_PAIRS -1 の間でなければなりません (0 色ペアは黒色背景に白色前景となるように設定されており、 変更することができません) 。fg および bg 引数は 0 と COLORS の間でなければなりません。 色ペアが以前に初期化されていれば、スクリーンを更新して、指定 された色ペアの部分を新たな設定に変更します。

initscr( )
ライブラリを初期化します。スクリーン全体をあらわす WindowObject を返します。注意: 端末のオープン時にエラーが発生した場合、curses ライブラリ によってインタープリタが終了される場合があります。

isendwin( )
endwin() がすでに呼び出されている (すなわち、curses ライブラリ が非初期化されてしまっている) 場合に真を返します。

keyname( k)
k に番号付けされているキーの名前を返します。印字可能な ASCII 文字を生成するキーの名前はそのキーの文字自体になります。 コントロールキーと組み合わせたキーの名前は、キャレットの後に対応する ASCII 文字が続く 2 文字の文字列になります。Alt キーと組み合わせた キー (128-255) の名前は、先頭に `M-' が付き、その後に対応する ASCII 文字が続く文字列になります。

killchar( )
ユーザの現在の行削除文字を返します。 Unix オペレーティングシステムでは、この値は curses プログラムが 制御している端末の属性であり、curses ライブラリ自体では設定 されません。

longname( )
現在の端末について記述している terminfo の長形式 name フィールドが 入った文字列を返します。verbose 形式記述の最大長は 128 文字です。 この値は initscr() 呼び出しの後でのみ定義されています。

meta( yes)
yes が 1 の場合、8 ビット文字を入力として許します。yes が 0 の場合、 7 ビット文字だけを許します。

mouseinterval( interval)
ボタンが押されてから離されるまでの時間をマウスクリック一回として認識 する最大の時間間隔を設定します。以前の内部設定値を返します。 標準の値は 200 ミリ秒、または 5 分の 1 秒です。

mousemask( mousemask)
報告すべきマウスイベントを設定し、(availmask, oldmask) の組からなるタプルを返します。 availmask はどの指定されたマウスイベントのどれが報告されるかを 示します; どのイベント指定も完全に失敗した場合には 0 が返ります。 oldmask は与えられたウィンドウの以前のマウスイベントマスク です。この関数が呼ばれない限り、マウスイベントは何も報告されません。

napms( ms)
ms ミリ秒スリープします。

newpad( nlines, ncols)
与えられた行とカラム数を持つパッド (pad) データ構造を生成し、その ポインタを返します。パッドはウィンドウオブジェクトとして返されます。

パッドはウィンドウと同じようなものですが、スクリーンのサイズによって 制限されており、スクリーンの特定の部分に関連付けられていなくても かまいません。大きなウィンドウが必要であり、スクリーンにはその ウィンドウの一部しか一度に表示しない場合に使うことができます。 (スクロールや入力エコーなどによる) パッドに対する再描画は起こりません。 パッドに対する refresh() および noutrefresh() メソッド は、パッド中の表示する部分と表示するために利用するスクリーン上の位置を 指定する 6 つの引数が必要です。これらの引数は pminrow、 pmincol、 sminrow、 smincol、 smaxrow、smaxcol です; p で始まる引数はパッド中の表示領域の左上位置で、s で始まる引数は パッド領域を表示するスクリーン上のクリップ矩形を指定します。

newwin( [nlines, ncols,] begin_y, begin_x)
左上の角が (begin_y, begin_x) で、高さ／幅が nlines/ncols の新規ウィンドウを返します。

標準では、ウィンドウは指定された位置からスクリーンの右下まで 広がります。

nl( )
newlime モードに入ります。このモードはリターンキーを入力中の改行 として変換し、出力時に改行文字を復帰 (return) と改行 (line-feed) に変換 します。newline モードは初期化時にはオンになっています。

nocbreak( )
cbreak モードから離れます。行バッファリングを行う通常の ``cooked'' モードに戻ります。

noecho( )
echo モードから離れます。入力のエコーバックはオフにされます。

nonl( )
newline モードから離れます。入力時のリターンキーから改行への変換、 および出力時の改行から復帰／改行への低レベル変換を無効化します (ただし、addch('\n') の振る舞いは変更せず、仮想スクリーン 上では常に復帰と改行に等しくなります)。変換をオフにすることで、 curses は水平方向の動きを少しだけ高速化できることがあります; また、入力中のリターンキーの検出ができるようになります。

noqiflush( )
noquiflush ルーチンを使うと、通常行われている INTR、QUIT、および SUSP 文字による入力および出力キューのフラッシュが行われなく なります。シグナルハンドラが終了した際、割り込みが発生しなかった かのように出力を続たい場合、ハンドラ中で noqiflush() を呼び出すことができます。

noraw( )
raw モードから離れます。行バッファリングを行う通常の ``cooked'' モードに戻ります。

pair_content( pair_number)
要求された色ペア中の色を含む (fg, bg) からなる タプルを返します。pair_number は 0 から COLOR_PAIRS - 1 の間でなければなりません。

pair_number( attr)
attr に対する色ペアセットの番号を返します。color_pair() はこの関数の逆に相当します。

putp( string)
tputs(str, 1, putchar) と等価です; 現在の端末における、 指定された terminfo 機能の値を出力します。putp の出力は常に標準 出力に送られるので注意して下さい。

qiflush( [flag])
flag が偽なら、noqiflush() を呼ぶのとと同じ効果です。 flag が真か、引数が与えられていない場合、制御文字が読み出された 最にキューはフラッシュされます。

raw( )
raw モードに入ります。raw モードでは、通常の行バッファリングと 割り込み (interrupt)、終了 (quit)、一時停止 (suspend)、および フロー制御キーはオフになります; 文字は curses 入力関数に一文字 づつ渡されます。

reset_prog_mode( )
端末を ``program'' モードに復旧し、予め def_prog_mode() で保存した内容に戻します。

reset_shell_mode( )
端末を ``shell'' モードに復旧し、予め def_shell_mode() で保存した内容に戻します。

setsyx( y, x)
仮想スクリーンカーソルを y、x に設定します。 y および x が共に -1 の場合、leaveok が設定されます。

setupterm( [termstr, fd])
端末を初期化します。termstr は文字列で、端末の名前を与えます; 省略された場合、TERM 環境変数の値が使われます。fd は 初期化シーケンスが送られる先のファイル記述子です; fd を与えない場合、sys.stdout のファイル記述子が使われます。

start_color( )
プログラマがカラーを利用したい場合で、かつ他の何らかのカラー操作 ルーチンを呼び出す前に呼び出さなくてはなりません。 この関数は initscr() を呼んだ直後に呼ぶようにしておくと よいでしょう。

start_color() は 8 つの基本色 (黒、赤、緑、黄、青、マゼンタ、 シアン、および白) と、色数の最大値と端末がサポートする色ペアの最大数 が入っている、curses モジュールにおける二つのグローバル変数、 COLORS および COLOR_PAIRS を初期化します。 この関数はまた、色設定を端末のスイッチが入れられたときの状態に 戻します。

termattrs( )
端末がサポートする全てのビデオ属性を論理和した値を返します。 この情報は、curses プログラムがスクリーンの見え方を 完全に制御する必要がある場合に便利です。

termname( )
14 文字以下になるように切り詰められた環境変数 TERM の値を返します。

tigetflag( capname)
terminfo 機能名 capname に対応する機能値をブール値で返します。 capname がブール値で表される機能値でない場合 -1 が返され、機能がキャンセルされているか、端末記述上に見つからない 場合には 0 を返します。

tigetnum( capname)
terminfo 機能名 capname に対応する機能値を数値で返します。 capname が数値で表される機能値でない場合 -2 が返され、機能がキャンセルされているか、端末記述上に見つからない 場合には -1 を返します。

tigetstr( capname)
terminfo 機能名 capname に対応する機能値を文字列値で返します。 capname が文字列値で表される機能値でない場合や、 機能がキャンセルされているか、端末記述上に見つからない 場合には None を返します。

tparm( str[,...])
str を与えられたパラメタを使って文字列にインスタンス化します。 str は terminfo データベースから得られたパラメタを持つ文字列 でなければなりません。例えば、tparm(tigetstr("cup"), 5, 3) は '\033[6;4H' のようになります。厳密には端末の形式に よって異なる結果となります。

typeahead( fd)
先読みチェックに使うためのファイル記述子 fd を指定します。 fd が -1 の場合、先読みチェックは行われません。

curses ライブラリはスクリーンを更新する間、先読み文字列を定期的に 検索することで ``行はみ出し最適化 (line-breakout optimization)'' を行います。入力が得られ、かつ入力は端末からのものである場合、現在 行おうとしている更新は refresh や doupdate を再度呼び出すまで 先送りにします。この関数は異なるファイル記述子で先読みチェックを 行うように指定することができます。

unctrl( ch)
ch の印字可能な表現を文字列で返します。制御文字は例えば ^C のようにキャレットに続く文字として表示 されます。印字可能文字はそのままです。

ungetch( ch)
ch をプッシュして、 getch() を次に呼び出したときに 返されるようにします。注意: getch() を呼び出すまでは ch は一つしかプッシュできません。

ungetmouse( id, x, y, z, bstate)
与えられた状態データが関連付けられた KEY_MOUSE イベントを 入力キューにプッシュします。

use_env( flag)
この関数を使う場合、initscr() または newterm を呼ぶ前に 呼び出さなくてはなりません。flag が偽の場合、環境変数 LINES および COLUMNS の値 (これらは標準の設定で 使われます) の値が設定されていたり、curses がウィンドウ内で 動作して (この場合 LINES や COLUMNS が設定 されていないとウィンドウのサイズを使います) いても、terminfo データベースに指定された lines および columns の値を使います。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.14 curses Up: 6.14 curses Next: 6.14.2 Window オブジェクト


6.14.2 Window オブジェクト

上記の initscr() や newwin() が返すウィンドウ は、以下のメソッドを持ちます:

addch( [y, x,] ch[, attr])
注意: ここで 文字 は Python 文字 (長さ 1 の文字列) C における 文字 (ASCII コード) を意味します。(この注釈は文字について触れている ドキュメントではどこでも当てはまります。) 組み込みの ord() は文字列をコードの集まりにする際に 便利です。

(y, x) にある文字 ch を属性 attr で描画します。このときその場所に以前描画された文字は上書きされます。 標準の設定では、文字の位置および属性はウィンドウオブジェクトにおける 現在の設定になります。

addnstr( [y, x,] str, n[, attr])
文字列 str から最大で n 文字を (y, x) に属性 attr で描画します。以前ディスプレイにあった内容はすべて 上書きされます。

addstr( [y, x,] str[, attr])
(y, x) に文字列 str を属性 attr で描画 します。以前ディスプレイにあった内容はすべて上書きされます。

attroff( attr)
現在のウィンドウに書き込まれた全ての内容に対し ``バックグラウンド'' に設定された属性 attr を除去します。

attron( attr)
現在のウィンドウに書き込まれた全ての内容に対し ``バックグラウンド'' に属性 attr を追加します。

attrset( attr)
``バックグラウンド'' の属性セットを attr に設定します。 初期値は 0 (属性なし) です。

bkgd( ch[, attr])
ウィンドウ上の背景プロパティを、 attr を属性とする 文字 ch に設定します。変更はそのウィンドウ中の全ての文字に 以下のようにして適用されます:
  • ウィンドウ中の全ての文字の属性が新たな背景属性に変更されます。
  • 以前の背景文字が出現すると、常に新たな背景文字に変更されます。

bkgdset( ch[, attr])
ウィンドウの背景を設定します。ウィンドウの背景は、文字と何らかの 属性の組み合わせから成り立ちます。背景情報の属性の部分は、 ウィンドウ上に描画されている空白でない全ての文字と組み合わされ (OR され) ます。空白文字には文字部分と属性部分の両方が組み合わされ ます。背景は文字のプロパティとなり、スクロールや行／文字の挿入／削除 操作の際には文字と一緒に移動します。

border( [ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]])
ウィンドウの縁に境界線を描画します。各引数には境界の特定部分を表現 するために使われる文字を指定します; 詳細は以下のテーブルを参照 してください。文字は整数または 1 文字からなる文字列で指定されます。

注意: どの引数も、0 を指定した場合標準設定の文字が 使われるようになります。キーワード引数は使うことが できません。 標準の設定はテーブル中に示されています:

引数 | 記述 | 標準の設定値
ls | 左側 | ACS_VLINE
rs | 右側 | ACS_VLINE
ts | 上側 | ACS_HLINE
bs | 下側 | ACS_HLINE
tl | 左上の角 | ACS_ULCORNER
tr | 右上の角 | ACS_URCORNER
bl | 左下の角 | ACS_BLCORNER
br | 右下の角 | ACS_BRCORNER

box( [vertch, horch])
border() と同様ですが、ls および rs は 共に vertch で、ts および bs は共に horch です。この関数では、角に使われる文字は常に標準設定の値です。

clear( )
erase() に似ていますが、次に refresh() が呼び出された 際に全てのウィンドウを再描画するようにします。

clearok( yes)
yes が 1 ならば、次の refresh() はウィンドウを完全に 消去します。

clrtobot( )
カーソルの位置からウィンドウの端までを消去します: カーソル以降の 全ての行が削除されるため、 clrtoeol() が実行されたのと おなじになります。

clrtoeol( )
カーソル位置から行末までを消去します。

cursyncup( )
ウィンドウの全ての親ウィンドウについて、現在のカーソル位置 を反映するよう更新します。

delch( [x, y])
(y, x) にある文字を削除します。 Delete any character at (y, x).

deleteln( )
カーソルの下にある行を削除します。後続の行はすべて 1 行上に移動します。

derwin( [nlines, ncols,] begin_y, begin_x)
``derive window (ウィンドウを導出する)'' の短縮形です。 derwin() は subwin() と同じですが、 begin_y および begin+x はスクリーン全体の原点ではなく、 ウィンドウの原点からの相対位置です。導出されたウィンドウオブジェクト が返されます。

echochar( ch[, attr])
文字 ch に属性 attr を付与し、即座に refresh() をウィンドウに対して呼び出します。

enclose( y, x)
与えられた文字セル座標をスクリーン原点から相対的なものとし、 ウィンドウの中に含まれるかを調べて、真または偽を返します。 スクリーン上のウィンドウの一部がマウスイベントの発生場所を 含むかどうかを調べる上で便利です。

erase( )
ウィンドウをクリアします。

getbegyx( )
左上の角の座標をあらわすタプル (y, x) を返します。

getch( [x, y])
文字を取得します。返される整数は ASCII の範囲の値となる わけではない ので注意してください: ファンクションキー、 キーパッド上のキー等は 256 よりも大きな数字を返します。無遅延 (no-delay) モードでは、入力がない場合 -1 が返されます。

getkey( [x, y])
文字を取得し、 getch() のように整数を返す代わりに 文字列を返します。ファンクションキー、キーバットキーなどは キー名の入った複数バイトからなる文字列を返します。無遅延 モードでは、入力がない場合例外が送出されます。

getmaxyx( )
ウィンドウの高さおよび幅を表すタプル (y, x) を返します。

getparyx( )
親ウィンドウ中におけるウィンドウの開始位置を x と y の二つの 整数で返します。ウィンドウに親ウィンドウがない場合-1,-1 を返します。

getstr( [x, y])
原始的な文字編集機能つきで、ユーザの入力文字列を読み取ります。

getyx( )
ウィンドウの左上角からの相対で表した現在のカーソル位置をタプル (y, x) で返します。

hline( [y, x,] ch, n)
(y, x) から始まり、 n の長さを持つ、 文字 ch で作られる水平線を表示します。

idcok( flag)
flag が偽の場合、curses は端末のハードウェアによる文字挿入／削除 機能を使おうとしなくなります; flag が真ならば、文字挿入／削除 は有効にされます。curses が最初に初期化された際には文字挿入／削除は 標準の設定で有効になっています。

idlok( yes)
yes が 1 であれば、curses はハードウェアの行編集 機能を利用しようと試みます。行挿入／削除は無効化されます。

immedok( flag)
flag が真ならば、ウィンドウイメージ内における何らかの変更 があるとウィンドウを更新するようになります; すなわち、refresh() を自分で呼ばなくても良くなります。とはいえ、wrefresh を繰り返し 呼び出すことになるため、この操作はかなりパフォーマンスを低下させます。 標準の設定では無効になっています。

inch( [x, y])
ウィンドウの指定の位置の文字を返します。下位 8 ビットが常に文字となり、 それより上のビットは属性を表します。

insch( [y, x,] ch[, attr])
(y, x) に文字 ch を属性 attr で描画し、 行の x からの内容を 1 文字分右にずらします。

insdelln( nlines)
nlines 行を指定されたウィンドウの現在の行の上に挿入します。 その下にある nlines 行は失われます。負の nlines を指定 すると、カーソルのある行以降の nlines を削除し、削除された行の 後ろに続く内容が上に来ます。その下にある nlines は消去されます。 現在のカーソル位置はそのままです。

insertln( )
カーソルの下に空行を 1 行入れます。それ以降の行は 1 行づつ下に移動 します。

insnstr( [y, x,] str, n [, attr])
文字列をカーソルの下にある文字の前に (一行に収まるだけ) 最大 n 文字 挿入します。n がゼロまたは負の値の場合、文字列全体が挿入されます。 カーソルの右にある全ての文字は右に移動し、行の左端にある文字は失われます。 カーソル位置は (y、 x が指定されていた場合はそこに移動しますが、 その後は) 変化しません。

insstr( [y, x, ] str [, attr])
キャラクタ文字列を (行に収まるだけ) カーソルより前に挿入します。 カーソルの右側にある文字は全て右にシフトし、行の右端の文字は失われます。 カーソル位置は (y、 x が指定されていた場合はそこに移動しますが、 その後は) 変化しません。

instr( [y, x][, n])
現在のカーソル位置、または y, x が指定されている場合には その場所から始まるキャラクタ文字列をウィンドウから抽出して返します。 属性は文字から剥ぎ取られます。n が指定された場合、instr() は (末尾の NUL 文字を除いて) 最大で n 文字までの長さからなる 文字列を返します。

is_linetouched( line)
指定した行が、最後に refresh() を呼んだ時から変更されている 場合に真を返します; そうでない場合には偽を返します。 line が現在のウィンドウ上の有効な行でない場合、 curses.error 例外を送出します。

is_wintouched( )
指定したウィンドウが、最後に refresh() を呼んだ時から変更されている 場合に真を返します; そうでない場合には偽を返します。

keypad( yes)
yes が 1 の場合、ある種のキー (キーパッドやファンクションキー) によって生成されたエスケープシーケンスは curses で 解釈されます。yes が 0 の場合、エスケープシーケンスは 入力ストリームにそのままの状態で残されます。

leaveok( yes)
yes が 1 の場合、カーソルは ``カーソル位置'' に移動せず 現在の場所にとどめます。これにより、カーソルの移動を減らせる 可能性があります。この場合、カーソルは不可視にされます。

yes が 0 の場合、カーソルは更新の際に常に ``カーソル位置'' に移動します。

move( new_y, new_x)
カーソルを (new_y, new_x) に移動します。

mvderwin( y, x)
ウィンドウを親ウィンドウの中で移動します。ウィンドウのスクリーン相対 となるパラメタ群は変化しません。このルーチンは親ウィンドウの一部を スクリーン上の同じ物理位置に表示する際に用いられます。

mvwin( new_y, new_x)
ウィンドウの左上角が (new_y, new_x) になるように移動します。

nodelay( yes)
yes が 1 の場合、getch() は非ブロックで動作します。

notimeout( yes)
yes が 1 の場合、エスケープシーケンスはタイムアウト しなくなります。

yes が 0 の場合、数ミリ秒間の間エスケープシーケンスは 解釈されず、入力ストリーム中にそのままの状態で残されます。

noutrefresh( )
更新をマークはしますが待機します。この関数はウィンドウのデータ構造 を表現したい内容を反映するように更新しますが、物理スクリーン上に 反映させるための強制更新を行いません。更新を行うためには doupdate() を呼び出します。

overlay( destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])
ウィンドウを destwin の上に重ね書き (overlay) します。 ウィンドウは同じサイズである必要はなく、重なっている領域だけが 複写されます。この複写は非破壊的 (non-destructive) です。これは 現在の背景文字が destwin の内容を上書きしないことを意味します。

複写領域をきめ細かく制御するために、overlay() の第二形式を 使うことができます。sminrow および smincol は 元のウィンドウの左上の座標で、他の変数は destwin 内の矩形を 表します。

overwrite( destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])
destwin の上にウィンドウの内容を上書き (overwrite) します。 ウィンドウは同じサイズである必要はなく、重なっている領域だけが 複写されます。この複写は破壊的 (destructive) です。これは 現在の背景文字が destwin の内容を上書きすることを意味します。

複写領域をきめ細かく制御するために、overlay() の第二形式を 使うことができます。sminrow および smincol は 元のウィンドウの左上の座標で、他の変数は destwin 内の矩形を 表します。

putwin( file)
ウィンドウに関連付けられている全てのデータを与えられたファイルオブジェクト に書き込みます。この情報は後に getwin() 関数を使って 取得することができます。

redrawln( beg, num)
beg 行から始まる num スクリーン行の表示内容が壊れており、 次の refresh() 呼び出しで完全に再描画されなければならない ことを通知します。

redrawwin( )
ウィンドウ全体を更新 (touch) し、次の refresh() 呼び出しで 完全に再描画されるようにします。

refresh( [pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol])
ディスプレイを即時更新し (現実のウィンドウとこれまでの描画／削除 メソッドの内容との同期をとり) ます。

6 つのオプション引数はウィンドウが newpad() で生成された 場合にのみ指定することができます。追加の引数はパッドやスクリーンの どの部分が含まれるのかを示すために必要です。 pminrow および pmincol にはパッドが表示されている矩形の 左上角を指定します。sminrow, smincol, smaxrow, および smaxcol には、スクリーン上に表示される矩形の縁を指定します。 パッド内に表示される矩形の右下角はスクリーン座標から計算されるので、 矩形は同じサイズでなければなりません。矩形は両方とも、それぞれの ウィンドウ構造内に完全に含まれていなければなりません。 pminrow, pmincol, sminrow, または smincol に負の値を指定すると、ゼロを指定したものとして扱われます。

scroll( [lines = 1])
スクリーンまたはスクロール領域を上に lines 行スクロール します。

scrollok( flag)
ウィンドウのカーソルが、最下行で改行を行ったり最後の文字を入力したり した結果、ウィンドウやスクロール領域の縁からはみ出して移動した際の 動作を制御します。flag が偽の場合、カーソルは最下行にそのまま にしておかれます。flag が真の場合、ウィンドウは 1 行上に スクロールします。端末の物理スクロール効果を得るためには idlok() も呼び出す必要があるので注意してください。

setscrreg( top, bottom)
スクロール領域を top から bottom に設定します。 スクロール動作は全てこの領域で行われます。

standend( )
A_STANDOUT 属性をオフにします。端末によっては、この操作で 全ての属性をオフにする副作用が発生します。

standout( )
A_STANDOUT 属性をオンにします。

subpad( [nlines, ncols,] begin_y, begin_x)
左上の角が (begin_y, begin_x) にあり、幅／高さが それぞれ ncols/nlines であるようなサブウィンドウを返します。

subwin( [nlines, ncols,] begin_y, begin_x)
左上の角が (begin_y, begin_x) にあり、幅／高さが それぞれ ncols/nlines であるようなサブウィンドウを返します。

標準の設定では、サブウィンドウは指定された場所からウィンドウの右下角まで 広がります。

syncdown( )
このウィンドウの上位のウィンドウのいずれかで更新(touch)された各場所を このウィンドウ内でも更新します。 このルーチンは refresh() から呼び出されるので、 手動で呼び出す必要はほとんどないはずです。

syncok( flag)
flag を真にして呼び出すと、ウィンドウが変更された際は常に syncup() を自動的に呼ぶようになります。

syncup( )
ウィンドウ内で更新 (touch) した場所を、上位の全てのウィンドウ内でも更新します。

timeout( delay)
ウィンドウのブロックまたは非ブロック読み込み動作を設定します。 delay が負の場合、ブロック読み出しが使われ、入力を無期限で 待ち受けます。delay がゼロの場合、非ブロック読み出しが 使われ、 入力待ちの文字がない場合 getch() は -1 を返し ます。delay が正の値であれば、 getch() は delay ミリ秒間ブロックし、ブロック後の時点で入力がない場合には -1 を返します。

touchline( start, count)
start から始まる count 行が変更されたかのように 振舞わせます。

touchwin( )
描画を最適化するために、全てのウィンドウが変更されたかのように 振舞わせます。

untouchwin( )
ウィンドウ内の全ての行を、最後に refresh() を呼んだ際から 変更されていないものとしてマークします。

vline( [y, x,] ch, n)
(y, x) から始まり、 n の長さを持つ、 文字 ch で作られる垂直線を表示します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.14.1 関数 Up: 6.14 curses Next: 6.14.3 定数


6.14.3 定数

curses モジュールでは以下のデータメンバを定義しています:

ERR
getch() のような整数を返す curses ルーチンの いくつかは、失敗した際に ERR を返します。

OK
napms() のような整数を返す curses ルーチンの いくつかは、成功した際に OK を返します。

version
モジュールの現在のバージョンを表現する文字列です。 __version__ でも取得できます。

以下に文字セルの属性を指定するために利用可能ないくつかの定数を示します:

属性 | 意味
A_ALTCHARSET | 代用文字 (alternate character) モード。
A_BLINK | 点滅モード。
A_BOLD | 太字モード。
A_DIM | 低輝度モード。
A_NORMAL | 通常の属性。
A_STANDOUT | 強調モード。
A_UNDERLINE | 下線モード。

キーは "KEY_" で始まる名前をもつ整数定数です。利用可能な キーキャップはシステムに依存します。

キー定数 | キー
KEY_MIN | 最小のキー値
KEY_BREAK | ブレーク (Break, 信頼できません)
KEY_DOWN | 下向き矢印 (Down-arrow)
KEY_UP | 上向き矢印 (Up-arrow)
KEY_LEFT | 左向き矢印 (Left-arrow)
KEY_RIGHT | 右向き矢印 (Right-arrow)
KEY_HOME | ホームキー (Home, または上左矢印)
KEY_BACKSPACE | バックスペース (Backspace, 信頼できません)
KEY_F0 | ファンクションキー 64 個までサポートされています。
KEY_Fn | ファンクションキー n の値
KEY_DL | 行削除 (Delete line)
KEY_IL | 行挿入 (Insert line)
KEY_DC | 文字削除 (Delete char)
KEY_IC | 文字挿入、または文字挿入モードへ入る
KEY_EIC | 文字挿入モードから抜ける
KEY_CLEAR | 画面消去
KEY_EOS | 画面の末端まで消去
KEY_EOL | 行末端まで消去
KEY_SF | 前に 1 行スクロール
KEY_SR | 後ろ (逆方向) に 1 行スクロール
KEY_NPAGE | 次のページ (Page Next)
KEY_PPAGE | 前のページ (Page Prev)
KEY_STAB | タブ設定
KEY_CTAB | タブリセット
KEY_CATAB | 全てのタブをリセット
KEY_ENTER | 入力または送信 (信頼できません)
KEY_SRESET | ソフトウェア (部分的) リセット (信頼できません)
KEY_RESET | リセットまたはハードリセット (信頼できません)
KEY_PRINT | 印刷 (Print)
KEY_LL | 下ホーム (Home down) または最下行 (左下)
KEY_A1 | キーパッドの左上キー
KEY_A3 | キーパッドの右上キー
KEY_B2 | キーパッドの中央キー
KEY_C1 | キーパッドの左下キー
KEY_C3 | キーパッドの右下キー
KEY_BTAB | Back tab
KEY_BEG | 開始 (Beg)
KEY_CANCEL | キャンセル (Cancel)
KEY_CLOSE | 閉じる (Close)
KEY_COMMAND | コマンド (Cmd)
KEY_COPY | コピー (Copy)
KEY_CREATE | 生成 (Create)
KEY_END | 終了 (End)
KEY_EXIT | 終了 (Exit)
KEY_FIND | 検索 (Find)
KEY_HELP | ヘルプ (Help)
KEY_MARK | マーク (Mark)
KEY_MESSAGE | メッセージ (Message)
KEY_MOVE | 移動 (Move)
KEY_NEXT | 次へ (Next)
KEY_OPEN | 開く (Open)
KEY_OPTIONS | オプション (Options)
KEY_PREVIOUS | 前へ (Prev)
KEY_REDO | やり直し (Redo)
KEY_REFERENCE | 参照 (Ref)
KEY_REFRESH | 更新 (Refresh)
KEY_REPLACE | 置換 (Replace)
KEY_RESTART | 再起動 (Restart)
KEY_RESUME | 再開 (Resume)
KEY_SAVE | 保存 (Save)
KEY_SBEG | シフト付き開始 Beg
KEY_SCANCEL | シフト付きキャンセル Cancel
KEY_SCOMMAND | シフト付き Command
KEY_SCOPY | シフト付き Copy
KEY_SCREATE | シフト付き Create
KEY_SDC | シフト付き Delete char
KEY_SDL | シフト付き Delete line
KEY_SELECT | 選択 (Select)
KEY_SEND | シフト付き End
KEY_SEOL | シフト付き Clear line
KEY_SEXIT | シフト付き Dxit
KEY_SFIND | シフト付き Find
KEY_SHELP | シフト付き Help
KEY_SHOME | シフト付き Home
KEY_SIC | シフト付き Input
KEY_SLEFT | シフト付き Left arrow
KEY_SMESSAGE | シフト付き Message
KEY_SMOVE | シフト付き Move
KEY_SNEXT | シフト付き Next
KEY_SOPTIONS | シフト付き Options
KEY_SPREVIOUS | シフト付き Prev
KEY_SPRINT | シフト付き Print
KEY_SREDO | シフト付き Redo
KEY_SREPLACE | シフト付き Replace
KEY_SRIGHT | シフト付き Right arrow
KEY_SRSUME | シフト付き Resume
KEY_SSAVE | シフト付き Save
KEY_SSUSPEND | シフト付き Suspend
KEY_SUNDO | シフト付き Undo
KEY_SUSPEND | 一時停止 (Suspend)
KEY_UNDO | 元に戻す (Undo)
KEY_MOUSE | マウスイベント通知
KEY_RESIZE | 端末リサイズイベント
KEY_MAX | 最大キー値

VT100 や、X 端末エミュレータのようなソフトウェアエミュレーションでは、 通常少なくとも 4 つのファンクションキー (KEY_F1、 KEY_F2、 KEY_F3、 KEY_F4) が利用可能 で、矢印キーは KEY_UP、 KEY_DOWN、 KEY_LEFT および KEY_RIGHT が対応付け られています。計算機に PC キーボードが付属している場合、 矢印キーと 12 個のファンクションキー (古い PC キーボードには 10 個しか ファンクションキーがないかもしれません) が利用できると考えて よいでしょう; また、以下のキーパッド対応付けは標準的なものです:

キーキャップ | 定数
Insert | KEY_IC
Delete | KEY_DC
Home | KEY_HOME
End | KEY_END
Page Up | KEY_NPAGE
Page Down | KEY_PPAGE

代用文字 (alternative character) セットを以下の表に列挙します。 これらは VT100 端末から継承したものであり、X 端末のような ソフトウェアエミュレーション上で一般に利用可能なものです。 グラフィックが利用できない場合、curses は印字可能 ASCII文字による 粗雑な近似出力を行います。 注意: これらは initscr() が呼び出された後でしか 利用できません。

ACS コード | 意味
ACS_BBSS | 右上角の別名
ACS_BLOCK | 黒四角ブロック
ACS_BOARD | 白四角ブロック
ACS_BSBS | 水平線の別名
ACS_BSSB | 左上角の別名
ACS_BSSS | 上向き T 字罫線の別名
ACS_BTEE | 下向き T 字罫線
ACS_BULLET | 黒丸(bullet)
ACS_CKBOARD | チェッカーボードパタン (点描)
ACS_DARROW | 下向き矢印
ACS_DEGREE | 度
ACS_DIAMOND | ダイアモンド
ACS_GEQUAL | より大きいか等しい
ACS_HLINE | 水平線
ACS_LANTERN | ランタン(lantern) シンボル
ACS_LARROW | left arrow
ACS_LEQUAL | より小さいか等しい
ACS_LLCORNER | 左下角
ACS_LRCORNER | 右下角
ACS_LTEE | left tee
ACS_NEQUAL | 等号否定
ACS_PI | パイ記号
ACS_PLMINUS | プラスマイナス記号
ACS_PLUS | 大プラス記号
ACS_RARROW | 右向き矢印
ACS_RTEE | 右向き T 字罫線
ACS_S1 | scan line 1
ACS_S3 | scan line 3
ACS_S7 | scan line 7
ACS_S9 | scan line 9
ACS_SBBS | 右下角の別名
ACS_SBSB | 垂直線の別名
ACS_SBSS | 右向き T 字罫線の別名
ACS_SSBB | 左下角の別名
ACS_SSBS | 下向き T 字罫線の別名
ACS_SSSB | 左向き T 字罫線の別名
ACS_SSSS | 交差罫線または大プラス記号の別名
ACS_STERLING | ポンドスターリング記号
ACS_TTEE | 上向き T 字罫線
ACS_UARROW | 上向き矢印
ACS_ULCORNER | 左上角
ACS_URCORNER | 右上角
ACS_VLINE | 垂直線

以下のテーブルは定義済みの色を列挙したものです:

定数 | 色
COLOR_BLACK | 黒
COLOR_BLUE | 青
COLOR_CYAN | シアン (薄く緑がかった青)
COLOR_GREEN | 緑
COLOR_MAGENTA | マゼンタ (紫がかった赤)
COLOR_RED | 赤
COLOR_WHITE | 白
COLOR_YELLOW | 黄色

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.14.2 Window オブジェクト Up: 6.14 curses Next: 6.15 curses.textpad


6.15 curses.textpad -- curses プログラムのためのテキスト入力ウィジェット

バージョン1.6 以降で新規追加された 仕様です。

curses.textpad モジュールでは、curses ウィンドウ内での基本的な テキスト編集を処理し、Emacs に似た (すなわち Netscape Navigator, BBedit 6.x, FrameMaker, その他諸々のプログラムとも似た) キーバインドを サポートしている Textbox クラスを提供します。このモジュールでは また、テキストボックスを枠で囲むなどの目的のために有用な、矩形描画 関数を提供しています。

curses.textpad モジュールでは以下の関数を定義しています:

rectangle( win, uly, ulx, lry, lrx)
矩形を描画します。最初の引数はウィンドウオブジェクトでなければ なりません; 残りの引数はそのウィンドウからの相対座標になります。 2 番目および 3 番目の引数は描画すべき矩形の左上角の y および x 座標です; 4 番目および 5 番目の引数は右下角の y および x 座標です。 矩形は、 VT100/IBM PC におけるフォーム文字を利用できる 端末(xterm やその他のほとんどのソフトウェア端末エミュレータを含む) ではそれを使って描画されます。そうでなければ ASCII 文字のダッシュ、 垂直バー、およびプラス記号で描画されます。

  • 6.15.1 Textbox オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.14.3 定数 Up: 6. 汎用オペレーティングシステムサービス Next: 6.15.1 Textbox オブジェクト


6.15.1 Textbox オブジェクト

以下のような Textbox オブジェクトをインスタンス生成することが できます:

class Textbox( win)
テキストボックスウィジェットオブジェクトを返します。win 引数は、テキストボックスを入れるための WindowObject で なければなりません。テキストボックスの編集カーソルは、最初は テキストボックスが入っているウィンドウの左上角に配置され、その 座標は (0, 0) です。インスタンスの stripspaces フラグの初期値はオンに設定されます。

Textbox オブジェクトは以下のメソッドを持ちます:

edit( [validator])
普段使うことになるエントリポイントです。終了キーストロークの一つが 入力されるまで編集キーストロークを受け付けます。validator を与える場合、関数でなければなりません。validator は キーストロークが入力されるたびにそのキーストロークが引数となって 呼び出されます; 返された値に対して、コマンドキーストロークとして 解釈が行われます。このメソッドはウィンドウの内容を文字列として返します; ウィンドウ内の空白が含められるかどうかは stripspaces メンバ で決められます。

do_command( ch)
単一のコマンドキーストロークを処理します。以下にサポートされている 特殊キーストロークを示します:

キーストローク | 動作
Control-A | ウィンドウの左端に移動します。
Control-B | カーソルを左へ移動し、必要なら前の行に折り返します。
Control-D | カーソル下の文字を削除します。
Control-E | 右端 (stripspaces がオフのとき) または行末 (stripspaces がオンのとき) に移動します。
Control-F | カーソルを右に移動し、必要なら次の行に折り返します。
Control-G | ウィンドウを終了し、その内容を返します。
Control-H | 逆方向に文字を削除します。(バックスペース)
Control-J | ウィンドウが 1 行であれば終了し、そうでなければ新しい行を挿入します。
Control-K | 行が空白行ならその行全体を削除し、そうでなければカーソル以降行末までを消去します。
Control-L | スクリーンを更新します。
Control-N | カーソルを下に移動します; 1 行下に移動します。
Control-O | カーソルの場所に空行を 1 行挿入します。
Control-P | カーソルを上に移動します; 1 行上に移動します。

移動操作は、カーソルがウィンドウの縁にあって移動ができない場合には 何も行いません。場合によっては、以下のような同義のキーストロークが サポートされています:

定数 | キーストローク
KEY_LEFT | Control-B
KEY_RIGHT | Control-F
KEY_UP | Control-P
KEY_DOWN | Control-N
KEY_BACKSPACE | Control-h

他のキーストロークは、与えられた文字を挿入し、(行折り返し付きで) 右に移動するコマンドとして扱われます。

gather( )
このメソッドはウィンドウの内容を文字列として返します; ウィンドウ内の 空白が含められるかどうかは stripspaces メンバ変数で決められ ます。

stripspaces
このデータメンバはウィンドウ内の空白領域の解釈方法を制御するための フラグです。フラグがオンに設定されている場合、各行の末端にある 空白領域は無視されます; すなわち、末端空白領域にカーソルが入ると、 その場所の代わりに行の末尾にカーソルが移動します。また、末端の空白 領域はウィンドウの内容を取得する際に剥ぎ取られます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.15 curses.textpad Up: 6.15 curses.textpad Next: 6.16 curses.wrapper


6.16 curses.wrapper -- curses プログラムのための端末ハンドラ

バージョン1.6 以降で新規追加された 仕様です。

このモジュールでは関数 wrapper() 一つを提供しています。 これは curses 使用アプリケーションの残りの部分となるもう一つの関数です。 アプリケーションが例外を送出した場合、wrapper() は スタックを整理してトレースバックを生成する前に端末を正常な状態に 復元します。

wrapper( func, ...)
curses を初期化し、別の関数 func を呼び出、エラーが発生 した場合には通常のキーボード／スクリーン動作に戻すラッパ関数です。 呼び出し可能オブジェクト func は主ウィンドウの 'stdscr' に 対する最初の引数として渡されます。その他の引数は wrapper() に渡されます。

フック関数を呼び出す前に、 wrapper() は cbreak モード をオン、エコーをオフにし、端末キーパッドを有効にします。 端末がカラーをサポートしている場合にはカラーを初期化します。 (通常終了も例外による終了も) 終了時には cooked モードに復元し、 エコーをオンにし、端末キーパッドを無効化します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.15.1 Textbox オブジェクト Up: 6. 汎用オペレーティングシステムサービス Next: 6.17 curses.ascii


6.17 curses.ascii -- ASCII 文字に関するユーティリティ

バージョン1.6 以降で新規追加された 仕様です。

curses.ascii モジュールでは、 ASCII 文字を指す 名前定数と、様々な ASCII 文字区分についてある文字が帰属するか どうかを調べる関数を提供します。 このモジュールで提供されている定数は以下の制御文字の名前です:

Name | Meaning
NUL | 空
SOH | ヘディング開始、コンソール割り込み
STX | テキスト開始
ETX | テキスト終了
EOT | テキスト伝送終了
ENQ | 問い合わせ、ACK フロー制御時に使用
ACK | 肯定応答
BEL | ベル
BS | 一文字後退
TAB | タブ
HT | TAB の別名: ``水平タブ''
LF | 改行
NL | LF の別名: ``改行''
VT | 垂直タブ
FF | 改頁
CR | 復帰
SO | シフトアウト、他の文字セットの開始
SI | シフトイン、標準の文字セットに復帰
DLE | データリンクでのエスケープ
DC1 | 装置制御 1、フロー制御のための XON
DC2 | 装置制御 2、ブロックモードフロー制御
DC3 | 装置制御 3、フロー制御のための XOFF
DC4 | 装置制御 4
NAK | 否定応答
SYN | 同期信号
ETB | ブロック転送終了
CAN | キャンセル
EM | 媒体終端
SUB | 代入文字
ESC | エスケープ文字
FS | ファイル区切り文字
GS | グループ区切り文字
RS | レコード区切り文字、ブロックモード終了子
US | 単位区切り文字
SP | 空白文字
DEL | 削除

これらの大部分は、最近は実際に定数の意味通りに使われることがほとんど ないので注意してください。これらのニーモニック符号はデジタル計算機 より前のテレプリンタにおける慣習から付けられたものです。

このモジュールでは、標準 C ライブラリの関数を雛型とする以下の関数を サポートしています:

isalnum( c)
ASCII 英数文字かどうかを調べます; "isalpha(c) or isdigit(c)" と等価です。

isalpha( c)
ASCII アルファベット文字かどうかを調べます; "isupper(c) or islower(c)" と等価です。

isascii( c)
文字が 7 ビット ASCII 文字に合致するかどうかを調べます。

isblank( c)
ASCII 余白文字かどうかを調べます。

iscntrl( c)
ASCII 制御文字 (0x00 から 0x1f の範囲) かどうかを調べます。

isdigit( c)
ASCII 10 進数字、すなわち "0" から "9" までの 文字かどうかを調べます。 "c in string.digits" と等価です。

isgraph( c)
空白以外の ASCII 印字可能文字かどうかを調べます。

islower( c)
ASCII 小文字かどうかを調べます。

isprint( c)
空白文字を含め、 ASCII 印字可能文字かどうかを調べます。

ispunct( c)
空白または英数字以外の ASCII 印字可能文字かどうかを調べます。

isspace( c)
ASCII 余白文字、すなわち空白、改行、復帰、改頁、水平タブ、 垂直タブかどうかを調べます。

isupper( c)
ASCII 大文字かどうかを調べます。

isxdigit( c)
ASCII 16 進数字かどうかを調べます。 "c in string.hexdigits" と等価です。

isctrl( c)
ASCII 制御文字 (0 から 31 までの値) かどうかを調べます。

ismeta( c)
非 ASCII 文字 (0x80 またはそれ以上の値) かどうかを調べます。

これらの関数は数字も文字列も使えます; 引数を文字列にした場合、 組み込み関数 ord() を使って変換されます。

これらの関数は全て、関数に渡した文字列の最初の文字から得られた ビット値を調べるので注意してください; 関数はホスト計算機で使われている 文字列エンコーディングについて何ら関知しません。文字列エンコーディング について関知する (そして国際化に関するプロパティを正しく扱う) 関数 については、 モジュール string を参照してください。

以下の 2 つの関数は、引数として 1 文字の文字列または整数で表したバイト値の どちらでもとり得ます; これらの関数は引数と同じ型で値を返します。

ascii( c)
ASCII 値を返します。c の下位 7 ビットに対応します。

ctrl( c)
与えた文字に対応する制御文字を返します (0x1f とビット単位で論理積 を取ります) 。

alt( c)
与えた文字に対応する 8 ビット文字を返します (0x80 とビット単位で論理和 を取ります) 。

以下の関数は 1 文字からなる文字列値または整数値を引数に取り、文字列 を返します。

unctrl( c)
ASCII 文字 c の文字列表現を返します。もし c が印字可能 文字であれば、返される文字列は c そのものになります。 もし c が制御文字 (0x00-0x1f) であれば、 キャレット ("^") と、その後ろに続く c に対応した 大文字からなる文字列になります。c が ASCII 削除文字 (0x7f) であれば、文字列は '^?' になります。c のメタビット (0x80) がセットされていれば、メタビットは取り去られ、前述のルール が適用され、"!" が前につけられます。

controlnames
0 (NUL) から 0x1f (US) までの 32 の ASCII 制御文字と、空白文字 "SP" のニーモニック符号名からなる 33 要素の文字列による配列です。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.16 curses.wrapper Up: 6. 汎用オペレーティングシステムサービス Next: 6.18 curses.panel


6.18 curses.panel -- curses のためのパネルスタック拡張

パネルは深さ (depth) の機能が追加されたウィンドウです。これにより、 ウィンドウをお互いに重ね合わせることができ、各ウィンドウの可視部分だけ が表示されます。パネルはスタック中に追加したり、スタック内で上下移動 させたり、スタックから除去することができます。

  • 6.18.1 関数
  • 6.18.2 Panel オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.17 curses.ascii Up: 6. 汎用オペレーティングシステムサービス Next: 6.18.1 関数


6.18.1 関数

curses.panel では以下の関数を定義しています:

bottom_panel( )
パネルスタックの最下層のパネルを返します。

new_panel( win)
与えられたウィンドウ win に関連付けられたパネルオブジェクトを 返します。

top_panel( )
パネルスタックの最上層のパネルを返します。

update_panels( )
仮想スクリーンをパネルスタック変更後の状態に更新します。この関数では curses.doupdate() を呼ばないので、ユーザは自分で呼び出す 必要があります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.18 curses.panel Up: 6.18 curses.panel Next: 6.18.2 Panel オブジェクト


6.18.2 Panel オブジェクト

上記の new_panel() が返す Panel オブジェクトは スタック順の概念を持つウィンドウです。 ウィンドウはパネルに関連付けられており、表示する内容を決定 している一方、パネルのメソッドはパネルスタック中のウィンドウの深さ 管理を担います。

Panel オブジェクトは以下のメソッドを持っています:

above( )
現在のパネルの上にあるパネルを返します。

below( )
現在のパネルの下にあるパネルを返します。

bottom( )
パネルをスタックの最下層にプッシュします。

hidden( )
パネルが隠れている (不可視である) 場合に真を返し、そうでない場合 偽を返します。

hide( )
パネルを隠します。この操作ではオブジェクトは消去されず、 スクリーン上のウィンドウを不可視にするだけです。

move( y, x)
パネルをスクリーン座標 (y, x) に移動します。

replace( win)
パネルに関連付けられたウィンドウを win に変更します。

set_userptr( obj)
パネルのユーザポインタを obj に設定します。このメソッドは 任意のデータをパネルに関連付けるために使われ、任意の Python オブジェクト にすることができます。

show( )
(隠れているはずの) パネルを表示します。

top( )
パネルをスタックの最上層にプッシュします。

userptr( )
パネルのユーザポインタを返します。任意の Python オブジェクトです。

window( )
パネルに関連付けられているウィンドウオブジェクトを返します。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.18.1 関数 Up: 6.18 curses.panel Next: 6.19 getopt


6.19 getopt -- コマンドラインオプションのパーザ

このモジュールはsys.argvに入っているコマンドラインオプションの構文解 析を支援します。 `-' や `--' の特別扱いも含めて、 Unixのgetopt()と同じ記法をサポートしています。 3番目の引数(省略可能)を設定することで、 GNUのソフトウェアでサポートされているような長形式のオプションも利用することが できます。 このモジュールは1つの関数と例外を提供しています:

getopt( args, options[, long_options])
コマンドラインオプションとパラメータのリストを構文解析します。 argsは構文解析の対象になる引数リストです。これは 先頭のプログラム名を除いたもので、通常"sys.argv[1:]"で与えられます。 options はスクリプトで認識させたいオプション文字と、引数が必要な場 合にはコロン(":")をつけます。つまりUnixの getopt()と同じフォーマットになります。

注意: GNUの getopt()とは違って、オプションでない引数の後は全て オプションではないと判断されます。これは GNUでない、Unixシステムの挙 動に近いものです。

long_optionsは長形式のオプションの名前を示す文字列のリストです。 名前には、先頭の'--'は含めません。引数が必要な場合 には名前の最後に等号("=")を入れます。長形式のオプションだけを 受けつけるためには、optionsは空文字列である必要があります。 長形式のオプションは、該当するオプションを一意に決定できる長さまで入力さ れていれば認識されます。たとえば、long_optionsが ['foo', 'frob']の場合、--foは--foo に該当しますが、--f では一意に決定できないので、 GetoptErrorが発生します。

返り値は2つの要素から成っています: 最初は (option, value)のタプルのリスト、2つ目はオプションリス トを取り除いたあとに残ったプログラムの引数リストです(argsの末尾部 分のスライスになります)。 それぞれの引数と値のタプルの最初の要素は、短形式の時はハイフン 1つで始まる文字列(例:'-x')、長形式の時はハイフン2つで始まる文字 列(例: '--long-option')となり、引数が2番目の要素になりま す。引数をとらない場合には空文字列が入ります。オプションは見つかった順 に並んでいて、複数回同じオプションを指定することができます。長形式と短 形式のオプションは混在させることができます。

gnu_getopt( args, options[, long_options])

この関数はデフォルトでGNUスタイルのスキャンモードを使う以外は getopt()と同じように動作します。つまり、オプションと オプションでない引数とを混在させることができます。getopt()関 数はオプションでない引数を見つけると解析をやめてしまいます。

オプション文字列の最初の文字が '+'にするか、環境変数 POSIXLY_CORRECTを設定することで、 オプションでない引数を見つけると解析をやめるように振舞いを変えることがで きます。

exception GetoptError

引数リストの中に認識できないオプションがあった場合か、引数が必要なオプショ ンに引数が与えられなかった場合に発生します。例外の引数は原因を示す文字 列です。長形式のオプションについては、不要な引数が与えられた場合にもこ の例外が発生します。msg属性とopt属性で、エラーメッセー ジと関連するオプションを取得できます。特に関係するオプションが無い場合 にはoptは空文字列となります。

バージョン1.6 以降で変更された 仕様: GetoptError は errorの別名として導入されました。

exception error
GetoptErrorへのエイリアスです。後方互換性のために残されてい ます。

Unixスタイルのオプションを使った例です:

>>> import getopt
>>> args = '-a -b -cfoo -d bar a1 a2'.split()
>>> args
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'abc:d:')
>>> optlist
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']

長形式のオプションを使っても同様です:

>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
>>> args = s.split()
>>> args
['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'x', [
...     'condition=', 'output-file=', 'testing'])
>>> optlist
[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x',
 '')]
>>> args
['a1', 'a2']

スクリプト中での典型的な使い方は以下のようになります:

import getopt, sys

def main():
    try:
        opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
    except getopt.GetoptError:
        # ヘルプメッセージを出力して終了
        usage()
        sys.exit(2)
    output = None
    verbose = False
    for o, a in opts:
        if o == "-v":
            verbose = True
        if o in ("-h", "--help"):
            usage()
            sys.exit()
        if o in ("-o", "--output"):
            output = a
    # ...

if __name__ == "__main__":
    main()
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.18.2 Panel オブジェクト Up: 6. 汎用オペレーティングシステムサービス Next: 6.20 optparse


6.20 optparse -- 強力なコマンドラインオプション解析器

バージョン2.3 以降で新規追加された 仕様です。

optparse モジュールは、Python による強力で柔軟、拡張性があり 簡単に利用できるコマンドライン解析ライブラリです。 optparse を使うことで、有能で洗練されたコマンドラインオプションの 解析機能を少ない労力でスクリプトに追加できます。

以下は optparse を使っていくつかのコマンドラインオプション を簡単なスクリプトに追加する例です:

from optparse import OptionParser

parser = OptionParser()
parser.add_option("-f", "--file", dest="filename",
                  help="write report to FILE", metavar="FILE")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose", default=1,
                  help="don't print status messages to stdout")

(options, args) = parser.parse_args()

このようにわずかな行数のコードによって、スクリプトのユーザは コマンドライン上で以下のような "よくある使い方" を実行できるように なります:

$ <yourscript> -f outfile --quiet
$ <yourscript> -qfoutfile
$ <yourscript> --file=outfile -q
$ <yourscript> --quiet --file outfile

(これらの結果は全て options.filename == "outfile" および options.verbose == 0 ...つまり予想していた結果となります)

もっと気の利いたことに、ユーザは

$ <yourscript> -h
$ <yourscript> --help
のいずれかを実行することができ、optparse はスクリプトの オプションについて簡単にまとめた内容を出力します:

usage: <yourscript> [options]

options:
  -h, --help           show this help message and exit
  -fFILE, --file=FILE  write report to FILE
  -q, --quiet          don't print status messages to stdout

以上は optparse がコマンドライン解析に与える柔軟性のほんの 一部にすぎません。

  • 6.20.1 オプション解析への道
    • 6.20.1.1 用語
    • 6.20.1.2 オプションはどう使うのでしょうか？
    • 6.20.1.3 固定引数はどう使うのでしょうか？
  • 6.20.2 基本的な使い方
    • 6.20.2.1 "store" アクション
    • 6.20.2.2 その他の "store_*" 操作
    • 6.20.2.3 デフォルト値を設定する
    • 6.20.2.4 ヘルプを作成する
    • 6.20.2.5 バージョン番号を出力する
    • 6.20.2.6 エラー処理
    • 6.20.2.7 全てをつなぎ合わせる
  • 6.20.3 進んだ使い方
    • 6.20.3.1 パーザを生成してオプションを追加する
    • 6.20.3.2 オプションを定義する
    • 6.20.3.3 オプションに対するアクション
    • 6.20.3.4 オプションの型
    • 6.20.3.5 オプションパーザへのクエリと操作
    • 6.20.3.6 オプション間の衝突
  • 6.20.4 callback オプション
    • 6.20.4.1 callback オプションを定義する
    • 6.20.4.2 コールバック関数はどのように呼び出されるか
    • 6.20.4.3 エラー処理
    • 6.20.4.4 例
  • 6.20.5 optparse を拡張する
    • 6.20.5.1 新たな型を追加する
    • 6.20.5.2 新たなアクションを追加する
    • 6.20.5.3 拡張を行う他の理由 optparse
    • 6.20.5.4 拡張の例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.19 getopt Up: 6. 汎用オペレーティングシステムサービス Next: 6.20.1 オプション解析への道


6.20.1 オプション解析への道

optparse は、私が考えている最も明瞭かつ素直で ユーザフレンドリーなコマンドラインプログラムのインタフェース を設計するための方法を実装したものです。

簡単に言うと、私は引数解析の王道 (そしてたくさんの邪道) についてかなり頑固な考えを持っており、optparse はそういった考えの多くを反映しています。 この節では上記の哲学について説明するつもりです。この哲学は Unix と GNU ツールキットに強く影響されています。

  • 6.20.1.1 用語
  • 6.20.1.2 オプションはどう使うのでしょうか？
  • 6.20.1.3 固定引数はどう使うのでしょうか？
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20 optparse Up: 6.20 optparse Next: 6.20.1.1 用語


6.20.2 基本的な使い方

optparse はとても柔軟性があって強力な一方、基本的なケースを 動作させるために試練を受けたり大量のドキュメントを読む必要は ありません。 このドキュメントでは、いくつかの単純な使用パターンを実演して、 スクリプトで optparse を使えるようにすることを目的としています。

コマンドラインを optparse で解析するためには、 OptionParser インスタンスを作成して populate する必要が あります。当然ながら、optparse を使うスクリプトはいずれも OptionParser クラスを import しなければなりません。

from optparse import OptionParser

メインプログラムの冒頭で、パーザを作成してください:

parser = OptionParser()

これで、パーザ内のオプションを移すことができます。各オプションは 現実には同義のオプション文字列になります; ほとんどの場合、 短いオプション文字列を一つと、長いオプション文字列を一つ -- 例えば -f and --file -- を持ちます:

parser.add_option("-f", "--file", ...)

もちろん、最も知りたいことは、オプション文字列の後に続くキーワード 引数が何かということです。このドキュメントでは、キーワード引数として 指定できる内容について 4 種類: action、type、 dest (destination: 目的変数)、 およびhelp だけをカバーします。

  • 6.20.2.1 "store" アクション
  • 6.20.2.2 その他の "store_*" 操作
  • 6.20.2.3 デフォルト値を設定する
  • 6.20.2.4 ヘルプを作成する
  • 6.20.2.5 バージョン番号を出力する
  • 6.20.2.6 エラー処理
  • 6.20.2.7 全てをつなぎ合わせる
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.1.3 固定引数はどう使うのでしょうか？ Up: 6.20 optparse Next: 6.20.2.1 "store" アクション


6.20.3 進んだ使い方

ここからはリファレンスのドキュメントです。まだ 6.20.2 節の基本的なドキュメントを読んでいない なら、まず読んでください。

  • 6.20.3.1 パーザを生成してオプションを追加する
  • 6.20.3.2 オプションを定義する
  • 6.20.3.3 オプションに対するアクション
  • 6.20.3.4 オプションの型
  • 6.20.3.5 オプションパーザへのクエリと操作
  • 6.20.3.6 オプション間の衝突
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.2.7 全てをつなぎ合わせる Up: 6.20 optparse Next: 6.20.3.1 パーザを生成してオプションを追加する


6.20.4 callback オプション

optparse の組み込みのアクションや型が望みにかなったもので なく、とはいえ optparse を拡張して独自のアクションや型を 定義するほどではない場合、おそらく callback オプションを定義する 必要があるでしょう。callback オプションの定義はきわめて簡単です; 注意を要するのは、よいコールバック関数 (callback function、 optparse がオプションをコマンドライン上に見つけた際に 呼び出される関数) を書くところです。

  • 6.20.4.1 callback オプションを定義する
  • 6.20.4.2 コールバック関数はどのように呼び出されるか
  • 6.20.4.3 エラー処理
  • 6.20.4.4 例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.3.6 オプション間の衝突 Up: 6.20 optparse Next: 6.20.4.1 callback オプションを定義する


6.20.5 optparse を拡張する

optparse がコマンドラインオプションを解析する手法における 二つの主要な制御要素は、各オプションに対するアクションと型です。 このため、ほとんどの拡張の方向性は、新たなアクションか型の追加に なっています。

また、拡張例の節には optparse に対する異なったやり方での 拡張を実演したものが収められています: 例えば、大小文字の区別 をしないオプションパーザや、``必須オプション'' を実装している 二種類のオプションパーザです。

  • 6.20.5.1 新たな型を追加する
  • 6.20.5.2 新たなアクションを追加する
  • 6.20.5.3 拡張を行う他の理由 optparse
  • 6.20.5.4 拡張の例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.4.4 例 Up: 6.20 optparse Next: 6.20.5.1 新たな型を追加する


6.21 tempfile -- 一時的なファイルやディレクトリの生成

このモジュールを使うと、一時的なファイルやディレクトリを生成できます。 このモジュールはサポートされている全てのプラットフォームで利用可能 です。

バージョン 2.3 の Python では、このモジュールに対してセキュリティを 高める為の見直しが行われました。現在では新たに 3 つの関数、 NamedTemporaryFile()、 mkstemp()、および mkdtemp() が提供されており、安全でない mktemp を使いつづける必要をなくしました。 このモジュールで生成される一時ファイルはもはやプロセス番号を 含みません; その代わり、6 桁のランダムな文字からなる文字列が 使われます。

また、ユーザから呼び出し可能な関数は全て、一時ファイルの場所や 名前を直接操作できるようにするための追加の引数をとるように なりました。もはや変数 tempdir および template を 使う必要はありません。以前のバージョンとの互換性を維持するために、 引数の順番は多少変です; 明確さのためにキーワード引数を使うことを お勧めします。

このモジュールではユーザから呼び出し可能な以下の関数を定義しています:

TemporaryFile( [mode='w+b'][, bufsize=-1][, suffix][, prefix][, dir])
一時的な記憶領域として使うことができるファイル (またはファイル類似の) オブジェクトを返します。ファイルは mkstemp を使って 生成されます。このファイルは閉じられると (オブジェクトが ガーベジコレクションされた際に、暗黙のうちに閉じられる場合を含みます) すぐに消去されます。Unix環境では、ファイルが生成されるとすぐに そのファイルのディレクトリエントリは除去されてしまいます。一方、他の プラットフォームではこの機能はサポートされていません; 従って、 コードを書くときには、この関数で作成した一時ファイルをファイルシステム上で見る ことができる、あるいはできないということをあてにすべきではありません。

生成されたファイルを一旦閉じなくてもファイルを読み書きできるように するために、mode パラメタは標準で 'w+b' に設定されています。 ファイルに記録するデータが何であるかに関わらず全てのプラットフォームで 一貫性のある動作をさせるために、バイナリモードが使われています。 bufsize の値は標準で -1 で、これはオペレーティングシステム における標準の値を使うことを意味しています。

dir、prefix および suffix パラメタは mkstemp() に渡されます。

NamedTemporaryFile( [mode='w+b'][, bufsize=-1][, suffix][, prefix][, dir])
この関数はファイルがファイルシステム上で見ることができるよう保証 されている点を除き、TemporaryFile() と全く同じに働きます。 (Unixでは、ディレクトリ エントリはunlinkされません) ファイル名はファイルオブジェクトの name メンバから 取得することができます。このファイル名を使って一時ファイルをもう一度 開くとことができるかどうかは、プラットフォームによって異なります。 (Unixでは可能でしたが、Windows NT以降では開く事ができません。)

バージョン2.3 以降で新規追加された 仕様です。

mkstemp( [suffix][, prefix][, dir][, text=False])
可能な限り最も安全な手段で一時ファイルを生成します。 使用するプラットフォームでos.open() の O_EXCL フラグが正しく実装されている限り、ファイルの生成で競合条件が起こる ことはありません。このファイルは、ファイルを生成したユーザのユーザ ID からのみ読み書き可能です。使用するプラットフォームにおいて、 ファイルを実行可能かどうかを示す許可ビットが使われている場合、 ファイルは誰からも実行不可なように設定されます。 このファイルのファイル記述子は子プロセスに継承されません。

TemporaryFile() と違って、mkstemp() で生成された ファイルが用済みになったときにファイルを消去するのはユーザの責任です。

suffix が指定された場合、ファイル名は指定された 拡張子で終わります。そうでない場合には拡張子は付けられません。 mkstemp() はファイル名と拡張子の間にドットを追加 しません; 必要なら、suffix の先頭につけてください。

prefix が指定された場合、ファイル名は指定された プレフィクス(接頭文字列) で始まります; そうでない場合、標準の プレフィクスが使われます。

dir が指定された場合、一時ファイルは指定されたディレクトリ 下に作成されます; そうでない場合、標準のディレクトリが使われます。

text が指定された場合、ファイルをバイナリモード (標準の設定) かテキストモードで開くかを示します。使用するプラットフォームによっては この値を設定しても変化はありません。

mkstemp() は開かれたファイルを扱うための OS レベルの値 とファイルの絶対パス名が順番に並んだタプルを返します。 バージョン2.3 以降で新規追加された 仕様です。

mkdtemp( [suffix][, prefix][, dir])
可能な限り安全な方法で一時ディレクトリを作成します。 ディレクトリの生成で競合条件は発生しません。 ディレクトリを作成したユーザ ID だけが、このディレクトリ に対して内容を読み出したり、書き込んだり、検索したりすることが できます。

mkdtemp() によって作られたディレクトリとその内容が用済みに なった時、にそれを消去するのはユーザの責任です。

prefix、suffix、および dir 引数は mkstemp() のものと同じです。

mkdtemp() は新たに生成されたディレクトリの絶対パス名を 返します。 バージョン2.3 以降で新規追加された 仕様です。

mktemp( [suffix][, prefix][, dir])
リリース 2.3 以降で撤廃された仕様です。 Use mkstemp() instead.
一時ファイルの絶対パス名を返します。このパス名は少なくともこの関数が 呼び出された時点ではファイルシステム中に存在しなかったパス名です。 prefix、prefix、 suffix、および dir 引数は mkstemp() のものと同じです。

警告: この関数を使うとプログラムのセキュリティホールになる可能性 があります。この関数が返したファイル名を返した後、あなたがそのファイル名 を使って次に何かをしようとする段階に至る前に、誰か他の人間が あなたにパンチをくらわせてしまうかもしれません。

このモジュールでは、一時的なファイル名の作成方法を指定する 2 つの グローバル変数を使います。これらの変数は上記のいずれかの関数を最初 に呼び出した際に初期化されます。関数呼び出しをおこなうユーザは これらの値を変更することができますが、これはお勧めできません; その代わりに関数に適切な引数を指定してください。

tempdir
この値が None 以外に設定された場合、このモジュールで定義されて いる関数全てのdir 引数に対する標準の設定値となります。

tempdir が設定されていないか None の場合、上記のいずれかの 関数を呼び出した際は常に、Python は標準的なディレクトリ候補のリスト を検索し、関数を呼び出しているユーザの権限でファイルを作成できる 最初のディレクトリ候補を tempdir に設定します。リストは以下の ようになっています:

  1. 環境変数 TMPDIR で与えられているディレクトリ名。
  2. 環境変数 TEMP で与えられているディレクトリ名。
  3. 環境変数 TMP で与えられているディレクトリ名。
  4. プラットフォーム依存の場所:
    • Macintosh では Temporary Items フォルダ。
    • RiscOS では環境変数 Wimp$ScrapDir で与えられて いるディレクトリ名。
    • Windows ではディレクトリ C:\TEMP、 C:\TMP、 \TEMP、および \TMP の順。
    • その他の全てのプラットフォームでは、/tmp、 /var/tmp、および /usr/tmp の順。
  5. 最後の手段として、現在の作業ディレクトリ。

gettempdir( )
現在選択されている、テンポラリファイルを作成するためのディレクトリ を返します。tempdir が None でない場合、単にその内容 を返します; そうでない場合には上で記述されている検索が実行され、 その結果が返されます。

template
リリース 2.0 以降で撤廃された仕様です。 代わりに gettempprefix() を使ってください。
この値に None 以外の値を設定した場合、mktemp() が返すファイル名のディレクトリ部を含まない先頭部分 (プレフィクス) を 定義します。ファイル名を一意にするために、 6 つのランダムな文字および 数字がこのプレフィクスの後に追加されます。Windows では、標準の プレフィクスは~T です; 他のシステムでは tmp です。

このモジュールの古いバージョンでは、os.fork() を呼び出した 後に template を None に設定することが必要でした; この仕様はバージョン 1.5.2 からは必要なくなりました。

gettempprefix( )
一時ファイルを生成する際に使われるファイル名の先頭部分を返します。 この先頭部分にはディレクトリ部は含まれません。変数 template を直接読み出すよりもこの関数を使うことを勧めます。 バージョン1.5.2 以降で新規追加された 仕様です。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.5.4 拡張の例 Up: 6. 汎用オペレーティングシステムサービス Next: 6.22 errno


6.22 errno -- 標準の errno システムシンボル

このモジュールから標準の errno システムシンボルを取得することが できます。個々のシンボルの値は errno に対応する整数値です。 これらのシンボルの名前は、linux/include/errno.h から借用され ており、かなり網羅的なはずです。

errorcode
errno 値を背後のシステムにおける文字列表現に対応付ける辞書です。 例えば、errno.errorcode[errno.EPERM] は 'EPERM' に対応付けられます。

数値のエラーコードをエラーメッセージに変換するには、 os.strerror() を使ってください。

以下のリストの内、現在のプラットフォームで使われていないシンボルは モジュール上で定義されていません。定義されているシンボルだけを挙げた リストは errno.errorcode.keys() として取得することができます。 取得できるシンボルには以下のようなものがあります:

EPERM
許可されていない操作です (Operation not permitted)
ENOENT
ファイルまたはディレクトリがありません (No such file or directory)
ESRCH
指定したプロセスが存在しません (No such process)
EINTR
割り込みシステムコールです (Interrupted system call)
EIO
I/O エラーです (I/O error)
ENXIO
そのようなデバイスまたはアドレスはありません (No such device or address)
E2BIG
引数リストが長すぎます (Arg list too long)
ENOEXEC
実行形式にエラーがあります (Exec format error)
EBADF
ファイル番号が間違っています (Bad file number)
ECHILD
子プロセスがありません (No child processes)
EAGAIN
再試行してください (Try again)
ENOMEM
空きメモリがありません (Out of memory)
EACCES
許可がありません (Permission denied)
EFAULT
不正なアドレスです (Bad address)
ENOTBLK
ブロックデバイスが必要です (Block device required)
EBUSY
そのデバイスまたは資源は使用中です (Device or resource busy)
EEXIST
ファイルがすでに存在します (File exists)
EXDEV
デバイス間のリンクです (Cross-device link)
ENODEV
そのようなデバイスはありません (No such device)
ENOTDIR
ディレクトリではありません (Not a directory)
EISDIR
ディレクトリです (Is a directory)
EINVAL
無効な引数です (Invalid argument)
ENFILE
ファイルテーブルがオーバフローしています (File table overflow)
EMFILE
開かれたファイルが多すぎます (Too many open files)
ENOTTY
タイプライタではありません (Not a typewriter)
ETXTBSY
テキストファイルが使用中です (Text file busy)
EFBIG
ファイルが大きすぎます (File too large)
ENOSPC
デバイス上に空きがありません (No space left on device)
ESPIPE
不正なシークです (Illegal seek)
EROFS
読み出し専用ファイルシステムです (Read-only file system)
EMLINK
リンクが多すぎます (Too many links)
EPIPE
パイプが壊れました (Broken pipe)
EDOM
数学引数が関数の定義域を越えています (Math argument out of domain of func)
ERANGE
表現できない数学演算結果になりました (Math result not representable)
EDEADLK
リソースのデッドロックが起きます (Resource deadlock would occur)
ENAMETOOLONG
ファイル名が長すぎます (File name too long)
ENOLCK
レコードロッキングが利用できません (No record locks available)
ENOSYS
実装されていない機能です (Function not implemented)
ENOTEMPTY
ディレクトリが空ではありません (Directory not empty)
ELOOP
これ以上シンボリックリンクを追跡できません (Too many symbolic links encountered)
EWOULDBLOCK
操作がブロックします (Operation would block)
ENOMSG
指定された型のメッセージはありません (No message of desired type)
EIDRM
識別子が除去されました (Identifier removed)
ECHRNG
チャネル番号が範囲を超えました (Channel number out of range)
EL2NSYNC
レベル 2 で同期がとれていません (Level 2 not synchronized)
EL3HLT
レベル 3 で終了しました (Level 3 halted)
EL3RST
レベル 3 でリセットしました (Level 3 reset)
ELNRNG
リンク番号が範囲を超えています (Link number out of range)
EUNATCH
プロトコルドライバが接続されていません (Protocol driver not attached)
ENOCSI
CSI 構造体がありません (No CSI structure available)
EL2HLT
レベル 2 で終了しました (Level 2 halted)
EBADE
無効な変換です (Invalid exchange)
EBADR
無効な要求記述子です (Invalid request descriptor)
EXFULL
変換テーブルが一杯です (Exchange full)
ENOANO
陰極がありません (No anode)
EBADRQC
無効なリクエストコードです (Invalid request code)
EBADSLT
無効なスロットです (Invalid slot)
EDEADLOCK
ファイルロックにおけるデッドロックエラーです (File locking deadlock error)
EBFONT
フォントファイル形式が間違っています (Bad font file format)
ENOSTR
ストリーム型でないデバイスです (Device not a stream)
ENODATA
利用可能なデータがありません (No data available)
ETIME
時間切れです (Timer expired)
ENOSR
streams リソースを使い切りました (Out of streams resources)
ENONET
計算機はネットワーク上にありません (Machine is not on the network)
ENOPKG
パッケージがインストールされていません (Package not installed)
EREMOTE
対象物は遠隔にあります (Object is remote)
ENOLINK
リンクが切られました (Link has been severed)
EADV
Advertise エラーです (Advertise error)
ESRMNT
Srmount エラーです (Srmount error)
ECOMM
送信時の通信エラーです (Communication error on send)
EPROTO
プロトコルエラーです (Protocol error)
EMULTIHOP
多重ホップを試みました (Multihop attempted)
EDOTDOT
RFS 特有のエラーです (RFS specific error)
EBADMSG
データメッセージではありません (Not a data message)
EOVERFLOW
定義されたデータ型にとって大きすぎる値です (Value too large for defined data type)
ENOTUNIQ
名前がネットワーク上で一意でありません (Name not unique on network)
EBADFD
ファイル記述子の状態が不正です (File descriptor in bad state)
EREMCHG
遠隔のアドレスが変更されました (Remote address changed)
ELIBACC
必要な共有ライブラリにアクセスできません (Can not access a needed shared library)
ELIBBAD
壊れた共有ライブラリにアクセスしています (Accessing a corrupted shared library)
ELIBSCN
a.out の .lib セクションが壊れています (.lib section in a.out corrupted)
ELIBMAX
リンクを試みる共有ライブラリが多すぎます (Attempting to link in too many shared libraries)
ELIBEXEC
共有ライブラリを直接実行することができません (Cannot exec a shared library directly)
EILSEQ
不正なバイト列です (Illegal byte sequence)
ERESTART
割り込みシステムコールを復帰しなければなりません (Interrupted system call should be restarted)
ESTRPIPE
ストリームパイプのエラーです (Streams pipe error)
EUSERS
ユーザが多すぎます (Too many users)
ENOTSOCK
非ソケットに対するソケット操作です (Socket operation on non-socket)
EDESTADDRREQ
目的アドレスが必要です (Destination address required)
EMSGSIZE
メッセージが長すぎます (Message too long)
EPROTOTYPE
ソケットに対して不正なプロトコル型です (Protocol wrong type for socket)
ENOPROTOOPT
利用できないプロトコルです (Protocol not available)
EPROTONOSUPPORT
サポートされていないプロトコルです (Protocol not supported)
ESOCKTNOSUPPORT
サポートされていないソケット型です (Socket type not supported)
EOPNOTSUPP
通信端点に対してサポートされていない操作です (Operation not supported on transport endpoint)
EPFNOSUPPORT
サポートされていないプロトコルファミリです (Protocol family not supported)
EAFNOSUPPORT
プロトコルでサポートされていないアドレスファミリです (Address family not supported by protocol)
EADDRINUSE
アドレスは使用中です (Address already in use)
EADDRNOTAVAIL
要求されたアドレスを割り当てできません (Cannot assign requested address)
ENETDOWN
ネットワークがダウンしています (Network is down)
ENETUNREACH
ネットワークに到達できません (Network is unreachable)
ENETRESET
リセットによってネットワーク接続が切られました (Network dropped connection because of reset)
ECONNABORTED
ソフトウェアによって接続が終了されました (Software caused connection abort)
ECONNRESET
接続がピアによってリセットされました (Connection reset by peer)
ENOBUFS
バッファに空きがありません (No buffer space available)
EISCONN
通信端点がすでに接続されています (Transport endpoint is already connected)
ENOTCONN
通信端点が接続されていません (Transport endpoint is not connected)
ESHUTDOWN
通信端点のシャットダウン後は送信できません (Cannot send after transport endpoint shutdown)
ETOOMANYREFS
参照が多すぎます: 接続できません (Too many references: cannot splice)
ETIMEDOUT
接続がタイムアウトしました (Connection timed out)
ECONNREFUSED
接続を拒否されました (Connection refused)
EHOSTDOWN
ホストはシステムダウンしています (Host is down)
EHOSTUNREACH
ホストへの経路がありません (No route to host)
EALREADY
すでに処理中です (Operation already in progress)
EINPROGRESS
現在処理中です (Operation now in progress)
ESTALE
無効な NFS ファイルハンドルです (Stale NFS file handle)
EUCLEAN
(Structure needs cleaning)
ENOTNAM
XENIX 名前付きファイルではありません (Not a XENIX named type file)
ENAVAIL
XENIX セマフォは利用できません (No XENIX semaphores available)
EISNAM
名前付きファイルです (Is a named type file)
EREMOTEIO
遠隔側の I/O エラーです (Remote I/O error)
EDQUOT
ディスククオータを超えました (Quota exceeded)
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.21 tempfile Up: 6. 汎用オペレーティングシステムサービス Next: 6.23 glob


6.23 glob -- Unix 形式のパス名のパターン展開

glob モジュールはUnix シェルで使われているルールに従って指定され たパターンにマッチするすべてのパス名を見つけ出します。 チルダ展開は使えませ んが、*、 ?と []で表される文字範囲には正しくマッチしま す。これはos.listdir() 関数と fnmatch.fnmatch()関数を 一緒に使って実行されていて、 実際に subshell を呼び出しているわけではありま せん。(チルダ展開とシェル変数展開を利用したければ、 os.path.expantion() とos.path.expandvars()を 使ってください。)

glob( pathname)
pathname (パスの指定を含んだ文字列でなければいけません。)にマッチする 空の可能性のあるパス名のリストを返します。

pathname は( /usr/src/Python-1.5/Makefileのように)絶対パスでも いいし、(../../Tools/*/*.gifのように)相対パスでもよくて、シェル形式の ワイルドカードを含んでいてもかまいません。

たとえば、次のファイルだけがあるディレクトリを考えてください: 1.gif、 2.txt、 and card.gif。glob()は次のような結果になり ます。 パスに接頭するどの部分が保たれているかに注意してください。

>>> import glob
>>> glob.glob('./[0-9].*')
['./1.gif', './2.txt']
>>> glob.glob('*.gif')
['1.gif', 'card.gif']
>>> glob.glob('?.gif')
['1.gif']

参考資料:

fnmatchモジュール:
シェル形式の(パスではない)ファイル名展開.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.22 errno Up: 6. 汎用オペレーティングシステムサービス Next: 6.24 fnmatch


6.24 fnmatch -- Unix ファイル名のパターンマッチ

このモジュールは Unix のシェル形式のワイルドカードへの対応を提供します が、(reモジュールでドキュメント化されている) 正規表現と同じではありません。シェル形式のワイルドカードで使われる特 別な文字は、

Pattern | Meaning
* | すべてにマッチします
? | 任意の一文字にマッチします
[seq] | seqにある任意の文字にマッチします
[!seq] | seqにない任意の文字にマッチします

ファイル名のセパレーター(Unixでは'/')はこのモジュールに固有なもので は ない ことに注意してください。パス名展開については、 globモジュールを参照してください (globはパス名の部分にマッチさせるのにfnmatch()を使っ ています)。同様に、ピリオドで始まるファイル名はこのモジュールに固有ではなく て、* と? のパターンでマッチします。

fnmatch( filename, pattern)
filenameの文字列がpatternの文字列にマッチするかテストして、真、偽のいずれか を返します。 もしもオペレーティングシステムが大文字、小文字を区別するなら、 比較を行う前に、すべて大文字、あるいは小文字に標準化されます。 オペレーティ ングシステムに標準かどうかは別にして、大文字、小文字を区別する比較が必要なと きには、かわりにfnmatchcase() を使ってください。

fnmatchcase( filename, pattern)
filename が pattern にマッチするかテストして、真、偽を返します。 比較は大文字、小文字を区別します。

filter( names, pattern)
pattern にマッチする names のリストの部分集合を返します。 [n for n in names if fnmatch(n, pattern)]と同じですが、もっと効率よく 実装しています。 バージョン2.2 以降で新規追加された 仕様です。

参考資料:

globモジュール:
Unix シェル形式のパス展開。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.23 glob Up: 6. 汎用オペレーティングシステムサービス Next: 6.25 shutil


6.25 shutil -- 高レベルなファイル操作

shutilモジュールはファイルやファイルの収集に関する多くの高レベ ルな操作方法を提供します。特にファイルのコピーや削除のための関数が用意さ れています。

注意: MacOSにおいてはリソースフォークや他のメタデータは取り扱う ことができません。

つまり、ファイルをコピーする際にこれらのリソースは失われたり、ファイルタ イプや作成者コードは正しく認識されないことを意味します。

copyfile( src, dst)
srcで指定されたファイル内容をdstで指定されたファイルへとコ ピーします。 もしdstが存在したら置き換えられ、そうでなければ新規作成されます。 キャラクタやブロックデバイス、パイプ等の特別なファイルはこの関数ではコ ピーできません。 srcとdstには文字列としてパス名を与えられます。

copyfileobj( fsrc, fdst[, length])
ファイル形式のオブジェクトfsrcの内容をfdstへコピーします。 整数値lengthはバッファサイズを表します。特に負のlengthは チャンク内のソースデータを繰り返し操作することなくコピーします。 つまり標準ではデータは制御不能なメモリ消費を避けるためにチャンク内 に読み込まれます。

copymode( src, dst)
srcから[vardstへパーミッションをコピーします。ファイル内容や所 有者、グループは影響を受けません。 srcとdstには文字列としてパス名を与えられます。

copystat( src, dst)
srcからdstへパーミッション最終アクセス時間、最終更新時間を コピーします。ファイル内容や所有者、グループは影響を受けません。 srcとdstには文字列としてパス名を与えられます。

copy( src, dst)
ファイルsrcをファイルまたはディレクトリdistへコピーします。 もし、dstがディレクトリであればファイル名はsrcと同じものが 指定されたディレクトリ内に作成（または上書き）されます。 パーミッションはコピーされます。 srcとdstには文字列としてパス名を与えられます。

copy2( src, dst)
copy()と類似していますが、最終アクセス時間や最終更新時間も同 様にコピーされます。これは Unix コマンドの cp -pと同様の働きをします。

copytree( src, dst[, symlinks])
srcを起点としてディレクトリツリー全体を再帰的にコピーします。 dstで指定されたディレクトリは既存のものではなく新規に作成されるも のでなくてはなりません。個々のファイルはcopy2()によってコピー されます。If symlinksが真であれば、元のディレクトリ内の シンボリックリンクはコピー先のディレクトリ内へシンボリックリンクとして コピーされます。偽が与えられたり省略された場合は元のディレクトリ内のリ ンクの対象となっているファイルがコピー先のディレクトリ内へコピーされま す。エラーが発生したときはエラー理由のリストを持った例外を引き起こします。

この関数のソースコードは道具としてよりも使用例として捉えられるべきでしょう。

バージョン2.3 以降で変更された 仕様: コピー中にエラーが発生した場合、メッセージを出力するのではなく 例外を引き起こすように変更。

rmtree( path[, ignore_errors[, onerror]])
ディレクトリツリー全体を削除します。もしignore_errorsが真であれば 削除に失敗したことによるエラーは無視され、偽が与えられたり省略された場 合はこれらのエラーはonerrorで与えられたハンドラを呼び出して処理 され、これが省略された場合は例外を引き起こします。

onerrorが与えられた場合、それは3つのパラメータfunction, pathおよびexcinfoを受け入れて呼び出し可能のものでなくてはな りません。最初のパラメータfunctionは例外を引き起こす関数で os.remove()やos.rmdir()等が用いられるでしょう。 二番目のパラメータはpathはfunctionへ渡らせるパス名です。 三番目のパラメータexcinfoはsys.exc_info()で返されるよ うな例外情報になるでしょう。onerrorが引き起こす例外はキャッチでき ません。

move( src, dst)
再帰的にファイルやディレクトリを別の場所へ移動します。

もし移動先が現在のファイルシステム上であれば単純に名前を変更します。 そうでない場合はコピーを行い、その後コピー元は削除されます。

バージョン2.3 以降で新規追加された 仕様です。

exception Error
この例外は複数ファイルの操作を行っているときに生じる例外をまとめたもの です。copytreeに対しては例外の引数は3つのタプル(srcname, dstname, exception)からなるリストです。

バージョン2.3 以降で新規追加された 仕様です。

  • 6.25.1 使用例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.24 fnmatch Up: 6. 汎用オペレーティングシステムサービス Next: 6.25.1 使用例


6.25.1 使用例

以下は前述のcopytree()関数のドキュメント文字列を省略した実装 例です。 本モジュールで提供される他の関数の使い方を示しています。

def copytree(src, dst, symlinks=0):
    names = os.listdir(src)
    os.mkdir(dst)
    for name in names:
        srcname = os.path.join(src, name)
        dstname = os.path.join(dst, name)
        try:
            if symlinks and os.path.islink(srcname):
                linkto = os.readlink(srcname)
                os.symlink(linkto, dstname)
            elif os.path.isdir(srcname):
                copytree(srcname, dstname, symlinks)
            else:
                copy2(srcname, dstname)
        except (IOError, os.error), why:
            print "Can't copy %s to %s: %s" % (`srcname`, `dstname`, str(why))
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.25 shutil Up: 6.25 shutil Next: 6.26 locale


6.26 locale -- 国際化サービス

locale モジュールは POSIX ロケールデータベース およびロケール関連機能へのアクセスを提供します。 POSIX ロケール機構を使うことで、プログラマはソフトウェアが 実行される各国における詳細を知らなくても、 アプリケーション上で特定の地域文化に関係する部分を扱うことが できます。

locale モジュールは、_locale を被うように実装されており、ANSI C ロケール実装を使っている _locale が利用可能なら、こちらを先に使うようになっています。

locale モジュールでは以下の例外と関数を定義しています:

exception Error
setlocale() が失敗したときに送出される例外です。

setlocale( category[, locale])

locale を指定する場合、文字列、 (language code, encoding)、からなるタプル、または None をとることができます。locale がタプルのの場合、 ロケール別名解決エンジンによって文字列に変換されます。 locale が与えられていて、かつ None でない場合、 setlocale() は category の設定を変更します。 変更することのできるカテゴリは以下に列記されており、値は ロケール設定の名前です。空の文字列を指定すると、ユーザの環境における 標準設定になります。 ロケールの変更に失敗した場合、Error が送出されます。 成功した場合、新たなロケール設定が返されます。

locale が省略されたり None の場合、category の現在の設定が返されます。

setlocale() はほとんどのシステムでスレッド安全では ありません。アプリケーションを書くとき、大抵は以下のコード

import locale
locale.setlocale(locale.LC_ALL, '')

から書き始めます。これは全てのカテゴリをユーザの環境における 標準設定 (大抵は環境変数 LANG で指定されています) に設定します。その後複数スレッドを使ってロケールを変更したり しない限り、問題は起こらないはずです。

バージョン2.0 以降で変更された 仕様: 引数 locale の値としてタプルをサポートしました。

localeconv( )
地域的な慣行のデータベースを辞書として返します。辞書は以下の文字列を キーとして持っています:

キー名 | カテゴリ | 意味
LC_NUMERIC | 'decimal_point' | 小数点を表す文字です。
  'grouping' | 'thousands_sep' が来るかもしれない場所を相対的に 表した数からなる配列です。配列が CHAR_MAX で終端されている 場合、それ以上の桁では桁数字のグループ化を行いません。配列が 0 で終端されている場合、最後に指定したグループが反復的に使われます。
  'thousands_sep' | 桁グループ間を区切るために使われる文字です。
LC_MONETARY | 'int_curr_symbol' | 国際通貨を表現する記号です。
  'currency_symbol' | 地域的な通貨を表現する記号です。
  'mon_decimal_point' | 金額表示の際に使われる小数点です。
  'mon_thousands_sep' | 金額表示の際に桁区切り記号です。
  'mon_grouping' | 'grouping' と同じで、金額表示の際に使われます。
  'positive_sign' | 正の値の金額表示に使われる記号です。
  'negative_sign' | 負の値の金額表示に使われる記号です。
  'frac_digits' | 金額を地域的な方法で表現する際の小数点以下の桁数です。
  'int_frac_digits' | 金額を国際的な方法で表現する際の小数点以下の桁数です。

'p_sign_posn' および 'n_sing_posn' の取り得る値は 以下の通りです。

値 | 説明
0 | 通貨記号および値は丸括弧で囲われます。
1 | 符号は値と通貨記号より前に来ます。
2 | 符号は値と通貨記号の後に続きます。
3 | 符号は値の直前に来ます。
4 | 符号は値の直後に来ます。
LC_MAX | このロケールでは特に指定しません。

nl_langinfo( option)

ロケール特有の情報を文字列として返します。この関数は全てのシステムで 利用可能なわけではなく、指定できる option もプラットフォーム 間で大きく異なります。引数として使えるのは、locale モジュールで利用 可能なシンボル定数を表す数字です。

getdefaultlocale( [envvars])
標準のロケール設定を取得しようと試み、結果をタプル (language code, encoding) の形式で 返します。 POSIXによると、setlocale(LC_ALL, '') を呼ばなかった プログラムは、移植可能な 'C' ロケール設定を使います。 setlocale(LC_ALL, '') を呼ぶことで、LANG 変数で 定義された標準のロケール設定を使うようになります。 Python では現在のロケール設定に干渉したくないので、上で述べた ような方法でその挙動をエミュレーションしています。

他のプラットフォームとの互換性を維持するために、環境変数 LANG だけでなく、引数 envvars で指定された環境変数のリスト も調べられます。envvars は標準では GNU gettext で使われて いるサーチパスになります; パスには必ず変数名 "LANG" が含まれて いるからです。GNU gettext サーチパスは 'LANGUAGE'、 'LC_ALL'、'LC_CTYPE'、および 'LANG' が 列挙した順番に含まれています。

'C' の場合を除き、言語コードは RFC 1766 に対応します。 language code および encoding が決定できなかった 場合、None になるかもしれません。

バージョン2.0 以降で新規追加された 仕様です。

getlocale( [category])
与えられたロケールカテゴリに対する現在の設定を、 language code、 encoding を含む配列で返します。 category として LC_ALL 以外の LC_* の 値の一つを指定できます。標準の設定は LC_CTYPE です。

'C' の場合を除き、言語コードは RFC 1766 に対応します。 language code および encoding が決定できなかった 場合、None になるかもしれません。

バージョン2.0 以降で新規追加された 仕様です。

getpreferredencoding( [do_setlocale])
テキストデータをエンコードする方法を、ユーザの設定に基づいて 返します。ユーザの設定は異なるシステム間では異なった方法で 表現され、システムによってはプログラミング的に得ることができない こともあるので、この関数が返すのはただの推測です。

システムによっては、ユーザの設定を取得するために setlocale を呼び出す必要があるため、この関数はスレッド安全 ではありません。setlocale を呼び出す必要がない、または 呼び出したくない場合、do_setlocale を False に 設定する必要があります。 バージョン2.3 以降で新規追加された 仕様です。

normalize( localename)
与えたロケール名を規格化したロケールコードを返します。返される ロケールコードは setlocale() で使うために書式化されて います。規格化が失敗した場合、もとの名前がそのまま返されます。

与えたエンコードがシステムにとって未知の場合、標準の設定では、 この関数は setlocale() と同様に、エンコーディングを ロケールコードにおける標準のエンコーディングに設定します。 バージョン2.0 以降で新規追加された 仕様です。

resetlocale( [category])
category のロケールを標準設定にします。

標準設定は getdefaultlocale() を呼ぶことで決定されます。 category は標準で LC_ALL になっています。 バージョン2.0 以降で新規追加された 仕様です。

strcoll( string1, string2)
現在の LC_COLLATE 設定に従って二つの文字列を比較します。 他の比較を行う関数と同じように、string1 が string2 に対して前に来るか、後に来るか、あるいは二つが等しいかによって、 それぞれ負の値、正の値、あるいは 0 を返します。

strxfrm( string)
文字列を組み込み関数 cmp() で 使える形式に変換し、かつロケールに則した結果を返します。 この関数は同じ文字列が何度も比較される場合、例えば文字列から なる配列を順序付けて並べる際に使うことができます。

format( format, val[, grouping])
数値 val を現在の LC_NUMERIC の設定に基づいて 書式化します。書式は % 演算子の慣行に従います。浮動小数点 数については、必要に応じて浮動小数点が変更されます。grouping が真なら、ロケールに配慮した桁数の区切りが行われます。

str( float)
浮動小数点数を str(float) と同じように書式化しますが、 ロケールに配慮した小数点が使われます。

atof( string)
文字列を LC_NUMERIC で設定された慣行に従って浮動小数点に変換 します。

atoi( string)
文字列を LC_NUMERIC で設定された慣行に従って整数に変換します。

LC_CTYPE
文字タイプ関連の関数のためのロケールカテゴリです。このカテゴリの 設定に従って、モジュール string における関数の振る舞い が変わります。

LC_COLLATE
文字列を並べ替えるためのロケールカテゴリです。locale モジュールの関数 strcoll() および strxfrm() が 影響を受けます。

LC_TIME
時刻を書式化するためのロケールカテゴリです。time.strftime() はこのカテゴリに設定されている慣行に従います。

LC_MONETARY
金額に関係する値を書式化するためのロケールカテゴリです。 設定可能なオプションは関数 localeconv() で得ることが できます。

LC_MESSAGES
メッセージ表示のためのロケールカテゴリです。現在 Python は アプリケーション毎にロケールに対応したメッセージを出力する 機能はサポートしていません。os.strerror() が 返すような、オペレーティングシステムによって表示される メッセージはこのカテゴリによって影響を受けます。

LC_NUMERIC
数字を書式化するためのロケールカテゴリです。関数 format()、
atoi()、 atof() および locale モジュール
の str() が影響を受けます。他の数値書式化操作は影響を
受けません。

LC_ALL
全てのロケール設定を総合したものです。ロケールを変更する際にこの フラグが使われた場合、そのロケールにおける全てのカテゴリを設定 しようと試みます。一つでも失敗したカテゴリがあった場合、全ての カテゴリにおいて設定変更を行いません。このフラグを使ってロケールを 取得した場合、全てのカテゴリにおける設定を示す文字列が返されます。 この文字列は、後に設定を元に戻すために使うことができます。

CHAR_MAX
localeconv() の返す特別な値のためのシンボル定数です。

関数 nl_langinfo は以下のキーのうち一つを受理します。 ほとんどの記述は GNU C ライブラリ中の対応する説明から引用されています。

CODESET
選択されたロケールで用いられている文字エンコーディングの名前を 文字列で返します。

D_T_FMT
時刻および日付をロケール特有の方法で表現するために、 strftime(3) の 書式化文字列として用いることのできる文字列を返します。

D_FMT
日付をロケール特有の方法で表現するために、 strftime(3) の 書式化文字列として用いることのできる文字列を返します。

T_FMT
時刻をロケール特有の方法で表現するために、 strftime(3) の 書式化文字列として用いることのできる文字列を返します。

T_FMT_AMPM
時刻を 午前／午後の書式で表現するために、 strftime(3) の 書式化文字列として用いることのできる文字列を返します。 返される値は

DAY_1 ... DAY_7
1 週間中の n 番目の曜日名を返します。警告: ロケール US における、 DAY_1 を日曜日とする慣行に従っています。国際的な (ISO 8601) 月曜日を週の初めとする慣行ではありません。

ABDAY_1 ... ABDAY_7
1 週間中の n 番目の曜日名を略式表記で返します。

MON_1 ... MON_12
n 番目の月の名前を返します。

ABMON_1 ... ABMON_12
n 番目の月の名前を略式表記で返します。

RADIXCHAR
基数点 (小数点ドット、あるいは小数点コンマ、等) を返します。

THOUSEP
1000 単位桁区切り (3 桁ごとのグループ化) の区切り文字を返します。

YESEXPR
肯定／否定で答える質問に対する肯定回答を正規表現関数で 認識するために利用できる正規表現を返します。 警告: 表現は C ライブラリの regex() 関数 に合ったものでなければならず、これは re で 使われている構文とは異なるかもしれません。

NOEXPR
肯定／否定で答える質問に対する否定回答を正規表現関数で 認識するために利用できる正規表現を返します。

CRNCYSTR
通貨シンボルを返します。シンボルを値の前に表示させる場合には "-" 、値の後ろに表示させる場合には "+" 、シンボルを基数点と 置き換える場合には "." を前につけます。

ERA
現在のロケールで使われている年代を表現する値を返します。

ほとんどのロケールではこの値を定義していません。この値を設定している ロケールの例は日本です。日本では、日付の伝統的な表示法に、時の天皇 に対応する元号名を含めます。

通常この値を直接指定する必要はありません。E を書式化文字列に 指定することで、関数 strftime がこの情報を使うようになります。 返される文字列の様式は決められていないので、異なるシステム間で様式に 関する同じ知識が使えると期待してはいけません。

ERA_YEAR
返される値はロケールでの現年代の年値です。

ERA_D_T_FMT
返される値は strftime で日付および時間をロケール固有の 年代に基づいた方法で表現するための書式化文字列として使うことができます。

ERA_D_FMT
返される値は strftime で日付をロケール固有の 年代に基づいた方法で表現するための書式化文字列として使うことができます。

ALT_DIGITS
返される値は 0 から 99 までの 100 個の値の表現です。

例:

>>> import locale
>>> loc = locale.setlocale(locale.LC_ALL) # get current locale
>>> locale.setlocale(locale.LC_ALL, 'de_DE') # use German locale; name might vary with platform
>>> locale.strcoll('f\xe4n', 'foo') # compare a string containing an umlaut
>>> locale.setlocale(locale.LC_ALL, '') # use user's preferred locale
>>> locale.setlocale(locale.LC_ALL, 'C') # use default (C) locale
>>> locale.setlocale(locale.LC_ALL, loc) # restore saved locale

  • 6.26.1 ロケールの背景、詳細、ヒント、助言および補足説明
  • 6.26.2 Python 拡張の作者と、Python を埋め込むようなプログラムに関して
  • 6.26.3 メッセージカタログへのアクセス
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.25.1 使用例 Up: 6. 汎用オペレーティングシステムサービス Next: 6.26.1 ロケールの背景、詳細、ヒント、助言および補足説明


6.26.1 ロケールの背景、詳細、ヒント、助言および補足説明

C 標準では、ロケールはプログラム全体にわたる特性であり、その変更は 高価な処理であるとしています。加えて、頻繁にロケールを変更する ようなひどい実装はコアダンプを引き起こすこともあります。 このことがロケールを正しく利用する上で苦痛となっています。

そもそも、プログラムが起動した際、ロケールはユーザの希望するロケール にかかわらず "C" です。プログラムは setlocale(LC_ALL, '') を呼び出して、明示的にユーザの希望する ロケール設定を行わなければなりません。

setlocale() をライブラリルーチン内で呼ぶことは、 それがプログラム全体に及ぼす副作用の面から、一般的によくない考えです。 ロケールを保存したり復帰したりするのもよくありません: 高価な処理 であり、ロケールの設定が復帰する以前に起動してしまった他のスレッド に悪影響を及ぼすからです。

もし、汎用を目的としたモジュールを作っていて、ロケールによって 影響をうけるような操作 (例えば string.lower() や time.strftime() の書式の一部) のロケール独立の バージョンが必要ということになれば、標準ライブラリルーチンを 使わずに何とかしなければなりません。よりましな方法は、ロケール設定が 正しく利用できているか確かめることです。最後の手段は、 あなたのモジュールが "C" ロケール以外の設定には互換性がない とドキュメントに書くことです。

stringモジュールの大小文字の変換を 行う関数はロケール設定によって影響を受けます。setlocale() 関数を呼んで LC_CTYPE 設定を変更した場合、変数 string.lowercase、string.uppercase および string.letters は計算しなおされます。 例えば from string import letters のように、 `from ... import ...' を使ってこれらの変数を 使っている場合には、それ以降の setlocale() の影響を 受けないので注意してください。

ロケールに従って数値操作を行うための唯一の方法はこのモジュールで 特別に定義されている関数: atof()、 atoi()、 format()、 str() を使うことです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.26 locale Up: 6.26 locale Next: 6.26.2 Python 拡張の作者と、Python を埋め込むようなプログラムに関して


6.26.2 Python 拡張の作者と、Python を埋め込むようなプログラムに関して

拡張モジュールは、現在のロケールを調べる以外は、決して setlocale() を呼び出してはなりません。 しかし、返される値もロケールの復帰のために使えるだけなので、 さほど便利とはいえません (例外はおそらくロケールが "C" か どうか調べることでしょう)。

Python があるアプリケーション内に埋め込まれており、アプリケーションが Python を初期化する前にロケールを設定した場合は一般的に問題はありません。 このとき Python は設定されているロケールを使います。ただし、 LC_NUMERIC ロケールは常に "C" に設定されます。

locale モジュールの関数 setlocale() は、LC_NUMERIC ロケール設定が操作できるような印象を Python プログラマに与えますが、C のレベルではこれは当てはまりません。 C コードでは、常に LC_NUMERIC ロケール設定は "C" になります。これは、小数点文字がピリオド以外の別の文字に変更 された場合にうまく動作しなくなるものがあまりにも多い (例えば Python パーザはうまく動作しません) からです。 補足説明: Python のグローバルインタプリタをロックしないまま 動作するスレッド間では、数値ロケール設定が一致しなくなることが あるかもしれません。 このため、LC_NUMERIC ロケールの設定を実装するための 可搬性のある唯一の方法は、数値ロケールをユーザの希望するロケールに 設定して、直接関係のある値を展開し、最後に "C" 数値ロケールを復帰する ことです。

ロケールを変更するために Python コードで locale モジュール を使った場合、Python を埋め込んでいるアプリケーションにも影響を 及ぼします。Python を埋め込んでいるアプリケーションに影響が及ぶ ことを望まない場合、config.c ファイル内の組み込みモジュールの テーブルから _locale 拡張モジュール (ここで全てを行っています) を削除し、共有ライブラリから _locate モジュールにアクセス できないようにしてください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.26.1 ロケールの背景、詳細、ヒント、助言および補足説明 Up: 6.26 locale Next: 6.26.3 メッセージカタログへのアクセス


6.26.3 メッセージカタログへのアクセス

C ライブラリの gettext インタフェースが提供されているシステムでは、 locake モジュールでそのインタフェースを公開しています。 このインタフェースは関数 gettext()、 dgettext()、 dcgettext()、textdomain()、および bindtextdomain() からなります。 これらは gettext モジュールの同名の関数に似ていますが、 メッセージカタログとして C ライブラリのバイナリフォーマットを使い、 メッセージカタログを探すために C ライブラリのサーチアルゴリズムを 使います。

Python アプリケーションでは、通常これらの関数を呼び出す必要は ないはずで、代わりに gettext を呼ぶべきです。 例外として知られているのは、内部で gettext() または cdgettext() を呼び出すような C ライブラリにリンク するアプリケーションです。こうしたアプリケーションでは、 ライブラリが正しいメッセージカタログを探せるようにテキスト ドメイン名を指定する必要があります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.26.2 Python 拡張の作者と、Python を埋め込むようなプログラムに関して Up: 6.26 locale Next: 6.27 gettext


6.27 gettext -- 多言語対応に関する国際化サービス

gettext モジュールは、 Python によるモジュールや アプリケーションの国際化 (I18N, I-nternationalizatio-N) および地域化 (L10N, L-ocalizatio-N) サービスを提供します。 このモジュールは GNU gettext メッセージカタログへの API と、 より高レベルで Python ファイルに適しているクラスに基づいた API の 両方をサポートしてます。以下で述べるインタフェースを使うことで、 モジュールやアプリケーションのメッセージをある自然言語で記述しておき、 翻訳されたメッセージのカタログを与えて他の異なる自然言語の環境下で動作 させることができます。

ここでは Python のモジュールやアプリケーションを地域化する ためのいくつかのヒントも提供しています。

  • 6.27.1 GNU gettext API
  • 6.27.2 クラスに基づいた API
    • 6.27.2.1 NullTranslations クラス
    • 6.27.2.2 GNUTranslations クラス
    • 6.27.2.3 Solaris メッセージカタログ機構のサポート
    • 6.27.2.4 Catalog コンストラクタ
  • 6.27.3 プログラムやモジュールを国際化する
    • 6.27.3.1 モジュールを地域化する
    • 6.27.3.2 アプリケーションを地域化する
    • 6.27.3.3 動作中 (on the fly) に言語を切り替える
    • 6.27.3.4 翻訳処理の遅延解決
  • 6.27.4 謝辞
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.26.3 メッセージカタログへのアクセス Up: 6. 汎用オペレーティングシステムサービス Next: 6.27.1 GNU gettext API


6.27.1 GNU gettext API

gettext モジュールでは、以下の GNU gettext API に 非常に良く似た API を提供しています。この API を使う場合、 メッセージ翻訳の影響はアプリケーション全体に及ぼすことになります。 アプリケーションが単一の言語しか扱わず、各言語に依存する部分を ユーザのロケール情報によって選ぶのなら、ほとんどの場合この方法で やりたいことを実現できます。Python モジュールを地域化していたり、 アプリケーションの実行中に言語を切り替えたい場合、おそらくクラス に基づいた API を使いたくなるでしょう。

bindtextdomain( domain[, localedir])
domain をロケール辞書 localedir に結び付け (bind) ます。 具体的には、 gettext は与えられたドメインに対する バイナリ形式の .mo ファイルを、(Unixでは) localedir/language/LC_MESSAGES/domain.mo から探します。ここで languages はそれぞれ環境変数 LANGUAGE、LC_ALL 、LC_MESSAGES、 および LANG の中から検索されます。

localedir が省略されるか None の場合、現在 domain に結び付けられている内容が返されます。6.2

textdomain( [domain])
現在のグローバルドメインを調べたり変更したりします。 domain が None の場合、現在のグローバルドメインが返され ます。それ以外の場合にはグローバルドメインは domain に設定され、 設定されたグローバルドメインを返します。

gettext( message)
現在のグローバルドメイン、言語、およびロケール辞書に基づいて、 message の特定地域向けの翻訳を返します。通常、 ローカルな名前空間ではこの関数に _ という別名をつけます (下の例を参照してください)。

dgettext( domain, message)
gettext() と同様ですが、指定された domain から メッセージを探します。

ngettext( singular, plural, n)

gettext() と同様ですが、複数形の場合を考慮しています。 翻訳文字列が見つかった場合、n の様式を適用し、 その結果得られたメッセージを返します (言語によっては二つ以上の 複数形があります)。 翻訳文字列が見つからなかった場合、 n が 1 なら singular を返します; そうでない場合 plural を返します。

複数形の様式はカタログのヘッダから取り出されます。様式は C または Python の式で、自由な変数 n を持ちます; 式の評価値はカタログ中の 複数形のインデクスとなります。.po ファイルで用いられる 詳細な文法と、様々な言語における様式については、GNU gettext ドキュメントを参照してください。

バージョン2.3 以降で新規追加された 仕様です。

dngettext( domain, singular, plural, n)
ngettext() と同様ですが、指定された domain から メッセージを探します。

バージョン2.3 以降で新規追加された 仕様です。

GNU gettext では dcgettext() も定義していますが、 このメソッドはあまり有用ではないと思われるので、現在のところ 実装されていません。

以下にこの API の典型的な使用法を示します:

import gettext
gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
gettext.textdomain('myapplication')
_ = gettext.gettext
# ...
print _('This is a translatable string.')

... に結び付けられている内容が返されます。6.2
標準でロケールが収められているディレクトリはシステム依存です; 例えば、RedHat Linux では /usr/share/locale ですが、 Solaris では /usr/lib/locale です。 gettext モジュールはこうしたシステム依存の標準設定をサポートしません; その代わりに sys.prefix/share/locale を標準の 設定とします。この理由から、常にアプリケーションの開始時に 絶対パスで明示的に指定して bindtextdomain() を呼び出す のが最良のやり方ということになります。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.27 gettext Up: 6.27 gettext Next: 6.27.2 クラスに基づいた API


6.27.2 クラスに基づいた API

クラス形式の gettext モジュールのAPI は GNU gettext API よりも高い柔軟性と利便性を持っています。 Python のアプリケーションやモジュールを地域化するにはこちらを使う 方を勧めます。gettext では、GNU .mo 形式のファイルを 解釈し、標準の 8 ビット文字列または Unicode 文字列形式でメッセージ を返す ``翻訳'' クラスを定義しています。 翻訳オブジェクトのインスタンスも組み込み名前空間に関数 _() として組み入れる (install) ことができます。

find( domain[, localedir[, languages[, all]]])
この関数は標準的な .mo ファイル検索アルゴリズムを実装 しています。textdomain() と同じく、domain を引数に とります。オプションの localedir は bindtextdomain() と同じです。またオプションの languages は文字列を列挙したリスト で、各文字列は言語コードを表します。

localedir が与えられていない場合、標準のシステムロケール ディレクトリが使われます。6.3

languages が与えられなかった場合、以下の環境変数: LANGUAGE、LC_ALL、 LC_MESSAGES、および LANG が検索されます。空でない値を返した最初の候補が languages 変数として使われます。 この環境変数は言語名をコロンで分かち書きしたリストを含んで いなければなりません。find() はこの文字列をコロンで 分割し、言語コードの候補リストを生成します。

find() は次に言語コードを展開および正規化し、リストの 各要素について、以下のパス構成:

localedir/language/LC_MESSAGES/domain.mo

からなる実在するファイルの探索を反復的に行います。find() は上記のような実在するファイルで最初に見つかったものを返します。 該当するファイルが見つからなかった場合、None が返されます。 all が与えられていれば、全ファイル名のリストが言語リストまたは 環境変数で指定されている順番に並べられたものを返します。

translation( domain[, localedir[, languages[, class_,[fallback]]]])

Translations インスタンスを domain、localedir、および languages に基づいて 生成して返します。 domain、localedir、および languages はまず 関連付けられている .mo ファイルパスのリストを取得する ためにfind() に渡されます。同じ .mo ファイル名を 持つインスタンスはキャッシュされます。実際にインスタンス化される クラスは class_ が与えられていればそのクラスが、そうでない 時には GNUTranslations です。クラスのコンストラクタは 単一の引数としてファイルオブジェクトを取らなくてはなりません。

複数のファイルが発見された場合、後で見つかったファイルは前に見つかった ファイルの代替でと見なされ、後で見つかった方が利用されます。 代替の設定を可能にするには、copy.copy を使ってキャッシュから 翻訳オブジェクトを複製します; こうすることで、実際のインスタンスデータは キャッシュのものと共有されます。

.mo ファイルが見つからなかった場合、fallback が偽 (標準の設定です) ならこの関数は IOError を送出し、 fallback が真なら NullTranslations インスタンスが 返されます。

install( domain[, localedir[, unicode]])
関数 translation() に渡した domain および localedir に基づいて、Python の組み込み名前空間に関数 _ を組み入れます。 unicode フラグは translation() の返した翻訳オブジェクト の install メソッドに渡されます。

以下に示すように、通常はアプリケーション中の文字列を関数 _() の呼び出しで包み込んで翻訳対象候補であることを示します:

print _('This string will be translated.')

利便性を高めるためには、_() 関数を Python の組み込み 名前空間に組み入れる必要があります。こうすることで、アプリケーション内の 全てのモジュールからアクセスできるようになります。

... ディレクトリが使われます。6.3
上の bindtextdomain() に関する脚注を参照してください。

  • 6.27.2.1 NullTranslations クラス
  • 6.27.2.2 GNUTranslations クラス
  • 6.27.2.3 Solaris メッセージカタログ機構のサポート
  • 6.27.2.4 Catalog コンストラクタ
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.27.1 GNU gettext API Up: 6.27 gettext Next: 6.27.2.1 NullTranslations クラス


6.27.3 プログラムやモジュールを国際化する

国際化 (I18N, I-nternationalizatio-N) とは、プログラムを複数の言語に 対応させる操作を指します。地域化 (L10N, L-ocalizatio-N) とは、すでに 国際化されているプログラムを特定地域の言語や文化的な事情に対応させる ことを指します。Python プログラムに多言語メッセージ機能を追加するには、 以下の手順を踏む必要があります:

  1. プログラムやモジュールで翻訳対象とする文字列に特殊なマークを つけて準備します
  2. マークづけをしたファイルに一連のツールを走らせ、生のメッセージ カタログを生成します
  3. 特定の言語へのメッセージカタログの翻訳を作成します
  4. メッセージ文字列を適切に変換するために gettext モジュールを使います

ソースコードを I18N 化する準備として、ファイル内の全ての文字列 を探す必要があります。翻訳を行う必要のある文字列はどれも _('...') -- すなわち関数 _() の呼び出しで 包むことでマーク付けしなくてはなりません。例えば以下のようにします:

filename = 'mylog.txt'
message = _('writing a log message')
fp = open(filename, 'w')
fp.write(message)
fp.close()

この例では、文字列 'writing a log message' が翻訳対象候補として マーク付けされており、文字列 'mylog.txt' および 'w' は されていません。

Python の配布物には、ソースコードに準備作業を行った後で メッセージカタログの生成を助ける 2 つのツールが付属します。 これらはバイナリ配布の場合には付属していたりしなかったりしますが、 ソースコード配布には入っており、Tools/i18n ディレクトリ にあります。

pygettext プログラム 6.4 は全ての Python ソースコードを走査し、予め翻訳対象としてマーク した文字列を探し出します。このツールは GNU gettext プログラムと同様ですが、Python ソースコードの機微について 熟知している反面、C 言語や C++言語のソースコードについては 全く知りません。(C 言語による拡張モジュールのように) C 言語の コードも翻訳対象にしたいのでない限り、 GNU gettext は必要ありません。

pygettext は、テキスト形式 Uniforum スタイルによる人間が 判読可能なメッセージカタログ .pot ファイル群を生成します。 このファイル群はソースコード中でマークされた全ての文字列と、 それに対応する翻訳文字列のためのプレースホルダを含むファイル で構成されています。 pygettext はコマンドライン形式のスクリプトで、 xgettext と同様のコマンドラインインタフェースをサポート します; 使用法についての詳細を見るには:

pygettext.py --help

を起動してください。

これら .pot ファイルのコピーは次に、サポート対象の 各自然言語について、言語ごとのバージョンを作成する個々の人間の 翻訳者に頒布されます。翻訳者たちはプレースホルダ部分を埋めて 言語ごとのバージョンをつくり、.po ファイルとして 返します。(Tools/i18n ディレクトリ内の) msgfmt.py 6.5 プログラムを使い、翻訳者から返された .po ファイルから 機械可読な .mo バイナリカタログファイルを生成します。 .mo ファイルは、 gettext モジュールが実行時に 実際の翻訳処理を行うために使われます。

gettext モジュールをソースコード中でどのように使うかは アプリケーション全体を国際化するのか、それとも単一のモジュールを 国際化するのかによります。

... プログラム6.4
同様の作業を行う xpot と呼ばれるプログラムを François Pinard が書いています。このプログラムは 彼の po-utils パッケージの一部で、 http://www.iro.umontreal.ca/contrib/po-utils/HTML/ で入手できます。
...msgfmt.py6.5
msgfmt.py は GNU msgfmt とバイナリ互換ですが、 より単純で、Python だけを使った実装がされています。 このプログラムと pygettext.py があれば、通常 Python プログラムを国際化するために GNU gettext パッケージを インストールする必要はありません。

  • 6.27.3.1 モジュールを地域化する
  • 6.27.3.2 アプリケーションを地域化する
  • 6.27.3.3 動作中 (on the fly) に言語を切り替える
  • 6.27.3.4 翻訳処理の遅延解決
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.27.2.4 Catalog コンストラクタ Up: 6.27 gettext Next: 6.27.3.1 モジュールを地域化する


6.27.4 謝辞

以下の人々が、このモジュールのコード、フィードバック、設計に関する 助言、過去の実装、そして有益な経験談による貢献をしてくれました:

  • Peter Funk
  • James Henstridge
  • Juan David Ibáñez Palomar
  • Marc-André Lemburg
  • Martin von Löwis
  • François Pinard
  • Barry Warsaw
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.27.3.4 翻訳処理の遅延解決 Up: 6.27 gettext Next: 6.28 logging


6.28 logging -- Python用ロギング機能

バージョン2.3 以降で新規追加された 仕様です。 このモジュールでは、アプリケーションのための柔軟なエラーログ記録 (logiing) システムを実装するための関数やクラスを定義しています。

ログ記録は Logger クラスのインスタンス (以降 ロガー :logger) におけるメソッドを呼び出すことで行われます。各インスタンスは 名前をもち、ドット (ピリオド) を区切り文字として表記することで、 概念的には名前空間中の階層構造に配置されることになります。 例えば、"scan" と名づけられたロガーは "scan.text"、"scan.html"、 および "scan.pdf" ロガーの親ロガーとなります。ロガー名には何をつけてもよく、 ログに記録されるメッセージの生成元となるアプリケーション中の特定の 領域を示すことになります。

ログ記録されたメッセージにはまた、重要度レベル (level of importance) が関連付けられています。デフォルトのレベルとして提供されているものは DEBUG、INFO、WARNING、 ERROR および CRITICAL です。簡便性のために、 Logger の適切なメソッド群を呼ぶことで、ログに記録されたメッセージの 重要性を指定することができます。それらのメソッドとは、デフォルトの レベルを反映する形で、debug()、 info()、 warning()、 error() および critical() となっています。 これらのレベルを指定するにあたって制限はありません: Logger の より汎用的なメソッドで、明示的なレベル指定のための引数を持つ log() を使って自分自身でレベルを定義したり使用したりできます。

レベルもロガーに関連付けることができ、デベロッパが設定することも、 保存されたログ記録設定を読み込む際に設定することもできます。 ロガーに対してログ記録メソッドが呼び出されると、ロガーは自らの レベルとメソッド呼び出しに関連付けられたレベルを比較します。 ロガーのレベルがメソッド呼び出しのレベルよりも高い場合、実際の ログメッセージは生成されません。これはログ出力の冗長性を制御 するための基本的なメカニズムです。

ログ記録されるメッセージは LogRecord クラスのインスタンスとして コード化されます。ロガーがあるイベントを実際にログ出力すると決定した 場合、ログメッセージから LogRecord インスタンスが生成されます。

ログ記録されるメッセージは、ハンドラ (handers) を通して、 処理機構 (dispatch mechanism) にかけられます。ハンドラは Handler クラスのサブクラスのインスタンスで、ログ記録された (LogRecord 形式の) メッセージが、そのメッセージの伝達対象となる相手 (エンドユーザ、サポートデスクのスタッフ、システム管理者、開発者) に行き着くようにする役割を持ちます。ハンドラには特定の行き先に方向付け られた LogRecord インスタンスが渡されます。各ロガーは ゼロ個、単一またはそれ以上のハンドラを (Logger の addHandler メソッド) で関連付けることができます。 ロガーに直接関連付けられたハンドラに加えて、 ロガーの上位にあるロガー全てに関連付けられたハンドラ がメッセージを処理する際に呼び出されます。

ロガーと同様に、ハンドラは関連付けられたレベルを持つことができます。 ハンドラのレベルはロガーのレベルと同じ方法で、フィルタとして働きます。 ハンドラがあるイベントを実際に処理すると決定した場合、 emit() メソッドが使われ、メッセージを発送先に送信します。ほとんどの ユーザ定義の Hnadler のサブクラスで、この emit() をオーバライドする必要があるでしょう。

基底クラスとなる Handler クラスに加えて、多くの有用なサブクラスが 提供されています:

  1. StreamHandler のインスタンスはストリーム (ファイル様 オブジェクト) にエラーメッセージを送信します。

  2. FileHandler のインスタンスはディスク上のファイルに エラーメッセージを送信します。 files.

  3. RotatingFileHandler のインスタンスは最大ログファイルの サイズ指定とログファイルの交替機能をサポートしながら、ディスク上のファイルに エラーメッセージを送信します。

  4. SocketHandler のインスタンスは TCP/IP ソケットにエラーメッセージを送信します。 TCP/IP sockets.

  5. DatagramHandler のインスタンスは UDP ソケットにエラーメッセージを送信します。

  6. SMTPHandler のインスタンスは指定された電子メールアドレスにエラーメッセージを送信します。

  7. SysLogHandler のインスタンスは遠隔を含むマシン上の syslog デーモンにエラーメッセージを送信します。

  8. NTEventLogHandler のインスタンスは Windows NT/2000/XP イベントログにエラーメッセージを送信します。

  9. MemoryHandler のインスタンスはメモリ上のバッファにエラーメッセージを送信し、指定された条件でフラッシュされるようにします。

  10. HTTPHandler のインスタンスは "GET" か "POST"セマンティクスを使って HTTP サーバにエラーメッセージを送信します。

StreamHandler および FileHandler クラスは、中核となる ログ化機構パッケージ内で定義されています。他のハンドラはサブモジュール、 logging.handlers で定義されています。 (サブモジュールには もうひとつ logging.config があり、これは環境設定機能の ためのものです。)

ログ記録されたメッセージは Formatter クラスのインスタンスを 介し、表示用に書式かされます。これらのインスタンスは % 演算子と辞書を 使うのに適した書式化文字列で初期化されます。

複数のメッセージの初期化をバッチ処理するために、 BufferingFormatter のインスタンスを使うことができます。 書式化文字列 (バッチ処理で各メッセージに適用されます) に加えて、 ヘッダ (header) およびトレイラ (trailer) 書式化文字列が用意されて います。

ロガーレベル、ハンドラレベルの両方または片方に基づいたフィルタリング が十分でない場合、Logger および Handler インスタンスに Filter のインスタンスを (addFilter() メソッドを介して) 追加することができます。メッセージの処理を進める前に、ロガーとハンドラは ともに、全てのフィルタでメッセージの処理が許可されているか調べます。 いずれかのフィルタが偽となる値を返した場合、メッセージの処理は 行われません。

基本的な Filter 機能では、指定されたロガー名でフィルタを 行えるようになっています。この機能が利用された場合、名前付けされた ロガーとその下位にあるロガーに送られたメッセージがフィルタを通過 できるようになり、その他のメッセージは捨てられます。

上で述べたクラスに加えて、いくつかのモジュールレベルの関数が存在します。

getLogger( [name])
指定された名前のロガーを返します。名前が指定されていない場合、 ロガー階層のルート (root) にあるロガーを返します。

与えられた名前に対して、この関数はどの呼び出しでも同じロガーインスタンス を返します。従って、ロガーインスタンスをアプリケーションの各部 でやりとりする必要はなくなります。

debug( msg[, *args[, **kwargs]])
L レベル DEBUG のメッセージをルートロガーで記録します。 msg はメッセージの書式化文字列で、args は msg に 取り込むための引数です。キーワード文字列 kwargs からは exc_info のみが調べられ、この値の評価値が偽でない場合、 (sys.exc_info から得た) 例外情報がログメッセージに追加されます。

info( msg[, *args[, **kwargs]])
レベル INFO のメッセージをルートロガーで記録します。 引数は debug() と同じように解釈されます。

warning( msg[, *args[, **kwargs]])
レベル WARNING のメッセージをルートロガーで記録します。 引数は debug() と同じように解釈されます。

error( msg[, *args[, **kwargs]])
レベル ERROR のメッセージをルートロガーで記録します。 引数は debug() と同じように解釈されます。

critical( msg[, *args[, **kwargs]])
レベル CRITICAL のメッセージをルートロガーで記録します。 引数は debug() と同じように解釈されます。

exception( msg[, *args])
レベル ERROR のメッセージをルートロガーで記録します。 引数は debug() と同じように解釈されます。 例外情報はログメッセージに追加されます。このメソッドは 例外ハンドラからのみ呼び出されます。

disable( lvl)
全てのロガーに対して、ロガー自体のレベルに優先するような上書きレベル lvl を与えます。アプリケーション全体にわたって一時的にログ出力の 頻度を押し下げる必要が生じた場合にはこの関数が有効です。

addLevelName( lvl, levelName)
内部辞書内でレベル lvl をテキスト levelName に関連付け ます。これは例えば Formatter でメッセージを書式化する 際のように、数字のレベルをテキスト表現に対応付ける際に用いられます。 この関数は自作のレベルを定義するために使うこともできます。 使われるレベル対する唯一の制限は、レベルは正の整数でなくては ならず、メッセージの深刻さが上がるに従ってレベルの数も上がらなくては ならないということです。

getLevelName( lvl)
ログ記録レベル lvl のテキスト表現を返します。レベルが定義 済みのレベル CRITICAL、ERROR、 WARNING、 INFO、あるいは DEBUG のいずれかである場合、対応する文字列が返されます。 addLevelName() を使ってレベルに名前を関連づけていた 場合、lvl に関連付けられていた名前が返されます。そうでない 場合、文字列 "Level %s" % lvl が返されます。

makeLogRecord( attrdict)
属性が attrdict で定義された、新たな LogRecord インスタンスを生成して返します。この関数は pickle 化された LogRecord 属性の辞書を作成し、ソケットを介して送信し、受信端で LogRecord インスタンスとして再構成する際に便利です。

makeLogRecord( attrdict)
attrdict で属性を定義した、新しい LogRecord インスタンスを 返します。この関数は、逆 pickle 化された LogRecord 属性辞書を socket 越しに受け取り、受信端で LogRecord インスタンスに再構築す る場合に有用です。

basicConfig( )
デフォルトのフォーマッタ (formatter) を持つ StreamHandler を生成してルートロガーに追加し、ログ記録システムの基本的な環境設定を 行います。 関数 debug()、info()、warning()、 error()、および critical() は、ルートロガーに ハンドラが定義されていない場合に自動的に basicConfig() を呼び出します。

shutdown( )
ログ記録システムに対して、バッファのフラッシュを行い、全てのハンドラを 閉じることで順次シャットダウンを行うように告知します。

setLoggerClass( klass)
ログ記録システムに対して、ロガーをインスタンス化する際にクラス klass を使うように指示します。指定するクラスは引数として 名前だけをとるようなメソッド __init__() を定義して いなければならず、__init__() では Logger.__init__() を呼び出さなければなりません。典型的な利用法として、この関数は自作の ロガーを必要とするようなアプリケーションにおいて、他のロガーが インスタンス化される前にインスタンス化されます。

参考資料:

PEP 282, A Logging System
本機能を Python 標準ライブラリに含めるよう記述している提案書。

  • 6.28.1 Logger オブジェクト
  • 6.28.2 Handler オブジェクト
    • 6.28.2.1 StreamHandler
    • 6.28.2.2 FileHandler
    • 6.28.2.3 RotatingFileHandler
    • 6.28.2.4 SocketHandler
    • 6.28.2.5 DatagramHandler
    • 6.28.2.6 SysLogHandler
    • 6.28.2.7 NTEventLogHandler
    • 6.28.2.8 SMTPHandler
    • 6.28.2.9 MemoryHandler
    • 6.28.2.10 HTTPHandler
  • 6.28.3 Formatter オブジェクト
  • 6.28.4 Filter オブジェクト
  • 6.28.5 LogRecord オブジェクト
  • 6.28.6 スレッド安全性
  • 6.28.7 環境設定
    • 6.28.7.1 環境設定のための関数
    • 6.28.7.2 環境設定ファイルの書式
  • 6.28.8 Using the logging package
    • 6.28.8.1 Basic example - log to a file
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.27.4 謝辞 Up: 6. 汎用オペレーティングシステムサービス Next: 6.28.1 Logger オブジェクト


6.28.1 Logger オブジェクト

ロガーは以下の属性とメソッドを持ちます。ロガーを直接インスタンス化 することはできず、常にモジュール関数 logging.getLogger(name) を介してインスタンス化するので注意してください。

propagate
この値の評価結果が偽になる場合、ログ記録しようとするメッセージは このロガーに渡されず、また子ロガーから上位の (親の) ロガーに 渡されません。コンストラクタはこの属性を 1 に設定します。

setLevel( lvl)
このロガーの閾値を lvl に設定します。ログ記録しようとする メッセージで、lvl よりも深刻でないものは無視されます。 ロガーが生成された際、レベルは NOTSET (全てのメッセージ がルートロガーで処理されるか、非ルートロガーの場合には親ロガーに 処理を代行させる) に設定されます。

isEnabledFor( lvl)
深刻さが lvl のメッセージが、このロガーで処理されることに なっているかどうかを示します。このメソッドはまず、 logging.disable(lvl) で設定されるモジュールレベル の深刻さレベルを調べ、次にロガーの実効レベルを getEffectiveLevel() で調べます。

getEffectiveLevel( )
このロガーの実効レベルを示します。NOTSET 以外の値が setLevel() で設定されていた場合、その値が返されます。 そうでない場合、NOTSET 以外の値が見つかるまでロガーの 階層をルートロガーの方向に追跡します。見つかった場合、その値が 返されます。

debug( msg[, *args[, **kwargs]])
レベル DEBUG のメッセージをこのロガーで記録します。 msg はメッセージの書式化文字列で、args は msg に 取り込むための引数です。キーワード文字列 kwargs からは exc_info のみが調べられ、この値の評価値が偽でない場合、 (sys.exc_info から得た) 例外情報がログメッセージに追加されます。

info( msg[, *args[, **kwargs]])
レベル INFO のメッセージをこのロガーで記録します。 引数は debug() と同じように解釈されます。

warning( msg[, *args[, **kwargs]])
レベル WARNING のメッセージをこのロガーで記録します。 引数は debug() と同じように解釈されます。

error( msg[, *args[, **kwargs]])
レベル ERROR のメッセージをこのロガーで記録します。 引数は debug() と同じように解釈されます。

critical( msg[, *args[, **kwargs]])
レベル CRITICAL のメッセージをこのロガーで記録します。 引数は debug() と同じように解釈されます。

log( lvl, msg[, *args[, **kwargs]])
レベル lvl のメッセージをこのロガーで記録します。 その他の引数は debug() と同じように解釈されます。

exception( msg[, *args])
レベル ERROR のメッセージをこのロガーで記録します。 引数は debug() と同じように解釈されます。 例外情報はログメッセージに追加されます。このメソッドは 例外ハンドラからのみ呼び出されます。

addFilter( filt)
指定されたフィルタ filt をこのロガーに追加します。

removeFilter( filt)
指定されたフィルタ filt をこのロガーから除去します。

filter( record)
このロガーのフィルタをレコード (record) に適用し、レコードが フィルタを透過して処理されることになる場合には真を返します。

addHandler( hdlr)
指定されたハンドラ hdlr をこのロガーに追加します。

removeHandler( hdlr)
指定されたハンドラ hdlr をこのロガーから除去します。

findCaller( )
呼び出し元のソースファイル名と行番号を調べます。ファイル名と行番号 を 2 要素のタプルで返します。

handle( record)
レコードをこのロガーおよびその上位ロガーに (propagate の 値が偽になるまで) さかのぼった関連付けられている全てのハンドラに渡して 処理します。このメソッドはソケットから受信した逆 pickle 化された レコードに対してもレコードがローカルで生成された場合と同様に用いられます。 filter() によって、ロガーレベルでのフィルタが適用されます。

makeRecord( name, lvl, fn, lno, msg, args, exc_info)
このメソッドは、特殊な LogRecord インスタンスを生成する ためにサブクラスでオーバライドできるファクトリメソッドです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28 logging Up: 6.28 logging Next: 6.28.2 Handler オブジェクト


6.28.2 Handler オブジェクト

ハンドラは以下の属性とメソッドを持ちます。Handler は直接インスタンス化されることはありません; このクラスは より便利なサブクラスの基底クラスとして働きます。しかしながら、 サブクラスにおける __init__() メソッドでは、 Handler.__init__() を呼び出す必要があります。

__init__( level=NOTSET)
レベルを設定して、Handler インスタンスを初期化します。 空のリストを使ってフィルタを設定し、I/O 機構へのアクセスを 直列化するために (createLock() を使って) ロックを生成します。

createLock( )
スレッド安全でない根底の I/O 機能に対するアクセスを直列化 するために用いられるスレッドロック (thread lock) を初期化します。

acquire( )
createLock() で生成されたスレッドロックを獲得します。

release( )
acquire() で獲得したスレッドロックを解放します。

setLevel( lvl)
このハンドラに対する閾値を lvl に設定します。 ログ記録しようとするメッセージで、lvl よりも深刻でないものは 無視されます。ハンドラが生成された際、レベルは NOTSET (全てのメッセージが処理される) に設定されます。

setFormatter( form)
このハンドラのフォーマッタを form に設定します。

addFilter( filt)
指定されたフィルタ filt をこのハンドラに追加します。

removeFilter( filt)
指定されたフィルタ filt をこのハンドラから除去します。

filter( record)
このハンドラのフィルタをレコードに適用し、レコードが フィルタを透過して処理されることになる場合には真を返します。

flush( )
全てのログ出力がフラッシュされるようにします。このクラスの バージョンではなにも行わず、サブクラスで実装するためのものです。

close( )
ハンドラで使われている全てのリソースを始末します。このクラスの バージョンではなにも行わず、サブクラスで実装するためのものです。

handle( record)
ハンドラに追加されたフィルタの条件に応じて、指定されたログレコードを 発信します。このメソッドは I/O スレッドロックの獲得/開放を伴う実際の ログ発信をラップします。

handleError( )
このメソッドは emit() の呼び出し中に例外に遭遇した際に ハンドラから呼び出されます。デフォルトではこのメソッドは 何も行いません。すなわち、例外は暗黙のまま無視されます。 ほとんどのログ記録システムでは、これがほぼ望ましい機能です - というのは、ほとんどのユーザはログ記録システム自体のエラーは 気にせず、むしろアプリケーションのエラーに興味があるからです。 しかしながら、望むならこのメソッドを自作のハンドラと置き換え ることはできます。

format( record)
レコードに対する書式化を行います - フォーマッタ が設定されていれば、それを使います。そうでない場合、 モジュールにデフォルト指定されたフォーマッタを使います。

emit( record)
指定されたログ記録レコードを実際にログ記録する際の全ての処理 を行います。このメソッドのこのクラスのバージョンはサブクラスで 実装するためのものなので、NotImplementedError を送出します。

  • 6.28.2.1 StreamHandler
  • 6.28.2.2 FileHandler
  • 6.28.2.3 RotatingFileHandler
  • 6.28.2.4 SocketHandler
  • 6.28.2.5 DatagramHandler
  • 6.28.2.6 SysLogHandler
  • 6.28.2.7 NTEventLogHandler
  • 6.28.2.8 SMTPHandler
  • 6.28.2.9 MemoryHandler
  • 6.28.2.10 HTTPHandler
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.1 Logger オブジェクト Up: 6.28 logging Next: 6.28.2.1 StreamHandler


6.28.3 Formatter オブジェクト

Formatter は以下の属性とメソッドを持っています。 Formatter は LogRecord を (通常は) 人間か外部のシステム で解釈できる文字列に変換する役割を担っています。基底クラスの Formatter では書式化文字列を指定することができます。 何も指定されなかった場合、'%s(message)
n' の値が使われます。

Formatter は書式化文字列とともに初期化され、LogRecord 属性に 入っている知識を利用できるようにします - 上で触れたデフォルトの 値では、ユーザによるメッセージと引数はあらかじめ書式化されて、 LogRecord の message 属性に入っていることを利用しているようにです。 この書式化文字列は、Python 標準の % を使った変換文字列で構成されます。文字列整形に関する詳細は 8 ``String Formatting Operations'' の章を参照してください。

現状で、 LogRecord の有用な属性は以下に述べるようになっています:

Format | Description
%(name)s | ロガー (ログ記録チャネル) の名前
%(levelno)s | メッセージのログ記録レベルを表す数字 (DEBUG, INFO, WARNING, ERROR, CRITICAL)
%(levelname)s | メッセージのログ記録レベルを表す文字列 ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL")
%(pathname)s | ログ記録の呼び出しが行われたソースファイルの 全パス名 (取得できる場合)
%(filename)s | パス名中のファイル名部分
%(module)s | モジュール名 (ファイル名の名前部分)
%(lineno)d | ログ記録の呼び出しが行われたソース行番号 (取得できる場合)
%(created)f | LogRecord が生成された時刻 (time.time() の返した値)
%(asctime)s | LogRecord が生成された時刻を人間が読める書式で 表したもの。 デフォルトでは ``2003-07-08 16:49:45,896'' 形式 (コンマ以降の数字は時刻のミリ秒部分) です
%(msecs)d | LogRecord が生成された時刻の、ミリ秒部分
%(thread)d | スレッド ID (取得できる場合)
%(process)d | プロセス ID (取得できる場合)
%(message)s | レコードが発信された際に処理された msg % args の結果

class Formatter( [fmt[, datefmt]])
Formatter クラスの新たなインスタンスを返します。インスタンスは 全体としてのメッセージに対する書式化文字列と、メッセージの 日付/時刻部分のための書式化文字列を伴って初期化されます。fmt が指定されない場合、 '%(message)s' が使われます。 datefmt が指定されない場合、ISO8601 日付書式が使われます。

format( record)
レコードの属性辞書が、文字列を書式化する演算で被演算子として 使われます。書式化された結果の文字列を返します。 辞書を書式化する前に、二つの準備段階を経ます。 レコードの message 属性が msg % args を使って 処理されます。書式化された文字列が '(asctime)' を含む なら、 formatTime() が呼び出され、イベントの発生時刻を 書式化します。例外情報が存在する場合、formatException() を使って書式化され、メッセージに追加されます。

formatTime( record[, datefmt])
このメソッドは、フォーマッタが書式化された時間を利用したい際に、 format() から呼び出されます。このメソッドは特定の要求を 提供するためにフォーマッタで上書きすることができますが、基本的な 振る舞いは以下のようになります: datefmt (文字列) が指定された 場合、レコードが生成された時刻を書式化するために time.strftime() で使われます。そうでない場合、 ISO8601 書式が使われます。結果の文字列が返されます。

formatException( exc_info)
指定された例外情報 (sys.exc_info() が返すような 標準例外のタプル) を文字列として書式化します。 デフォルトの実装は単に traceback.print_exception() を使います。結果の文字列が返されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.2.10 HTTPHandler Up: 6.28 logging Next: 6.28.4 Filter オブジェクト


6.28.4 Filter オブジェクト

Filter は Handler と Logger によって利用され、 レベルによる制御よりも洗練されたフィルタ処理を提供します。基底の フィルタクラスでは、ロガーの階層構造のある点よりも下層にあるイベント だけを通過させます。例えば、"A.B" で初期化されたフィルタは ロガー "A.B"、 "A.B.C"、 "A.B.C.D"、 "A.B.D" などでログ記録された イベントを通過させます。しかし、 "A.BB"、"B.A.B" などは通過させません。 空の文字列で初期化された場合、全てのイベントを通過させます。

class Filter( [name])
Filter クラスのインスタンスを返します。 name が指定されて いれば、name はロガーの名前を表します。指定されたロガーとその子ロガー のイベントがフィルタを通過できるようになります。name が指定 されなければ、全てのイベントを通過させます。

filter( record)
指定されたレコードがログされているか？ されていなければゼロを、 されていればゼロでない値を返します。適切と判断されれば、このメソッド によってレコードは in place で修正されることがあります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.3 Formatter オブジェクト Up: 6.28 logging Next: 6.28.5 LogRecord オブジェクト


6.28.5 LogRecord オブジェクト

何かをログ記録する際は常に LogRecord インスタンスが生成されます。 インスタンスにはログ記録されることになっているイベントに関係する 全ての情報が入っています。インスタンスに渡される主要な情報は msg および args で、これらは msg % args を使って 組み合わせられ、レコードのメッセージフィールドを生成します。 レコードはまた、レコードがいつ生成されたか、ログ記録がソースコード 行のどこで呼び出されたか、あるいはログ記録すべき何らかの例外情報 といった情報も含んでいます。

LogRecord にはメソッドがありません; ログ記録イベントの情報を収めた ただの容器 (repository) です。このオブジェクトが辞書でなくクラスに なっている唯一の理由は、拡張を容易にするためです。

class LogRecord( name, lvl, pathname, lineno, msg, args, exc_info)
関係のある情報とともに初期化された LogRecord のインスタンスを 返します。name はロガーの名前です; lvl は数字で表された レベルです; pathname はログ記録呼び出しが見つかったソースファイル の絶対パス名です。msg はユーザ定義のメッセージ (書式化文字列) です; args はタプルで、msg と合わせて、ユーザメッセージ を生成します; exc_info は例外情報のタプルで、 sys.exc_info() を呼び出して得られたもの (または、 例外情報が取得できない場合には None) です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.4 Filter オブジェクト Up: 6.28 logging Next: 6.28.6 スレッド安全性


6.28.6 スレッド安全性

logging モジュールは、クライアントで特殊な作業を必要としない かぎりスレッド安全 (thread-safe) なようになっています。このスレッド 安全性はスレッドロックによって達成されています; モジュールの共有データへのアクセスを直列化するためのロックが 一つ存在し、各ハンドラでも根底にある I/O へのアクセスを直列化するために ロックを生成します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.5 LogRecord オブジェクト Up: 6.28 logging Next: 6.28.7 環境設定


6.28.7 環境設定

  • 6.28.7.1 環境設定のための関数
  • 6.28.7.2 環境設定ファイルの書式
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.6 スレッド安全性 Up: 6.28 logging Next: 6.28.7.1 環境設定のための関数


6.28.8 Using the logging package

  • 6.28.8.1 Basic example - log to a file
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.7.2 環境設定ファイルの書式 Up: 6.28 logging Next: 6.28.8.1 Basic example -


7. オプションのオペレーティングシステムサービス

この章で説明するモジュールでは、 特定のオペレーティングシステムでだけ利用できる オペレーティングシステム機能へのインターフェースを提供します。 このインターフェースは、 おおむね Unix や C のインターフェースにならってモデル化してありますが、 他のシステム上（WindowsやNTなど）でも利用できることがあります。 次に概要を示します。

signal | 非同期イベントにハンドラを設定します。
socket | 低レベルネットワークインターフェース。
select | 複数のストリームに対してI/O 処理の完了を待機します。
thread | 1つのインタープリタの中でのマルチスレッド制御
threading | 高レベルスレッドインターフェース
dummy_thread | thread の代替モジュール。
dummy_threading | threading の代替モジュール。
Queue | 同期キュークラス
mmap | Unix とWindowsのメモリマップファイルへのインターフェース
anydbm | DBM 形式のデータベースモジュールに対する汎用インタフェース。
dbhash | BSD データベースライブラリへの DBM 形式のインタフェース。
whichdb | どのDBM形式のモジュールが与えられたデータベースを作ったかを推測する
bsddb | Berkeley DB ライブラリへのインタフェース
dumbdbm | 単純な DBM インタフェースに対する可搬性のある実装。
zlib | gzip 互換の圧縮／解凍ルーチンへの低レベル インタフェース
gzip | ファイルオブジェクトを用いた gzip 圧縮および解凍のためのインタフェース
bz2 | bzip2 互換の圧縮／解凍ルーチンへのインタフェース
zipfile | ZIP-フォーマットのアーカイブファイルを読み書きする
tarfile | tar-形式のアーカイブファイルを読み書きします。
readline | Python のための GNU readline サポート。
rlcompleter | GNU readline ライブラリ向けのPython識別子補完

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.8.1 Basic example - Up: Python ライブラリリファレンス Next: 7.1 signal


7.1 signal -- 非同期イベントにハンドラを設定する

このモジュールでは Python でシグナルハンドラを使うための機構を 提供します。シグナルとハンドラを扱う上では、一般的なルールが いくつかあります:

  • 特定のシグナルに対するハンドラが一度設定されると、明示的に リセットしないかぎり設定されたままになります (Python は背後の実装系 に関係なく BSD 形式のインタフェースをエミュレートします)。 例外は SIGCHLD のハンドラで、この場合は背後の実装系の 仕様に従います。

  • クリティカルセクションから一時的にシグナルを``ブロック''することは できません。この機能をサポートしないUnix系システムも存在するた めです。

  • Python のシグナルハンドラは Python のユーザが望む限り非同期で呼び 出されますが、呼び出されるのは Python インタプリタの ``原子的な (atomic)'' 命令実行単位の間です。従って、 (巨大なサイズのテキストに対する正規表現の一致検索のような) 純粋に C 言語のレベルで実現されている時間のかかる処理中に 到着したシグナルは、不定期間遅延する可能性があります。

  • シグナルが I/O 操作中に到着すると、シグナルハンドラが処理を返した 後に I/O 操作が例外を送出する可能性があります。 これは背後にある Unix システムが割り込みシステムコールにどういう 意味付けをしているかに依存します。

  • C 言語のシグナルハンドラは常に処理を返すので、SIGFPE や SIGSEGV のような同期エラーの捕捉はほとんど意味が ありません。

  • Python は標準でごく小数のシグナルハンドラをインストールしています: SIGPIPE は無視されます (従って、パイプやソケットに対する 書き込みで生じたエラーは通常の Python 例外として報告されます) SIGINT は KeyboardInterrupt 例外に変換されます。 これらはどれも上書きすることができます。

  • シグナルとスレッドの両方を同じプログラムで使用する場合にはいくつか 注意が必要です。シグナルとスレッドを同時に利用する上で基本的に注意 すべきことは: 常に signal() 命令は主スレッド (main thread)の 処理中で実行するということです。どのスレッドも alarm()、 getsignal()、あるいは pause() を実行する ことができます; しかし、主スレッドだけが新たなシグナルハンドラを 設定することができ、従ってシグナルを受け取ることができるのは主スレッド だけです (これは、背後のスレッド実装が個々のスレッドに対するシグナル 送信をサポートしているかに関わらず、Python signal モジュール が強制している仕様です)。従って、シグナルをスレッド間通信の手段として 使うことはできません。代わりにロック機構を使ってください。

以下に signal モジュールで定義されている変数を示します:

SIG_DFL
二つある標準シグナル処理オプションのうちの一つです; 単にシグナルに 対する標準の関数を実行します。例えば、ほとんどのシステムでは、 SIGQUIT に対する標準の動作はコアダンプと終了で、 SIGCLD に対する標準の動作は単にシグナルの無視です。

SIG_IGN
もう一つの標準シグナル処理オプションで、単に受け取ったシグナルを 無視します。

SIG*
全てのシグナル番号はシンボル定義されています。例えば、ハングアップ シグナルは signal.SIGHUP で定義されています; 変数名は C 言語のプログラムで使われているのと同じ名前で、<signal.h> にあります。 `signal()' に関する Unix マニュアルページでは、 システムで定義されているシグナルを列挙しています (あるシステムではリストは signal(2) に、別のシステムでは signal(7) に列挙されています)。 全てのシステムで同じシグナル名のセットを定義しているわけではないので 注意してください; このモジュールでは、システムで定義されているシグナル 名だけを定義しています。

NSIG
最も大きいシグナル番号に 1 を足した値です。

signal モジュールでは以下の関数を定義しています:

alarm( time)
time がゼロでない値の場合、この関数は time 秒後頃に SIGALRM をプロセスに送るように要求します。 それ以前にスケジュールしたアラームはキャンセルされます (常に一つの アラームしかスケジュールできません)。この場合、戻り値は以前に設定 されたアラームシグナルが通知されるまであと何秒だったかを示す値です。 time がゼロの場合、アラームは一切スケジュールされず、現在 スケジュールされているアラームがキャンセルされます。 戻り値は以前にスケジュールされたアラームが通知される予定時刻までの 残り時間です。戻り値がゼロの場合、現在アラームがスケジュールされて いないことを示します。(Unix マニュアルページ alarm(2) を参照してください)。 利用可能: Unix。

getsignal( signalnum)
シグナル signalnum に対する現在のシグナルハンドラを返します。 戻り値は呼び出し可能な Python オブジェクトか、signal.SIG_IGN、 signal.SIG_DFL、および None といった特殊な値 のいずれかです。ここで signal.SIG_IGN は以前そのシグナルが 無視されていたことを示し、signal.SIG_DFL は以前そのシグナルの 標準の処理方法が使われていたことを示し、None はシグナルハンドラが まだ Python によってインストールされていないことを示します。

pause( )
シグナルを受け取るまでプロセスを一時停止します; その後、適切な ハンドラが呼び出されます。戻り値はありません。Windows では利用 できません。(Unix マニュアルページ signal(2) を 参照してください。)

signal( signalnum, handler)
シグナル signalnum に対するハンドラを関数 handler にします。 handler は二つの引数 (下記参照) を取る呼び出し可能な Python オブジェクトにするか、signal.SIG_IGN あるいは signal.SIG_DFL といった特殊な値にすることができます。 以前に使われていたシグナルハンドラが返されます (上記の getsignal() の記述を参照してください)。 (Unix マニュアルページ signal(2) を参照してください。)

複数スレッドの使用が有効な場合、この関数は主スレッドからのみ呼び出す ことができます; 主スレッド以外のスレッドで呼び出そうとすると、例外 ValueError が送出されます。

handler は二つの引数: シグナル番号、および現在のスタックフレーム (None またはフレームオブジェクト; フレームオブジェクトに ついての記述はリファレンスマニュアルを参照してください)、 とともに呼び出されます。

  • 7.1.1 例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7. オプションのオペレーティングシステムサービス Up: 7. オプションのオペレーティングシステムサービス Next: 7.1.1 例


7.1.1 例

以下は最小限のプログラム例です。この例では alarm() を使って、ファイルを開く処理を待つのに費やす時間を制限します; これはそのファイルが電源の入れられていないシリアルデバイスを 表している場合に有効で、通常こうした場合には os.open() は未定義の期間ハングアップしてしまいます。ここではファイルを開く まで 5 秒間のアラームを設定することで解決しています; ファイルを 開く処理が長くかかりすぎると、アラームシグナルが送信され、 ハンドラが例外を送出するようになっています。

import signal, os

pdef handler(signum, frame):
    print 'Signal handler called with signal', signum
    raise IOError, "Couldn't open device!"

# Set the signal handler and a 5-second alarm
signal.signal(signal.SIGALRM, handler)
signal.alarm(5)

# This open() may hang indefinitely
fd = os.open('/dev/ttyS0', os.O_RDWR)

signal.alarm(0)          # Disable the alarm
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.1 signal Up: 7.1 signal Next: 7.2 socket


7.2 socket -- 低レベルネットワークインターフェース

このモジュールは、PythonでBSD ソケット インターフェースを利用する ために使用します。最近のUnixシステム、Windows, MacOS, BeOS, OS/2な ど、多くのプラットフォームで利用可能です。

C言語によるソケットプログラミングの基礎については、以下の資料を参照して ください。 An Introductory 4.3BSD Interprocess Communication Tutorial (Stuart Sechrest), An Advanced 4.3BSD Interprocess Communication Tutorial (Samuel J. Leffler他), Unix Programmer's Manual, Supplementary Documents 1(PS1:7章 PS1:8章)。ソケットの詳細については、 各プラットフォームのソケット関連システムコールに関するドキュメント(Unix では マニュアルページ、WindowsではWinSock(またはWinSock2)仕様書)も参照し てください。IPv6対応のAPIについては、RFC 2553 Basic Socket Interface Extensions for IPv6を参照してくださ い。

Pythonインターフェースは、Unixのソケット用システムコールとライブラリ を、そのままPythonのオブジェクト指向スタイルに変換したものです。各種ソケ ット関連のシステムコールは、socket()関数で生成する ソケット オブジェクトのメソッドとして実装されてい ます。メソッドのパラメータはCのインターフェースよりも多少高水準で、例え ばread()やwrite()メソッドではファイルオブジェクトと同 様、受信時のバッファ確保や送信時の出力サイズなどは自動的に処理されます。

ソケットのアドレスは以下のように指定します:単一の文字列は、 AF_UNIXアドレスファミリを示します。(host, port)のペアはAF_INETアドレスファミリを示し、host は'daring.cwi.nl'のようなインターネットドメイン形式または '100.50.200.5'のようなIPv4アドレスを文字列で、portはポート 番号を整数で指定します。AF_INET6アドレスファミリは (host, port, flowinfo, scopeid)の長さ4の タプルで示し、flowinfoとscopeidにはそれぞれCの struct sockaddr_in6におけるsin6_flowinfoと sin6_scope_idの値を指定します。後方互換性のため、socket モジュールのメソッドではsin6_flowinfoとsin6_scope_idを省略 する事ができますが、scopeidを省略するとスコープを持ったIPv6アドレ スの処理で問題が発生する場合があります。現在サポートされているアドレスフ ァミリは以上です。ソケットオブジェクトで利用する事のできるアドレス形式 は、ソケットオブジェクトの作成時に指定したアドレスファミリで決まります。

IPv4アドレスのホストアドレスが空文字列の場合、INADDR_ANYとし て処理されます。また、'<broadcast>'の場合は INADDR_BROADCASTとして処理されます。IPv6では後方互換性のため この機能は用意されていませんので、IPv6をサポートするPythonプログラムでは 利用しないで下さい。

IPv4/v6ソケットのhost部にホスト名を指定すると、処理結果が一定では ない場合があります。これはPythonはDNSから取得したアドレスのうち最初のア ドレスを使用するので、DNSの処理やホストの設定によって異なるIPv4/6アドレ スを取得する場合があるためです。常に同じ結果が必要であれば、hostに 数値のアドレスを指定してください。

エラー時には例外が発生します。引数型のエラーやメモリ不足の場合には通常の 例外が発生し、ソケットやアドレス関連のエラーの場合は socket.errorが発生します。

setblocking()メソッドで、非ブロッキングモードを使用することがで きます。また、より汎用的にsettimeout()メソッドでタイムアウトを 指定する事ができます。

socketモジュールでは、以下の定数と関数を提供しています。

exception error
この例外は、ソケット関連のエラーが発生した場合に送出されます。例外の値は 障害の内容を示す文字列か、またはos.errorと同様な (errno, string)のペアとなります。オペレーティングシス テムで定義されているエラーコードについてはerrno を参照してください。

exception herror
この例外は、C APIのgethostbyname_ex()や gethostbyaddr()などで、h_errnoのようなアドレス関連のエ ラーが発生した場合に送出されます。

例外の値は(h_errno, string)のペアで、ライブラリの呼び 出し結果を返します。stringはC関数hstrerror()で取得し た、h_errnoの意味を示す文字列です。

exception gaierror
この例外はgetaddrinfo()とgetnameinfo()でアドレス関 連のエラーが発生した場合に送出されます。

例外の値は(error, string)のペアで、ライブラリの呼び出 し結果を返します。stringはC関数gai_strerror()で取得し た、h_errnoの意味を示す文字列です。

exception timeout
この例外は、あらかじめ settimeout() を呼び出してタイムアウトを 有効にしてあるソケットでタイムアウトが生じた際に送出されます。 例外に付属する値は文字列で、その内容は現状では常に ``timed out'' となります。 バージョン2.3 以降で新規追加された 仕様です。

AF_UNIX
AF_INET
AF_INET6
アドレス（およびプロトコル）ファミリを示す定数で、socket()の 最初の引数に指定することができます。AF_UNIXファミリをサポート しないプラットフォームでは、AF_UNIXは未定義となります。

SOCK_STREAM
SOCK_DGRAM
SOCK_RAW
SOCK_RDM
SOCK_SEQPACKET
ソケットタイプを示す定数で、socket()の2番目の引数に指定するこ とができます。(ほとんどの場合、SOCK_STREAMと SOCK_DGRAM以外は必要ありません。)

SO_*
SOMAXCONN
MSG_*
SOL_*
IPPROTO_*
IPPORT_*
INADDR_*
IP_*
IPV6_*
EAI_*
AI_*
NI_*
TCP_*

Unixのソケット・IPプロトコルのドキュメントで定義されている各種定数。 ソケットオブジェクトのsetsockopt()やgetsockopt()で使用 します。ほとんどのシンボルはUnixのヘッダファイルに従っています。一部 のシンボルには、デフォルト値を定義してあります。

has_ipv6
現在のプラットフォームでIPv6がサポートされているか否かを示す真偽値。 バージョン2.3 以降で新規追加された 仕様です。

getaddrinfo( host, port[, family[, socktype[, proto[, flags]]]])
host/port 引数の指すアドレス情報を解決して、 ソケット操作に必要な全ての引数が入った 5 要素のタプルを返します。 hostはドメイン名、IPv4/v6アドレスの文字列、またはNone です。port は'http'のようなサービス名文字列、ポート番号 を表す数値、またはNone です。

これ以外の引数は省略可能で、指定する場合には数値でなければなりません。 hostとport に空文字列かNone を指定すると C APIに NULLを渡せます。 getattrinfo() 関数は以下の構造をとる 5 要素のタプルを返します:

(family, socktype, proto, canonname, sockaddr)

family・socktype・protoは、socket()関数を呼 び出す際に指定する値と同じ整数です。canonnameはhostの規準名 を示す文字列です。AI_CANONNAMEを指定した場合、数値によるIPv4/ v6アドレスを返します。sockaddrは、ソケットアドレスを上述の形式で表 すタプルです。この関数の使い方については、httplibモジュール などのソースを参考にしてください。

バージョン2.2 以降で新規追加された 仕様です。

getfqdn( [name])
nameの完全修飾ドメイン名を返します。nameが空または省略された 場合、ローカルホストを指定したとみなします。完全修飾ドメイン名の取得には まずgethostbyaddr()でチェックし、次に可能であればエイリアスを 調べ、名前にピリオドを含む最初の名前を値として返します。完全修飾ドメイ ン名を取得できない場合、ホスト名を返します。

バージョン2.0 以降で新規追加された 仕様です。

gethostbyname( hostname)
ホスト名を'100.50.200.5'のようなIPv4形式のアドレスに変換します。 ホスト名としてIPv4アドレスを指定した場合、その値は変換せずにそのまま返り ます。gethostbyname() APIへのより完全なインターフェースが必要 であれば、gethostbyname_ex()を参照してください。 gethostbyname()は、IPv6名前解決をサポートしていません。IPv4/ v6のデュアルスタックをサポートする場合はgetaddrinfo()を使用し ます。

gethostbyname_ex( hostname)
ホスト名から、IPv4形式の各種アドレス情報を取得します。戻り値は (hostname, aliaslist, ipaddrlist)のタプルで、hostnameは ip_addressで指定したホストの正式名、aliaslistは同じアドレス の別名のリスト(空の場合もある)、ipaddrlistは同じホスト上の同一イ ンターフェースのIPv4アドレスのリスト(ほとんどの場合は単一のアドレスのみ) を示します。gethostbyname()は、IPv6名前解決をサポートしていま せん。IPv4/v6のデュアルスタックをサポートする場合は getaddrinfo()を使用します。

gethostname( )
Pythonインタープリタを現在実行中のマシンのホスト名を示す文字列を取得しま す。実行中マシンのIPアドレスが必要であれば、 gethostbyname(gethostname())を使用してください。この処理は実行中 ホストのアドレス-ホスト名変換が可能であることを前提としていますが、常に 変換可能であるとは限りません。注意: gethostname()は完全修飾ド メイン名を返すとは限りません。完全修飾ドメイン名が必要であれば、 gethostbyaddr(gethostname())としてください(下記参照)。

gethostbyaddr( ip_address)
(hostname, aliaslist, ipaddrlist)のタプルを返 し、hostnameはip_addressで指定したホストの正式名、 aliaslistは同じアドレスの別名のリスト(空の場合もある)、 ipaddrlistは同じホスト上の同一インターフェースのIPv4アドレスのリ スト(ほとんどの場合は単一のアドレスのみ)を示します。完全修飾ドメイン名が 必要であれば、getfqdn()を使用してください。 gethostbyaddrは、IPv4/IPv6の両方をサポートしています。

getnameinfo( sockaddr, flags)
ソケットアドレスsockaddrから、(host, port)のタ プルを取得します。flagsの設定に従い、hostは完全修飾ドメイン 名または数値形式アドレスとなります。同様に、portは文字列のポート名 または数値のポート番号となります。 バージョン2.2 以降で新規追加された 仕様です。

getprotobyname( protocolname)
'icmp'のようなインターネットプロトコル名を、socket()の 第三引数として指定する事ができる定数に変換します。これは主にソケットを`` raw''モード(SOCK_RAW)でオープンする場合には必要ですが、通常の ソケットモードでは第三引数に0を指定するか省略すれば正しいプロトコルが自 動的に選択されます。

getservbyname( servicename, protocolname)
インターネットサービス名とプロトコルから、そのサービスのポート番号を取得 します。プロトコル名として、'tcp'か'udp'を指定することがで きます。

socket( family, type[, proto])
アドレスファミリ、ソケットタイプ、プロトコル番号を指定してソケットを作成 します。アドレスファミリにはAF_INET・AF_INET6・ AF_UNIXを指定することができます。ソケットタイプには SOCK_STREAM・SOCK_DGRAM・または"SOCK_"の何れ かを指定します。プロトコル番号には通常省略するか、または0を指定します。

ssl( sock[, keyfile, certfile])
ソケットsockによるSSL接続を初期化します。keyfileには、PEMフ ォーマットのプライベートキーファイル名を指定します。certfileには、 PEMフォーマットの認証チェーンファイル名を指定します。処理が成功すると、 新しいSSLObjectが返ります。

警告: 証明書の認証は全く行いません。

fromfd( fd, family, type[, proto])
既存のファイルディスクリプタ(ファイルオブジェクトのfileno()で返 る整数)から、ソケットオブジェクトを構築します。アドレスファミリとプロト コル番号はsocket()と同様に指定します。ファイルディスクリプタ はソケットを指していなければなりませんが、実際にソケットであるかどうかの チェックは行っていません。このため、ソケット以外のファイルディスクリプタ を指定するとその後の処理が失敗する場合があります。この関数が必要な事はあ まりありませんが、Unixのinetデーモンのようにソケットを標準入力や標準 出力として使用するプログラムで使われます。この関数で使用するソケットは、 ブロッキングモードと想定しています。 利用可能:Unix

ntohl( x)
32ビット整数のバイトオーダを、ネットワークバイトオーダからホストバイト オーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致す るマシンでは、この関数は何もしません。それ以外の場合は4バイトのスワップ を行います。

ntohs( x)
16ビット整数のバイトオーダを、ネットワークバイトオーダからホストバイト オーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致す るマシンでは、この関数は何もしません。それ以外の場合は2バイトのスワップ を行います。

htonl( x)
32ビット整数のバイトオーダを、ホストバイトオーダからネットワークバイト オーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致す るマシンでは、この関数は何もしません。それ以外の場合は4バイトのスワップ を行います。

htons( x)
16ビット整数のバイトオーダを、ホストバイトオーダからネットワークバイト オーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致す るマシンでは、この関数は何もしません。それ以外の場合は2バイトのスワップ を行います。

inet_aton( ip_string)
ドット記法によるIPv4アドレス('123.45.67.89'など)を32ビットにパッ クしたバイナリ形式に変換し、長さ4の文字列として返します。この関数が返す 値は、標準Cライブラリのstruct in_addr型を使用する関数に渡す事がで きます。

IPv4アドレス文字列が不正であれば、socket.errorが発生します。 このチェックは、この関数で使用しているCの実装 inet_aton()で 行われます。

inet_aton()は、IPv6をサポートしません。IPv4/v6のデュアルスタ ックをサポートする場合はgetnameinfo()を使用します。

inet_ntoa( packed_ip)
32ビットにパックしたバイナリ形式のIPv4アドレスを、ドット記法による文字列 ('123.45.67.89'など)に変換します。この関数が返す値は、標準Cライブ ラリのstruct in_addr型を使用する関数に渡す事ができます。

この関数に渡す文字列の長さが4バイト以外であれば、 socket.errorが発生します。 inet_ntoa()は、IPv6をサポートしません。IPv4/v6のデュアルスタ ックをサポートする場合はgetnameinfo()を使用します。

inet_pton( address_family, ip_string)
IPアドレスを、アドレスファミリ固有の文字列からパックしたバイナリ形式に変 換します。inet_pton()は、struct in_addr型 (inet_aton()と同様)やstruct in6_addrを使用するライブ ラリやネットワークプロトコルを呼び出す際に使用することができます。

現在サポートされているaddress_familyは、AF_INETと AF_INET6です。ip_stringに不正なIPアドレス文字列を指定す ると、socket.errorが発生します。有効なip_stringは、 address_familyとinet_pton()の実装によって異なります。

利用可能: Unix (サポートしていないプラットフォームもあります) バージョン2.3 以降で新規追加された 仕様です。

inet_ntop( address_family, packed_ip)
パックしたIPアドレス(数文字の文字列)を、'7.10.0.5'や '5aef:2b::8'などの標準的な、アドレスファミリ固有の文字列形式に変 換します。inet_ntop()は(inet_ntoa()と同様に) struct in_addr型やstruct in6_addr型のオブジェクトを返す ライブラリやネットワークプロトコル等で使用することができます。

現在サポートされているaddress_familyは、AF_INETと AF_INET6です。packed_ipの長さが指定したアドレスファミリ で適切な長さでなければ、ValueErrorが発生します。 inet_ntop()でエラーとなると、socket.errorが発生し ます。

利用可能: Unix (サポートしていないプラットフォームもあります) バージョン2.3 以降で新規追加された 仕様です。

getdefaulttimeout( )
新規に生成されたソケットオブジェクトの、デフォルトのタイムアウト値を浮動 小数点形式の秒数で返します。タイプアウトを使用しない場合にはNone を返します。最初にsocketモジュールがインポートされた時の初期値は Noneです。

バージョン2.3 以降で新規追加された 仕様です。

setdefaulttimeout( timeout)
新規に生成されたソケットオブジェクトの、デフォルトのタイムアウト値を浮動 小数点形式の秒数で指定します。タイムアウトを使用しない場合には Noneを指定します。最初にsocketモジュールがインポートされた時の初 期値はNoneです。

バージョン2.3 以降で新規追加された 仕様です。

SocketType
ソケットオブジェクトの型を示す型オブジェクト。type(socket(...))と 同じです。

参考資料:

SocketServerモジュール:
ネットワークサーバの開発を省力化するためのク ラス群。.

  • 7.2.1 socket オブジェクト
  • 7.2.2 SSL オブジェクト
  • 7.2.3 例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.1.1 例 Up: 7. オプションのオペレーティングシステムサービス Next: 7.2.1 socket オブジェクト


7.2.1 socket オブジェクト

ソケットオブジェクトは以下のメソッドを持ちます。makefile()以外 のメソッドは、Unixのソケット用システムコールに対応しています。

accept( )
接続を受け付けます。ソケットはアドレスにbind済みで、listen中である必要が あります。戻り値は(conn, address)のペアで、conn は接続を通じてデータの送受信を行うための新しいソケットオブジェク ト、addressは接続先でソケットにbindしているアドレスを示します。

bind( address)
ソケットをaddressにbindします。bind済みのソケットを再バインドする 事はできません。addressのフォーマットはアドレスファミリによって異 なります(前述)。 注意: 本来、このメソッドは単一のタプルのみを引数として受け付けますが、 以前はAF_INETアドレスを示す二つの値を指定する事ができました。 これは本来の仕様ではなく、Python 2.0以降では使用することはできません。

close( )
ソケットをクローズします。以降、このソケットでは全ての操作が失敗します。 リモート端点ではキューに溜まったデータがフラッシュされた後はそれ以上の データを受信しません。ソケットはガベージコレクション時に自動的にクローズ されます。

connect( address)
addressで示されるリモートソケットに接続します。addressのフ ォーマットはアドレスファミリによって異なります(前述)。 注意: 本来、このメソッドは単一のタプルのみを引数として受け付けますが、 以前はAF_INETアドレスを示す二つの値を指定する事ができました。 これは本来の仕様ではなく、Python 2.0以降では使用することはできません。

connect_ex( address)
connect(address)と同様ですが、C言語のconnect() 関数の呼び出しでエラーが発生した場合には例外を送出せずにエラーを戻り値と して返します。(これ以外の、``host not found,''等のエラーの場合には例外が 発生します。)処理が正常に終了した場合には0を返し、エラー時には errnoの値を返します。この関数は、非同期接続をサポートする場合な どに使用することができます。 注意: 本来、このメソッドは単一のタプルのみを引数として受け付けますが、 以前はAF_INETアドレスを示す二つの値を指定する事ができました。 これは本来の仕様ではなく、Python 2.0以降では使用することはできません。

fileno( )
ソケットのファイルディスクリプタを整数型で返します。ファイルディスクリプ タは、select.select()などで使用します。

getpeername( )
ソケットが接続しているリモートアドレスを返します。この関数は、リモート IPv4/v6ソケットのポート番号を調べる場合などに使用します。addressの フォーマットはアドレスファミリによって異なります(前述)。この関数をサポー トしていないシステムも存在します。

getsockname( )
ソケット自身のアドレスを返します。この関数は、IPv4/v6ソケットのポート番 号を調べる場合などに使用します。addressのフォーマットはアドレスフ ァミリによって異なります(前述)。

getsockopt( level, optname[, buflen])
ソケットに指定されたオプションを返します(Unixのマニュアルページ getsockopt(2)を参照)。SO_*等のシンボルは、このモジ ュールで定義しています。buflenを省略した場合、取得するオブションは 整数とみなし、整数型の値を戻り値とします。buflenを指定した場合、長 さbuflenのバッファでオプションを受け取り、このバッファを文字列とし て返します。このバッファは、呼び出し元プログラムでstruct モジュール等を利用して内容を読み取ることができま す。

listen( backlog)
ソケットをListenし、接続を待ちます。引数backlogには接続キューの最 大の長さ(1以上)を指定します。backlogの最大数はシステムに依存します (通常は5)。

makefile( [mode[, bufsize]])
ソケットに関連付けられたファイルオブジェクトを返します(ファイルオ ブジェクトについては2.3.8の``ファイルオブジェクト''を 参照)。ファイルオブジェクトはソケットをdup()したファイルディ スクリプタを使用しており、ソケットオブジェクトとファイルオブジェクトは 別々にクローズしたりガベージコレクションで破棄したりする事ができます。ソ ケットはブロッキングモードでなければなりません。 オプション引数のmodeとbufsize には、file()組み込み関数と同じ値を指定します。 2.1の``組み込み関数''を参照してください。

recv( bufsize[, flags])
ソケットからデータを受信し、文字列として返します。受信する最大バイト数 は、bufsizeで指定します。flagsのデフォルト値は0です。値の意 味についてはUnixマニュアルページのrecv(2)を参照してくださ い。

recvfrom( bufsize[, flags])
ソケットからデータを受信し、結果をタプル(string, address)として返します。stringは受信データの文字列で、 addressは送信元のアドレスを示します。オプション引数flagsの意 味は、上記recv()と同じです。addressのフォーマットはアドレ スファミリによって異なります(前述)。

send( string[, flags])
ソケットにデータを送信します。ソケットはリモートソケットに接続済みでなけ ればなりません。オプション引数flagsの意味は、上記recv()と 同じです。戻り値として、送信したバイト数を返します。アプリケーションで は、必ず戻り値をチェックし、全てのデータが送られた事を確認する必要があり ます。データの一部だけが送信された場合、アプリケーションで残りのデータを 再送信してください。

sendall( string[, flags])
ソケットにデータを送信します。ソケットはリモートソケットに接続済みでなけ ればなりません。オプション引数flagsの意味は、上記recv()と 同じです。send()と異なり、このメソッドはstringの全データ を送信するか、エラーが発生するまで処理を継続します。正常終了の場合は Noneを返し、エラー発生時には例外が発生します。エラー発生時、送信 されたバイト数を調べる事はできません。

sendto( string[, flags], address)
ソケットにデータを送信します。このメソッドでは接続先をaddressで指 定するので、接続済みではいけません。オプション引数flagsの意味は、 上記recv()と同じです。戻り値として、送信したバイト数を返しま す。addressのフォーマットはアドレスファミリによって異なります(前 述)。

setblocking( flag)
ソケットのブロッキング・非ブロッキングモードを指定します。flagが0 の場合は非ブロッキングモード、0以外の場合はブロッキングモードとなりま す。全てのソケットは、初期状態ではブロッキングモードです。非ブロッキング モードでは、recv()メソッド呼び出し時に読み込みデータが無かった りsend()メソッド呼び出し時にデータを処理する事ができないような 場合にerror例外が発生します。しかし、ブロッキングモードでは 呼び出しは処理が行われるまでブロックされます。s.setblocking(0)は s.settimeout(0)と、s.setblocking(1)は s.settimeout(None)とそれぞれ同じ意味を持ちます。

settimeout( value)
ソケットのブロッキング処理のタイムアウト値を指定します。valueに は、正の浮動小数点で秒数を指定するか、もしくはNoneを指定します。 浮動小数点値を指定した場合、操作が完了する前にvalueで指定した秒数 が経過するとtimeoutが発生します。タイムアウト値にNoneを 指定すると、ソケットのタイムアウトを無効にします。 s.settimeout(0.0)はs.setblocking(0)と、 s.settimeout(None)はs.setblocking(1)とそれぞれ同じ意味を持 ちます。 バージョン2.3 以降で新規追加された 仕様です。

gettimeout( )
ソケットに指定されたタイムアウト値を取得します。タイムアウト値が設定され ている場合には浮動小数点型で秒数が、設定されていなければNoneが返 ります。この値は、最後に呼び出されたsetblocking()または settimeout()によって設定されます。 バージョン2.3 以降で新規追加された 仕様です。

ソケットのブロッキングとタイムアウトについて:ソケットオブジェクトのモー ドは、ブロッキング・非ブロッキング・タイムアウトの何れかとなります。初期 状態では常にブロッキングモードです。ブロッキングモードでは、処理が完了す るまでブロックされます。非ブロッキングモードでは、処理を行う事ができなけ れば(不幸にもシステムによって異なる値の)エラーとなります。タイムアウト モードでは、ソケットに指定したタイムアウトまでに完了しなければ処理は失敗 となります。setblocking()メソッドは、settimeout()の省 略形式です。

内部的には、タイムアウトモードではソケットを非ブロッキングモードに設定し ます。ブロッキングとタイムアウトの設定は、ソケットと同じネットワーク端点 へ接続するファイルディスクリプタにも反映されます。この結果、 makefile()で作成したファイルオブジェクトはブロッキングモードで のみ使用することができます。これは非ブロッキングモードとタイムアウトモー ドでは、即座に完了しないファイル操作はエラーとなるためです。

setsockopt( level, optname, value)
ソケットのオプションを設定します(Unixのマニュアルページ setsockopt(2)を参照)。SO_*等のシンボルは、このモジ ュールで定義しています。valueには、整数または文字列をバッファとし て指定する事ができます。文字列を指定する場合、文字列には適切なビットを設 定するようにします。(structモジュール を利用すれば、Cの構造体を文字列にエンコードする事ができます。)

shutdown( how)
接続の片方向、または両方向を切断します。howが0の場合、以降 は受信を行えません。howが1の場合、以降は送信を行えません。 howが2の場合、以降は送受信を行えません。

read()メソッドとwrite()メソッドは存在しませんので注意 してください。代わりにflagsを省略したrecv()と send()を使うことができます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.2 socket Up: 7.2 socket Next: 7.2.2 SSL オブジェクト


7.2.2 SSL オブジェクト

SSLオブジェクトには、以下のメソッドがあります。

write( s)
文字列sをSSL接続で出力します。戻り値として、送信したバイト数を返し ます。

read( [n])
SSL接続からデータを受信します。nを指定した場合は指定したバイト数の データを受信し、省略時はEOFまで読み込みます。戻り値として、受信したバイ ト列の文字列を返します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.2.1 socket オブジェクト Up: 7.2 socket Next: 7.2.3 例


7.2.3 例

以下はTCP/IPプロトコルの簡単なサンプルとして、受信したデータをクライアン トにそのまま返送するサーバ(接続可能なクライアントは一件のみ)と、サーバに 接続するクライアントの例を示します。サーバでは、socket()・ bind()・listen()・accept()を実行し(複数のクラ イアントからの接続を受け付ける場合、accept()を複数回呼び出しま す)、クライアントではsocket()とconnect()だけを呼び出 しています。サーバではsend()/recv()メソッドはlisten中 のソケットで実行するのではなく、accept()で取得したソケットに対 して実行している点にも注意してください。

次のクライアントとサーバは、IPv4のみをサポートしています。

# Echo server program
import socket

HOST = ''                 # Symbolic name meaning the local host
PORT = 50007              # Arbitrary non-privileged port
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.bind((HOST, PORT))
s.listen(1)
conn, addr = s.accept()
print 'Connected by', addr
while 1:
    data = conn.recv(1024)
    if not data: break
    conn.send(data)
conn.close()

# Echo client program
import socket

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.connect((HOST, PORT))
s.send('Hello, world')
data = s.recv(1024)
s.close()
print 'Received', `data`

The next two examples are identical to the above two, but support both IPv4 and IPv6. The server side will listen to the first address family available (it should listen to both instead). On most of IPv6-ready systems, IPv6 will take precedence and the server may not accept IPv4 traffic. The client side will try to connect to the all addresses returned as a result of the name resolution, and sends traffic to the first one connected successfully.

次のサンプルは上記のサンプルとほとんど同じですが、IPv4とIPv6の両方をサ ポートしています。サーバでは、IPv4/v6の両方ではなく、利用可能な最初のア ドレスファミリだけをlistenしています。ほとんどのIPv6対応システムではIPv6 が先に現れるため、サーバはIPv4には応答しません。クライアントでは名前解決 の結果として取得したアドレスに順次接続を試み、最初に接続に成功したソケッ トにデータを送信しています。

# Echo server program
import socket
import sys

HOST = ''                 # Symbolic name meaning the local host
PORT = 50007              # Arbitrary non-privileged port
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
    af, socktype, proto, canonname, sa = res
    try:
    s = socket.socket(af, socktype, proto)
    except socket.error, msg:
    s = None
    continue
    try:
    s.bind(sa)
    s.listen(1)
    except socket.error, msg:
    s.close()
    s = None
    continue
    break
if s is None:
    print 'could not open socket'
    sys.exit(1)
conn, addr = s.accept()
print 'Connected by', addr
while 1:
    data = conn.recv(1024)
    if not data: break
    conn.send(data)
conn.close()

# Echo client program
import socket
import sys

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
    af, socktype, proto, canonname, sa = res
    try:
    s = socket.socket(af, socktype, proto)
    except socket.error, msg:
    s = None
    continue
    try:
    s.connect(sa)
    except socket.error, msg:
    s.close()
    s = None
    continue
    break
if s is None:
    print 'could not open socket'
    sys.exit(1)
s.send('Hello, world')
data = s.recv(1024)
s.close()
print 'Received', `data`
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.2.2 SSL オブジェクト Up: 7.2 socket Next: 7.3 select


7.3 select -- I/O 処理の完了を待機する

このモジュールでは、ほとんどのオペレーティングシステムで利用可能な select() および poll() 関数へのアクセス 機構を提供します。Windows の上ではソケットに対してしか動作しないので 注意してください; その他のオペレーティングシステムでは、他のファイル 形式でも (特に Unixではパイプにも) 動作します。通常のファイルに 対して適用し、最後にファイルを読み出した時から内容が増えているかを 決定するために使うことはできません。

このモジュールでは以下の内容を定義しています:

exception error
エラーが発生したときに送出される例外です。エラーに付属する 値は、 errno からとったエラーコードを表す数値とその エラーコードに対応する文字列からなるペアで、C 関数の perror() が出力するものと同様です。

poll( )
(全てのオペレーティングシステムでサポートされているわけでは ありません。) ポーリングオブジェクトを返します。このオブジェクトは ファイル記述子を登録したり登録解除したりすることができ、 ファイル記述子に対する I/O イベント発生をポーリングすることが できます; ポーリングオブジェクトが提供しているメソッドについては 下記の 7.3.1 節を参照してください。

select( iwtd, owtd, ewtd[, timeout])
Unix の select() システムコールに対する直接的な インタフェースです。最初の 3 つの引数は `待機可能なオブジェクト' からなるリストです: ファイル記述子を表す整数値、または 引数を持たず、整数を返すメソッド fileno() を持つ オブジェクトです。待機可能なオブジェクトの 3 つのリストはそれぞれ 入力、出力、そして `例外状態' に対応します。いずれかに空のリストを 指定してもかまいませんが、3 つ全てを空のリストにしてもよいかどうか はプラットフォームに依存します (Unix では動作し、Windows では 動作しないことが知られています)。オプションの timeout 引数 にはタイムアウトまでの秒数を浮動小数点数型で指定します。 timeout 引数が省略された場合、関数は少なくとも一つのファイル 記述子が何らかの準備完了状態になるまでブロックします。 タイムアウト値ゼロは、ポーリングを行いブロックしないことを示します。

戻り値は準備完了状態のオブジェクトからなる 3 つのリストです: 従ってこのリストはそれぞれ関数の最初の 3 つの引数のサブセットに なります。ファイル記述子のいずれも準備完了にならないままタイムアウト した場合、3 つの空のリストが返されます。

リストの中に含めることのできるオブジェクトは Python ファイル オブジェクト (すなわち sys.stdin, あるいは open() や os.popen() が返すオブジェクト)、socket.socket() が返すソケットオブジェクト です。 wrapper クラスを自分で定義することもできます。この場合、 適切な (単なる乱数ではなく本当のファイル記述子を返す)fileno() メソッドを持つ必要があります 注意: select はWindows のファイルオブジェクトを受理 しませんが、ソケットは受理します 。 Windows では、 背後の select() 関数は WinSock ライブラリで提供されて おり、WinSock によって生成されたものではないファイル記述子を扱う ことができないのです。

  • 7.3.1 ポーリングオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.2.3 例 Up: 7. オプションのオペレーティングシステムサービス Next: 7.3.1 ポーリングオブジェクト


7.3.1 ポーリングオブジェクト

poll() システムコールはほとんどの Unix システムでサポート されており、非常に多数のクライアントに同時にサービスを提供するような ネットワークサーバが高い拡張性を持てるようにしています。 poll() に高い拡張性があるのは、select() が ビット対応表を構築し、対象ファイルの記述子に対応するビットを立て、 その後全ての対応表の全てのビットを線形探索するのに対し、 poll() は対象のファイル記述子を列挙するだけでよいから です。 select() は O(最大のファイル記述子番号) なのに対し、 poll() は O(対象とするファイル記述子の数) で済みます。

register( fd[, eventmask])
ファイル記述子をポーリングオブジェクトに登録します。これ以降の poll() メソッド呼び出しでは、そのファイル記述子に処理待ち中の I/O イベントがあるかどうかを監視します。fd は整数か、 整数値を返す fileno() メソッドを持つオブジェクトを取ります。 ファイルオブジェクトも通常 fileno() を実装しているので、 引数として使うことができます。

eventmask はオプションのビットマスクで、どのタイプの I/O イベント を監視したいかを記述します。この値は以下の表で述べる定数 POLLIN、 POLLPRI、および POLLOUT の組み合わせにすることが できます。ビットマスクを指定しない場合、標準の値が使われ、 3 種のイベント全てに対して監視が行われます。

定数 | 意味
POLLIN | 読み出せるデータの存在
POLLPRI | 緊急の読み出しデータの存在
POLLOUT | 書き出せるかどうか: 書き出し処理がブロックしないかどうか
POLLERR | 何らかのエラー状態
POLLHUP | ハングアップ
POLLNVAL | 無効な要求: 記述子が開かれていない

すでに登録済みのファイル記述子を登録してもエラーにはならず、 一度だけ登録した場合と同じ効果になります。

unregister( fd)
ポーリングオブジェクトによって追跡中のファイル記述子を登録解除します。 register() メソッドと同様に、fd は整数か、 整数値を返す fileno() メソッドを持つオブジェクトを取ります。

登録されていないファイル記述子を登録解除しようとすると KeyError 例外が送出されます。

poll( [timeout])
登録されたファイル記述子に対してポーリングを行い、 報告すべき I/O イベントまたはエラーの発生したファイル記述子に 毎に 2 要素のタプル (fd, event) からなるリスト を返します。リストは空になることもあります。 fd はファイル記述子で、event は該当するファイル記述子 について報告されたイベントを表すビットマスクです -- 例えば POLLIN は入力待ちを示し、POLLOUT はファイル記述子 に対する書き込みが可能を示す、などです。 空のリストは呼び出しがタイムアウトしたか、報告すべきイベントが どのファイル記述子でも発生しなかったことを示します。 timeout が与えられた場合、処理を戻すまで待機する時間の長さを ミリ秒単位で指定します。timeout が省略されたり、負の値であったり、 あるいは None の場合、そのポーリングオブジェクトが監視している 何らかのイベントが発生するまでブロックします。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.3 select Up: 7.3 select Next: 7.4 thread


7.4 thread -- マルチスレッドのコントロール

このモジュールはマルチスレッド(別名 軽量プロセス (light-weight processes)またはタスク(tasks)) に用いられる低レベルプリミティブを提供します -- グローバルデータ空間を共有するマルチスレッドを制御します。 同期のための単純なロック(別名 mutexesまたは バイナリセマフォ(binary semaphores))が提供されています。

このモジュールはオプションです。 Windows, Linux, SGI IRIX, Solaris 2.x、そして同じようなPOSIXスレッド (別名``pthread'')実装のシステム上でサポートされます。 threadを使用することのできないシステムでは、 dummy_threadが用意されています。 dummy_threadはこのモジュールと同じインターフェース を持ち、置き換えて使用することができます。

定数と関数は以下のように定義されています:

exception error
スレッド特有のエラーで送出されます。

LockType
これはロックオブジェクトのタイプです。

start_new_thread( function, args[, kwargs])
新しいスレッドを開始して、そのIDを返します。 スレッドは引数リストargs(タプルでなければなりません)の 関数functionを実行します。 オプション引数kwargsはキーワード引数の辞書を指定します。 関数が戻るとき、スレッドは黙って終了します。 関数が未定義の例外でターミネートしたとき、スタックトレースが表示され、 そしてスレッドが終了します(しかし他のスレッドは走り続けます)。

interrupt_main( )
メインスレッドで KeyboardInterrupt を送出します。サブスレッドは この関数を使ってメインスレッドに割り込みをかけることができます。 バージョン2.3 以降で新規追加された 仕様です。

exit( )
SystemExit例外を送出します。 それが捕えられないときは、黙ってスレッドを終了させます。

allocate_lock( )
新しいロックオブジェクトを返します。 ロックのメソッドはこの後に記述されます。 ロックは初期状態としてアンロック状態です。

get_ident( )
現在のスレッドの`スレッドID'を返します。 これは0でない整数です。 この値は直接の意味を持っていません; 例えばスレッド特有のデータの辞書に索引をつけるためのような、 マジッククッキーとして意図されています。 スレッドが終了し、他のスレッドが作られたとき、 スレッドIDは再利用されるかもしれません。

ロックオブジェクトは次のようなメソッドを持っています:

acquire( [waitflag])
オプションの引数なしで使用すると、このメソッドは他のスレッドがロックし ているかどうかにかかわらずロックを獲得し、None を返します。 ただし他のスレッドがすでにロックしている場合には解除されるまで 待ってからロックを獲得します (同時にロックを獲得できるスレッドは ひとつだけであり、これこそがロックの存在理由です)。 整数の引数 waitflag を指定すると、その値によって動作が変わります。 引数が 0 のときは、待たずにすぐ獲得できる場合にだけロックを獲得 します。0 以外の値を与えると、先の例と同様、ロックの状態に かかわらず獲得をおこないます。なお、引数を与えた場合、ロックを獲得すると True、できなかったときには False を返します。

release( )
ロックを解放します。そのロックは既に獲得されたものでなければなりませんが、 しかし同じスレッドによって獲得されたものである必要はありません。

locked( )
ロックの状態を返します: 同じスレッドによって獲得されたものならTrue、 違うのならFalseを返します。

Caveats:

  • スレッドは割り込みと奇妙な相互作用をします: KeyboardInterrupt例外は任意のスレッドによって受け取られます。 (signalモジュールが利用可能なとき、 割り込みは常にメインスレッドへ行きます。)

  • sys.exit()を呼び出す、 あるいはSystemExit例外を送出することは、 exit()を呼び出すことと同じです。

  • I/O待ちをブロックするかもしれない全ての組込み関数が、 他のスレッドの走行を許すわけではありません。 (ほとんどの一般的なもの (time.sleep(), file.read(), select.select())は期待通りに働きます。)

  • ロックのacquire()メソッドに割り込むことはできません -- KeyboardInterrupt例外は、ロックが獲得された後に発生します。

  • メインスレッドが終了したとき、他のスレッドが生き残るかどうかは、 システムが定義します。 ネイティブスレッド実装を使うSGI IRIXでは生き残ります。 その他の多くのシステムでは、try ... finally節 を実行せずに殺されたり、デストラクタを実行せずに殺されたりします。

  • メインスレッドが終了したとき、それの通常のクリーンアップは行なわれず (try ... finally節が尊重されることは除きます)、 標準I/Oファイルはフラッシュされません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.3.1 ポーリングオブジェクト Up: 7. オプションのオペレーティングシステムサービス Next: 7.5 threading


7.5 threading -- 高レベルスレッドインターフェース

このモジュールは、低レベルなthreadモジュールの上に、 高レベルスレッドインターフェースを構築しています。

threadが存在しないために threading を利用できない場合、 代わりにrefmodule[dummythreading]dummy_threadingを使用することができます。

関数とオブジェクトは次のように定義されています:

activeCount( )
現在のアクティブなThreadオブジェクトの数を返します。 この返された数は、enumerate()から返されるリストの長さと等しいです。 現在のアクティブなスレッドの数を返す関数です。

Condition( )
新しい条件変数オブジェクトを返すファクトリー関数です。 条件変数は、一つ以上のスレッドが他のスレッドによって通知されるまで 待つことを許します。

currentThread( )
呼んだ関数のスレッドに相当する、現在のThreadオブジェクトを返します。 その関数のスレッドがthreadingモジュールを使って作られていなければ、 機能を制限したダミースレッドオブジェクトが返されます。

enumerate( )
現在のすべてのアクティブThreadオブジェクトのリストを返します。 このリストは、デーモンスレッド(currentThread()によって作られた ダミースレッドオブジェクト)と、メインスレッドを含みます。 このリストは、ターミネートしたスレッドと、 まだ開始していないスレッドを除きます。

Event( )
新しいイベントオブジェクトを返すファクトリー関数です。
イベントは、set()メソッドでTrueにセットでき、
clear()メソッドでFalseにリセットできるフラグを扱います。
wait()メソッドは、フラグがTrueになるまでブロックします。

Lock( )
新しいプリミティブロックオブジェクトを返すファクトリー関数です。 いったんスレッドがロックを獲得すると、 それが解放されるまで次の獲得試行をブロックします; どのスレッドがそれを解放してもかまいません。

RLock( )
新しい再入可能ロックオブジェクトを返すファクトリー関数です。 再入可能ロックはそれを獲得したスレッドによって解放されなければなりません。 いったんスレッドが再入可能ロックを獲得すると、 同じスレッドはブロックされずにもう一度それを獲得できます; そのスレッドは獲得した回数だけ解放しなければいけません。

Semaphore( [value])
新しいセマフォオブジェクトを返すファクトリー関数です。 セマフォは、release()を呼び出した数から、 acquire()を呼び出した数を引いて、 初期値を足した数を反映するカウンターを扱います。 acquire()メソッドは、カウンターが負にならずに返ることができるまで、 ブロックします。 もしvalueが与えられなかったら、デフォルトに1を使います。

BoundedSemaphore( [value])
新しい有限セマフォオブジェクトを返すファクトリー関数です。 有限セマフォは、現在値が初期値を超過することを阻止します。 もし超過した場合、ValueErrorが投げられます。 ほとんどの状況で、セマフォは限りある容量しかもたない資源を 保護するために使用されます。 セマフォがあまりにも何度も解放される場合、それはバグの表れです。 もしvalueが与えられなかったら、デフォルトに1を使います。

class Thread
制御しているスレッドを表すクラスです。 このクラスは制限のある範囲内で安全にサブクラス化できます。

class Timer
指定した時間が経過しか後に、関数を実行するスレッドです。

settrace( func)
threading モジュールで開始された全てのスレッドに トレース関数 を設定します。 func は各スレッドの run() が呼び出される以前に sys.settrace() に渡されます。 バージョン2.3 以降で新規追加された 仕様です。

setprofile( func)
threading モジュールで開始された全てのスレッドに プロファイル関数 を設定します。 func は各スレッドの run() が呼び出される以前に sys.settrace() に渡されます。 バージョン2.3 以降で新規追加された 仕様です。

オブジェクトの詳細なインターフェースを以下に説明します。

このモジュールのデザインはJavaスレッドモデルを適当に使いました。しかし、 Javaはロックと条件変数をすべてのオブジェクトの基本的な振舞いにしましたが、 Pythonではそれらは独立したオブジェクトです。PythonのThreadクラス はJavaスレッドクラスの振舞いのサブセットを提供します; 現在、優先スレッド、 スレッドグループはありません。スレッドのdestroy,stop,suspend,resume, interruptなどはできません。Javaスレッドクラスのstaticメソッドは、実装され たときに、モジュールレベルの関数にマップされています。

以下に記述された全てのメソッドはアトミックに実行されます。

  • 7.5.1 Lock オブジェクト
  • 7.5.2 RLock オブジェクト
  • 7.5.3 Condition オブジェクト
  • 7.5.4 Semaphore オブジェクト
    • 7.5.4.1 Semaphore の例
  • 7.5.5 Event オブジェクト
  • 7.5.6 Thread オブジェクト
  • 7.5.7 Timer オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.4 thread Up: 7. オプションのオペレーティングシステムサービス Next: 7.5.1 Lock オブジェクト


7.5.1 Lock オブジェクト

プリミティブロックはロックされたとき、特定のスレッドによって所有されない 同期プリミティブです。 Pythonでは現在、最も低レベルのプリミティブロックが利用可能であり、 thread拡張モジュールによって直接実装されています。

プリミティブロックは2つの状態 - ``ロック''または``アンロック'' - を持ちます。ロックはアンロック状態で作られます。 ロックは2つの基本メソッド、acquire()とrelease()を持ちます。 アンロック状態のとき、acquire()はロック状態へ変更し 直ちにリターンします。 ロック状態のとき、acquire()は、他のスレッドがrelease() を呼出しアンロック状態へ変更するまで、ブロックします。 そして、acquire()呼出しはロック状態へリセットしてリターンします。 release()メソッドはロック状態のときに呼ぶべきです; それはアンロック状態へ変更すると直ちにリターンします。 1つ以上のスレッドが、アンロック状態に変更されるのを待つため acquire()でブロックされているときに、 release()でアンロック状態へリセットされると、 1つのスレッドのみが先に進めます; 待っているスレッドのどれが進めるかは定義されておらず、 実装によって異なることでしょう。

全てのメソッドはアトミックに実行されます。

acquire( [blocking = 1])
ブロックまたは非ブロックのロックを獲得します。

引数なしで呼だ出すと、ロックがアンロックされるまでブロックして、 そしてロック状態へセットしリターンします。 この場合戻り値はありません。

引数blockingをTrueにセットして呼び出すと、 引数なしで呼び出したときと同じことを行ない、Trueを返します。

引数blockingをFalseにセットして呼び出すと、ブロックしません。 引数のない呼び出しにおいてブロックされる状況ならば、直ちにFalseを返します; そうでない状況ならば、引数なしで呼び出したときと同じことを行ない、 Trueを返します。

release( )
ロックを解放します。

ロック状態のとき、アンロック状態へリセットして返ります。 ロックがアンロック状態になるのを待っている他のスレッドが、 ブロックされていたとき、厳密に1つだけが進むことを許可します。

ロックがアンロック状態のとき、このメソッドを呼び出してはいけません。

戻り値はありません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.5 threading Up: 7.5 threading Next: 7.5.2 RLock オブジェクト


7.5.2 RLock オブジェクト

再入可能ロックは同じスレッドによって複数回獲得される同期プリミティブです。 それは内部に、プリミティブロックによって使われるロック/アンロック状態 に加えて、``所有スレッド''と``再帰レベル''の概念を使います。 ロック状態ではあるスレッドがロックを所有し、 アンロック状態ではどのスレッドもそれを所有しません。

ロックすると、スレッドはそのacquire()メソッドを呼びます。 いったんスレッドがロックを所有すると返ります。 アンロックすると、スレッドはそのrelease()メソッドを呼びます。 acquire()/release()呼び出しペアはネストされるべきです。 最後のrelease()だけは(最も外側のペアのrelease())は ロックをアンロック状態へリセットします。 そしてacquire()でブロックされた別のスレッドが進むことを許可します。

acquire( [blocking = 1])
ブロックまたは非ブロックのロックを獲得します。

引数なしで呼び出されたとき: もしこのスレッドが既にロックを所有する場合、 それによって再帰レベルをインクリメントし、直ちに返ります。 一方、別のスレッドがロックを所有する場合、アンロックされるまでブロックします。 いったんそのロックがアンロックされた(どのスレッドによっても所有されていない) とき、所有権を掴み、再帰レベルを1にセットし、返ります。 1つ以上のスレッドが、そのロックがアンロックされるのを待ち、 ブロックされているとき、ただ1つのスレッドがロックの所有権を掴むことができます。 この場合、返り値はありません。

blocking引数がTrueにセットされて呼び出されたとき、 引数無しで呼び出したときと同じように動作し、trueを返します。

blocking引数がFalseにセットされて呼び出されたとき、ブロックしません。 もし引数無しの呼び出しにおいてブロックされるような状況ならば、 直ちにFalseを返します; そうでない状況ならば、引数無しの呼出しと同じように動作して、 Trueを返します。

release( )
ロックを解放し、再帰レベルをデクリメントします。 デクリメントの後にそれが0になるならば、ロックをアンロックします (他のスレッドによって所有されていない場合)。 そして他のスレッドがブロックされていたならば、 それらのうちの1つに進むことを許可します。 デクリメントの後も再帰レベルが非0であるならば、引続きロック状態であり 呼出しスレッドによって所有されている。

呼出しスレッドがロックを所有しているとき、単にこのメソッドを呼出してください。 アンロック状態のとき、このメソッドを呼出してはいけません。

返り値はありません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.5.1 Lock オブジェクト Up: 7.5 threading Next: 7.5.3 Condition オブジェクト


7.5.3 Condition オブジェクト

条件変数(condition variable)はつねにある種類のロックに関係しています; 明示的にロックを渡すこともできますし、 デフォルトによって暗黙で作成させることもできます。 (いくつかの条件変数が同じロックを共有しなければならない場合、 そのロックを明示的に渡すことができます。)

条件変数は、関連するロックと対応するメソッドを呼出すacquire()と release()を持っています。 加えてwait(),notify(),notifyAll()メソッドを 持っています。 呼出しスレッドがロックを獲得しているときにだけ、 この3つのメソッドを呼出すようにしなければいけません。

wait()メソッドはロックを解放し、他のスレッドで同じ条件変数を notify()またはnotifyAll()によって起こされるまで ブロックします。 いったん起こされるとそれはロックを再獲得して戻ります。 タイムアウトを指定することも可能です。

notify()メソッドは条件変数を待っているスレッドを1つ起こします。 notifyAll()メソッドは条件変数を待っている全てのスレッドを起こします。

Note: notify()とnotifyAll()はロックを解放しません。 これは次のことを意味します; スレッドが起こされたときwait()呼出しから直ちに戻らず、 notify()またはnotifyAll()を呼出したスレッドが 最終的にロックの所有権を譲ることで戻ります。

Tip: 条件変数を使う典型的なプログラミングスタイルは、 共有状態へ同期アクセスするためにロックを使います。 状態の特定の変更に興味のあるスレッドは、望む状態になるまでwait()を 繰り返し呼出します。 同時に、待ちスレッドのうちの1つが望む状態に対して、 状態を変更するスレッドがnotify()またはnotifyAll()を 呼出します。 例えば、以下のコードはバッファ容量に限界のない場合における 一般的な生産者-消費者問題です。

# Consume one item
cv.acquire()
while not an_item_is_available():
    cv.wait()
get_an_available_item()
cv.release()

# Produce one item
cv.acquire()
make_an_item_available()
cv.notify()
cv.release()

notify()とnotifyAll()の選択は、その状態が1つだけ あるいは複数の待ちスレッドに興味があるかによって考慮します。 例えば典型的な生産者-消費者問題で、バッファに1つのアイテムを加えたとき、 1つだけ消費者スレッドを起こす必要があります。

class Condition( [lock])
もしlock引数をNone以外で与えるならば、 LockまたはRLockオブジェクトでなければならず、 それは基礎ロックとして使われます。 それ以外のとき、新しいRLockオブジェクトを作り基礎ロックとして 使われます。

acquire( *args)
基礎ロックを獲得します。 このメソッドは基礎ロックに関連するメソッドを呼出します。 返り値はそのメソッドからのものです。

release( )
基礎ロックを解放します。 このメソッドは基礎ロックに関連するメソッドを呼出します。 返り値はありません。

wait( [timeout])
通知を受ける(notify)あるいはタイムアウトするまで待ちます。 これは呼出しスレッドがロックを獲得しているときにだけ、呼出すことができます。

このメソッドは基礎ロックを解放し、他のスレッドで同じ条件変数の notify()またはnotifyAll()呼出しによって起こされるまで、 あるいはタイムアウトするまでブロックします。 いったん起こされたりタイムアウトしたなら、ロックを再獲得して戻ります。

timeout引数がNone以外で与えられたとき、 それはタイムアウトを秒(またはその分数)で指定する浮動小数であるべきです。

基礎ロックがRLockの場合、それが複数回再帰的に獲得さられたときに アンロックされないのでrelease()メソッドを使っては解放されません。 代わりに、RLockクラスの内部インターフェースが使うことで、実際には 再帰的に複数回獲得されたときにアンロックします。 そして他の内部インターフェースはロックが再獲得されたときに、 再帰レベルを元に戻すことで使用されます。

notify( )
もし存在するなら、この条件を待っているスレッドを起こします。 これは呼出しスレッドがロックを獲得しているときにだけ、呼出すように しなければいけません。

もし待っているスレッドがあるのなら、このメソッドは条件変数を 待っているスレッドのうちの1つを起こします。 もし待っているスレッドがないのなら、なにもしません。

もし待っているスレッドがあるのなら、現在の実装ではまさしく1つの スレッドを起こします。 しかしこの振舞いに依存するのは安全ではありません。 将来、最適化された実装は1つ以上のスレッドを起こすかもしれません。

Note: 起こされたスレッドは実際にロックを再獲得できるまでwait() 呼出しから戻りません。 notify()はロックを解放しないからです。

notifyAll( )
この条件を待っているすべてのスレッドを起こします。 このメソッドはnotify()のように作用しますが、 1つではなくすべての待ちスレッドを起こします。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.5.2 RLock オブジェクト Up: 7.5 threading Next: 7.5.4 Semaphore オブジェクト


7.5.4 Semaphore オブジェクト

これはコンピュータ科学の歴史の中で最も古い同期プリミティブの1つであり、 オランダのコンピュータ科学者 Edsger W. Dijkstra によって発明されました (彼はacquire()とrelease()の代わりに P()とV()を使いました)。

セマフォはacquire()でデクリメントされrelease()で インクリメントされる内部カウンタを管理します。 カウンタが0より小さくなることは決してありません。 カウンタが0であることをacquire()メソッドが見いだしたとき、 他のスレッドがrelease()を呼び出すまでブロックされます。

class Semaphore( [value])
オプション引数は内部カウンタの初期値を与えます; デフォルトは1です。

acquire( [blocking])
セマフォを獲得します。

引数なしで呼出したとき: 内部カウンタが0より大きいならば、 1だけデクリメントし直ちに戻ります。 内部カウンタが0ならば、他のスレッドがrelease()を呼出し カウンタを0より大きくするまでブロックされます。 複数のacquire()呼出しがブロックされる場合、 release()がそれらのうちのただ1つを起こすよう、 適切な内部ロックを行ないます。 その実装はランダムに1つを選び出すかもしれません。 そのためブロックされたスレッドが起こされる順序に依存してはなりません。 このケースの返り値はありません。

blockingをTrueで呼出したとき: 引数なしで呼出した場合と同じことを 行ない、Trueを返します。

blockingをFalseで呼出したとき: ブロックされません。 引数なし呼出しにおいてブロックされるような状況ならば、直ちにFalseを返します。 そうでないなら引数なし呼出しと同じことを行ない、Trueを返します。

release( )
セマフォを解放し、内部カウンタを1インクリメントします。 カウンタが0で、他のスレッドが0より大きくなるのを待っているのなら、 そのスレッドは起きます。

  • 7.5.4.1 Semaphore の例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.5.3 Condition オブジェクト Up: 7.5 threading Next: 7.5.4.1 Semaphore の例


7.5.5 Event オブジェクト

これはスレッド間で通信するための最も簡単なメカニズムの1つです: あるスレッドがイベントを発信し、他のスレッドがそれを待ちます。

イベントオブジェクトは、set()メソッドでTrueにセットし、
clear()メソッドでFalseにリセットする、内部フラグを管理します。
wait()メソッドはフラグがTrueになるまでブロックします。

class Event( )
内部フラグをFalseに初期化します。

isSet( )
内部フラグがTrueの場合、そしてTrueの場合のみ、Trueを返します。

set( )
内部フラグをTrueにセットします。 それがTrueになるのを待っている全てのスレッドは起こされます。 wait()を呼出したスレッドは、いったんフラグがTrueになると 全てがブロックされなくなります。

clear( )
内部フラグをFalseにリセットします。 その後、set()が内部フラグを再びTrueにセットするために呼出されるまで、 wait()を呼出したスレッドはブロックされるでしょう。

wait( [timeout])
内部フラグがTrueになるまでブロックします。 もし内部フラグがTrueだった場合、直ちに返ります。 そうでなかった場合、他のスレッドがset()を呼出し フラグをTrueにセットするまで、あるいはオプションtimeoutが 発生するまで、ブロックします。

timeout引数がNone以外で与えられたとき、 それはタイムアウトを秒(またはその分数)で指定する浮動小数です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.5.4.1 Semaphore の例 Up: 7.5 threading Next: 7.5.6 Thread オブジェクト


7.5.6 Thread オブジェクト

このクラスは個別のスレッド中で実行される活動を表わします。 その活動を決定する方法は2つあり、呼出し可能オブジェクトをコンストラクタへ渡す、 またはサブクラスでrun()メソッドをオーバーライドするということです。 他のメソッド(コンストラクタを除く)はサブクラスでオーバーライドしては なりません。 言いかえれば、このクラスの__init__()とrun()メソッド だけをオーバーライドしてください。

いったんスレッドオブジェクトが作成されれば、その活動をスレッドの start()メソッドを呼ぶことによりスタートさせなければなりません。 これは、それぞれのスレッドのrun()メソッドを起動します。

スレッドの活動が始まると、そのスレッドは'生きていて(alive)' そして'活動している(active)'と考えられます (これらの概念は、ほとんど同じであるが、しかし全く同じではない; それらの定義は故意に多少曖昧になっています)。 それは run()メソッドが終了した時に、 またはunhandled例外が送出された時に、生きること活動することをやめます。 スレッドが生きていてもisAlive()メソッドはテストします。

他のスレッドはスレッドのjoin()メソッドを呼ぶことができます。 join()メソッドを呼ばれたスレッドが終了するまで、 呼出しスレッドをブロックします。

スレッドは名前を持っています。 その名前はコンストラクタへ渡すことができ、 setName()メソッドでセットし、 getName()メソッドで得ることができます。

スレッドは``デーモンスレッド''としてフラグすることができます。 このフラグの意味は、デーモンスレッドだけが残されたとき、 Pythonプログラム全体が終了するということです。 初期値は作成するスレッドから継承されます。 そのフラグはsetDaemon()メソッドでセットされ、 isDaemon()メソッドで得ることができます。

``メインスレッド''オブジェクトがあります。 これはPythonプログラムの最初のスレッドに相当します。 それはデーモンスレッドではありません。

``ダミースレッドオブジェクト''を作成することができます。 これは``エイリアンスレッド''に相当するスレッドオブジェクトです。 スレッドモジュールの外部でスタートするスレッドで、 直接Cコードで実装されているようなものです。 ダミースレッドオブジェクトは機能が制限されています。 それらは常に、生きていて(alive)、活動していて(active)、 デーモン(daemon)であるが、join()することはできません。 エイリアンスレッドの終了は検知することが不可能であるので、 それらは削除されません。

class Thread( group=None, target=None, name=None, args=(), kwargs={})
このコンストラクタは常に引数とともに呼ばれるべきです。 引数:

groupはNoneでなければいけません。 ThreadGroupクラスが実装されたときのための、 将来の拡張として予約されています。

targetはrun()メソッドによって呼出される、 呼出し可能オブジェクトです。 デフォルトはNoneであり、何も呼出さないことを意味します。

nameはスレッドの名前です。 デフォルトによって、ユニークな名前は``Thread-N''の形式で構築されます。 Nは小さな10進数です。

argsはtargetを呼出すときに渡される引数のタプルです。 デフォルトは()です。

kwargsはtargetを呼出すときに渡される引数の辞書です。 デフォルトは{}です。

サブクラスがコンストラクタをオーバーライドしたときは、 スレッドが何かを始める前に、基底クラスのコンストラクタ (Thread.__init__())を確実に呼出さなくてはいけません。

start( )
スレッドの活動を始めます。

これはスレッドオブジェクトにつき一度だけ呼出すようにします。 オブジェクトのrun()メソッドが個別のスレッドの中で 呼出されるよう準備します。

run( )
スレッドの活動を表すメソッドです。

あなたは、このメソッドをサブクラスでオーバーライドします。 標準のrun()メソッドは、targetとして オブジェクトのコンストラクタに渡された、呼出し可能オブジェクトを呼出します。 もしあるのなら、argsとkwargs引数から得られたシーケンシャルな、 あるいは辞書の引数を使います。

join( [timeout])
スレッドが終了するまで待ちます。 これはjoin()メソッドが呼ばれたスレッドが終了するまで、 呼出しスレッドをブロックします。 もしくは、unhandled例外が送出される、あるいはオプションのタイムアウトが 発生するまでブロックします。

timeout引数がNone以外で与えられたとき、 それはタイムアウトを秒(またはその分数)で指定する浮動小数です。

スレッドは何度でもjoin()されることができます。

スレッドは自身にjoinすることはできません。 デッドロックを引き起こします。

スレッドがスタートする前にjoin()を試みることは 間違っています。

getName( )
スレッド名を返します。

setName( name)
スレッド名をセットします。

名前は識別のためだけに使われる文字列です。 セマンティクスではありません。 複数のスレッドに同じ名前を与えることができます。 初期名はコンストラクタによってセットされます。

isAlive( )
スレッドが生きているかどうか返します。

多くの場合、スレッドはstart()メソッドを呼出した瞬間から run()メソッドが終了するまで生きています。

isDaemon( )
スレッドのデーモンフラグを返します。

setDaemon( daemonic)
スレッドのデーモンフラグを真偽値daemonicでセットします。 これはstart()を呼出す前に使わなくてはいけません。

初期値は作成するスレッドから継承されます。

デーモンでないアクティブなスレッドが残ってないとき、 Pythonプログラム全体が終了します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.5.5 Event オブジェクト Up: 7.5 threading Next: 7.5.7 Timer オブジェクト


7.5.7 Timer オブジェクト

このクラスは、タイマーで一定の時間が経過した後に実行するべき動作を表します。 TimerはThreadのサブクラスであり、 カスタムスレッドの例としての機能を持っています。

start()メソッドを呼出すことで、 タイマーはスレッドとしてスタートします。 cancel()メソッドを呼出すことで、 (その動作が始まる前に)タイマーはストップすることが出来ます。 タイマーは、ユーザーによって指定された間隔と正確に同じでは ないかもしれませんが、その動作を実行する前に待ちます。

例:

def hello():
    print "hello, world"

t = Timer(30.0, hello)
t.start() # after 30 seconds, "hello, world" will be printed

class Timer( interval, function, args=[], kwargs={})
interval秒が過ぎた後に、引数argsとキーワード引数kwargs によってfunctionを実行するタイマーを作成します。

cancel( )
タイマーをストップして、その動作の実行をキャンセルします。 タイマーがまだその待ち状態にある場合では、単にこのように働きます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.5.6 Thread オブジェクト Up: 7.5 threading Next: 7.6 dummy_thread


7.6 dummy_thread -- thread の代替モジュール

このモジュールは thread モジュールのインターフェースをそっ くりまねるものです。thread モジュールがサポートされていな いプラットフォームで import することを意図して作られたものです。

使用例:

try:
    import thread as _thread
except ImportError:
    import dummy_thread as _thread

生成するスレッドが、他のブロックしたスレッドを待ち、デッドロック発生の 可能性がある場合には、このモジュールを使わないようにしてください。ブロッ キング I/O を使っている場合によく起きます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.5.7 Timer オブジェクト Up: 7. オプションのオペレーティングシステムサービス Next: 7.7 dummy_threading


7.7 dummy_threading -- threading の代替モジュール

このモジュールは threading モジュールのインターフェースを そっくりまねるものです。threading モジュールがサポートされ ていないプラットフォームで import することを意図して作られたものです。

使用例:

try:
    import threading as _threading
except ImportError:
    import dummy_threading as _threading

生成するスレッドが、他のブロックしたスレッドを待ち、デッドロック発生の 可能性がある場合には、このモジュールを使わないようにしてください。ブロッ キング I/O を使っている場合によく起きます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.6 dummy_thread Up: 7. オプションのオペレーティングシステムサービス Next: 7.8 Queue


7.8 Queue -- 同期キュークラス

Queueモジュールは、多生産者-多消費者FIFOキューを実装します。 これは、複数のスレッドの間で情報を安全に交換しなければならないときの スレッドプログラミングで特に有益です。 このモジュールのQueueクラスは、 必要なすべてのロックセマンティクスを実装しています。 これはPythonのスレッドサポートの状況に依存します。

参考資料:

bisectモジュール:
Queueクラスを使った優先順位付きキューの例.

Queueモジュールは以下のクラスと例外を定義します:

class Queue( maxsize)
クラスのコンストラクタです。 maxsizeはキューに置くことのできる要素数の上限を設定する整数です。 いったんこの大きさに達したら、挿入はキューの要素が消費されるまでブロック されます。 もしmaxsizeが0以下であるならば、キューの大きさは無限です。

exception Empty
空またはロックされているQueueオブジェクトで、 非ブロックメソッドとしてget()(またはget_nowait()) が呼ばれたとき、送出される例外です。

exception Full
満杯またはロックされているQueueオブジェクトで、 非ブロックメソッドとしてput()(またはput_nowait()) が呼ばれたとき、送出される例外です。

  • 7.8.1 キューオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.7 dummy_threading Up: 7. オプションのオペレーティングシステムサービス Next: 7.8.1 キューオブジェクト


7.8.1 キューオブジェクト

クラスQueueはキューオブジェクトを実装しており、 以下のメソッドを持っています。 このクラスは、他のキュー構造(例えばスタック)を実装するために 派生させられるますが、継承可能なインタフェースはここでは説明しません。 詳しいことはソースコードを見てください。 公開メソッドは次のものです:

qsize( )
キューの大まかなサイズを返します。 マルチスレッドセマンティクスにおいて、この値は信頼できません。

empty( )
キューが空ならTrueを返し、そうでないならFalseを返します。 マルチスレッドセマンティクスにおいて、この値は信頼できません。

full( )
キューが満杯ならTrueを返し、そうでないならFalseを返します。 マルチスレッドセマンティクスにおいて、この値は信頼できません。

put( item[, block[, timeout]])
itemをキューに入れます。 もしオプション引数blockがTrueでtimeoutがNone(デフォルト)ならば、 フリースロットが利用可能になるまでブロックします。 timeoutが正の値の場合、最大でtimeout秒間ブロックし、 その時間内に空きスロットが利用可能にならなければ、 例外Fullを送出します。 他方(blockがFalse)、直ちにフリースロットが利用できるならば、 キューにアイテムを置きます。できないならば、例外Fullを送出します (この場合timeoutは無視されます)。

バージョン2.3 以降で新規追加された 仕様: the timeout parameter

put_nowait( item)
put(item, False)と同じ意味です。

get( [block[, timeout]])
キューからアイテムを取り除き、それを返します。 もしオプション引数blockがTrueでtimeoutがNone(デフォルト)ならば、 アイテムが利用可能になるまでブロックします。 もしtimeoutが正の値の場合、最大でtimeout秒間ブロックし、 その時間内でアイテムが利用可能にならなければ、 例外Emptyを送出します。 他方(blockがFalse)、直ちにアイテムが利用できるならば、 それを返します。できないならば、例外Emptyを送出します (この場合timeoutは無視されます)。

バージョン2.3 以降で新規追加された 仕様: the timeout parameter

get_nowait( )
get(False)と同じ意味です。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.8 Queue Up: 7.8 Queue Next: 7.9 mmap


7.9 mmap -- メモリマップファイル

メモリにマップされたファイルオブジェクトは、 文字列とファイルオブジェクトの両方のように振舞います。 しかし通常の文字列オブジェクトとは異なり、これらは可変です。 文字列が期待されるほとんどの場所でmmapオブジェクトを利用できます。 例えば、メモリマップファイルを探索するために reモジュールを使うことができます。 それらは可変なので、 obj[index] = 'a' のように文字を 変換できますし、スライスを使うことで obj[i1:i2] = '...' のように 部分文字列を変換することができます。 現在のファイル位置をデータの始めとする読込みや書込み、 ファイルの異なる位置へseek()することもできます。

メモリマップファイルはUnix上とWindows上とでは異なる mmap()関数によって作られます。 いずれの場合も、開いたファイルのディスクリプタを、 更新のために提供しなければなりません。 すでに存在するPythonファイルオブジェクトをマップしたい場合は、 filenoパラメータのための現在値を手に入れるために、 fileno()メソッドを使用して下さい。 そうでなければ、ファイル・ディスクリプタを直接返すos.open()関数 (呼び出すときにはまだファイルが閉じている必要があります)を使って、 ファイルを開くことができます。

関数のUnixバージョンとWindowsバージョンのために、 オプションのキーワード・パラメータとしてaccessを指定する ことになるかもしれません。 accessは3つの値の内の1つを受け入れます。 ACCESS_READは読み込み専用、 ACCESS_WRITEは書き込み可能、 ACCESS_COPYはコピーした上での書き込みです。 accessはUnixとWindowsの両方で使用することができます。 accessが指定されない場合、Windowsのmmapは書き込み可能マップを返します。 3つのアクセス型すべてに対する初期メモリ値は、 指定されたファイルから得られます。 ACCESS_READを割り当てたメモリマップは TypeError例外を送出します。 ACCESS_WRITEを割り当てたメモリマップは メモリと元のファイルの両方に影響を与えます。 ACCESS_COPYを割り当てたメモリマップは メモリに影響を与えますが、元のファイルを更新することはありません。

mmap( fileno, length[, tagname[, access]])
(Windows)バージョンはファイルハンドルfilenoによって 指定されたファイルからlengthバイトをマップして、 mmapオブジェクトを返します。 lengthが0の場合、マップの最大の長さは mmap()が呼ばれたときのファイルサイズになるでしょう。

tagnameは、None以外で指定された場合、 マップのタグ名を与える文字列となります。 Windowsは同じファイルに対する様々なマップを持つことを可能にします。 既存のタグの名前を指定すればそのタグがオープンされ、 そうでなければこの名前の新しいタグが作成されます。 もしこのパラメータを省略したりNoneを与えたりしたならば、 マップは名前なしで作成されます。 タグ・パラメータの使用の回避は、あなたのコードをUnixとWindowsの間で 移植可能にしておくのを助けてくれるでしょう。

mmap( fileno, length[, flags[, prot[, access]]])
(Unix)バージョンは、ファイル・ディスクリプタ filenoに よって指定されたファイルからlengthバイトをマップし、 mmapオブジェクトを返します。

flagsはマップの種類を指定します。 MAP_PRIVATEはプライベートなcopy-on-write(書込み時コピー) のマップを作成します。 従って、mmapオブジェクトの内容への変更はこのプロセス内にのみ有効です。 MAP_SHAREDはファイルの同じ領域をマップする他のすべてのプロセス と共有されたマップを作成します。 デフォルトはMAP_SHAREDです。

protが指定された場合、希望のメモリ保護を与えます。 2つの最も有用な値は、PROT_READとPROT_WRITEです。 これは、読込み可能または書込み可能を指定するものです。 protのデフォルトはPROT_READ | PROT_WRITEです。

accessはオプションのキーワード・パラメータとして、 flagsとprotの代わりに指定してもかまいません。 flags,protとaccessの両方を指定することは間違っています。 このパラメーターを使用法についての情報は、 accessの記述を参照してください。

メモリマップフィイルオブジェクトは以下のメソッドをサポートしています:

close( )
ファイルを閉じます。 この呼出しの後にオブジェクトの他のメソッドの呼出すことは、 例外の送出を引き起こすでしょう。

find( string[, start])
オブジェクト内で部分文字列stringが見つかった場所の最も小さい インデックスを返します。 失敗したとき-1を返します。 startは探索を始めたい場所のインデックスで、デフォルトは0です。

flush( [offset, size])
ファイルのメモリコピー内での変更をディスクへフラッシュします。 この呼出しを使わなかった場合、オブジェクトが破壊される前に 変更が書き込まれる保証はありません。 もしoffsetとsizeが指定された場合、与えられたバイトの範囲の 変更だけがディスクにフラッシュされます。 指定されない場合、マップ全体がフラッシュされます。

move( dest, src, count)
オフセットsrcからインデックスdestへcountバイトだけ コピーします。 もしmmapがACCESS_READで作成されていた場合、 TypeError例外を送出します。

read( num)
現在のファイル位置からnumバイトの文字列を返します。 ファイル位置は返したバイトの分だけ後ろの位置へ更新されます。

read_byte( )
現在のファイル位置から長さ1の文字列を返します。 ファイル位置は1だけ進みます。

readline( )
現在のファイル位置から次の新しい行までの、1行を返します。

resize( newsize)
もしmmapがACCESS_READまたはACCESS_COPYで 作成されたならば、マップのリサイズはTypeError例外を送出します。

seek( pos[, whence])
ファイルの現在位置をセットします。 whence引数はオプションであり、デフォルトは0(絶対位置)です。 その他の値として、1(現在位置からの相対位置)と 2(ファイルの終わりからの相対位置)があります。

size( )
ファイルの長さを返します。 メモリマップ領域のサイズより大きいかもしれません。

tell( )
ファイル・ポインタの現在位置を返します。

write( string)
メモリ内のファイル・ポインタの現在位置からstringのバイト列を 書き込みます。 ファイル位置はバイト列が書き込まれた後の位置へ更新されます。 もしmmapがACCESS_READで作成されていた場合、 書き込み時にTypeError例外が送出されるでしょう。

write_byte( byte)
メモリ内のファイル・ポインタの現在位置から 単一文字の文字列byteを書き込みます。 ファイル位置は1だけ進みます。 もしmmapがACCESS_READで作成されていた場合、 書き込み時にTypeError例外が送出されるでしょう。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.8.1 キューオブジェクト Up: 7. オプションのオペレーティングシステムサービス Next: 7.10 anydbm


7.10 anydbm -- DBM 形式のデータベースへの汎用アクセスインタフェース

anydbm は種々の DBM データベース -- (bsddbを使う) dbhash、 gdbm、および dbm-- への汎用インタフェースです。 これらのモジュールがどれもインストールされていない場合、 dumbdbmモジュールの 低速で単純な DBM 実装が使われます。

open( filename[, flag[, mode]])
データベースファイル filename を開き、対応するオブジェクトを 返します。

データベースファイルがすでに存在する場合、whichdb モジュール を使ってファイルタイプが判定され、適切なモジュールが使われます; 既存のデータベースファイルが存在しなかった場合、上に挙げたモジュール中で 最初にインポートすることができたものが使われます。

オプションの flag は 既存のデータベースを読み込み専用で開く 'r'、 既存のデータベースを読み書き用に開く 'w'、 既存のデータベースが存在しない場合には新たに作成する 'c'、および 常に新たにデータベースを作成する 'n' をとることができます。 この引数が指定されない場合、標準の値は 'r' になります。

オプションの mode 引数は、新たにデータベースを作成しなければならない 場合に使われる Unix のファイルモードです。標準の値は 8 進数の 0666 です (この値は現在有効な umask で修飾されます)。

exception error
サポートされているモジュールのどれかによって送出されうる例外が 収められるタプルで、先頭の要素は anydbm.error になって います -- anydbm.error が送出された場合、後者が使われます。

open() によって返されたオブジェクトは辞書とほとんど同じ 同じ機能をサポートします; キーとそれに対応付けられた値を 記憶し、引き出し、削除することができ、has_key() および keys() メソッドを使うことができます。キーおよび値は 常に文字列です。

参考資料:

dbhashモジュール:
BSD db データベースインタフェース。.
dbmモジュール:
標準の Unix データベースインタフェース。.
dumbdbmモジュール:
dbm インタフェースの移植性のある実装。.
gdbmモジュール:
dbm インタフェースに基づいた GNU データベースインタフェース。.
shelveモジュール:
Python dbm インタフェース上に構築された 汎用オブジェクト永続化機構。.
whichdbモジュール:
既存のデータベースがどの形式のデータベースか判定する ユーティリティモジュール。.

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.9 mmap Up: 7. オプションのオペレーティングシステムサービス Next: 7.11 dbhash


7.11 dbhash -- BSD データベースライブラリへの DBM 形式のインタフェース

利用可能な条件: Unix, Windows.

dbhash モジュールでは BSD db ライブラリを使って データベースを開くための関数を提供します。このモジュールは、 DBM 形式 のデータベースへのアクセスを提供する他の Python データベースモジュールの インタフェースをそのまま反映しています。 dbhash を使うには bsddbモジュールが必要です。

このモジュールでは一つの例外と一つの関数を提供しています:

exception error
KeyError 以外のデータベースのエラーで送出されます。 bsddb.error と同じ意味です。

open( path[, flag[, mode]])
データベース db を開き、データベースオブジェクトを返します。 引数 path はデータベースファイルの名前です。

引数 flag は 'r' (標準の値)、 'w'、'c' (データベースが存在しない場合には作成する)、あるいは 'n' (常に新たな空のデータベースを作成する) をとることができます。 BSD db ライブラリがファイルロックをサポートするような プラットフォームでは、ロックを使うよう示すために "l" を追加することができます。

オプションの mode 引数は、新たにデータベースを作成しなければ ならないときにデータベースファイルに設定すべき Unix ファイル権限 ビットを表すために使われます; この値はプロセスの現在の umask 値で マスクされます。

参考資料:

anydbmモジュール:
dbm 形式のデータベースへの汎用インタフェース。.
bsddbモジュール:
BSD db ライブラリへの低レベルインタフェース。.
whichdbモジュール:
既存のデータベースがどの形式のデータベースか判定する ユーティリティモジュール。.

  • 7.11.1 データベースオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.10 anydbm Up: 7. オプションのオペレーティングシステムサービス Next: 7.11.1 データベースオブジェクト


7.11.1 データベースオブジェクト

open() によって返されるデータベースオブジェクトは、 全ての DBM 形式データベースやマップ型オブジェクトで共通のメソッドを 提供します。それら標準のメソッドに加え、dbhash では以下のメソッドが 利用可能です。

first( )
このメソッドと next() メソッドを使って、データベースの全ての キー/値のペアにわたってループ処理を行えます。探索はデータベースの 内部ハッシュ値の順番に行われ、キーの値に順に並んでいるとは限りません。 このメソッドは最初のキーを返します。

last( )
データベース探索における最後のキー/値を返します。逆順探索を開始する 際に使うことができます; previous() を参照してください。

next( )
データベースの順方向探索において、次のよりも後に来るキー/値のペアを 返します。以下のコードはデータベース db に ついて、キー全てを含むリストをメモリ上に生成することなく 全てのキーを出力します。

print db.first()
for i in xrange(1, len(db)):
    print db.next()

previous( )
データベースの逆方向探索において、手前に来るキー/値のペアを 返します。last() と併せて、逆方向の探索に用いられます。

sync( )
このメソッドはディスクにまだ書き込まれていないデータを全て書き込ませます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.11 dbhash Up: 7.11 dbhash Next: 7.12 whichdb


7.12 whichdb -- どのDBMモジュールがデータベースを作ったかを推測する

このモジュールに含まれる唯一の関数はあることを推測します。つまり、与えられたファイルを開くためには、利用可能なデータベースモジュール（dbm、gdbm、dbhash）のどれを用いるべきかということです。

whichdb( filename)
ファイルが読めないか存在しないために開くことが出来ない場合はNone、ファイルの形式を推測できない場合は空の文字列('')、推測できる場合は必要なモジュール名（'dbm'、'gdbm'など）を含む文字列を返します。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.11.1 データベースオブジェクト Up: 7. オプションのオペレーティングシステムサービス Next: 7.13 bsddb


7.13 bsddb -- Berkeley DB ライブラリへのインタフェース

利用可能な条件: Unix, Windows.

bsddb モジュールは Berkeley DB ライブラリへのインタフェース を提供します。ユーザは適当な open 呼び出しを使うことで、 ハッシュ、B-Tree、 またはレコードに基づくデータベースファイルを生成 することができます。bsddb オブジェクトは辞書と大体同じように振る舞い ます。しかし、キー及び値は文字列でなければならないので、 他のオブジェクトをキーとして使ったり、他の種のオブジェクトを記録 したい場合、それらのデータを何らかの方法で直列化しなければなりません。 これには通常 marshal.dumps や pickle.dumps が使われます。

Python 2.3以降のbsddbモジュールは、バージョン 3.1以降のBerkeley DBライブラリのみをサポートしています。(現時点では、3.1から4.1までのバー ジョンでの動作を確認しています。)

参考資料:

http://pybsddb.sourceforge.net/
新しいBerkeley DBインターフ ェースのドキュメントがあります。新しいインターフェースは、Berkeley DB 3と4でsleepycatが提供しているオブジェクト指向インターフェースとほぼ 同じインターフェースとなっています。

http://www.sleepycat.com/
Sleepycat Software は、最新の Berkeley DBライブラリを開発しています。

以下では、従来のbsddbモジュールと互換性のある、古いインターフェースを解 説しています。現在の、Db と DbEnvによるオブジェクト指向的インターフェー スについては上記 pybsddb のURLを参照してください。

警告: このインタフェースは旧式で、Python 2.3.x や以前のバージョンでは スレッド安全ではありません。マルチスレッドからアクセスを行おうとすると、 データの破壊やコアダンプ、デッドロックを引き起こすことがあります。 マルチスレッドやマルチプロセスでデータベースにアクセスする必要がある場合には、 上のリンク先にある、より新しい pybsddb インタフェースを使わねばなりません。

bsddb モジュールでは、適切な形式の Berkeley DB ファイルに アクセスするオブジェクトを生成する以下の関数を定義しています。 各関数の最初の二つの引数は同じです。可搬性のために、ほとんどの インスタンスでは最初の二つの引数だけが使われているはずです。

hashopen( filename[, flag[, mode[, bsize[, ffactor[, nelem[, cachesize[, hash[, lorder]]]]]]]])
filename と名づけられたハッシュ形式のファイルを開きます。 filename に None を指定することで、ディスクに保存する つもりがないファイルを生成することもできます。 オプションの flag には、ファイルを開くためのモードを指定します。 このモードは "r" (読み出し専用、デフォルト)、 "w" (読み書き)。 "c" (読み書き - 必要ならファイルを生成)、または "n" (読み書き - ファイル長を 0 に切り詰め)、にすることが できます。他の引数はほとんど使われることはなく、下位レベルの dbopen() 関数に渡されるだけです。他の引数の使い方 およびその解釈については Berkeley DB のドキュメントを読んで下さい。

btopen( filename[, flag[, mode[, btflags[, cachesize[, maxkeypage[, minkeypage[, psize[, lorder]]]]]]]])
filename と名づけられた B-Tree 形式のファイルを開きます。 filename に None を指定することで、ディスクに保存する つもりがないファイルを生成することもできます。 オプションの flag には、ファイルを開くためのモードを指定します。 このモードは "r" (読み出し専用、デフォルト)、 "w" (読み書き)、 "c" (読み書き - 必要ならファイルを生成)、または "n" (読み書き - ファイル長を 0 に切り詰め)、にすることが できます。他の引数はほとんど使われることはなく、下位レベルの dbopen() 関数に渡されるだけです。他の引数の使い方 およびその解釈については Berkeley DB のドキュメントを読んで下さい。

rnopen( filename[, flag[, mode[, rnflags[, cachesize[, psize[, lorder[, reclen[, bval[, bfname]]]]]]]]])
filename と名づけられた DB レコード形式のファイルを開きます、 filename に None を指定することで、ディスクに保存する つもりがないファイルを生成することもできます、 オプションの flag には、ファイルを開くためのモードを指定します、 このモードは "r" (読み出し専用, デフォルト), "w" (読み書き)、 "c" (読み書き - 必要ならファイルを生成)、または "n" (読み書き - ファイル長を 0 に切り詰め)、にすることが できます。他の引数はほとんど使われることはなく、下位レベルの dbopen() 関数に渡されるだけです、他の引数の使い方 およびその解釈については Berkeley DB のドキュメントを読んで下さい。

参考資料:

dbhashモジュール:
bsddb への DBM 形式のインタフェース.

注意: 2.3以降のUnix版Pythonには、bsddb185モジュールが存在する場合があ ります。このモジュールは古いBerkeley DB 1.85データベースライブラリを持つ システムをサポートするためだけに存在しています。新規に開発する コードでは、bsddb185を直接使用しないで下さい。

  • 7.13.1 ハッシュ、BTree、およびレコードオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.12 whichdb Up: 7. オプションのオペレーティングシステムサービス Next: 7.13.1 ハッシュ、BTree、およびレコードオブジェクト


7.13.1 ハッシュ、BTree、およびレコードオブジェクト

インスタンス化したハッシュ、B-Tree, およびレコードオブジェクトは 辞書型と同じメソッドをサポートするようになります。加えて、以下に 列挙したメソッドもサポートします。 バージョン2.3.1 以降で変更された 仕様: マップ型メソッドを追加しました

close( )
データベースの背後にあるファイルを閉じます。オブジェクトはアクセスできなく なります。これらのオブジェクトには oepn メソッドがないため、 再度ファイルを開くためには、新たな bsddb モジュールを開く 関数を呼び出さなくてはなりません。

keys( )
DB ファイルに収められているキーからなるリストを返します。リスト内の キーの順番は決まっておらず、あてにはなりません。特に、異なるファイル 形式の DB 間では返されるリストの順番が異なります。

has_key( key)
引数 key が DB ファイルにキーとして含まれている場合 1 を返します。

set_location( key)
カーソルを key で示される要素に移動し、キー及び値からなる タプルを返します。(bopen を使って開かれる) B-Tree データベースでは、key が実際にはデータベース内に存在しなかった 場合、カーソルは並び順が key の次に来るような要素を指し、 その場所のキー及び値が返されます。 他のデータベースでは、データベース中に key が見つからなかった 場合 KeyError が送出されます。

first( )
カーソルを DB ファイルの最初の要素に設定し、その要素を返します。 B-Tree データベースの場合を除き、ファイル中のキーの順番は決まって いません。

next( )
カーソルを DB ファイルの次の要素に設定し、その要素を返します。 B-Tree データベースの場合を除き、ファイル中のキーの順番は決まって いません。

previous( )
カーソルを DB ファイルの直前の要素に設定し、その要素を返します。 B-Tree データベースの場合を除き、ファイル中のキーの順番は決まって いません。 (hashopen() で開かれるような) ハッシュ表データベース ではサポートされていません。

last( )
カーソルを DB ファイルの最後の要素に設定し、その要素を返します。 ファイル中のキーの順番は決まっていません。 (hashopen() で開かれるような) ハッシュ表データベース ではサポートされていません。

sync( )
ディスク上のファイルをデータベースに同期させます。

以下はプログラム例です:

>>> import bsddb
>>> db = bsddb.btopen('/tmp/spam.db', 'c')
>>> for i in range(10): db['%d'%i] = '%d'% (i*i)
...
>>> db['3']
'9'
>>> db.keys()
['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
>>> db.first()
('0', '0')
>>> db.next()
('1', '1')
>>> db.last()
('9', '81')
>>> db.set_location('2')
('2', '4')
>>> db.previous()
('1', '1')
>>> for k, v in db.iteritems():
...     print k, v
0 0
1 1
2 4
3 9
4 16
5 25
6 36
7 49
8 64
9 81
>>> '8' in db
True
>>> db.sync()
0
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.13 bsddb Up: 7.13 bsddb Next: 7.14 dumbdbm


7.14 dumbdbm -- 可搬性のある DBM 実装

注意: dumbdbm モジュールは、 anydbm が安定なモジュールを 他に見つけることができなかった際の最後の手段とされています。 dumbdbm モジュールは速度を重視して書かれているわけではなく、 他のデータベースモジュールのように重い使い方をするためのものでは ありません。

dumbdbm モジュールは永続性辞書に類似したインタフェースを 提供し、全て Python で書かれています。 gdbm や bsddb といったモジュールと異なり、 外部ライブラリは必要ありません。他の永続性マップ型のように、 キーおよび値は常に文字列でなければなりません。

このモジュールでは以下の内容を定義してします:

exception error
I/O エラーのような dumbdbm 特有のエラーの際に送出されます。 不正なキーを指定したときのような、一般的な対応付けエラーの際には KeyError が送出されます。

open( filename[, flag[, mode]])
dumbdbm データベースを開き、 dubmdbm オブジェクトを返します。 filename 引数はデータベースファイル名の雛型 (特定の拡張子を もたないもの) です。dumbdbm データベースが生成される際、 .dat および .dir の拡張子を持ったファイルが生成されます。

オプションの flag 引数は現状では無視されます; データベースは 常に更新のために開かれ、存在しない場合には新たに作成されます。

オプションの mode 引数は Unix におけるファイルのモードで、 データベースを作成する際に使われます。デフォルトでは 8 進コード の 0666 になっています (umask によって修正を受けます)。 バージョン2.2 以降で変更された 仕様: mode 引数は以前のバージョンでは無視されます

参考資料:

anydbmモジュール:
dbm 形式のデータベースに対する汎用インタフェース。.
dbmモジュール:
DBM/NDBM ライブラリに対する同様のインタフェース。.
gdbmモジュール:
GNU GDBM ライブラリに対する同様のインタフェース。.
shelveモジュール:
非文字列データを記録する永続化モジュール。.
whichdbモジュール:
既存のデータベースの形式を判定するために使われるユーティリティモジュール。.

  • 7.14.1 Dumbdbm オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.13.1 ハッシュ、BTree、およびレコードオブジェクト Up: 7. オプションのオペレーティングシステムサービス Next: 7.14.1 Dumbdbm オブジェクト


7.14.1 Dumbdbm オブジェクト

UserDict.DictMixin クラスで提供されているメソッドに加え、 dumbdbm オブジェクトでは以下のメソッドを提供しています。

sync( )
ディスク上の辞書とデータファイルを同期します。このメソッドは Shelve オブジェクトの sync メソッドから 呼び出されます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.14 dumbdbm Up: 7.14 dumbdbm Next: 7.15 zlib


7.15 zlib -- gzip 互換の圧縮

このモジュールでは、データ圧縮を必要とするアプリケーションが zlib ライブラリ を使って圧縮および解凍を行えるようにします。 zlib ライブラリ自体の Web ホームページは http://www.gzip.org/zlib/にある。2000 年 9 月の時点での最新バージョンは 1.1.3 です。可能なら これ以降のバージョンを使うのがよいでしょう。 以前のバージョンの zlib ライブラリにはこの Python モジュールと互換性 のない部分があることが知られています。

このモジュールで利用可能な例外と関数を以下に示します:

exception error
圧縮および解凍時のエラーによって送出される例外。

adler32( string[, value])
string のAdler-32 チェックサムを計算します。 （Adler-32 チェックサムは、おおむね CRC32 と同等の信頼性を持ちながら はるかに高速に計算することができます。） value が与えられていれば、value はチェックサム計算の 初期値として使われます。それ以外の場合には固定のデフォルト値が 使われます。この機能によって、複数の入力文字列を結合したデータ全体 にわたり、通しのチェックサムを計算することができます。 このアルゴリズムは暗号法論的には強力とはいえないので、認証やデジタル 署名などに用いるべきではありません。このアルゴリズムはチェックサム アルゴリズムとして用いるために設計されたものなので、汎用的な ハッシュアルゴリズムには向きません。

compress( string[, level])
string で与えられた文字列を圧縮し、圧縮されたデータを含む 文字列を返します。 level は 1 から 9 までの 整数をとる値で、圧縮のレベルを制御します。 1 は最も高速 で最小限の圧縮を行います。9 はもっとも低速になりますが 最大限の圧縮を行います。デフォルトの値は 6 です。 圧縮時に何らかのエラーが発生した場合、 error 例外を 送出します。

compressobj( [level])
一度にメモリ上に置くことができないようなデータストリームを圧縮 するための圧縮オブジェクトを返します。level は 1 から 9 までの整数で、圧縮レベルを制御します。1 は もっとも高速で最小限の圧縮を、9 はもっとも低速になりますが 最大限の圧縮を行います。デフォルトの値は 6 です。

crc32( string[, value])
string の CRC (Cyclic Redundancy Check, 巡回符号方式) チェックサムを計算します。value が与えられていれば、チェックサム 計算の初期値として使われます。与えられていなければデフォルトの初期値 が使われます。value を与えることで、複数の入力文字列を結合した データ全体にわたり、通しのチェックサムを計算することができます。 このアルゴリズムは暗号法論的には強力ではなく、認証やデジタル署名 に用いるべきではありません。アルゴリズムはチェックサムアルゴリズムと して設計されてえいるので、汎用のハッシュアルゴリズムには向きません。

decompress( string[, wbits[, bufsize]])
string 内のデータを解凍して、解凍されたデータを含む文字列を 返します。wbits パラメタはウィンドウバッファの大きさを制御 します。 bufsize が与えられていれば、出力バッファの書記サイズ として使われます。解凍処理に何らかのエラーが生じた場合、 error 例外を送出します。

wbits の絶対値は、データを圧縮する際に用いられるヒストリ バッファのサイズ (ウィンドウサイズ) に対し、 2 を底とする対数を とったものです。最近のほとんどのバージョンの zlib ライブラリを 使っているなら、wbits の絶対値は 8 から 15 とするべきです。 より大きな値はより良好な圧縮につながりますが、より多くのメモリ を必要とします。デフォルトの値は 15 です。wbits の値が 負の場合、標準的な gzip ヘッダを出力しません。 これは zlib ライブラリの非公開仕様であり、unzip の 圧縮ファイル形式に対する互換性のためのものです。

bufsize は解凍されたデータを保持するためのバッファサイズの 初期値です。バッファの空きは必要に応じて必要なだけ増加するので、 なれば、必ずしも正確な値を指定する必要はありません。この値の チューニングでできることは、 malloc() が呼ばれる回数を 数回減らすことぐらいです。デフォルトのサイズは 16384 です。

decompressobj( [wbits])
メモリ上に一度に展開できないようなデータストリームを解凍するために 用いられる解凍オブジェクトを返します。wbits パラメタは ウィンドウバッファのサイズを制御します。

圧縮オブジェクトは以下のメソッドをサポートします:

compress( string)
string を圧縮し、圧縮されたデータを含む文字列を返します。この 文字列は少なくとも string に相当します。このデータは以前に呼んだ compress() が返した出力と結合することができます。入力の一部は 以後の処理のために内部バッファに保存されることもあります。

flush( [mode])
未処理の入力データが処理され、この未処理部分を圧縮したデータを含む 文字列が返されます。mode は定数 Z_SYNC_FLUSH 、 Z_FULL_FLUSH 、または Z_FINISH のいずれかをとり、 デフォルト値は Z_FINISH です。Z_SYNC_FLUSH および Z_FULL_FLUSH ではこれ以後にもデータ文字列を圧縮できる モードで、解凍時の部分的なエラーリカバリを可能にします。一方、 Z_FINISH は圧縮ストリームを閉じ、これ以後のデータの圧縮 を禁止します。 mode に Z_FINISH を設定して flush() メソッドを呼び出した後は、compress() メソッドを再び呼ぶべきではありません。唯一の現実的な操作はこの オブジェクトを削除することだけです。

解凍オブジェクトは以下のメソッドと 2 つの属性をサポートします:

unused_data
圧縮データの末尾までのバイト列が入った文字列です。 すなわち、この値は圧縮データの入っているバイト列の最後の文字 までが読み出せるかぎり "" となります。入力文字列全てが圧縮 データを含んでいた場合、この属性は "" 、すなわち空文字列に なります。

圧縮データ文字列がどこで終了しているかを決定する唯一の 方法は、実際にそれを解凍することです。つまり、大きなファイル の一部分に圧縮データが含まれているときに、その末端を調べるために は、データをファイルから読み出し、空でない文字列を後ろに続けて、 unused_data が空文字列でなくなるまで、解凍オブジェクトの decompress メソッドに入力しつづけるしかありません。

unconsumed_tail
解凍されたデータを収めるバッファの長さ制限を超えたために、最も最近の decompress 呼び出しで処理しきれなかったデータを含む文字列です。 このデータはまだ zlib 側からは見えていないので、正しい解凍出力を得るには 以降の decompress メソッド呼び出しに (場合によっては後続の データが追加された) データを差し戻さなければなりません。

decompress( string)
[max_length] string を解凍し、少なくとも string の一部分に対応する 解凍されたデータを含む文字列を返します。このデータは以前に decompress() メソッドを呼んだ時に返された出力と結合する ことができます。入力データの一部分が以後の処理のために内部バッファに 保存されることもあります。

オプションパラメタ max_length が与えられると、返される解凍データ の長さが max_length 以下に制限されます。このことは入力した圧縮 データの全てが処理されるとは限らないことを意味し、処理されなかった データは unconsumed_tail 属性に保存されます。 解凍処理を継続したいならば、この保存されたデータを以降の decompress() 呼び出しに渡さなくてはなりません。 max_length が与えられなかった場合、全ての入力が解凍され、 unconsumed_tail 属性は空文字列になります。

flush( )
未処理の入力データを全て処理し、最終的に圧縮されなかった残りの 出力文字列を返します。 flush() を呼んだ後、 decompress() を再度呼ぶべきではありません。このときできる唯一現実的な操作は オブジェクトの削除だけです。

参考資料:

gzipモジュール:
Reading and writing gzip-format files.
http://www.gzip.org/zlib/
The zlib library home page.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.14.1 Dumbdbm オブジェクト Up: 7. オプションのオペレーティングシステムサービス Next: 7.16 gzip


7.16 gzip -- gzip ファイルのサポート

zlib モジュールで提供されているデータ圧縮は、GNU の 圧縮プログラム gzip のものと互換性があります。 そこで、gzip モジュールでは、gzip 形式の ファイルを読み書きするための GzipFile クラスを提供します。 このクラスのオブジェクトは自動的にデータを圧縮または解凍するので、 通常のファイルオブジェクトのように見えます。 gzip や gunzip プログラムで解凍できる、 compress や pack による他の形式の圧縮ファイルは このモジュールではサポートされていないので注意してください。

このモジュールでは以下の項目を定義しています:

class GzipFile( [filename[, mode[, compresslevel[, fileobj]]]])
GzipFile クラスのコンストラクタです。GzipFile オブジェクト は readinto() と truncate() メソッドを除くほとんどの ファイルオブジェクトのメソッドをシミュレートします。 少なくとも fileobj および filename は有効な値でなければ なりません。

クラスの新しいインスタンスは、fileobj に基づいて作成 されます。fileobj は通常のファイル、StringIO オブジェクト、そしてその他ファイルをシミュレートできる オブジェクトでかまいません。値はデフォルトでは None で、 ファイルオブジェクトを生成するために filename を開きます。

gzip ファイルヘッダ中には、ファイルが解凍されたときの元の ファイル名を収めることができますが、fileobj が None でない場合、引数 filename がファイル名として認識できる文字列 であれば、filename はファイルヘッダに収めるためだけに使われ ます。そうでない場合（この値はデフォルトでは空文字列です）、 元のファイル名はヘッダに収められません。

mode 引数は、ファイルを読み出すのか、書き込むのかによって、 'r', 'rb', 'a', 'ab', 'w', そして 'wb', のいずれかになります。fileobj の ファイルモードが認識可能な場合、mode はデフォルトで fileobj のモードと同じになります。そうでない場合、 デフォルトのモードは 'rb' です。'b' フラグがついて いなくても、ファイルがバイナリモードで開かれることを保証するために 'b' フラグが追加されます。これはプラットフォーム間での移植性の ためです。

compresslevel 引数は 1 から 9 までの整数で、 圧縮のレベルを制御します。1 は最も高速で最小限の圧縮しか 行いません。9 は最も低速ですが、最大限の圧縮を行います。 デフォルトの値は 9 です。

圧縮したデータの後ろにさらに何か追記したい場合もあるので、 GzipFile オブジェクトの close() メソッド呼び出し は fileobj をクローズしません。この機能によって、書き 込みのためにオープンした StringIO オブジェクトを fileobj として渡し、（GzipFile を close() した後に） StringIO オブジェクトの getvalue() メソッドを使って 書き込んだデータの入っているメモリバッファを取得することができます。

open( filename[, mode[, compresslevel]])
GzipFile(filename, mode, compresslevel) の短縮形です。 引数 filename は必須です。デフォルトで mode は'rb' に、 compresslevel は 9 に設定されています。

参考資料:

zlibモジュール:
gzip ファイル形式のサポートを行うために必要な 基本ライブラリモジュール。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.15 zlib Up: 7. オプションのオペレーティングシステムサービス Next: 7.17 bz2


7.17 bz2 -- bzip2 互換の圧縮ライブラリ

バージョン2.3 以降で新規追加された 仕様です。

このモジュールでは bz2 圧縮ライブラリのためのわかりやすいインタフェースを 提供します。モジュールでは完全なファイルインタフェース、データを一括 して圧縮（解凍）する関数、データを逐次的に圧縮（解凍）するためのクラス 型を実装しています。

bz2 モジュールで提供されている機能を以下にまとめます:

  • BZ2File クラスは、readline(), readlines(), writelines(), seek(), 等を含む完全な ファイルインタフェースを実装します。
  • BZ2File クラスは seek() をエミュレーションで サポートします。
  • BZ2File クラスは広範囲の改行文字バリエーションを サポートします。
  • BZ2File クラスはファイルオブジェクトで言うところの、先読み アルゴリズムを用いた行単位の反復処理機能を提供します。
  • 逐次的圧縮（解凍）が BZ2Compressor および BZ2Decompressor クラスでサポートされています。
  • 一括圧縮（解凍）が関数 compress() および decompress() でサポートされています。
  • 個別のロックメカニズムによってスレッド安全性を持っています。
  • 埋め込みドキュメントが完備しています。

  • 7.17.1 ファイルの圧縮（解凍）
  • 7.17.2 逐次的な圧縮（解凍）
  • 7.17.3 一括圧縮（解凍）
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.16 gzip Up: 7. オプションのオペレーティングシステムサービス Next: 7.17.1 ファイルの圧縮（解凍）


7.17.1 ファイルの圧縮（解凍）

圧縮ファイルの操作は BZ2File クラスで提供されています。

class BZ2File( filename[, mode[, buffering[, compresslevel]]])
bz2 ファイルを開きます。ファイルのモードは 'r' または 'w' で、それぞれ読み出しと書き込みに対応します。 書き出し用に開いた場合、ファイルが存在しないなら新しくファイルが 作成され、そうでない場合ファイルは切り詰められます。 buffering パラメタが与えられた場合、0 はバッファリング を行わないことを表し、それよりも大きい値はバッファサイズの指定値 となります。デフォルトでは 0 です。compresslevel が与えられている場合、この値は 1 から 9 までの 整数値でなければなりません。デフォルトの値は 9 です。 ファイルへの入力に広範囲の改行文字バリエーションをサポートさせたい 場合は "U" をファイルモードに追加します。 入力ファイルの行末はどれも、Pythonからは "\n" として見えます。 また、また、開かれているファイルオブジェクトは newlines 属性 を持ち、None (まだ改行文字を読み込んでいない時), '\r', '\n', '\r\n' または全ての改行文字バリエーション を含むタプルになります。広範囲の改行文字サポートは読み込みだけで 利用可能です。生成されるインスタンスは通常のファイルインスタンスと 同様の反復操作をサポートします。

close( )
ファイルを閉じます。オブジェクトのデータ属性 closed を真に します。閉じられたファイルは以後の入出力操作に用いることができません。 close() 自体はエラーを引き起こすことなく何度も呼び出すことが できます。

read( [size])
最大で size バイトの解凍されたデータを読み出し、文字列として 返します。size 引数が負であるか省略された場合、EOF に たどり着くまで読み込みます。

readline( [size])
ファイルから次の 1 行を読み出し、改行文字も含めて文字列を返します。 負でない size 値は、返される文字列の最大バイト長を制限します (その場合不完全な行が返されることもあります) EOF の時には空文字列 が返されます。

readlines( [size])
ファイルから読み取った行文字列の集合からなるリストを返します。 オプション引数 size が与えられていれば、返される行文字列 全体のバイト数長さの大体の上限が指定されます。

xreadlines( )
前のバージョンとの互換性のために用意されています。 BZ2File オブジェクトはかつて xreadlines モジュールで提供されて いたパフォーマンス最適化を含んでいます。
リリース 2.3 以降で撤廃された仕様です。 このメソッドは file オブジェクトの同名の メソッドとの互換性のために用意されていますが、現在は推奨されない メソッドです。代りに for line in file を使ってください。

seek( offset[, whence])
ファイル位置を移動します。 引数 offset はバイト数での値です。 オプション引数 whence はデフォルトで 0 (ファイルの 先頭からのオフセットであり、offset >= 0 となるはず) に設定されて います。他の値は 1 (現在のファイル位置からの相対位置であり、 正負どちらの値もとり得ます)、および 2 (ファイルの終末端からの 相対位置であり、通常負の値になりますが、多くのプラットフォームで ファイルの終末端を越えて seek を行うことができます)。

bz2 ファイルの seek はエミュレーションであり、パラメタの設定によっては 処理が非常に低速になるかもしれないので注意してください。

tell( )
現在のファイル位置を整数（long 整数になるかもしれません）で返します。

write( data)
ファイルに文字列 data を書き込みます。バッファリングのため、 ディスク上のファイルに書き込まれたデータを反映させるには close() が必要になるかもしれないので注意してください。

writelines( sequence_of_strings)
複数の文字列からなる配列をファイルに書き込みます。それぞれの 文字列を書き込む際にさらに改行文字が追加されることはありません。 配列は文字列を反復して取り出すことができる任意のオブジェクト でもかまいません。この操作はそれぞれの文字列を write() を呼んで 書き込むのと同等の操作です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.17 bz2 Up: 7.17 bz2 Next: 7.17.2 逐次的な圧縮（解凍）


7.17.2 逐次的な圧縮（解凍）

逐次的な圧縮および解凍は BZ2Compressor および BZ2Decompressor クラスを用いて行われます。

class BZ2Compressor( [compresslevel])
新しい圧縮オブジェクトを作成します。このオブジェクトはデータを逐次的に 圧縮できます。一括してデータを圧縮したいのなら、compress() 関数を代りに使ってください。compresslevel パラメタを与える場合、 この値は 1 and 9 の間の整数でなければなりません。 デフォルトの値は 9 です。

compress( data)
圧縮オブジェクトに追加のデータを入力します。データが圧縮された チャンクを生成することができた場合にはチャンクを返します。 圧縮データの入力を終えた後は 圧縮処理を終えるために flush() を呼んでください。 内部バッファに残っている未処理のデータが返されます。

flush( )
圧縮処理を終え、内部バッファに残されているデータを返します。 メソッドを呼んだ後は、この圧縮オブジェクトを使うべきではありません。

class BZ2Decompressor( )
新しい解凍オブジェクトを生成します。このオブジェクトは逐次的にデータ を解凍できます。一括してデータを解凍したいのなら、 decompress() 関数を代りに使ってください。

decompress( data)
解凍オブジェクトに追加のデータを入力します。可能な限り、データが 解凍されたチャンクを生成することができた場合にはチャンクを 返します。ストリームの末端に到達した後に解凍処理を行おうと した場合には、例外 EOFError が送出されます。 ストリームの終末端の後ろに何らかのデータがあった場合には、解凍 操作からは無視され、このデータはオブジェクトの unused_data 属性に収められます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.17.1 ファイルの圧縮（解凍） Up: 7.17 bz2 Next: 7.17.3 一括圧縮（解凍）


7.17.3 一括圧縮（解凍）

一括での圧縮および解凍を行うための関数、compress() および decompress() が提供されています。

compress( data[, compresslevel])
data を一括して圧縮します。データを逐次的に圧縮したいなら、 BZ2Compressor を代りに使ってください。もし compresslevel パラメタを与えるなら、この値は 1 から 9 をとらなくては なりません。デフォルトの値は 9 です。

decompress( data)
data を一括して解凍します。データを逐次的に解凍したいなら、 BZ2Decompressor を代りに使ってください。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.17.2 逐次的な圧縮（解凍） Up: 7.17 bz2 Next: 7.18 zipfile


7.18 zipfile -- ZIP アーカイブの処理

バージョン1.6 以降で新規追加された 仕様です。

ZIP は一般によく知られているアーカイブ （書庫化）および圧縮の標準ファイルフォーマットです。 このモジュールでは ZIP 形式のファイルの作成、読み書き、ファイルの 作成、書庫内のファイルリスト読み出しを行うためのツールを提供します。 より高度な使い方でこのモジュールを利用したいなら、 PKZIP Application Note に定義されている ZIP ファイルフォーマットを理解することが必要に なるでしょう。

このモジュールは現在のところ、コメントを追記した ZIP ファイルや マルチディスク ZIP ファイルを扱うことはできません。

このモジュールで利用できる属性を以下に示します:

exception error
不備のある ZIP ファイル操作の際に送出されるエラー

class ZipFile
ZIP ファイルの読み書きのためのクラスです。 コンストラクタの詳細については、 ``ZipFile オブジェクト'' (7.18.1 節) を参照してください。

class PyZipFile
Python ライブラリを含む ZIP アーカイブを生成するためのクラスです。

class ZipInfo( [filename[, date_time]])
アーカイブ中のメンバに関する情報を提供するために用いられるクラスです。 このクラスのインスタンスは ZipFile オブジェクトの getinfo() および infolist() メソッドによって返され ます。zipfile モジュールを利用するほとんどのユーザはこの オブジェクトを自ら生成する必要はなく、モジュールが生成して返す オブジェクトを利用するだけでしょう。 filename はアーカイブメンバの完全な名前で、 date_time は ファイルの最終更新時刻を記述する、 6 つの フィールドからなるタプルでなくてはなりません。各フィールドについては 7.18.3, ``ZipInfo オブジェクト'' 節を参照してください。

is_zipfile( filename)
filename が正しいマジックナンバをもつ ZIP ファイルのときに True を返し、そうでない場合 False を返します。この モジュールは現在のところ、コメントを追記した ZIP ファイルを扱うこと ができません。

ZIP_STORED
アーカイブメンバが圧縮されていないことを表す数値定数です。

ZIP_DEFLATED
通常の ZIP 圧縮手法を表す数値定数。ZIP 圧縮は zlib モジュールを必要 とします。現在のところ他の圧縮手法はサポートされていません。

参考資料:

PKZIP Application Note
ZIP ファイル形式およびアルゴリズムを作成した Phil Katz によるドキュメント。

Info-ZIP Home Page
Info-ZIP プロジェクトによる ZIP アーカイブプログラム及びプログラム開発ライブラリに関する情報。

  • 7.18.1 ZipFile オブジェクト
  • 7.18.2 PyZipFile オブジェクト
  • 7.18.3 ZipInfo オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.17.3 一括圧縮（解凍） Up: 7. オプションのオペレーティングシステムサービス Next: 7.18.1 ZipFile オブジェクト


7.18.1 ZipFile オブジェクト

class ZipFile( file[, mode[, compression]])
ZIP ファイルを開きます。file はファイルへのパス名 (文字列) またはファイルのように振舞うオブジェクトのどちらでもかまいません。 mode パラメタは、既存のファイルを読むためには 'r'、 既存のファイルを切り詰めたり新しいファイルに書き込むためには 'w'、 追記を行うためには 'a' でなくてはなりません。 mode が 'a' で file が既存の ZIP ファイルを 参照している場合、追加するファイルは既存のファイル中の ZIP アーカイブ に追加されます。file が ZIP を参照していない場合、新しい ZIP アーカイブが生成され、既存のファイルの末尾に追加されます。このことは、 ある ZIP ファイルを他のファイル、例えば python.exe に

cat myzip.zip >> python.exe

として追加することができ、少なくとも WinZip がこのような ファイルを読めることを意味します。 compression はアーカイブを書き出すときの ZIP 圧縮法で、 ZIP_STORED または ZIP_DEFLATED でなくては なりません。不正な値を指定すると RuntimeError が送出 されます。また、ZIP_DEFLATED 定数が指定されているのに zlib を利用することができない場合、 RuntimeError が送出されます。デフォルト値は ZIP_STORED です。

close( )
アーカイブファイルを閉じます。close() は プログラムを終了する前に必ず呼び出さなければなりません。 さもないとアーカイブ上の重要なレコードが書き込まれません。

getinfo( name)
アーカイブメンバ name に関する情報を持つ ZipInfo オブジェクトを返します。

infolist( )
アーカイブに含まれる各メンバの ZipInfo オブジェクトからなる リストを返します。既存のアーカイブファイルを開いている場合、 リストの順番は実際の ZIP ファイル中のメンバの順番と同じになります。

namelist( )
アーカイブメンバの名前のリストを返します。

printdir( )
アーカイブの目次を sys.stdout に出力します。

read( name)
アーカイブ中のファイルの大きさをバイト数で返します。アーカイブは 読み込みまたは追記モードで開かれていなくてはなりません。

testzip( )
アーカイブ中の全てのファイルを読み、CRC チェックサムが正常か調べます。 アーカイブ中で不正なチェックサムをもつ最初のファイルの名前を返します。 不正なファイルがなければ None を返します。

write( filename[, arcname[, compress_type]])
ファイル名 filename のファイルに、 arcname の アーカイブ名 (デフォルトでは filename と同じになります) で アーカイブを書き出します。 compress_type が与えられていれば、コンストラクタを使って 生成したときに与えた compression パラメタは上書きされます。 アーカイブのモードは 'w' または 'a' でなくてはなりません。

writestr( zinfo_or_arcname, bytes)
文字列 bytesをアーカイブに書き込みます。zinfo_or_arcname はアーカイブ中で指定するファイル名か、またはZipInfo インスタンス を指定します。zinfo_or_arcnameにZipInfo インスタンスを指定 する場合、zinfoインスタンスには少なくともファイル名、日付および時刻 を指定しなければなりません。ファイル名を指定した場合、日付と時刻には現在の 日付と時間が設定されます。アーカイブはモード 'w' または 'a' で開かれていなければなりません。

以下のデータ属性も利用することができます。

debug
使用するデバッグ出力レベル。この属性は 0 (デフォルト、何も出力しない) から 3 (最も多くデバッグ情報を 出力する) までの値に設定することができます。デバッグ情報は sys.stdout に出力されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.18 zipfile Up: 7.18 zipfile Next: 7.18.2 PyZipFile オブジェクト


7.18.2 PyZipFile オブジェクト

PyZipFile コンストラクタは ZipFile コンストラクタ と同じパラメタを必要とします。インスタンスは ZipFile の メソッドの他に、追加のメソッドを一つ持ちます。

writepy( pathname[, basename])
*.py ファイルを探し、*.py ファイルに対応するファイルを アーカイブに追加します。 対応するファイルとは、もしあれば *.pyo であり、そうでなければ *.pyc で、必要に応じて *.py からコンパイルします。 もし pathname がファイルなら、ファイル名は .py で終わっていな ければなりません。また、(*.py に対応する *.py[co]) ファイルはアーカイブのトップレベルに (パス情報なしで) 追加されます。 もし pathname がディレクトリで、ディレクトリがパッケージディレクトリ でないなら、全ての *.py[co] ファイルはトップレベルに追加され ます。もしディレクトリがパッケージディレクトリなら、全ての *.py[co] ファイルはパッケージ名の名前をもつファイルパスの 下に追加されます。サブディレクトリがパッケージディレクトリなら、 それらは再帰的に追加されます basename はクラス内部での呼び出し に使用するためのものです。

writepy() メソッドは以下のようなファイル名を持ったアーカイブ を生成します。

    string.pyc                    # トップレベル名
    test/__init__.pyc             # パッケージディレクトリ
    test/testall.pyc              # test.testall モジュール
    test/bogus/__init__.pyc       # サブパッケージディレクトリ
    test/bogus/myfile.pyc         # test.bogus.myfile サブモジュール

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.18.1 ZipFile オブジェクト Up: 7.18 zipfile Next: 7.18.3 ZipInfo オブジェクト


7.18.3 ZipInfo オブジェクト

ZipFile オブジェクトの getinfo() および infolist() メソッドは ZipInfo クラスのインスタンス を返します。それぞれのインスタンスオブジェクトは ZIP アーカイブの 一個のメンバについての情報を保持しています。

インスタンスは以下の属性を持ちます:

filename
アーカイブ中のファイルの名前。

date_time
アーカイブメンバの最終更新日時。この属性は6つの値からなるタプルです。:

Index | Value
0 | 西暦年
1 | 月 (1 から始まる)
2 | 日 (1 から始まる)
3 | 時 (0 から始まる)
4 | 分 (0 から始まる)
5 | 秒 (0 から始まる)

compress_type
アーカイブメンバの圧縮形式。

comment
各アーカイブメンバに対するコメント。

extra
拡張フィールドデータ。 この文字列データに含まれているデータの内部構成については、 PKZIP Application Note でコメントされています。

create_system
ZIP アーカイブを作成したシステムを記述する文字列。

create_version
このアーカイブを作成した PKZIP のバージョン。

extract_version
このアーカイブを展開する際に必要な PKZIP のバージョン。

reserved
予約領域。ゼロでなくてはなりません。

flag_bits
ZIP フラグビット列。

volume
ファイルヘッダのボリュームナンバ。

internal_attr
内部属性。

external_attr
外部ファイル属性。

header_offset
  ファイルヘッダへのバイト数で表したオフセット。

file_offset
ファイルデータの開始点へのバイト数で表したオフセット。

CRC
圧縮前のファイルの CRC-32 チェックサム。

compress_size
圧縮後のデータのサイズ。

file_size
圧縮前のファイルのサイズ。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.18.2 PyZipFile オブジェクト Up: 7.18 zipfile Next: 7.19 tarfile


7.19 tarfile -- tar アーカイブファイルを読み書きする

バージョン2.3 以降で新規追加された 仕様です。

tarfile モジュールは、tar アーカイブを読んで作成することができるようにします。 いくつかの事実と外観：

  • gzip と bzip2 で圧縮されたアーカイブを読み書きします。
  • POSIX 1003.1-1990 準拠あるいは GNU tar 互換のアーカイブを作成します。
  • GNU tar 拡張機能 長い名前、 longlink および sparse を読みます。
  • GNU tar 拡張機能を使って、無制限長さのパス名を保存します。
  • ディレクトリ、普通のファイル、ハードリンク、シンボリックリンク、fifo、 キャラクタデバイスおよびブロックデバイスを処理します。また、タイムスタンプ、 アクセス許可およびオーナーのようなファイル情報の取得および保存が可能です。
  • テープデバイスを取り扱うことができます。

open( [name[, mode [, fileobj[, bufsize]]]])
パス名 nameに TarFile オブジェクトを返します。 TarFile オブジェクトに関する詳細な情報については、 TarFile オブジェクト (セクション 7.19.1)を見て下さい。

mode has to be a string of the form 'filemode[:compression]', it defaults to 'r'. Here is a full list of mode combinations: mode は、'ファイルモード[:圧縮]'の形の文字列でなければならず、 そのデフォールトは 'r'です。以下にモードの組み合わせの完全な一覧を示します。

mode | 動作
'r' | 透過な圧縮つきで読み込むためにオープンします(推奨)。
'r:' | 圧縮なしで排他的に読み込むためにオープンします。
'r:gz' | gzip 圧縮で読み込むためにオープンします。
'r:bz2' | bzip2 圧縮で読み込むためにオープンします。
'a' または 'a:' | 圧縮なしで追加するためにオープンします。
'w' または 'w:' | 非圧縮で書き込むためにオープンします。
'w:gz' | gzip 圧縮で書き込むためにオープンします。
'w:bz2' | bzip2 圧縮で書き込むためにオープンします。

'a:gz' あるいは 'a:bz2'は可能ではないことに注意して下さい。 もし modeが、ある(圧縮した)ファイルを読み込み用にオープンするのに、 適していないなら、ReadErrorが発生します。これを防ぐには mode 'r' を使って下さい。もし圧縮メソッドがサポートされていなければ、 CompressionError が発生します。

もし fileobjが指定されていれば、それは nameでオープンされた ファイルオブジェクトの代替として使うことができます。

特別な目的のために、modeの2番目のフォーマット: 'ファイルモード|[圧縮]' があります。open は、そのデータを ブロックのストリームとして処理する TarFile オブジェクトを返します。 ランダムシーキングはそのファイルにはなされません。もし fileobj が与えられていれば、 それは、それぞれ read()、write() メソッドを持つ、任意の オブジェクトで構いません。 bufsize は、ブロックサイズを指定し、デフォールトでは 20 * 512 バイト です。例えば sys.stdin とソケットファイルオブジェクトやテーブデバイスの 組み合わせでは、これを変更して使って下さい。 しかし、そのような TarFile オブジェクトには、ランダムにアクセスされることを 許さないという制限があります、 例 (セクション 7.19.3)を見て下さい。 現在可能なモードは：

mode | 動作
'r|' | 非圧縮 tar ブロックの ストリーム を読み込みにオープンします。
'r|gz' | gzip 圧縮 ストリームを読み込みにオープンします。
'r|bz2' | bzip2 圧縮 ストリーム を読み込みにオープンします。
'w|' | 非圧縮 ストリームを書き込みにオープンします。
'w|gz' | gzip 圧縮 ストリーム を書き込みにオープンします。
'w|bz2' | bzip2 圧縮 ストリームを書き込みにオープンします。

class TarFile
tar アーカイブを読んだり、書いたりするためのクラスです。このクラスを 直接使わないで下さい、その代わりに open() を使った方が良いです。 TarFile オブジェクト (セクション 7.19.1)を見て下さい。

is_tarfile( name)
もし nameが tar アーカイブファイルであれば、Trueを返し、 その tarfile モジュールで読むことができます。

class TarFileCompat( filename[, mode[, compression]])

zipfile-風なインターフェースを持つ tar アーカイブへの 制限されたアクセスのためのクラスです。より詳細については zipfileのドキュメントに当たって下さい。 compression は、以下の定数のどれかでなければなりません：

TAR_PLAIN
非圧縮 tar アーカイブのための定数。
TAR_GZIPPED
gzip圧縮 tar アーカイブのための定数。

exception TarError
すべての tarfile 例外のための基本クラスです。

exception ReadError
tar アーカイブがオープンされた時、tarfile モジュールで操作 できないか、あるいは何か無効であるとき発生します。

exception CompressionError
圧縮方法がサポートされていないか、あるいはデータを正しくデコードできない 時に発生します。

exception StreamError
ストリーム風の TarFile オブジェクトで典型的な制限の ために発生します。

exception ExtractError
extract()を使った時、もしTarFile.errorlevel == 2 の フェータルでない エラーに対してだけ発生します。

参考資料:

zipfileモジュール:
zipfile 標準モジュールのドキュメント。.

GNU tar マニュアル、標準セクション
GNU tar 拡張機能を含む、 tar アーカイブファイルのためのドキュメント。

  • 7.19.1 TarFile オブジェクト
  • 7.19.2 TarInfo オブジェクト
  • 7.19.3 例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.18.3 ZipInfo オブジェクト Up: 7. オプションのオペレーティングシステムサービス Next: 7.19.1 TarFile オブジェクト


7.19.1 TarFile オブジェクト

TarFile オブジェクトは、tar アーカイブへのインターフェースを提供します。 tar アーカイブは一連のブロックです。アーカイブメンバー(保存されたファイル)は、 ヘッダーブロックとそれに続くデータブロックから構成されています。ある tar アーカイブに ファイルを何回も保存することができます。各アーカイブメンバーは、 TarInfo オブジェクトによって表わされます、詳細については TarInfo オブジェクト (セクション 7.19.2)を見て下さい。

class TarFile( [name [, mode[, fileobj]]])
(非圧縮の) tar アーカイブ nameをオープンします。 mode は、既存のアーカイブから読み込むには 'r' 、 既存のファイルにデータを追加するには 'a'、あるいは既存のファイルを 上書きして新しいファイルを作成するには 'w' のどれかです。mode のデフォールトは 'r'です。

もし fileobjが与えられていれば、それを使ってデータを読み書きします。 もしそれが決定できれば、modeは fileobj のモードで上書きされます。.

注意: fileobj は、TarFileをクローズする時は、クローズされません。

open( ...)
代替コンストラクタです。モジュールレベルでの open() 関数は、 実際はこのクラスメソッドへのショートカットです。詳細については セクション 7.19 を見て下さい。

getmember( name)
メンバー name に対する TarInfo オブジェクトを返します。 もし nameがアーカイブに見つからなければ、KeyErrorが発生します。
注意: もしメンバーがアーカイブに1つ以上あれば、その最後に出現する ものが、最新のバージョンであるとみなされます。

getmembers( )
TarInfo オブジェクトのリストとしてアーカイブのメンバーを返します。 このリストはアーカイブ内のメンバーと同じ順番です。

getnames( )
メンバーをその名前のリストとして返します。これは getmembers()で返されるリストと同じ順番です。

list( verbose=True)
コンテンツの表を sys.stdout に印刷します。もし verbose が False であれば、メンバー名のみ印刷します。もしそれが True であれば、"ls -l"-風の出力が作成されます。

next( )
TarFileが読み込み用にオープンされている時、 アーカイブの次のメンバーを TarInfoオブジェクトとして返します。もしそれ以上利用可能なものがなければ、 None を返します。

extract( member[, path])
メンバーをアーカイブから現在の作業ディレクトリに、そのフル名を使って、 抽出します。そのファイル情報はできるだけ正確に 抽出されます。 memberは、ファイル名でもTarInfo オブジェクトでも構いません。 pathを使って、異なるディレクトリを指定することができます。

extractfile( member)
アーカイブからメンバーをオブジェクトとして抽出します。 memberは、ファイル名あるいは TarInfo オブジェクトです。 もし memberが普通のファイルであれば、ファイル風のオブジェクトを返します。 もし memberがリンクであれば、ファイル風のオブジェクトをリンクのターゲットから 構成します。 もし memberが上のどれでもなければ、None が返されます。
注意: ファイル風のオブジェクトは読み出し専用で以下のメソッドを提供します： read(), readline(), readlines(), seek(), tell().

add( name[, arcname[, recursive=True]])
ファイル nameをアーカイブに追加します。name は、任意のファイルタイプ (ディレクトリ、fifo、シンボリックリンク等)です。 もしarcname が与えられていれば、それはアーカイブ内のファイルの代替名を 指定します。デフォールトではディレクトリは再帰的に追加されます。 これは、recursive を Falseに設定することで避けることができます。

addfile( tarinfo[, fileobj])
TarInfoオブジェクトtarinfoをアーカイブに追加します。 もし fileobj が与えられていれば、tarinfo.size バイトがそれから読まれ、 アーカイブに追加されます。gettarinfo()を使って TarInfo オブジェクトを作成することができます。
注意: Windows プラットフォームでは、fileobjは、ファイルサイズに関する問題を避けるために、 常に、モード 'rb' でオープンされるべきです。

gettarinfo( [name[, arcname [, fileobj]]])
TarInfoオブジェクトをファイル name あるいは (そのファイル記述子に os.fstat()を使って) ファイルオブジェクトfileobjの どちらか用に作成します。 TarInfoの属性のいくつかは、 addfile()を使って追加する前に修正することができます。 arcnameがもし与えられていれば、アーカイブ内のファイルの 代替名を指定します。

close( )
TarFileをクローズします。書き出しモードでは、完了ゼロブロックが 2つ、アーカイブに追加されます。

posix=True
もしTrueなら、POSIX 1003.1-1990 準拠のアーカイブを作成します。GNU 拡張機能は使われません、というのは、それらは POSIX 標準の一部ではないからです。 これはファイル名の長さを最大 256 に、linkname を100文字に制限します。 もしパス名がこの制限を越えたら、ValueErrorが 発生します。 もし Falseであれば、GNU tar 互換アーカイブを作成します。それは POSIX 準拠ではありませんが、無制限長さのパス名を保管することができます。

dereference=False
もし Falseであれば、シンボリックリンクとハードリンクをアーカイブに追加します。 もし Trueであれば、ターゲットファイルの内容をアーカイブに追加します。これは、 リンクをサポートしないシステムには何も効果もありません。

ignore_zeros=False
もし Falseであれば、空のブロックをアーカイブの終わりとして処理します。 もし Trueであれば、空(で無効な)ブロックは飛ばして、できるだけ多くの メンバーを取得しようとします。これは連結した、あるいは損傷したアーカイブでのみ 役に立ちます。

debug=0
0(デバッグメッセージなし)から 3(すべてのデバッグ メッセージあり)までを設定すべきです。そのメッセージは sys.stdout に書かれます。

errorlevel=0
もし 0 なら、extract()を使っている時、すべてのエラーが無視されます。 それでも、デバッギングが有効である時は、それらは、デバッグ出力にエラーメッセージとして 出力されます。 もし1なら、すべてのフェータルエラーが、OSErrorあるいは IOError 例外として発生します。 もし2なら、すべてのフェータルでないエラーが、TarError例外と して、やはり発生します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.19 tarfile Up: 7.19 tarfile Next: 7.19.2 TarInfo オブジェクト


7.19.2 TarInfo オブジェクト

TarInfo オブジェクトは TarFile の一つのメンバーを表します。ファイルに 必要な(ファイルタイプ、ファイルサイズ、時刻、許可、所有者等のような)すべての属性を保存する他に、 そのタイプを決定するのに役に立ついくつかのメソッドを提供します。 これにはファイルのデータそのものは含まれません。

TarInfoオブジェクトは TarFileのメソッド getmember()、 getmembers() および gettarinfo()によって返されます。

class TarInfo( [name])
TarInfo オブジェクトを作成します。

frombuf( )
TarInfo オブジェクトを文字列バッファから作成して返します。

tobuf( )
TarInfo オブジェクトから文字列バッファを作成します。

TarInfoオブジェクトには以下の public なデータ属性があります：

name
アーカイブメンバーの名前。

size
バイト単位でのサイズ。

mtime
最終更新時刻。

mode
許可ビット。

type
ファイルタイプ。 type は普通、以下の定数のどれかです： REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, CONTTYPE, CHRTYPE, BLKTYPE, GNUTYPE_SPARSE。 TarInfo オブジェクトのタイプをもっと便利に決定するには、 以降の is_*() メソッドを使って下さい。

linkname
ターゲットファイル名の名前で、これは タイプLNKTYPE と SYMTYPE の TarInfoオブジェクトにだけ存在します。

uid, gid
このメンバーを本来保存した人のユーザとグループID。

uname, gname
ユーザとグループ名

TarInfoオブジェクトは便利な照会用のメソッドもいくつか提供しています：

isfile( )
もし Tarinfo オブジェクトが普通のファイルであれば、True を返します。

isreg( )
isfile()と同じです。

isdir( )
もしそれがディレクトリであれば Trueを返します。

issym( )
もしそれがシンボリックリンクであれば Trueを返します。

islnk( )
もしそれがハードリンクであれば Trueを返します。

ischr( )
もしそれがキャラクタデバイスであれば Trueを返します。

isblk( )
もしそれがブロックデバイスであれば Trueを返します。

isfifo( )
もしそれが FIFO であれば Trueを返します。

isdev( )
もしそれが、キラクタデバイス、ブロックデバイスあるいは FIFOのどれかであれば Trueを返します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.19.1 TarFile オブジェクト Up: 7.19 tarfile Next: 7.19.3 例


7.19.3 例

非圧縮 tar アーカイブをファイル名のリストから作成する方法：

import tarfile
tar = tarfile.open("sample.tar", "w")
for name in ["foo", "bar", "quux"]:
    tar.add(name)
tar.close()

gzip 圧縮 tar アーカイブを作成してメンバー情報のいくつかを表示する方法：

import tarfile
tar = tarfile.open("sample.tar.gz", "r:gz")
for tarinfo in tar:
    print tarinfo.name, " は 大きさが ", tarinfo.size, "バイトで ",
    if tarinfo.isreg():
        print "普通のファイルです。"
    elif tarinfo.isdir():
        print "ディレクトリです。"
    else:
        print "ファイル・ディレクトリ以外のものです。"
tar.close()

見せかけの情報を持つ tar アーカイブを作成する方法：

import tarfile
tar = tarfile.open("sample.tar.gz", "w:gz")
for name in namelist:
    tarinfo = tar.gettarinfo(name, "fakeproj-1.0/" + name)
    tarinfo.uid = 123
    tarinfo.gid = 456
    tarinfo.uname = "johndoe"
    tarinfo.gname = "fake"
    tar.addfile(tarinfo, file(name))
tar.close()

非圧縮 tar ストリームをsys.stdinから抽出する 唯一の方法：

import sys
import tarfile
tar = tarfile.open(mode="r|", fileobj=sys.stdin)
for tarinfo in tar:
    tar.extract(tarinfo)
tar.close()
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.19.2 TarInfo オブジェクト Up: 7.19 tarfile Next: 7.20 readline


7.20 readline -- GNU readline のインタフェース

利用可能な条件: Unix.

readline モジュールでは、補完をしやすくしたり、 ヒストリファイルを Python インタプリタから読み書きできるように するためのいくつかの関数を定義しており、これらは直接使うことも rlcompleter モジュールを介して使うこともできます。

readline モジュールでは以下の関数を定義しています:

parse_and_bind( string)
readline 初期化ファイルの行を一行解釈して実行します。

get_line_buffer( )
行編集バッファの現在の内容を返します。

insert_text( string)
コマンドラインにテキストを挿入します。

read_init_file( [filename])
readline 初期化ファイルを解釈します。 標準のファイル名設定は最後に使われたファイル名です。

read_history_file( [filename])
readline ヒストリファイルを読み出します。 標準のファイル名設定は ~/.history です。

write_history_file( [filename])
readline ヒストリファイルを保存します。 標準のファイル名設定は ~/.history です。

get_history_length( )
ヒストリファイルに必要な長さを返します。負の値はヒストリファイル のサイズに制限がないことを示します。

set_history_length( length)
ヒストリファイルに必要な長さを設定します。この値は write_history_file() がヒストリを保存する際にファイルを 切り詰めるために使います。負の値はヒストリファイルのサイズを制限 しないことを示します。

set_startup_hook( [function])
startup_hook 関数を設定または除去します。function が指定されて いれば、新たな startup_hook 関数として用いられます; 省略されるか None になっていれば、現在インストール されているフック関数は除去されます。 startup_hook 関数は readline が最初のプロンプトを出力する 直前に引数なしで呼び出されます。

set_pre_input_hook( [function])
pre_input_hook 関数を設定または除去します。function が指定されて いれば、新たな pre_input_hook 関数として用いられます; 省略されるか None になっていれば、現在インストール されているフック関数は除去されます。 pre_input_hook 関数は readline が最初のプロンプトを出力した 後で、かつ readline が入力された文字を読み込み始める直前に 引数なしで呼び出されます。

set_completer( [function])
completer 関数を設定または除去します。function が指定されて いれば、新たな completer 関数として用いられます; 省略されるか None になっていれば、現在インストール されている completer 関数は除去されます。 completer 関数は function(text, state) の形式で、関数が文字列でない値を返すまで state を 0, 1, 2, ..., にして呼び出します。 この関数は text から始まる文字列の補完結果として可能性の あるものを返さなくてはなりません。

get_completer( )
completer 関数を取得します。completer 関数が設定されていなければ Noneを返します。 バージョン2.3 以降で新規追加された 仕様です。

get_begidx( )
readline タブ補完スコープの先頭のインデクスを取得します。

get_endidx( )
readline タブ補完スコープの末尾のインデクスを取得します。

set_completer_delims( string)
タブ補完のための readline 単語区切り文字を設定します。

get_completer_delims( )
タブ補完のための readline 単語区切り文字を取得します。

add_history( line)
1 行をヒストリバッファに追加し、最後に打ち込まれた行のようにします。

参考資料:

rlcompleterモジュール:
対話的プロンプトで Python 識別子を補完する機能。.

  • 7.20.1 例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.19.3 例 Up: 7. オプションのオペレーティングシステムサービス Next: 7.20.1 例


7.20.1 例

以下の例では、ユーザのホームディレクトリにある .pyhist という 名前のヒストリファイルを自動的に読み書きするために、readline モジュールによるヒストリの読み書き関数をどのように使うかを例示しています。 以下のソースコードは通常、対話セッションの中で PYTHONSTARTUP ファイルから読み込まれ自動的に実行されることになります。

import os
histfile = os.path.join(os.environ["HOME"], ".pyhist")
try:
    readline.read_history_file(histfile)
except IOError:
    pass
import atexit
atexit.register(readline.write_history_file, histfile)
del os, histfile
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.20 readline Up: 7.20 readline Next: 7.21 rlcompleter


7.21 rlcompleter -- GNU readline向け補完関数

利用可能な条件: Unix.

rlcompleterモジュールではPythonの識別子やキーワードを定義した readlineモジュール向けの補完関数を定義しています。

readlineモジュールがUnix依存なのでこのモジュールもUnix に依存しています。

rlcompleterモジュールはCompleterクラスを定義しています。

使用例:

>>> import rlcompleter
>>> import readline
>>> readline.parse_and_bind("tab: complete")
>>> readline. <TAB PRESSED>
readline.__doc__          readline.get_line_buffer  readline.read_init_file
readline.__file__         readline.insert_text      readline.set_completer
readline.__name__         readline.parse_and_bind
>>> readline.

rlcompleterモジュールは Pythonの対話モードで利用する為にデザイ ンされています。ユーザは以下の命令を初期化ファイル (環境変数PYTHONSTARTUPによって定義されます)に書き込むことで、 Tabキーによる補完を利用できます:

try:
    import readline
except ImportError:
    print "Module readline not available."
else:
    import rlcompleter
    readline.parse_and_bind("tab: complete")

  • 7.21.1 Completerオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.20.1 例 Up: 7. オプションのオペレーティングシステムサービス Next: 7.21.1 Completerオブジェクト


7.21.1 Completerオブジェクト

Completerオブジェクトは以下のメソッドを持っています:

complete( text, state)
textのstate番目の補完候補を返します。

もしtextがピリオド(".")を含まない場合、 __main__、__builtin__で定義されて いる名前か、キーワード ( keyword モジュールで定義されている) から補完されます。

ピリオドを含む名前の場合、副作用を出さずに名前を最後まで評価しようとしま す(関数を明示的に呼び出しはしませんが、__getattr__()を呼んでし まうことはあります)そして、dir()関数でマッチする語を見つけま す。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.21 rlcompleter Up: 7.21 rlcompleter Next: 8. Unix独特のサービス


8. Unix独特のサービス

本章に記述されたモジュールは、Unixオペレーティングシステム、 あるいはそれから変形した多くのものに特有する機能のためのインター フェイスを提供します。 その概要を以下に述べます。

posix | 最も一般的な POSIX システムコール群 (通常は os モジュールを介して利用されます)。
pwd | パスワードデータベースへのアクセスを提供する (getpwnam() など)。
grp | グループデータベースへのアクセス (getgrnam() およびその仲間)。
crypt | Unix パスワードをチェックするための関数 crypt()。
dl | 共有オブジェクトのC関数の呼び出し
dbm | ndbmを基にした基本的なデータベースインタフェースです。
gdbm | GNU による dbm の再実装。
termios | POSIX スタイルの端末制御。
TERMIOS | termios モジュールを利用する上で必要となる シンボル定数。
tty | 一般的な端末制御操作のためのユーティリティ関数群。
pty | SGIとLinux用の擬似端末を制御する
fcntl | fcntl() および ioctl() システム コール。
pipes | Python による Unix シェルパイプラインへのインタフェース。
posixfile | ロック機構をサポートするファイル類似オブジェクト。
resource | 現プロセスのリソース使用状態を提供するためのインタフェース。
nis | Sun の NIS (Yellow Pages) ライブラリへのインタフェース。
syslog | Unix syslog ライブラリルーチン群へのインタフェース。
commands | 外部コマンドを実行するためのユーティリティです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.21.1 Completerオブジェクト Up: Python ライブラリリファレンス Next: 8.1 posix


8.1 posix -- 最も一般的な POSIX システムコール群

利用可能な条件: Unix.

このモジュールはオペレーティングシステムの機能のうち、C 言語標準 および POSIX 標準 (Unix インタフェースをほんの少し隠蔽した) で標準化されている機能に対するアクセス機構を提供します。

このモジュールを直接 import しないで下さい。 その代わりに、 移植性のあるインタフェースを提供している os をインポート してください。Unixでは、 os モジュールが提供する インタフェースは posix の内容を内包しています。 非 Unix オペレーティングシステムでは posix モジュール を使うことはできませんが、その部分的な機能セットは、たいてい os インタフェースを介して利用することができます。 os は、一度 import してしまえば posix の代わり であることによるパフォーマンス上のペナルティは 全くありません。 その上、os は os.environ の 内容が変更された際に自動的に putenv() を呼ぶなど、 いくつかの追加機能を提供しています。

以下の説明は非常に簡潔なものです; 詳細については、 Unix マニュアルの (または POSIX) ドキュメントの) 対応する項目を 参照してください。path で呼ばれる引数は文字列で与えられた パス名を表します。

エラーは例外として報告されます; よくある例外は型エラーです。 一方、システムコールから報告されたエラーは以下に述べるように error (標準例外 OSError と同義です) を送出します。

  • 8.1.1 ラージファイルのサポート
  • 8.1.2 モジュールの内容
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8. Unix独特のサービス Up: 8. Unix独特のサービス Next: 8.1.1 ラージファイルのサポート


8.1.1 ラージファイルのサポート

いくつかのオペレーティングシステム (AIX, HPIX, Irix および Solaris が含まれます) は、int および long を 32 ビット値と する C プログラムモデルで 2Gb を超えるサイズのファイルのサポート を提供しています。このサポートは典型的には 64 ビット値のオフセット 値と、そこからの相対サイズを定義することで実現しています。この ようなファイルは時にラージファイル (large files) と呼ばれます。

Python では、off_t のサイズが long より大きく、 かつ long long 型を利用することができて、少なくとも off_t 型と同じくらい大きなサイズである場合、ラージファイルの サポートが有効になります。この場合、ファイルのサイズ、オフセットおよび Python の通常整数型の範囲を超えるような値の表現には Python の長整数型が 使われます。例えば、ラージファイルのサポートは Irix の最近のバージョン では標準で有効ですが、Solaris 2.6 および 2.7 では、以下のように する必要があります:

CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \
        ./configure

On large-file-capable Linux systems, this might work:

CFLAGS='-D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64' OPT="-g -O2 $CFLAGS" \
        ./configure

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.1 posix Up: 8.1 posix Next: 8.1.2 モジュールの内容


8.1.2 モジュールの内容

posix では以下のデータ項目を定義しています:

environ
インタプリタが起動した時点の環境変数文字列を表現する辞書です。 例えば、environ['HOME'] はホームディレクトリの パス名で、C 言語の getenv("HOME") と等価です。

この辞書を変更しても、execv()、popen() または system() などに渡される環境変数文字列には影響しません; そうした環境を変更するする必要がある場合、environ を execve() に渡すか、system() または popen() の命令文字列に変数の代入や export 文を 追加してください。

注意: os モジュールでは、もう一つの environ 実装を提供しており、環境変数が変更された場合、その内容を更新する ようになっています。os.environ を更新した場合、この辞書は 古い内容を表していることになってしまうので、このことにも注意 してください。posix モジュール版を直接アクセスするよりも、 os モジュール版を使う方が推奨されています。

このモジュールのその他の内容は os モジュールからのみの アクセスになっています; 詳しい説明はos モジュールの ドキュメントを参照してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.1.1 ラージファイルのサポート Up: 8.1 posix Next: 8.2 pwd


8.2 pwd -- パスワードデータベースへのアクセスを提供する

利用可能な条件: Unix.

このモジュールはUnixのユーザアカウントとパスワードのデータベースへ のアクセスを提供します。全てのUnix系OSで利用できます。

パスワードデータベースの各エントリはタプルのようなオブジェクトで提供され、 それぞれの属性はpasswd構造体のメンバに対応しています(下 の属性欄については、<pwd.h>を見てください)。

インデックス | 属性 | 意味
0 | pw_name | ログイン名
1 | pw_passwd | 暗号化されたパスワード(optional))
2 | pw_uid | ユーザID(UID)
3 | pw_gid | グループID(GID)
4 | pw_gecos | 実名またはコメント
5 | pw_dir | ホームディレクトリ
6 | pw_shell | シェル

UIDとGIDは整数で、それ以外は全て文字列です。 検索したエントリが見つからないとKeyErrorが発生します。

注意: 伝統的なUnixでは、pw_passwdフィールドはDES由来のアルゴリ ズムで暗号化されたパスワード(crypyモジュー ルをごらんください)が含まれています。しかし、近代的なUNIX系OSではシャドウパスワードとよばれる仕組みを利用しています。この場合には pw_passwdフィールドにはアスタリスク('*')か、"x"と いう一文字だけが含まれており、暗号化されたパスワードは、一般には見えない /etc/shadowというファイルに入っています。

このモジュールでは以下のものが定義されています:

getpwuid( uid)
与えられたUIDに対応するパスワードデータベースのエントリを返します。

getpwnam( name)
与えられたユーザ名に対応するパスワードデータベースのエントリを返します。

getpwall( )
パスワードデータベースの全てのエントリを、任意の順番で並べたリストを返し ます。

参考資料:

grpモジュール:
このモジュールに似た、グループデータベースへのアクセス を提供するモジュール。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.1.2 モジュールの内容 Up: 8. Unix独特のサービス Next: 8.3 grp


8.3 grp -- グループデータベースへのアクセス

利用可能な条件: Unix.

このモジュールでは Unix グループ (group) データベースへのアクセス機構を 提供します。全ての Unix バージョンで利用可能です。

このモジュールはグループデータベースのエントリをタプルに似たオブジェクト として報告されます。このオブジェクトの属性は group 構造体の各メンバ (以下の属性フィールド、<pwd.h> を参照) に対応 します:

インデクス | 属性 | 意味
0 | gr_name | グループ名
1 | gr_passwd | (暗号化された) グループパスワード; しばしば空文字列になります
2 | gr_gid | 数字のグループ ID
3 | gr_mem | グループメンバの全てのユーザ名

gid は整数、名前およびパスワードは文字列、そしてメンバリストは 文字列からなるリストです。 (ほとんどのユーザは、パスワードデータベースで自分が入れられているグループ のメンバとしてグループデータベース内では明示的に列挙されていないので 注意してください。完全なメンバ情報を取得するには両方のデータベースを 調べてください。)

このモジュールでは以下の内容を定義しています:

getgrgid( gid)
与えられたグループ ID に対するグループデータベースエントリを返します。 要求したエントリが見つからなかった場合、KeyError が 送出されます。

getgrnam( name)
与えられたグループ名に対するグループデータベースエントリを返します。 要求したエントリが見つからなかった場合、KeyError が 送出されます。

getgrall( )
全ての入手可能なグループエントリを返します。順番は決まっていません。

参考資料:

pwdモジュール:
このモジュールと類似の、ユーザデータベースへのインタフェース。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.2 pwd Up: 8. Unix独特のサービス Next: 8.4 crypt


8.4 crypt -- Unix パスワードをチェックするための関数

利用可能な条件: Unix.

このモジュールは DES アルゴリズムに基づいた 一方向ハッシュ関数である crypt(3) ルーチンを実装しています。詳細については Unix マニュアルページ を参照してください。このモジュールは、Python スクリプトが ユーザから入力されたパスワードを受理できるようにしたり、Unix パスワードに (脆弱性検査のための) 辞書攻撃を試みるのに使えます。

crypt( word, salt)
word は通常はユーザのパスワードで、プロンプトやグラフィカル インタフェースからタイプ入力されます。salt は通常ランダムな 2 文字からなる文字列で、DES アルゴリズムに 4096 通りのうち 1 つの 方法で外乱を与えるために使われます。salt に使う文字は集合 [./a-zA-Z0-9] の要素でなければなりません。 ハッシュされたパスワードを文字列として返します。パスワード文字列 は salt と同じ文字集合に含まれる文字からなります (最初の 2 文字は salt 自体です).

典型的な使用例のサンプルコード:

import crypt, getpass, pwd

def login():
    username = raw_input('Python login:')
    cryptedpasswd = pwd.getpwnam(username)[1]
    if cryptedpasswd:
        if cryptedpasswd == 'x' or cryptedpasswd == '*':
            raise "Sorry, currently no support for shadow passwords"
        cleartext = getpass.getpass()
        return crypt.crypt(cleartext, cryptedpasswd[:2]) == cryptedpasswd
    else:
        return 1
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.3 grp Up: 8. Unix独特のサービス Next: 8.5 dl


8.5 dl -- 共有オブジェクトのC関数の呼び出し

利用可能な条件: Unix.

dlモジュールはdlopen()関数へのインターフェースを 定義します。 これはダイナミックライブラリにハンドルするための Unixプラットフォーム上の最も一般的なインターフェースです。 そのライブラリの任意の関数を呼ぶプログラムを与えます。

注意: このモジュールはsizeof(int) == sizeof(long) == sizeof(char *) でなければ働きません。 そうでなければimportするときにSystemErrorが送出されるでしょう。

dlモジュールは次の関数を定義します:

open( name[, mode = RTLD_LAZY])
共有オブジェクトファイルを開いて、ハンドルを返します。 モードは遅延結合(RTLD_LAZY)または即時結合(RTLD_NOW) を表します。 デフォルトはRTLD_LAZYです。 いくつかのシステムはRTLD_NOWをサポートしていないことに 注意してください。

返り値はdlobjectです。

dlモジュールは次の定数を定義します:

RTLD_LAZY
open()の引数として使います。

RTLD_NOW
open()の引数として使います。 即時結合をサポートしないシステムでは、 この定数がモジュールに現われないことに注意してください。 最大のポータビリティを求めるならば、システムが即時結合をサポートする かどうかを決定するためにhasattr()を使用してください。

dlモジュールは次の例外を定義します:

exception error
動的なロードやリンクルーチンの内部でエラーが生じたときに送出される例外です。

例:

>>> import dl, time
>>> a=dl.open('/lib/libc.so.6')
>>> a.call('time'), time.time()
(929723914, 929723914.498)

この例はDebian GNU/Linuxシステム上で行なったもので、 このモジュールの使用はたいてい悪い選択肢であるという事実のよい例です。

  • 8.5.1 Dlオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.4 crypt Up: 8. Unix独特のサービス Next: 8.5.1 Dlオブジェクト


8.5.1 Dlオブジェクト

open()によって返されたDlオブジェクトは次のメソッドを持っています:

close( )
メモリーを除く全てのリソースを解放します。

sym( name)
nameという名前の関数が参照された共有オブジェクトに存在する場合、 そのポインター(整数値)を返します。 存在しない場合Noneを返します。 これは次のように使えます:

>>> if a.sym('time'):
...     a.call('time')
... else:
...     time.time()

(0はNULLポインターであるので、この関数は0でない数を返すだろう ということに注意してください)

call( name[, arg1[, arg2...]])
参照された共有オブジェクトのnameという名前の関数を呼出します。 引数は、Python整数(そのまま渡される)、Python文字列(ポインターが渡される)、 None (NULLとして渡される) のどれかでなければいけません。 Pythonはその文字列が変化させられるのを好まないので、 文字列はconst char*として関数に渡されるべきであることに 注意してください。

最大で10個の引数が渡すことができ、 与えられない引数はNoneとして扱われます。 関数の返り値はC long(Python整数である)です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.5 dl Up: 8.5 dl Next: 8.6 dbm


8.6 dbm -- UNIX dbmのシンプルなインタフェース

利用可能な条件: Unix.

dbmモジュールはUnix(n)dbmインタフェースの ライブラリを提供します。dbmオブジェクトは、キーと値が必ず文字列である以外は 辞書オブジェクトのようなふるまいをします。 print文などでdbmインスタンスを出力してもキーと値は出力されません。 また、items()とvalues()メソッドはサポートされません。

このモジュールは、BSD DB、GNU GDBM互換インタフェースを持った クラシックなndbmインタフェースを使うことができます。 Unix上のビルド時にconfigureスクリプトで適切なヘッダファイルが 割り当られます。

以下はこのモジュールの定義:

exception error
I/Oエラーのようなdbm特有のエラーが起ったときに上げられる値です。 また、正しくないキーが与えられた場合に通常のマッピングエラーのような KeyErrorが上げられます。

library
ndbmが使用している実装ライブラリ名です。

open( filename[, flag[, mode]])
dbmデータベースを開いてdbmオブジェクトを返します。 引数filenameはデータベースのファイル名を指定します。 (拡張子.dirや.pagは付けません。 また、BSD DBは拡張子.dbがついたファイルが一つ作成されます。)

オプション引数flagは次のような値を指定します:

Value | Meaning
'r' | 存在するデータベースを読取り専用で開きます。(デフォルト)
'w' | 存在するデータベースを読み書き可能な状態で開きます。
'c' | データベースを読み書き可能な状態で開きます。 また、データベースが存在しない場合は新たに作成します。
'n' | Always create a new, empty database, open for reading and writing
'n' | 常に空のデータベースが作成され、読み書き可能な状態で開きます。

オプション引数modeはデータベース作成時に使用される Unixのファイルモードを指定します。デフォルトでは8進数の0666です

参考資料:

anydbmモジュール:
dbmスタイルの一般的なインタフェース.
gdbmモジュール:
GNU GDBMライブラリの類似したインタフェース.
whichdbモジュール:
存在しているデータベースの形式を決めるための ユーティリティモジュール.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.5.1 Dlオブジェクト Up: 8. Unix独特のサービス Next: 8.7 gdbm


8.7 gdbm -- GNU による dbm の再実装

利用可能な条件: Unix.

このモジュールは dbmモジュールに よく似ていますが、gdbm を使っていくつかの追加機能を提供しています。 gdbm と dbm では生成されるファイル形式に互換性がないので 注意してください。

gdbm モジュールでは GNU DBM ライブラリへのインタフェースを 提供します。gdbm オブジェクトはキーと値が常に文字列である ことを除き、マップ型 (辞書型) と同じように動作します。 gdbm オブジェクトに対して print を適用しても キーや値を印字することはなく、items() 及び values() メソッドはサポートされていません。

このモジュールでは以下の定数および関数を定義しています:

exception error
I/O エラーのような gdbm 特有のエラーで送出されます。 誤ったキーの指定のように、一般的なマップ型のエラーに対しては KeyError が送出されます。

open( filename, [flag, [mode]])
gdbm データベースを開いて gdbm オブジェクトを返します。 filename 引数はデータベースファイルの名前です。

オプションの flag としては、 'r' (既存のデータベースを読み込み専用で開く -- 標準の値です)、 'w' (既存のデータベースを読み書き用に開く)、 'c' (既存のデータベースが存在しない場合には新たに作成する)、または 'n' (常に新たにデータベースを作成する)、をとることができます。

データベースをどのように開くかを制御するために、フラグに以下の文字を 追加することができます:

  • 'f' -- データベースを高速モードで開きます。このモードではデータベースへの書き込みはファイルシステムと同期されません。
  • 's' -- 同期モードで開きます。データベースへの変更はファイルに即座いに書き込まれます。
  • 'u' -- データベースをロックしません。

全てのバージョンの gdbm で全てのフラグが有効とは限りません。 モジュール定数 open_flags はサポートされているフラグ文字 からなる文字列です。無効なフラグが指定された場合、例外 error が送出されます。

オプションの mode 引数は、新たにデータベースを作成しなければならない 場合に使われる Unix のファイルモードです。標準の値は 8 進数の 0666 です。

辞書型形式のメソッドに加えて、gdbm オブジェクトには以下のメソッド があります:

firstkey( )
このメソッドと next() メソッドを使って、データベースの全ての キーにわたってループ処理を行うことができます。探索は gdbm の 内部ハッシュ値の順番に行われ、キーの値に順に並んでいるとは限りません。 このメソッドは最初のキーを返します。

nextkey( key)
データベースの順方向探索において、key よりも後に来るキーを 返します。以下のコードはデータベース db に ついて、キー全てを含むリストをメモリ上に生成することなく 全てのキーを出力します:

k = db.firstkey()
while k != None:
    print k
    k = db.nextkey(k)

reorganize( )
大量の削除を実行した後、gdbm ファイルの占めるスペースを 削減したい場合、このルーチンはデータベースを再組織化します。 この再組織化を使う以外に gdbm はデータベースファイルの 大きさを短くすることはありません; そうでない場合、削除された 部分のファイルスペースは保持され、新たな (キー、値の) ペアが追加 される際に再利用されます。

sync( )
データベースが高速モードで開かれていた場合、このメソッドは ディスクにまだ書き込まれていないデータを全て書き込ませます。

参考資料:

anydbmモジュール:
dbm 形式のデータベースへの汎用インタフェース。.
whichdbモジュール:
既存のデータベースがどの形式のデータベースか判定する ユーティリティモジュール。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.6 dbm Up: 8. Unix独特のサービス Next: 8.8 termios


8.8 termios -- POSIX スタイルの端末制御

利用可能な条件: Unix.

このモジュールでは端末 I/O 制御のための POSIX 準拠の関数呼び出し インタフェースを提供します。これら呼び出しのための完全な記述については、 POSIX または Unix マニュアルページを参照してください。 POSIX termios 形式の端末制御をサポートする Unix の バージョンで (かつインストール時に指定した場合に) のみ利用可能です。

このモジュールの関数は全て、ファイル記述子 fd を最初の引数 としてとります。この値は、sys.stdin.fileno() が返すような 整数のファイル記述子でも、sys.stdin 自体のようなファイル オブジェクトでもかまいません。

このモジュールではまた、モジュールで提供されている関数を使う上で 必要となる全ての定数を定義しています; これらの定数は C の対応 する関数と同じ名前を持っています。これらの端末制御インタフェース を利用する上でのさらなる情報については、あなたのシステムの ドキュメンテーションを参考にしてください。

このモジュールでは以下の関数を定義しています:

tcgetattr( fd)
ファイル記述子 fd の端末属性を含むリストを返します。その形式は: [iflag, oflag, cflag, lflag, ispeed, ospeed, cc] です。cc は端末特殊文字のリストです (それぞれ長さ 1 の文字列です。ただしインデクス VMIN および VTIME の内容は、それらのフィールドが定義されていた場合整数 の値となります)。

端末設定フラグおよび端末速度の解釈、および配列 cc のインデクス 検索は、termios で定義されているシンボル定数を使って行わなければ なりません。

tcsetattr( fd, when, attributes)
ファイル記述子 fd の端末属性を attributes から取り出して 設定します。attributes は tcgetattr() が返すような リストです。引数 when は属性がいつ変更されるかを決定します: TCSANOW は即時変更を行い、TCSAFLUSH は現在 キューされている出力を全て転送し、全てのキューされている入力を無視 した後に変更を行います。

tcsendbreak( fd, duration)
ファイル記述子 fd にブレークを送信します。duration をゼロ にすると、 0.25-0.5 秒間のブレークを送信します; duration の値が ゼロでない場合、その意味はシステム依存です。

tcdrain( fd)
ファイル記述子 fd に書き込まれた全ての出力が転送されるまで 待ちます。

tcflush( fd, queue)
ファイル記述子 fd にキューされたデータを無視します。 どのキューかはqueue セレクタで指定します: TCIFLUSH は入力キュー、 TCOFLUSH は出力キュー、TCIOFLUSH は両方のキューです。

tcflow( fd, action)
ファイル記述子 fd の入力または出力をサスペンドしたりレジューム したりします。引数 action は出力をサスペンドする TCOOFF、 出力をレジュームする TCOON 、入力をサスペンドする TCIOFF 、入力をレジュームする TCION をとることが できます。

参考資料:

ttyモジュール:
一般的な端末制御操作のための便利な関数。.

  • 8.8.1 使用例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.7 gdbm Up: 8. Unix独特のサービス Next: 8.8.1 使用例


8.8.1 使用例

以下はエコーバックを切った状態でパスワード入力を促す関数です。 ユーザの入力に関わらず以前の端末属性を正確に回復するために、 二つの tcgetattr() と try ... finally 文によるテクニックが使われています:

def getpass(prompt = "Password: "):
    import termios, sys
    fd = sys.stdin.fileno()
    old = termios.tcgetattr(fd)
    new = termios.tcgetattr(fd)
    new[3] = new[3] & ~termios.ECHO          # lflags
    try:
        termios.tcsetattr(fd, termios.TCSADRAIN, new)
        passwd = raw_input(prompt)
    finally:
        termios.tcsetattr(fd, termios.TCSADRAIN, old)
    return passwd

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.8 termios Up: 8.8 termios Next: 8.9 TERMIOS


8.9 TERMIOS -- termios モジュールで使われる定数

利用可能な条件: Unix.

リリース 2.1 以降で撤廃された仕様です。 必要な定数は termios から取り込んでください。

このモジュールはtermiosモジュール を使う上で必要となるシンボル定数を定義しています (上の節を参照して ください)。これらの定数のリストは POSIX または Unix のマニュアル ページを参照してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.8.1 使用例 Up: 8. Unix独特のサービス Next: 8.10 tty


8.10 tty -- 端末制御のための関数群

利用可能な条件: Unix.

tty モジュールは端末を cbreak および raw モードにする ための関数を定義しています。

このモジュールは termios モジュールを必要とするため、 Unixでしか動作しません。

tty モジュールでは、以下の関数を定義しています:

setraw( fd[, when])
ファイル記述子 fd のモードを raw モードに変えます。 when を省略すると標準の値は TERMIOS.TCAFLUSH に なり、termios.tcsetattr() に渡されます。

setcbreak( fd[, when])
ファイル記述子 fd のモードを cbreakモードに変えます。 when を省略すると標準の値は TERMIOS.TCAFLUSH に なり、termios.tcsetattr() に渡されます。

参考資料:

termiosモジュール:
低レベル端末制御インタフェース。.
TERMIOSモジュール:
端末制御操作で便利な定数群。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.9 TERMIOS Up: 8. Unix独特のサービス Next: 8.11 pty


8.11 pty -- 擬似端末ユーティリティ

利用可能な条件: IRIX, Linux.

ptyモジュールは擬似端末(他のプロセスを実行してその制御をしてい る端末をプログラムで読み書きする)を制御する操作を定義しています。

擬似端末の制御はプラットフォームに強く依存するので、SGIとLinux用のコード しか存在していません。(Linux用のコードは他のプラットフォームでも動作するよ うに作られていますがテストされていません。)

ptyモジュールでは以下の関数を定義しています:

fork( )

forkします。子プロセスの制御端末を擬似端末に接続します。 返り値は(pid, fd)です。子プロセスはpidとして0、 、fdとしてinvalid をそれぞれ受けとります。親プロセスは pidとして子プロセスのPID、fdとして子プロセスの制御端末(子プ ロセスの標準入出力に接続されている)のファイルディスクリプタを受けとります。

openpty( )

新しい擬似端末のペアを開きます。 利用できるならos.openpty()を使い、 利用できなければSGIと一般的なUnixシステム用の エミュレーションコードを使います。 マスター、スレーブそれぞれのためのファイルディスクリプタ、 (master, slave)のタプルを返します。

spawn( argv[, master_read[, stdin_read]])

プロセスを生成して制御端末を現在のプロセスの標準入出力に接続します。 これは制御端末を読もうとするプログラムをごまかすために利用されます。

master_readとstdin_readにはファイルディスクリプタから読み込む 関数を指定してください。デフォルトでは呼ばれるたびに1024バイトずつ読み 込もうとします。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.10 tty Up: 8. Unix独特のサービス Next: 8.12 fcntl


8.12 fcntl -- fcntl() および ioctl() システムコール

利用可能な条件: Unix.

このモジュールでは、ファイル記述子 (file descriptor) に基づいた ファイル制御および I/O 制御を実現します。 このモジュールは、 Unix のルーチンである fcntl() および ioctl() へのインタフェースです。

このモジュール内の全ての関数はファイル記述子 fd を最初の引数に 取ります。この値は sys.stdin.fileno() が返すような 整数のファイル記述子でも、sys.stdin 自体のような、純粋に ファイル記述子だけを返す fileno() メソッドを提供している ファイルオブジェクトでもかまいません。

このモジュールでは以下の関数を定義しています:

fcntl( fd, op[, arg])
要求された操作をファイル記述子 fd (または fileno() メソッドを提供しているファイルオブジェクト) に対して実行します。 操作は op で定義され、オペレーティングシステム依存です。 これらの操作コードは fcntl モジュール内にもあります。 引数 arg はオプションで、標準では整数値 0 です。 この引数を与える場合、整数か文字列の値をとります。 引数が無いか整数値の場合、この関数の戻り値は C 言語の fcntl() を呼び出した際の整数の戻り値になります。 引数が文字列の場合には、struct.pack で作られる ようなバイナリの構造体を表します。 バイナリデータはバッファにコピーされ、そのアドレスが C 言語の fcntl() 呼び出しに渡されます。 呼び出しが成功した後に戻される値はバッファの内容で、文字列 オブジェクトに変換されています。返される文字列は arg 引数 と同じ長さになます。この値は 1024 バイトに制限されています。 オペレーティングシステムからバッファに返される情報の長さが 1024 バイトよりも大きい場合、大抵はセグメンテーション違反となるか、 より不可思議なデータの破損を引き起こします。

fcntl() が失敗した場合、IOError が 送出されます。

ioctl( fd, op, arg)
この関数は fcntl() 関数と同じですが、操作が通常ライブラリ モジュール termios で定義されており、引数の扱いがより 複雑であるところが異なります。

パラメタ arg は整数か、存在しない (整数 0 と等価なもの として扱われます) か、(通常の Python 文字列のような) 読み出し専用の バッファインタフェースをサポートするオブジェクトか、読み書き バッファインタフェースをサポートするオブジェクトです。

最後の型のオブジェクトを除き、動作は fcntl() 関数と 同じです。

可変なバッファが渡された場合、動作は mutate_flag 引数の 値で決定されます。

この値が偽の場合、バッファの可変性は無視され、動作は読み出しバッファ の場合と同じになりますが、上で述べた 1024 バイトの制限は回避されます - 従って、どれだけオペレーティングシステムが希望するより長いバッファを 渡しても正しく動作します。

mutate_flag が真の場合、バッファは (実際には) 根底にある ioctl() システムコールに渡され、後者の戻り値が 呼び出し側の Python に引き渡され、バッファの新たな内容は ioctl の動作を反映します。 この説明はやや単純化されています。というのは、与えられたバッファが 1024 バイト長よりも短い場合、バッファはまず 1024 バイト長の 静的なバッファにコピーされてから ioctl に渡され、 その後引数で与えたバッファに戻しコピーされるからです。

mutate_flag が与えられなかった場合、2.3 ではこの値は偽となります。 この仕様は今後のいくつかのバージョンを経た Python で変更される予定 です: 2.4 では、 mutate_flag を提供し忘れると警告が出されますが 同じ動作を行い、2.5 ではデフォルトの値が真となるはずです。

以下に例を示します:

>>> import array, fcntl, struct, termios, os
>>> os.getpgrp()
13341
>>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, "  "))[0]
13341
>>> buf = array.array('h', [0])
>>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
0
>>> buf
array('h', [13341])

flock( fd, op)
ファイル記述子 fd (fileno() メソッドを提供している ファイルオブジェクトも含む) に対してロック操作 op を実行します。 詳細は Unix マニュアルの flock(3) を参照してください (システムによっては、この関数は fcntl() を使って エミュレーションされています)。

lockf( fd, operation, [len, [start, [whence]]])
本質的に fcntl() によるロッキングの呼び出しをラップ したものです。fd はロックまたはアンロックするファイルの ファイル記述子で、operation は以下の値:

  • LOCK_UN - アンロック
  • LOCK_SH - 共有ロックを取得
  • LOCK_EX - 排他的ロックを取得

のうちいずれかになります。

operation が LOCK_SH または LOCK_EX の場合、LOCK_NB とビット OR にすることでロック取得時に ブロックしないようにすることができます。LOCK_NB が 使われ、ロックが取得できなかった場合、IOError が送出 され、例外は errno 属性を持ち、その値は EACCESS または EAGAIN になります (オペレーティングシステムに 依存します; 可搬性のため、両方の値をチェックしてください)。 少なくともいくつかのシステムでは、 ファイル記述子が参照している ファイルが書き込みのために開かれている場合、LOCK_EX だけしか使うことができません。

length はロックを行いたいバイト数、start は ロック領域先頭の whence からの相対的なバイトオフセット、 whence は fileobj.seek() と同じで、具体的には:

  • 0 - ファイル先頭からの相対位置 (SEEK_SET)
  • 1 - 現在のバッファ位置からの相対位置 (SEEK_CUR)
  • 2 - ファイルの末尾からの相対位置 (SEEK_END)

start の標準の値は 0 で、ファイルの先頭から開始することを 意味します。whence の標準の値も 0 です。

以下に (全ての SVR4 互換システムでの) 例を示します:

import struct, fcntl

file = open(...)
rv = fcntl(file, fcntl.F_SETFL, os.O_NDELAY)

lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
rv = fcntl.fcntl(file, fcntl.F_SETLKW, lockdata)

最初の例では、戻り値 rv は整数値を保持しています; 二つ目の 例では文字列値を保持しています。lockdata 変数の構造体 レイアウトはシステム依存です -- 従って flock() を 呼ぶ方がベターです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.11 pty Up: 8. Unix独特のサービス Next: 8.13 pipes


8.13 pipes -- シェルパイプラインへのインタフェース

利用可能な条件: Unix.

pipes モジュールでは、'pipeline' の概念 -- ある ファイルを別のファイルに変換する機構の直列接続 -- を抽象化する ためのクラスを定義しています。

このモジュールは /bin/sh コマンドラインを利用するため、 os.system() および os.popen() のための POSIX 準拠のシェル、または互換のシェルが必要です。

pipes モジュールでは、以下のクラスを定義しています:

class Template( )
パイプラインを抽象化したクラス。

使用例:

>>> import pipes
>>> t=pipes.Template()
>>> t.append('tr a-z A-Z', '--')
>>> f=t.open('/tmp/1', 'w')
>>> f.write('hello world')
>>> f.close()
>>> open('/tmp/1').read()
'HELLO WORLD'

  • 8.13.1 テンプレートオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.12 fcntl Up: 8. Unix独特のサービス Next: 8.13.1 テンプレートオブジェクト


8.13.1 テンプレートオブジェクト

テンプレートオブジェクトは以下のメソッドを持っています:

reset( )
パイプラインテンプレートを初期状態に戻します。

clone( )
元のパイプラインテンプレートと等価の新しいオブジェクトを返します。

debug( flag)
flag が真の場合、デバッグをオンにします。そうでない場合、 デバッグをオフにします。デバッグがオンの時には、実行されるコマンド が印字され、より多くのメッセージを出力するようにするために、シェルに set -x 命令を与えます。

append( cmd, kind)
新たなアクションをパイプラインの末尾に追加します。cmd 変数は 有効な bourne shell 命令でなければなりません。kind 変数は 二つの文字からなります。

最初の文字は '-' (コマンドが標準入力からデータを読み出すことを 意味します)、'f' (コマンドがコマンドライン上で与えたファイルから データを読み出すことを意味します)、あるいは '.' (コマンドは 入力を読まないことを意味します、従ってパイプラインの先頭になります)、の いずれかになります。

同様に、二つ目の文字は '-' (コマンドが標準出力に結果を書き込む ことを意味します)、'f' (コマンドがコマンドライン上で指定した ファイルに結果を書き込むことを意味します)、あるいは '.' (コマンド はファイルを書き込まないことを意味し、パイプラインの末尾になります)、 のいずれかになります。

prepend( cmd, kind)
パイプラインの先頭に新しいアクションを追加します。引数の説明については append() を参照してください。

open( file, mode)
ファイル類似のオブジェクトを返します。このオブジェクトは file を開いていますが、パイプラインを通して読み書きするようになっています。 mode には 'r' または 'w' のいずれか一つしか与える ことができないので注意してください。

copy( infile, outfile)
パイプを通して infile を outfile にコピーします。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.13 pipes Up: 8.13 pipes Next: 8.14 posixfile


8.14 posixfile -- ロック機構をサポートするファイル類似オブジェクト

利用可能な条件: Unix.

リリース 1.5 以降で撤廃された仕様です。 このモジュールが提供しているよりも うまく処理ができ、可搬性も高いロック操作が fcntl.lockf() で提供されています。

このモジュールでは、組み込みのファイルオブジェクトの上にいくつかの 追加機能を実装しています。特に、このオブジェクトはファイルのロック機構、 ファイルフラグへの操作、およびファイルオブジェクトを複製するための 簡単なインタフェースを実装しています。オブジェクトは全ての標準 ファイルオブジェクトのメソッドに加え、以下に述べるメソッドを持って います。このモジュールはファイルのロック機構に fcntl.fcntl() を用いるため、ある種の Unixでしか動作しません。

posixfile オブジェクトをインスタンス化するには、 posixfile モジュールの open() 関数を使います。生成されるオブジェクト は標準ファイルオブジェクトとだいたい同じルック& フィールです。

posixfile モジュールでは、以下の定数を定義しています:

SEEK_SET
オフセットをファイルの先頭から計算します。

SEEK_CUR
オフセットを現在のファイル位置から計算します。

SEEK_END
オフセットをファイルの末尾から計算します。

posixfile モジュールでは以下の関数を定義しています:

open( filename[, mode[, bufsize]])
指定したファイル名とモードで新しい posixfile オブジェクトを作成 します。filename、mode および bufsize 引数は 組み込みの open() 関数と同じように解釈されます。

fileopen( fileobject)
指定した標準ファイルオブジェクトで新しい posixfile オブジェクトを 作成します。作成されるオブジェクトは元のファイルオブジェクトと 同じファイル名およびモードを持っています。

posixfile オブジェクトでは以下の追加メソッドを定義しています:

lock( fmt, [len[, start[, whence]]])
ファイルオブジェクトが参照しているファイルの指定部分にロックをかけます。 指定の書式は下のテーブルで説明されています。 len 引数にはロックする部分の長さを指定します。標準の値は 0 です。 start にはロックする部分の先頭オフセットを指定し、その 標準値は 0 です。whence 引数はオフセットをどこからの 相対位置にするかを指定します。この値は定数 SEEK_SET、 SEEK_CUR、または SEEK_END のいずれかになります。 標準の値は SEEK_SET です。引数についてのより詳しい情報は システムの fcntl(2) マニュアルページを参照してください。

flags( [flags])
ファイルオブジェクトが参照しているファイルに指定したフラグを設定 します。新しいフラグは特に指定しない限り以前のフラグと OR されます。 指定書式は下のテーブルで説明されています。flags 引数なしの 場合、現在のフラグを示す文字列が返されます ("?" 修飾子と同じ です) 。 フラグについてのより詳しい情報はシステムの fcntl(2) マニュアルページを参照してください。

dup( )
ファイルオブジェクトと、背後のファイルポインタおよびファイル記述子 を複製します。返されるオブジェクトは新たに開かれたファイルのように 振舞います。

dup2( fd)
ファイルオブジェクトと、背後のファイルポインタおよびファイル記述子 を複製します。新たなオブジェクトは指定したファイル記述子を持ちます。 それ以外の点では、返されるオブジェクトは新たに開かれたファイルのように 振舞います。

file( )
posixfile オブジェクトが参照している標準ファイルオブジェクトを返します。 この関数は標準ファイルオブジェクトを使うよう強制している関数を使う 場合に便利です。

全てのメソッドで、要求された操作が失敗した場合には IOError が送出されます。

lock() の書式指定文字には以下のような意味があります:

書式指定 | 意味
u | 指定領域のロックを解除します
r | 指定領域の読み出しロックを要求します
w | 指定領域の書き込みロックを要求します

これに加え、以下の修飾子を書式に追加できます:

修飾子 | 意味 | 注釈
| | ロック操作が処理されるまで待ちます |
? | 要求されたロックと衝突している第一のロックを返すか、衝突がない場合には None を返します。 | (1)

注釈:

(1)
返されるロックは (mode, len, start, whence, pid) の形式で、mode はロックの形式を表す文字 ('r' または 'w') です。この修飾子は ロック要求の許可を行わせません; すなわち、問い合わせの目的にしか 使えません。

flags() の書式指定文字には以下のような意味があります:

書式 | 意味
a | 追記のみ (append only) フラグ
c | 実行時クローズ (close on exec) フラグ
n | 無遅延 (no delay) フラグ (非ブロック (non-blocking) フラグとも呼ばれます)
s | 同期 (synchronization) フラグ

これに加え、以下の修飾子を書式に追加できます:

修飾子 | 意味 | 注釈
! | 指定したフラグを通常の 'オン' にせず 'オフ' にします | (1)
= | フラグを標準の 'OR' 操作ではなく置換します。 | (1)
? | 設定されているフラグを表現する文字からなる文字列を返します。 | (2)

注釈:

(1)
"!" および "=" 修飾子は互いに排他の関係にあります。

(2)
この文字列が表すフラグは同じ呼び出しによってフラグが置き換えられた後のものです。

以下に例を示します:

import posixfile

file = posixfile.open('/tmp/test', 'w')
file.lock('w|')
...
file.lock('u')
file.close()
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.13.1 テンプレートオブジェクト Up: 8. Unix独特のサービス Next: 8.15 resource


8.15 resource -- リソース使用状態の情報

利用可能な条件: Unix.

このモジュールでは、プログラムによって使用されているシステムリソースを 計測したり制御するための基本的なメカニズムを提供します。

特定のシステムリソースを指定したり、現在のプロセスやその子プロセスの リソース使用情報を要求するためにはシンボル定数が使われます。

エラーを表すための例外が一つ定義されています:

exception error
下に述べる関数は、背後にあるシステムコールが予期せず失敗した場合、 このエラーを送出するかもしれません。

  • 8.15.1 リソースの制限
  • 8.15.2 リソースの使用状態
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.14 posixfile Up: 8. Unix独特のサービス Next: 8.15.1 リソースの制限


8.15.1 リソースの制限

リソースの使用は下に述べる setrlimit() 関数を使って制限 することができます。各リソースは二つ組の制限値: ソフトリミット (soft limit) 、およびハードリミット (hard limit) 、で制御されます。 ソフトリミットは現在の制限値で、時間とともにプロセスによって下げたり 上げたりできます。ソフトリミットはハードリミットを超えることは できません。ハードリミットはソフトリミットよりも高い任意の値まで 下げることができますが、上げることはできません。(スーパユーザの 有効な UID を持つプロセスのみがハードリミットを上げることができます。)

制限をかけるべく指定できるリソースはシステムに依存します。指定できる リソースは getrlimit(2) マニュアルページで解説されています。 以下に列挙するリソースは背後のオペレーティングシステムがサポートする 場合にサポートされています; オペレーティングシステム側で値を調べたり 制御したりできないリソースは、そのプラットフォーム向けのこのモジュール 内では定義されていません。

getrlimit( resource)
resource の現在のソフトおよびハードリミットを表すタプル (soft, hard) を返します。無効なリソースが 指定された場合には ValueError が、背後のシステム コールが予期せず失敗した場合には error が送出されます。

setrlimit( resource, limits)
resouce の新たな消費制限を設定します。limits 引数 には、タプル (soft, hard) による二つの整数で、 新たな制限を記述しなければなりません。現在指定可能な最大の制限 を指定するために -1 を使うことができます。

無効なリソースが指定された場合、ソフトリミットの値がハードリミット の値を超えている場合、プロセスが (スーパユーザの有効な UID を持って いない状態で) ハードリミットを引き上げようとした場合には ValueError が送出されます。背後のシステムコールが予期せず 失敗した場合には error が送出される可能性もあります。

以下のシンボルは、後に述べる関数 setrlimit() および getrlimit() を使って消費量を制御することができるリソース を定義しています。これらのシンボルの値は、C プログラムで使われて いるシンボルと全く同じです。

getrlimit(2) の Unix マニュアルページには、指定可能な リソースが列挙されています。全てのシステムで同じシンボルが使われて いるわけではなく、また同じリソースを表すために同じ値が使われて いるとも限らないので注意してください。このモジュールはプラットフォーム 間の相違を隠蔽しようとはしていません -- あるプラットフォームで 定義されていないシンボルは、そのプラットフォーム向けの本モジュール では利用することができません。

RLIMIT_CORE
現在のプロセスが生成できるコアファイルの最大 (バイト) サイズです。 プロセスの全体イメージを入れるためにこの値より大きなサイズのコア ファイルが要求された結果、部分的なコアファイルが生成される可能性が あります。

RLIMIT_CPU
プロセッサが利用することができる最大プロセッサ時間 (秒) です。 この制限を超えた場合、SIGXCPU シグナルがプロセスに送られ ます。(どのようにしてシグナルを捕捉したり、例えば開かれているファイルを ディスクにフラッシュするといった有用な処理を行うかについての情報は、 signal モジュールのドキュメントを参照してください)

RLIMIT_FSIZE
プロセスが生成できるファイルの最大サイズです。マルチスレッドプロセス の場合、この値は主スレッドのスタックにのみ影響します。

RLIMIT_DATA
プロセスのヒープの最大 (バイト) サイズです。

RLIMIT_STACK
現在のプロセスのコールスタックの最大 (バイト) サイズです。

RLIMIT_RSS
プロセスが取りうる最大 RAM 常駐ページサイズ (resident set size) です。

RLIMIT_NPROC
現在のプロセスが生成できるプロセスの上限です。

RLIMIT_NOFILE
現在のプロセスが開けるファイル記述子の上限です。

RLIMIT_OFILE
RLIMIT_NOFILE の BSD での名称です。

RLIMIT_MEMLOCK
メモリ中でロックできる最大アドレス空間です。

RLIMIT_VMEM
プロセスが占有できるマップメモリの最大領域です。

RLIMIT_AS
アドレス空間でプロセスが占有できる最大領域 (バイト) です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.15 resource Up: 8.15 resource Next: 8.15.2 リソースの使用状態


8.15.2 リソースの使用状態

以下の関数はリソース使用情報を取得するために使われます:

getrusage( who)
この関数は、who 引数で指定される、現プロセスおよびその子プロセスに よって消費されているリソースを記述するオブジェクトを返します。 who 引数は以下に記述される RUSAGE_* 定数のいずれかを 使って指定します。

返される値の各フィールドはそれぞれ、個々のシステムリソースがどれくらい 使用されているか、例えばユーザモードでの実行に費やされた時間やプロセス が主記憶からスワップアウトされた回数、を示しています。幾つかの値、 例えばプロセスが使用しているメモリ量は、内部時計の最小単位に依存します。

以前のバージョンとの互換性のため、返される値は 16 要素からなるタプル としてアクセスすることもできます。

戻り値のフィールド ru_utime および ru_stime は 浮動小数点数で、それぞれユーザモードでの実行に費やされた時間、および システムモードでの実行に費やされた時間を表します。それ以外の値は 整数です。これらの値に関する詳しい情報は getrusage(2) を調べてください。以下に簡単な概要を示します:

インデクス | フィールド名 | リソース
0 | ru_utime | ユーザモード実行時間 (float)
1 | ru_stime | システムモード実行時間 (float)
2 | ru_maxrss | 最大常駐ページサイズ
3 | ru_ixrss | 共有メモリサイズ
4 | ru_idrss | 非共有メモリサイズ
5 | ru_isrss | 非共有スタックサイズ
6 | ru_minflt | I/O を必要とするページフォールト数
7 | ru_majflt | I/O を必要としないページフォールト数
8 | ru_nswap | スワップアウト回数
9 | ru_inblock | ブロック入力操作数
10 | ru_oublock | ブロック出力操作数
11 | ru_msgsnd | 送信メッセージ数
12 | ru_msgrcv | 受信メッセージ数
13 | ru_nsignals | 受信シグナル数
14 | ru_nvcsw | 自発的な実行コンテキスト切り替え数
15 | ru_nivcsw | 非自発的な実行コンテキスト切り替え数

この関数は無効な who 引数を指定した場合には ValueError を送出します。また、異常が発生 した場合には error 例外が送出される可能性があります。

バージョン2.3 以降で変更された 仕様: 各値を返されたオブジェクトの属性としてアクセス できるようにしました

getpagesize( )
システムページ内のバイト数を返します。(ハードウェアページサイズと 同じとは限りません。) この関数はプロセスが使用しているメモリの バイト数を決定する上で有効です。getrusage() が 返すタプルの 3 つ目の要素はページ数で数えたメモリ使用量です; ページサイズを掛けるとバイト数になります。

以下の RUSAGE_* シンボルはどのプロセスの情報を提供させるか を指定するために関数 getrusage() に渡されます。

RUSAGE_SELF
RUSAGE_SELF はプロセス自体に属する情報を要求するために 使われます。

RUSAGE_CHILDREN
getrusage() に渡すと呼び出し側プロセスの子プロセスのリソース 情報を要求します。

RUSAGE_BOTH
getrusage() に渡すと現在のプロセスおよび子プロセスの両方が 消費しているリソースを要求します。全てのシステムで利用可能なわけでは ありません。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.15.1 リソースの制限 Up: 8.15 resource Next: 8.16 nis


8.16 nis -- Sun の NIS (Yellow Pages) へのインタフェース

利用可能な条件: UNIX.

nis モジュールは複数のホストを集中管理する上で便利な NIS ライブラリを薄くラップします。

NIS は Unix システム上にしかないので、このモジュールは Unixでしか利用できません。

nis モジュールでは以下の関数を定義しています:

match( key, mapname)
mapname 中で key に一致するものを返すか、見つからない 場合にはエラー (nis.error) を送出します。 両方の引数とも文字列で、 key は 8 ビットクリーンです。 返される値は (NULL その他を含む可能性のある) 任意のバイト配列 です。

mapname は他の名前の別名になっていないか最初にチェックされます。

cat( mapname)
match(key, mapname)==value となる key を value に対応付ける辞書を返します。 辞書内のキーと値は共に任意のバイト列なので注意してください。

mapname は他の名前の別名になっていないか最初にチェックされます。

maps( )
有効なマップのリストを返します。

nis モジュールは以下の例外を定義しています:

exception error
NIS 関数がエラーコードを返した場合に送出されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.15.2 リソースの使用状態 Up: 8. Unix独特のサービス Next: 8.17 syslog


8.17 syslog -- Unix syslog ライブラリルーチン群

利用可能な条件: Unix.

このモジュールでは Unix syslog ライブラリルーチン群への インタフェースを提供します。syslog の便宜レベルに関する詳細な記述 は Unix マニュアルページを参照してください。

このモジュールでは以下の関数を定義しています:

syslog( [priority,] message)
文字列 message をシステムログ機構に送信します。末尾の改行文字 は必要に応じて追加されます。各メッセージは facility および level からなる優先度でタグ付けされます。オプションの priority 引数はメッセージの優先度を定義します。標準の 値は LOG_INFO です。priority 中に、便宜レベルが (LOG_INFO | LOG_USER のように) 論理和を使ってコード化されて いない場合、openlog() を呼び出した際の値が使われます。

openlog( ident[, logopt[, facility]])
標準以外のログオプションは、syslog() の呼び出しに先立って openlog() でログファイルを開く際、明示的に設定することができます。 標準の値は (通常) indent = 'syslog'、 logopt = 0、facility = LOG_USER です。 ident 引数は全てのメッセージの先頭に付加する文字列です。 オプションの logopt 引数はビットフィールドの値になります - とりうる組み合わせ値については以下を参照してください。 オプションの facility 引数は、便宜レベルコードの設定が 明示的になされていないメッセージに対する、標準の便宜レベルを設定します。

closelog( )
ログファイルを閉じます。

setlogmask( maskpri)
優先度マスクを maskpri に設定し、以前のマスク値を返します。 maskpri に設定されていない優先度レベルを持った syslog() の呼び出しは無視されます。標準では全ての優先度をログ出力します。 関数 LOG_MASK(pri) は個々の優先度 pri に対する 優先度マスクを計算します。関数 LOG_UPTO(pri) は優先度 pri までの全ての優先度を含むようなマスクを計算します。

このモジュールでは以下の定数を定義しています:

優先度 (高い優先度順):

LOG_EMERG、 LOG_ALERT、 LOG_CRIT、 LOG_ERR、 LOG_WARNING、 LOG_NOTICE、 LOG_INFO、 LOG_DEBUG。

便宜レベル:

LOG_KERN、 LOG_USER、 LOG_MAIL、 LOG_DAEMON、 LOG_AUTH、 LOG_LPR、 LOG_NEWS、 LOG_UUCP、 LOG_CRON、および LOG_LOCAL0 から LOG_LOCAL7。

ログオプション:

<syslog.h> で定義されている場合、 LOG_PID、 LOG_CONS、 LOG_NDELAY、 LOG_NOWAIT、および LOG_PERROR。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.16 nis Up: 8. Unix独特のサービス Next: 8.18 commands


8.18 commands -- コマンド実行ユーティリティ

利用可能な条件: Unix.

commandsは、システムへコマンド文字列を渡して実行する os.popen()のラッパー関数を含んでいるモジュールです。 外部で実行したコマンドの結果や、その終了ステータスを扱います。

commandsモジュールは以下の関数を定義しています。

getstatusoutput( cmd)
文字列cmdをos.popen()を使いシェル上で実行し、 タプル(status, output)を返します。 実際には{ cmd ; } 2>&1と実行されるため、 標準出力とエラー出力が混合されます。 また、出力の最後の改行文字は取り除かれます。 コマンドの終了ステータスはC言語関数のwait()の規則に従って 解釈することができます。

getoutput( cmd)
getstatusoutput()に似ていますが、 終了ステータスは無視され、コマンドの出力のみを返します。

getstatus( file)
"ls -ld file"の出力を文字列で返します。 この関数はgetoutput()を使い、引数内の バックスラッシュ記号「 [image] 」とドル記号「$」を適切にエスケープします。

例:

>>> import commands
>>> commands.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> commands.getstatusoutput('cat /bin/junk')
(256, 'cat: /bin/junk: No such file or directory')
>>> commands.getstatusoutput('/bin/junk')
(256, 'sh: /bin/junk: not found')
>>> commands.getoutput('ls /bin/ls')
'/bin/ls'
>>> commands.getstatus('/bin/ls')
'-rwxr-xr-x  1 root        13352 Oct 14  1994 /bin/ls'

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.17 syslog Up: 8. Unix独特のサービス Next: 9. Pythonデバッガ


9. Pythonデバッガ

モジュールpdbはPythonプログラム用の対話的ソースコードデバッガを定義します。(条件付き)ブレークポイントの設定やソース行レベルでのシングルステップ実行、スタックフレームのインスペクション、ソースコードリスティングおよびいかなるスタックフレームのコンテキストにおける任意のPythonコードの評価をサポートしています。事後解析デバッギングもサポートし、プログラムの制御下で呼び出すことができます。

デバッガは拡張可能です -- 実際にはクラスPdbとして定義されています。現在これについてのドキュメントはありませんが、ソースを読めば簡単に理解できます。拡張インターフェースはモジュールbdb(ドキュメントなし)とcmdを使っています。

デバッガのプロンプトは"(Pdb) "です。デバッガに制御された状態でプログラムを実行するための典型的な使い方は:

>>> import pdb
>>> import mymodule
>>> pdb.run('mymodule.test()')
> <string>(0)?()
(Pdb) continue
> <string>(1)?()
(Pdb) continue
NameError: 'spam'
> <string>(1)?()
(Pdb)

他のスクリプトをデバッグするために、pdb.pyをスクリプトとして呼び出すこともできますせます。例えば:

python /usr/local/lib/python1.5/pdb.py myscript.py

クラッシュしたプログラムを調べるための典型的な使い方は:

>>> import pdb
>>> import mymodule
>>> mymodule.test()
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
  File "./mymodule.py", line 4, in test
    test2()
  File "./mymodule.py", line 3, in test2
    print spam
NameError: spam
>>> pdb.pm()
> ./mymodule.py(3)test2()
-> print spam
(Pdb)

モジュールは以下の関数を定義しています。それぞれが少しづつ違った方法でデバッガに入ります:

run( statement[, globals[, locals]])
デバッガに制御された状態で(文字列として与えられた)statementを実行します。デバッガプロンプトはあらゆるコードが実行される前に現れます。ブレークポイントを設定し、"continue"とタイプできます。あるいは、文を"step"や"next"を使って一つづつ実行することができます(これらのコマンドはすべて下で説明します)。オプションのglobalsとlocals引数はコードを実行する環境を指定します。デフォルトでは、モジュール__main__の辞書が使われます。(exec文またはeval()組み込み関数の説明を参照してください。)

runeval( expression[, globals[, locals]])
デバッガの制御もとで(文字列として与えられる)expressionを評価します。runeval()がリターンしたとき、式の値を返します。その他の点では、この関数はrun()を同様です。

runcall( function[, argument, ...])
function(関数またはメソッドオブジェクト、文字列ではありません)を与えられた引数とともに呼び出します。runcall()がリターンしたとき、関数呼び出しが返したものは何でも返します。デバッガプロンプトは関数に入るとすぐに現れます。

set_trace( )
スタックフレームを呼び出したところでデバッガに入ります。たとえコードが別の方法でデバッグされている最中でなくても(例えば、アサーションが失敗するとき)、これはプログラムの所定の場所でブレークポイントをハードコードするために役に立ちます。

post_mortem( traceback)
与えられたtracebackオブジェクトの事後解析デバッギングに入ります。

pm( )
sys.last_tracebackのトレースバックの事後解析デバッギングに入ります。

  • 9.1 デバッガコマンド
  • 9.2 どのように動作しているか
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 8.18 commands Up: Python ライブラリリファレンス Next: 9.1 デバッガコマンド


9.1 デバッガコマンド

デバッガは以下のコマンドを認識します。ほとんどのコマンドは一文字または二文字に省略することができます。例えば、"h(elp)"が意味するのは、ヘルプコマンドを入力するために"h"か"help"のどちらか一方を使うことができるということです(が、"he"や"hel"は使えず、また"H"や"Help"、"HELP"も使えません)。コマンドの引数は空白(スペースまたはタブ)で区切られなければなりません。オプションの引数はコマンド構文の角括弧("[]")の中に入れなければなりません。角括弧をタイプしてはいけません。コマンド構文における選択肢は垂直バー("|")で区切られます。

空行を入力すると入力された直前のコマンドを繰り返します。例外: 直前のコマンドが"list"コマンドならば、次の11行がリストされます。

デバッガが認識しないコマンドはPython文とみなして、デバッグしているプログラムのコンテキストおいて実行されます。Python文は感嘆符("!")を前に付けることもできます。これはデバッグ中のプログラムを調査する強力な方法です。変数を変更したり関数を呼び出したりすることさえ可能です。このような文で例外が発生した場合には例外名がプリントされますが、デバッガの状態は変化しません。

複数のコマンドを";;"で区切って一行で入力することができます。(一つだけの";"は使われません。なぜなら、Pythonパーサへ渡される行内の複数のコマンドのための分離記号だからです。)コマンドを分割するために何も知的なことはしていません。たとえ引用文字列の途中であっても、入力は最初の";;"対で分割されます。

デバッガはエイリアスをサポートします。エイリアスはパラメータを持つことができ、調査中のコンテキストに対して人がある程度柔軟に対応できます。

ファイル.pdbrcはユーザのホームディレクトリか、またはカレントディレクトリにあります。それはまるでデバッガのプロンプトでタイプしたかのように読み込まれて実行されます。これは特にエイリアスのために便利です。両方のファイルが存在する場合、ホームディレクトリのものが最初に読まれ、そこに定義されているエイリアスはローカルファイルにより上書きされることがあります。

h(elp) [command]

引数なしでは、利用できるコマンドの一覧をプリントします。引数としてcommandがある場合は、そのコマンドについてのヘルプをプリントします。"help pdb"は完全ドキュメンテーションファイルを表示します。環境変数PAGERが定義されているならば、代わりにファイルはそのコマンドへパイプされます。command引数が識別子でなければならないので、"!"コマンドについてのヘルプを得るためには"help exec"と入力しなければならない。

w(here)

スタックの底にある最も新しいフレームと一緒にスタックトレースをプリントします。矢印はカレントフレームを指し、それがほとんどのコマンドのコンテキストを決定します。

d(own)

(より新しいフレームに向かって)スタックトレース内でカレントフレームを一レベル下げます。

u(p)

(より古いフレームに向かって)スタックトレース内でカレントフレームを一レベル上げます。

b(reak) [[filename:]lineno|function[, condition]]

lineno引数がある場合は、現在のファイルのその場所にブレークポイントを設定します。function引数がある場合は、その関数の中の最初の実行可能文にブレークポイントを設定します。別のファイル(まだロードされていないかもしれないもの)のブレークポイントを指定するために、行番号はファイル名とコロンをともに先頭に付けられます。 ファイルはsys.pathにそって検索されます。各ブレークポイントは番号を割り当てられ、その番号を他のすべてのブレークポイントコマンドが参照することに注意してください。

If a second argument is present, it is an expression which must evaluate to true before the breakpoint is honored. 二番目の引数がある場合は、それはブレークポイントがhonor(???)される前に真と評価しなければならない式です。

引数なしの場合は、それぞれのブレークポイントに対して、そのブレークポイントに行き当たった回数、現在の通過カウント(ignore count)と、もしあれば関連条件を含めてすべてのブレークポイントをリストします。

tbreak [[filename:]lineno|function[, condition]]

一時的なブレークポイントで、最初にそこに達したときに自動的に取り除かれます。引数はbreakと同じです。

cl(ear) [bpnumber [bpnumber ...]]

スペースで区切られたブレークポイントナンバーのリストを与えると、それらのブレークポイントを解除します。引数なしの場合は、すべてのブレークポイントを解除します(が、はじめに確認します)。

disable [bpnumber [bpnumber ...]]

スペースで区切られたブレークポイントナンバーのリストとして与えられるブレークポイントを無効にします。ブレークポイントを無効にすると、プログラムの実行を止めることができなくなりますが、ブレークポイントの解除と違いブレークポイントのリストに残ったままになり、(再び)有効にすることができます。

enable [bpnumber [bpnumber ...]]

指定したブレークポイントを有効にします。

ignore bpnumber [count]

与えられたブレークポイントナンバーに通過カウントを設定します。countが省略されると、通過カウントは0に設定されます。通過カウントがゼロになったとき、ブレークポイントが機能する状態になります。ゼロでないときは、そのブレークポイントが無効にされず、どんな関連条件も真に評価されていて、ブレークポイントに来るたびにcountが減らされます。

condition bpnumber [condition]

conditionはブレークポイントがhonored(???)する前に真に評価しなければならない式です。conditionがない場合は、どんな既存の条件も取り除かれます。すなわち、ブレークポイントに条件がありません。

s(tep)

現在の行を実行し、最初に実行可能なものがあらわれたときに(呼び出された関数の」中か、現在の関数の次の行で)停止します.

n(ext)

現在の関数の次の行に達するか、あるいは関数が返るまで実行を継続します。("next"と"step"の差は"step"が呼び出された関数の内部で停止するのに対し、"next"は呼び出された関数を(ほぼ)全速力で実行し、現在の関数内の次の行で停止するだけです。

r(eturn)

現在の関数が返るまで実行を継続します。

c(ont(inue))

ブレークポイントに出会うまで、実行を継続します。

j(ump) lineno

次に実行する行を指定します。最も底のフレーム中でのみ実行可能です。 前に戻って実行したり、不要な部分をスキップして先の処理を実行する 場合に使用します。

ジャンプには制限があり、例えば forループの中には飛び込めませんし、 finally節の外にも飛ぶ事ができません。

l(ist) [first[, last]]

現在のファイルのソースコードをリスト表示します。引数なしの場合は、現在の行の周囲を11行リストするか、または前のリストの続きを表示します。引数が一つある場合は、その行の周囲を11行表示します。引数が二つの場合は、与えられた範囲をリスト表示します。第二引数が第一引数より小さいときは、カウントと解釈されます。

a(rgs)

現在の関数の引数リストをプリントします。

p expression

現在のコンテキストにおいてexpressionを評価し、その値をプリントします。(注意: "print"も使うことができますが、デバッガコマンドではありません -- これはPythonのprint文を実行します。)

pp expression

pprintモジュールを使って例外の値が整形されることを除いて"p"コマンドと同様です。

alias [name [command]]

nameという名前のcommandを実行するエイリアスを作成します。コマンドは引用符で囲まれていてはいけません。入れ替え可能なパラメータは"%1"、"%2"などで指し示され、さらに"%*"は全パラメータに置き換えられます。コマンドが与えられなければ、nameに対する現在のエイリアスを表示します。引数が与えられなければ、すべてのエイリアスがリストされます。

エイリアスは入れ子になってもよく、pdbプロンプトで合法的にタイプできるどんなものでも含めることができます。内部pdbコマンドをエイリアスによって上書きすることができます。そのとき、このようなコマンドはエイリアスが取り除かれるまで隠されます。エイリアス化はコマンド行の最初の語へ再帰的に適用されます。行の他のすべての語はそのままです。

例として、二つの便利なエイリアスがあります(特に.pdbrcファイルに置かれたときに):

#Print instance variables (usage "pi classInst")
alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k]
#Print instance variables in self
alias ps pi self

unalias name

指定したエイリアスを削除します。

[!]statement

現在のスタックフレームのコンテキストにおいて(一行の)statementを実行します。文の最初の語がデバッガコマンドと共通でない場合は、感嘆符を省略することができます。グローバル変数を設定するために、同じ行に"global"コマンドとともに代入コマンドの前に付けることができます。

(Pdb) global list_options; list_options = ['-l']
(Pdb)

q(uit)

デバッガを終了します。実行しているプログラムは中断されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 9. Pythonデバッガ Up: 9. Pythonデバッガ Next: 9.2 どのように動作しているか


9.2 どのように動作しているか

いくつかの変更がインタプリタへ加えられました:

  • sys.settrace(func)がグローバルトレース関数を設定します
  • そこで、ローカルトレース関数を使うこともできます(後ろを参照)

トレース関数は三つの引数を持ちます: frame、eventおよびarg。frameは現在のスタックフレームです。eventは文字列です: 'call'、'line'、'return'または'exception'。argはイベント型に依存します。

新しいローカルスコープに入ったときはいつでも、グローバルトレース関数が('call'に設定されたeventとともに)呼び出されます。そのスコープで用いられるローカルトレース関数への参照を返すか、またはスコープがトレースされるべきでないならばNoneを返します。

ローカルトレース関数はそれ自身への(あるいは、さらにそのスコープ内でさらにトレースを行うための他の関数への)参照を返します。または、そのスコープにおけるトレースを停止させるためにNoneを返します。

トレース関数としてインスタンスメソッドが受け入れられます(また、とても便利です)。

イベントは以下のような意味を持ちます:

'call'
関数が呼び出されます(または、他のコードブロックに入ります)。グローバルトレース関数が呼び出されます。argはNoneです。戻り値はローカルトレース関数を指定します。

'line'
インタプリタがコードの新しい行を実行しようとしているところです(ときどき、一行に複数行イベントが存在します)。ローカルトレース関数が呼び出されます。argはNoneです。戻り値は新しいローカルトレース関数を指定します。

'return'
関数(または、コードブロック)が返ろうとしているところです。ローカルトレース関数が呼び出されます。argは返るであろう値です。トレース関数の戻り値は無視されます。

'exception'
例外が生じています。ローカルトレース関数が呼び出されます。argは三要素の(exception, value, traceback)です。戻り値は新しいローカルトレース関数を指定します。

例外が一連の呼び出し元を伝えられて行くときに、'exception'イベントは各レベルで生成されることことに注意してください。

コードとフレームオブジェクトについてさらに情報を得るには、Python Reference Manualを参照してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 9.1 デバッガコマンド Up: 9. Pythonデバッガ Next: 10. Python プロファイラ


10. Python プロファイラ

Copyright © 1994, by InfoSeek Corporation, all rights reserved.

Written by James Roskind.10.1

Permission to use, copy, modify, and distribute this Python software and its associated documentation for any purpose (subject to the restriction in the following sentence) without fee is hereby granted, provided that the above copyright notice appears in all copies, and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of InfoSeek not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. This permission is explicitly restricted to the copying and modification of the software to remain in Python, compiled Python, or other languages (such as C) wherein the modified or derived code is exclusively imported into a Python module.

INFOSEEK CORPORATION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INFOSEEK CORPORATION BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

このプロファイラは私が Python プログラミングを始めてからわずか3週間後 に書いたものです。その結果、稚拙なコードが出来上がってしまったのかもし れませんが、なにせ私はまだ初心者なのでそれもよくわかりません :-) コー ドはプロファイリングにふさわしいスピードを実現することに心血を注ぎまし た。しかし部分的な繰り返しを避けたため、かなり不格好になってしまったと ころがあります。改善のための意見があれば、ぜひ jar@netscape.com までメールをください。サポートの 約束 はできませんが...フィードバックへの感謝だけは確実にいたします。

... Roskind.10.1
アップデートと LATEX への変換は Guido van Rossum によるもの。テキスト中に古いプロファイラのリファレン スも残してありますが、そのコードはもう含まれていません。

  • 10.1 プロファイラとは
  • 10.2 旧バージョンのプロファイラとの違い
  • 10.3 インスタント・ユーザ・マニュアル
  • 10.4 決定論的プロファイリングとは何か?
  • 10.5 リファレンス・マニュアル
    • 10.5.1 Stats クラス
  • 10.6 制限事項
  • 10.7 キャリブレーション(補正)
  • 10.8 拡張 -- プロファイラの改善
  • 10.9 hotshot -- ハイパフォーマンス・ロギング・プロファイラ
    • 10.9.1 プロファイル・オブジェクト
    • 10.9.2 hotshot データの利用
    • 10.9.3 使用例
  • 10.10 timeit -- 小さなコード断片の実行時間計測
    • 10.10.1 コマンドライン・インターフェース
    • 10.10.2 使用例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 9.2 どのように動作しているか Up: Python ライブラリリファレンス Next: 10.1 プロファイラとは


10.1 プロファイラとは

プロファイラとは、プログラム実行時の様々な状態を得ることにより、 その実行効率を調べるためのプログラムです。ここで解説するのは、 profile と pstats モジュールが提供するプロファイラ機 能についてです。このプロファイラはどの Python プログラムに対しても 決定論的プロファイリングをおこないます。また、プロファイルの結果 検証をす早くおこなえるよう、レポート生成用のツールも提供されています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10. Python プロファイラ Up: 10. Python プロファイラ Next: 10.2 旧バージョンのプロファイラとの違い


10.2 旧バージョンのプロファイラとの違い

(この節は歴史的資料としてのみ意味を持っています。ここで述べている旧バー ジョンのプロファイラとは Python 1.1. 以前のものを指しています)

旧バージョンのプロファイリングモジュールとの大きな違いは、より少ない CPU 時間で、より多くの情報が得られるようになったことです。CPU 時間と情 報量のトレードオフではなく、トレードアップを実現したのです。

主な内容は次の通りです。

バグ修正:
ローカル・スタック・フレームの扱いに関する不具合を修 正し、関数の実行時間を正しく計上するようにしました。

正確さの向上:
プロファイラ自体の実行時間をユーザコード側に計上 してしまうことがなくなりました。プラットフォーム毎のキャリブレーション (補正)をサポートし、プロファイラがプロファイル中にファイ ルの読み込みをおこなわないようにしました(当然その時間をユーザコードの ものとして計上することもなくなりました)。

スピードアップ:
2つ以上の(たぶん5つ)の点を改善した結果、CPU の 負荷が減りました。プロファイリング中はレポート生成用モジュール (pstats) を使う必要がないため、軽いプロファイラモジュールだけ を常時ロードするようにしました。

再帰的な関数のサポート:
再帰エントリのカウントにより、再帰関数 内で処理に費やされる時間が正確に計算されるようになりました。

レポート生成ユーザインターフェースの大幅な改善:

統計データを読み込む関数は任意の数のファイル名のリストを受け取り、独立 した複数のプロファイル結果を合わせて総合的なレポートが作成できるように なりました。ソートの基準はキーワードで指定できるようになりました(4つの 整数オプションを除く)。レポートはどのプロファイル・ファイルが参照され たかと同様に、どの関数がプロファイルされたかを示すようになりました。 そのほか出力形式は改善もおこなわれています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.1 プロファイラとは Up: 10. Python プロファイラ Next: 10.3 インスタント・ユーザ・マニュアル


10.3 インスタント・ユーザ・マニュアル

この節は ``マニュアルなんか読みたくない人''のために書かれています。こ こではきわめて簡単な概要説明とアプリケーションのプロファイリングを手っ とり早くおこなう方法だけを解説します。

main エントリにある関数 "foo()" をプロファイルしたいとき、モジュー ルに次の内容を追加します。

import profile
profile.run('foo()')

このように書くことで "foo()" を実行すると同時に一連の情報(プロファ イル)が表示されます。この方法はインタプリタ上で作業をしている場合、最 も便利なやり方です。プロファイルの結果をファイルに残し、後で検証したい ときは、run() の2番目の引数にファイル名を指定します。

import profile
profile.run('foo()', 'fooprof')

スクリプトファイル profile.py を使って、別のスクリプトをプロファ イルすることも可能です。次のように実行します。

python /usr/local/lib/python1.5/profile.py myscript.py

プロファイル内容を確認するときは、pstats モジュールのメソッド を使用します。統計データの読み込みは次のようにします。

import pstats
p = pstats.Stats('fooprof')

Stats クラス(上記コードはこのクラスのインスタンスを生成するだ けの内容です)は "p" に読み込まれたデータを操作したり、表示するた めの各種メソッドを備えています。先に profile.run() を実行し たとき表示された内容と同じものは、3つのメソッド・コールにより実現でき ます。

p.strip_dirs().sort_stats(-1).print_stats()

最初のメソッドはモジュール名からファイル名の前に付いているパス部分を取 り除きます。2番目のメソッドはエントリをモジュール名/行番号/名前にもと づいてソートします(旧プロファイラとの構文上の互換性機能)。3番目のメソッ ドで全ての統計情報を出力します。次のようなソート・メソッドも使えます。

p.sort_stats('name')
p.print_stats()

最初の行ではリストを関数名でソートしています。2号目で情報を出力してい ます。さらに次の内容も試してください。

p.sort_stats('cumulative').print_stats(10)

このようにすると、関数が消費した累計時間でソートされ、さらにその上位10 件だけを表示します。どのアルゴリズムが時間を多く消費しているのか知りた いときは、この方法が役に立つはずです。

ループで多くの時間を消費している関数はどれか調べたいときは、次のように します。

p.sort_stats('time').print_stats(10)

上記は関数の実行で消費した時間でソートされ、上位10個の関数の情報が表示 されます。

次の内容も試してください。

p.sort_stats('file').print_stats('__init__')

このようにするとファイル名でソートされ、そのうちクラスの初期化メソッド (メソッド名 "__init__")に関する統計情報だけが表示されます。

p.sort_stats('time', 'cum').print_stats(.5, 'init')

上記は情報を時間 (time) をプライマリ・キー、累計時間 (cumulative time) をセカンダリ・キーにしてソートした後でさらに条件を絞って統計情報を出力 します。 ".5" は上位 50% だけの選択を意味し、さらにその中から 文字列 init を含むものだけが表示されます。

どの関数がどの関数を呼び出しているのかを知りたければ、次のようにします ("p" は最後に実行したときの状態でソートされています)。

p.print_callers(.5, 'init')

このようにすると、各関数ごとの呼出し側関数の一覧が得られます。

さらに詳しい機能を知りたければマニュアルを読むか、次の関数の実行結果 から内容を推察してください。

p.print_callees()
p.add('fooprof')

スクリプトとして起動した場合、pstats モジュールはプロファイル のダンプを読み込み、分析するための統計ブラウザとして動きます。シンプル な行指向のインターフェース(cmd を使って実装)とヘルプ機能を 備えています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.2 旧バージョンのプロファイラとの違い Up: 10. Python プロファイラ Next: 10.4 決定論的プロファイリングとは何か?


10.4 決定論的プロファイリングとは何か?

決定論的プロファイリングとは、すべての 関数呼出し、関数からのリターン、例外発生をモニターし、正確なタイミングを 記録することで、イベント間の時間、つまりどの時間にユーザ・コードが実行 されているのかを計測するやり方です。もう一方の統計学的プロファイ リング(このモジュールでこの方法は採用していません)とは、有効なインス トラクション・ポインタからランダムにサンプリングをおこない、プログラム のどこで時間が使われているかを推定する方法です。後者の方法は、オーバヘッ ドが少いものの、プログラムのどこで多くの時間が使われているか、その相対 的な示唆に留まります。

Python の場合、実行中必ずインタプリタが動作するため、決定論的プロファ イリングをおこなうにあたり、計測用のコードは必須ではありません。Python は自動的に各イベントにフック(オプションとしてコールバック)を提供 します。Python インタプリタの特性として、大きなオーバーヘッドを伴う傾 向がありますが、一般的なアプリケーションに決定論的プロファイリングを用 いると、プロセスのオーバーヘッドは少くて済む傾向があります。結果的に決 定論的プロファイリングは少ないコストで、Python プログラムの実行時間に 関する統計を得られる方法となっているのです。

呼出し回数はコード中のバグ発見にも使用できます(とんでもない数の呼出し がおこなわれている部分)。インライン拡張の対象とすべき部分を見つけるた めにも使えます(呼出し頻度の高い部分)。内部時間の統計は、注意深く最適化 すべき``ホット・ループ''の発見にも役立ちます。累積時間の統計は、アルゴ リズム選択に関連した高レベルのエラー検知に役立ちます。なお、このプロファ イラは再帰的なアルゴリズム実装の累計時間を計ることが可能で、通常のルー プを使った実装と直接比較することもできるようになっています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.3 インスタント・ユーザ・マニュアル Up: 10. Python プロファイラ Next: 10.5 リファレンス・マニュアル


10.5 リファレンス・マニュアル

プロファイラのプライマリ・エントリ・ポイントはグローバル関数 profile.run() です。通常、プロファイル情報の作成に使われま す。情報は pstats.Stats クラスのメソッドを使って整形や出力をお こないます。以下はすべての標準エントリポイントと関数の解説です。さらに いくつかのコードの詳細を知りたければ、「プロファイラの拡張」を読んでく ださい。派生クラスを使ってプロファイラを``改善''する方法やモジュールの ソースコードの読み方が述べられています。

run( string[, filename[, ...]])

この関数はオプション引数として exec 文に渡すファイル名を指定 できます。このルーチンは必ず最初の引数の exec を試み、実行結 果からプロファイル情報を収集しようとします。ファイル名が指定されていな いときは、各行の標準名(standard name)文字列(ファイル名/行数/関数名)で ソートされた、簡単なレポートが表示されます。以下はその出力例です。

      main()
      2706 function calls (2004 primitive calls) in 4.504 CPU seconds

Ordered by: standard name

ncalls  tottime  percall  cumtime  percall filename:lineno(function)
     2    0.006    0.003    0.953    0.477 pobject.py:75(save_objects)
  43/3    0.533    0.012    0.749    0.250 pobject.py:99(evaluate)
 ...

最初の行はこのプロファイルが profile.run('main()') の呼び出しに よって生成されたものであり、実行された文字列は 'main()' である ことを示しています。2行目は2706回の関数呼出しがあったことを示していま す。このうち2004回はプリミティブなものです。プリミティブ な呼 び出しとは、再帰によるものではない関数呼出しを指します。次の行 Ordered by: standard name は、一番右側の欄の文字列を使ってソー トされたことを意味します。各カラムの見出しの意味は次の通りです。

ncalls

呼出し回数

tottime

この関数が消費した時間の合計(サブ関数呼出しの時間は除く)

percall

tottime を ncalls で割った値

cumtime

サブ関数を含む関数の(実行開始から終了までの)消費時間の合計。この項目は 再帰的な関数においても正確に計測されます。

percall

cumtime をプリミティブな呼び出し回数で割った値

filename:lineno(function)

その関数のファイル名、行番号、関数名

("43/3" など)最初の欄に2つの数字が表示されている場合、最初の値は 呼出し回数、2番目はプリミティブな呼び出しの回数を表しています。関数が再 帰していない場合はどちらの回数も同じになるため、1つの数値しか表示され ません。

プロファイラ・データの分析は pstats モジュールを使っておこな います。

class Stats( filename[, ...])
このコンストラクタは filename で指定した(単一または複数の)ファイ ルから``統計情報オブジェクト''のインスタンスを生成します。 Stats オブジェクトはレポートを出力するメソッドを通じて操作しま す。

上記コンストラクタで指定するファイルは、使用する Stats に対応 したバージョンの profile で作成されたものでなければなりません。 将来のバージョンのプロファイラとの互換性は保証されておらず、(旧 バージョンのものなど)他のプロファイラとの互換性もないことに注意してく ださい。

複数のファイルを指定した場合、同一の関数の統計情報はすべて合算され、複 数のプロセスで構成される全体をひとつのレポートで検証することが可能にな ります。既存の Stats オブジェクトに別のファイルの情報を追加す るときは、add() メソッドを使用します。

  • 10.5.1 Stats クラス
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.4 決定論的プロファイリングとは何か? Up: 10. Python プロファイラ Next: 10.5.1 Stats クラス


10.5.1 Stats クラス

Stats には次のメソッドがあります。

strip_dirs( )

このメソッドは Stats にファイル名の前に付いているすべてのパス 情報を取り除かせるためのものです。出力の幅を80文字以内に収めたいときに 重宝します。このメソッドはオブジェクトを変更するため、取り除いたパス情 報は失われます。パス情報除去の操作後、オブジェクトが保持するデータエント リは、オブジェクトの初期化、ロード直後と同じように``ランダムに''並んで います。strip_dirs() を実行した結果、2つの関数名が区別できな い(両者が同じファイルの同じ行番号で同じ関数名となった)場合、一つのエン トリに合算されされます。

add( filename[, ...])

Stats クラスのこのメソッドは、既存のプロファイリング・オブジェ クトに情報を追加します。引数は対応するバージョンの profile.run() によって生成されたファイルの名前でなくてはな りません。関数の名前が区別できない(ファイル名、行番号、関数名が同じ)場 合、一つの関数の統計情報として合算されます。

dump_stats( filename)
Stats オブジェクトに読み込まれたデータを、ファイル名 filename のファイルに保存します。ファイルが存在しない場合 新たに作成され、すでに存在する場合には上書きされます。 このメソッドは profile.Profile クラスの同名のメソッドと 等価です。 バージョン2.3 以降で新規追加された 仕様です。

sort_stats( key[, ...])

このメソッドは Stats オブジェクトを指定した基準に従ってソート します。引数には通常ソートのキーにしたい項目を示す文字列を指定します (例: 'time' や'name' など)。

2つ以上のキーが指定された場合、2つ目以降のキーは、それ以前のキーで同等 となったデータエントリの再ソートに使われます。たとえば "sort_stats('name', 'file')" とした場合、まずすべてのエントリが関 数名でソートされた後、同じ関数名で複数のエントリがあればファイル名でソー トされるのです。

キー名には他のキーと判別可能である限り綴りを省略して名前を指定できます。 現バージョンで定義されているキー名は以下の通りです。

正式名 | 内容
'calls' | 呼び出し回数
'cumulative' | 合計時間
'file' | ファイル名
'module' | モジュール名
'pcalls' | プリミティブな呼び出しの回数
'line' | 行番号
'name' | 関数名
'nfl' | 関数名/ファイル名/行番号
'stdname' | 標準名
'time' | 内部時間

すべての統計情報のソート結果は降順(最も多く時間を消費したものが一番上 に来る)となることに注意してください。ただし、関数名、ファイル名、行数 に関しては昇順(アルファベット順)になります。'nfl' と 'stdname' はやや異なる点があります。標準名(standard name)とは表 示欄の名前なのですが、埋め込まれた行番号の文字コード順でソートされます。 たとえば、(ファイル名が同じで)3、20、40という行番号のエントリがあった 場合、20、30、40 の順に表示されます。一方 'nfl' は行番号を数値 として比較します。結果的に、sort_stats('nfl') は sort_stats('name', 'file', 'line') と指定した場合と同じになりま す。

旧バージョンのプロファイラとの互換性のため、数値を引数に使った -1、 0、 1、 2 の形式もサポートしています。 それぞれ 'stdname'、'calls'、'time'、 'cumulative' として処理されます。引数をこの旧形式で指定した場合、 最初のキー(数値キー)だけが使われ、複数のキーを指定しても2番目以降は無 視されます。

reverse_order( )

Stats クラスのこのメソッドは、オブジェクト内の情報のリストを逆 順にソートします。これは旧プロファイラとの互換性のために用意されていま す。現在は選択したキーに応じて昇順、降順が適切に選ばれるため、このメソッ ドの必要性はほとんどないはずです。

print_stats( [restriction, ...])

Stats クラスのこのメソッドは、profile.run() の項で 述べた プロファイルのレポートを出力します。

出力するデータの順序はオブジェクトに対し最後におこなった sort_stats() による操作にもとづいたものになります (add() と strip_dirs() による制限にも支配されます)。

引数は一覧に大きな制限を加えることになります。初期段階でリストはプロファ イルした関数の完全な情報を持っています。制限の指定は(行数を指定する)整 数、(行のパーセンテージを指定する) 0.0 から 1.0 までの割合を指定する小 数、(出力する standard name にマッチする)正規表現のいずれかを使ってお こないます。正規表現は Python 1.5b1 で導入された re モジュー ルで使える Perl スタイルのものです。複数の制限は指定された場合、それは 指定の順に適用されます。たとえば次のようになります。

print_stats(.1, 'foo:')

上記の場合まず出力するリストは全体の10%に制限され、さらにファイル名の 一部に文字列 ".*foo:" を持つ関数だけが出力されます。

print_stats('foo:', .1)

こちらの例の場合、リストはまずファイル名に ".*foo:" を持つ関数だ けに制限され、その中の最初の 10% だけが出力されます。

print_callers( [restriction, ...])

Stats クラスのこのメソッドは、プロファイルのデータベースの中か ら何らかの関数呼び出しをおこなった関数すべてを出力します。出力の順序は print_stats() によって与えられるものと同じです。出力を制限す る引数も同じです。呼出し側関数の後にパーレンで囲まれて表示される数値は 呼出しが何回おこなわれたかを示すものです。続いてパーレンなしで表示され る数値は、関数が消費した時間の合計です。

print_callees( [restriction, ...])

Stats クラスのこのメソッドは指定した関数から呼出された関数のリ ストを出力します。呼出し側、呼出される側の方向は逆ですが、引数と出力の 順序に関しては print_callers() と同じです。

ignore( )
リリース 1.5.1 以降で撤廃された仕様です。 現バージョンの Python のPython では不要です。10.2

... では不要です。10.2
Python が None 以外の使われなかった結果を表示するときに使われ たもので、旧バージョンとの互換性のためだけに定義されています。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.5 リファレンス・マニュアル Up: 10.5 リファレンス・マニュアル Next: 10.6 制限事項


10.6 制限事項

このプロファイラには2つの基本的な制限事項があります。ひとつは、Python インタプリタによる 呼び出し、リターン、例外発生 とい うイベントの連携を前提にしていることです。コンパイル済みの C コード はインタプリタの管理外で、プロファイラからは``見えません''。(組込み関 数を含む) C のコードに費やされた時間は、その C コードを呼出した Python 関数のものとして計上されることになります。ただし C コードが Python のコードを呼び出す場合は、適切にプロファイルされます。

2つ目の制限はタイミング情報の正確さに関するものです。決定論的プロファ イラの正確さに関する根本的問題です。最も明白な制限は、(一般に)``クロッ ク''は .001 秒の精度しかないということです。これ以上の精度で計測するこ とはできません。仮に充分な精度が得られたとしても、``エラー''が計測の平 均値に影響を及ぼすことがあります。最初のエラーを取り除いたとしても、そ れがまた別のエラーを引き起こす原因となり...。

もうひとつの問題として、イベントを検知してからプロファイラがその時刻を 実際に取得するまでに ``いくらかの時間がかかる'' ことです。プロ ファイラが時刻を取得する(そしてその値を保存する)までの間に、ユーザコー ドがもう一度処理を実行したときにも、同様の遅延が発生します。結果的に多 く呼び出される関数または多数の関数から呼び出される関数の情報にはこの種 のエラーが蓄積する傾向にあります。

この種のエラーによる遅延の蓄積は一般にクロックの精度を越える(1クロック 以下のタイミング)ところで起きていますが、一方でこの時間を累計可 能ということが大きな意味を持っています。このプロファイラはプラットフォー ムごとに(平均値から)予想されるエラーによる遅延を補正する機能を備えてい ます。プロファイラに補正を施すと(少くとも形式的には)正確さが増しますが、 ときには数値が負の値になってしまうこともあります(呼出し回数が少く、確 率の神があなたに意地悪をしたとき :-) )。プロファイルの結果に負の値が出 力されても驚かないでください。これは補正をおこなった場合にのみ 現れることで、実際の計測結果は補正をおこなわない場合より、より正確なは ずだからです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.5.1 Stats クラス Up: 10. Python プロファイラ Next: 10.7 キャリブレーション(補正)


10.7 キャリブレーション(補正)

プロファイラは イベントをハンドリングの際の time 関数呼出しおよびその 値を保存するためのオーバーヘッドを補正するための、定数を持っています。 デフォルトの値は 0 です。以下の手順で、プラットフォームに合った、より 適切な定数が得られます(前節「制限事項」の説明を参照)。

import profile
pr = profile.Profile()
for i in range(5):
    print pr.calibrate(10000)

メソッドは引数として与えられた数だけ Python の呼出しをおこないます。呼 出しは直接、プロファイラを使って呼出しの両方が実施され、それぞれの時間 が計測されます。その結果、プロファイラのイベントに隠されたオーバーヘッ ドが計算され、その値は浮動小数として返されます。たとえば、800 MHz の Pentium で Windows 2000 を使用、Python の time.clock() をタイマとして 使った場合、値はおよそ 12.5e-6 となります。

この手順で使用しているオブジェクトはほぼ一定の結果を返します。非 常に早いコンピュータを使う場合、もしくはタイマの性能が貧弱な場合は一 定の結果を得るために引数に 100000 や 1000000 といった大きな値を指定す る必要があるかもしれません。

一定の結果が得られたら、それを使う方法には3通りあります。10.3

import profile

# 1. 算出した補正値 (your_computed_bias) をこれ以降生成する
#    Profile インスタンスに適用する。
profile.Profile.bias = your_computed_bias

# 2. 特定の Profile インスタンスに補正値を適用する。
pr = profile.Profile()
pr.bias = your_computed_bias

# 3. インスタンスのコンストラクタに補正値を指定する。
pr = profile.Profile(bias=your_computed_bias)

方法を選択したら、補正値は小さめに設定した方が良いでしょう。プロファイ ルの結果に負の値が表われる``確率が少なく''なるはずです。

...一定の結果が得られたら、それを使う方法には3通りあります。10.3
Python 2.2 より前のバージョンではプロファイラのソースコードに補正値と して埋め込まれた定数を直接編集する必要がありました。今でも同じことは可 能ですが、その方法は説明しません。なぜなら、もうソースを編集する必要が ないからです。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.6 制限事項 Up: 10. Python プロファイラ Next: 10.8 拡張


10.8 拡張 -- プロファイラの改善

profile モジュールの Profile クラスはプロファイラの機 能を拡張するため、派生クラスの作成を前提に書かれています。しかしその方 法を説明するには、Profile の内部動作について詳細な解説が必要と なるため、ここでは述べません。もし拡張をおこないたいのであれば、 profile モジュールのソースを注意深く読む必要があります。

プロファイラが時刻を取得する方法を変更したいだけなら(たとえば、通常の 時間(wall-clock)を使いたいとか、プロセスの経過時間を使いたい場合)、時 刻取得用の関数を Profile クラスのコンストラクタに指定すること ができます。

pr = profile.Profile(your_time_func)

この結果生成されるプロファイラは時刻取得に your_time_func() を 呼び出すようになります。このようなユーザ定義関数は単一の数値、あるいは その合計が(os.times() と同じように)累計時間を示すリストを返 すようになっていなければなりません。関数が1つの数値、あるいは長さ2の数 値のリストを返すようになっていれば、非常に高速に処理が可能になります。

選択する時刻取得関数によって、プロファイラクラスを補正する必要があるこ とに注意してください。多くのマシンにおいて、プロファイル時のオーバヘッ ドを少なくする方法として、タイマはロング整数を返すのが最善です。 os.times() は浮動小数のタプルを返すので おすすめできま せん)。タイマをより正確なものに置き換えたいならば、派生クラスでそのディ スパッチ・メソッドを適切なタイマ呼出しと適切な補正をおこなうように書き 直す必要があります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.7 キャリブレーション(補正) Up: 10. Python プロファイラ Next: 10.9 hotshot


10.9 hotshot -- ハイパフォーマンス・ロギング・プロファイラ

バージョン2.2 以降で新規追加された 仕様です。

このモジュールは _hotshot C モジュールへのより良いインターフェー スを提供します。Hotshot は既存の profile に置き換わるもの です。その大半が C で書かれているため、profile に比べパフォー マンス上の影響がはるかに少なく済みます。

class Profile( logfile[, lineevents=0[, linetimings=1]])

プロファイラ・オブジェクト。引数 logfile はプロファイル・データ のログを保存するファイル名です。引数 lineevents はソースコー ドの1 行ごとにイベントを発生させるか、関数の呼び出し/リターンのときだ け発生させるかを指定します。デフォルトの値は 0 (関数の呼び出し/ リターンのときだけログを残す)です。引数 linetimings は時間情報を 記録するかどうかを指定します。デフォルトの値は 1 (時間情報を記 録する)です。

  • 10.9.1 プロファイル・オブジェクト
  • 10.9.2 hotshot データの利用
  • 10.9.3 使用例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.8 拡張 Up: 10. Python プロファイラ Next: 10.9.1 プロファイル・オブジェクト


10.9.1 プロファイル・オブジェクト

プロファイル・オブジェクトは以下のメソッドを持っています。

addinfo( key, value)
プロファイル出力の際、任意のラベル名を追加します。

close( )
ログファイルを閉じ、プロファイラを終了します。

fileno( )
プロファイラのログファイルのファイル・ディスクリプタを返します。

run( cmd)
スクリプト環境で exec 互換文字列のプロファイルをおこないます。 __main__ モジュールのグローバル変数は、スクリプトの グローバル変数、ローカル変数の両方に使われます。

runcall( func, *args, **keywords)
単一の呼び出し可能オブジェクトのプロファイルをおこないます。位置依存引 数やキーワード引数を追加して呼び出すオブジェクトに渡すこともできます。 呼び出しの結果はそのまま返されます。例外が発生したときはプロファイリン グが無効になり、例外をそのまま伝えるようになっています。

runctx( cmd, globals, locals)

指定した環境で exec 互換文字列の評価をおこないます。文字列の コンパイルはプロファイルを開始する前におこなわれます。

start( )
プロファイラを開始します。

stop( )
プロファイラを停止します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.9 hotshot Up: 10.9 hotshot Next: 10.9.2 hotshot データの利用


10.9.2 hotshot データの利用

バージョン2.2 以降で新規追加された 仕様です。

このモジュールは hotshot プロファイル・データを標準の pstats オブジェクトにロードします。

load( filename)
filename から hotshot データを読み込み、pstats.Stats ク ラスのインスタンスを返します。

参考資料:

profileモジュール:
profile モジュールの Stats クラス.

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.9.1 プロファイル・オブジェクト Up: 10.9 hotshot Next: 10.9.3 使用例


10.9.3 使用例

これは Python の``ベンチマーク'' pystone を使った例です。実行にはやや 時間がかかり、巨大な出力ファイルを生成するので注意してください。

>>> import hotshot, hotshot.stats, test.pystone
>>> prof = hotshot.Profile("stones.prof")
>>> benchtime, stones = prof.runcall(test.pystone.pystones)
>>> prof.close()
>>> stats = hotshot.stats.load("stones.prof")
>>> stats.strip_dirs()
>>> stats.sort_stats('time', 'calls')
>>> stats.print_stats(20)
         850004 function calls in 10.090 CPU seconds

   Ordered by: internal time, call count

   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
        1    3.295    3.295   10.090   10.090 pystone.py:79(Proc0)
   150000    1.315    0.000    1.315    0.000 pystone.py:203(Proc7)
    50000    1.313    0.000    1.463    0.000 pystone.py:229(Func2)
 .
 .
 .
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.9.2 hotshot データの利用 Up: 10.9 hotshot Next: 10.10 timeit


10.10 timeit -- 小さなコード断片の実行時間計測

バージョン2.3 以降で新規追加された 仕様です。

このモジュールは Python の小さなコード断片の時間を簡単に計測する手段を 提供します。インターフェースはコマンドラインとメソッドとして呼び出し可 能なものの両方を備えています。また、このモジュールは実行時間の計測にあ たり陥りがちな落し穴に対する様々な対策が取られています。詳しくは、 O'Reilly の Python Cookbook、``Algorithms'' の章にある Tim Peters が書いた解説を参照してください。

このモジュールには次のパブリック・クラスが定義されています。

class Timer( [stmt='pass' [, setup='pass' [, timer=<timer function>]]])

小さなコード断片の実行時間計測をおこなうためのクラスです。

コンストラクタは引数として、時間計測の対象となる文、セットアップに使用 する追加の文、タイマ関数を受け取ります。文のデフォルト値は両方とも 'pass' で、タイマ関数はプラットフォーム依存(モジュールの doc string を参照)です。文には複数行の文字列リテラルを含まない限り、改行を 入れることも可能です。

最初の文の実行時間を計測には timeit() メソッドを使用します。
また timeit() を複数回呼び出し、その結果のリストを返す
repeat() メソッドも用意されています。

print_exc( [file=None])
計測対象コードのトレースバックを出力するためのヘルパー。

利用例:

    t = Timer(...)       # try/except の外側で
    try:
        t.timeit(...)    # または t.repeat(...)
    except:
        t.print_exc()

標準のトレースバックより優れた点は、コンパイルしたテンプレートのソース 行が表示されることです。オプションの引数 file にはトレースバック の出力先を指定します。デフォルトは sys.stderr になっています。

repeat( [repeat=3 [, number=1000000]])
timeit() を複数回呼び出します。

このメソッドは timeit() を複数回呼び出し、その結果をリストで
返すユーティリティ関数です。最初の引数には timeit() を呼び出
す回数を指定します。2番目の引数は timeit() へ引数として渡す
数値です。

注意:

結果のベクトルから平均値や標準偏差を計算して出力させたいと思うかもしれ ませんが、それはあまり意味がありません。多くの場合、最も低い値がそのマ シンが与えられたコード断片を実行する場合の下限値です。結果のうち高めの 値は、Python のスピードが一定しないために生じたものではなく、時刻取得 の際他のプロセスと衝突がおこったため、正確さが損なわれた結果生じたもの です。したがって、結果のうち min() だけが見るべき値となりま す。この点を押さえた上で、統計的な分析よりも常識的な判断で結果を見るよ うにしてください。

timeit( [number=1000000])

メイン文の実行時間を number 回取得します。このメソッドはセットアッ プ文を1回だけ実行し、メイン文を指定回数実行するのにかかった秒数を浮動 小数で返します。引数はループを何回実行するかの指定で、デフォルト値は 100万回です。メイン文、セットアップ文、タイマ関数はコンストラクタで指 定されたものを使用します。

  • 10.10.1 コマンドライン・インターフェース
  • 10.10.2 使用例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.9.3 使用例 Up: 10. Python プロファイラ Next: 10.10.1 コマンドライン・インターフェース


10.10.1 コマンドライン・インターフェース

コマンドラインからプログラムとして呼び出す場合は、次の書式を使います。

python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]

以下のオプションが使用できます。

-n N/--number=N
'statement' を何回実行するか
-r N/--repeat=N
タイマを何回リピートするか(デフォルトは 3)
-s S/--setup=S
最初に1回だけ実行する文 (デフォルトは 'pass')
-t/--time
time.time() を使用する (Windows を除くすべてのプラットフォームのデフォルト)
-c/--clock
time.clock() を使用する(Windows のデフォルト)
-v/--verbose
時間計測の結果をそのまま詳細な数値でくり返し表示する
-h/--help
簡単な使い方を表示して終了する

文は複数行指定することもできます。その場合、各行は独立した文として引数 に指定されたものとして処理します。クォートと行頭のスペースを使って、イ ンデントした文を使うことも可能です。この複数行のオプションは -s においても同じ形式で指定可能です。

オプション -n でループの回数が指定されていない場合、10回 から始めて、所要時間が 0.2 秒になるまで回数を増やすことで適切なループ 回数が自動計算されるようになっています。

デフォルトのタイマ関数はプラットフォーム依存です。Windows の場合、 time.clock() はマイクロ秒の精度がありますが、 time.time() は 1/60 秒の精度しかありません。一方 Unixの場 合、time.clock() でも 1/100 秒の精度があり、 time.time() はもっと正確です。いずれのプラットフォームにお いても、デフォルトのタイマ関数は CPU 時間ではなく通常の時間を返します。 つまり、同じコンピュータ上で別のプロセスが動いている場合、タイミングの 衝突する可能性があるということです。正確な時間を割り出すために最善の方 法は、時間の取得を数回くり返しその中の最短の時間を採用することです。 -r オプションはこれをおこなうもので、デフォルトのくり返し 回数は3回になっています。多くの場合はデフォルトのままで充分でしょう。 Unixの場合 time.clock() を使って CPU 時間で測定することも できます。

注意: pass 文の実行による基本的なオーバーヘッドが存在することに注意してく ださい。ここにあるコードはこの事実を隠そうとはしておらず、注意を払う 必要があります。基本的なオーバーヘッドは引数なしでプログラムを起動す ることにより計測できます。

基本的なオーバヘッドは Python のバージョンによって異なります。Python 2.3 とそれ以前の Python の公平な比較をおこなう場合、古い方の Python は -O オプションで起動し SET_LINENO 命令の実行時間が 含まれないようにする必要があります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.10 timeit Up: 10.10 timeit Next: 10.10.2 使用例


10.10.2 使用例

以下に2つの使用例を記載します(ひとつはコマンドライン・インターフェース によるもの、もうひとつはモジュール・インターフェースによるものです)。 内容はオブジェクトの属性の有無を調べるのに hasattr() を使っ た場合と try/except を使った場合の比較です。

% timeit.py 'try:' '  str.__nonzero__' 'except AttributeError:' '  pass'
100000 loops, best of 3: 15.7 usec per loop
% timeit.py 'if hasattr(str, "__nonzero__"): pass'
100000 loops, best of 3: 4.26 usec per loop
% timeit.py 'try:' '  int.__nonzero__' 'except AttributeError:' '  pass'
1000000 loops, best of 3: 1.43 usec per loop
% timeit.py 'if hasattr(int, "__nonzero__"): pass'
100000 loops, best of 3: 2.23 usec per loop

>>> import timeit
>>> s = """\
... try:
...     str.__nonzero__
... except AttributeError:
...     pass
... """
>>> t = timeit.Timer(stmt=s)
>>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
17.09 usec/pass
>>> s = """\
... if hasattr(str, '__nonzero__'): pass
... """
>>> t = timeit.Timer(stmt=s)
>>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
4.85 usec/pass
>>> s = """\
... try:
...     int.__nonzero__
... except AttributeError:
...     pass
... """
>>> t = timeit.Timer(stmt=s)
>>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
1.97 usec/pass
>>> s = """\
... if hasattr(int, '__nonzero__'): pass
... """
>>> t = timeit.Timer(stmt=s)
>>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
3.15 usec/pass

定義した関数に timeit モジュールがアクセスできるように するために、import 文の入った setup 引数を渡すことができます:

def test():
    "Stupid test function"
    L = []
    for i in range(100):
        L.append(i)

if __name__=='__main__':
    from timeit import Timer
    t = Timer("test()", "from __main__ import test")
    print t.timeit()

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.10.1 コマンドライン・インターフェース Up: 10.10 timeit Next: 11. インターネットプロトコルとその支援


11. インターネットプロトコルとその支援

この章で記述されるモジュールは、インターネットプロトコルと 関連技術の支援を実装します。それらは全てPythonで実装されています。 これらのモジュールの大部分は、システム依存のモジュール socketが存在することが必要ですが、 これは現在ではほとんどの一般的なプラットフォーム上でサポート されています。ここに概観を示します。

webbrowser | ウェウブブラウザーのための使い易いコントローラー
cgi | サーバ側で動作するスクリプトにおいてフォームの内容を 解釈するために使われるゲートウェイインタフェース規格のサポート。
cgitb | 設定可能な、CGI スクリプトのトレースバック処理機構です。
urllib | URL による任意のネットワークリソースへのアクセス (socket が必要です)。
urllib2 | 様々なプロトコルで URL を開くための拡張可能なライブラリ
httplib | HTTP および HTTPS プロトコルのクライアント (ソケットを必要とします) 。
ftplib | FTPプロトコルクライアント(ソケットを必要とします)。
gopherlib | gopher プロトコルのクライアント (ソケットを必要とします)。
poplib | POP3 プロトコルクライアント (socketsを必要とする)
imaplib | IMAP4 protocol client (requires sockets).
nntplib | NNTP プロトコルクライアント (ソケットを必要とします)。
smtplib | SMTP プロトコル クライアント (ソケットが必要です)。
telnetlib | Telnet クライアントクラス
urlparse | URL を解析して構成要素にします。
SocketServer | ネットワークサーバ構築のためのフレームワーク。
BaseHTTPServer | 基本的な機能を持つ HTTP サーバ (SimpleHTTPServer および CGIHTTPServer の基底クラス)。
SimpleHTTPServer | このモジュールは HTTP サーバに基本的なリクエストハンドラを提供します。
CGIHTTPServer | CGI スクリプトの実行機能を持つ HTTP サーバのためのリクエスト処理機構を提供します。
Cookie | HTTP状態管理(cookies)のサポート.
xmlrpclib | XML-RPC client access.
SimpleXMLRPCServer | 基本的なXML-RPCサーバーの実装。
DocXMLRPCServer | セルフ-ドキュメンティング XML-RPC サーバの実装。
asyncore | 非同期なソケット制御サービスのためのベースクラス
asynchat | 非同期コマンド/レスポンスプロトコルの開発サポート

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 10.10.2 使用例 Up: Python ライブラリリファレンス Next: 11.1 webbrowser


11.1 webbrowser -- 便利なウェブブラウザコントローラー

webbrowserモジュールにはウェブベースのドキュメントを表示するための、とてもハイレベルなインターフェースが定義されています。 このコントローラーオブジェクトは使い易く、プラットフォーム非依存です。 たいていの環境では、このモジュールのopen()を呼び出すだけで正しく 動作します。

Unixでは、X11上でグラフィカルなブラウザが選択されますが、グラフィカルなブ ラウザが利用できなかったり、X11が利用できない場合はテキストモードのブラウザ が使われます。 もしテキストモードのブラウザが使われたら、ユーザがブラウザから抜け出すまでプ ロセスの呼び出しはブロックされます。

Unixでは、環境変数BROWSERが存在するならプラットフォームのデフォ ルトであるブラウザのリストをオーバーライドし、コロンで区切られたリストの順に ブラウザの起動を試みます。 リストの中の値に%sが含まれていたら、テキストモードのブラウザのコマン ドラインとして%sの代わりにURLが引数として解釈されます； もし%sが含まれなければ、起動するブラウザの名前として単純に解釈されま す。

非UnixプラットフォームあるいはUnix上でX11ブラウザが利用可能な場合、制 御プロセスはユーザがブラウザを終了するのを待ちませんが、ディスプレイにブラウ ザのウィンドウを表示させたままにします。

以下の例外が定義されています：

exception Error
ブラウザのコントロールエラーが起こると発生する例外。

以下の関数が定義されています：

open( url[, new=0][, autoraise=1])
デフォルトのブラウザでurlを表示します。 newがtrueなら、可能であればブラウザの新しいウィンドウが開きます。 autoraiseがtrueなら、可能であればウィンドウが前面に表示されます（多く のウィンドウマネージャではこの変数の設定に関わらず、前面に表示されます）。

open_new( url)
可能であれば、デフォルトブラウザの新しいウィンドウでurlを開きますが、 そうでない場合はブラウザのただ１つのウィンドウでurlを開きます。

get( [name])
ブラウザの種類nameのコントローラーオブジェクトを返します。 もしnameが空文字列なら、呼び出した環境に適したデフォルトブラウザのコン トローラーを返します。

register( name, constructor[, instance])
ブラウザの種類nameを登録します。 ブラウザの種類が登録されたら、get()でそのブラウザのコントローラー を呼び出すことができます。 instanceが指定されなかったり、Noneなら、インスタンスが必要な時 にはconstructorがパラメータなしに呼び出されて作られます。 instanceが指定されたら、constructorは呼び出されないので、 Noneでかまいません。

この登録は、変数BROWSERを設定するか、getを空文字列でな く、宣言したハンドラの名前と一致する引数とともに呼び出すときだけ、役に立ちま す。

いくつかの種類のブラウザがあらかじめ定義されています。 このモジュールで定義されている、関数get()に与えるブラウザの名前 と、それぞれのコントローラークラスのインスタンスを以下の表に示します。

Type Name | Class Name | Notes
'mozilla' | Netscape('mozilla') |
'netscape' | Netscape('netscape') |
'mosaic' | GenericBrowser('mosaic %s &') |
'kfm' | Konqueror() | (1)
'grail' | Grail() |
'links' | GenericBrowser('links %s') |
'lynx' | GenericBrowser('lynx %s') |
'w3m' | GenericBrowser('w3m %s') |
'windows-default' | WindowsDefault | (2)
'internet-config' | InternetConfig | (3)

Notes:

(1)
``Konqueror''はUnixのKDEデスクトップ環境のファイルマネージャで、KDEが動作 している時にだけ意味を持ちます。 何か信頼できる方法でKDEを検出するのがいいでしょう；変数KDEDIRでは十 分ではありません。 また、KDE 2でkonquerorコマンドを使うときにも、``kfm''が使われます -- Konquerorを動作させるのに最も良い方法が実装によって選択されます。

(2)
Windowsプラットフォームのみ；標準拡張モジュールwin32apiと win32conを必要とします。

(3)
MacOSプラットフォームのみ；Macintosh Library Modulesマニュアルに解説されている標準MacPythonモジュールic を必要とします。

  • 11.1.1 ブラウザコントローラーオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11. インターネットプロトコルとその支援 Up: 11. インターネットプロトコルとその支援 Next: 11.1.1 ブラウザコントローラーオブジェクト


11.1.1 ブラウザコントローラーオブジェクト

ブラウザコントローラーには２つのメソッドが定義されていて、モジュールレベルの 便利な２つの関数に相当します：

open( url[, new])
このコントローラーでハンドルされたブラウザでurlを表示します。 newがtrueなら、可能であればブラウザの新しいウィンドウが開きます。

open_new( url)
可能であれば、このコントローラーでハンドルされたブラウザの新しいウィンドウで urlを開きますが、そうでない場合はブラウザのただ１つのウィンドウで urlを開きます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.1 webbrowser Up: 11.1 webbrowser Next: 11.2 cgi


11.2 cgi -- CGI (ゲートウェイインタフェース規格) のサポート

ゲートウェイインタフェース規格 (CGI) に準拠したスクリプトを サポートするためのモジュールです。

このモジュールは Python で書かれた CGI スクリプトで使われる 数多くのユーティリティを定義しています。

  • 11.2.1 はじめに
  • 11.2.2 cgi モジュールを使う
  • 11.2.3 高レベルインタフェース
  • 11.2.4 古いクラス群
  • 11.2.5 関数
  • 11.2.6 セキュリティへの配慮
  • 11.2.7 CGI スクリプトを Unix システムにインストールする
  • 11.2.8 CGI スクリプトをテストする
  • 11.2.9 CGI スクリプトをデバッグする
  • 11.2.10 よくある問題と解決法
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.1.1 ブラウザコントローラーオブジェクト Up: 11. インターネットプロトコルとその支援 Next: 11.2.1 はじめに


11.2.1 はじめに

CGI スクリプトは、HTTP サーバによって起動され、通常は HTML の <FORM> または <ISINDEX> エレメントを通じてユーザ が入力した内容を処理するために使われます。

ほとんどの場合、CGI スクリプトはサーバ上の特殊な cgi-bin ディレクトリ下に置かれます。HTTP サーバはまずリクエストの全ての 情報 (クライアントのホスト名、リクエストされている URL、クエリ 文字列、その他諸々) をスクリプトを動作させるシェルの環境変数 に設定し、スクリプトを実行した後、スクリプトの出力をクライアント に送信します。

スクリプトの入力端もまたクライアントに接続されており、フォーム上の データは時としてこの経路を通じて読み出されます; その他の場合、 フォームデータは URL の一部分である ``クエリ文字列'' を介して 渡されます。このモジュールでは、上記のケースの違いに注意しながら Python スクリプトに対しては単純なインタフェースを提供するための ものです。このモジュールではまた、スクリプトをデバッグするための ユーティリティを多数提供しています。また、最近はフォームを 経由したファイルのアップロードをサポートしています (ブラウザ側 がサポートしていればです -- Grail 0.3 および Netscape 2.0 は サポートしています。)

CGI スクリプトの出力は 2 つのセクションからなり、空行で分割 されています。最初のセクションは複数のヘッダからなり、 後続するデータがどのようなものかをクライアントに通知します。 最小のヘッダセクションを生成するための Python のコードは 以下のようなものです:

print "Content-Type: text/html"     # HTML is following
print                               # blank line, end of headers

二つ目のセクションは通常、ヘッダやインラインイメージ等の付属した テキストをうまくフォーマットして表示できるようにした HTML です。 以下に単純な HTML を出力する Python コードを示します:

print "<TITLE>CGI script output</TITLE>"
print "<H1>This is my first CGI script</H1>"
print "Hello, world!"

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.2 cgi Up: 11.2 cgi Next: 11.2.2 cgi モジュールを使う


11.2.2 cgi モジュールを使う

先頭には "import cgi" と書いてください。"from cgi import *"と書いてはいけません -- このモジュールは以前のバージョンとの互換性を 持たせるために内部で呼び出すための名前を多数定義しており、それらが ユーザの名前空間に存在する必要はありません。

新たにスクリプトを各なら、以下の行を付け加えることを検討してください:

import cgitb; cgitb.enable()

これによって、特別な例外処理が有効にされ、エラーが発生した際にブラウザ 上に詳細な報告を出力するようになります。ユーザにスクリプトの内部を 見せたくないのなら、以下のようにして報告をファイルに保存することも できます:

import cgitb; cgitb.enable(display=0, logdir="/tmp")

スクリプトを開発する際には、この機能はとても役に立ちます。 cgitb が生成する報告はバグを追跡するために掛かる 時間を大きく減らせるような情報を提供してくれます。スクリプトを テストし終わり、正確に動作することを確認した後はいつでも cgitb の行を削除することができます。

入力されたフォームデータを取得するには、 FieldStorage クラス を使うのが最良の方法です。このモジュール定義されている他のクラスの ほとんどは以前のバージョンとの互換性のためのものです。 インスタンス生成は引数なしで必ず 1 度だけ行います。これにより、 標準入力または環境変数からフォームの内容が読み出されます (どちらから読み出されるかは、CGI 標準に従って設定されている 複数の環境変数の値によって決められます)。インスタンスが標準入力を 使うかもしれないので、インスタンス生成を行うのは一度だけにしなければ なりません。

FieldStorage のインスタンスは Python の辞書のようにインデクス 参照することができ、標準の辞書に対するメソッド has_key() と keys() をサポートしています。組み込みの関数 len() もサポートされています。空の文字列を含むフォームのフィールドは 無視され、辞書上にはありません; そういった値を保持するには、 FieldStorage のインスタンスを生成する時にオプションの keep_blank_values キーワード引数を true に設定してください。

例えば、以下のコード (Content-Type: ヘッダと空行は すでに出力された後とします) は name および addr フィールドが両方とも空の文字列に設定されていないか調べます:

form = cgi.FieldStorage()
if not (form.has_key("name") and form.has_key("addr")):
    print "<H1>Error</H1>"
    print "Please fill in the name and addr fields."
    return
print "<p>name:", form["name"].value
print "<p>addr:", form["addr"].value
...further form processing here...

ここで、"form[key]" で参照される各フィールドは それ自体が FieldStorage (または MiniFieldStorage 。フォームのエンコードによって変わります) のインスタンスです。 インスタンスの属性 value フィールドの文字列値になります。 getvalue() メソッドはこの文字列値を直接返します。 getvalue() は 2 つめの引数にオプションの値を与えることが でき、リクエストされたキーが存在しない場合に返されるデフォルトの 値になります。

入力されたフォームデータが同じ名前をもった 1 個以上のフィールドを持つ場合、 "form[key]" で得られるオブジェクトは FieldStorage や MiniFieldStorage のインスタンスではなく、それらインスタンスから なるリストになります。同じく、この状況では、 "form.getvalue(key)" は文字列を要素とするリストを返します。 もしこうした状況が起こりうると思われる (HTML のフォームに同じ名前をもった フィールドが複数含まれている) なら、組み込み関数 isinstance() を使って、返された値が単一のインスタンスかインスタンスのリストかを 調べてください。例えば、以下のコードは任意の数のユーザ名フィールドを 結合し、コンマで分割された文字列にします:

value = form.getvalue("username", "")
if isinstance(value, list):
    # Multiple username fields specified
    usernames = ",".join(value)
else:
    # Single or no username field specified
    usernames = value

フィールドがアップロードされたファイルを表す場合、value 属性または getvalue() メソッドを介してアクセスされた 値はファイルの内容を全て文字列としてメモリ上に読み込みます。 これは望ましくない機能かもしれません。アップロードされたファイルが あるかどうかは filename 属性および file 属性の いずれかで調べることができます。その後、以下のようにして file 属性から落ち着いてデータを読み出すことができます:

fileitem = form["userfile"]
if fileitem.file:
    # It's an uploaded file; count lines
    linecount = 0
    while 1:
        line = fileitem.file.readline()
        if not line: break
        linecount = linecount + 1

現在ドラフトとなっているファイルアップロードの標準仕様では、一つの フィールドから (再帰的な multipart/* エンコーディングを 使うことで) 複数のファイルがアップロードされる可能性を受け入れています。 この場合、アイテムは辞書形式の FieldStorage アイテムと なります。複数ファイルかどうかは type 属性が multipart/form-data (または multipart/* に マッチする他の MIME 型) になっているかどうか調べることで判別できます。 この場合、トップレベルのフォームオブジェクトと同様にして再帰的に 個別処理することができます。

フォームが ``古い'' 形式で入力された場合 (クエリ文字列または application/x-www-form-urlencoded データの単一の部分の場合) アイテムは実際には MiniFieldStorage クラスのインスタンス になります。この場合、list 、file 、および filename 属性は常に None になります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.2.1 はじめに Up: 11.2 cgi Next: 11.2.3 高レベルインタフェース


11.2.3 高レベルインタフェース

バージョン2.2 以降で新規追加された 仕様です。

前節では CGI フォームデータを FieldStorage クラスを使って 読み出す方法について解説しました。この節ではより分かりやすく直感的 な方法でフォームデータを読み出せるようにするために追加されたより 高レベルのインタフェースについて記述します。 このインタフェースは前節で記述された技術を廃用化するものでは ありません -- 例えば、前節の技術は依然としてファイルのアップロードを 効率的に行う上で便利です。

このインタフェースは 2 つの単純なメソッドからなります。このメソッドを 使うことで、一般的な方法でフォームデータを処理することができ、 一つのフォーム名についてポストされた値が一つなのかそれ以上なのか について心配する必要がなくなります。

前節では、一つのフォーム名に対して一つ以上の値がポストされる かもしれない場合には常に以下のようなコードを書くよう学びました:

item = form.getvalue("item")
if isinstance(item, list):
    # The user is requesting more than one item.
else:
    # The user is requesting only one item.

こういった状況は、例えば以下のように、同じ名前を持った複数の チェックボックスからなるグループがフォームに含まれているような場合に よく起こります:

<input type="checkbox" name="item" value="1" />
<input type="checkbox" name="item" value="2" />

しかしながら、ほとんどの場合あるフォーム中で特定の名前を持った コントロールはただ一つなので、その名前に関連付けられた値は ただ一つしかないと期待され、かつ一つの値しか必要ありません。 そこで、スクリプトには例えば以下のようなコードを書くでしょう:

user = form.getvalue("user").toupper()

このコードの問題点は、クライアント側がスクリプトに有効な入力 を提供すると期待できないところにあります。 例えば、もし好奇心旺盛なユーザがもう一つの "user=foo" ペア をクエリ文字列に追加したら、getvalue(``'user') メソッドを 呼び出したときに文字列ではなくリストが返されるため、このスクリプトは クラッシュするでしょう。 リストに対して toupper() メソッドを呼び出すと、引数が 有効でない (リスト型はその名前のメソッドを持っていない) ため、例外 AttributeError が送出されます。

従って、フォームデータに入力された値を読み出すための適切な方法は、 常に取得した値が単一の値からなるか、あるいは複数の値からなるか を調べるコードを使うことになります。これでは煩わしく、また、より 読みにくいスクリプトになってしまいます。

より便利なアプローチは、ここで述べる高レベルのインタフェースが 提供する getfirst() および getlist() メソッドを 使うことです。

getfirst( name[, default])
フォームフィールド name に関連付けられた値をつねに一つだけ 返す軽量メソッドです。このメソッドは同じ名前で 1 つ以上の値が ポストされた場合、最初の値だけを返します。フォームから値を受信する 際の値が並べられる順番はブラウザ間で異なる可能性があり、特定の順番 であるとは期待できないので注意してください。 11.1

指定したフォームフィールドや値がない場合、このメソッドはオプションの引数 default を返します。このパラメタを指定しない場合、標準の 値は None に設定されます。

getlist( name)
このメソッドはフォームフィールド name に関連付けられた値を 常にリストで返します。name に指定したフォームフィールドや値が 存在しない場合、このメソッドは空のリストを返します。値が一つだけ 存在する場合、要素を一つだけ含むリストを返します。

これらのメソッドを使うことで、以下のようにナイスでコンパクトな コードを書くことができます:

import cgi
form = cgi.FieldStorage()
user = form.getfirst("user", "").toupper()    # This way it's safe.
for item in form.getlist("item"):
    do_something(item)

... であるとは期待できないので注意してください。11.1
最近のバージョンの HTML 仕様では、フィールドの値が提供される 順番を取り決めてはいますが、ある HTTP リクエストがその取り決めに 従ったブラウザから受信したのかどうか、そもそもブラウザから送信 されたのかどうかの判別は退屈で間違いやすいので注意してください。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.2.2 cgi モジュールを使う Up: 11.2 cgi Next: 11.2.4 古いクラス群


11.2.4 古いクラス群

これらのクラスは、cgi モジュールの以前のバージョンに入って おり、以前のバージョンとの互換性のために現在もサポートされています。 新しいアプリケーションでは FieldStorage クラスを使うべきです。

SvFormContentDict は単一の値しか持たないフォームデータの内容 を辞書として記憶します; このクラスでは、各フィールド名はフォーム中に 一度しか現れないと仮定しています。

FormContentDict は複数の値を持つフォームデータの内容 を辞書として記憶します (フォーム要素は値のリストです); フォームが同じ名前を持ったフィールドを複数含む際に便利です。

他のクラス (FormContent、InterpFormContentDict) は 非常に古いアプリケーションとの後方互換性のために存在します。 これらのクラスをいまだに使っていて、個のモジュールの次のバージョンで 消えてしまったら非常に不便な場合は私に連絡を下さい。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.2.3 高レベルインタフェース Up: 11.2 cgi Next: 11.2.5 関数


11.2.5 関数

より細かくコントロールしたり、このモジュールで実装されている アルゴリズムを他の状況で利用したい場合には、これらの関数が 便利です。

parse( fp[, keep_blank_values[, strict_parsing]])
環境変数、またはファイルからからクエリを解釈します (ファイルは 標準で sys.stdin になります) keep_blank_values および strict_parsing パラメタはそのまま parse_qs() に 渡されます。

parse_qs( qs[, keep_blank_values[, strict_parsing]])
文字列引数として渡されたクエリ文字列 (application/x-www-form-urlencoded 型のデータ) を 解釈します。解釈されたデータは辞書として返されます。 辞書のキーは一意なクエリ変数名で、値は各変数名に対する値からなる リストです。

オプションの引数 keep_blank_values は、 URL エンコード されたクエリ中で値の入っていないものを空文字列と見なすかどうか を示すフラグです。値が真であれば、値の入っていないフィールド は空文字列のままになります。標準では偽で、値の入っていない フィールドは無視され、そのフィールドはクエリに含まれていない ものとして扱われます。

オプションの引数 strict_pasing はパース時のエラーをどう 扱うかを決めるフラグです。値が偽なら (標準の設定です)、 エラーは暗黙のうちに無視されます。値が真なら、ValueError 例外 が送出されます。

辞書等をクエリ文字列に変換する場合はurllib. urlencode()関数を使用してください。

parse_qsl( qs[, keep_blank_values[, strict_parsing]])
文字列引数として渡されたクエリ文字列 (application/x-www-form-urlencoded 型のデータ) を 解釈します。解釈されたデータは名前と値のペアからなるリストです。

オプションの引数 keep_blank_values は、 URL エンコード されたクエリ中で値の入っていないものを空文字列と見なすかどうか を示すフラグです。値が真であれば、値の入っていないフィールド は空文字列のままになります。標準では偽で、値の入っていない フィールドは無視され、そのフィールドはクエリに含まれていない ものとして扱われます。

オプションの引数 strict_pasing はパース時のエラーをどう 扱うかを決めるフラグです。値が偽なら (標準の設定です)、 エラーは暗黙のうちに無視されます。値が真なら、ValueError 例外 が送出されます。

ペアのリストからクエリ文字列を生成する場合は、urllib.urlencode() 関数を使用します。

parse_multipart( fp, pdict)
(ファイル入力のための) multipart/form-data 型の入力を 解釈します。引数は入力ファイルを示す fp と Content-Type: ヘッダ内の他のパラメタを含む辞書 pdict です。

parse_qs() と同じく辞書を返し、キーはフィールド名で、 対応する値は各フィールドの値によるリストです。この関数は簡単に 使うことができますが、数メガバイトのデータがアップロードされる と考えられる場合にはあまり適していません -- その場合、 より柔軟性のある FieldStorage を代りに使ってください。

マルチパートデータがネストしている場合、各パートを解釈する ことはできないので注意してください -- 代りに FieldStorage を使ってください。

parse_header( string)
(Content-Type: のような) MIME ヘッダを解釈し、ヘッダの 主要値と各パラメタからなる辞書にします。

test( )
メインプログラムから利用できる堅牢性テストを行う CGI スクリプトです。 最小の HTTP ヘッダと HTML フォームからスクリプトに提供された全ての 情報を書式化して出力します。

print_environ( )
シェル変数を HTML に書式化して出力します。

print_form( form)
フォームを HTML に初期化して出力します。

print_directory( )
現在のディレクトリを HTML に書式化して出力します。 Format the current directory in HTML.

print_environ_usage( )
意味のある (CGI の使う) 環境変数を HTML で出力します。

escape( s[, quote])
文字列 s 中の文字 "&"、 "<"、 および ">" を HTML で正しく表示できる文字配列に変換します。 それらの文字が HTML に含まれるかもしれないようなテキストを出力 する必要があるときに使ってください。 オプションの引数 quote がの値が真であれば、二重引用符文字 (""") も変換されます; この機能は、例えば <A HREF="..."> といったような HTML の属性値を出力に含めるのに 役立ちます。クオートされる値が単引用符か二重引用符、またはその両方 を含む可能性がある場合は、代りに xml.sax.saxutils の quoteattr() 関数の利用を検討してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.2.4 古いクラス群 Up: 11.2 cgi Next: 11.2.6 セキュリティへの配慮


11.2.6 セキュリティへの配慮

重要なルールが一つあります: ( 関数 os.system() または os.popen() 、またはその他の同様の機能によって ) 外部プログラムを呼び出すなら、クライアントから受信した任意の 文字列をシェルに渡していないことをよく確かめてください。 これはよく知られているセキュリティホールであり、これによって Web のどこかにいる悪賢いハッカーが、だまされやすい CGI スクリプトに任意の シェルコマンドを実行させることができてしまいます。URL の一部や フィールド名でさえも信用してはいけません。CGI へのリクエストは あなたの作ったフォームから送信されるとは限らないからです！

安全な方法をとるためには、フォームから入力さｒた文字をシェルに 渡す場合、文字列が英数文字、ダッシュ、アンダースコア、および ピリオドだけを含むことを確認してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.2.5 関数 Up: 11.2 cgi Next: 11.2.7 CGI スクリプトを Unix


11.2.7 CGI スクリプトを Unix システムにインストールする

あなたの使っている HTTP サーバのドキュメントを読んでください。そして ローカルシステムの管理者と一緒にどのディレクトリに CGI スクリプト をインストールすべきかを調べてください; 通常これはサーバのファイル システムツリー内の cgi-bin ディレクトリです。

あなたのスクリプトが ``others'' によって読み取り可能および実行可能 であることを確認してください; Unix ファイルモードは 8 進表記で 0755 です ("chmod 0755 filename" を使ってください)。 スクリプトの最初の行の 1 カラム目が、 #! で開始し、その後に Python インタプリタへのパス名が続いていることを確認してください。 例えば:

#!/usr/local/bin/python

Python インタプリタが存在し、``others'' によって実行可能であることを 確かめてください。

あなたのスクリプトが読み書きする必要があるファイルが全て ``others'' によってそれぞれ読み出し可能、書き込み可能である ことを確かめてください -- それらのファイルモードは読み出し可能 については 0644 で、書き込み可能については 0666 になるはずです。これは、セキュリティ上の理由から、 HTTP サーバが あなたのスクリプトを特権を全く持たないユーザ ``nobody'' の権限で 実行するからです。この権限下では、誰でもが読める (書ける、実行できる) ファイルしか読む (書く、実行する) ことができません。 スクリプト実行時のディレクトリや環境変数のセットもあなたがログイン したときの設定と異なります。特に、実行ファイルに対するシェルの 検索パス (PATH) や Python のモジュール検索パス (PYTHONPATH)が何らかの値に設定されていることを期待しては いけません。

モジュールを Python の標準設定におけるモジュール検索パス上にない ディレクトリからロードする必要がある場合、他のモジュールを取り込む 前にスクリプト内で検索パスを変更することができます。例えば:

import sys
sys.path.insert(0, "/usr/home/joe/lib/python")
sys.path.insert(0, "/usr/local/lib/python")

(この方法では、最後に挿入されたディレクトリが最初に検索されます！)

非 Unix システムにおける説明は変わるでしょう; あなたの使っている HTTP サーバのドキュメントを調べてください (普通は CGI スクリプトに 関する節があります)。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.2.6 セキュリティへの配慮 Up: 11.2 cgi Next: 11.2.8 CGI スクリプトをテストする


11.2.8 CGI スクリプトをテストする

残念ながら、一般的に CGI スクリプトはコマンドラインから起動しよう としても動かず、コマンドラインから起動した場合には完璧に動作する スクリプトが、不思議なことにサーバからの起動では失敗することが あります。しかし、スクリプトをコマンドラインから実行しなければ ならない理由が一つあります: もしスクリプトが文法エラーを含んで いれば、Python インタプリタはそのプログラムを全く実行しないため、 HTTP サーバはほとんどの場合クライアントに謎めいたエラーを送信 するからです。

スクリプトが構文エラーを含まないのにうまく動作しないなら、次の 節に読み進むしかありません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.2.7 CGI スクリプトを Unix Up: 11.2 cgi Next: 11.2.9 CGI スクリプトをデバッグする


11.2.9 CGI スクリプトをデバッグする

何よりもまず、些細なインストール関連のエラーでないか確認してください -- 上の CGI スクリプトのインストールに関する節を注意深く読むことで、 大きく時間を節約できます。もしインストールの手続きを正しく理解 しているか不安なら、このモジュールのファイル (cgi.py) をコピーして、CGI スクリプトとしてインストールしてみてください。 このファイルはスクリプトとして呼び出すと、スクリプトの実行環境と フォームの内容を HTML フォームに出力します。 正しいモードなどをフォームに与えて、リクエストを送ってみてください。 標準的な cgi-bin ディレクトリにインストールされていれば、 以下の形式でブラウザに URL を入力することで、リクエストを送ることが できるはずです:

http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home

もしタイプ 404 のエラーになるなら、サーバはスクリプトを見つける ことができていません - おそらくあなたはスクリプトを別のディレクトリ に入れる必要があるでしょう。他のエラーになるなら、先に進む前に 解決しなければならないインストール上の問題があります。 もしうまく書式化された実行環境の情報とフォーム内容 (この例では、 各フィールドはフィールド名 ``addr'' に対して値 ``At Home''、および フィールド名 ``name'' に対して ``Joe Blow'' ) になるなら、 cgi.py スクリプトは正しくインストールされています。 同じ操作をあなたの自作スクリプトに対して行えば、スクリプトをデバッグ できるようになるはずです。 　 次のステップでは cgi モジュールの test() 関数を 呼び出すことになります: メインプログラムコードを以下の 1 行、

cgi.test()

と置き換えてください。この操作で cgi.py ファイル自体を インストールした時と同じ結果を出力するはずです。

通常の Python スクリプトが unhandled exception 例外を送出する場合 (様々な理由: モジュール名のタイプミス、ファイルが開けなかった、など)、 Python インタプリタはナイスなトレースバックを出力して終了します。 Python インタプリタはあなたの CGI スクリプトが例外を送出した場合 にも同様にするので、大抵はトレースバックが HTTP サーバのいずれかの ログファイルに残るか、あるいはまったく無視されます。

幸運なことに、あなたが自作のスクリプトで 何らかの コードを 実行できるようになったら、cgitb モジュールを使って 簡単にトレースバックをブラウザに送信することができます。まだ そうでないなら、以下の一行:

import cgitb; cgitb.enable()

をスクリプトの先頭に追加してください。そしてスクリプトを再度 走らせます; 問題が発生すれば、クラッシュの原因を見出せるような 詳細な報告を読むことができます。

cgitb モジュールのインポートに問題がありそうだと 思うなら、(組み込みモジュールだけを使った) もっと堅牢なアプローチを 取ることができます:

import sys
sys.stderr = sys.stdout
print "Content-Type: text/plain"
print
...your code here...

このコードは Python インタプリタがトレースバックを出力することに 依存しています。出力のコンテント型はプレーンテキストに設定されて おり、全ての HTML 処理を無効にしています。スクリプトがうまく動作 する場合、生の HTML コードがクライアントに表示されます。スクリプト が例外を送出する場合、最初の 2 行が出力された後、トレースバックが 表示されます。HTML の解釈は行われないので、トレースバックを 読むことができるでしょう。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.2.8 CGI スクリプトをテストする Up: 11.2 cgi Next: 11.2.10 よくある問題と解決法


11.2.10 よくある問題と解決法

  • ほとんどの HTTP サーバはスクリプトの実行が完了するまで CGI からの 出力をバッファします。このことは、スクリプトの実行中にクライアントが 進捗状況報告を表示できないことを意味します。

  • 上のインストールに関する説明を調べましょう。

  • HTTP サーバのログファイルを調べましょう。(別のウィンドウで "tail -f logfile" を実行すると便利かもしれません！)

  • 常に "python script.py" などとして、スクリプトが構文エラーで ないか調べましょう。

  • スクリプトに構文エラーがないなら、"import cgitb; cgitb.enable()"をスクリプトの先頭に追加してみましょう。

  • 外部プログラムを起動するときには、スクリプトがそのプログラムを 見つけられるようにしましょう。これは通常、絶対パス名を使うことを 意味します -- PATH は普通、あまり CGI スクリプトにとって 便利でない値に設定されています。

  • 外部のファイルを読み書きする際には、CGI スクリプトを動作 させるときに使われる userid でファイルを読み書きできるように なっているか確認しましょう: userid は通常、Web サーバを動作させて いる userid か、Web サーバの "suexec" 機能で明示的に指定 している userid になります。

  • CGI スクリプトを set-uid モードにしてはいけません。これはほとんど のシステムで動作せず、セキュリティ上の信頼性もありません。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.2.9 CGI スクリプトをデバッグする Up: 11.2 cgi Next: 11.3 cgitb


11.3 cgitb -- CGI スクリプトのトレースバック管理機構

バージョン2.2 以降で新規追加された 仕様です。

cgitb モジュールでは、Python スクリプトのための特殊な例外処理を 提供します。(実はこの説明は少し的外れです。このモジュールはもともと 徹底的なトレースバック情報を CGI スクリプトで生成した HTML 内に表示 するための設計されました。その後この情報を平文テキストでも 表示できるように一般化されています。) このモジュールの有効化後に捕捉されない例外が生じた場合、 詳細で書式化された報告が Web ブラウザに送信されます。この報告には 各レベルにおけるソースコードの抜粋が示されたトレースバックと、現在動作 している関数の引数やローカルな変数が収められており、問題のデバッグを 助けます。オプションとして、この情報をブラウザに送信する代わりに ファイルに保存することもできます。

この機能を有効化するためには、単に自作の CGI スクリプトの最初に以下の一行を 追加します:

import cgitb; cgitb.enable()

enable() 関数のオプションは、報告をブラウザに表示するか どうかと、後で解析するためにファイルに報告をログ記録するかどうかを 制御します。

enable( [display[, logdir[, context [, format]]]])
この関数は、sys.excepthook を設定することで、 インタプリタの標準の例外処理を cgitb モジュールに肩代わり させるようにします。

オプションの引数 display は標準で 1 になっており、 この値は 0 にしてトレースバックをブラウザに送らないように抑制する こともできます。引数 logdir はログファイルを配置する ディレクトリです。オプションの引数 context は、トレースバック の中で現在の行の周辺の何行を表示するかです; この値は標準で 5 です。 オプションの引数 format が "html" の場合、出力は HTML に書式化されます。その他の値を指定すると平文テキストの出力を 強制します。デフォルトの値は "html" です。

handler( [info])
この関数は標準の設定 (ブラウザに報告を表示しますがファイルには ログを書き込みません) を使って例外を処理します。 この関数は、例外を捕捉した際に cgitb を使って報告 したい場合に使うことができます。 オプションの info 引数は、例外の型、例外の値、トレースバック オブジェクトからなる 3 要素のタプルでなければなりません。これは sys.exc_info() によって返される値と全く 同じです。info 引数が与えられていない場合、現在の 例外は sys.exc_info() から取得されます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.2.10 よくある問題と解決法 Up: 11. インターネットプロトコルとその支援 Next: 11.4 urllib


11.4 urllib -- URL による任意のリソースへのアクセス

このモジュールはワールドワイドウェブ (World Wide Web) を介してデータを 取り寄せるための高レベルのインタフェースを提供する。特に、関数 urlopen() は組み込み関数 open() と同様に動作し、 ファイル名の代わりにファイルユニバーサルリソースロケータ (URL) を 指定することができます。いくつかの制限はあります -- URL は読み出し 専用でしか開けませんし、seek 操作を行うことはできません。

このモジュールでは、以下の public な関数を定義します。

urlopen( url[, data[, proxies]])
URL で表されるネットワーク上のオブジェクトを読み込み用に開きます。 URL がスキーム識別子を持たないか、スキーム識別子が file: である場合、ローカルシステムのファイルが (広範囲の改行サポート なしで) 開かれます。それ以外の場合は ネットワーク上のどこかにあるサーバへのソケットを開きます。 接続を作ることができないか、サーバがエラーコードを返した場合、 例外 IOError が送出されます。全ての処理がうまくいけば、 ファイル類似のオブジェクトが返されます。このオブジェクトは以下の メソッド: read() 、 readline() 、 readlines() 、 fileno() 、 close() 、 info() そして geturl() をサポートします。 また、適切なイテレータプロトコルのサポートもしています。

info() および geturl() メソッドを除き、 これらのメソッドはファイルオブジェクトと同じインタフェースを持って います -- このマニュアルの 2.3.8 セクションを 参照してください。 (ですが、このオブジェクトは組み込みのファイル オブジェクトではないので、まれに真の組み込みファイルオブジェクトが 必要な場所では使うことができません)

info() メソッドは開いた URL に関連付けられたメタ情報 を含む mimetools.Message クラスのインスタンスを返します。 URL へのアクセスメソッドが HTTP である場合、メタ情報中の ヘッダ情報はサーバが HTML ページを返すときに先頭に付加するヘッダ 情報です (Content-Length および Content-Type を含みます) 。 アクセスメソッドが FTP の場合、ファイル取得リクエストに応答 してサーバがファイルの長さを返したときには (これは現在では普通に なりましたが) Content-Length ヘッダがメタ情報に含められます。 Content-type ヘッダは MIME タイプが推測可能なときにメタ情報に 含められます。アクセスメソッドがローカルファイルの場合、 返されるヘッダ情報にはファイルの最終更新日時を表す Date エントリ、 ファイルのサイズを示す Content-Length エントリ、そして推測される ファイル形式の Content-Type エントリが含まれます。 mimetoolsモジュールを 参照してください。

geturl() メソッドはページの実際の URL を返します。場合に よっては、HTTP サーバはクライアントの要求を他の URL に振り向け (redirect 、リダイレクト) します。 関数 urlopen() はユーザに対してリダイレクトを透過的に 行いますが、呼び出し側にとってクライアントがどの URL にリダイレクト されたかを知りたいときがあります。geturl() メソッドを 使うと、このリダイレクトされた URL を取得できます。

url に http: スキーム識別子を使う場合、data 引数を 与えて POST 形式のリクエストを行うことができます (通常リクエストの 形式は GET です)。引数 data は標準の application/x-www-form-urlencoded 形式でなければなりません; 以下の urlencode() 関数を参照してください。

urlopen() 関数は認証を必要としないプロキシ (proxy) に対して 透過的に動作します。Unix または Windows 環境では、 Python を起動 する前に、環境変数 http_proxy、 ftp_proxy 、および gopher_proxy にそれぞれのプロキシサーバを指定する URL を 設定してください。 例えば ("%" はコマンドプロンプトです):

% http_proxy="http://www.someproxy.com:3128"
% export http_proxy
% python
...

Windows 環境では、プロキシを指定する環境変数が設定されていない場合、 プロキシの設定値はレジストリの Internet Settings セクションから取得 されます。

Macintosh 環境では、urlopen() は 「インターネットの設定」 (InternetConfig) からプロキシ情報を取得します。

別の方法として、オプション引数 proxies を使って明示的にプロキシを 設定することができます。この引数はスキーム名をプロキシの URL にマップする 辞書型のオブジェクトでなくてはなりません。空の辞書を指定するとプロキシを 使いません。None (デフォルトの値です) を指定すると、上で述べた ように環境変数で指定されたプロキシ設定を使います。例えば:

# http://www.someproxy.com:3128 を http プロキシに使う
proxies = proxies={'http': 'http://www.someproxy.com:3128'}
filehandle = urllib.urlopen(some_url, proxies=proxies)
# プロキシを使わない
filehandle = urllib.urlopen(some_url, proxies={})
# 環境変数からプロキシを使う - 両方の表記とも同じ意味です。
filehandle = urllib.urlopen(some_url, proxies=None)
filehandle = urllib.urlopen(some_url)

(訳注: 上記と矛盾する内容です。おそらく旧バージョンのドキュメントです) 関数 urlopen() は明示的なプロキシ指定をサポートしていません。 環境変数のプロキシ設定を上書きしたい場合には URLopener を使う か、FancyURLopener などのサブクラスを使ってください。

認証を必要とするプロキシは現在のところサポートされていません。 これは実装上の制限 (implementation limitation) と考えています。

バージョン2.3 以降で変更された 仕様: proxies のサポートを追加しました。

urlretrieve( url[, filename[, reporthook[, data]]])
URL で表されるネットワーク上のオブジェクトを、必要に応じてローカルな ファイルにコピーします。URL がローカルなファイルを指定していたり、 オブジェクトのコピーが正しくキャッシュされていれば、そのオブジェクトは コピーされません。タプル (filename, headers) を 返し、filename はローカルで見つかったオブジェクトに対する ファイル名で、headers は urlopen() が返した (おそらくキャッシュされているリモートの) オブジェクトに info() を適用して得られるものになります。 urlopen() と同じ例外を送出します。

2 つめの引数がある場合、オブジェクトのコピー先となるファイルの位置を 指定します (もしなければ、ファイルの場所は一時ファイル (tmpfile) の 置き場になり、名前は適当につけられます)。 3 つめの引数がある場合、ネットワークとの接続が確立された際に一度 呼び出され、以降データのブロックが読み出されるたびに呼び出されるフック 関数 (hook function) を指定します。フック関数には 3 つの引数が渡され ます; これまで転送されたブロック数のカウント、バイト単位で表された ブロックサイズ、ファイルの総サイズです。3 つ目のファイルの総サイズ は、ファイル取得の際の応答時にファイルサイズを返さない古い FTP サーバ では -1 になります。

url が http: スキーム識別子を使っていた場合、オプション 引数 data を与えることで POST リクエストを行うよう 指定することができます (通常リクエストの形式は GET です)。 data 引数は標準の application/x-www-form-urlencoded 形式でなくてはなりません; 以下の urlencode() 関数を参照して ください。

_urlopener
パブリック関数 urlopen() および urlretrieve() は FancyURLopener クラスのインスタンスを生成します。 インスタンスは要求された動作に応じて使用されます。 この機能をオーバライドするために、プログラマは URLopener または FancyURLopener のサブクラスを作り、そのクラスから 生成したインスタンスを変数 urllib._urlopener に代入した 後、呼び出したい関数を呼ぶことができます。 例えば、アプリケーションが URLopener が定義しているのとは 異なった User-Agent: ヘッダを指定したい場合があるかも しれません。この機能は以下のコードで実現できます:

import urllib

class AppURLopener(urllib.FancyURLopener):
    def __init__(self, *args):
        self.version = "App/1.7"
        urllib.FancyURLopener.__init__(self, *args)

urllib._urlopener = AppURLopener()

urlcleanup( )
以前の urlretrieve() で生成された可能性のあるキャッシュを 消去します。

quote( string[, safe])
string に含まれる特殊文字を "%xx" エスケープで置換 （quote）します。 アルファベット、数字、および文字 "_.-" は quote 処理 を行いません。オプションのパラメタ safe は quote 処理しない 追加の文字を指定します -- デフォルトの値は '/' です。

例: quote('/~connolly/') は '/%7econnolly/' になります。

quote_plus( string[, safe])
quote() と似ていますが、加えて空白文字をプラス記号 (``+'') に 置き換えます。これは HTML フォームの値を quote 処理する際に 必要な機能です。もとの文字列におけるプラス記号は safe に含まれて いない限りエスケープ置換されます。上と同様に、safe の デフォルトの値は '/' です。

unquote( string)
"%xx" エスケープをエスケープが表す 1 文字に置き換えます。

例: unquote('/%7Econnolly/') は '/~connolly/' になります。

unquote_plus( string)
unquote() と似ていますが、加えてプラス記号を空白文字に置き換 えます。これは quote 処理された HTML フォームの値を元に戻すのに必要な 機能です。

urlencode( query[, doseq])
マップ型オブジェクト、または 2 つの要素をもったタプルからなる配列 を、 ``URL にエンコードされた (url-encoded)'' に変換して、 上述の urlopen() のオプション引数 data に適した 形式にします。この関数はフォームのフィールド値でできた辞書を POST 型のリクエストに渡すときに便利です。 返される文字列は key=value のペアを "&" で区切った配列で、key と value の双方は上の quote_plus() で quote 処理されます。 オプションのパラメタ doseq が与えられていて、その評価結果が真 であった場合、配列 doseq の個々の要素について key=value のペアが生成されます。 2 つの要素をもったタプルからなる配列が引数 query として使われた 場合、各タプルの最初の値が key で、2 番目の値が value になります。 このときエンコードされた文字列中のパラメタの順番は配列中のタプルの順番 と同じになります。 cgi モジュールでは、関数 parse_qs() および parse_qsl() を提供しており、クエリ文字列を解析して Python のデータ構造にするのに利用できます。

pathname2url( path)
ローカルシステムにおける記法で表されたパス名 path を、URL に おけるパス部分の形式に変換します。この関数は完全な URL を生成するわけ ではありません。返される値は常に quote() を使って quote 処理 されたものになります。

url2pathname( path)
URL のパスの部分 path をエンコードされた URL の形式からローカル システムにおけるパス記法に変換します。この関数は path をデコード するために unquote() を使います。

class URLopener( [proxies[, **x509]])
URL をオープンし、読み出すためのクラスの基礎クラス (base class)です。 http: 、 ftp: 、gopher: または file: 以外のスキームを使ったオブジェクトのオープンをサポートしたいのでない かぎり、FancyURLopener を使おうと思うことになるでしょう。

デフォルトでは、 URLopener クラスは User-Agent: ヘッダとして "urllib/VVV" を送信します。ここで VVV は urllib のバージョン番号です。アプリケーションで独自の User-Agent: ヘッダを送信したい場合は、URLopener かまたは FancyURLopener のサブクラスを作成し、open() メソッドを呼び出す前にインスタンス属性 version を適切な 文字列値に設定することで行うことができます。

オプションのパラメタ proxies はスキーム名をプロキシの URL に マップする辞書でなくてはなりません。空の辞書はプロキシ機能を完全に オフにします。デフォルトの値は None で、この場合、 urlopen() の定義で述べたように、プロキシを設定する環境変数が 存在するならそれを使います。

追加のキーワードパラメタは x509 に集められますが、これは https: スキームによる認証に使われます。キーワード引数 key_file および cert_file がサポートされています。 実際に https: 形式の URL からリソースを取得するには両方の 引数が必要です。

class FancyURLopener( ...)
FancyURLopener は URLopener のサブクラスで、 以下の HTTP レスポンスコード: 301、302、303、 307、および 401 を取り扱う機能を提供します。 レスポンスコード 30x に対しては、 Location: ヘッダを使って実際の URL を取得します。 レスポンスコード 401 (認証が要求されていることを示す) に対しては、 ベーシック認証 (basic HTTP authintication) が行われます。 レスポンスコード 30x に対しては、最大で maxtries 属性に指定された数だけ再帰呼び出しを行うように なっています。この値はデフォルトで 10 です。

注意: RFC 2616 によると、 POST 要求に対する 301 および 302 応答はユーザの承認無しに自動的にリダイレクトしてはなりません。 実際は、これらの応答に対して自動リダイレクトを許すブラウザでは POST を GET に変更しており、urllib でもこの動作を 再現します。

コンストラクタに与えるパラメタは URLopener と同じです。

注意: 基本的な HTTP 認証を行う際、 FancyURLopener インスタンスは prompt_user_passwd() メソッドを呼び出します。このメソッドは デフォルトでは実行を制御している端末上で認証に必要な情報を要求する ように実装されています。必要ならば、このクラスのサブクラスにおいて より適切な動作をサポートするために prompt_user_passwd() メソッドをオーバライドしてもかまいません。

制限:

  • 現在のところ、以下のプロトコルだけがサポートされています: HTTP、 (バージョン 0.9 および 1.0)、 Gopher (Gopher-+ を除く)、 FTP、 およびローカルファイル。

  • urlretrieve() のキャッシュ機能は、有効期限ヘッダ (Expiration time header) を正しく処理できるようにハックするための 時間を取れるまで、無効にしてあります。

  • ある URL がキャッシュにあるかどうか調べるような関数があればと思って います。。

  • 後方互換性のため、 URL がローカルシステム上のファイルを指している ように見えるにも関わらずファイルを開くことができなければ、 URL は FTP プロトコルを使って再解釈されます。この機能は時として混乱を招く エラーメッセージを引き起こします。

  • 関数 urlopen() および urlretrieve() は、 ネットワーク接続が確立されるまでの間、一定でない長さの遅延を引き起こす ことがあります。このことは、これらの関数を使ってインタラクティブな Web クライアントを構築するのはスレッドなしには難しいことを意味します。

  • urlopen() または urlretrieve() が返すデータは サーバが返す生のデータです。このデータはバイナリデータ (例えば画像 データ) 、生テキスト (plain text)、または (例えば) HTMLでもかまいません。HTTP プロトコルはリプライ ヘッダ (reply header) にデータのタイプに関する情報を返します。 タイプは Content-Type: ヘッダを見ることで推測できます。

    Gopher プロトコルでは、データのタイプに 関する情報は URL にエンコードされます; これを展開することは簡単 ではありません。返されたデータが HTML であれば、 htmllibを使ってパースすることが できます。

  • このモジュールは認証を必要とするプロキシをサポートしません。 将来実装されるかもしれません。

  • urllib モジュールは URL 文字列を解釈したり構築したりする (ドキュメント化されていない) ルーチンを含んでいますが、URL を操作するためのインタフェースとしては、 urlparseモジュールをお勧めします。

  • 11.4.1 URLopener オブジェクト
  • 11.4.2 使用例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.3 cgitb Up: 11. インターネットプロトコルとその支援 Next: 11.4.1 URLopener オブジェクト


11.4.1 URLopener オブジェクト

URLopener および FancyURLopener クラスのオブジェクトは 以下の属性を持っています。

open( fullurl[, data])
適切なプロトコルを使って fullurl を開きます。このメソッドは キャッシュとプロキシ情報を設定し、その後適切な open メソッドを入力引数 つきで呼び出します。認識できないスキームが与えられた場合、 open_unknown() が呼び出されます。 data 引数は urlopen() の引数 data と同じ意味を持っています。

open_unknown( fullurl[, data])
オーバライド可能な、未知のタイプの URL を開くためのインタフェースです。

retrieve( url[, filename[, reporthook[, data]]])
url のコンテンツを取得し、filename に書き込みます。 返り値はタプルで、ローカルシステムにおけるファイル名と、 応答ヘッダ (URL がリモートを指している場合) または None (URL がローカルを指している場合) からなります。呼び出し側の処理は その後 filename を開いて内容を読み出さなくてはなりません。 filename が与えられており、かつ URL がローカルシステム上の ファイルを示しているばあい、入力ファイル名が返されます。URL が ローカルのファイルを示しておらず、かつ filename が与えられて いない場合、ファイル名は入力 URL の最後のパス構成要素につけられた拡張子と 同じ拡張子を tempfile.mktemp() につけたものになります。 reporthook を与える場合、この変数は 3 つの数値パラメタを受け取る 関数でなくてはなりません。この関数はデータの塊 (chunk) がネットワークから 読み込まれるたびに呼び出されます。ローカルの URL を与えた場合 reporthook は無視されます。

url が http: スキーム識別子を使っている場合、オプションの 引数 data を与えて POST リクエストを行うよう指定できます (通常のリクエストの形式は GET です) 。 引数 data は標準の application/x-www-form-urlencoded 形式でなくてはなりません; 上の urlencode() を参照して下さい。

version
URL をオープンするオブジェクトのユーザエージェントを指定する 変数です。urllib を特定のユーザエージェントであると サーバに通知するには、サブクラスの中でこの値をクラス変数として 値を設定するか、コンストラクタの中でベースクラスを呼び出す前に 値を設定してください。

FancyURLopener クラスはオーバライド可能な追加のメソッドを提供 しており、適切な振る舞いをさせることができます:

prompt_user_passwd( host, realm)
指定されたセキュリティ領域 (security realm) 下にある与えられたホスト において、ユーザ認証に必要な情報を返すための関数です。この関数が 返す値は (user, password) 、からなるタプルなくて はなりません。値はベーシック認証 (basic authentication) で使われます。

このクラスでの実装では、端末に情報を入力するようプロンプトを出します; ローカルの環境において適切な形で対話型モデルを使うには、このメソッドを オーバライドしなければなりません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.4 urllib Up: 11.4 urllib Next: 11.4.2 使用例


11.4.2 使用例

以下は "GET" メソッドを使ってパラメタを含む URL を取得するセッション の例です:

>>> import urllib
>>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query?%s" % params)
>>> print f.read()

以下は "POST" メソッドを代わりに使った例です:

>>> import urllib
>>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query", params)
>>> print f.read()

以下の例では、環境変数による設定内容に対して上書きする形で HTTP プロキシを 明示的に設定しています:

>>> import urllib
>>> proxies = {'http': 'http://proxy.example.com:8080/'}
>>> opener = urllib.FancyURLopener(proxies)
>>> f = opener.open("http://www.python.org")
>>> f.read()

以下の例では、環境変数による設定内容に対して上書きする形で、まったく プロキシを使わないよう設定しています:

>>> import urllib
>>> opener = urllib.FancyURLopener({})
>>> f = opener.open("http://www.python.org/")
>>> f.read()
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.4.1 URLopener オブジェクト Up: 11.4 urllib Next: 11.5 urllib2


11.5 urllib2 -- URL を開くための拡張可能なライブラリ

urllib2 モジュールは基本的な認証、暗号化認証、リダイレクション その他の介在する複雑なアクセス環境において (大抵は HTTP で) URL を開くための関数とクラスを定義します。

urllib2 モジュールでは以下の関数を定義しています:

urlopen( url[, data])
URL url を開きます。url は文字列でも Request オブジェクトでもかまいません (現時点では、コードの中で引数が本当に Request クラスのインスタンスまたは Request のサブクラス のインスタンスであるかどうかがチェックされます)。

data は文字列で、サーバに送信する追加のデータを指定します。 HTTP リクエストは data をサポートする唯一のリクエスト形式 ですが、ここでは data は例えば urllib.urlencode() が返すような application/x-www-form-urlencoded 形式で エンコードされたバッファでなくてはなりません。

この関数は以下の 2 つのメソッドを持つファイル類似のオブジェクトを返します:

  • geturl() -- 取得されたリソースの URL を返します。
  • info() -- 取得されたページのメタ情報を辞書形式の オブジェクトで返します。

エラーが発生した場合 URLError を送出します。

install_opener( opener)
標準で URL を開くオブジェクトとして OpenerDirector のインスタンス をインストールします。このコードは引数が本当に OpenerDirector のインスタンスであるかどうかはチェックしないので、適切なインタフェース を持ったクラスは何でも動作します。

build_opener( [handler, ...])
与えられた順番に URL ハンドラを連鎖させる OpenerDirector のインスタンスを返します。handler は BaseHandler または BaseHandler のサブクラスのインスタンスのどちらか です (どちらの場合も、コンストラクトは引数無しで呼び出せるように なっていなければなりません) 。以下のクラス:

ProxyHandler, UnknownHandler, HTTPHandler, HTTPDefaultErrorHandler, HTTPRedirectHandler, FTPHandler, FileHandler

については、そのクラスの インスタンスか、そのサブクラスのインスタンスが handler に含まれていない限り、handler よりも先に連鎖します。

Python が SSL をサポートするように設定してインストールされている 場合 (socket.ssl() が存在する場合) 、 HTTPSHandler も追加されます。

Python 2.3 からは、BaseHandler サブクラスでも handler_order メンバ変数を変更して、ハンドラリスト 内での場所を変更できるようになりました。 現在全てのハンドラの handler_oder は 500 ですが、 例外として ProxyHandler では 100 になっています。

状況に応じて、以下の例外が送出されます:

exception URLError
ハンドラが何らかの問題に遭遇した場合、この例外 (またはこの例外から 導出された例外)を送出します。この例外は IOError のサブクラスです。

exception HTTPError
URLError のサブクラスです。このオブジェクトは例外でない ファイル類似のオブジェクトとして返り値に使うことができます (urlopen() が返すのと同じものです)。この機能は、例えば サーバからの認証リクエストのように、変わった HTTP エラーを処理する のに役立ちます。

exception GopherError

URLError のサブクラスです。この例外は Gopher ハンドラに よって送出されます。

以下のクラスが提供されています:

class Request( url[, data[, headers]])
このクラスは URL リクエストを抽象化したものです。

url は有効な URL を指す文字列でなくてはなりません。 data の詳細については add_data() の記述を見てください。 headers は辞書でなくてはなりません。 この辞書は add_header() を辞書のキーおよび値を引数として呼び出した時と 同じように扱われます。

class OpenerDirector( )
OpenerDirector クラスは、BaseHandler の連鎖的に 呼び出して URL を開きます。このクラスはハンドラをどのように連鎖 させるか、またどのようにエラーをリカバリするかを管理します。

class BaseHandler( )
このクラスはハンドラ連鎖に登録される全てのハンドラがベースとしている クラスです - このクラスでは登録のための単純なメカニズムだけを扱います。

class HTTPDefaultErrorHandler( )
HTTP エラー応答のための標準のハンドラを定義します; 全てのレスポンスに 対して、例外 HTTPError を送出します。

class HTTPRedirectHandler( )
リダイレクションを扱うクラスです。

class ProxyHandler( [proxies])
このクラスはプロキシを通過してリクエストを送らせます。 引数 proxies を与える場合、プロトコル名からプロキシの URL へ対応付ける辞書でなくてはなりません。 標準では、プロキシのリストを環境変数 protocol_proxy から読み出します。

class HTTPPasswordMgr( )
(realm, uri) -> (user, password) の対応付けデータベースを保持します。

class HTTPPasswordMgrWithDefaultRealm( )
(realm, uri) -> (user, password) の対応付けデータベースを保持します。 レルム None はその他諸々のレルムを表し、他のレルムが 該当しない場合に検索されます。

class AbstractBasicAuthHandler( [password_mgr])
このクラスはHTTP 認証を補助するための混ぜ込みクラス (mixin class) です。 遠隔ホストとプロキシの両方に対応しています。 password_mgr を与える場合、HTTPPasswordMgr と互換性が なければなりません; 互換性のためにサポートしなければならないインタフェースについての 情報はセクション 11.5.6 を参照してください。

class HTTPBasicAuthHandler( [password_mgr])
遠隔ホストとの間での認証を扱います。 password_mgr を与える場合、HTTPPasswordMgr と互換性が なければなりません; 互換性のためにサポートしなければならないインタフェースについての 情報はセクション 11.5.6 を参照してください。

class ProxyBasicAuthHandler( [password_mgr])
プロキシとの間での認証を扱います。 password_mgr を与える場合、HTTPPasswordMgr と互換性が なければなりません; 互換性のためにサポートしなければならないインタフェースについての 情報はセクション 11.5.6 を参照してください。

class AbstractDigestAuthHandler( [password_mgr])
このクラスはHTTP 認証を補助するための混ぜ込みクラス (mixin class) です。 遠隔ホストとプロキシの両方に対応しています。 password_mgr を与える場合、HTTPPasswordMgr と互換性が なければなりません; 互換性のためにサポートしなければならないインタフェースについての 情報はセクション 11.5.6 を参照してください。

class HTTPDigestAuthHandler( [password_mgr])
遠隔ホストとの間での認証を扱います。 password_mgr を与える場合、HTTPPasswordMgr と互換性が なければなりません; 互換性のためにサポートしなければならないインタフェースについての 情報はセクション 11.5.6 を参照してください。

class ProxyDigestAuthHandler( [password_mgr])
プロキシとの間での認証を扱います。 password_mgr を与える場合、HTTPPasswordMgr と互換性が なければなりません; 互換性のためにサポートしなければならないインタフェースについての 情報はセクション 11.5.6 を参照してください。

class HTTPHandler( )
HTTP の URL を開きます。

class HTTPSHandler( )
HTTPS の URL を開きます。

class FileHandler( )
ローカルファイルを開きます。

class FTPHandler( )
FTP の URL を開きます。

class CacheFTPHandler( )
FTP の URL を開きます。遅延を最小限にするために、開かれている FTP 接続に対するキャッシュを保持します。

class GopherHandler( )
gopher の URL を開きます。

class UnknownHandler( )
その他諸々のためのクラスで、未知のプロトコルの URL を開きます。

  • 11.5.1 Request オブジェクト
  • 11.5.2 OpenerDirector オブジェクト
  • 11.5.3 BaseHandler オブジェクト
  • 11.5.4 HTTPRedirectHandler オブジェクト
  • 11.5.5 ProxyHandler オブジェクト
  • 11.5.6 HTTPPasswordMgr オブジェクト
  • 11.5.7 AbstractBasicAuthHandler オブジェクト
  • 11.5.8 HTTPBasicAuthHandler オブジェクト
  • 11.5.9 ProxyBasicAuthHandler オブジェクト
  • 11.5.10 AbstractDigestAuthHandler オブジェクト
  • 11.5.11 HTTPDigestAuthHandler オブジェクト
  • 11.5.12 ProxyDigestAuthHandler オブジェクト
  • 11.5.13 HTTPHandler オブジェクト
  • 11.5.14 HTTPSHandler オブジェクト
  • 11.5.15 FileHandler オブジェクト
  • 11.5.16 FTPHandler オブジェクト
  • 11.5.17 CacheFTPHandler オブジェクト
  • 11.5.18 GopherHandler オブジェクト
  • 11.5.19 UnknownHandler オブジェクト
  • 11.5.20 例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.4.2 使用例 Up: 11. インターネットプロトコルとその支援 Next: 11.5.1 Request オブジェクト


11.5.1 Request オブジェクト

以下のメソッドは Request の全ての公開インタフェースを記述します。 従ってサブクラスではこれら全てのメソッドをオーバライドしなければなりません。

add_data( data)
Request のデータを data に設定します。この値は HTTP ハンドラ以外のハンドラでは無視されます。HTTP ハンドラでは、データは application/x-www-form-encoded でエンコードされたバッファ でなくてはなりません。このメソッドを使うとリクエストの形式が GET POST に変更されます。

get_method( )
HTTP リクエストメソッドを示す文字列を返します。このメソッドは HTTP リクエストだけに対して意味があり、現状では常に ("GET", "POST") のうちのいずれかの値をとります。

has_data( )
インスタンスが None でないデータを持つかどうかを返します。

get_data( )
インスタンスのデータを返します。

add_header( key, val)
リクエストに新たなヘッダを追加します。ヘッダは HTTP ハンドラ以外の ハンドラでは無視されます。HTTP ハンドラでは、引数はサーバに送信される ヘッダのリストに追加されます。同じ名前を持つヘッダを 2 つ以上持つ ことはできず、key の衝突が生じた場合、後で追加したヘッダが前に 追加したヘッダを上書きします。現時点では、この機能は HTTP の機能を 損ねることはありません。というのは、複数回呼び出したときに意味を 持つようなヘッダには、どれもただ一つのヘッダを使って同じ機能を果たす ための (ヘッダ特有の) 方法があるからです。

get_full_url( )
コンストラクタで与えられた URL を返します。

get_type( )
URL のタイプ -- いわゆるスキーム (scheme) -- を返します。

get_host( )
接続を行う先のホスト名を返します。

get_selector( )
セレクタ -- サーバに送られる URL の一部分 -- を返します。

set_proxy( host, type)
リクエストがプロキシサーバを経由するように準備します。 host および type はインスタンスのもとの設定と置き換えられ ます。インスタンスのセレクタはコンストラクタに与えたもともとの URL に なります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5 urllib2 Up: 11.5 urllib2 Next: 11.5.2 OpenerDirector オブジェクト


11.5.2 OpenerDirector オブジェクト

OpenerDirector インスタンスは以下のメソッドを持っています:

add_handler( handler)
handler は BaseHandler のインスタンスでなければ なりません。以下のメソッドを使った検索が行われ、URL を取り扱うことが 可能なハンドラの連鎖が追加されます。

  • protocol_open() -- ハンドラが protocol の URL を開く方法を知っているかどうかを 調べます。
  • protocol_error_type() -- ハンドラが protocol から返される type エラーの扱い方を知っているかどうかを調べます。

close( )
循環参照を明示的にやめさせて、全てのハンドラを削除します。 OpenerDirector は登録されているハンドラを参照する必要があり、 ハンドラは自分を呼び出す OpenerDirector を参照する必要が あるため、循環参照が生まれます。最近のバージョンの Python では 循環参照を修正しますが、たまに明示的に循環参照をやめさせた方が よいことがあります。

open( url[, data])
与えられた url (リクエストオブジェクトでも文字列でも かまいません) を開きます。オプションとして data を与えることが できます。 引数、返り値、および送出される例外は urlopen() と同じ です (urlopen() の場合、標準でインストールされている OpenerDirector の open() メソッドを呼び出します) 。

error( proto[, arg[, ...]])
与えられたプロトコルにおけるエラーを処理します。このメソッドは 与えられたプロトコルにおける登録済みのエラーハンドラを (プロトコル固有の) 引数で呼び出します。 HTTP プロトコルは特殊な ケースで、特定のエラーハンドラを選び出すのに HTTP レスポンスコード を使います; ハンドラクラスの http_error_*() メソッドを 参照してください。

返り値および送出される例外は urlopen() と同じものです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.1 Request オブジェクト Up: 11.5 urllib2 Next: 11.5.3 BaseHandler オブジェクト


11.5.3 BaseHandler オブジェクト

BaseHandler オブジェクトは直接的に役に立つ 2 つのメソッド と、その他として導出クラスで使われることを想定したメソッドを 提供します。以下は直接的に使うためのメソッドです:

add_parent( director)
親オブジェクトとして、director を追加します。

close( )
全ての親オブジェクトを削除します。

以下のメンバおよびメソッドは BaseHandler から導出された クラスでのみ使われます:

parent
有効な OpenerDirector です。この値は違うプロトコルを 使って URL を開く場合やエラーを処理する際に使われます。

default_open( req)
このメソッドは BaseHandler では定義されて いません。 しかし、全ての URL をキャッチさせたいなら、サブクラスで定義する 必要があります。

このメソッドが定義されていた場合、OpenerDirector から 呼び出されます。このメソッドは OpenerDirector の メソッド open() が返す値について記述されているようなファイル類似の オブジェクトか、None を返さなくてはなりません。 このメソッドが送出する例外は、真に例外的なことが起きない限り、 URLError を送出しなければなりません (例えば、 MemoryError を URLError をマップしては いけません)。

このメソッドはプロトコル固有のオープンメソッドが呼び出される前に 呼び出されます。

protocol_open( req)
このメソッドは BaseHandler では定義されて いません。 しかしプロトコルの指定された URL をキャッチしたいなら、サブクラスで 定義する必要があります。

このメソッドが定義されていた場合、OpenerDirector から 呼び出されます。戻り値は default_open と同じでなければ なりません。

unknown_open( req)
このメソッドは BaseHandler では定義されて いません。 しかし URL を開くための特定のハンドラが登録されていないような URL を キャッチしたいなら、サブクラスで定義する必要があります。

このメソッドが定義されていた場合、OpenerDirector から 呼び出されます。戻り値は default_open と同じでなければ なりません。

http_error_default( req, fp, code, msg, hdrs)
このメソッドは BaseHandler では定義されて いません。 しかしその他の処理されなかった HTTP エラーを処理する機能をもたせたいなら、 サブクラスで定義する必要があります。このメソッドはエラーに遭遇した OpenerDirector から自動的に呼び出されます。その他の状況では 普通呼び出すべきではありません。

req は Request オブジェクトで、 fp は HTTP エラー本体を読み出せるようなファイル類似のオブジェクトに なります。code は 3 桁の 10 進数からなるエラーコードで、 msg ユーザ向けのエラーコード解説です。hdrs は エラー応答のヘッダをマップしたオブジェクトです。

返される値および送出される例外は urlopen() と同じ ものでなければなりません。

http_error_nnn( req, fp, code, msg, hdrs)
nnn は 3 桁の 10 進数からなる HTTP エラーコードでなくては なりません。このメソッドも BaseHandler では定義されていませんが、 サブクラスのインスタンスで定義されていた場合、エラーコード nnn の HTTP エラーが発生した際に呼び出されます。

特定の HTTP エラーに対する処理を行うためには、このメソッドをサブクラスで オーバライドする必要があります。

引数、返される値、および送出される例外は http_error_default() と同じものでなければなりません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.2 OpenerDirector オブジェクト Up: 11.5 urllib2 Next: 11.5.4 HTTPRedirectHandler オブジェクト


11.5.4 HTTPRedirectHandler オブジェクト

注意: HTTP リダイレクトによっては、このモジュールのクライアントコード 側での処理を必要とします。その場合、 HTTPError が送出されます。 様々なリダイレクトコードの厳密な意味に関する詳細は RFC 2616 を 参照してください。

redirect_request( req, fp, code, msg, hdrs)
リダイレクトの通知に応じて、 Request または None を返します。このメソッドは http_error_30*() メソッドに おいて、リダイレクトの通知をサーバから受信した際に、 デフォルトの実装として呼び出されます。 リダイレクトを起こす場合、新たな Request を生成して、 http_error_30*() がリダイレクトを実行できるようにします。 そうでない場合、他の Handler のいずれにもこの URL を 処理させたくなければ HTTPError を送出し、 リダイレクト処理を行うことはできないが他の Handler なら可能かもしれない場合には None を返します。

注意: このメソッドのデフォルトの実装は、RFC 2616 に厳密に従ったものでは ありません。 RFC 2616 では、POST リクエストに対する 301 および 302 応答が、 ユーザの承認なく自動的にリダイレクトされてはならないと述べています。 現実には、ブラウザは POST を GET に変更することで、これらの 応答に対して自動的にリダイレクトを行えるようにしています。 デフォルトの実装でも、この挙動を再現しています。

http_error_301( req, fp, code, msg, hdrs)

Location: URL にリダイレクトします。このメソッドは HTTP における `moved permanently' レスポンスを取得した際に 親オブジェクトとなる OpenerDirector によって呼び出されます。

http_error_302( req, fp, code, msg, hdrs)
http_error_301() と同じですが、`found' レスポンスに対して 呼び出されます。

http_error_303( req, fp, code, msg, hdrs)
http_error_301() と同じですが、`see other' レスポンスに対して 呼び出されます。

http_error_307( req, fp, code, msg, hdrs)
http_error_301() と同じですが、`temporary redirect' レスポンスに対して呼び出されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.3 BaseHandler オブジェクト Up: 11.5 urllib2 Next: 11.5.5 ProxyHandler オブジェクト


11.5.5 ProxyHandler オブジェクト

protocol_open( request)
ProxyHandler は、 コンストラクタで与えた辞書 proxies にプロキシが設定されている ような protocol 全てについて、メソッド protocol_open() を持つことになります。 このメソッドは request.set_proxy() を呼び出して、 リクエストがプロキシを通過できるように修正します。その後 連鎖するハンドラの中から次のハンドラを呼び出して実際に プロトコルを実行します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.4 HTTPRedirectHandler オブジェクト Up: 11.5 urllib2 Next: 11.5.6 HTTPPasswordMgr オブジェクト


11.5.6 HTTPPasswordMgr オブジェクト

以下のメソッドは HTTPPasswordMgr および HTTPPasswordMgrWithDefaultRealm オブジェクトで利用できます。

add_password( realm, uri, user, passwd)
uri は単一の URI でも複数の URI からなる配列でもかまいません。 realm 、user および passwd は文字列でなくてはなりません。 このメソッドによって、realm と与えられた URI の上位 URI に対して (user, passwd) が認証トークンとして使われるようになります。

find_user_password( realm, authuri)
与えられたレルムおよび URI に対するユーザ名またはパスワードがあれば それを取得します。該当するユーザ名／パスワードが存在しない場合、 このメソッドは (None, None) を返します。

HTTPPasswordMgrWithDefaultRealm オブジェクトでは、与えられた realm に対して該当するユーザ名/パスワードが存在しない場合、 レルム None が検索されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.5 ProxyHandler オブジェクト Up: 11.5 urllib2 Next: 11.5.7 AbstractBasicAuthHandler オブジェクト


11.5.7 AbstractBasicAuthHandler オブジェクト

handle_authentication_request( authreq, host, req, headers)
ユーザ名／パスワードを取得し、再度サーバへのリクエストを試みることで、 サーバからの認証リクエストを処理します。 authreq はリクエストにおいてレルムに関する情報が含まれている ヘッダの名前、host は認証を行う対象のホスト名、req は (失敗した) Request オブジェクト、そして headers は エラーヘッダでなくてはなりません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.6 HTTPPasswordMgr オブジェクト Up: 11.5 urllib2 Next: 11.5.8 HTTPBasicAuthHandler オブジェクト


11.5.8 HTTPBasicAuthHandler オブジェクト

http_error_401( req, fp, code, msg, hdrs)
認証情報がある場合、認証情報付きで再度リクエストを試みます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.7 AbstractBasicAuthHandler オブジェクト Up: 11.5 urllib2 Next: 11.5.9 ProxyBasicAuthHandler オブジェクト


11.5.9 ProxyBasicAuthHandler オブジェクト

http_error_407( req, fp, code, msg, hdrs)
認証情報がある場合、認証情報付きで再度リクエストを試みます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.8 HTTPBasicAuthHandler オブジェクト Up: 11.5 urllib2 Next: 11.5.10 AbstractDigestAuthHandler オブジェクト


11.5.10 AbstractDigestAuthHandler オブジェクト

handle_authentication_request( authreq, host, req, headers)
authreq はリクエストにおいてレルムに関する情報が含まれている ヘッダの名前、host は認証を行う対象のホスト名、req は (失敗した) Request オブジェクト、そして headers は エラーヘッダでなくてはなりません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.9 ProxyBasicAuthHandler オブジェクト Up: 11.5 urllib2 Next: 11.5.11 HTTPDigestAuthHandler オブジェクト


11.5.11 HTTPDigestAuthHandler オブジェクト

http_error_401( req, fp, code, msg, hdrs)
認証情報がある場合、認証情報付きで再度リクエストを試みます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.10 AbstractDigestAuthHandler オブジェクト Up: 11.5 urllib2 Next: 11.5.12 ProxyDigestAuthHandler オブジェクト


11.5.12 ProxyDigestAuthHandler オブジェクト

http_error_407( req, fp, code, msg, hdrs)
認証情報がある場合、認証情報付きで再度リクエストを試みます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.11 HTTPDigestAuthHandler オブジェクト Up: 11.5 urllib2 Next: 11.5.13 HTTPHandler オブジェクト


11.5.13 HTTPHandler オブジェクト

http_open( req)
HTTP リクエストを送ります。req.has_data() に応じて、 GET または POST のどちらでも送ることができます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.12 ProxyDigestAuthHandler オブジェクト Up: 11.5 urllib2 Next: 11.5.14 HTTPSHandler オブジェクト


11.5.14 HTTPSHandler オブジェクト

https_open( req)
HTTPS リクエストを送ります。req.has_data() に応じて、 GET または POST のどちらでも送ることができます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.13 HTTPHandler オブジェクト Up: 11.5 urllib2 Next: 11.5.15 FileHandler オブジェクト


11.5.15 FileHandler オブジェクト

file_open( req)
ホスト名がない場合、またはホスト名が 'localhost' の場合に ファイルをローカルでオープンします。そうでない場合、プロトコルを ftp に切り替え、parent を使って再度オープンを 試みます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.14 HTTPSHandler オブジェクト Up: 11.5 urllib2 Next: 11.5.16 FTPHandler オブジェクト


11.5.16 FTPHandler オブジェクト

ftp_open( req)
req で表されるファイルを FTP 越しにオープンします。 ログインは常に空のユーザネームおよびパスワードで行われます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.15 FileHandler オブジェクト Up: 11.5 urllib2 Next: 11.5.17 CacheFTPHandler オブジェクト


11.5.17 CacheFTPHandler オブジェクト

CacheFTPHandler オブジェクトは FTPHandler オブジェクトに 以下のメソッドを追加したものです:

setTimeout( t)
接続のタイムアウトを t 秒に設定します。

setMaxConns( m)
キャッシュ付き接続の最大接続数を m に設定します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.16 FTPHandler オブジェクト Up: 11.5 urllib2 Next: 11.5.18 GopherHandler オブジェクト


11.5.18 GopherHandler オブジェクト

gopher_open( req)
req で表される gopher 上のリソースをオープンします。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.17 CacheFTPHandler オブジェクト Up: 11.5 urllib2 Next: 11.5.19 UnknownHandler オブジェクト


11.5.19 UnknownHandler オブジェクト

unknown_open( )
例外 URLError を送出します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.18 GopherHandler オブジェクト Up: 11.5 urllib2 Next: 11.5.20 例


11.5.20 例

以下の例では、 python.org のメインページを取得して、その最初の 100 バイト分を表示します:

>>> import urllib2
>>> f = urllib2.urlopen('http://www.python.org/')
>>> print f.read(100)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<?xml-stylesheet href="./css/ht2html

今度は CGI の標準入力にデータストリームを送信し、CGI が返すデータ を読み出します:

>>> import urllib2
>>> req = urllib2.Request(url='https://localhost/cgi-bin/test.cgi',
...                       data='This data is passed to stdin of the CGI')
>>> f = urllib2.urlopen(req)
>>> print f.read()
Got Data: "This data is passed to stdin of the CGI"

上の例で使われているサンプルの CGI は以下のようになっています:

#!/usr/bin/env python
import sys
data = sys.stdin.read()
print 'Content-type: text-plain\n\nGot Data: "%s"' %
data
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.19 UnknownHandler オブジェクト Up: 11.5 urllib2 Next: 11.6 httplib


11.6 httplib -- HTTP プロトコルクライアント

このモジュールでは HTTP および HTTPS プロトコルのクライアント側 を実装しているクラスを定義しています。このモジュールは通常直接 使われることはありません -- モジュール urllibは HTTP や HTTPS を 使う URL を扱うためにこのモジュールを使います。 注意: HTTPS のサポートは socket モジュールが SSL を サポートするようにコンパイルされている場合のみ利用できます。

このモジュールで定義されている定数は以下の通りです:

HTTP_PORT
HTTP プロトコルの標準のポート (通常は 80) です。

HTTPS_PORT
HTTPS プロトコルの標準のポート (通常は 443) です。

このモジュールでは以下のクラスを提供しています:

class HTTPConnection( host[, port])
HTTPConnection インスタンスは、HTTP サーバとの一回の トランザクションを表現します。インスタンスの生成はホスト名と オプションのポート番号を与えて行います。ポート番号が与えられ なかった場合、ホスト名文字列が host:port の形式であれば、ホスト名からポート番号を導き、そうでない 場合には標準の HTTP ポート番号 (80) が使われます。例えば、 以下の呼び出しは全て同じサーバの同じポートに接続するインスタンス を生成します:

>>> h1 = httplib.HTTPConnection('www.cwi.nl')
>>> h2 = httplib.HTTPConnection('www.cwi.nl:80')
>>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)

class HTTPSConnection( host[, port, key_file, cert_file])
HTTPConnection のサブクラスで、セキュアなサーバと 通信するために SSL を使います。標準のポート番号は 443 です。 key_fileには、秘密鍵を格納したPEM形式ファイルのファイル名を指定します。cert_fileには、PEM形式の証明書チェーンファイルを指定します。

警告: この関数は証明書の検査を行いません！

必要に応じて以下の例外が送出されます:

exception HTTPException
このモジュールにおける他の例外クラスの基底クラスです。 Exception のサブクラスです。

exception NotConnected
HTTPException サブクラスです。

exception InvalidURL
HTTPException のサブクラスで、ポート番号が与えられて いるが、その値が数字でなかったり空のオブジェクトの場合に送出 されます。

exception UnknownProtocol
HTTPException のサブクラスです。

exception UnknownTransferEncoding
HTTPException のサブクラスです。

exception IllegalKeywordArgument
HTTPException のサブクラスです。

exception UnimplementedFileMode
HTTPException のサブクラスです。

exception IncompleteRead
HTTPException のサブクラスです。

exception ImproperConnectionState
HTTPException のサブクラスです。

exception CannotSendRequest
ImproperConnectionState のサブクラスです。

exception CannotSendHeader
ImproperConnectionState のサブクラスです。

exception ResponseNotReady
ImproperConnectionState のサブクラスです。

exception BadStatusLine
HTTPException のサブクラスです。 サーバが理解できない HTTP 状態コードで応答した場合に送出されます。

  • 11.6.1 HTTPConnection オブジェクト
  • 11.6.2 HTTPResponse オブジェクト
  • 11.6.3 例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.5.20 例 Up: 11. インターネットプロトコルとその支援 Next: 11.6.1 HTTPConnection オブジェクト


11.6.1 HTTPConnection オブジェクト

HTTPConnection インスタンスは以下のメソッドを持ちます:

request( method, url[, body[, headers]])
このメソッドは、 HTTP 要求メソッド method およびセレクタ url を使って、要求をサーバに送ります。body 引数が存在する場合、 ヘッダが終了した後に送信する文字列データでなければなりません。 ヘッダの Content-Length は自動的に正しい値に設定されます。 headers 引数は要求と同時に送信される拡張 HTTP ヘッダの内容からなる マップ型でなくてはなりません。

getresponse( )
サーバに対して HTTP 要求を送り出した後に呼び出されなければりません。 要求に対する応答を取得します。HTTPResponse インスタンスを 返します。

set_debuglevel( level)
デバッグレベル (印字されるデバッグ出力の量) を設定します。 標準のデバッグレベルは 0 で、デバッグ出力を全く印字 しません。

connect( )
オブジェクトを生成するときに指定したサーバに接続します。

close( )
サーバへの接続を閉じます。

send( data)
サーバにデータを送ります。このメソッドは endheaders() が呼び出された直後で、かつ getreply() が呼び出される 前に使わなければなりません。

putrequest( request, selector)
サーバへの接続が確立したら、最初にこのメソッドを呼び出さなくては なりません。このメソッドは request 文字列、selector 文字列、 そして HTTP バージョン (HTTP/1.1) からなる一行を送信します。

putheader( header, argument[, ...])
RFC 822 形式のヘッダをサーバに送ります。この処理では、header、 コロンとスペース、そして最初の引数からなる 1 行をサーバに送ります。 追加の引数が与えられている場合、各々の行がタブと引数からなる連続した行が 送られます。

endheaders( )
サーバに食う行を送り、ヘッダ部が終了したことを通知します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.6 httplib Up: 11.6 httplib Next: 11.6.2 HTTPResponse オブジェクト


11.6.2 HTTPResponse オブジェクト

HTTPResponse インスタンスは以下のメソッドと属性を持ちます:

read( [amt])
応答の本体全体か、amt バイトまで読み出して返します。

getheader( name[, default])
ヘッダ name の内容を取得して返すか、該当するヘッダがない場合には default を返します。

msg
応答ヘッダを含む mimetools.Message インスタンスです。

version
サーバが使用した HTTP プロトコルバージョンです。10 は HTTP/1.0 を、 11 は HTTP/1.1 を表します。

status
サーバから返される状態コードです。

reason
サーバから返される応答の理由文です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.6.1 HTTPConnection オブジェクト Up: 11.6 httplib Next: 11.6.3 例


11.6.3 例

以下はどうやって "GET" リクエストを行うかを示す例です:

>>> import httplib
>>> conn = httplib.HTTPConnection("www.python.org")
>>> conn.request("GET", "/index.html")
>>> r1 = conn.getresponse()
>>> print r1.status, r1.reason
200 OK
>>> data1 = r1.read()
>>> conn.request("GET", "/parrot.spam")
>>> r2 = conn.getresponse()
>>> print r2.status, r2.reason
404 Not Found
>>> data2 = r2.read()
>>> conn.close()

以下はどうやって "POST" リクエストを行うかを示す例です:

>>> import httplib, urllib
>>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> headers = {"Content-type": "application/x-www-form-urlencoded",
...            "Accept": "text/plain"}
>>> conn = httplib.HTTPConnection("musi-cal.mojam.com:80")
>>> conn.request("POST", "/cgi-bin/query", params, headers)
>>> response = conn.getresponse()
>>> print response.status, response.reason
200 OK
>>> data = response.read()
>>> conn.close()
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.6.2 HTTPResponse オブジェクト Up: 11.6 httplib Next: 11.7 ftplib


11.7 ftplib -- FTPプロトコルクライアント

このモジュールではFTPクラスと、それに関連するいくつかの項目を定 義しています。 FTPクラスは、FTPプロトコルのクライアント側の機能を備えています。 このクラスを使うとFTPのいろいろな機能の自動化、例えば他のFTPサーバのミ ラーリングといったことを実行するPythonプログラムを書くことができます。 また、urllibモジュールもFTPを使うURLを操作するのにこのクラス を使っています。 FTP (File Transfer Protocol)についての詳しい情報はInternet RFC 959を参 照して下さい。

ftplibモジュールを使ったサンプルを以下に示します：

>>> from ftplib import FTP
>>> ftp = FTP('ftp.cwi.nl')   # ホストのデフォルトポートへ接続
>>> ftp.login()               # ユーザ名 anonymous、パスワード anonyumou
s@
>>> ftp.retrlines('LIST')     # ディレクトリの内容をリストアップ
total 24418
drwxrwsr-x   5 ftp-usr  pdmaint     1536 Mar 20 09:48 .
dr-xr-srwt 105 ftp-usr  pdmaint     1536 Mar 21 14:32 ..
-rw-r--r--   1 ftp-usr  pdmaint     5305 Mar 20 09:48 INDEX
 .
 .
 .
>>> ftp.retrbinary('RETR README', open('README', 'wb').write)
'226 Transfer complete.'
>>> ftp.quit()

このモジュールは以下の項目を定義しています：

class FTP( [host[, user[, passwd[, acct]]]])
FTPクラスの新しいインスタンスを返します。 hostが与えられると、connect(host)メソッドが実行されま す。 userが与えられると、さらにlogin(user, passwd, aracct)メソッドが実行されます（このpasswdとacctは指定され なければデフォルトでは空文字列です）。

all_errors
FTPインスタンスのメソッドの結果、FTP接続で（プログラミングのエ ラーと考えられるメソッドの実行によって）発生する全ての例外（タプル形 式）。 この例外には以下の４つのエラーはもちろん、socket.errorと IOErrorも含まれます。

exception error_reply
サーバから想定外の応答があった時に発生する例外。

exception error_temp
400-499の範囲のエラー応答コードを受け取った時に発生する例外。

exception error_perm
500-599の範囲のエラー応答コードを受け取った時に発生する例外。

exception error_proto
1-5の数字で始まらない応答コードをサーバから受け取った時に発生する例外。

参考資料:

netrcモジュール:
.netrcファイルフォーマットのパーザ。 .netrcファイルは、FTPクライアントがユーザにプロンプトを出す前に、 ユーザ認証情報をロードするのによく使われます。.

PythonのソースディストリビューションのTools/scripts/ftpmi rror.pyファイルは、FTPサイトあるいはその一部をミ ラーリングするスクリプトで、ftplibモジュールを使っています。こ のモジュールを適用した応用例として使うことができます。

  • 11.7.1 FTP オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.6.3 例 Up: 11. インターネットプロトコルとその支援 Next: 11.7.1 FTP オブジェクト


11.7.1 FTP オブジェクト

いくつかのコマンドは２つのタイプについて実行します：１つはテキストファイ ルで、もう１つはバイナリファイルを扱います。 これらのメソッドのテキストバージョンでは"lines"、バイナリバージョン では"binary"の語がメソッド名の終わりについています。

FTPインスタンスには以下のメソッドがあります：

set_debuglevel( level)
インスタンスのデバッグレベルを設定します。 この設定によってデバッグ時に出力される量を調節します。 デフォルトは0で、何も出力されません。 1なら、一般的に１つのコマンドあたり１行の適当な量のデバッグ出力を 行います。 2以上なら、コントロール接続で受信した各行を出力して、最大のデバッ グ出力をします。

connect( host[, port])
指定されたホストとポートに接続します。 ポート番号のデフォルト値はFTPプロトコルの仕様で定められた21です。 他のポート番号を指定する必要はめったにありません。 この関数はひとつのインスタンスに対して一度だけ実行すべきです； インスタンスが作られた時にホスト名が与えられていたら、呼び出すべきではあ りません。 これ以外の他の全てのメソッドは接続された後で実行可能となります。

getwelcome( )
接続して最初にサーバから送られてくるウェルカムメッセージを返します。 （このメッセージには、ユーザにとって適切な注意書きやヘルプ情報が含まれる ことがあります。）

login( [user[, passwd[, ac ct]]])
与えられたuserでログインします。 passwdとacctのパラメータは省略可能で、デフォルトでは空文字列 です。 もしuserが指定されないなら、デフォルトで'anonymous'になりま す。 もしuserが'anonymous'なら、デフォルトのpasswdは 'anonymous@'になります。 このfunctionは各インスタンスについて一度だけ、接続が確立した後に呼び出さ なければなりません； インスタンスが作られた時にホスト名とユーザ名が与えられていたら、このメ ソッドを実行すべきではありません。 ほとんどのFTPコマンドはクライアントがログインした後に実行可能になりま す。

abort( )
実行中のファイル転送を中止します。 これはいつも機能するわけではありませんが、やってみる価値はあります。

sendcmd( command)
シンプルなコマンド文字列をサーバに送信して、受信した文字列を返します。

voidcmd( command)
シンプルなコマンド文字列をサーバに送信して、その応答を扱います。 応答コードが200-299の範囲にあれば何も返しません。 それ以外は例外を発生します。

retrbinary( command, callback[, maxblocksize[, rest]])
バイナリ転送モードでファイルを受信します。 commandは適切な"RETR"コマンド： 'RETR filename'でなければなりません。 関数callbackは、受信したデータブロックのそれぞれに対して、データブ ロックを１つの文字列の引数として呼び出されます。 省略可能な引数maxblocksizeは、実際の転送を行うのに作られた低レベル のソケットオブジェクトから読み込む最大のチャンクサイズを指定します（これ はcallbackに与えられるデータブロックの最大サイズにもなります）。 妥当なデフォルト値が設定されます。 restは、transfercmd()メソッドと同じものです。

retrlines( command[, callback])
ASCII転送モードでファイルとディレクトリのリストを受信します。 commandは、適切な"RETR"コマンド（retrbinary()を参 照）あるいは"LIST"コマンド（通常は文字列'LIST'）でなければな りません。 関数callbackは末尾のCRLFを取り除いた各行に対して実行されます。 デフォルトではcallbackはsys.stdoutに各行を印字します。

set_pasv( boolean)
booleanがtrueなら``パッシブモード''をオンにし、そうでないならパッ シブモードをオフにします。 （Python 2.0以前ではデフォルトでパッシブモードはオフにされていましたが、 Python 2.1以後ではデフォルトでオンになっています。）

storbinary( command, file[, blocksize])
バイナリ転送モードでファイルを転送します。 commandは適切な"STOR"コマンド："STOR filename"で なければなりません。 fileは開かれたファイルオブジェクトで、read()メソッドで EOFまで読み込まれ、ブロックサイズblocksizeでデータが転送されま す。 引数blocksizeのデフォルト値は8192です。 バージョン2.1 以降で変更された 仕様: blocksizeのデフォルト値が追加されました

storlines( command, file)
ASCII転送モードでファイルを転送します。 commandは適切な"STOR"コマンドでなければなりません（st orbinary()を参照）。 fileは開かれたファイルオブジェクトで、readline()メソッド でEOFまで読み込まれ、各行がデータが転送されます。

transfercmd( cmd[, rest])
データ接続中に転送を初期化します。 もし転送中なら、"EPRT"あるいは"PORT"コマンドと、cmdで指 定したコマンドを送信し、接続を続けます。 サーバがパッシブなら、"EPSV"あるいは"PASV"コマンドを送信して接 続し、転送コマンドを開始します。 どちらの場合も、接続のためのソケットを返します。

省略可能なrestが与えられたら、"REST"コマンドがサーバに送信さ れ、restを引数として与えます。 restは普通、要求したファイルのバイトオフセット値で、最初のバイトを とばして指定したオフセット値からファイルのバイト転送を再開するよう伝えま す。 しかし、RFC 959ではrestが印字可能なASCIIコード33から126の範囲の文 字列からなることを要求していることに注意して下さい。 したがって、transfercmd()メソッドはrestを文字列に変換しま すが、文字列の内容についてチェックしません。 もし"REST"コマンドをサーバが認識しないなら、例外error_re plyが発生します。 この例外が発生したら、引数restなしにtransfercmd()を実行し ます。

ntransfercmd( cmd[, rest])
transfercmd()と同様ですが、データと予想されるサイズとのタプルを 返します。 もしサイズが計算できないなら、サイズの代わりにNoneが返されます。 cmdとrestはtransfercmd()のものと同じです。

nlst( argument[, ...])
"NLST"コマンドで返されるファイルのリストを返します。 省略可能なargumentは、リストアップするディレクトリです（デフォルト ではサーバのカレントディレクトリです）。 "NLST"コマンドに非標準である複数の引数を渡すことができます。

dir( argument[, ...])
"LIST"コマンドで返されるディレクトリ内のリストを作り、標準出力へ出 力します。 省略可能なargumentは、リストアップするディレクトリです（デフォルト ではサーバのカレントディレクトリです）。 "LIST"コマンドに非標準である複数の引数を渡すことができます。 もし最後の引数が関数なら、retrlines()のようにcallbackとし て使われます；デフォルトではsys.stdoutに印字します。 このメソッドはNoneを返します。

rename( fromname, toname)
サーバ上のファイルのファイル名fromnameをtonameへ変更します。

delete( filename)
サーバからファイルfilenameを削除します。 成功したら応答のテキストを返し、そうでないならパーミッションエラーでは error_permを、他のエラーではerror_replyを返しま す。

cwd( pathname)
サーバのカレントディレクトリを設定します。

mkd( pathname)
サーバ上に新たにディレクトリを作ります。

pwd( )
サーバ上のカレントディレクトリのパスを返します。

rmd( dirname)
サーバ上のディレクトリdirnameを削除します。

size( filename)
サーバ上のファイルfilenameのサイズを尋ねます。 成功したらファイルサイズが整数で返され、そうでないならNoneが返さ れます。 "SIZE"コマンドは標準化されていませんが、多くの普通のサーバで実装さ れていることに注意して下さい。

quit( )
サーバに"QUIT"コマンドを送信し、接続を閉じます。 これは接続を閉じるのに``礼儀正しい''方法ですが、"QUIT"コマンドに反 応してサーバの例外が発生するかもしれません。 この例外は、close()メソッドによってFTPインスタンスに対 するその後のコマンド使用が不可になっていることを示しています（下記参 照）。

close( )
接続を一方的に閉じます。 既に閉じた接続に対して実行すべきではありません（例えばquit()を 呼び出して成功した後など）。 この実行の後、FTPインスタンスはもう使用すべきではありません （close()あるいはquit()を呼び出した後で、 login()メソッドをもう一度実行して再び接続を開くことはできませ ん）。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.7 ftplib Up: 11.7 ftplib Next: 11.8 gopherlib


11.8 gopherlib -- gopher プロトコルのクライアント

このモジュールでは、gopher プロトコルのクライアント側について最小限の 実装を提供しています。このモジュールは urllib モジュールで gopher プロトコルを使う URL を扱うために用いられます。

このモジュールでは以下の関数を定義しています:

send_selector( selector, host[, port])
selector 文字列を host および port (標準の値は 70 です) の gopher サーバに送信します。 返信されたドキュメントデータを読み出すための、開かれた状態のファイル オブジェクトを返します。

send_query( selector, query, host[, port])
selector 文字列、および query 文字列を host および port (標準の値は 70 です) の gopher サーバに送信します。 返信されたドキュメントデータを読み出すための、開かれた状態のファイル オブジェクトを返します。

gopher サーバから返されるデータは任意の形式であり、セレクタ (selector) 文字列の最初の文字に依存するので注意してください。データがテキスト (セレクタの最初の文字が "0") の場合、各行は CRLF で終端 され、データ全体は "." 一個だけからなる行で終端されます。 ".." で始まる行の先頭は "." に置き換えられます。 ディレクトリリスト (セレクタの最初の文字が "1") の場合にも、 同じプロトコルで転送されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.7.1 FTP オブジェクト Up: 11. インターネットプロトコルとその支援 Next: 11.9 poplib


11.9 poplib -- POP3 プロトコルクライアント

このモジュールは、 POP3 クラスを定義します。これはPOP3サーバへの 接続と、 RFC 1725 に定められたプロトコルを実装します。 POP3 クラスは minimalとoptinalという2つのコマンドセットをサポートします。

POP3についての注意事項は、それが広くサポートされているにもかかわらず、 既に時代遅れだということです。幾つも実装されているPOP3サーバーの品質は、 貧弱なものが多数を占めています。もし、お使いのメールサーバーがIMAPを サポートしているなら、 imaplib や IMAP4 が 使えます。 IMAPサーバーは、より良く実装されている傾向があります。

poplib モジュールでは、ひとつのクラスが提供されています。

class POP3( host[, port])
このクラスが、実際にPOP3プロトコルを実装します。インスタンスが初期化 されるときに、コネクションが作成されます。 port が省略されると、POP3標準のポート(110)が使われます。

1つの例外が、 poplib モジュールのアトリビュートとして定義されています。

exception error_proto
例外は、すべてのエラーで発生します。例外の理由は文字列としてコンストラクタに 渡されます。

参考資料:

imaplibモジュール:
The standard Python IMAP module.
Frequently Asked Questions About Fetchmail
POP/IMAPクライアント fetchmail のFAQ。POPプロトコルを ベースにしたアプリケーションを書くときに有用な、POP3サーバの種類や RFCへの適合度といった情報を収集しています。

  • 11.9.1 POP3 オブジェクト
  • 11.9.2 POP3 の例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.8 gopherlib Up: 11. インターネットプロトコルとその支援 Next: 11.9.1 POP3 オブジェクト


11.9.1 POP3 オブジェクト

POP3コマンドはすべて、それと同じ名前のメソッドとしてlower-caseで 表現されます。そしてそのほとんどは、サーバからのレスポンスとなる テキストを返します。

POP3 クラスのインスタンスは以下のメソッドを持ちます。

set_debuglevel( level)
インスタンスのデバッグレベルを指定します。これはデバッギングアウトプット の表示量をコントロールします。デフォルト値の 0 は、デバッギング アウトプットを表示しません。値を 1 とすると、デバッギングアウト プットの表示量を適当な量にします。これは大体、リクエストごと1行になります。 値を 2 以上にすると、デバッギングアウトプットの表示量を最大にします。 コントロール中の接続で送受信される各行をログに出力します。

getwelcome( )
POP3サーバーから送られるグリーティングメッセージを返します。

user( username)
userコマンドを送出します。応答はパスワード要求を表示します。

pass_( password)
パスワードを送出します。応答は、メッセージ数とメールボックスのサイズを 含みます。 注：サーバー上のメールボックスは quit() が呼ばれるまでロックされます。

apop( user, secret)
POP3サーバーにログオンするのに、よりセキュアなAPOP認証を使用します。

rpop( user)
POP3サーバーにログオンするのに、（UNIXのr-コマンドと同様の）RPOP認証を使用します。

stat( )
メールボックスの状態を得ます。結果は2つのintegerからなるタプルとなります。 (message count, mailbox size).

list( [which])
メッセージのリストを要求します。結果は以下のような形式で表されます。 (response, ['mesg_num octets', ...]) which が与えられると、それによりメッセージを指定します。

retr( which)
which 番のメッセージ全体を取り出し、そのメッセージに既読フラグを 立てます。結果は (response, ['line', ...], octets) という形式で表されます。

dele( which)
which 番のメッセージに削除のためのフラグを立てます。ほとんどの サーバで、QUITコマンドが実行されるまでは実際の削除は行われません （もっとも良く知られた例外は Eudora QPOPで、その配送メカニズムはRFCに 違反しており、どんな切断状況でも削除操作を未解決にしています）。

rset( )
メールボックスの削除マークすべてを取り消します。

noop( )
何もしません。接続保持のために使われます。

quit( )
Signoff: commit changes, unlock mailbox, drop connection. サインオフ：変更をコミットし、メールボックスをアンロックして、接続を破棄します。

top( which, howmuch)
メッセージヘッダと howmuch で指定した行数のメッセージを、 whichで指定したメッセージ分取り出します。結果は以下のような 形式となります。 (response, ['line', ...], octets).

このメソッドはPOP3のTOPコマンドを利用し、RETRコマンドのように、メッセージに 既読フラグをセットしません。残念ながら、TOPコマンドはRFCでは貧弱な仕様しか 定義されておらず、しばしばノーブランドのサーバーでは（その仕様が）守られて いません。このメソッドを信用してしまう前に、実際に使用するPOPサーバーで テストをしてください。

uidl( [which])
（ユニークIDによる）メッセージダイジェストのリストを返します。 which が設定されている場合、結果はユニークIDを含みます。それは 'response mesgnum uidという形式のメッセージ、 または(response, ['mesgnum uid', ...],octets)という 形式のリストとなります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.9 poplib Up: 11.9 poplib Next: 11.9.2 POP3 の例


11.9.2 POP3 の例

これは（エラーチェックもない）最も小さなサンプルで、メールボックスを 開いて、すべてのメッセージを取り出し、プリントします。

import getpass, poplib

M = poplib.POP3('localhost')
M.user(getpass.getuser())
M.pass_(getpass.getpass())
numMessages = len(M.list()[1])
for i in range(numMessages):
    for j in M.retr(i+1)[1]:
        print j

モジュールの末尾に、より広い範囲の使用例となるtestセクションがあります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.9.1 POP3 オブジェクト Up: 11.9 poplib Next: 11.10 imaplib


11.10 imaplib -- IMAP4 プロトコルクライアント

このモジュールでは三つのクラス、IMAP4, IMAP4_SSL と IMAP4_stream を定義します。これらのクラスは IMAP4 サーバへの接続をカプセル化し、 RFC 2060 に定義されている IMAP4rev1 クライアントプロトコルの大規模な サブセットを実装しています。このクラスは IMAP4 (RFC 1730) 準拠の サーバと後方互換性がありますが、"STATUS" コマンドは IMAP4 では サポートされていないので注意してください。

imaplib モジュール内では三つのクラスを提供しており、 IMAP4 は基底クラスとなります:

class IMAP4( [host[, port]])
このクラスは実際の IMAP4 プロトコルを実装しています。 インスタンスが初期化された際に接続が生成され、プロトコルバージョン (IMAP4 または IMAP4rev1) が決定されます。host が指定されて いない場合、 '' (ローカルホスト) が用いられます。 port が省略された場合、標準の IMAP4 ポート番号 (143) が用いられます。

例外は IMAP4 クラスの属性として定義されています:

exception IMAP4.error
何らかのエラー発生の際に送出される例外です。例外の理由は 文字列としてコンストラクタに渡されます。

exception IMAP4.abort
IMAP4 サーバのエラーが生じると、この例外が送出されます。 この例外は IMAP4.error のサブクラスです。 通常、インスタンスを閉じ、新たなインスタンスを再び生成することで、 この例外から復旧できます。

exception IMAP4.readonly
この例外は書き込み可能なメイルボックスの状態がサーバによって変更された 際に送出されます。 この例外は IMAP4.error のサブクラスです。 他の何らかのクライアントが現在書き込み権限を獲得しており、 メイルボックスを開きなおして書き込み権限を再獲得する必要があります。

このモジュールではもう一つ、安全 (secure) な接続を使ったサブクラスが あります:

class IMAP4_SSL( [host[, port[, keyfile[, certfile]]]])
IMAP4 から導出されたサブクラスで、SSL 暗号化ソケットを 介して接続を行います (このクラスを利用するためには SSL サポート付きで コンパイルされた socket モジュールが必要です) 。 host が指定されて いない場合、 '' (ローカルホスト) が用いられます。 port が省略された場合、標準の IMAP4-over-SSL ポート番号 (993) が用いられます。 keyfile および certfile もオプションです - これらは SSL 接続のための PEM 形式の秘密鍵 (private key) と認証チェイン (certificate chain) ファイルです。

さらにもう一つのサブクラスは、子プロセスで確立した接続を使用する 場合に使用します。

class IMAP4_stream( command)
IMAP4 から導出されたサブクラスで、commandを os.popen2()に渡して作成される stdin/stdout ディスクリプタと接続します。 バージョン2.3 以降で新規追加された 仕様です。

以下のユーティリティ関数が定義されています:

Internaldate2tuple( datestr)
IMAP4 INTERNALDATE 文字列を標準世界時 (Coordinated Universal Time) に変換します。time モジュール形式のタプルを返します。

Int2AP( num)
整数を [A .. P] からなる文字集合を用いて表現した 文字列に変換します。

ParseFlags( flagstr)
IMAP4 "FLAGS" 応答を個々のフラグからなるタプルに変換します。

Time2Internaldate( date_time)
time モジュールタプルを IMAP4 "INTERNALDATE"表現形式に変換します。文字列形式: "DD-Mmm-YYYY HH:MM:SS +HHMM" (二重引用符含む) を返します。

IMAP4 メッセージ番号は、メイルボックスに対する変更が行われた 後には変化します; 特に、 "EXPUNGE" 命令はメッセージの削除を 行いますが、残ったメッセージには再度番号を振りなおします。従って、 メッセージ番号ではなく、 UID 命令を使い、その UID を利用するよう 強く勧めます。

モジュールの末尾に、より拡張的な使用例が収められたテストセクションが あります。

参考資料:

プロトコルに関する記述、およびプロトコルを実装したサーバの ソースとバイナリは、全て ワシントン大学の IMAP Information Center (http://www.cac.washington.edu/imap/) にあります。

  • 11.10.1 IMAP4 オブジェクト
  • 11.10.2 IMAP4 の使用例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.9.2 POP3 の例 Up: 11. インターネットプロトコルとその支援 Next: 11.10.1 IMAP4 オブジェクト


11.10.1 IMAP4 オブジェクト

全ての IMAP4rev1 命令は、同じ名前のメソッドで表されており、大文字の ものも小文字のものもあります。

命令に対する引数は全て文字列に変換されます。例外は "AUTHENTICATE"の引数と "APPEND" の最後の引数で、これは IMAP4 リテラルとして 渡されます。必要に応じて (IMAP4 プロトコルが感知対象としている 文字が文字列に入っており、かつ丸括弧か二重引用符で囲われていなかった 場合) 文字列はクオートされます。しかし、"LOGIN" 命令の password 引数は常にクオートされます。文字列がクオートされない ようにしたい (例えば "STORE" 命令の flags 引数) 場合、 文字列を丸括弧で囲んでください (例: r'(\Deleted)')。

各命令はタプル: (type, [data, ...]) を返し、 type は通常 'OK' または 'NO' です。 data は命令に対する応答をテキストにしたものか、命令に対する 実行結果です。各 data は文字列かタプルとなります。タプルの場合、 最初の要素はレスポンスのヘッダで、次の要素にはデータが格納されます。 (ie: 'literal' value)

IMAP4 のインスタンスは以下のメソッドを持っています:

append( mailbox, flags, date_time, message)
指定された名前のメイルボックスにメッセージを追加します。

authenticate( func)
認証命令です -- 応答の処理が必要です。現在は実装されておらず、 例外を送出します。

check( )
サーバ上のメイルボックスにチェックポイントを設定します。 Checkpoint mailbox on server.

close( )
現在選択されているメイルボックスを閉じます。削除されたメッセージは 書き込み可能メイルボックスから除去されます。"LOGOUT" 前に 実行することを勧めます。

copy( message_set, new_mailbox)
message_set で指定したメッセージ群を new_mailbox の 末尾にコピーします。

create( mailbox)
mailbox と名づけられた新たなメイルボックスを生成します。

delete( mailbox)
mailbox と名づけられた古いメイルボックスを削除します。

expunge( )
選択されたメイルボックスから削除された要素を永久に除去します。 各々の削除されたメッセージに対して、"EXPUNGE" 応答を 生成します。返されるデータには "EXPUNGE" メッセージ番号を 受信した順番に並べたリストが入っています。

fetch( message_set, message_parts)
メッセージ (の一部) を取りよせます。message_parts はメッセージパートの名前を表す文字列を丸括弧で囲ったもので、 例えば: ""(UID BODY[TEXT])"" のようになります。 返されるデータはメッセージパートのエンベロープ情報とデータ からなるタプルです。

getacl( mailbox)
mailbox に対する "ACL" を取得します。 このメソッドは非標準ですが、 "Cyrus" サーバでサポートされています。

getquota( root)
"quota" root により、リソース使用状況と制限値を取得します。 このメソッドは RFC 2087 で定義されている IMAP4 QUOTA 拡張の一部です。 バージョン2.3 以降で新規追加された 仕様です。

getquotaroot( mailbox)
mailbox に対して "quota" root を実行した結果のリストを 取得します。 このメソッドは RFC 2087 で定義されている IMAP4 QUOTA 拡張の一部です。 バージョン2.3 以降で新規追加された 仕様です。

list( [directory[, pattern]])
pattern にマッチする directoryメイルボックス名を列挙します。 directory の標準の設定値は最上レベルのメイルフォルダで、 pattern は標準の設定では全てにマッチします。返されるデータには "LIST" 応答のリストが入っています。

login( user, password)
平文パスワードを使ってクライアントを照合します。 password はクオートされます。

login_cram_md5( user, password)
パスワードの保護のため、クライアント認証時に"CRAM-MD5"だけを使用します。 これは、"CAPABILITY"レスポンスに "AUTH=CRAM-MD5" が含まれる場合のみ 有効です。 バージョン2.3 以降で新規追加された 仕様です。
+

logout( )
サーバへの接続を遮断します。サーバからの "BYE" 応答を返します。

lsub( [directory[, pattern]])
購読しているメイルボックス名のうち、ディレクトリ内でパターンにマッチ するものを列挙します。 directory の標準の設定値は最上レベルのメイルフォルダで、 pattern は標準の設定では全てにマッチします。返されるデータには 返されるデータはメッセージパートエンベロープ情報とデータからなるタプルです。

noop( )
サーバに "NOOP" を送信します。

open( host, port)
host 上の port に対するソケットを開きます。 このメソッドで確立された接続オブジェクトは read、 readline、send、およびshutdown メソッドで 使われます。このメソッドはオーバライドすることができます。

partial( message_num, message_part, start, length)
メッセージの後略された部分を取り寄せます。 返されるデータはメッセージパートエンベロープ情報とデータからなるタプルです。

proxyauth( user)
userとして認証されたものとします。 認証された管理者がユーザの代理としてメイルボックスにアクセス する際に使用します。 バージョン2.3 以降で新規追加された 仕様です。
+
read( size)
遠隔のサーバから size バイト読み出します。 このメソッドはオーバライドすることができます。

readline( )
遠隔のサーバから一行読み出します。 このメソッドはオーバライドすることができます。

recent( )
サーバに更新を促します。新たなメッセージがない場合応答は None になり、そうでない場合 "RECENT" 応答の値になります。

rename( oldmailbox, newmailbox)
oldmailbox という名前のメイルボックスを newmailbox に名称変更します。

response( code)
応答 code を受信していれば、そのデータを返し、そうでなければ None を返します。通常の形式 (usual type) ではなく指定したコード を返します。

search( charset, criterion[, ...])
条件に合致するメッセージをメイルボックスから検索します。返される データには合致したメッセージ番号をスペースで分割したリストが入って います。charset は None でもよく、この場合にはサーバ への要求内に "CHARSET" は指定されません。IMAP プロトコルは 少なくとも一つの条件 (criterion) が指定されるよう要求しています; サーバがエラーを返した場合、例外が送出されます。

例:

# M is a connected IMAP4 instance...
msgnums = M.search(None, 'FROM', '"LDJ"')

# or:
msgnums = M.search(None, '(FROM "LDJ")')

select( [mailbox[, readonly]])
メイルボックスを選択します。返されるデータは mailbox 内の メッセージ数 ("EXISTS" 応答) です。標準の設定では mailbox は 'INBOX' です。readonly が設定された 場合、メイルボックスに対する変更はできません。

send( data)
遠隔のサーバに data を送信します。 このメソッドはオーバライドすることができます。

setacl( mailbox, who, what)
"ACL" を mailbox に設定します。 このメソッドは非標準ですが、 "Cyrus" サーバでサポートされています。

setquota( root, limits)
"quota" root のリソースを limits に設定します。 このメソッドは RFC 2087 で定義されている IMAP4 QUOTA 拡張の一部です。 バージョン2.3 以降で新規追加された 仕様です。

shutdown( )
open で確立された接続を閉じます。 このメソッドはオーバライドすることができます。

socket( )
サーバへの接続に使われているソケットインスタンスを返します。

sort( sort_criteria, charset, search_criterion[, ...])
sort 命令は search に結果の並べ替え (sort) 機能をつけた 変種です。返されるデータには、条件に合致するメッセージ番号をスペースで 分割したリストが入っています。 sort 命令は search_criterium の前に二つの引数を持ちます; sort_criteria のリストを丸括弧で囲ったものと、検索時の charset です。 search と違って、検索時の charset は必須です。 uid sort 命令もあり、search に対する uid search と同じように sort 命令に対応します。 sort 命令はまず、charset 引数の指定に従って searching criteria の文字列を解釈し、メイルボックスから与えられた検索条件に合致する メッセージを探します。次に、合致したメッセージの数を返します。

"IMAP4rev1" 拡張命令です。

status( mailbox, names)
mailbox の指定ステータス名の状態情報を要求します。

store( message_set, command, flag_list)
メイルボックス内のメッセージ群のフラグ設定を変更します。

subscribe( mailbox)
新たなメイルボックスを購読 (subscribe) します。

uid( command, arg[, ...])
command args を、メッセージ番号ではなく UID で指定されたメッセージ群に 対して実行します。命令内容に応じた応答を返します。少なくとも 一つの引数を与えなくてはなりません; 何も与えない場合、サーバは エラーを返し、例外が送出されます。

unsubscribe( mailbox)
古いメイルボックスの購読を解除 (unsubscribe) します。

xatom( name[, arg[, ...]])
サーバから "CAPABILITY" 応答で通知された単純な拡張命令を 許容 (allow) します。

IMAP4_SSL のインスタンスは追加のメソッドを一つだけ持ちます:

ssl( )
サーバへの安全な接続に使われる SSLObject インスタンスを返します。

以下の属性が IMAP4 のインスタンス上で定義されています:

PROTOCOL_VERSION
サーバから返された "CAPABILITY" 応答にある、サポートされている 最新のプロトコルです。

debug
デバッグ出力を制御するための整数値です。初期値はモジュール変数 Debug から取られます。3 以上の値にすると各命令をトレースします。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.10 imaplib Up: 11.10 imaplib Next: 11.10.2 IMAP4 の使用例


11.10.2 IMAP4 の使用例

以下にメイルボックスを開き、全てのメッセージを取得して印刷する 最小の (エラーチェックをしない) 使用例を示します:

import getpass, imaplib

M = imaplib.IMAP4()
M.login(getpass.getuser(), getpass.getpass())
M.select()
typ, data = M.search(None, 'ALL')
for num in data[0].split():
    typ, data = M.fetch(num, '(RFC822)')
    print 'Message %s\n%s\n' % (num, data[0][1])
M.logout()
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.10.1 IMAP4 オブジェクト Up: 11.10 imaplib Next: 11.11 nntplib


11.11 nntplib -- NNTP プロトコルクライアント

このモジュールでは、 クラス NNTP を定義しています。このクラス は NNTP プロトコルのクライアント側を実装しています。このモジュールを 使えば、ニュースリーダや記事投稿プログラム、または自動的にニュース記事を 処理するプログラムを実装することができます。NNTP (Network News Transfer Protocol、ネットニュース転送プロトコル) の詳細については、 インターネット RFC 977 を参照してください。

以下にこのモジュールの使い方の小さな例を二つ示します。 ニュースグループに関する統計情報を列挙し、最新 10 件の記事を出力 するには以下のようにします:

>>> s = NNTP('news.cwi.nl')
>>> resp, count, first, last, name = s.group('comp.lang.python')
>>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
Group comp.lang.python has 59 articles, range 3742 to 3803
>>> resp, subs = s.xhdr('subject', first + '-' + last)
>>> for id, sub in subs[-10:]: print id, sub
...
3792 Re: Removing elements from a list while iterating...
3793 Re: Who likes Info files?
3794 Emacs and doc strings
3795 a few questions about the Mac implementation
3796 Re: executable python scripts
3797 Re: executable python scripts
3798 Re: a few questions about the Mac implementation
3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules
3802 Re: executable python scripts
3803 Re: \POSIX{} wait and SIGCHLD
>>> s.quit()
'205 news.cwi.nl closing connection.  Goodbye.'

ファイルから記事を投稿するには、以下のようにします (この例では記事番号は有効な番号を指定していると仮定しています):

>>> s = NNTP('news.cwi.nl')
>>> f = open('/tmp/article')
>>> s.post(f)
'240 Article posted successfully.'
>>> s.quit()
'205 news.cwi.nl closing connection.  Goodbye.'

このモジュール自体では以下の内容を定義しています:

class NNTP( host[, port [, user[, password [, readermode]]]])
ホスト host 上で動作し、ポート番号 port で要求待ちを している NNTP サーバとの接続を表現する新たな NNTP クラスの インスタンスを返します。標準のport は 119 です。オプションの user および password が与えられているか、 または /.netrcに適切な認証情報が指定されている場合、 "AUTHINFO USER" および "AUTHINFO PASS" 命令を使って サーバに対して身元証明および認証を行います。オプションのフラグ readermode が真の場合、認証の実行に先立って "mode reader" 命令が送信されます。reader モードは、ローカルマシン上の NNTP サーバ に接続していて、"group" のような reader 特有の命令を呼び出し たい場合に便利なことがあります。予期せず NNTPPermanentError に遭遇したなら、readermode を設定する必要があるかもしれません。 readermode 標準で None です。

class NNTPError( )
標準の例外 Exception から導出されており、nntplib モジュールが送出する全ての例外の基底クラスです。

class NNTPReplyError( )
期待はずれの応答がサーバから返された場合に送出される例外です。 以前のバージョンとの互換性のために、error_reply はこのクラスと等価になっています。

class NNTPTemporaryError( )
エラーコードの範囲が 400-499 のエラーを受信した場合に送出される例外です。 以前のバージョンとの互換性のために、error_temp はこのクラスと等価になっています。

class NNTPPermanentError( )
エラーコードの範囲が 500-599 のエラーを受信した場合に送出される例外です。 以前のバージョンとの互換性のために、error_perm はこのクラスと等価になっています。

class NNTPProtocolError( )
サーバから返される応答が 1-5 の範囲の数字で始まっていない場合に 送出される例外です。 以前のバージョンとの互換性のために、error_proto はこのクラスと等価になっています。

class NNTPDataError( )
応答データ中に何らかのエラーが存在する場合に送出される例外です。 以前のバージョンとの互換性のために、error_data はこのクラスと等価になっています。

  • 11.11.1 NNTP オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.10.2 IMAP4 の使用例 Up: 11. インターネットプロトコルとその支援 Next: 11.11.1 NNTP オブジェクト


11.11.1 NNTP オブジェクト

NNTP インスタンスは以下のメソッドを持っています。全てのメソッドにおける 戻り値のタプルで最初の要素となる response は、サーバの応答 です: この文字列は 3 桁の数字からなるコードで始まります。 サーバの応答がエラーを示す場合、上記のいずれかの例外が送出されます。

getwelcome( )
サーバに最初に接続した際に送信される応答中のウェルカムメッセージを 返します。(このメッセージには時に、ユーザにとって重要な免責事項や ヘルプ情報が入っています。)

set_debuglevel( level)
インスタンスのデバッグレベルを設定します。このメソッドは印字される デバッグ出力の量を制御します。標準では 0 に設定されていて、 これはデバッグ出力を全く印字しません。1 はそこそこの量、 一般に NNTP 要求や応答あたり 1 行のデバッグ出力を生成します。 値が 2 やそれ以上の場合、(メッセージテキストを含めて) NNTP 接続上で送受信された全ての内容を一行ごとにログ出力する、 最大限のデバッグ出力を生成します。

newgroups( date, time, [file])
"NEWSGROUPS" 命令を送信します。date 引数は 'yymmdd' の形式を取り、日付を表します。 time 引数は 'hhmmss' の形式をとり、 時刻を表します。与えられた日付および時刻以後新たに出現した ニュースグループ名のリストを groups として、 (response, groups) を返します。 file引数が指定されている場合、"NEWGROUPS"コマンドの出力結果は ファイルに格納されます。fileが文字列の場合、この文字列をファイル名 としてファイルをオープンし、書き込み後にクローズします。fileがファ イルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出し て出力結果を格納します。fileが指定されている場合は戻り値として空の リストを返します。

newnews( group, date, time, [file])
"NEWNEWS" 命令を送信します。ここで、group はグループ名 または '*' で、 date および time は newsgrups() における引数と同じ意味を持ちます。 (response, articles) からなるペアを返し、 articles は記事 ID のリストです。 file引数が指定されている場合、"NEWNEWS"コマンドの出力結果は ファイルに格納されます。fileが文字列の場合、この文字列をファイル名 としてファイルをオープンし、書き込み後にクローズします。fileがファ イルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出し て出力結果を格納します。fileが指定されている場合は戻り値として空の リストを返します。

list( [file])
"LIST" 命令を送信します。(response, list) からなるペアを返します。list はタプルからなるリストです。 各タプルは (group, last, first, flag) の形式をとり、group がグループ名、last および first はそれぞれ最新および最初の記事の記事番号 (を表す文字列)、そして flag は投稿が可能な場合には 'y'、そうでない場合には 'n'、グループがモデレート (moderated) されている場合には 'm' となります。(順番に注意してください: last、 first の順です。) file引数が指定されている場合、"LIST"コマンドの出力結果は ファイルに格納されます。fileが文字列の場合、この文字列をファイル名 としてファイルをオープンし、書き込み後にクローズします。fileがファ イルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出し て出力結果を格納します。fileが指定されている場合は戻り値として空の リストを返します。

group( name)
"GROUP" 命令を送信します。name はグループ名です。タプル (response, count, first, last, name) を返します。count はグループ中の記事数 (の推定値) で、 first はグループ中の最初の記事番号、last はグループ中の 最新の記事番号、name はグループ名です。記事番号は文字列で 返されます。

help( [file])
"HELP" 命令を送信します。(response, list) からなるペアを返します。list はヘルプ文字列からなるリストです。 file引数が指定されている場合、"HELP"コマンドの出力結果は ファイルに格納されます。fileが文字列の場合、この文字列をファイル名 としてファイルをオープンし、書き込み後にクローズします。fileがファ イルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出し て出力結果を格納します。fileが指定されている場合は戻り値として空の リストを返します。

stat( id)
"STAT" 命令を送信します。id は ("<" と ">" に囲まれた形式の) メッセージ ID か、 (文字列の) 記事番号です。 三つ組み (response, number, id) を返します。 number は (文字列の) 記事番号で、id は ("<" と ">" に囲まれた形式の) メッセージ ID です。

next( )
"NEXT" 命令を送信します。stat() のような応答を返します。

last( )
"LAST" 命令を送信します。stat() のような応答を返します。

head( id)
"HEAD" 命令を送信します。id は stat() における のと同じ意味を持ちます。 (response, number, id, list) からなるタプルを返します。最初の 3 要素は stat() と 同じもので、list は記事のヘッダからなるリスト (まだ解析されておらず、末尾の改行が取り去られたヘッダ行のリスト) です。

body( id,[file])
"BODY" 命令を送信します。id は stat() における のと同じ意味を持ちます。file 引数が与えられている場合、 記事本体 (body) はファイルに保存されます。file が文字列 の場合、このメソッドはその名前を持つファイルオブジェクトを 開き、記事を書き込んで閉じます。file がファイルオブジェクトの 場合、write() を呼び出して記事本体を記録します。 head() のような戻り値を返します。file が与えられて いた場合、 返される list は空のリストになります。

article( id)
"ARTICLE" 命令を送信します。id は stat() における のと同じ意味を持ちます。head() のような戻り値を返します。

slave( )
"SLAVE" 命令を送信します。サーバの response を返します。

xhdr( header, string, [file])
"XHDR" 命令を送信します、この命令は RFC には定義されていませんが、 一般に広まっている拡張です。header 引数は、例えば 'subject' といったヘッダキーワードです。string 引数は 'first-last' の形式でなければならず、ここで first および last は検索の対象とする記事範囲の最初と最後の 記事番号です。(response, list) のペアを返します。 list は (id, text) のペアからなるリストで、 id が (文字列で表した) 記事 ID、text がその記事の ヘッダテキストです。 file引数が指定されている場合、"XHDR"コマンドの出力結果は ファイルに格納されます。fileが文字列の場合、この文字列をファイル名 としてファイルをオープンし、書き込み後にクローズします。fileがファ イルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出し て出力結果を格納します。fileが指定されている場合は戻り値として空の リストを返します。

post( file)
"POST" 命令を使って記事をポストします。file 引数は開かれているファイルオブジェクトで、その内容は readline() メソッドを使って EOF まで読み出されます。 内容は必要なヘッダを含め、正しい形式のニュース記事で なければなりません。post() メソッドは "."で始まる行を自動的にエスケープします。

ihave( id, file)
"IHAVE" 命令を送信します。応答がエラーでない場合、 file を post() と全く同じように扱います。

date( )
タプル (response, date, time) を返します。 このタプルには newnews() および newgroups() メソッド に合った形式の、現在の日付および時刻が入っています。 これはオプションの NNTP 拡張なので、全てのサーバでサポートされている とは限りません。

xgtitle( name, [file])
"XGTITLE" 命令を処理し、(response, list) からなるペアを返します。list は (name, title) を含むタプルのリストです。 file引数が指定されている場合、"XHDR"コマンドの出力結果は ファイルに格納されます。fileが文字列の場合、この文字列をファイル名 としてファイルをオープンし、書き込み後にクローズします。fileがファ イルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出し て出力結果を格納します。fileが指定されている場合は戻り値として空の リストを返します。 これはオプションの NNTP 拡張なので、全てのサーバでサポートされている とは限りません。

xover( start, end, [file])
(resp, list) からなるペアを返します。 list はタプルからなるリストで、各タプルは記事番号 start および end の間に区切られた記事です。各タプルは (article number, subject, poster, date, id, references, size, lines) の形式をとります。 file引数が指定されている場合、"XHDR"コマンドの出力結果は ファイルに格納されます。fileが文字列の場合、この文字列をファイル名 としてファイルをオープンし、書き込み後にクローズします。fileがファ イルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出し て出力結果を格納します。fileが指定されている場合は戻り値として空の リストを返します。 これはオプションの NNTP 拡張なので、全てのサーバでサポートされている とは限りません。

xpath( id)
(resp, path) からなるペアを返します。 path は メッセージ ID が id である記事のディレクトリパスです。 これはオプションの NNTP 拡張なので、全てのサーバでサポートされている とは限りません。

quit( )
"QUIT" 命令を送信し、接続を閉じます。このメソッドを呼び出した 後は、NTTP オブジェクトの他のいかなるメソッドも呼び出してはいけません。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.11 nntplib Up: 11.11 nntplib Next: 11.12 smtplib


11.12 smtplib -- SMTP プロトコル クライアント

smtplibモジュールは、SMTPまたはESMTPのリスナーデーモンを備えた 任意のインターネット上のホストにメイルを送るために使用することができる SMTPクライアント・セッション・オブジェクトを定義します。 SMTPおよびESMTPオペレーションの詳細は、 RFC 821 (Simple Mail Transfer Protocol) や RFC 1869 (SMTP Service Extensions)を調べてください。

class SMTP( [host[, port[, local_hostname]]])
SMTPインスタンスはSMTPコネクションをカプセル化し、 SMTPとESMTPの命令をサポートをします。 オプションであるhostとportを与えた場合は、 SMTPクラスのインスタンスが作成されると同時に、 connect()メソッドを呼び出し初期化されます。 また、ホストから応答が無い場合は、SMTPConnectErrorが上げられます。

普通に使う場合は、初期化と接続を行ってから、 sendmail()とquit()メソッドを呼びます。 使用例は先の方で記載しています。

このモジュールの例外には次のものがあります:

exception SMTPException
このモジュールの例外クラスのベースクラスです。

exception SMTPServerDisconnected
この例外はサーバが突然コネクションを切断するか、 もしくはSMTPインスタンスを生成する前にコネクションを張ろうと した場合に上げられます。

exception SMTPResponseException
SMTPのエラーコードを含んだ例外のクラスです。 これらの例外はSMTPサーバがエラーコードを返すときに生成されます。 エラーコードはsmtp_code属性に格納されます。 また、smtp_error属性にはエラーメッセージが格納されます。

exception SMTPSenderRefused
送信者のアドレスが弾かれたときに上げられる例外です。 全てのSMTPResponseException例外に、 SMTPサーバが弾いた`sender'アドレスの文字列がセットされます。

exception SMTPRecipientsRefused
全ての受取人アドレスが弾かれたときに上げられる例外です。 各受取人のエラーは属性recipientsによってアクセス可能で、 SMTP.sendmail()が返す辞書と同じ並びの辞書になっています。

exception SMTPDataError
SMTPサーバが、メッセージのデータを受け入れることを拒絶した時に 上げられる例外です。

exception SMTPConnectError
サーバへの接続時にエラーが 発生した時に上げられる例外です。

exception SMTPHeloError
サーバーが"HELO"メッセージを弾いた時に上げられる例外です。

参考資料:

RFC 821, Simple Mail Transfer Protocol
SMTP のプロトコル定義 です。このドキュメントでは SMTP のモデル、操作手順、プロトコルの 詳細についてカバーしています。
RFC 1869, SMTP Service Extensions
SMTP に対する ESMTP 拡張の定義です。このドキュメントでは、 新たな命令による SMTP の拡張、サーバによって提供される命令を 動的に発見する機能のサポート、およびいくつかの追加命令定義 について記述しています。

  • 11.12.1 SMTP オブジェクト
  • 11.12.2 SMTP 使用例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.11.1 NNTP オブジェクト Up: 11. インターネットプロトコルとその支援 Next: 11.12.1 SMTP オブジェクト


11.12.1 SMTP オブジェクト

SMTPクラスインスタンスは次のメソッドを提供します:

set_debuglevel( level)
コネクション間でやりとりされるメッセージ出力のレベルをセットします。 メッセージの冗長さはlevelに応じて決まります。

connect( [host[, port]])
ホスト名とポート番号をもとに接続します。デフォルトはlocalhostの 標準的なSMTPポート(25番)に接続します。 もしホスト名の末尾がコロン(":")で、後に番号がついている場合は、 「ホスト名:ポート番号」として扱われます。 このメソッドはコンストラクタにホスト名及びポート番号が指定されている場合、 自動的に呼び出されます。

docmd( cmd, [, argstring])
サーバへコマンドcmdを送信します。 オプション引数argstringはスペース文字でコマンドに連結します。 戻り値は、整数値のレスポンスコードと、サーバからの応答の値をタプルで返します。 (サーバからの応答が数行に渡る場合でも一つの大きな文字列で返します。)

通常、この命令を明示的に使う必要はありませんが、 自分で拡張するする時に使用するときに役立つかもしれません。

応答待ちのときに、サーバへのコネクションが失われると、 SMTPServerDisconnectedが上がります。

helo( [hostname])
SMTPサーバに"HELO"コマンドで身元を示します。 デフォルトではhostname引数はローカルホストを指します。

通常はsendmail()が呼びだすため、 これを明示的に呼び出す必要はありません。

ehlo( [hostname])
"EHLO"を利用し、ESMTPサーバに身元を明かします。 デフォルトではhostname引数はローカルホストを指します。

また、ESMTPオプションのために応答を調べたものは、 has_extn()に備えて保存されます。

has_extn()をメールを送信する前に使わない限り、 明示的にこのメソッドを呼び出す必要があるべきではなく、 sendmail()が必要とした場合に呼ばれます。、

has_extn( name)
nameが拡張SMTPサービス可能な場合には1を返し、 そうでなければ0を返します。

verify( address)
"VRFY"を利用してSMTPサーバにアドレスの妥当性をチェックします。 妥当である場合はコード250と完全なRFC 822アドレス(人名)のタプルを返します。 それ以外の場合は、400以上のエラーコードとエラー文字列を返します。

注意: ほとんどのサイトはスパマーの裏をかくためにSMTPの"VRFY"は 使用不可になっています。

login( user, password)
認証が必要なSMTPサーバにログインします。 認証に使用する引数はユーザ名とパスワードです。 まだセッションが無い場合は、"EHLO"または"HELO"コマンドで セッションを作ります。ESMTPの場合は"EHLO"が先に試されます。 認証が成功した場合は通常このメソッドは戻りますが、 例外が起こった場合は以下の例外が上がります:

SMTPHeloError
サーバが"HELO"に返答できなかった。
SMTPAuthenticationError
サーバがユーザ名/パスワードでの認証に失敗した。
SMTPError
どんな認証方法も見付からなかった。

starttls( [keyfile[, certfile]])
TLS(Transport Layer Security)モードでSMTPコネクションを出し、 全てのSMTPコマンドは暗号化されます。 これはehlo()をもう一度呼びだすときにするべきです。

keyfileとcertfileが提供された場合に、 socketモジュールのssl()関数が通るようになります。

sendmail( from_addr, to_addrs, msg[, mail_options, rcpt_options])
メールを送信します。必要な引数はRFC 822のfromアドレス文字列、 RFC 822のtoアドレス文字列のリスト、メッセージ文字列です。 送信側は"MAIL FROM"コマンドで使用されるmail_optionsの ESMTPオプション("8bitmime"のような)のリストを得るかもしれません。

全ての"RCPT"コマンドで使われるべきESMTPオプション (例えば"DSN"コマンド)は、rcpt_optionsを通して 利用することができます。(もし送信先別にESMTPオプションを使う必要があれば、 メッセージを送るためにmail、rcpt、data といった下位レベルのメソッドを使う必要があります。)

注意: 配送エージェントはfrom_addr、to_addrs引数を使い、 メッセージのエンベロープを構成します。 SMTPはメッセージヘッダを修正しません。

まだセッションが無い場合は、"EHLO"または"HELO"コマンドで セッションを作ります。ESMTPの場合は"EHLO"が先に試されます。 また、サーバがESMTP対応ならば、メッセージサイズとそれぞれ指定された オプションも渡します。(featureオプションがあればサーバの広告をセットします) "EHLO"が失敗した場合は、ESMTPオプションの無い"HELO"が試されます。

このメソッドはメールが受け入れられたときは普通に戻りますが、 そうでない場合は例外を投げます。このメソッドが例外を投げられなければ、 誰かが送信したメールを得るべきです。また、例外を投げれなかった場合は、 拒絶された受取人ごとへの1つのエントリーと共に、辞書を返します。 各エントリーは、サーバーによって送られたSMTPエラーコードおよび エラーメッセージのタプルを含んでいます。

このメソッドは次の例外を上げることがあります:

SMTPRecipientsRefused
全ての受信を拒否され、誰にもメールが届けられませんでした。 例外オブジェクトのrecipients属性は、 受信拒否についての情報の入った辞書オブジェクトです。 (辞書は少なくとも一つは受信されたときに似ています)。

SMTPHeloError
サーバが"HELP"に返答しませんでした。

SMTPSenderRefused
サーバがfrom_addrを弾きました。

SMTPDataError
サーバが予期しないエラーコードを返しました。(受信拒否以外)

また、この他の注意として、例外が上がった後も コネクションは開いたままになっています。

quit( )
SMTPセッションを終了し、コネクションを閉じます。

下位レベルのメソッドは標準SMTP/ESMTPコマンド"HELP"、 "RSET"、 "NOOP"、"MAIL"、"RCPT"、"DATA"に対応しています。 通常これらは直接呼ぶ必要はなく、また、ドキュメントもありません。 詳細はモジュールのコードを調べてください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.12 smtplib Up: 11.12 smtplib Next: 11.12.2 SMTP 使用例


11.12.2 SMTP 使用例

次の例は最低限必要なメールアドレス(`To' と `From')を含んだ メッセージを送信するものです。この例ではRFC 822ヘッダの加工もしていません。 メッセージに含まれるヘッダは、メッセージに含まれる必要があり、 特に、明確な'To'、と'From'アドレスはメッセージヘッダに 含まれている必要があります。

import smtplib
import string

def prompt(prompt):
    return raw_input(prompt).strip()

fromaddr = prompt("From: ")
toaddrs  = prompt("To: ").split()
print "Enter message, end with ^D (Unix) or ^Z (Windows):"

# Add the From: and To: headers at the start!
msg = ("From: %s\r\nTo: %s\r\n\r\n"
       % (fromaddr, ", ".join(toaddrs, ", ")))
while 1:
    try:
        line = raw_input()
    except EOFError:
        break
    if not line:
        break
    msg = msg + line

print "Message length is " + repr(len(msg))

server = smtplib.SMTP('localhost')
server.set_debuglevel(1)
server.sendmail(fromaddr, toaddrs, msg)
server.quit()
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.12.1 SMTP オブジェクト Up: 11.12 smtplib Next: 11.13 telnetlib


11.13 telnetlib -- Telnet クライアント

telnetlib モジュールでは、Telnet プロトコルを実装している Telnet クラスを提供します。Telnet プロトコルについての詳細は RFC 854 を参照してください。加えて、このモジュールでは Telnet プロトコルにおける制御文字 (下を参照してください) と、telnet オプション に対するシンボル定数を提供しています。telnet オプションに対する シンボル名は arpa/telnet.h の TELOPT_ がない状態 での定義に従います。伝統的に arpa/telnet.h に含められて いない telnet オプションのシンボル名については、このモジュールの ソースコード自体を参照してください。

telnet コマンドのシンボル定数は、IAC、DONT、DO、WONT、WILL、SE (サブネゴシエーション終了)、NOP (何もしない)、DM (データマーク)、 BRK (ブレーク)、IP (プロセス割り込み)、AO (出力中断)、 AYT (応答確認)、EC (文字削除)、EL (行削除)、GA (進め)、SB ( サブネゴシエーション開始) です。

class Telnet( [host[, port]])
Telnet は Telnet サーバへの接続を表現します。 標準では、Telnet クラスのインスタンスは最初はサーバに 接続していません; 接続を確立するには open() を使わなければ なりません。別の方法として、コンストラクタにホスト名とオプションの ポート番号を渡すことができます。この場合はコンストラクタの呼び出し が返る以前にサーバへの接続が確立されます。

すでに接続の開かれているンスタンスを再度開いてはいけません。

このクラスは多くの read_*() メソッドを持っています。 これらのメソッドのいくつかは、接続の終端を示す文字を読み込んだ場合に EOFError を送出するので注意してください。例外を送出する のは、これらの関数が終端に到達しなくても空の文字列を返す可能性 があるからです。詳しくは下記の個々の説明を参照してください。

参考資料:

RFC 854, Telnet プロトコル仕様 (Telnet Protocol Specification)
Telnet プロトコルの定義。

  • 11.13.1 Telnet オブジェクト
  • 11.13.2 Telnet Example
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.12.2 SMTP 使用例 Up: 11. インターネットプロトコルとその支援 Next: 11.13.1 Telnet オブジェクト


11.13.1 Telnet オブジェクト

Telnet インスタンスは以下のメソッドを持っています:

read_until( expected[, timeout])
expectedで指定された文字列を読み込むか、timeoutで指定された 秒数が経過するまで読み込みます。

与えられた文字列に一致する部分が見つからなかった場合、読み込む ことができたもの全てを返します。これは空の文字列になる可能性が あります。接続が閉じられ、転送処理済みのデータが得られない場合 には EOFError が送出されます。

read_all( )
EOFに到達するまでの全てのデータを読み込みます; 接続が 閉じられるまでブロックします。

read_some( )
EOF に到達しない限り、少なくとも 1 バイトの転送処理済みデータ を読み込みます。EOF に到達した場合は '' を返します。 すぐに読み出せるデータが存在しない場合にはブロックします。

read_very_eager( )
I/O によるブロックを起こさずに読み出せる全てのデータを読み込み ます (eager モード)。

接続が閉じられており、転送処理済みのデータとして読み出せるもの がない場合には EOFError が送出されます。それ以外の 場合で、単に読み出せるデータがない場合には '' を返します。 IAC シーケンス操作中でないかぎりブロックしません。

read_eager( )
現在すぐに読み出せるデータを読み出します。

接続が閉じられており、転送処理済みのデータとして読み出せるものが ない場合には EOFError が送出されます。それ以外の 場合で、単に読み出せるデータがない場合には '' を返します。 IAC シーケンス操作中でないかぎりブロックしません。

read_lazy( )
すでにキューに入っているデータを処理して返します (lazy モード)。

接続が閉じられており、読み出せるデータがない場合には EOFError を送出します。それ以外の場合で、転送処理済みの データで読み出せるものがない場合には '' を返します。 IAC シーケンス操作中でないかぎりブロックしません。

read_very_lazy( )
すでに処理済みキューに入っているデータを処理して返します (very lazy モード)。

接続が閉じられており、読み出せるデータがない場合には EOFError を送出します。それ以外の場合で、転送処理済みの データで読み出せるものがない場合には '' を返します。 このメソッドは決してブロックしません。

read_sb_data( )
SB/SE ペア (サブオプション開始／終了) の間に収集されたデータを返します。 SE コマンドによって起動されたコールバック関数はこれらのデータ にアクセスしなければなりません。

このメソッドはけっしてブロックしません。 バージョン2.3 以降で新規追加された 仕様です。

open( host[, port])
サーバホストに接続します。 第二引数はオプションで、ポート番号を指定します。 標準の値は通常の Telnet ポート番号 (23) です。

すでに接続しているインスタンスで再接続を試みてはいけません。

msg( msg[, *args])
デバッグレベルが > 0 のとき、デバッグ用のメッセージを 出力します。追加の引数が存在する場合、標準の 文字列書式化演算子 % を使って msg 中の 書式指定子に代入されます。

set_debuglevel( debuglevel)
デバッグレベルを設定します。debuglevel が大きくなるほど、 (sys.stdout に) デバッグメッセージがたくさん出力されます。

close( )
接続を閉じます。

get_socket( )
内部的に使われているソケットオブジェクトです。

fileno( )
内部的に使われているソケットオブジェクトのファイル記述子です。

write( buffer)
ソケットに文字列を書き込みます。このとき IAC 文字については 2 度送信します。接続がブロックした場合、書き込みがブロックする 可能性があります。接続が閉じられた場合、socket.error が送出されるかもしれません。

interact( )
非常に低機能の telnet クライアントをエミュレートする対話 関数です。

mt_interact( )
interact() のマルチスレッド版です。

expect( list[, timeout])
正規表現のリストのうちどれか一つにマッチするまでデータを読みます。

第一引数は正規表現のリストです。コンパイルされたもの (re.RegexObject のインスタンス) でも、コンパイルされて いないもの (文字列) でもかまいません。オプションの第二引数は タイムアウトで、単位は秒です; 標準の値は無期限に設定されています。

3 つの要素からなるタプル: 最初にマッチした正規表現のインデクス; 返されたマッチオブジェクト; マッチ部分を含む、マッチするまでに読み込まれたテキストデータ、 を返します。

ファイル終了子が見つかり、かつ何もテキストデータが読み込まれ なかった場合、EOFError が送出されます。そうでない 場合で何もマッチしなかった場合には (-1, None, text) が返されます。ここで text はこれまで受信したテキストデータ です (タイムアウトが発生した場合には空の文字列になる場合もあります)。

正規表現の末尾が (.* のような) 貪欲マッチングになっている 場合や、入力に対して 1 つ以上の正規表現がマッチする場合には、 その結果は決定不能で、I/O のタイミングに依存するでしょう。

set_option_negotiation_callback( callback)
telnet オプションが入力フローから読み込まれるたびに、 callback が (設定されていれば) 以下の引数形式: callback(telnet socket, command (DO/DONT/WILL/WONT), option) で呼び出されます。その後 telnet オプションに対しては telnetlib は何も行いません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.13 telnetlib Up: 11.13 telnetlib Next: 11.13.2 Telnet Example


11.13.2 Telnet Example

典型的な使い方を表す単純な例を示します:

import getpass
import sys
import telnetlib

HOST = "localhost"
user = raw_input("Enter your remote account: ")
password = getpass.getpass()

tn = telnetlib.Telnet(HOST)

tn.read_until("login: ")
tn.write(user + "\n")
if password:
    tn.read_until("Password: ")
    tn.write(password + "\n")

tn.write("ls\n")
tn.write("exit\n")

print tn.read_all()
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.13.1 Telnet オブジェクト Up: 11.13 telnetlib Next: 11.14 urlparse


11.14 urlparse -- URL を解析して構成要素にする

このモジュールでは URL (Uniform Resource Locator) 文字列をその構成要素 (アドレススキーム、ネットワーク上の位置、パスその他) に分解したり、 構成要素を URL に組みなおしたり、``相対 URL (relative URL)'' を指定した ``基底 URL (base URL)'' に基づいて絶対 URL に変換するための標準的な インタフェースを定義しています。

このモジュールは相対 URL のインターネット RFC に対応するように設計 されました (そして RFC の初期ドラフトのバグを発見しました！)。

以下の関数が定義されています:

urlparse( urlstring[, default_scheme[, allow_fragments]])
URL を解釈して 6 つの構成要素にし、6 要素のタプル: (アドレススキーム、ネットワーク上の位置、パス、パラメタ、クエリ、 フラグメント指定子) を返します。このタプルは URL の一般的な 構造: scheme://netloc/path;parameters?query#fragment に対応しています。 各タプル要素は文字列で、空の場合もあります。 構成要素がさらに小さい要素に分解されることはありません (例えば ネットワーク上の位置は単一の文字列になります)。また % によるエスケープ は展開されません。上で示された区切り文字がタプルの各要素の一部分 として含まれることはありませんが、path 要素の先頭のスラッシュ がある場合には例外です。

以下の例:

urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')

では、タプル

('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '')

になります。

default_scheme 引数が最低されている場合、標準のアドレススキーム を表し、アドレススキームを指定していない URL 文字列に対してのみ 使われます。この引数の標準の値は空文字列です。

allow_fragments 引数がゼロの場合、URL のアドレススキームが フラグメント指定をサポートしていても指定できなくなります。 この引数の標準の値は 1 です。

urlunparse( tuple)
urlparse() が返すような形式のタプルから URL 文字列を構築します。 解析された元の URL が、例えばクエリ内容が空の ? のような冗長な区切り文字 を持っていた場合には、多少違いはあるが等価な URL になるかもしれません。 (RFC のドラフトの時点では、これらは等価でした)。

urlsplit( urlstring[, default_scheme[, allow_fragments]])
urlparse() に似ていますが、URL から params を切り離し ません。このメソッドは通常、URL の path 部分において、各セグメント にパラメタ指定をできるようにした最近の URL 構文 (RFC 2396 参照) の 場合に、urlparse() の代わりに使われます。 パスセグメントとパラメタを分割するためには分割用の関数が必要 です。この関数は 5 要素のタプル: (アドレススキーム、ネットワーク上の位置、パス、クエリ、フラグメント指定子) を返します。 バージョン2.2 以降で新規追加された 仕様です。

urlunsplit( tuple)
urlsplit() が返すような形式のタプル中のエレメントを組み合わせ て、文字列の完全な URL にします。 バージョン2.2 以降で新規追加された 仕様です。

urljoin( base, url[, allow_fragments])
``基底 URL'' (base) と ``相対 URL'' (url) を組み合わせて、 完全な URL (``絶対 URL'') を構成します。 ぶっちゃけ、この関数は 基底 URL の要素、特にアドレススキーム、 ネットワーク上の位置、およびパス (の一部) を使って、相対 URL に ない要素を提供します。

以下の例:

urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')

では、文字列

'http://www.cwi.nl/%7Eguido/FAQ.html'

になります。

allow_fragments 引数は urlparse() における引数と同じ意味 を持ちます。

urldefrag( url)
url がフラグメント指定子を含む場合、フラグメント指定子 を持たないバージョンに修正された url と、別の文字列に分割 されたフラグメント指定子を返します。url 中にフラグメント 指定子がない場合、そのままの url と空文字列を返します。

参考資料:

RFC 1738, Uniform Resource Locators (URL)
この RFC では絶対 URL の形式的な文法と意味付けを仕様化しています。
RFC 1808, Relative Uniform Resource Locators
この RFC には絶対 URL と相対 URL を結合するための規則が ボーダケースの取扱い方を決定する ``異常な例'' つきで 収められています。
RFC 2396, Uniform Resource Identifiers (URI): Generic Syntax
この RFC では Uniform Resource Name (URN) と Uniform Resource Locator (URL) の両方に対する一般的な文法的要求事項を記述しています。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.13.2 Telnet Example Up: 11. インターネットプロトコルとその支援 Next: 11.15 SocketServer


11.15 SocketServer -- ネットワークサーバ構築のための フレームワーク

SocketServer モジュールはネットワークサーバを実装するタスクを 単純化します。

このモジュールには 4 つのサーバクラスがあります: TCPServer は、クライアントとサーバ間に継続的なデータ流路を提供 する、インターネット TCP プロトコルを使います。 UDPServer は、順序通りに到着しなかったり、転送中に喪失して しまってもかまわない情報の断続的なパケットである、データグラムを使います。 UnixStreamServer および UnixDatagramServer クラスも 同様ですが、Unix ドメインソケットを使います; 従って非 Unix プラットフォームでは利用できません。ネットワークプログラミングに ついての詳細は、W. Richard Steven 著 UNIX Network Programming や、 Ralph Davis 著 Win32 Network Programming のような 書籍を参照してください。

これらの 4 つのクラスは要求を 同期的に (synchronously) 処理します; 各要求は次の要求を開始する前に完結していなければなりません。 同期的な処理は、サーバで大量の計算を必要とする、あるいはクライアントが 処理するには時間がかかりすぎるような大量のデータを返す、といった理由に よってリクエストに長い時間がかかる状況には向いていません。 こうした状況の解決方法は別のプロセスを生成するか、個々の要求を 扱うスレッドを生成することです; ForkingMixIn および ThreadingMixIn 配合クラス (mix-in classes) を使えば、非同期的な動作をサポートできます。

サーバの作成にはいくつかのステップがあります。最初に、 BaseRequestHandler クラスをサブクラス化して 要求処理クラス (request hander class) を生成し、その handle() メソッドを上書きしなければなりません; このメソッドで入力される 要求を処理します。次に、サーバクラスのうち一つをインスタンス化して、 サーバのアドレスと要求処理クラスを渡さなければなりません。最後に、 サーバオブジェクトの handle_request() または serve_forever() メソッドを呼び出して、単一または多数の 要求を処理します。

ThreadingMixIn から継承してスレッドを利用した接続を行う場合、 突発的な通信切断時の処理を明示的に指定する必要があります。 ThreadingMixIn クラスには daemon_threads 属性があり、 サーバがスレッドの終了を待ち合わせるかどうかを指定する事ができます。 スレッドが独自の処理を行う場合は、このフラグを明示的に指定します。 デフォルトはFalseで、PythonはThreadingMixInクラス が起動した全てのスレッドが終了するまで実行し続けます。

サーバクラス群は使用するネットワークプロトコルに関わらず、同じ外部 メソッドおよび属性を持ちます:

fileno( )
サーバが要求待ちを行っているソケットのファイル記述子を整数で返します。 この関数は一般的に、同じプロセス中の複数のサーバを監視できるように するために、 select.select() に渡されます。

handle_request( )
単一の要求を処理します。この関数は以下のメソッド:
get_request()、 verify_request()、および
process_request() を順番に呼び出します。
ハンドラ中でユーザによって提供された handle() が例外
を送出した場合、サーバの handle_error() メソッドが
呼び出されます。

serve_forever( )
無限個の要求を処理します。この関数は単に無限ループ内で handle_request() を呼び出します。

address_family
サーバのソケットが属しているプロトコルファミリです。 取りえる値は socket.AF_INET および socket.AF_UNIX です。

RequestHandlerClass
ユーザが提供する要求処理クラスです; 要求ごとにこのクラスのインスタンス が生成されます。

server_address
サーバが要求待ちを行うアドレスです。アドレスの形式はプロトコルファミリ によって異なります。詳細は socket モジュールを参照してください。 インターネットプロトコルでは、この値は例えば('127.0.0.1', 80)の ようにアドレスを与える文字列と整数のポート番号を含むタプルです。

socket
サーバが入力の要求待ちを行うためのソケットオブジェクトです。

サーバクラスは以下のクラス変数をサポートします:

allow_reuse_address
サーバがアドレスの再使用を許すかどうかを示す値です。この値は標準 で False で、サブクラスで再使用ポリシを変更するために 設定することができます。

request_queue_size
要求待ち行列 (queue) のサイズです。単一の要求を処理するのに長時間 かかる場合には、サーバが処理中に届いた要求は最大 request_queue_size 個まで待ち行列に置かれます。 待ち行列が一杯になると、それ以降のクライアントからの要求は ``接続拒否 (Connection denied)'' エラーになります。標準の値は 通常 5 ですが、この値はサブクラスで上書きすることができます。

socket_type
サーバが使うソケットの型です; 取りえる値は 2 つで、 socket.SOCK_STREAM と socket.SOCK_DGRAM です。

TCPServer のような基底クラスのサブクラスで上書きできる サーバメソッドは多数あります; これらのメソッドはサーバオブジェクトの 外部のユーザにとっては役にたたないものです。

finish_request( )
RequestHandlerClass をインスタンス化し、handle() メソッドを呼び出して、実際に要求を処理します。

get_request( )
ソケットから要求を受理して、 クライアントとの通信に使われる 新しい ソケットオブジェクト、およびクライアントのアドレスからなる、 2 要素のタプルを返します。

handle_error( request, client_address)
この関数は RequestHandlerClass の handle() メソッドが例外を送出した際に呼び出されます。標準の動作では 標準出力へトレースバックを出力し、後続する要求を継続して処理します。

process_request( request, client_address)
finish_request() を呼び出して、RequestHandlerClass のインスタンスを生成します。必要なら、この関数から 新たなプロセスかスレッドを生成して要求を処理することができます; その処理は ForkingMixIn または ThreadingMixIn クラスが行います。

server_activate( )
サーバのコンストラクタによって呼び出され、サーバを活動状態に します。 このメソッドは上書きできます。

server_bind( )
サーバのコンストラクタによって呼び出され、適切なアドレスにソケットを バインドします。 このメソッドは上書きできます。

verify_request( request, client_address)
ブール値を返さなければなりません; 値が真の場合には要求が処理され、 偽の場合には要求は拒否されます。 サーバへのアクセス制御を実装するためにこの関数を上書きすることが できます。標準の実装では常に真を返します。

要求処理クラスでは、新たな handle() メソッドを定義 しなくてはならず、また以下のメソッドのいずれかを上書きすることができます。 各要求ごとに新たなインスタンスが生成されます。

finish( )
handle() メソッドが呼び出された後、何らかの後始末を行うために
呼び出されます。標準の実装では何も行いません。setup() または
handle() が例外を送出した場合には、この関数は呼び出されません。

handle( )
この関数では、クライアントからの要求を実現するために必要な全ての作業を 行わなければなりません。この作業の上で、いくつかのインスタンス属性を 利用することができます; クライアントからの要求は self.request です; クライアントのアドレスは self.client_address です; そしてサーバごとの情報にアクセスする場合には、サーバインスタンスを self.server で取得できます。

self.request の型はサービスがデータグラム型かストリーム型かで 異なります。ストリーム型では、self.request はソケットオブジェクト です; データグラムサービスでは、self.request は文字列になります。 しかし、この違いは要求処理配合クラスのStreamRequestHandler や DatagramRequestHandlerを使うことで隠蔽することができます。 これらのクラスでは setup() および finish() メソッド を上書きしており、self.rfile および self.wfile 属性を 提供しています。 self.rfile および self.wfile は、要求データを取得したり クライアントにデータを返すために、それぞれ読み出し、書き込みを行うことが できます。

setup( )
handle() メソッドより前に呼び出され、何らかの必要な 初期化処理を行います。標準の実装では何も行いません。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.14 urlparse Up: 11. インターネットプロトコルとその支援 Next: 11.16 BaseHTTPServer


11.16 BaseHTTPServer -- 基本的な機能を持つ HTTP サーバ

このモジュールでは、 HTTP サーバ (Web サーバ) を実装するための 二つののクラスを定義しています。通常、このモジュールが直接使用 されることはなく、特定の機能を持つ Web サーバを構築するために 使われます。 SimpleHTTPServerおよび CGIHTTPServerモジュール を参照してください。

最初のクラス、HTTPServer は SocketServer.TCPServer のサブクラスです。HTTPServer は HTTP ソケットを生成して リクエスト待ち (listen) を行い、リクエストをハンドラに渡します。 サーバを作成して動作させるためのコードは以下のようになります:

def run(server_class=BaseHTTPServer.HTTPServer,
        handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
    server_address = ('', 8000)
    httpd = server_class(server_address, handler_class)
    httpd.serve_forever()

class HTTPServer( server_address, RequestHandlerClass)
このクラスは TCPServer 型のクラスの上に構築されており、 サーバのアドレスをインスタンス変数 server_name および server_port に記憶します。サーバはハンドラから アクセス可能で、通常 server インスタンス変数でアクセス します。

class BaseHTTPRequestHandler( request, client_address, server)
このクラスはサーバに到着したリクエストを処理します。このメソッド 自体では、実際のリクエストに応答することはできません; (GET や POST のような) 各リクエストメソッドを処理するためには サブクラス化しなければなりません。 BaseHTTPRequestHandler では、サブクラスで使うための クラスやインスタンス変数、メソッド群を数多く提供しています。

このハンドラはリクエストを解釈し、次いでリクエスト形式ごとに固有の メソッドを呼び出します。メソッド名はリクエストの名称から構成 されます。例えば、リクエストメソッド "SPAM" に対しては、 do_SPAN() メソッドが引数なしで呼び出されます。 リクエストに関連する情報は全て、ハンドラのインスタンス変数 に記憶されています。サブクラスでは __init__() メソッドを 上書きしたり拡張したりする必要はありません。

BaseHTTPRequestHandler は以下のインスタンス変数を持っています:

client_address
HTTP クライアントのアドレスを参照している、 (host, port) の形式をとるタプルが入っています。

command
HTTP 命令 (リクエスト形式) が入っています。例えば 'GET' です。

path
リクエストされたパスが入っています。

request_version
リクエストのバージョン文字列が入っています。例えば 'HTTP/1.0' です。

headers
MessageClass クラス変数で指定されたクラスのインスタンス を保持しています。このインスタンスは HTTP リクエストのヘッダを 解釈し、管理しています。

rfile
入力ストリームが入っており、そのファイルポインタはオプション 入力データ部の先頭を指しています。

wfile
クライアントに返送する応答を書き込むための出力ストリームが 入っています。このストリームに書き込む際には、HTTP プロトコル に従った形式をとらなければなりません。

BaseHTTPRequestHandler は以下のクラス変数を持っています:

server_version
サーバのソフトウェアバージョンを指定します。 この値は上書きする必要が生じるかもしれません。 書式は複数の文字列を空白で分割したもので、各文字列は ソフトウェア名[/バージョン] の形式をとります。 例えば、'BaseHTTP/0.2' です。

sys_version
Python 処理系のバージョンが、version_string メソッドや server_version クラス変数で利用可能な形式で入っています。 例えば 'Python/1.4' です。

error_message_format
クライアントに返すエラー応答を構築するための書式化文字列を指定 します。この文字列は丸括弧で囲ったキー文字列で指定する形式を 使うので、書式化の対象となる値は辞書でなければなりません。 キー code は整数で、HTTP エラーコードを特定する数値です。 message は文字列で、何が発生したかを表す (詳細な) エラーメッセージが入ります。explain はエラーコード番号 の説明です。message および explain の標準の値は response クラス変数でみつけることができます。

protocol_version
この値には応答に使われる HTTP プロトコルのバージョンを指定します。 'HTTP/1.1' に設定されると、サーバは持続的 HTTP 接続を 許可します; しかしその場合、サーバは全てのクライアントに対する 応答に、正確な値を持つ Content-Length ヘッダを (send_header() を使って) 含め なければなりません。 以前のバージョンとの互換性を保つため、標準の設定値は 'HTTP/1.0' です。

MessageClass
HTTP ヘッダを解釈するための rfc822.Message 類似のクラスを 指定します。通常この値が上書きされることはなく、標準の値 mimetools.Message になっています。

responses
この変数はエラーコードを表す整数を二つの要素をもつタプルに対応付け ます。タプルには短いメッセージと長いメッセージが入っています。 例えば、 {code: (shortmessage, longmessage)} といったようになります。shortmessage は通常、エラー応答に おける message キーの値として使われ、longmessage は explain キーの値として使われます (error_message_format クラス変数を参照してください) 。

BaseHTTPRequestHandler インスタンスは以下のメソッドを持っています:

handle( )
handle_one_request() を一度だけ (持続的接続が有効になって いる場合には複数回) 呼び出して、HTTP リクエストを処理します。 このメソッドを上書きする必要はまったくありません; そうする代わりに 適切な do_*() を実装してください。

handle_one_request( )
このメソッドはリクエストを解釈し、適切な do_*() メソッドに 転送します。このメソッドを上書きする必要はまったくありません。

send_error( code[, message])
完全なエラー応答をクライアントに送信し、ログ記録します。 code は数値型で、 HTTP エラーコードを指定します。 message はオプションで、より詳細なメッセージテキストです。 完全なヘッダのセットが送信された後、error_message_format クラス変数を使って組み立てられたテキストが送られます。

send_response( code[, message])
応答ヘッダを送信し、受理したリクエストをログ記録します。HTTP 応答行が送られた後、Server および Date ヘッダが 送られます。これら二つのヘッダはそれぞれ version_string() および date_time_string() メソッドで取り出します。

send_header( keyword, value)
出力ストリームに特定の MIME ヘッダを書き込みます。keyword はヘッダのキーワードを指定し、value にはその値を指定します。

end_headers( )
応答中の MIME ヘッダの終了を示す空行を送信します。

log_request( [code[, size]])
受理された (成功した) リクエストをログに記録します。code には この応答に関連付けられた HTTP コード番号を指定します。 応答メッセージの大きさを知ることができる場合、size パラメタ に渡すとよいでしょう。

log_error( ...)
リクエストを遂行できなかった際に、エラーをログに記録します。 標準では、メッセージを log_message() に渡します。 従って同じ引数 (format と追加の値) を取ります。

log_message( format, ...)
任意のメッセージを sys.stderr にログ記録します。 このメソッドは通常、カスタムのエラーログ記録機構を作成するために 上書きされます。format 引数は標準の printf 形式の書式化 文字列で、log_message() に渡された追加の引数は 書式化の入力として適用されます。ログ記録される全てのメッセージ には、クライアントのアドレスおよび現在の日付、時刻が先頭に 付けられます。

version_string( )
サーバソフトウェアのバージョン文字列を返します。この文字列は クラス変数 server_version および sys_version を組み合わせたものです。

date_time_string( )
メッセージヘッダ向けに書式化された、現在の日付および時刻を返します。

log_data_time_string( )
ログ記録向けに書式化された、現在の日付および時刻を返します。

address_string( )
ログ記録向けに書式化された、クライアントのアドレスを返します。 このときクライアントの IP アドレスに対する名前解決を行います。

参考資料:

CGIHTTPServerモジュール:
CGI スクリプトをサポートするように拡張されたリクエストハンドラ。.

SimpleHTTPServerモジュール:
ドキュメントルートの下にあるファイルに対する要求への応答のみに制限した基本リクエストハンドラ。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.15 SocketServer Up: 11. インターネットプロトコルとその支援 Next: 11.17 SimpleHTTPServer


11.17 SimpleHTTPServer -- 簡潔な HTTP リクエストハンドラ

SimpleHTTPServer モジュールはリクエストハンドラ (request-handler) クラスを定義しています。インタフェースは BaseHTTPServer.BaseHTTPRequestHandler と互換で、 基底ディレクトリにあるファイルだけを提供します。

SimpleHTTPServer モジュールでは以下のクラスを定義しています:

class SimpleHTTPRequestHandler( request, client_address, server)
このクラスは、現在のディレクトリ以下にあるファイルを、HTTP リクエストにおけるディレクトリ構造に直接対応付けて提供するために 利用されます。

リクエストの解釈のような、多くの作業は基底クラス BaseHTTPServer.BaseHTTPRequestHandler で行われます。 このクラスは関数 do_GET() および do_HEAD() を実装しています。

SimpleHTTPRequestHandler では以下のメンバ変数を定義しています:

server_version
この値は "SimpleHTTP/" + __version__ になります。 __version__ はこのモジュールで定義されている値です。

extensions_map
拡張子を MIME 型指定子に対応付ける辞書です。標準の型指定は空文字列で 表され、この値は text/plain と見なされます。 対応付けは大小文字の区別をするので、小文字のキーのみを入れるべきです。

SimpleHTTPRequestHandler では以下のメソッドを定義しています:

do_HEAD( )
このメソッドは 'HEAD' 型のリクエスト処理を実行します: すなわち、 GET リクエストの時に送信されるものと同じヘッダを送信します。 送信される可能性のあるヘッダについての完全な説明は do_GET() メソッドを参照してください。

do_GET( )
リクエストを現在の作業ディレクトリからの相対的なパスとして解釈することで、 リクエストをローカルシステム上のファイルと対応付けます。

リクエストがディレクトリに対応付けられた場合、 出力は 403 応答 であり、その後に説明 'Directory listing not supported' が 続きます。 要求されたファイルを開く際に何らかの IOError 例外が 送出された場合、リクエストは 404、'File not found' エラーに対応づけられます。そうでない場合、コンテントタイプが extensions_map 変数を用いて推測されます。

出力は 'Content-type:' と推測されたコンテントタイプで、その 後にヘッダの終了を示す空白行が続き、さらにその後にファイルの内容が 続きます。このファイルは常にバイナリモードで開かれます。

使用例については関数 test() の実装を参照してください。

参考資料:

BaseHTTPServerモジュール:
Web サーバおよび要求ハンドラの基底クラス実装。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.16 BaseHTTPServer Up: 11. インターネットプロトコルとその支援 Next: 11.18 CGIHTTPServer


11.18 CGIHTTPServer -- CGI 実行機能付き HTTP リクエスト処理機構

CGIHTTPServer モジュールでは、 BaseHTTPServer.BaseHTTPRequestHandler 互換のインタフェース を持ち、SimpleHTTPServer.SimpleHTTPRequestHandler の動作を 継承していますが CGI スクリプトを動作することもできる、 HTTP 要求処理機構クラスを定義しています。

注意: このモジュールは CGI スクリプトを Unix および Windows システム 上で実行させることができます; Mac OS 上では、自分と同じプロセス内で Python スクリプトを実行することしかできないはずです。

CGIHTTPServer モジュールでは、以下のクラスを定義しています:

class CGIHTTPRequestHandler( request, client_address, server)
このクラスは、現在のディレクトリかその下のディレクトリにおいて、ファイルか CGI スクリプト出力を提供するために使われます。HTTP 階層構造から ローカルなディレクトリ構造への対応付けは SimpleHTTPServer.SimpleHTTPRequestHandler と 全く同じなので注意してください。

このクラスでは、ファイルが CGI スクリプトであると推測された 場合、これをファイルして提供する代わりにスクリプトを実行します。 他の一般的なサーバ設定は特殊な拡張子を使って CGI スクリプトであることを 示すのに対し、ディレクトリベースの CGI だけが使われます。

do_GET() および do_HEAD() 関数は、HTTP 要求 が cgi_directories パス以下のどこかを指している場合、 ファイルを提供するのではなく、CGI スクリプトを実行してその出力を 提供するように変更されています。

CGIHTTPRequestHandler では以下のデータメンバを定義しています:

cgi_directories
この値は標準で ['/cgi-bin', '/htbin'] であり、CGI スクリプト を含んでいることを示すディレクトリを記述します。

CGIHTTPRequestHandler では以下のメソッドを定義しています:

do_POST( )
このメソッドは、CGI スクリプトでのみ許されている 'POST' 型の HTTP 要求に対するサービスを行います。 CGI でない url に対して POST を試みた場合、出力は Error 501, "Can only POST to CGI scripts" になります。

セキュリティ上の理由から、CGI スクリプトはユーザ nobody の UID で動作 するので注意してください。CGI スクリプトが原因で発生した問題は、 Error 403 に変換されます。

使用例については、test() 関数の実装を参照してください。

参考資料:

BaseHTTPServerモジュール:
Web サーバとリクエスト処理機構を実装した基底クラスです。.

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.17 SimpleHTTPServer Up: 11. インターネットプロトコルとその支援 Next: 11.19 Cookie


11.19 Cookie -- HTTPの状態管理

CookieモジュールはHTTPの状態管理機能であるcookieの概念を抽象 化、定義しているクラスです。単純な文字列のみで構成されるcookieのほか、 シリアル化可能なあらゆるデータ型でクッキーの値を保持するための機能も備 えています。

このモジュールは元々RFC 2109とRFC 2068に定義されている構文解析の規 則を厳密に守っていました。しかし、MSIE 3.0xがこれらのRFCで定義された文 字の規則に従っていないことが判明したため、結局、やや厳密さを欠く構文 解析規則にせざるを得ませんでした。

exception CookieError
属性やSet-Cookie:ヘッダが正しくないなど、RFC 2109に合致してい ないときに発生する例外です。

class BaseCookie( [input])
このクラスはキーが文字列、値がMorselインスタンスで構成される辞書風オブジェ クトです。値に対するキーを設定するときは、値がキーと値を含む Morselに変換されることに注意してください。

inputが与えられたときは、そのままload()メソッドへ渡され ます。

class SimpleCookie( [input])
このクラスはBaseCookieの派生クラスで、value_decode()
は与えられた値の正当性を確認するように、value_encode()は
str()で文字列化するようにそれぞれオーバライドします。

class SerialCookie( [input])
このクラスはBaseCookieの派生クラスで、value_decode() とvalue_encode()をそれぞれpickle.loads()と pickle.dumps()を実行するようにオーバーライドします。

リリース 2.3 以降で撤廃された仕様です。 このクラスを使ってはいけません! 信頼できないcookieのデータか らピクルス化された値を読み込むことは、あなたのサーバ上で任意のコードを 実行するためにピクルス化した文字列の作成が可能であることを意味し、重大 なセキュリティホールとなります。

class SmartCookie( [input])
このクラスはBaseCookieの派生クラスで、value_decode() を、値がピクルス化されたデータとして正当なときは pickle.loads()を実行、そうでないときはその値自体を返すよう にオーバーライドします。またvalue_encode()を、値が文字列以外 のときはpickle.dumps()を実行、文字列のときはその値自体を返 すようにオーバーライドします。

リリース 2.3 以降で撤廃された仕様です。 SerialCookieと同じセキュリティ上の注意が当ては まります。

関連して、さらなるセキュリティ上の注意があります。後方互換性のため、 CookieモジュールはCookieというクラス名を SmartCookieのエイリアスとしてエクスポートしています。これはほ ぼ確実に誤った措置であり、将来のバージョンでは削除することが適当と思わ れます。アプリケーションにおいてSerialCookieクラスを使うべきで ないのと同じ理由でCookieクラスを使うべきではありません。

参考資料:

RFC 2109, HTTP State Management Mechanism
このモジュールが実装 しているHTTPの状態管理に関する規格です。

  • 11.19.1 Cookieオブジェクト
  • 11.19.2 Morselオブジェクト
  • 11.19.3 例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.18 CGIHTTPServer Up: 11. インターネットプロトコルとその支援 Next: 11.19.1 Cookieオブジェクト


11.19.1 Cookieオブジェクト

value_decode( val)
文字列表現を値にデコードして返します。戻り値の型はどのようなものでも許 されます。このメソッドはBaseCookieにおいて何も実行せず、オーバー ライドされるためにだけ存在します。

value_encode( val)
エンコードした値を返します。元の値はどのような型でもかまいませんが、戻 り値は必ず文字列となります。このメソッドはBaseCookieにおいて何 も実行せず、オーバーライドされるためにだけ存在します。

通常value_encode()とvalue_decode()はともに value_decodeの処理内容から逆算した範囲に収まっていなければなりま せん。

output( [attrs[, header[, sep]]])
HTTPヘッダ形式の文字列表現を返します。attrsとheaderはそれ ぞれMorselのoutput()メソッドに送られます。sep はヘッダの連結に用いられる文字で、デフォルトは改行となっています。

js_output( [attrs])
ブラウザがJavaScriptをサポートしている場合、HTTPヘッダを送信した場合と 同様に動作する埋め込み可能なJavaScript snippetを返します。

attrsの意味はoutput()と同じです。

load( rawdata)
rawdataが文字列であれば、HTTP_COOKIEとして処理し、その値 をMorselとして追加します。辞書の場合は次と同様の処理をおこない ます。

for k, v in rawdata.items():
    cookie[k] = v

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.19 Cookie Up: 11.19 Cookie Next: 11.19.2 Morselオブジェクト


11.19.2 Morselオブジェクト

class Morsel( )
RFC 2109の属性をキーと値で保持するabstractクラスです。

Morselは辞書風のオブジェクトで、キーは次のようなRFC 2109準拠の定数と なっています。

  • expires
  • path
  • comment
  • domain
  • max-age
  • secure
  • version

キーは大文字、小文字が区別されます。

value
クッキーの値。

coded_value
実際に送信する形式にエンコードされたcookieの値。

key
cookieの名前。

set( key, value, coded_value)
メンバkey、value、coded_valueに値をセットします。

isReservedKey( K)
KがMorselのキーであるかどうかを判定します。

output( [attrs[, header]])
MoselをHTTPヘッダ形式の文字列表現にして返します。attrsが与えられ なければ、デフォルトですべての属性が含まれます。attrsを指定する ときは属性をリストとして渡さなければなりません。headerのデフォル トは"Set-Cookie:"です。

js_output( [attrs])
ブラウザがJavaScriptをサポートしている場合、HTTPヘッダを送信した場合と 同様に動作する埋め込み可能なJavaScript snippetを返します。

attrsの意味はoutput()と同じです。

OutputString( [attrs])
Moselの文字列表現をHTTPやJavaScriptで囲まずに出力します。

attrsの意味はoutput()と同じです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.19.1 Cookieオブジェクト Up: 11.19 Cookie Next: 11.19.3 例


11.19.3 例

次の例はCookieの使い方を示したものです。

>>> import Cookie
>>> C = Cookie.SimpleCookie()
>>> C = Cookie.SerialCookie()
>>> C = Cookie.SmartCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> print C # generate HTTP headers
Set-Cookie: sugar=wafer;
Set-Cookie: fig=newton;
>>> print C.output() # same thing
Set-Cookie: sugar=wafer;
Set-Cookie: fig=newton;
>>> C = Cookie.SmartCookie()
>>> C["rocky"] = "road"
>>> C["rocky"]["path"] = "/cookie"
>>> print C.output(header="Cookie:")
Cookie: rocky=road; Path=/cookie;
>>> print C.output(attrs=[], header="Cookie:")
Cookie: rocky=road;
>>> C = Cookie.SmartCookie()
>>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
>>> print C
Set-Cookie: vienna=finger;
Set-Cookie: chips=ahoy;
>>> C = Cookie.SmartCookie()
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
>>> print C
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;";
>>> C = Cookie.SmartCookie()
>>> C["oreo"] = "doublestuff"
>>> C["oreo"]["path"] = "/"
>>> print C
Set-Cookie: oreo=doublestuff; Path=/;
>>> C = Cookie.SmartCookie()
>>> C["twix"] = "none for you"
>>> C["twix"].value
'none for you'
>>> C = Cookie.SimpleCookie()
>>> C["number"] = 7 # equivalent to C["number"] = str(7)
>>> C["string"] = "seven"
>>> C["number"].value
'7'
>>> C["string"].value
'seven'
>>> print C
Set-Cookie: number=7;
Set-Cookie: string=seven;
>>> C = Cookie.SerialCookie()
>>> C["number"] = 7
>>> C["string"] = "seven"
>>> C["number"].value
7
>>> C["string"].value
'seven'
>>> print C
Set-Cookie: number="I7\012.";
Set-Cookie: string="S'seven'\012p1\012.";
>>> C = Cookie.SmartCookie()
>>> C["number"] = 7
>>> C["string"] = "seven"
>>> C["number"].value
7
>>> C["string"].value
'seven'
>>> print C
Set-Cookie: number="I7\012.";
Set-Cookie: string=seven;
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.19.2 Morselオブジェクト Up: 11.19 Cookie Next: 11.20 xmlrpclib


11.20 xmlrpclib -- XML-RPC クライアントアクセス

バージョン2.2 以降で新規追加された 仕様です。

XML-RPCはXMLを利用した遠隔手続き呼び出し(Remote Procedure Call)の一種 で、HTTPをトランスポートとして使用します。XML-RPCではクライアントはリ モートサーバ(URIで指定されたサーバ)上のメソッドをパラメータを指定して呼 び出し、構造化されたデータを取得します。このモジュールは、XML-RPCクライ アントの開発をサポートしており、Pythonオブジェクトに適合する転送用XMLの 変換の全てを行います。

class ServerProxy( uri[, transport[, encoding[, verbose[, allow_none]]]])
ServerProxyは、リモートのXML-RPCサーバとの通信を管理するオブジェ クトです。最初のパラメータはURI(Uniform Resource Indicator)で、通常は サーバのURLを指定します。2番目のパラメータにはトランスポート・ファクトリ を指定する事ができます。トランスポート・ファクトリを省略した場合、URLが https: ならモジュール内部のSafeTransportインスタンスを使用し、そ れ以外の場合にはモジュール内部のTransportインスタンスを使用しま す。オプションの 3 番目の引数はエンコード方法で、デフォルトでは UTF-8 です。オプションの 4 番目の引数はデバッグフラグです。 allow_none が真の場合、Python の定数 None は XML に翻訳されます; デフォルトの動作は None に対して TypeError を送出します。 この仕様は XML-RPC 仕様でよく用いられている拡張ですが、 全てのクライアントやサーバでサポートされているわけではありません; 詳細記述については http://ontosys.com/xml-rpc/extensions.html を参照してください。

HTTP及びHTTPS通信の両方で、http://user:pass@host:port/pathのよう なHTTP基本認証のための拡張URL構文をサポートしています。user:pass はbase64でエンコードしてHTTPの`Authorization'ヘッダとなり、XML-RPCメソッ ド呼び出し時に接続処理の一部としてリモートサーバに送信されます。リモート サーバが基本認証を要求する場合のみ、この機能を利用する必要があります。

生成されるインスタンスはリモートサーバへのプロクシオブジェクトで、RPC呼 び出しを行う為のメソッドを持ちます。リモートサーバがイントロスペクション APIをサポートしている場合は、リモートサーバのサポートするメソッドを検索 (サービス検索)やサーバのメタデータの取得なども行えます。

ServerProxyインスタンスのメソッドは引数としてPythonの基礎型とオ ブジェクトを受け取り、戻り値としてPythonの基礎型かオブジェクトを返しま す。以下の型をXMLに変換(XMLを通じてマーシャルする)する事ができます(特別 な指定がない限り、逆変換でも同じ型として変換されます):

名前 | 意味
boolean | 定数TrueとFalse
整数 | そのまま
浮動少数点 | そのまま
文字列 | そのまま
配列 | 変換可能な要素を含むPythonシーケンス。 戻り値はリスト。
構造体 | Pythonの辞書。キーは文字列のみ。全ての値は変換可能でな くてはならない。
日付 | エポックからの経過秒数。引数として指定する時は DataTimeラッパクラスのインスタンスを使用する。
バイナリ | Binaryラッパクラスのインスタンス

上記のXML-RPCでサポートする全データ型を使用することができます。メソッド 呼び出し時、XML-RPCサーバエラーが発生するとFaultインスタンス を送出し、HTTP/HTTPSトランスポート層でエラーが発生した場合には ProtocolErrorを送出します。Python 2.2以降では組み込み型のサ ブクラスを作成する事ができますが、現在のところxmlrpclibではそのようなサ ブクラスのインスタンスをマーシャルすることはできません。

文字列を渡す場合、"<"・">"・"&"などのXMLで特殊な意味を持 つ文字は自動的にエスケープされます。しかし、ASCII値0～31の制御文字などの XMLで使用することのできない文字を使用することはできず、使用するとその XML-RPCリクエストはwell-formedなXMLとはなりません。そのような文字列を渡 す必要がある場合は、後述のBinaryラッパクラスを使用してください。

Serverは、上位互換性の為にServerProxyの別名として残され ています。新しいコードではServerProxyを使用してください。

参考資料:

XML-RPC HOWTO
A good description of XML operation and client software in several languages. Contains pretty much everything an XML-RPC client developer needs to know.
XML-RPC-Hacks page
Extensions for various open-source libraries to support instrospection and multicall.

  • 11.20.1 ServerProxy オブジェクト
  • 11.20.2 Boolean オブジェクト
  • 11.20.3 DateTime オブジェクト
  • 11.20.4 Binary オブジェクト
  • 11.20.5 Fault オブジェクト
  • 11.20.6 ProtocolError オブジェクト
  • 11.20.7 補助関数
  • 11.20.8 クライアントのサンプル
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.19.3 例 Up: 11. インターネットプロトコルとその支援 Next: 11.20.1 ServerProxy オブジェクト


11.20.1 ServerProxy オブジェクト

ServerProxyインスタンスの各メソッドはそれぞれXML-RPCサーバの遠隔 手続き呼び出しに対応しており、メソッドが呼び出されると名前と引数をシグネ チャとしてRPCを実行します(同じ名前のメソッドでも、異なる引数シグネチャに よってオーバロードされます)。RPC実行後、変換された値を返すか、または FaultオブジェクトもしくはProtocolErrorオブジェクトでエ ラーを通知します。

予約メンバsystemから、XMLイントロスペクションAPIの一般的なメソ ッドを利用する事ができます。

system.listMethods( )
XML-RPCサーバがサポートするメソッド名(system以外)を格納する文字列のリス トを返します。

system.methodSignature( name)
XML-RPCサーバで実装されているメソッドの名前を指定し、利用可能なシグネチ ャの配列を取得します。シグネチャは型のリストで、先頭の型は戻り値の型を示 し、以降はパラメータの型を示します。

XML-RPCでは複数のシグネチャ(オーバロード)を使用することができるので、単 独のシグネチャではなく、シグネチャのリストを返します。

シグネチャは、メソッドが使用する最上位のパラメータにのみ適用されます。例 えばあるメソッドのパラメータが構造体の配列で戻り値が文字列の場合、シグネ チャは単に"文字列, 配列" となります。パラメータが三つの整数で戻り値が文 字列の場合は"文字列, 整数, 整数, 整数"となります。

メソッドにシグネチャが定義されていない場合、配列以外の値が返ります。 Pythonでは、この値はlist以外の値となります。

system.methodHelp( name)
XML-RPCサーバで実装されているメソッドの名前を指定し、そのメソッドを解説 する文書文字列を取得します。文書文字列を取得できない場合は空文字列を返し ます。文書文字列にはHTMLマークアップが含まれます

イントロスペクション用のメソッドは、PHP・C・Microsoft .NETのサーバなどで サポートされています。UserLand Frontierの最近のバージョンでもイントロス ペクションを部分的にサポートしています。Perl, Python, Javaでのイントロス ペクションサポートについてはXML-RPC Hacksを参照してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.20 xmlrpclib Up: 11.20 xmlrpclib Next: 11.20.2 Boolean オブジェクト


11.20.2 Boolean オブジェクト

このクラスは全てのPythonの値で初期化することができ、生成されるインスタン スは指定した値の真偽値によってのみ決まります。Booleanという名前から想像 される通りに各種のPython演算子を実装しており、__cmp__(), __repr__(), __int__(), __nonzero__()で定義さ れる演算子を使用することができます。

以下のメソッドは、主に内部的にアンマーシャル時に使用されます:

encode( out)
出力ストリームオブジェクト out に、XML-RPCエンコーディングのBoolean値を出力します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.20.1 ServerProxy オブジェクト Up: 11.20 xmlrpclib Next: 11.20.3 DateTime オブジェクト


11.20.3 DateTime オブジェクト

このクラスは、エポックからの秒数・時間タプル・ISO 8061形式の時間/日付文 字列の何れかで初期化することができます。

decode( string)
文字列をインスタンスの新しい時間を示す値として指定します。

encode( out)
出力ストリームオブジェクト out に、XML-RPCエンコーディングの DateTime値を出力します。

また、__cmp__と__repr__で定義される演算子を使用するこ とができます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.20.2 Boolean オブジェクト Up: 11.20 xmlrpclib Next: 11.20.4 Binary オブジェクト


11.20.4 Binary オブジェクト

このクラスは、文字列(NULを含む)で初期化することができます。 Binaryの内容は、属性で参照します。

data
Binaryインスタンスがカプセル化しているバイナリデータ。このデータ は8bitクリーンです。

以下のメソッドは、主に内部的にマーシャル/アンマーシャル時に使用されます:

decode( string)
指定されたbase64文字列をデコードし、インスタンスのデータとします。

encode( out)
バイナリ値をbase64でエンコードし、出力ストリームオブジェクト out に出力します。

また、__cmp__で定義される演算子を使用することができます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.20.3 DateTime オブジェクト Up: 11.20 xmlrpclib Next: 11.20.5 Fault オブジェクト


11.20.5 Fault オブジェクト

Faultオブジェクトは、XML-RPCのfaultタグの内容をカプセル化してお り、以下のメンバを持ちます:

faultCode
失敗のタイプを示す文字列。

faultString
失敗の診断メッセージを含む文字列。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.20.4 Binary オブジェクト Up: 11.20 xmlrpclib Next: 11.20.6 ProtocolError オブジェクト


11.20.6 ProtocolError オブジェクト

ProtocolErrorオブジェクトはトランスポート層で発生したエラー(URI で指定したサーバが見つからなかった場合に発生する404 `not found'など)の内 容を示し、以下のメンバを持ちます:

url
エラーの原因となったURIまたはURL。

errcode
エラーコード。

errmsg
エラーメッセージまたは診断文字列。

headers
エラーの原因となったHTTP/HTTPSリクエストを含む文字列。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.20.5 Fault オブジェクト Up: 11.20 xmlrpclib Next: 11.20.7 補助関数


11.20.7 補助関数

boolean( value)
Pythonの値を、XML-RPCのBoolean定数 TrueまたはFalseに変換し ます。

binary( data)
Python文字列をそのまま Binary オブジェクトに変換します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.20.6 ProtocolError オブジェクト Up: 11.20 xmlrpclib Next: 11.20.8 クライアントのサンプル


11.20.8 クライアントのサンプル

# simple test program (from the XML-RPC specification)

# server = ServerProxy("http://localhost:8000") # local server
server = ServerProxy("http://betty.userland.com")

print server

try:
    print server.examples.getStateName(41)
except Error, v:
    print "ERROR", v
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.20.7 補助関数 Up: 11.20 xmlrpclib Next: 11.21 SimpleXMLRPCServer


11.21 SimpleXMLRPCServer -- 基本的なXML-RPCサーバー

SimpleXMLRPCServerモジュールはPythonで記述された基本的なXML-RPC サーバーフレームワークを提供します。サーバーはスタンドアロンであるか、SimpleXMLRPCServer を使うか、CGIXMLRPCRequestHandler を使って CGI 環境に組み込まれるかの、いずれかです。

class SimpleXMLRPCServer( addr[, requestHandler[, logRequests]])
新しくサーバーインスタンスを作成します。 引数requestHandlerには、リクエストハンドラーインスタンスのファクトリーを設定します。デフォルトはSimpleXMLRPCRequestHandlerです。引数addrとrequestHandlerはSocketServer.TCPServerのコンストラクターに引き渡されます。もし引数logRequestsが真(true)であれば、(それがデフォルトですが、)リクエストはログに記録されます。偽(false)である場合にはログは記録されません。このクラスはXML-RPCプロトコルで呼ばれる関数の登録のためのメソッドを提供します。

class CGIXMLRPCRequestHandler( )
CGI 環境における XML-RPC リクエストハンドラーを、新たに作成します。 バージョン2.3 以降で新規追加された 仕様です。

class SimpleXMLRPCRequestHandler( )
新しくリクエストハンドラーインスタンスを作成します。このリクエストハンドラーはPOSTリクエストを受け持ち、SimpleXMLRPCServerのコンストラクターの引数logRequestsに従ったログ出力を行います。

  • 11.21.1 SimpleXMLRPCServer オブジェクト
  • 11.21.2 CGIXMLRPCRequestHandler
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.20.8 クライアントのサンプル Up: 11. インターネットプロトコルとその支援 Next: 11.21.1 SimpleXMLRPCServer オブジェクト


11.21.1 SimpleXMLRPCServer オブジェクト

SimpleXMLRPCServer クラスは SocketServer.TCPServer のサブクラスで、基本的なスタンドアロンの XML-RPC サーバーを作成する手段を提供します。

register_function( function[, name])
XML-RPCリクエストに応じる関数を登録します。引数nameが与えられている場合はその値が、関数functionに関連付けられます。これが与えられない場合はfunction.__name__の値が用いられます。引数nameは通常の文字列でもユニコード文字列でも良く、Pythonで識別子として正しくない文字(" . "ピリオドなど )を含んでいても。

register_instance( instance)
オブジェクトを登録し、そのオブジェクトのregister_function()で登録されていないメソッドを公開します。もし、instanceがメソッド_dispatch()を定義していれば、_dispatch()が、リクエストされたメソッド名とパラメータの組を引数として呼び出されます。そして、_dispatch()の返り値が結果としてクライアントに返されます。もし、instanceがメソッド_dispatch()を定義していなければ、リクエストされたメソッド名がそのインスタンスに定義されているメソッド名から探されます。リクエストされたメソッド名がピリオドを含む場合は、（訳注：通常のPythonでのピリオドの解釈と同様に）階層的にオブジェクトを探索します。そして、そこで見つかったオブジェクトをリクエストから渡された引数で呼び出し、その返り値をクライアントに返します。

register_introspection_functions( )
XML-RPC のイントロスペクション関数、system.listMethods、system.methodHelp、system.methodSignature を登録します。 バージョン2.3 以降で新規追加された 仕様です。

register_multicall_functions( )
XML-RPC における複数の要求を処理する関数 system.multicall を登録します。

以下に例を示します。

class MyFuncs:
    def div(self, x, y) : return div(x,y)

server = SimpleXMLRPCServer(("localhost", 8000))
server.register_function(pow)
server.register_function(lambda x,y: x+y, 'add')
server.register_introspection_functions()
server.register_instance(MyFuncs())
server.serve_forever()

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.21 SimpleXMLRPCServer Up: 11.21 SimpleXMLRPCServer Next: 11.21.2 CGIXMLRPCRequestHandler


11.21.2 CGIXMLRPCRequestHandler

CGIXMLRPCRequestHandler クラスは、Python の CGI スクリプトに送られた XML-RPC リクエストを処理するときに使用できます

register_function( function[, name])
XML-RPC リクエストに応じる関数を登録します。 引数nameが与えられている場合はその値が、関数functionに関連付けられます。これが与えられない場合はfunction.__name__の値が用いられます。引数nameは通常の文字列でもユニコード文字列でも良く、Pythonで識別子として正しくない文字(" . "ピリオドなど )を含んでもかまいません。

register_instance( instance)
オブジェクトを登録し、そのオブジェクトのregister_function()で登録されていないメソッドを公開します。もし、instanceがメソッド_dispatch()を定義していれば、_dispatch()が、リクエストされたメソッド名とパラメータの組を引数として呼び出されます。そして、_dispatch()の返り値が結果としてクライアントに返されます。もし、instanceがメソッド_dispatch()を定義していなければ、リクエストされたメソッド名がそのインスタンスに定義されているメソッド名から探されます。リクエストされたメソッド名がピリオドを含む場合は、（訳注：通常のPythonでのピリオドの解釈と同様に）階層的にオブジェクトを探索します。そして、そこで見つかったオブジェクトをリクエストから渡された引数で呼び出し、その返り値をクライアントに返します。

register_introspection_functions( )
XML-RPC のイントロスペクション関数、system.listMethods、system.methodHelp、system.methodSignature を登録します。

register_multicall_functions( )
XML-RPC における複数の要求を処理する関数 system.multicall を登録します。

handle_request( [request_text = None])
XML-RPC リクエストを処理します。request_text で渡されるのは、HTTP サーバーに提供された POST データです。何も渡されなければ標準入力からのデータが使われます。

以下に例を示します。

class MyFuncs:
    def div(self, x, y) : return div(x,y)

handler = CGIXMLRPCRequestHandler()
handler.register_function(pow)
handler.register_function(lambda x,y: x+y, 'add')
handler.register_introspection_functions()
handler.register_instance(MyFuncs())
handler.handle_request()

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.21.1 SimpleXMLRPCServer オブジェクト Up: 11.21 SimpleXMLRPCServer Next: 11.22 DocXMLRPCServer


11.22 DocXMLRPCServer -- セルフ-ドキュメンティング XML-RPC サーバ

バージョン2.3 以降で新規追加された 仕様です。

DocXMLRPCServer モジュールは SimpleXMLRPCServer クラ スを拡張し、HTTP GET リクエストに対し HTML ドキュメントを返します。サー バは DocXMLRPCServer を使ったスタンドアロン環境、 DocCGIXMLRPCRequestHandler を使った CGI 環境の2つがあります。

class DocXMLRPCServer( addr[, requestHandler[, logRequests]])

当たなサーバ・インスタンスを生成します。各パラメータの内容は SimpleXMLRPCServer.SimpleXMLRPCServer のものと同じですが、 requestHandler のデフォルトは DocXMLRPCRequestHandler に なっています。

class DocCGIXMLRPCRequestHandler( )

CGI環境に XMR-RPC リクエスト・ハンドラの新たなインスタンスを生成します。

class DocXMLRPCRequestHandler( )

リクエスト・ハンドラの新たなインスタンスを生成します。このリクエスト・ ハンドラは XML-RPC POST リクエスト、ドキュメントの GET、そして DocXMLRPCServer コンストラクタに与えられた logRequests パラメータ設定を優先するため、ロギングの変更をサポートします。

  • 11.22.1 DocXMLRPCServer オブジェクト
  • 11.22.2 DocCGIXMLRPCRequestHandler
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.21.2 CGIXMLRPCRequestHandler Up: 11. インターネットプロトコルとその支援 Next: 11.22.1 DocXMLRPCServer オブジェクト


11.22.1 DocXMLRPCServer オブジェクト

DocXMLRPCServer は SimpleXMLRPCServer.SimpleXMLRPCServer の派生クラスで、セルフ- ドキュメンティングの手段と XML-RPC サーバ機能を提供します。HTTP POST リクエストは XML-RPC メソッドの呼び出しとして扱われます。HTTP GET リク エストは pydoc スタイルの HTML ドキュメント生成のリクエストとして扱わ れます。これはサーバが自分自身のドキュメントを Web ベースで提供可能で あることを意味します。

set_server_title( server_title)

生成する HTML ドキュメントのタイトルをセットします。このタイトルは HTML の title 要素として使われます。

set_server_name( server_name)

生成する HTML ドキュメントの名前をセットします。この名前は HTML 冒頭の h1 要素に使われます。

set_server_documentation( server_documentation)

生成する HTML ドキュメントの本文をセットします。この本文は ドキュメント中の名前の下にパラグラフとして出力されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.22 DocXMLRPCServer Up: 11.22 DocXMLRPCServer Next: 11.22.2 DocCGIXMLRPCRequestHandler


11.22.2 DocCGIXMLRPCRequestHandler

DocCGIXMLRPCRequestHandler は SimpleXMLRPCServer.CGIXMLRPCRequestHandler の派生クラスで、セ ルフ- ドキュメンティングの手段と XML-RPC CGI スクリプト機能を提供しま す。HTTP POST リクエストは XML-RCP メソッドの呼び出しとして扱われます。 HTTP GET リクエストは pydoc スタイルの HTML ドキュメント生成のリクエス トとして扱われます。これはサーバが自分自身のドキュメントを Web ベース で提供可能であることを意味します。

set_server_title( server_title)

生成する HTML ドキュメントのタイトルをセットします。このタイトルは HTML の title 要素として使われます。

set_server_name( server_name)

生成する HTML ドキュメントの名前をセットします。この名前は HTML 冒頭の h1 要素に使われます。

set_server_documentation( server_documentation)

生成する HTML ドキュメントの本文をセットします。この本文は ドキュメント中の名前の下にパラグラフとして出力されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.22.1 DocXMLRPCServer オブジェクト Up: 11.22 DocXMLRPCServer Next: 11.23 asyncore


11.23 asyncore -- 非同期ソケットハンドラ

このモジュールは、非同期ソケットサービスのクライアント・サーバを開発する ための基盤として使われます。

CPUが一つしかない場合、プログラムが``二つのことを同時に''実行する方法は 二つしかありません。もっとも簡単で一般的なのはマルチスレッドを利用する方 法ですが、これとはまったく異なるテクニックで、一つのスレッドだけでマルチ スレッドと同じような効果を得られるテクニックがあります。このテクニックは I/O処理が中心である場合にのみ有効で、CPU負荷の高いプログラムでは効果が無 く、この場合にはプリエンプティブなスケジューリングが可能なスレッドが有効 でしょう。しかし、多くの場合、ネットワークサーバではCPU負荷よりはIO負荷 が問題となります。

もしOSのI/Oライブラリがシステムコール select() をサポートし ている場合（ほとんどの場合はサポートされている）、I/O処理は``バックグラ ウンド''で実行し、その間に他の処理を実行すれば、複数の通信チャネルを同時 にこなすことができます。一見、この戦略は奇妙で複雑に思えるかもしれません が、いろいろな面でマルチスレッドよりも理解しやすく、制御も容易です。 asyncoreは多くの複雑な問題を解決済みなので、洗練され、パフォー マンスにも優れたネットワークサーバとクライアントを簡単に開発することがで きます。とくに、asynchatのような、対話型のアプリケーションや プロトコルには非常に有効でしょう。

基本的には、この二つのモジュールを使う場合は一つ以上のネットワーク チャネルをasyncore.dispatcherクラス、または asynchat.async_chatのインスタンスとして作成します。作成されたチ ャネルはグローバルマップに登録され、loop()関数で参照されま す。loop()には、専用のマップを渡す事も可能です。

チャネルを生成後、loop()を呼び出すとチャネル処理が開始し、最 後のチャネル（非同期処理中にマップに追加されたチャネルを含む）が閉じるま で継続します。

loop( [timeout[, use_poll[, map]]])
ポーリングループを開始し、全てのオープン済みチャネルがクローズされた場 合のみ終了します。全ての引数はオプションです。引数timeoutは select()またはpoll()の引数timeoutとして渡され、 秒単位で指定します。デフォルト値は30秒です。引数use_pollが真のと き、select()ではなくpoll()が使われます。デフォル ト値はFalseです。引数mapには、監視するチャネルをアイテム として格納した辞書を指定します。mapが省略された場合、グローバル なマップが使用される。グローバルなマップは、チャネルクラスの __init__()メソッドが呼び出されたときに自動的に更新されま す。- この仕組みを利用するのであれば、チャネルクラスの __init__()はオーバライドするのではなく、拡張しなければなりま せん。

class dispatcher( )
dispatcherクラスは、低レベルソケットオブジェクトの薄いラッ パーです。便宜上、非同期ループから呼び出されるイベント処理メソッドを 追加していますが、これ以外の点では、non-blockingなソケットと同様で す。

dispatcherクラスには二つのクラス属性があり、パフォーマンス向上 やメモリの削減のために更新する事ができます。

ac_in_buffer_size
非同期入力バッファのサイズ(デフォルト 4096)

ac_out_buffer_size
非同期出力バッファのサイズ(デフォルト 4096)

非同期ループ内で低レベルイベントが発生した場合、発生のタイミングやコネ クションの状態から特定の高レベルイベントへと置き換えることができます。 例えばソケットを他のホストに接続する場合、最初の書き込み可能イベントが 発生すれば接続が完了した事が分かります(この時点で、ソケットへの書き込 みは成功すると考えられる)。このように判定できる高レベルイベントを以下 に示します：

イベント | 解説
handle_connect() | 最初にwriteイベントが発生した時
handle_close() | 読み込み可能なデータなしでreadイベントが発生 した時
handle_accept() | listen中のソケットでreadイベントが発生した時

非同期処理中、マップに登録されたチャネルのreadable()メソッド とwritable()メソッドが呼び出され、select()か poll()でread/writeイベントを検出するリストに登録するか否か を判定します。

このようにして、チャネルでは低レベルなソケットイベントの種類より多くの種 類のイベントを検出する事ができます。以下にあげるイベントは、サブクラスで オーバライドすることが可能です：

handle_read( )
非同期ループで、チャネルのソケットのread()メソッドの呼び出しが 成功した時に呼び出されます。

handle_write( )
非同期ループで、書き込み可能ソケットが実際に書き込み可能になった時に呼 び出される。このメソッドは、パフォーマンスの向上のためバッファリングを 行う場合などに利用できます。例：
def handle_write(self):
    sent = self.send(self.buffer)
    self.buffer = self.buffer[sent:]

handle_expt( )
out of band (OOB)データが検出された時に呼び出されます。OOBはあまりサポー トされておらず、また滅多に使われないので、handle_expt()が呼び 出されることはほとんどありません。

handle_connect( )
ソケットの接続が確立した時に呼び出されます。``welcome''バナーの送信、プ ロトコルネゴシエーションの初期化などを行います。

handle_close( )
ソケットが閉じた時に呼び出されます。

handle_error( )
捕捉されない例外が発生した時に呼び出されます。デフォルトでは、短縮したト レースバック情報が出力されます。

handle_accept( )
listen中のチャネルがリモートホストからのconnect()で接続され、 接続が確立した時に呼び出されます。

readable( )
非同期ループ中に呼び出され、readイベントの監視リストに加えるか否かを決 定します。デフォルトのメソッドではTrueを返し、readイベントの発 生を監視します。

writable( )
非同期ループ中に呼び出され、writeイベントの監視リストに加えるか否かを 決定します。デフォルトのメソッドではTrueを返し、writeイベントの 発生を監視します。

さらに、チャネルにはソケットのメソッドとほぼ同じメソッドがあり、チャネル はソケットのメソッドの多くを委譲・拡張しており、ソケットとほぼ同じメソッ ドを持っています。

create_socket( family, type)
引数も含め、通常のソケット生成と同じ。socketモジュールを参 照のこと。

connect( address)
通常のソケットオブジェクトと同様、addressには一番目の値が接続先 ホスト、2番目の値がポート番号であるタプルを指定します。

send( data)
リモート側の端点にdataを送出します。

recv( buffer_size)
リモート側の端点より、最大buffer_sizeバイトのデータを読み込みま す。長さ0の文字列が返ってきた場合、チャネルはリモートから切断された事 を示します。

listen( backlog)
ソケットへの接続を待つ。引数backlogは、キューイングできるコネク ションの最大数を指定します(1以上)。最大数はシステムに依存でします（通 常は5)

bind( address)
ソケットをaddressにバインドします。ソケットはバインド済みであっ てはなりません。(addressの形式は、アドレスファミリに依存します。 socketモジュールを参照のこと。)

accept( )
接続を受け入れます。ソケットはアドレスにバインド済みであり、 listen()で接続待ち状態でなければなりません。戻り値は (conn, address)のペアで、connはデータの送受信 を行うソケットオブジェクト、addressは接続先ソケットがバインドさ れているアドレスです。

close( )
ソケットをクローズします。以降の全ての操作は失敗します。リモート端点で は、キューに溜まったデータ以外、これ以降のデータ受信は行えません。ソケ ットはガベージコレクト時に自動的にクローズされます。

  • 11.23.1 asyncoreの例：簡単なHTTPクライアント
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.22.2 DocCGIXMLRPCRequestHandler Up: 11. インターネットプロトコルとその支援 Next: 11.23.1 asyncoreの例：簡単なHTTPクライアント


11.23.1 asyncoreの例：簡単なHTTPクライアント

基本的なサンプルとして、以下に非常に単純なHTTPクライアントを示します。こ のHTTPクライアントはdispatcherクラスでソケットを利用しています。

class http_client(asyncore.dispatcher):
    def __init__(self, host,path):
        asyncore.dispatcher.__init__(self)
        self.path = path
        self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
        self.connect( (host, 80) )
        self.buffer = 'GET %s HTTP/1.0\r\n\r\n' % self.path

    def handle_connect(self):
        pass

    def handle_read(self):
        data = self.recv(8192)
        print data

    def writable(self):
        return (len(self.buffer) > 0)

    def handle_write(self):
        sent = self.send(self.buffer)
        self.buffer = self.buffer[sent:]
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.23 asyncore Up: 11.23 asyncore Next: 11.24 asynchat


11.24 asynchat -- 非同期ソケット コマンド/レスポンス ハンドラ

asynchatを使うと、asyncoreを基盤とした非同期な サーバ・クライアントをより簡単に開発する事ができます。 asynchatでは、プロトコルの要素が任意の文字列で終了するか、ま たは可変長の文字列であるようなプロトコルを容易に制御できるようになってい ます。asynchatは、抽象クラスasync_chatを定義してお り、async_chatを継承してcollect_incoming_data()メソッド とfound_terminator()メソッドを実装すれば使うことができます。 async_chatとasyncoreは同じ非同期ループを使用してお り、asyncore.dispatcherもasynchat.async_chatも同じチャネ ルマップに登録する事ができます。通常、asyncore.dispatcherはサー バチャネルとして使用し、リクエストの受け付け時に asynchat.async_chatオブジェクトを生成します。

class async_chat( )
このクラスは、asyncore.dispatcherから継承した抽象クラスです。 使用する際にはasync_chatのサブクラスを作成し、 collect_incoming_data()とfound_terminator()を定義し なければなりません。asyncore.dispatcherのメソッドを使用する事 もできますが、メッセージ/レスポンス処理を中心に行う場合には使えないメ ソッドもあります。

asyncore.dispatcherと同様に、async_chatも select()呼出し後のソケットの状態からイベントを生成します。 ポーリングループ開始後、イベント処理フレームワークが自動的に async_chatのメソッドを呼び出しますので、プログラマが処理を記述 する必要はありません。

asyncore.dispatcherと違い、async_chatでは プロデューサの first-in-first-outキュー(fifo)を作成する事ができ ます。プロデューサはmore()メソッドを必ず持ち、このメソッドで チャネル上に送出するデータを返します。プロデューサが枯渇状態 (i.e. これ以上のデータを持たない状態)にある場合、 more()は空文字列を返します。この時、async_chatは枯渇 状態にあるプロデューサをfifoから除去し、次のプロデューサが存在すればそ のプロデューサを使用します。fifoにプロデューサが存在しない場合、 handle_write()は何もしません。リモート端点からの入力の終了や 重要な中断点を検出する場合は、set_terminator()に記述します。

async_chatのサブクラスでは、入力メソッド collect_incoming_data()とfound_terminator()を定義 し、チャネルが非同期に受信するデータを処理します。以下にメソッドの解説 を示します。

close_when_done( )
プロデューサfifoのトップにNoneをプッシュします。このプロデュー サがポップされると、チャネルがクローズします。

collect_incoming_data( data)
チャネルが受信した不定長のデータをdataに指定して呼び出されます。 このメソッドは必ずオーバライドする必要があり、デフォルトの実装では、 NotImplementedError 例外を送出します。

discard_buffers( )
非常用のメソッドで、全ての入出力バッファとプロデューサfifoを廃棄します。

found_terminator( )
入力データストリームが、set_terminatorで指定した終了条件と一 致した場合に呼び出されます。このメソッドは必ずオーバライドする必要があ り、デフォルトの実装では、NotImplementedError 例外を送出し ます。入力データを参照する必要がある場合でも引数としては与えられないた め、入力バッファをインスタンス属性として参照しなければなりません。

get_terminator( )
現在のチャネルの終了条件を返します。

handle_close( )
チャネル閉じた時に呼び出されます。デフォルトの実装では単にチャネルのソ ケットをクローズします。

handle_read( )
チャネルの非同期ループでreadイベントが発生した時に呼び出され、デフォル トの実装では、set_terminator()で設定された終了条件をチェック します。終了条件として、特定の文字列か受信文字数を指定する事ができま す。終了条件が満たされている場合、handle_readは終了条件が成立 するよりも前のデータを引数としてcollect_incoming_data()を呼び 出し、その後found_terminator()を呼び出します。

handle_write( )
アプリケーションがデータを出力する時に呼び出され、デフォルトの実装では initiate_send()を呼び出します。initiate_send()では refill_buffer()を呼び出し、チャネルのプロデューサfifoからデー タを取得します。

push( data)
dataを持つsimple_producer(後述)オブジェクトを生成し、チ ャネルのproducer_fifoにプッシュして転送します。データをチャネル に書き出すために必要なのはこれだけですが、データの暗号化やチャンク化な どを行う場合には独自のプロデューサを使用する事もできます。

push_with_producer( producer)
指定したプロデューサオブジェクトをチャネルのfifoに追加します。これより 前にpushされたプロデューサが全て枯渇した後、チャネルはこのプロデューサ からmore()メソッドでデータを取得し、リモート端点に送信しま す。

readable( )
select()ループでこのチャネルの読み込み可能チェックを行う場 合には、Trueを返します。

refill_buffer( )
fifoの先頭にあるプロデューサのmore()メソッドを呼び出し、出力 バッファを補充します。先頭のプロデューサが枯渇状態の場合にはfifoからポ ップされ、その次のプロデューサがアクティブになります。アクティブなプロ デューサがNoneになると、チャネルはクローズされます。

set_terminator( term)
チャネルで検出する終了条件を設定します。termは入力プロトコルデー タの処理方式によって以下の3つの型の何れかを指定します。

term | 説明
string | 入力ストリーム中でstringが検出された時、 found_terminator()を呼び出します。
integer | 指定された文字数が読み込まれた時、 found_terminator()を呼び出します。
None | 永久にデータを読み込みます。

終了条件が成立しても、その後に続くデータは、 found_terminator()の呼出し後に再びチャネルを読み込めば取得す る事ができます。

writable( )
Should return True as long as items remain on the producer fifo, or the channel is connected and the channel's output buffer is non-empty.

プロデューサfifoが空ではないか、チャネルが接続中で出力バッファが空でな い場合、Trueを返します。

  • 11.24.1 asynchat - 補助クラスと関数
  • 11.24.2 asynchat 使用例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.23.1 asyncoreの例：簡単なHTTPクライアント Up: 11. インターネットプロトコルとその支援 Next: 11.24.1 asynchat - 補助クラスと関数


11.24.1 asynchat - 補助クラスと関数

class simple_producer( data[, buffer_size=512])
simple_producerには、一連のデータと、オプションとしてバッファ サイズを指定する事ができます。more()が呼び出されると、その都 度buffer_size以下の長さのデータを返します。

more( )
プロデューサから取得した次のデータか、空文字列を返します。

class fifo( [list=None])
各チャネルは、アプリケーションからプッシュされ、まだチャネルに書き出さ れていないデータをfifoに保管しています。fifoでは、必 要なデータとプロデューサのリストを管理しています。引数listには、 プロデューサかチャネルに出力するデータを指定する事ができます。

is_empty( )
fifoが空のときTrueを返します。

first( )
fifoにpush()されたアイテムのうち、最も古いアイテムを返します。

push( data)
データ(文字列またはプロデューサオブジェクト)をプロデューサfifoに追加します。

pop( )
fifoが空でなければ、(True, first())を返し、ポップされたアイテム を削除します。fifoが空であれば(False, None)を返します。

asynchatは、ネットワークとテキスト分析操作で使えるユーティリテ ィ関数を提供しています。

find_prefix_at_end( haystack, needle)
文字列haystackの末尾がneedleの先頭と一致するかを調べ、一致 した文字数を返します。ex)find_prefix_at_end("abc12
r", "
r") は1を返します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.24 asynchat Up: 11.24 asynchat Next: 11.24.2 asynchat 使用例


11.24.2 asynchat 使用例

以下のサンプルは、async_chatでHTTPリクエストを読み込む処理の一部 です。Webサーバは、クライアントからの接続毎に http_request_handlerオブジェクトを作成します。最初はチャネルの終 了条件に空行を指定してHTTPヘッダの末尾までを検出し、その後ヘッダ読み込み 済みを示すフラグを立てています。

ヘッダ読み込んだ後、リクエストの種類がPOSTであればデータが入力ストリーム に流れるため、Content-Length:ヘッダの値を数値として終了条件に指定 し、適切な長さのデータをチャネルから読み込みます。

必要な入力データを全て入手したら、チャネルの終了条件にNoneを指定 して残りのデータを無視するようにしています。この後、 handle_request()が呼び出されます。

class http_request_handler(asynchat.async_chat):

    def __init__(self, conn, addr, sessions, log):
        asynchat.async_chat.__init__(self, conn=conn)
        self.addr = addr
        self.sessions = sessions
        self.ibuffer = []
        self.obuffer = ""
        self.set_terminator("\r\n\r\n")
        self.reading_headers = True
        self.handling = False
        self.cgi_data = None
        self.log = log

    def collect_incoming_data(self, data):
        """Buffer the data"""
        self.ibuffer.append(data)

    def found_terminator(self):
        if self.reading_headers:
            self.reading_headers = False
            self.parse_headers("".join(self.ibuffer))
            self.ibuffer = []
            if self.op.upper() == "POST":
                clen = self.headers.getheader("content-length")
                self.set_terminator(int(clen))
            else:
                self.handling = True
                self.set_terminator(None)
                self.handle_request()
        elif not self.handling:
            self.set_terminator(None) # browsers sometimes over-send
            self.cgi_data = parse(self.headers, "".join(self.ibuffer))
            self.handling = True
            self.ibuffer = []
            self.handle_request()

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.24.1 asynchat - 補助クラスと関数 Up: 11.24 asynchat Next: 12. インターネット上のデータの操作


12. インターネット上のデータの操作

この章ではインターネット上で一般的に利用されているデータ形式の 操作をサポートするモジュール群について記述します．

formatter | 汎用の出力書式化機構およびデバイスインタフェース。
email | 電子メールのメッセージを解析、操作および生成を 支援するパッケージ。これには MIME 文書もふくまれる。
email.Message | 電子メールのメッセージを表現する基底クラス
email.Parser | 電子メールメッセージのフラットなテキストを解析し、 メッセージオブジェクト構造体を生成する。
email.Generator | メッセージ構造からフラットな電子メールテキストを生成する。
email.Header | 非ASCII形式のヘッダを表現する
email.Charset | 文字セット
email.Encoders | 電子メールメッセージのペイロードのためのエンコーダ。
email.Encoders | 電子メールメッセージのペイロードのためのエンコーダ。
email.Utils | 電子メールパッケージの雑多なユーティリティ。
email.Iterators | メッセージオブジェクトツリーをたどる。
mailcap | mailcap ファイルの操作。
mailbox | 様々なメールボックス形式の読み出し。
mhlib | Python から MH のメイルボックスを操作します。
mimetools | MIME-スタイルのメッセージ本体を解析するためのツール。
mimetypes | ファイル名拡張子の MIME 型へのマッピング。
MimeWriter | 汎用 MIME ファイルライター。
mimify | 電子メイルメッセージの MIME 化および非 MIME 化。
multifile | MIME データのような、個別の部分を含んだファイル群に対する 読み出しのサポート。
rfc822 | RFC 2822 形式のメイルメッセージを解釈します。
base64 | MIMEのbase64形式のエンコード、デコードを行う。
binascii | バイナリと各種 ASCIIコード化バイナリ表現との間の 変換を行うツール群。
binhex | binhex4 形式ファイルのエンコードおよびデコード。
quopri | MIME quoted-printable 形式ファイルのエンコードおよびデコード。
uu | uuencode形式のエンコードとデコードを行う。
xdrlib | 外部データ表現 (XDR, External Data Representation) データのエンコードおよびデコード。
netrc | .netrc ファイル群の読み出し。
robotparser | robots.txt ファイルを読み出し、 他の URL に対する取得可能性の質問に答えるクラス。
csv | デリミタで区切られた形式のファイルに対するテーブル状データ読み書き。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 11.24.2 asynchat 使用例 Up: Python ライブラリリファレンス Next: 12.1 formatter


12.1 formatter -- 汎用の出力書式化機構

このモジュールでは、二つのインタフェース定義を提供しており、 それらの各インタフェースについて複数の実装を提供しています。 formatter インタフェースは htmllib モジュールの HTMLParser クラスで使われており、writer インタフェースは formatter インタフェースを使う上で必要です。

formatter オブジェクトはある抽象化された書式イベントの流れを writer オブジェクト上の特定の出力イベントに変換します。 formatter はいくつかのスタック構造を管理することで、writer オブジェクトの様々な属性を変更したり復元したりできるように しています; このため、writer は相対的な変更や ``元に戻す'' 操作 を処理できなくてもかまいません。writer の特定のプロパティのうち、 formatter オブジェクトを介して制御できるのは、水平方向の字揃え、 フォント、そして左マージンの字下げです。 任意の、非排他的なスタイル設定を writer に提供するための メカニズムも提供されています。さらに、段落分割のように、 可逆でない書式化イベントの機能を提供するインタフェース もあります。

writer オブジェクトはデバイスインタフェースをカプセル化します。 ファイル形式のような抽象デバイスも物理デバイス同様にサポートされて います。ここで提供されている実装内容はすべて抽象デバイス上で 動作します。デバイスインタフェースは formatter オブジェクトが 管理しているプロパティを設定し、データを出力端に書き込める ようにします。

  • 12.1.1 formatter インタフェース
  • 12.1.2 formatter 実装
  • 12.1.3 writer インタフェース
  • 12.1.4 writer 実装
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12. インターネット上のデータの操作 Up: 12. インターネット上のデータの操作 Next: 12.1.1 formatter インタフェース


12.1.1 formatter インタフェース

formatter を作成するためのインタフェースは、インスタンス化しようと する個々の formatter クラスに依存します。以下で解説するのは、 インスタンス化された全ての formatter がサポートしなければならない インタフェースです。

モジュールレベルではデータ要素を一つ定義しています:

AS_IS
後に述べる push_font() メソッドでフォント指定をする時に 使える値です。また、その他の push_property() メソッドの新しい値として使うことができます。

AS_IS の値をスタックに置くと、どのプロパティが変更されたかの 追跡を行わずに、対応する pop_property() メソッドが呼び 出されるようになります。

formatter インスタンスオブジェクトには以下の属性が定義されています:

writer
formatter とやり取りを行う writer インスタンスです。

end_paragraph( blanklines)
開かれている段落があれば閉じ、次の段落との間に少なくとも blanklines が挿入されるようにします。

add_line_break( )
強制改行挿入します。既に強制改行がある場合は挿入しません。 論理的な段落は中断しません。

add_hor_rule( *args, **kw)
出力に水平罫線を挿入します。現在の段落に何らかのデータがある 場合、強制改行が挿入されますが、論理的な段落は中断しません。 引数とキーワードは writer の send_line_break() メソッドに 渡されます。

add_flowing_data( data)
空白を折りたたんで書式化しなければならないデータを提供します。 空白の折りたたみでは、直前や直後の add_flowing_data 呼び出しに 入っている空白も考慮されます。このメソッドに渡されたデータは 出力デバイスで行末の折り返し (word-wrap) されるものと想定されて います。出力デバイスでの要求やフォント情報に応じて、writer オブジェクト でも何らかの行末折り返しが行われなければならないので注意してください。

add_literal_data( data)
変更を加えずに writer に渡さなければならないデータを提供します。 改行およびタブを含む空白を data の値にしても問題ありません。

add_label_data( format, counter)
現在の左マージン位置の左側に配置されるラベルを挿入します。この ラベルは箇条書き、数字つき箇条書きの書式を構築する際に使われます。 format の値が文字列の場合、整数の値 counter の 書式指定として解釈されます。

format の値が文字列の場合、整数の値をとる counter の 書式化指定として解釈されます。書式化された文字列はラベルの値に なります; format が文字列でない場合、ラベルの値として 直接使われます。ラベルの値は writer の send_label_data() メソッドの唯一の引数として渡されます。非文字列のラベル値をどう 解釈するかは関連付けられた writer に依存します。

書式化指定は文字列からなり、 counter の値と合わせてラベルの値を算出 するために使われます。書式文字列の各文字はラベル値にコピーされます。 このときいくつかの文字は counter 値を変換を指すものとして認識されます。 特に、文字 "1" はアラビア数字の counter 値を表し、 "A" と "a" はそれぞれ大文字および小文字の アルファベットによる counter 値を表し、"I" と "i" はそれぞれ大文字および小文字のローマ数字による counter 値を表し ます。アルファベットおよびローマ字数字への変換の際には、counter の 値はゼロ以上である必要があるので注意してください。

flush_softspace( )
以前の add_flowing_data() 呼び出しでバッファされている 出力待ちの空白を、関連付けられている writer オブジェクトに送信 します。このメソッドは writer オブジェクトに対するあらゆる直接操作 の前に呼び出さなければなりません。

push_alignment( align)
新たな字揃え (alignment) 設定を字揃えスタックの上にプッシュします。 変更を行いたくない場合には AS_IS にすることができます。 字揃え設定値が以前の設定から変更された場合、writer の new_alignment() メソッドが align の値と共に呼び出されます。

pop_alignment( )
以前の字揃え設定を復元します。

push_font( (size, italic, bold, teletype))
writer オブジェクトのフォントプロパティのうち、一部または全てを変更します。 AS_IS に設定されていないプロパティは引数で渡された値に 設定され、その他の値は現在の設定を維持します。writer の new_font() メソッドは完全に設定解決されたフォント指定で 呼び出されます。

pop_font( )
以前のフォント設定を復元します。

push_margin( margin)
左マージンのインデント数を一つ増やし、論理タグ margin を 新たなインデントに関連付けます。マージンレベルの初期値は 0 です。変更された論理タグの値は真値とならなければなりません; AS_IS 以外の偽の値はマージンの変更としては不適切です。

pop_margin( )
以前のマージン設定を復元します。

push_style( *styles)
任意のスタイル指定をスタックにプッシュします。全てのスタイルは スタイルスタックに順番にプッシュされます。AS_IS 値を含み、 スタック全体を表すタプルは writer の new_styles() メソッド に渡されます。

pop_style( [n = 1])
push_style() に渡された最新 n 個のスタイル指定を ポップします。AS_IS 値を含み、変更されたスタックを表す タプルは writer の new_styles() メソッドに渡されます。

set_spacing( spacing)
writer の割り付けスタイル (spacing style) を設定します。

assert_line_data( [flag = 1])
現在の段落にデータが予期せず追加されたことを formatter に知らせます。 このメソッドは writer を直接操作した際に使わなければなりません。 writer 操作の結果、出力の末尾が強制改行となった場合、オプションの flag 引数を偽に設定することができます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.1 formatter Up: 12.1 formatter Next: 12.1.2 formatter 実装


12.1.2 formatter 実装

このモジュールでは、formatter オブジェクトに関して二つの実装を 提供しています。ほとんどのアプリケーションではこれらのクラスを 変更したりサブクラス化することなく使うことができます。

class NullFormatter( [writer])
何も行わない formatter です。writer を省略すると、 NullWriter インスタンスが生成されます。 NullFormatter インスタンスは、writer のメソッドを 全く呼び出しません。writer へのインタフェースを実装する場合には このクラスのインタフェースを継承する必要がありますが、実装を 継承する必要は全くありません。

class AbstractFormatter( writer)
標準の formatter です。この formatter 実装は広範な writer で適用できることが実証されており、ほとんどの状況で直接使うことが できます。高機能の WWW ブラウザを実装するために使われたこともあります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.1.1 formatter インタフェース Up: 12.1 formatter Next: 12.1.3 writer インタフェース


12.1.3 writer インタフェース

writer を作成するためのインタフェースは、インスタンス化しようと する個々の writer クラスに依存します。以下で解説するのは、 インスタンス化された全ての writer がサポートしなければならない インタフェースです。 ほとんどのアプリケーションでは AbstractFormatter クラスを formatter として使うことができますが、通常 writer はアプリケーション 側で与えなければならないので注意してください。

flush( )
バッファに蓄積されている出力データやデバイス制御イベントを フラッシュします。

new_alignment( align)
字揃えのスタイルを設定します。align の値は任意のオブジェクト を取りえますが、慣習的な値は文字列または None で、 None は writer の ``好む'' 字揃えを使うことを表します。 慣習的な align の値は 'left'、 'center'、 'right'、および 'justify' です。

new_font( font)
フォントスタイルを設定します。font は、デバイスの標準のフォント が使われることを示す None か、 (size, italic, bold,teletype) の形式をとるタプルになります。size はフォントサイズを示す文字列 になります; 特定の文字列やその解釈はアプリケーション側で定義します。 italic、bold、および teletype といった値は ブール値で、それらの属性を使うかどうかを指定します。

new_margin( margin, level)
マージンレベルを整数値 level に設定し、論理タグ (logical tag) を margin に設定します。論理タグの解釈は writer の判断に 任されます; 論理タグの値に対する唯一の制限は level が 非ゼロの値の際に偽であってはならないということです。

new_spacing( spacing)
割り付けスタイル (spacing style) を spacing に設定します。 Set the spacing style to spacing.

new_styles( styles)
追加のスタイルを設定します。styles の値は任意の値からなる タプルです; AS_IS 値は無視されます。 styles タプルはアプリケーションや writer の実装上の都合に より、集合としても、スタックとしても解釈され得ます。

send_line_break( )
現在の行を改行します。

send_paragraph( blankline)
少なくとも blankline 空行分の間隔か、空行そのもので段落を 分割します。blankline の値は整数になります。 writer の実装では、改行を行う必要がある場合、このメソッドの呼び出しに 先立って send_line_break() の呼び出しを受ける必要あります; このメソッドには段落の最後の行を閉じる機能は含まれておらず、 段落間に垂直スペースを空ける役割しかありません。

send_hor_rule( *args, **kw)
水平罫線を出力デバイスに表示します。このメソッドへの引数は 全てアプリケーションおよび writer 特有のものなので、注意して 解釈する必要があります。このメソッドの実装では、すでに改行が send_line_break() によってなされているものと仮定しています。

send_flowing_data( data)
行端が折り返され、必要に応じて再割り付け解析を行った (re-flowed) 文字データを出力します。このメソッドを連続して呼び出す上では、 writer は複数の空白文字は単一のスペース文字に縮約されていると 仮定することがあります。

send_literal_data( data)
すでに表示用に書式化された文字データを出力します。 これは通常、改行文字で表された改行を保存し、新たに改行を持ち込 まないことを意味します。 send_formatted_data() インタフェースと違って、 データには改行やタブ文字が埋め込まれていてもかまいません。

send_label_data( data)
可能ならば、data を現在の左マージンの左側に設定します。 data の値には制限がありません; 文字列でない値の扱い方は アプリケーションや writer に完全に依存します。このメソッドは 行の先頭でのみ呼び出されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.1.2 formatter 実装 Up: 12.1 formatter Next: 12.1.4 writer 実装


12.1.4 writer 実装

このモジュールでは、3 種類の writer オブジェクトインタフェース実装を 提供しています。ほとんどのアプリケーションでは、 NullWriter から新しい writer クラスを導出する必要があるでしょう。

class NullWriter( )
インタフェース定義だけを提供する writer クラスです; どのメソッドも 何ら処理を行いません。このクラスは、メソッド実装をまったく継承する 必要のない writer 全ての基底クラスになります。

class AbstractWriter( )
この writer は formatter をデバッグするのに利用できますが、それ以外 に利用できるほどのものではありません。各メソッドを呼び出すと、 メソッド名と引数を標準出力に印字して呼び出されたことを示します。

class DumbWriter( [file[, maxcol = 72]])
単純な writer クラスで file に渡されたファイルオブジェクトか file が省略された場合には標準出力に出力を書き込みます。 出力は maxcol で指定されたカラム数で単純な行端折り返しが行われます。 このクラスは連続した段落を再割り付けするのに適しています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.1.3 writer インタフェース Up: 12.1 formatter Next: 12.2 email


12.2 email -- 電子メールと MIME 処理のためのパッケージ

バージョン2.2 以降で新規追加された 仕様です。

email パッケージは電子メールのメッセージを管理するライブラリです。 これには MIME やそれ以外の RFC 2822ベースのメッセージ文書もふくまれます。 このパッケージはいくつかの古い標準パッケージ、rfc822、 mimetools、multifile などにふくまれていた 機能のほとんどを持ち、くわえて標準ではなかった mimecntl などの 機能もふくんでいます。このパッケージは、とくに電子メールのメッセージを SMTP (RFC 2821) サーバに送信するために作られているというわけでは ありません。それは smtplib モジュールの機能です。 email パッケージは RFC 2822 に加えて、RFC 2045-RFC 2047 および RFC 2231 など MIME 関連の RFC をサポートしており、できるかぎり RFC に準拠することをめざしています。

email パッケージの一番の特徴は、電子メールの内部表現である オブジェクトモデル と、電子メールメッセージの解析および生成とを 分離していることです。email パッケージを使うアプリケーションは 基本的にはオブジェクトを処理することができます。メッセージに子オブジェクトを 追加したり、メッセージから子オブジェクトを削除したり、内容を完全に 並べかえたり、といったことができます。フラットなテキスト文書から オブジェクトモデルへの変換、またそこからフラットな文書へと戻す変換は それぞれ別々の解析器 (パーサ) と生成器 (ジェネレータ) が担当しています。 また、一般的な MIME オブジェクトタイプのいくつかについては手軽な サブクラスが存在しており、メッセージフィールド値を抽出したり解析したり、 RFC 準拠の日付を生成したりなどのよくおこわれるタスクについては いくつかの雑用ユーティリティもついています。

以下の節では email パッケージの機能を説明します。 説明の順序は多くのアプリケーションで一般的な使用順序にもとづいています。 まず、電子メールメッセージをファイルあるいはその他のソースから フラットなテキスト文書として読み込み、つぎにそのテキストを解析して 電子メールのオブジェクト構造を作成し、その構造を操作して、 最後にフラットなテキストに戻す、という順序になっています。

このオブジェクト構造は、まったくのゼロから作りだしたものであっても いっこうにかまいません。この場合も上と似たような作業順序になるでしょう。

またここには email パッケージが提供するすべての クラスおよびモジュールに関する説明と、email パッケージを 使っていくうえで遭遇するかもしれない例外クラス、いくつかの補助ユーティリティ、 そして少々のサンプルも含まれています。古い mimelib や前バージョンの email パッケージののユーザのために、現行バージョンとの違いと 移植についての節も設けてあります。

参考資料:

smtplibモジュール:
SMTP プロトコル クライアント.

  • 12.2.1 電子メールメッセージの表現
    • 12.2.1.1 推奨されないメソッド
  • 12.2.2 電子メールメッセージを解析(パース)する
    • 12.2.2.1 Parser クラスの API
    • 12.2.2.2 追加事項
  • 12.2.3 MIME 文書を生成する
    • 12.2.3.1 Deprecated methods
  • 12.2.4 電子メールおよび MIME オブジェクトをゼロから作成する
  • 12.2.5 国際化されたヘッダ
  • 12.2.6 文字セットの表現
  • 12.2.7 エンコーダ
  • 12.2.8 例外クラス
  • 12.2.9 雑用ユーティリティ
  • 12.2.10 イテレータ
  • 12.2.11 (Python 2.2.1 までの) email v1 とのちがい
  • 12.2.12 mimelib との違い
  • 12.2.13 使用例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.1.4 writer 実装 Up: 12. インターネット上のデータの操作 Next: 12.2.1 電子メールメッセージの表現


12.2.1 電子メールメッセージの表現

Message クラスは、 email パッケージの中心となるクラスです。 これは email オブジェクトモデルの基底クラスになっています。 Message はヘッダフィールドを検索したりメッセージ本体にアクセスするための 核となる機能を提供します。

概念的には、Message オブジェクトには ヘッダ と ペイロード が 格納されています。ヘッダは、RFC 2822 形式のフィールド名およびフィールド値が コロンで区切られたものです。コロンはフィールド名またはフィールド値の どちらにも含まれません。

ヘッダは大文字小文字を区別した形式で保存されますが、ヘッダ名が一致するかどうかの検査は 大文字小文字を区別せずにおこなうことができます。Unix-From ヘッダまたは From_ ヘッダとして知られるエンベロープヘッダがひとつ存在することもあります。 ペイロードは、単純なメッセージオブジェクトの場合は単なる文字列ですが、 MIME コンテナ文書 (multipart/* または message/rfc822 など) の場合は Message オブジェクトの リストになっています。

Message オブジェクトは、メッセージヘッダにアクセスするための マップ (辞書) 形式のインタフェイスと、ヘッダおよびペイロードの両方に アクセスするための明示的なインタフェイスを提供します。 これにはメッセージオブジェクトツリーからフラットなテキスト文書を 生成したり、一般的に使われるヘッダのパラメータにアクセスしたり、また オブジェクトツリーを再帰的にたどったりするための便利なメソッドを含みます。

Message クラスのメソッドは以下のとおりです:

class Message( )
コンストラクタは引数をとりません。

as_string( [unixfrom])
メッセージ全体をフラットな文字列として返します。 オプション unixfrom が True の場合、返される文字列には エンベロープヘッダも含まれます。unixfrom のデフォルトは False です。

このメソッドは手軽に利用する事ができますが、必ずしも期待通りにメッセージを フォーマットするとは限りません。以下の例のように Generator のインスタンスを生成して flatten() メソッドを直接呼び出せば より柔軟な処理を行う事ができます。

from cStringIO import StringIO
from email.Generator import Generator
fp = StringIO()
g = Generator(fp, mangle_from_=False, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()

__str__( )
as_string(unixfrom=True) と同じです。

is_multipart( )
メッセージのペイロードが子 Message オブジェクトからなる リストであれば True を返し、そうでなければ False を返します。 is_multipart() が False を返した場合は、ペイロードは 文字列オブジェクトである必要があります。

set_unixfrom( unixfrom)
メッセージのエンベロープヘッダを unixfrom に設定します。これは文字列である必要があります。

get_unixfrom( )
メッセージのエンベロープヘッダを返します。 エンベロープヘッダが設定されていない場合は None が返されます。

attach( payload)
与えられた payload を現在のペイロードに追加します。 この時点でのペイロードは None か、あるいは Message オブジェクトの リストである必要があります。このメソッドの実行後、ペイロードは必ず Message オブジェクトのリストになります。ペイロードに スカラーオブジェクト (文字列など) を格納したい場合は、かわりに set_payload() を使ってください。

get_payload( [i[, decode]])
現在のペイロードへの参照を返します。これは is_multipart() が True の場合 Message オブジェクトのリストになり、is_multipart() が False の場合は文字列になります。ペイロードがリストの場合、 リストを変更することはそのメッセージのペイロードを変更することになります。

オプション引数の i がある場合、 is_multipart() が True ならば get_payload() は ペイロード中で 0 から数えて i 番目の要素を返します。i が 0 より小さい場合、あるいはペイロードの個数以上の場合は IndexError が発生します。ペイロードが文字列 (つまり is_multipart() が False) にもかかわらず i が与えられたときは TypeError が発生します。

オプションの decode はそのペイロードが Content-Transfer-Encoding: ヘッダに従って デコードされるべきかどうかを指示するフラグです。 この値が True でメッセージが multipart ではない場合、 ペイロードはこのヘッダの値が "quoted-printable" または "base64" のときにかぎりデコードされます。これ以外のエンコーディングが 使われている場合、Content-Transfer-Encoding: ヘッダが ない場合、あるいは曖昧なbase64データが含まれる場合は、ペイロードはそのまま (デコードされずに) 返されます。 もしメッセージが multipart で decode フラグが True の場合は None が返されます。decode のデフォルト値は False です。

set_payload( payload[, charset])
メッセージ全体のオブジェクトのペイロードを payload に設定します。 ペイロードの形式をととのえるのは呼び出し側の責任です。 オプションの charset はメッセージのデフォルト文字セットを設定します。 詳しくは set_charset() を参照してください。

バージョン2.2.2 以降で変更された 仕様: charset 引数の追加

set_charset( charset)
ペイロードの文字セットを charset に変更します。 ここには Charsetインスタンス (email.Charset 参照)、 文字セット名をあらわす文字列、あるいは None のいずれかが指定できます。 文字列を指定した場合、これは Charset インスタンスに変換されます。 charset が None の場合、charset パラメータは Content-Type: ヘッダから除去されます。 これ以外のものを文字セットとして指定した場合、 TypeError が発生します。

ここでいうメッセージとは、charset.input_charset でエンコードされた text/* 形式のものを仮定しています。これは、もし必要とあらば プレーンテキスト形式を変換するさいに charset.output_charset の エンコードに変換されます。MIME ヘッダ (MIME-Version:, Content-Type:, Content-Transfer-Encoding:) は必要に応じて追加されます。

バージョン2.2.2 以降で新規追加された 仕様です。

get_charset( )
そのメッセージ中のペイロードの Charset インスタンスを 返します。 バージョン2.2.2 以降で新規追加された 仕様です。

以下のメソッドは、メッセージの RFC 2822 ヘッダにアクセスするための マップ (辞書) 形式のインタフェイスを実装したものです。 これらのメソッドと、通常のマップ (辞書) 型はまったく同じ意味をもつわけでは ないことに注意してください。たとえば辞書型では、同じキーが複数あることは 許されていませんが、ここでは同じメッセージヘッダが複数ある場合があります。 また、辞書型では keys() で返されるキーの順序は保証されていませんが、 Message オブジェクト内のヘッダはつねに元のメッセージ中に 現れた順序、あるいはそのあとに追加された順序で返されます。削除され、その後 ふたたび追加されたヘッダはリストの一番最後に現れます。

こういった意味のちがいは意図的なもので、最大の利便性をもつようにつくられています。

注意: どんな場合も、メッセージ中のエンベロープヘッダは このマップ形式のインタフェイスには含まれません。

__len__( )
複製されたものもふくめてヘッダ数の合計を返します。

__contains__( name)
メッセージオブジェクトが name という名前のフィールドを持っていれば true を返します。 この検査では名前の大文字小文字は区別されません。name は最後にコロンをふくんでいてはいけません。 このメソッドは以下のように in 演算子で使われます:

if 'message-id' in myMessage:
    print 'Message-ID:', myMessage['message-id']

__getitem__( name)
指定された名前のヘッダフィールドの値を返します。 name は最後にコロンをふくんでいてはいけません。 そのヘッダがない場合は None が返され、KeyError 例外は発生しません。

注意: 指定された名前のフィールドがメッセージのヘッダに 2回以上現れている場合、 どちらの値が返されるかは未定義です。ヘッダに存在するフィールドの値をすべて 取り出したい場合は get_all() メソッドを使ってください。

__setitem__( name, val)

メッセージヘッダに name という名前の val という値をもつ フィールドをあらたに追加します。このフィールドは現在メッセージに 存在するフィールドのいちばん後に追加されます。

注意: このメソッドでは、すでに同一の名前で存在するフィールドは 上書きされません。もしメッセージが名前 name をもつ フィールドをひとつしか持たないようにしたければ、最初にそれを除去してください。 たとえば:

del msg['subject']
msg['subject'] = 'PythonPythonPython!'

__delitem__( name)
メッセージのヘッダから、 name という名前をもつ フィールドをすべて除去します。たとえこの名前をもつヘッダが 存在していなくても例外は発生しません。

has_key( name)
メッセージが name という名前をもつ ヘッダフィールドを持っていれば真を、そうでなければ偽を返します。

keys( )
メッセージ中にあるすべてのヘッダのフィールド名のリストを返します。

values( )
メッセージ中にあるすべてのフィールドの値のリストを返します。

items( )
メッセージ中にあるすべてのヘッダのフィールド名とその値を 2-タプルのリストとして返します。

get( name[, failobj])
指定された名前をもつフィールドの値を返します。 これは指定された名前がないときにオプション引数の failobj (デフォルトでは None) を返すことをのぞけば、__getitem__() と同じです。

役に立つメソッドをいくつか紹介します:

get_all( name[, failobj])
name の名前をもつフィールドのすべての値からなるリストを返します。 該当する名前のヘッダがメッセージ中に含まれていない場合は failobj (デフォルトでは None) が返されます。

add_header( _name, _value, **_params)
拡張ヘッダ設定。このメソッドは __setitem__() と似ていますが、 追加のヘッダ・パラメータをキーワード引数で指定できるところが違っています。 _name に追加するヘッダフィールドを、_value にそのヘッダの 最初の値を渡します。

キーワード引数辞書 _params の各項目ごとに、 そのキーがパラメータ名として扱われ、キー名にふくまれる アンダースコアはハイフンに置換されます (なぜならハイフンは 通常の Python 識別子としては使えないからです)。ふつう、 パラメータの値が None 以外のときは、key="value" の 形で追加されます。パラメータの値が None のときはキーのみが追加されます。

例を示しましょう:

msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')

こうするとヘッダには以下のように追加されます。

Content-Disposition: attachment; filename="bud.gif"

replace_header( _name, _value)
ヘッダの置換。_name と一致するヘッダで最初に見つかったものを置き換えます。 このときヘッダの順序とフィールド名の大文字小文字は保存されます。 一致するヘッダがない場合、 KeyError が発生します。

バージョン2.2.2 以降で新規追加された 仕様です。

get_content_type( )
そのメッセージの content-type を返します。 返された文字列は強制的に小文字で maintype/subtype の形式に変換されます。 メッセージ中に Content-Type: ヘッダがない場合、デフォルトの content-type は get_default_type() が返す値によって与えられます。 RFC 2045 によればメッセージはつねにデフォルトの content-type を もっているので、get_content_type() はつねになんらかの値を返すはずです。

RFC 2045 はメッセージのデフォルト content-type を、 それが multipart/digest コンテナに現れているとき以外は text/plain に規定しています。あるメッセージが multipart/digest コンテナ中にある場合、その content-type は message/rfc822 になります。 もし Content-Type: ヘッダが適切でない content-type 書式だった場合、 RFC 2045 はそれのデフォルトを text/plain として扱うよう 定めています。

バージョン2.2.2 以降で新規追加された 仕様です。

get_content_maintype( )
そのメッセージの主 content-type を返します。 これは get_content_type() によって 返される文字列の maintype 部分です。

バージョン2.2.2 以降で新規追加された 仕様です。

get_content_subtype( )
そのメッセージの副 content-type (sub content-type、subtype) を返します。 これは get_content_type() によって 返される文字列の subtype 部分です。

バージョン2.2.2 以降で新規追加された 仕様です。

get_default_type( )
デフォルトの content-type を返します。 ほどんどのメッセージではデフォルトの content-type は text/plain ですが、メッセージが multipart/digest コンテナに 含まれているときだけ例外的に message/rfc822 になります。

バージョン2.2.2 以降で新規追加された 仕様です。

set_default_type( ctype)
デフォルトの content-type を設定します。 ctype は text/plain あるいは message/rfc822 である必要がありますが、強制ではありません。 デフォルトの content-type はヘッダの Content-Type: には 格納されません。

バージョン2.2.2 以降で新規追加された 仕様です。

get_params( [failobj[, header[, unquote]]])
メッセージの Content-Type: パラメータをリストとして返します。 返されるリストは キー/値の組からなる 2要素タプルが連なったものであり、 これらは "=" 記号で分離されています。"=" の左側は キーになり、右側は値になります。パラメータ中に "=" がなかった場合、 値の部分は空文字列になり、そうでなければその値は get_param() で 説明されている形式になります。また、オプション引数 unquote が True (デフォルト) である場合、この値は unquote されます。

オプション引数 failobj は、Content-Type: ヘッダが 存在しなかった場合に返すオブジェクトです。オプション引数 header には Content-Type: のかわりに検索すべきヘッダを指定します。

バージョン2.2.2 以降で変更された 仕様: unquote が追加されました

get_param( param[, failobj[, header[, unquote]]])
メッセージの Content-Type: ヘッダ中のパラメータ param を 文字列として返します。そのメッセージ中に Content-Type: ヘッダが 存在しなかった場合、 failobj (デフォルトは None) が返されます。

オプション引数 header が与えられた場合、 Content-Type: のかわりにそのヘッダが使用されます。

パラメータのキー比較は常に大文字小文字を区別しません。 返り値は文字列か 3 要素のタプルで、タプルになるのはパラメータが RFC 2231 エンコードされている場合です。3 要素タプルの場合、各要素の値は (CHARSET, LANGUAGE, VALUE) の形式になっています。 CHARSET と LAGUAGE は None になることがあり、その場合 VALUE は us-ascii 文字セットでエンコードされているとみなさねば ならないので注意してください。普段は LANGUAGE を無視できます。 この関数を使うアプリケーションは 3要素タプルが返された場合を想定している必要があります。 この場合、Unicode 文字列にして返すなどの処理をおこなうことが考えられます:

param = msg.get_param('foo')
if isinstance(param, tuple):
    param = unicode(param[2], param[0] or 'us-ascii')

いずれの場合もパラメータの値は (文字列であれ 3要素タプルの VALUE 項目であれ) つねに unquote されます。 ただし、unquote が False に指定されている場合は unquote されません。

バージョン2.2.2 以降で変更された 仕様: unquote 引数の追加、3要素タプルが返り値になる可能性あり

set_param( param, value[, header[, requote[, charset[, language]]]])

Content-Type: ヘッダ中のパラメータを設定します。 指定されたパラメータがヘッダ中にすでに存在する場合、その値は value に置き換えられます。Content-Type: ヘッダがまだ このメッセージ中に存在していない場合、RFC 2045 にしたがいこの値には text/plain が設定され、新しいパラメータ値が末尾に追加されます。

オプション引数 header が与えられた場合、 Content-Type: のかわりにそのヘッダが使用されます。 オプション引数 unquote が False でない限り、 この値は unquote されます (デフォルトは True)。

オプション引数 charset が与えられると、 そのパラメータは RFC 2231 に従ってエンコードされます。 オプション引数 language は RFC 2231 の言語を指定しますが、 デフォルトではこれは空文字列となります。 charset と language はどちらも文字列である必要があります。

バージョン2.2.2 以降で新規追加された 仕様です。

del_param( param[, header[, requote]])
指定されたパラメータを Content-Type: ヘッダ中から完全に とりのぞきます。ヘッダはそのパラメータと値がない状態に書き換えられます。 requote が False でない限り (デフォルトでは True です)、 すべての値は必要に応じて quote されます。オプション変数 header が与えられた場合、 Content-Type: のかわりにそのヘッダが使用されます。

バージョン2.2.2 以降で新規追加された 仕様です。

set_type( type[, header][, requote])
Content-Type: ヘッダの maintype と subtype を設定します。 type は maintype/subtype という形の文字列でなければなりません。 それ以外の場合は ValueError が発生します。

このメソッドは Content-Type: ヘッダを置き換えますが、 すべてのパラメータはそのままにします。requote が False の場合、 これはすでに存在するヘッダを quote せず放置しますが、そうでない場合は 自動的に quote します (デフォルト動作)。

オプション変数 header が与えられた場合、 Content-Type: のかわりにそのヘッダが使用されます。 Content-Type: ヘッダが設定される場合には、 MIME-Version: ヘッダも同時に付加されます。

バージョン2.2.2 以降で新規追加された 仕様です。

get_filename( [failobj])
そのメッセージ中の Content-Disposition: ヘッダにある、 filename パラメータの値を返します。目的のヘッダが欠けていたり、 filename パラメータがない場合には failobj が返されます。 返される文字列はつねに Utils.unquote() によって unquote されます。

get_boundary( [failobj])
そのメッセージ中の Content-Type: ヘッダにある、 boundary パラメータの値を返します。目的のヘッダが欠けていたり、 boundary パラメータがない場合には failobj が返されます。 返される文字列はつねに Utils.unquote() によって unquote されます。

set_boundary( boundary)
メッセージ中の Content-Type: ヘッダにある、 boundary パラメータに値を設定します。set_boundary() は 必要に応じて boundary を quote します。そのメッセージが Content-Type: ヘッダを含んでいない場合、 HeaderParseError が発生します。

注意: このメソッドを使うのは、古い Content-Type: ヘッダを 削除して新しい boundary をもったヘッダを add_header() で 足すのとは少し違います。set_boundary() は 一連のヘッダ中での Content-Type: ヘッダの位置を保つからです。 しかし、これは元の Content-Type: ヘッダ中に存在していた 連続する行の順番までは 保ちません。

get_content_charset( [failobj])
そのメッセージ中の Content-Type: ヘッダにある、 charset パラメータの値を返します。値はすべて小文字に変換されます。 メッセージ中に Content-Type: がなかったり、このヘッダ中に boundary パラメータがない場合には failobj が返されます。

注意: これは get_charset() メソッドとは異なります。 こちらのほうは文字列のかわりに、そのメッセージボディのデフォルト エンコーディングの Charset インスタンスを返します。

バージョン2.2.2 以降で新規追加された 仕様です。

get_charsets( [failobj])
メッセージ中に含まれる文字セットの名前をすべてリストにして返します。 そのメッセージが multipart である場合、返されるリストの 各要素がそれぞれの subpart のペイロードに対応します。それ以外の場合、 これは長さ 1 のリストを返します。

リスト中の各要素は文字列であり、これは対応する subpart 中の それぞれの Content-Type: ヘッダにある charset の値です。 しかし、その subpart が Content-Type: をもってないか、 charset がないか、あるいは MIME maintype が text でない いずれかの場合には、リストの要素として failobj が返されます。

walk( )
walk() メソッドは多目的のジェネレータで、 これはあるメッセージオブジェクトツリー中のすべての part および subpart を わたり歩くのに使えます。順序は深さ優先です。おそらく典型的な用法は、 walk() を for ループ中でのイテレータとして 使うことでしょう。ループを一回まわるごとに、次の subpart が返されるのです。

以下の例は、 multipart メッセージのすべての part において、 その MIME タイプを表示していくものです。

>>> for part in msg.walk():
>>>     print part.get_content_type()
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822

Message オブジェクトはオプションとして 2つのインスタンス属性を とることができます。これはある MIME メッセージからプレーンテキストを 生成するのに使うことができます。

preamble
MIME ドキュメントの形式では、 ヘッダ直後にくる空行と最初の multipart 境界をあらわす文字列のあいだに いくらかのテキスト (訳注: preamble, 序文) を埋めこむことを許しています。 このテキストは標準的な MIME の範疇からはみ出しているので、 MIME 形式を認識するメールソフトからこれらは通常まったく見えません。 しかしメッセージのテキストを生で見る場合、あるいはメッセージを MIME 対応していないメールソフトで見る場合、このテキストは 目に見えることになります。

preamble 属性は MIME ドキュメントに加える この最初の MIME 範囲外テキストを含んでいます。 Parser があるテキストをヘッダ以降に発見したが、 それはまだ最初の MIME 境界文字列が現れる前だった場合、 パーザはそのテキストをメッセージの preamble 属性に格納します。 Generator がある MIME メッセージからプレーンテキスト形式を 生成するとき、これはそのテキストをヘッダと最初の MIME 境界の間に挿入します。 詳細は email.Parser および email.Generator を 参照してください。

注意: そのメッセージに preamble がない場合、 preamble 属性には None が格納されます。

epilogue
epilogue 属性はメッセージの最後の MIME 境界文字列から メッセージ末尾までのテキストを含むもので、それ以外は preamble 属性と同じです。

注意: multipart メッセージからフラットなテキストを生成するとき、 (標準的な Generator を使ったとして) もしそのメッセージに epilogue が ない場合、最後の MIME 境界文字列のあとには改行文字が追加されません。 もしそのメッセージオブジェクトが epilogue をもっており、 それが改行文字から始まっていない場合、改行文字が MIME 境界文字列のあとに 追加されます。これはややぶかっこうに見えますが、ほとんどの場合はこれで うまくいきます。要するに、もし multipart 境界のあとに かならず改行を入れるようにしたければ、epilogue に 空文字列を入れておけばよいのです。

  • 12.2.1.1 推奨されないメソッド
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2 email Up: 12.2 email Next: 12.2.1.1 推奨されないメソッド


12.2.2 電子メールメッセージを解析(パース)する

メッセージオブジェクト構造体をつくるには 2つの方法があります。 ひとつはまったくのスクラッチから Message を生成して、これを attach() と set_payload() 呼び出しを介してつなげていく方法で、 もうひとつは電子メールメッセージのフラットなテキスト表現を 解析 (parse、パーズ) する方法です。

email パッケージでは、MIME 文書をふくむ、 ほとんどの電子メールの文書構造に対応できる標準的なパーザ (解析器) を提供しています。 このパーザに文字列あるいはファイルオブジェクトを渡せば、パーザは そのオブジェクト構造の基底となる (root の) Message インスタンスを返します。 簡単な非MIMEメッセージであれば、この基底オブジェクトのペイロードは たんにメッセージのテキストを格納する文字列になるでしょう。MIMEメッセージであれば、 基底オブジェクトはその is_multipart() メソッドに対して True を 返します。そして、その各 subpart に get_payload() メソッドおよび walk() メソッドを介してアクセスすることができます。

このパーザは、ある制限された方法で拡張できます。また、もちろん 自分でご自分のパーザを完全に無から実装することもできます。 email パッケージについているパーザと Message クラスの間に 隠された秘密の関係はなにもありませんので、ご自分で実装されたパーザも、 それが必要とするやりかたでメッセージオブジェクトツリーを作成することができます。

おもなパーザクラスは Parser です。これは電子メールの ヘッダおよびペイロードを両方解析します。multipart メッセージの 場合、これはそのコンテナのボディを再帰的に解析します。 解析には 2つのモードがサポートされており、ひとつは strict 解析で、 これはふつういかなる RFC非準拠なメッセージも受けつけません。 もうひとつは lax 解析で、こちらはよく知られた MIME の書式上の 問題に対処しようとします。

email.Parser モジュールはまた、HeaderParser と呼ばれる 2番目のクラスも提供しています。これはメッセージのヘッダのみを処理したい場合に 使うことができ、ずっと高速な処理がおこなえます。なぜならこれはメッセージ本体を 解析しようとはしないからです。かわりに、そのペイロードにはメッセージ本体の 生の文字列が格納されます。HeaderParser クラスは Parser クラスと同じ API をもっています。

  • 12.2.2.1 Parser クラスの API
  • 12.2.2.2 追加事項
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.1.1 推奨されないメソッド Up: 12.2 email Next: 12.2.2.1 Parser クラスの API


12.2.3 MIME 文書を生成する

よくある作業のひとつは、メッセージオブジェクト構造から フラットな電子メールテキストを生成することです。この作業は smtplib や nntplib モジュールを使って メッセージを送信したり、メッセージをコンソールに出力したりするときに 必要になります。あるメッセージオブジェクト構造をとってきて、 そこからフラットなテキスト文書を生成するのは Generator クラスの仕事です。

繰り返しになりますが、email.Parser モジュールと同じく、 この機能は既存の Generator だけに限られるわけではありません。 これらはご自身でゼロから作りあげることもできます。しかし、 既存のジェネレータはほとんどの電子メールを標準に沿ったやり方で 生成する方法を知っていますし、MIME メッセージも非 MIME メッセージも 扱えます。さらにこれはフラットなテキストから Parser クラスを使って メッセージ構造に変換し、それをまたフラットなテキストに戻しても、 結果が冪等 12.2 になるよう設計されています。

Generator クラスで公開されているメソッドには、以下のようなものがあります:

class Generator( outfp[, mangle_from_[, maxheaderlen]])
Generator クラスのコンストラクタは outfp と呼ばれる ストリーム形式 12.3 のオブジェクトひとつを 引数にとります。outfp は write() メソッドをサポートし、 Python 拡張 print 文の出力ファイルとして使えるようになっている必要があります。

オプション引数 mangle_from_ はフラグで、True のときは メッセージ本体に現れる行頭のすべての "From " という文字列の最初に ">" という文字を追加します。これは、このような行が Unix の mailbox 形式のエンペローブヘッダ区切り文字列として誤認識されるのを防ぐための、 移植性ある唯一の方法です (詳しくは WHY THE CONTENT-LENGTH FORMAT IS BAD (なぜ Content-Length 形式が有害か) を参照してください)。デフォルトでは mangle_from_ は True になっていますが、 Unix の mailbox 形式ファイルに出力しないのならば これは False に設定してもかまいません。

オプション引数 maxheaderlen は連続していないヘッダの最大長を 指定します。ひとつのヘッダ行が maxheaderlen (これは文字数です、 tab は空白 8文字に展開されます) よりも長い場合、ヘッダは email.Header クラスで定義されているように途中で 折り返され、間にはセミコロンが挿入されます。 もしセミコロンが見つからない場合、そのヘッダは放置されます。 ヘッダの折り返しを禁止するにはこの値にゼロを指定してください。 デフォルトは 78 文字で、RFC 2822 で推奨されている (ですが強制ではありません) 値です。

これ以外のパブリックな Generator メソッドは以下のとおりです:

flatten( msg[, unixfrom])
msg を基点とするメッセージオブジェクト構造体の 文字表現を出力します。出力先のファイルにはこの Generator インスタンスが 作成されたときに指定されたものが使われます。各 subpart は深さ優先順序 (depth-first) で出力され、得られるテキストは適切に MIME エンコードされた ものになっています。

オプション引数 unixfrom は、基点となるメッセージオブジェクトの 最初の RFC 2822 ヘッダが現れる前に、エンペローブヘッダ区切り文字列を 出力することを強制するフラグです。そのメッセージオブジェクトが エンペローブヘッダをもたない場合、標準的なエンペローブヘッダが自動的に 作成されます。デフォルトではこの値は False に設定されており、 エンペローブヘッダ区切り文字列は出力されません。

注意: 各 subpart に関しては、エンペローブヘッダは出力されません。

バージョン2.2.2 以降で新規追加された 仕様です。

clone( fp)
この Generator インスタンスの独立したクローンを生成し返します。 オプションはすべて同一になっています。

バージョン2.2.2 以降で新規追加された 仕様です。

write( s)
文字列 s を既定のファイルに出力します。 ここでいう出力先は Generator コンストラクタに 渡した outfp のことをさします。この関数はただ単に 拡張 print 文で使われる Generator インスタンスに対して ファイル操作風の API を提供するためだけのものです。

ユーザの便宜をはかるため、メソッド Message.as_string() と str(aMessage) (つまり Message.__str__() のことです) をつかえば メッセージオブジェクトを特定の書式でフォーマットされた文字列に簡単に変換することができます。 詳細は email.Message を参照してください。

email.Generator モジュールはひとつの派生クラスも提供しています。 これは DecodedGenerator と呼ばれるもので、Generator 基底クラスと 似ていますが、非text型の subpart を特定の書式でフォーマットされた 表現形式で置きかえるところが違っています。

class DecodedGenerator( outfp[, mangle_from_[, maxheaderlen[, fmt]]])

このクラスは Generator から派生したもので、 メッセージの subpart をすべて渡り歩きます。subpart の主形式が text だった場合、これはその subpart のペイロードを デコードして出力します。オプション引数 _mangle_from_ および maxheaderlen の意味は基底クラス Generator のそれと同じです。

Subpart の主形式が text ではない場合、オプション引数 fmt がそのメッセージペイロードのかわりのフォーマット文字列として使われます。 fmt は "%(keyword)s" のような形式を展開し、 以下のキーワードを認識します:

  • type - 非text型 subpart の MIME 形式

  • maintype - 非text型 subpart の MIME 主形式 (maintype)

  • subtype - 非text型 subpart の MIME 副形式 (subtype)

  • filename - 非text型 subpart のファイル名

  • description - 非text型 subpart につけられた説明文字列

  • encoding - 非text型 subpart の Content-transfer-encoding

fmt のデフォルト値は None です。 こうすると以下の形式で出力します:

[Non-text (%(type)s) part of message omitted, filename %(filename)s]

バージョン2.2.2 以降で新規追加された 仕様です。

... 結果が冪等12.2
訳注: idempotent、その操作を何回くり返しても 1回だけ行ったのと 結果が同じになること。
... ストリーム形式12.3
訳注: file-like object

  • 12.2.3.1 Deprecated methods
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.2.2 追加事項 Up: 12.2 email Next: 12.2.3.1 Deprecated methods


12.2.4 電子メールおよび MIME オブジェクトをゼロから作成する

ふつう、メッセージオブジェクト構造はファイルまたは何がしかの テキストをパーザに通すことで得られます。パーザは与えられた テキストを解析し、基底となる root のメッセージオブジェクトを返します。 しかし、完全なメッセージオブジェクト構造を何もないところから作成することも また可能です。個別の Message を手で作成することさえできます。 実際には、すでに存在するメッセージオブジェクト構造をとってきて、 そこに新たな Message オブジェクトを追加したり、あるものを 別のところへ移動させたりできます。これは MIME メッセージを 切ったりおろしたりするために非常に便利なインターフェイスを提供します。

新しいメッセージオブジェクト構造は Message インスタンスを 作成することにより作れます。ここに添付ファイルやその他適切なものを すべて手で加えてやればよいのです。MIME メッセージの場合、 email パッケージはこれらを簡単におこなえるようにするために いくつかの便利なサブクラスを提供しています。これらのサブクラスは email パッケージ内にある、 そのクラスと同じ名前をもつモジュールから import してやります。 たとえば:

import email.MIMEImage.MIMEImage

または以下のようにします:

from email.MIMEText import MIMEText

以下がそのサブクラスです:

class MIMEBase( _maintype, _subtype, **_params)
これはすべての MIME 用サブクラスの基底となるクラスです。 とくに MIMEBase のインスタンスを直接作成することは (可能ではありますが) ふつうはしないでしょう。MIMEBase は 単により特化された MIME 用サブクラスのための便宜的な基底クラスとして提供されています。

_maintype は Content-Type: の主形式 (maintype) であり (text や image など)、_subtype は Content-Type: の副形式 (subtype) です (plain や gif など)。 _params は各パラメータのキーと値を格納した辞書であり、 これは直接 Message.add_header() に渡されます。

MIMEBase クラスはつねに (_maintype、 _subtype、 および _params にもとづいた) Content-Type: ヘッダと、 MIME-Version: ヘッダ (必ず 1.0 に設定される) を追加します。

class MIMENonMultipart( )
MIMEBase のサブクラスで、これは multipart 形式でない MIME メッセージのための中間的な基底クラスです。このクラスのおもな目的は、 通常 multipart 形式のメッセージに対してのみ意味をなす attach() メソッドの使用をふせぐことです。もし attach() メソッドが 呼ばれた場合、これは MultipartConversionError 例外を発生します。

バージョン2.2.2 以降で新規追加された 仕様です。

class MIMEMultipart( [subtype[, boundary[, _subparts[, _params]]]])

MIMEBase のサブクラスで、これは multipart 形式の MIME メッセージのための中間的な基底クラスです。オプション引数 _subtype は デフォルトでは mixed になっていますが、そのメッセージの副形式 (subtype) を 指定するのに使うことができます。メッセージオブジェクトには multipart/_subtype という値をもつ Content-Type: ヘッダとともに、 MIME-Version: ヘッダが追加されるでしょう。

オプション引数 boundary は multipart の境界文字列です。 これが None の場合 (デフォルト)、境界は必要に応じて計算されます。

_subparts はそのペイロードの subpart の初期値からなるシーケンスです。 このシーケンスはリストに変換できるようになっている必要があります。 新しい subpart はつねに Message.attach() メソッドを使って そのメッセージに追加できるようになっています。

Content-Type: ヘッダに対する追加のパラメータは キーワード引数 _params を介して取得あるいは設定されます。 これはキーワード辞書になっています。

バージョン2.2.2 以降で新規追加された 仕様です。

class MIMEAudio( _audiodata[, _subtype[, _encoder[, **_params]]])

MIMEAudio クラスは MIMENonMultipart のサブクラスで、 主形式 (maintype) が audio の MIME オブジェクトを作成するのに使われます。 _audiodata は実際の音声データを格納した文字列です。 もしこのデータが標準の Python モジュール sndhdr によって 認識できるものであれば、Content-Type: ヘッダの 副形式 (subtype) は自動的に決定されます。 そうでない場合はその画像の形式 (subtype) を _subtype で 明示的に指定する必要があります。副形式が自動的に決定できず、 _subtype の指定もない場合は、TypeError が発生します。

オプション引数 _encoder は呼び出し可能なオブジェクト (関数など) で、 トランスポートのさいに画像の実際のエンコードをおこないます。 このオブジェクトは MIMEAudio インスタンスの引数をひとつだけ取ることができます。 この関数は、与えられたペイロードをエンコードされた形式に変換するのに get_payload() および set_payload() を使う必要があります。 また、これは必要に応じて Content-Transfer-Encoding: あるいは そのメッセージに適した何らかのヘッダを追加する必要があります。 デフォルトのエンコーディングは base64 です。組み込みのエンコーダの詳細については email.Encoders を参照してください。

_params は MIMEBase コンストラクタに直接渡されます。

class MIMEImage( _imagedata[, _subtype[, _encoder[, **_params]]])

MIMEImage クラスは MIMENonMultipart のサブクラスで、 主形式 (maintype) が image の MIME オブジェクトを作成するのに使われます。 _imagedata は実際の画像データを格納した文字列です。 もしこのデータが標準の Python モジュール imghdr によって 認識できるものであれば、Content-Type: ヘッダの 副形式 (subtype) は自動的に決定されます。 そうでない場合はその画像の形式 (subtype) を _subtype で 明示的に指定する必要があります。副形式が自動的に決定できず、 _subtype の指定もない場合は、TypeError が発生します。

オプション引数 _encoder は呼び出し可能なオブジェクト (関数など) で、 トランスポートのさいに画像の実際のエンコードをおこないます。 このオブジェクトは MIMEImage インスタンスの引数をひとつだけ取ることができます。 この関数は、与えられたペイロードをエンコードされた形式に変換するのに get_payload() および set_payload() を使う必要があります。 また、これは必要に応じて Content-Transfer-Encoding: あるいは そのメッセージに適した何らかのヘッダを追加する必要があります。 デフォルトのエンコーディングは base64 です。組み込みのエンコーダの詳細については email.Encoders を参照してください。

_params は MIMEBase コンストラクタに直接渡されます。

class MIMEMessage( _msg[, _subtype])
MIMEMessage クラスは MIMENonMultipart のサブクラスで、 主形式 (maintype) が message の MIME オブジェクトを作成するのに使われます。ペイロードとして使われるメッセージは _msg になります。これは Message クラス (あるいはそのサブクラス) の インスタンスでなければいけません。そうでない場合、この関数は TypeError を発生します。

オプション引数 _subtype はそのメッセージの副形式 (subtype) を設定します。 デフォルトではこれは rfc822 になっています。

class MIMEText( _text[, _subtype[, _charset[, _encoder]]])

MIMEText クラスは MIMENonMultipart のサブクラスで、 主形式 (maintype) が text の MIME オブジェクトを作成するのに使われます。ペイロードの文字列は _text になります。_subtype には副形式 (subtype) を指定し、 デフォルトは plain です。_charset はテキストの 文字セットで、MIMENonMultipart コンストラクタに引数として渡されます。 デフォルトではこの値は us-ascii になっています。 テキストデータに対しては文字コードの推定やエンコードはまったく行われません。

リリース 2.2.2 以降で撤廃された仕様です。 The _encoding 引数はもはや時代遅れとなっており、推奨されません。 現在ではエンコードは _charset 引数にもとづき暗黙のうちに行われます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.3.1 Deprecated methods Up: 12.2 email Next: 12.2.5 国際化されたヘッダ


12.2.5 国際化されたヘッダ

RFC 2822 は電子メールメッセージの形式を規定する基本規格です。 これはほとんどの電子メールが ASCII 文字のみで構成されていたころ普及した RFC 822 標準から発展したものです。RFC 2822 は電子メールが すべて 7-bit ASCII 文字のみから構成されていると仮定して作られた仕様です。

もちろん、電子メールが世界的に普及するにつれ、この仕様は国際化されてきました。 今では電子メールに言語依存の文字セットを使うことができます。 基本規格では、まだ電子メールメッセージを 7-bit ASCII 文字のみを 使って転送するよう要求していますので、多くの RFC でどうやって 非ASCII の電子メールを RFC 2822準拠な形式にエンコードするかが 記述されています。これらの RFC は以下のものを含みます: RFC 2045、 RFC 2046、 RFC 2047、 および RFC 2231。 email パッケージは、 email.Header および email.Charset モジュールでこれらの規格を サポートしています。

ご自分の電子メールヘッダ、たとえば Subject: や To: などのフィールドに非ASCII文字を入れたい場合、 Header クラスを使う必要があります。Message オブジェクトの 該当フィールドに文字列ではなく、Header インスタンスを値として 使うのです。たとえば:

>>> from email.Message import Message
>>> from email.Header import Header
>>> msg = Message()
>>> h = Header('p\xf6stal', 'iso-8859-1')
>>> msg['Subject'] = h
>>> print msg.as_string()
Subject: =?iso-8859-1?q?p=F6stal?=

Subject: フィールドに非ASCII文字をふくめていることに 注目してください。ここでは、含めたいバイト列がエンコードされている 文字セットを指定して Header インスタンスを作成することによって 実現しています。のちにこの Message インスタンスから フラットなテキストを生成するさいに、この Subject: フィールドは RFC 2047 準拠の適切な形式にエンコードされます。MIME 機能のついている メーラなら、このヘッダに埋めこまれた ISO-8859-1 文字をただしく表示するでしょう。

バージョン2.2.2 以降で新規追加された 仕様です。

以下は Header クラスの説明です:

class Header( [s[, charset[, maxlinelen[, header_name[, continuation_ws[, errors]]]]]])
別の文字セットの文字列をふくむ MIME準拠なヘッダを作成します。

オプション引数 s はヘッダの値の初期値です。 これが None の場合 (デフォルト)、ヘッダの初期値は設定されません。 この値はあとから append() メソッドを呼びだすことによって 追加することができます。s はバイト文字列か、あるいは Unicode 文字列でもかまいません。 この意味については append() の項を参照してください。

オプション引数 charset には 2つの目的があります。 ひとつは append() メソッドにおける charset 引数と 同じものです。もうひとつの目的は、これ以降 charset 引数を 省略した append() メソッド呼び出しすべてにおける、 デフォルト文字セットを決定するものです。コンストラクタに charset が与えられない場合 (デフォルト)、初期値の s および 以後の append() 呼び出しにおける文字セットとして us-ascii が使われます。

行の最大長は maxlinelen によって明示的に指定できます。 最初の行を (Subject: などの s に含まれない フィールドヘッダの責任をとるため) 短く切りとる場合、 header_name にそのフィールド名を指定してください。 maxlinelen のデフォルト値は 76 であり、header_name の デフォルト値は None です。これはその最初の行を 長い、切りとられたヘッダとして扱わないことを意味します。

オプション引数 continuation_ws は RFC 2822準拠の 折り返し用余白文字で、ふつうこれは空白か、ハードウェアタブ文字 (hard tab) である 必要があります。ここで指定された文字は複数にわたる行の行頭に挿入されます。

オプション引数 errors は、append() メソッドにそのまま渡されます。

append( s[, charset[, errors]])
この MIME ヘッダに文字列 s を追加します。

オプション引数 charset がもし与えられた場合、これは Charset インスタンス (email.Charset を参照) か、 あるいは文字セットの名前でなければなりません。この場合は Charset インスタンスに変換されます。この値が None の場合 (デフォルト)、 コンストラクタで与えられた charset が使われます。

s はバイト文字列か、Unicode 文字列です。 こればバイト文字列 (isinstance(s, str) が真) の場合、 charset はその文字列のエンコーディングであり、 これが与えられた文字セットでうまくデコードできないときは UnicodeError が発生します。

いっぽう s が Unicode 文字列の場合、charset は その文字列の文字セットを決定するためのヒントとして使われます。 この場合、RFC 2822準拠のヘッダは RFC 2047 の規則をもちいて作成され、 Unicode 文字列は以下の文字セットを (この優先順位で) 適用してエンコードされます: us-ascii、 charset で与えられたヒント、それもなければ utf-8。 最初の文字セットは UnicodeError をなるべくふせぐために使われます。

オプション引数 errors は unicode() 又は ustr.encode() の呼び出し時に使用し、デフォルト値は ``strict''です。

encode( [splitchars])
メッセージヘッダを RFC に沿ったやり方でエンコードします。 おそらく長い行は折り返され、非ASCII部分は base64 または quoted-printable エンコーディングで包含されるでしょう。 オプション引数 splitchars には長いASCII行を分割する 文字の文字列を指定し、 RFC 2822 のhighest level syntactic breaksの 大まかなサポートの為に使用します。この引数は RFC 2047 でエンコード された行には影響しません。

Header クラスは、標準の演算子や組み込み関数を サポートするためのメソッドもいくつか提供しています。

__str__( )
Header.encode() と同じです。 str(aHeader) などとすると有用でしょう。

__unicode__( )
組み込みの unicode() 関数の補助です。 ヘッダを Unicode 文字列として返します。

__eq__( other)
このメソッドは、ふたつの Header インスタンスどうしが等しいかどうか 判定するのに使えます。

__ne__( other)
このメソッドは、ふたつの Header インスタンスどうしが異なっているかどうかを 判定するのに使えます。

さらに、email.Header モジュールは以下のような 便宜的な関数も提供しています。

decode_header( header)
文字セットを変換することなしに、メッセージのヘッダをデコードします。 ヘッダの値は header に渡します。

この関数はヘッダのそれぞれのデコードされた部分ごとに、 (decoded_string, charset) という形式の 2要素タプルからなる リストを返します。charset はヘッダのエンコードされていない部分に 対しては None を、それ以外の場合はエンコードされた文字列が 指定している文字セットの名前を小文字からなる文字列で返します。

以下はこの使用例です:

>>> from email.Header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[('p\\xf6stal', 'iso-8859-1')]

make_header( decoded_seq[, maxlinelen[, header_name[, continuation_ws]]])
decode_header() によって返される 2要素タプルのリストから Header インスタンスを作成します。

decode_header() はヘッダの値をとってきて、 (decoded_string, charset) という形式の 2要素タプルからなる リストを返します。ここで decoded_string はデコードされた文字列、 charset はその文字セットです。

この関数はこれらのリストの項目から、Header インスタンスを返します。 オプション引数 maxlinelen、header_name および continuation_ws は Header コンストラクタに与えるものと同じです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.4 電子メールおよび MIME オブジェクトをゼロから作成する Up: 12.2 email Next: 12.2.6 文字セットの表現


12.2.6 文字セットの表現

このモジュールは文字セットを表現する Charset クラスと 電子メールメッセージにふくまれる文字セット間の変換、および 文字セットのレジストリとこのレジストリを操作するための いくつかの便宜的なメソッドを提供します。Charset インスタンスは email パッケージ中にあるほかのいくつかのモジュールで使用されます。

バージョン2.2.2 以降で新規追加された 仕様です。

class Charset( [input_charset])
文字セットを email のプロパティに写像する。 Map character sets to their email properties.

このクラスはある特定の文字セットに対し、電子メールに課される制約の情報を提供します。 また、与えられた適用可能な codec をつかって、文字セット間の変換をおこなう 便宜的なルーチンも提供します。またこれは、ある文字セットが与えられたときに、 その文字セットを電子メールメッセージのなかで どうやって RFC に準拠したやり方で使用するかに関する、 できうるかぎりの情報も提供します。

文字セットによっては、それらの文字を電子メールのヘッダあるいはメッセージ本体で使う場合は quoted-printable 形式あるいは base64形式でエンコードする必要があります。 またある文字セットはむきだしのまま変換する必要があり、電子メールの中では 使用できません。

以下ではオプション引数 input_charset について説明します。 この値はつねに小文字に強制的に変換されます。 そして文字セットの別名が正規化されたあと、この値は文字セットの レジストリ内を検索し、ヘッダのエンコーディングと メッセージ本体のエンコーディング、および出力時の変換に使われる codec をみつけるのに使われます。 たとえば input_charset が iso-8859-1 の場合、ヘッダおよびメッセージ本体は quoted-printable でエンコードされ、出力時の変換用 codec は必要ありません。 もし input_charset が euc-jp ならば、ヘッダは base64 でエンコードされ、 メッセージ本体はエンコードされませんが、出力されるテキストは euc-jp 文字セットから iso-2022-jp 文字セットに変換されます。

Charset インスタンスは以下のようなデータ属性をもっています:

input_charset
最初に指定される文字セットです。 一般に通用している別名は、正式な 電子メール用の名前に変換されます (たとえば、latin_1 は iso-8859-1 に変換されます)。 デフォルトは 7-bit の us-ascii です。

header_encoding
この文字セットが電子メールヘッダに使われる前にエンコードされる必要がある場合、 この属性は Charset.QP (quoted-printable エンコーディング)、 Charset.BASE64 (base64 エンコーディング)、あるいは 最短の QP または BASE64 エンコーディングである Charset.SHORTEST に 設定されます。そうでない場合、この値は None になります。

body_encoding
header_encoding と同じですが、この値はメッセージ本体のための エンコーディングを記述します。これはヘッダ用のエンコーディングとは 違うかもしれません。body_encoding では、Charset.SHORTEST を 使うことはできません。

output_charset
文字セットによっては、電子メールのヘッダあるいはメッセージ本体に 使う前にそれを変換する必要があります。もし input_charset が それらの文字セットのどれかをさしていたら、この output_charset 属性は それが出力時に変換される文字セットの名前をあらわしています。 それ以外の場合、この値は None になります。

input_codec
input_charset を Unicode に変換するための Python 用 codec 名です。 変換用の codec が必要ないときは、この値は None になります。

output_codec
Unicode を output_charset に変換するための Python 用 codec 名です。 変換用の codec が必要ないときは、この値は None になります。 この属性は input_codec と同じ値をもつことになるでしょう。

Charset インスタンスは、以下のメソッドも持っています:

get_body_encoding( )
メッセージ本体のエンコードに使われる content-transfer-encoding の値を返します。

この値は使用しているエンコーディングの文字列 "quoted-printable" または "base64" か、 あるいは関数のどちらかです。後者の場合、これはエンコードされる Message オブジェクトを 単一の引数として取るような関数である必要があります。この関数は変換後 Content-Transfer-Encoding: ヘッダ自体を、なんであれ適切な値に設定する必要があります。

このメソッドは body_encoding が QP の場合 "quoted-printable" を返し、body_encoding が BASE64 の場合 "base64" を返します。それ以外の場合は文字列 "7bit" を返します。

convert( s)
文字列 s を input_codec から output_codec に変換します。

to_splittable( s)
おそらくマルチバイトの文字列を、安全に split できる形式に変換します。 s には split する文字列を渡します。

これは input_codec を使って文字列を Unicode にすることで、 文字と文字の境界で (たとえそれがマルチバイト文字であっても) 安全に split できるようにします。

input_charset の文字列 s をどうやって Unicode に変換すればいいかが 不明な場合、このメソッドは与えられた文字列そのものを返します。

Unicode に変換できなかった文字は、Unicode 置換文字 (Unicode replacement character) "U+FFFD" に置換されます。

from_splittable( ustr[, to_output])
split できる文字列をエンコードされた文字列に変換しなおします。 ustr は ``逆split'' するための Unicode 文字列です。

このメソッドでは、文字列を Unicode からべつのエンコード形式に変換するために 適切な codec を使用します。与えられた文字列が Unicode ではなかった場合、 あるいはそれをどうやって Unicode から変換するか不明だった場合は、 与えられた文字列そのものが返されます。

Unicode から正しく変換できなかった文字については、 適当な文字 (通常は "?") に置き換えられます。

to_output が True の場合 (デフォルト)、 このメソッドは output_codec をエンコードの形式として 使用します。to_output が False の場合、これは input_codec を使用します。

get_output_charset( )
出力用の文字セットを返します。

これは output_charset 属性が None でなければその値になります。 それ以外の場合、この値は input_charset と同じです。

encoded_header_len( )
エンコードされたヘッダ文字列の長さを返します。 これは quoted-printable エンコーディングあるいは base64 エンコーディングに対しても 正しく計算されます。

header_encode( s[, convert])
文字列 s をヘッダ用にエンコードします。

convert が True の場合、 文字列は入力用文字セットから出力用文字セットに自動的に変換されます。 これは行の長さ問題のあるマルチバイトの文字セットに対しては役に立ちません (マルチバイト文字はバイト境界ではなく、文字ごとの境界で split する必要があります)。 これらの問題を扱うには、高水準のクラスである Header クラスを 使ってください (email.Header を参照)。 convert の値はデフォルトでは False です。

エンコーディングの形式 (base64 または quoted-printable) は、 header_encoding 属性に基づきます。

body_encode( s[, convert])
文字列 s をメッセージ本体用にエンコードします。

convert が True の場合 (デフォルト)、 文字列は入力用文字セットから出力用文字セットに自動的に変換されます。 header_encode() とは異なり、メッセージ本体にはふつう バイト境界の問題やマルチバイト文字セットの問題がないので、 これはきわめて安全におこなえます。

エンコーディングの形式 (base64 または quoted-printable) は、 body_encoding 属性に基づきます。

Charset クラスには、 標準的な演算と組み込み関数をサポートする いくつかのメソッドがあります。

__str__( )
input_charset を小文字に変換された文字列型として返します。 __repr__() は、__str__() の別名となっています。

__eq__( other)
このメソッドは、2つの Charset インスタンスが同じかどうかをチェックするのに使います。

__ne__( other)
このメソッドは、2つの Charset インスタンスが異なるかどうかをチェックするのに使います。

また、email.Charset モジュールには、 グローバルな文字セット、文字セットの別名(エイリアス) および codec 用のレジストリに 新しいエントリを追加する以下の関数もふくまれています:

add_charset( charset[, header_enc[, body_enc[, output_charset]]])
文字の属性をグローバルなレジストリに追加します。

charset は入力用の文字セットで、その文字セットの正式名称を指定する必要があります。

オプション引数 header_enc および body_enc は quoted-printable エンコーディングをあらわす Charset.QP か、 base64 エンコーディングをあらわす Charset.BASE64、 最短の quoted-printable または base64 エンコーディングをあらわす Charset.SHORTEST、あるいはエンコーディングなしの None の どれかになります。SHORTEST が使えるのは header_enc だけです。 デフォルトの値はエンコーディングなしの None になっています。

オプション引数 output_charset には出力用の文字セットが入ります。 Charset.convert() が呼ばれたときの変換は まず入力用の文字セットを Unicode に変換し、それから出力用の文字セットに 変換されます。デフォルトでは、出力は入力と同じ文字セットになっています。

input_charset および output_charset は このモジュール中の文字セット-codec 対応表にある Unicode codec エントリである 必要があります。モジュールがまだ対応していない codec を追加するには、 add_codec() を使ってください。より詳しい情報については codecs モジュールの文書を参照してください。

グローバルな文字セット用のレジストリは、モジュールの global 辞書 CHARSETS 内に保持されています。

add_alias( alias, canonical)
文字セットの別名 (エイリアス) を追加します。 alias はその別名で、たとえば latin-1 のように指定します。 canonical はその文字セットの正式名称で、たとえば iso-8859-1 のように指定します。

文字セットのグローバルな別名用レジストリは、モジュールの global 辞書 ALIASES 内に保持されています。

add_codec( charset, codecname)
与えられた文字セットの文字と Unicode との変換をおこなう codec を追加します。

charset はある文字セットの正式名称で、 codecname は Python 用 codec の名前です。 これは組み込み関数 unicode() の第2引数か、 あるいは Unicode 文字列型の encode() メソッドに 適した形式になっていなければなりません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.5 国際化されたヘッダ Up: 12.2 email Next: 12.2.7 エンコーダ


12.2.7 エンコーダ

何もないところから Message を作成するときしばしば必要になるのが、 ペイロードをメールサーバに通すためにエンコードすることです。 これはとくにバイナリデータを含んだ image/* や text/* タイプのメッセージで必要です。

email パッケージでは、Encoders モジュールにおいて いくかの便宜的なエンコーディングをサポートしています。実際にはこれらの エンコーダは MIMEImage および MIMEText クラスの コンストラクタでデフォルトエンコーダとして使われています。 すべてのエンコーディング関数は、エンコードするメッセージオブジェクト ひとつだけを引数にとります。これらはふつうペイロードを取りだし、 それをエンコードして、ペイロードをエンコードされたものにセットしなおします。 これらはまた Content-Transfer-Encoding: ヘッダを適切な値に 設定します。

提供されているエンコーディング関数は以下のとおりです:

encode_quopri( msg)
ペイロードを quoted-printable 形式にエンコードし、 Content-Transfer-Encoding: ヘッダを quoted-printable 12.4 に設定します。 これはそのペイロードのほとんどが通常の印刷可能な文字からなっているが、 印刷不可能な文字がすこしだけあるときのエンコード方法として適しています。

encode_base64( msg)
ペイロードを base64 形式でエンコードし、 Content-Transfer-Encoding: ヘッダを base64 に変更します。これはペイロード中の データのほとんどが印刷不可能な文字である場合に適しています。 quoted-printable 形式よりも結果としてはコンパクトなサイズになるからです。 base64 形式の欠点は、これが人間にはまったく読めないテキストに なってしまうことです。

encode_7or8bit( msg)
これは実際にはペイロードを変更はしませんが、ペイロードの形式に応じて Content-Transfer-Encoding: ヘッダを 7bit あるいは 8bit に適した形に設定します。

encode_noop( msg)
これは何もしないエンコーダです。 Content-Transfer-Encoding: ヘッダを設定さえしません。

...quoted-printable12.4
注意: encode_quopri() を 使ってエンコードすると、データ中のタブ文字や空白文字も エンコードされます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.6 文字セットの表現 Up: 12.2 email Next: 12.2.8 例外クラス


12.2.8 例外クラス

何もないところから Message を作成するときしばしば必要になるのが、 ペイロードをメールサーバに通すためにエンコードすることです。 これはとくにバイナリデータを含んだ image/* や text/* タイプのメッセージで必要です。

email パッケージでは、Encoders モジュールにおいて いくかの便宜的なエンコーディングをサポートしています。実際にはこれらの エンコーダは MIMEImage および MIMEText クラスの コンストラクタでデフォルトエンコーダとして使われています。 すべてのエンコーディング関数は、エンコードするメッセージオブジェクト ひとつだけを引数にとります。これらはふつうペイロードを取りだし、 それをエンコードして、ペイロードをエンコードされたものにセットしなおします。 これらはまた Content-Transfer-Encoding: ヘッダを適切な値に 設定します。

提供されているエンコーディング関数は以下のとおりです:

encode_quopri( msg)
ペイロードを quoted-printable 形式にエンコードし、 Content-Transfer-Encoding: ヘッダを quoted-printable 12.5 に設定します。 これはそのペイロードのほとんどが通常の印刷可能な文字からなっているが、 印刷不可能な文字がすこしだけあるときのエンコード方法として適しています。

encode_base64( msg)
ペイロードを base64 形式でエンコードし、 Content-Transfer-Encoding: ヘッダを base64 に変更します。これはペイロード中の データのほとんどが印刷不可能な文字である場合に適しています。 quoted-printable 形式よりも結果としてはコンパクトなサイズになるからです。 base64 形式の欠点は、これが人間にはまったく読めないテキストに なってしまうことです。

encode_7or8bit( msg)
これは実際にはペイロードを変更はしませんが、ペイロードの形式に応じて Content-Transfer-Encoding: ヘッダを 7bit あるいは 8bit に適した形に設定します。

encode_noop( msg)
これは何もしないエンコーダです。 Content-Transfer-Encoding: ヘッダを設定さえしません。

...quoted-printable12.5
注意: encode_quopri() を 使ってエンコードすると、データ中のタブ文字や空白文字も エンコードされます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.7 エンコーダ Up: 12.2 email Next: 12.2.9 雑用ユーティリティ


12.2.9 雑用ユーティリティ

email ではいくつかの便利なユーティリティを提供しています。

quote( str)
文字列 str 内のバックスラッシュを バックスラッシュ2つ に置換した 新しい文字列を返します。また、ダブルクォートは バックスラッシュ + ダブルクォートに置換されます。

unquote( str)
文字列 str を 逆クォートした新しい文字列を返します。 もし str の先頭あるいは末尾がダブルクォートだった場合、 これらは単に切りおとされます。同様にもし str の先頭あるいは末尾が 角ブラケット (<、>) だった場合も切りおとされます。

parseaddr( address)
アドレスをパーズします。To: や Cc: のような アドレスをふくんだフィールドの値を与えると、構成部分の 実名 と 電子メールアドレス を取り出します。 パーズに成功した場合、これらの情報をタプル (realname, email_address) にして返します。 失敗した場合は 2要素のタプル ('', '') を返します。

formataddr( pair)
parseaddr() の逆で、実名と電子メールアドレスからなる 2要素のタプル (realname, email_address) を引数にとり、 To: あるいは Cc: ヘッダに適した形式の文字列を 返します。タプル pair の第1要素が偽である場合、第2要素の値を そのまま返します。

getaddresses( fieldvalues)
このメソッドは 2要素タプルのリストを parseaddr() と同じ形式で返します。 fieldvalues はたとえば Message.get_all() が返すような、 ヘッダのフィールド値からなるシーケンスです。以下はある電子メールメッセージから すべての受け取り人を得る一例です:

from email.Utils import getaddresses

tos = msg.get_all('to', [])
ccs = msg.get_all('cc', [])
resent_tos = msg.get_all('resent-to', [])
resent_ccs = msg.get_all('resent-cc', [])
all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)

parsedate( date)
RFC 2822 に記された規則にもとづいて日付を解析します。 しかし、メイラーによってはここで指定された規則に従っていないものがあり、 そのような場合 parsedate() はなるべく正しい日付を推測しようとします。 date は RFC 2822 形式の日付を保持している文字列で、 "Mon, 20 Nov 1995 19:12:08 -0500" のような形をしています。 日付の解析に成功した場合、parsedate() は 関数 time.mktime() に直接渡せる形式の 9要素からなるタプルを返し、失敗した場合は None を返します。 返されるタプルの 6、7、8番目のフィールドは有効ではないので注意してください。

parsedate_tz( date)
parsedate() と同様の機能を提供しますが、 None または 10要素のタプルを返すところが違います。 最初の 9つの要素は time.mktime() に直接渡せる形式のものであり、 最後の 10番目の要素は、その日付の時間帯の UTC (グリニッジ標準時の公式な呼び名です) に対するオフセットです 12.6。 入力された文字列に時間帯が指定されていなかった場合、10番目の要素には None が入ります。 タプルの 6、7、8番目のフィールドは有効ではないので注意してください。

mktime_tz( tuple)
parsedate_tz() が返す 10要素のタプルを UTC の タイムスタンプに変換します。与えられた時間帯が None である場合、 時間帯として現地時間 (localtime) が仮定されます。 マイナーな欠点: mktime_tz() はまず tuple の最初の 8要素を localtime として変換し、つぎに時間帯の差を加味しています。 夏時間を使っている場合には、これは通常の使用にはさしつかえないものの、 わずかな誤差を生じるかもしれません。

formatdate( [timeval[, localtime]])
日付を RFC 2822 形式の文字列で返します。例:

Fri, 09 Nov 2001 01:08:47 -0000

オプションとして float 型の値をもつ引数 timeval が与えられた場合、 これは time.gmtime() および time.localtime() に 渡されます。それ以外の場合、現在の時刻が使われます。

オプション引数 localtime はフラグです。 これが True の場合、この関数は timeval を解析したあと UTC のかわりに現地時間 (localtime) の時間帯をつかって変換します。 おそらく夏時間も考慮に入れられるでしょう。 デフォルトではこの値は False で、UTC が使われます。

make_msgid( [idstring])
RFC 2822 準拠形式の Message-ID: ヘッダに適した 文字列を返します。オプション引数 idstring が文字列として 与えられた場合、これはメッセージ ID の一意性を高めるのに利用されます。

decode_rfc2231( s)
RFC 2231 に従って文字列 s をデコードします。

encode_rfc2231( s[, charset[, language]])
RFC 2231 に従って s をエンコードします。 オプション引数 charset および language が与えられた場合、 これらは文字セット名と言語名として使われます。 もしこれらのどちらも与えられていない場合、s はそのまま返されます。 charset は与えられているが language が与えられていない場合、 文字列 s は language の空文字列を使ってエンコードされます。

decode_params( params)
RFC 2231 に従ってパラメータのリストをデコードします。 params は (content-type, string-value) のような形式の 2要素からなるタプルです。

以下の関数はもはや時代遅れとなっており、推奨されません:

dump_address_pair( pair)
リリース 2.2.2 以降で撤廃された仕様です。 これのかわりに formataddr() メソッドを使ってください。

decode( s)
リリース 2.2.2 以降で撤廃された仕様です。 これのかわりに Header.decode_header() メソッドを使ってください。

encode( s[, charset[, encoding]])
リリース 2.2.2 以降で撤廃された仕様です。 これのかわりに Header.encode() メソッドを使ってください。

... に対するオフセットです12.6
注意: この時間帯のオフセット値は time.timezone の値と 符合が逆です。これは time.timezone が POSIX 標準に準拠しているのに対して、 こちらは RFC 2822 に準拠しているからです。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.8 例外クラス Up: 12.2 email Next: 12.2.10 イテレータ


12.2.10 イテレータ

Message.walk() メソッドを使うと、簡単に メッセージオブジェクトツリー内を次から次へとたどる (iteration) ことができます。 email.Iterators モジュールはこのための高水準イテレータを いくつか提供します。

body_line_iterator( msg[, decode])
このイテレータは msg 中のすべてのサブパートに含まれる ペイロードをすべて順にたどっていき、ペイロード内の文字列を 1行ずつ返します。 サブパートのヘッダはすべて無視され、Python 文字列でないペイロードからなる サブパートも無視されます。これは readline() を使って、 ファイルからメッセージを (ヘッダだけとばして) フラットなテキストとして 読むのにいくぶん似ているかもしれません。

オプション引数 decode は、Message.get_payload()にそのまま渡されます。

typed_subpart_iterator( msg[, maintype[, subtype]])
このイテレータは msg 中のすべてのサブパートをたどり、 それらの中で指定された MIME 形式 maintype と subtype をもつようなパートのみを返します。

subtype は省略可能であることに注意してください。 これが省略された場合、サブパートの MIME 形式は maintype のみが チェックされます。じつは maintype も省略可能で、 その場合にはデフォルトは text です。

つまり、デフォルトでは typed_subpart_iterator() は MIME 形式 text/* をもつサブパートを順に返していくというわけです。

以下の関数は役に立つデバッグ用ツールとして追加されたもので、 パッケージとして公式なサポートのあるインターフェイスではありません。

_structure( msg[, fp[, level]])
そのメッセージオブジェクト構造の content-type をインデントつきで 表示します。たとえば:

>>> msg = email.message_from_file(somefile)
>>> _structure(msg)
multipart/mixed
    text/plain
    text/plain
    multipart/digest
        message/rfc822
            text/plain
        message/rfc822
            text/plain
        message/rfc822
            text/plain
        message/rfc822
            text/plain
        message/rfc822
            text/plain
    text/plain

オプション引数 fp は出力を渡すためのストリーム 12.7オブジェクトです。 これは Python の拡張 print 文が対応できるようになっている必要があります。 level は内部的に使用されます。

... は出力を渡すためのストリーム12.7
訳注: 原文では file-like。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.9 雑用ユーティリティ Up: 12.2 email Next: 12.2.11 (Python 2.2.1 までの)


12.2.11 (Python 2.2.1 までの) email v1 とのちがい

email パッケージ バージョン 1 は、Python 2.2.1 リリースの ときまでバンドルされていました。バージョン 2 は Python 2.3 リリース用に 開発され、Python 2.2.2 にバックポートされたものです。 またこれは distutils ベースの別個のパッケージとしても配布されています。 email バージョン 2 はバージョン 1 とほとんどの点で下位互換ですが、 以下のような違いがあります:

  • email.Header モジュールおよび email.Charset モジュールが 追加されています。

  • Message インスタンスの Pickle 形式が変わりました。 が、これは正式に定義されたことは一度もないので (そしてこれからも)、 この変更は互換性の欠如とはみなされていません。ですがもし お使いのアプリケーションが Message インスタンスを pickle あるいは unpickle しているなら、現在 email バージョン 2 では プライベート変数 _charset および _default_type を 含むようになったということに注意してください。

  • Message クラス中のいくつかのメソッドは推奨されなくなったか、 あるいは呼び出し形式が変更になっています。また、多くの新しいメソッドが 追加されています。詳しくは Message クラスの文書を参照してください。 これらの変更は完全に下位互換になっているはずです。

  • message/rfc822 形式のコンテナは、 見た目上のオブジェクト構造が変わりました。email バージョン 1 では この content type はスカラー形式のペイロードとして表現されていました。 つまり、コンテナメッセージの is_multipart() は false を返し、get_payload() はリストオブジェクトではなく 単一の Message インスタンスを直接返すようになっていたのです。

    この構造はパッケージ中のほかの部分と整合がとれていなかったため、 message/rfc822 形式のオブジェクト表現形式が 変更されました。email バージョン 2 では、コンテナは is_multipart() に True を返します。 また get_payload() はひとつの Message インスタンスを 要素とするリストを返すようになりました。

    注意: ここは下位互換が完全には成りたたなくなっている部分のひとつです。 けれどもあらかじめ get_payload() が返すタイプをチェックするように なっていれば問題にはなりません。ただ message/rfc822 形式の コンテナを Message インスタンスにじかに set_payload() しないようにさえすればよいのです。

  • Parser コンストラクタに strict 引数が 追加され、parse() および parsestr() メソッドには headersonly 引数がつきました。strict フラグは また email.message_from_file() と email.message_from_string() にも追加されています。

  • Generator.__call__() はもはや推奨されなくなりました。 かわりに Generator.flatten() を使ってください。また、 Generator クラスには clone() メソッドが追加されています。

  • email.Generator モジュールに DecodedGenerator クラスが 加わりました。

  • 中間的な基底クラスである MIMENonMultipart および MIMEMultipart がクラス階層の中に追加され、 ほとんどの MIME 関係の派生クラスがこれを介するようになっています。

  • MIMEText コンストラクタの _encoder 引数は 推奨されなくなりました。いまやエンコーダは _charset 引数に もとづいて暗黙のうちに決定されます。

  • email.Utils モジュールにおける以下の関数は 推奨されなくなりました: dump_address_pairs()、 decode()、 および encode()。 また、このモジュールには以下の関数が追加されています: make_msgid()、 decode_rfc2231()、 encode_rfc2231() そして decode_params()。

  • Public ではない関数 email.Iterators._structure() が 追加されました。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.10 イテレータ Up: 12.2 email Next: 12.2.12 mimelib との違い


12.2.12 mimelib との違い

email パッケージはもともと mimelib と 呼ばれる個別のライブラリからつくられたものです。その後変更が加えられ、 メソッド名がより一貫したものになり、いくつかのメソッドやモジュールが 加えられたりはずされたりしました。いくつかのメソッドでは、 その意味も変更されています。しかしほとんどの部分において、 mimelib パッケージで使うことのできた機能は、ときどきその方法が変わってはいるものの email パッケージでも使用可能です。 mimelib パッケージと email パッケージの間の 下位互換性はあまり優先はされませんでした。

以下では mimelib パッケージと email パッケージにおける 違いを簡単に説明し、それに沿ってアプリケーションを移植するさいの 指針を述べています。

おそらく 2つのパッケージのもっとも明らかな違いは、 パッケージ名が email に変更されたことでしょう。 さらにトップレベルのパッケージが以下のように変更されました:

  • messageFromString() は message_from_string() に名前が変更されました。

  • messageFromFile() は message_from_file() に名前が変更されました。

Message クラスでは、以下のような違いがあります:

  • asString() メソッドは as_string() に名前が変更されました。

  • ismultipart() メソッドは is_multipart() に名前が変更されました。

  • get_payload() メソッドはオプション引数として decode をとるようになりました。

  • getall() メソッドは get_all() に名前が変更されました。

  • addheader() メソッドは add_header() に名前が変更されました。

  • gettype() メソッドは get_type() に名前が変更されました。

  • getmaintype() メソッドは get_main_type() に名前が変更されました。

  • getsubtype() メソッドは get_subtype() に名前が変更されました。

  • getparams() メソッドは get_params() に名前が変更されました。 また、従来の getparams() は文字列のリストを返していましたが、 get_params() は 2-タプルのリストを返すようになっています。 これはそのパラメータのキーと値の組が、"=" 記号によって分離されたものです。

  • getparam() メソッドは get_param().

  • getcharsets() メソッドは get_charsets() に名前が変更されました。

  • getfilename() メソッドは get_filename() に名前が変更されました。

  • getboundary() メソッドは get_boundary() に名前が変更されました。

  • setboundary() メソッドは set_boundary() に名前が変更されました。

  • getdecodedpayload() メソッドは廃止されました。 これと同様の機能は get_payload() メソッドの decode フラグに 1 を渡すことで実現できます。

  • getpayloadastext() メソッドは廃止されました。 これと同様の機能は email.Generator モジュールの DecodedGenerator クラスによって提供されます。

  • getbodyastext() メソッドは廃止されました。 これと同様の機能は email.Iterators モジュールにある typed_subpart_iterator() を使ってイテレータを作ることにより 実現できます。

Parser クラスは、その public なインターフェイスは変わっていませんが、 これはより一層かしこくなって message/delivery-status 形式のメッセージを 認識するようになりました。これは配送状態通知 12.8において、各ヘッダブロックを表す独立した Message パートを含む ひとつの Message インスタンスとして表現されます。

Generator クラスは、その public なインターフェイスは変わっていませんが、 email.Generator モジュールに新しいクラスが加わりました。 DecodedGenerator と呼ばれるこのクラスは 以前 Message.getpayloadastext() メソッドで使われていた 機能のほとんどを提供します。

また、以下のモジュールおよびクラスが変更されています:

  • MIMEBase クラスのコンストラクタ引数 _major と _minor は、それぞれ _maintype と _subtype に変更されています。

  • Image クラスおよびモジュールは MIMEImage に 名前が変更されました。_minor 引数も _subtype に 名前が変更されています。

  • Text クラスおよびモジュールは MIMEText に 名前が変更されました。_minor 引数も _subtype に 名前が変更されています。

  • MessageRFC822 クラスおよびモジュールは MIMEMessage に 名前が変更されました。注意: 従来バージョンの mimelib では、 このクラスおよびモジュールは RFC822 という名前でしたが、 これは大文字小文字を区別しないファイルシステムでは Python の標準ライブラリモジュール rfc822 と 名前がかち合ってしまっていました。

    また、MIMEMessage クラスはいまや message main type をもつあらゆる種類の MIME メッセージを 表現できるようになりました。これはオプション引数として、 MIME subtype を指定する _subtype 引数をとることができる ようになっています。デフォルトでは、_subtype は rfc822 に なります。

mimelib では、address および date モジュールで いくつかのユーティリティ関数が提供されていました。 これらの関数はすべて email.Utils モジュールの中に 移されています。

MsgReader クラスおよびモジュールは廃止されました。 これにもっとも近い機能は email.Iterators モジュール中の body_line_iterator() 関数によって提供されています。

... 認識するようになりました。これは配送状態通知12.8
配送状態通知 (Delivery Status Notifications, DSN) は RFC 1894 によって定義されています。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.11 (Python 2.2.1 までの) Up: 12.2 email Next: 12.2.13 使用例


12.2.13 使用例

ここでは email パッケージを使って電子メールメッセージを 読む・書く・送信するいくつかの例を紹介します。より複雑な MIME メッセージについても扱います。

最初に、テキスト形式の単純なメッセージを作成・送信する方法です:

# Import smtplib for the actual sending function
import smtplib

# Import the email modules we'll need
from email.MIMEText import MIMEText

# Open a plain text file for reading.  For this example, assume that
# the text file contains only ASCII characters.
fp = open(textfile, 'rb')
# Create a text/plain message
msg = MIMEText(fp.read())
fp.close()

# me == the sender's email address
# you == the recipient's email address
msg['Subject'] = 'The contents of %s' % textfile
msg['From'] = me
msg['To'] = you

# Send the message via our own SMTP server, but don't include the
# envelope header.
s = smtplib.SMTP()
s.connect()
s.sendmail(me, [you], msg.as_string())
s.close()
Download as text (original file name: email-simple.py).

つぎに、あるディレクトリ内にある何枚かの家族写真をひとつの MIME メッセージに 収めて送信する例です:

# Import smtplib for the actual sending function
import smtplib

# Here are the email pacakge modules we'll need
from email.MIMEImage import MIMEImage
from email.MIMEMultipart import MIMEMultipart

COMMASPACE = ', '

# Create the container (outer) email message.
msg = MIMEMultipart()
msg['Subject'] = 'Our family reunion'
# me == the sender's email address
# family = the list of all recipients' email addresses
msg['From'] = me
msg['To'] = COMMASPACE.join(family)
msg.preamble = 'Our family reunion'
# Guarantees the message ends in a newline
msg.epilogue = ''

# Assume we know that the image files are all in PNG format
for file in pngfiles:
    # Open the files in binary mode.  Let the MIMEImage class automatically
    # guess the specific image type.
    fp = open(file, 'rb')
    img = MIMEImage(fp.read())
    fp.close()
    msg.attach(img)

# Send the email via our own SMTP server.
s = smtplib.SMTP()
s.connect()
s.sendmail(me, family, msg.as_string())
s.close()
Download as text (original file name: email-mime.py).

つぎはあるディレクトリに含まれている内容全体を ひとつの電子メールメッセージとして送信するやり方です 12.9:

#!/usr/bin/env python

"""Send the contents of a directory as a MIME message.

Usage: dirmail [options] from to [to ...]*

Options:
    -h / --help
        Print this message and exit.

    -d directory
    --directory=directory
        Mail the contents of the specified directory, otherwise use the
        current directory.  Only the regular files in the directory are sent,
        and we don't recurse to subdirectories.

`from' is the email address of the sender of the message.

`to' is the email address of the recipient of the message, and multiple
recipients may be given.

The email is sent by forwarding to your local SMTP server, which then does the
normal delivery process.  Your local machine must be running an SMTP server.
"""

import sys
import os
import getopt
import smtplib
# For guessing MIME type based on file name extension
import mimetypes

from email import Encoders
from email.Message import Message
from email.MIMEAudio import MIMEAudio
from email.MIMEBase import MIMEBase
from email.MIMEMultipart import MIMEMultipart
from email.MIMEImage import MIMEImage
from email.MIMEText import MIMEText

COMMASPACE = ', '

def usage(code, msg=''):
    print >> sys.stderr, __doc__
    if msg:
        print >> sys.stderr, msg
    sys.exit(code)

def main():
    try:
        opts, args = getopt.getopt(sys.argv[1:], 'hd:', ['help', 'directory='])
    except getopt.error, msg:
        usage(1, msg)

    dir = os.curdir
    for opt, arg in opts:
        if opt in ('-h', '--help'):
            usage(0)
        elif opt in ('-d', '--directory'):
            dir = arg

    if len(args) < 2:
        usage(1)

    sender = args[0]
    recips = args[1:]

    # Create the enclosing (outer) message
    outer = MIMEMultipart()
    outer['Subject'] = 'Contents of directory %s' % os.path.abspath(dir)
    outer['To'] = COMMASPACE.join(recips)
    outer['From'] = sender
    outer.preamble = 'You will not see this in a MIME-aware mail reader.\n'
    # To guarantee the message ends with a newline
    outer.epilogue = ''

    for filename in os.listdir(dir):
        path = os.path.join(dir, filename)
        if not os.path.isfile(path):
            continue
        # Guess the content type based on the file's extension.  Encoding
        # will be ignored, although we should check for simple things like
        # gzip'd or compressed files.
        ctype, encoding = mimetypes.guess_type(path)
        if ctype is None or encoding is not None:
            # No guess could be made, or the file is encoded (compressed), so
            # use a generic bag-of-bits type.
            ctype = 'application/octet-stream'
        maintype, subtype = ctype.split('/', 1)
        if maintype == 'text':
            fp = open(path)
            # Note: we should handle calculating the charset
            msg = MIMEText(fp.read(), _subtype=subtype)
            fp.close()
        elif maintype == 'image':
            fp = open(path, 'rb')
            msg = MIMEImage(fp.read(), _subtype=subtype)
            fp.close()
        elif maintype == 'audio':
            fp = open(path, 'rb')
            msg = MIMEAudio(fp.read(), _subtype=subtype)
            fp.close()
        else:
            fp = open(path, 'rb')
            msg = MIMEBase(maintype, subtype)
            msg.set_payload(fp.read())
            fp.close()
            # Encode the payload using Base64
            Encoders.encode_base64(msg)
        # Set the filename parameter
        msg.add_header('Content-Disposition', 'attachment', filename=filename)
        outer.attach(msg)

    # Now send the message
    s = smtplib.SMTP()
    s.connect()
    s.sendmail(sender, recips, outer.as_string())
    s.close()

if __name__ == '__main__':
    main()
Download as text (original file name: email-dir.py).

そして最後に、上のような MIME メッセージをどうやって 展開してひとつのディレクトリ上の複数ファイルにするかを示します:

#!/usr/bin/env python

"""Unpack a MIME message into a directory of files.

Usage: unpackmail [options] msgfile

Options:
    -h / --help
        Print this message and exit.

    -d directory
    --directory=directory
        Unpack the MIME message into the named directory, which will be
        created if it doesn't already exist.

msgfile is the path to the file containing the MIME message.
"""

import sys
import os
import getopt
import errno
import mimetypes
import email

def usage(code, msg=''):
    print >> sys.stderr, __doc__
    if msg:
        print >> sys.stderr, msg
    sys.exit(code)

def main():
    try:
        opts, args = getopt.getopt(sys.argv[1:], 'hd:', ['help', 'directory='])
    except getopt.error, msg:
        usage(1, msg)

    dir = os.curdir
    for opt, arg in opts:
        if opt in ('-h', '--help'):
            usage(0)
        elif opt in ('-d', '--directory'):
            dir = arg

    try:
        msgfile = args[0]
    except IndexError:
        usage(1)

    try:
        os.mkdir(dir)
    except OSError, e:
        # Ignore directory exists error
        if e.errno <> errno.EEXIST: raise

    fp = open(msgfile)
    msg = email.message_from_file(fp)
    fp.close()

    counter = 1
    for part in msg.walk():
        # multipart/* are just containers
        if part.get_content_maintype() == 'multipart':
            continue
        # Applications should really sanitize the given filename so that an
        # email message can't be used to overwrite important files
        filename = part.get_filename()
        if not filename:
            ext = mimetypes.guess_extension(part.get_type())
            if not ext:
                # Use a generic bag-of-bits extension
                ext = '.bin'
            filename = 'part-%03d%s' % (counter, ext)
        counter += 1
        fp = open(os.path.join(dir, filename), 'wb')
        fp.write(part.get_payload(decode=1))
        fp.close()

if __name__ == '__main__':
    main()
Download as text (original file name: email-unpack.py).

... ひとつの電子メールメッセージとして送信するやり方です12.9
最初の思いつきと用例は Matthew Dixon Cowles のおかげです。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.12 mimelib との違い Up: 12.2 email Next: 12.3 mailcap


12.3 mailcap -- mailcap ファイルの操作

mailcap ファイルは、メイルリーダや Web ブラウザのような MIME 対応の アプリケーションが、異なる MIME タイプのファイルにどのように反応 するかを設定するために使われます (``mailcap'' の名前は ``mail capability'' から取られました)。 例えば、ある mailcap ファイルに "video/mpeg; xmpeg %s" のような 行が入っていたとします。ユーザが email メッセージや Web ドキュメント 上でその MIME タイプ video/mpeg に遭遇すると、 "%s" はファイル名 (通常テンポラリファイルに属するものになります) に置き換えられ、ファイルを閲覧するために xmpeg プログラムが 自動的に起動されます。

mailcap の形式は RFC 1524, ``A User Agent Configuration Mechanism For Multimedia Mail Format Information'' で文書化されていますが、この文書はインターネット標準ではありません。 しかしながら、 mailcap ファイルはほとんどの Unix システムで サポートされています。

findmatch( caps, MIMEtype[, key[, filename[, plist]]])
2 要素のタプルを返します; 最初の要素は文字列で、実行すべき コマンド (os.system() に渡されます) が入っています。 二つめの要素は与えられた MIME タイプに対する mailcap エントリです。 一致する MIME タイプが見つからなかった場合、(None, None) が 返されます。

key は desired フィールドの値で、 実行すべき動作のタイプを表現します; ほとんどの場合、単に MIME 形式のデータ本体を見たいと思うので、標準の値は 'view' になっています。与えられた MIME 型をもつ新たなデータ本体を作成した 場合や、既存のデータ本体を置き換えたい場合には、'view' の他に 'compose' および 'edit' を取ることもできます。

これらフィールドの完全なリストについては RFC 1524 を参照してください。

filename はコマンドライン中で "%s" に代入されるファイル名 です; 標準の値は '/dev/null' で、たいていこの値を使いたい わけではないはずです。従って、ファイル名を指定してこのフィールドを 上書きする必要があるでしょう。

plist は名前付けされたパラメタのリストです; 標準の値は単なる 空のリストです。リスト中の各エントリはパラメタ名を含む文字列、 等号 ("=")、およびパラメタの値でなければなりません。 mailcap エントリには %{foo} といったような名前つき のパラメタを含めることができ、'foo' と名づけられたパラメタの値に 置き換えられます。例えば、コマンドライン "showpartial %{id} %{number} %{total}"が mailcap ファイルにあり、plist が ['id=1', 'number=2', 'total=3'] に設定されていれば、コマンドラインは 'showpartial 1 2 3' になります。

mailcap ファイル中では、 オプションの ``test'' フィールドを 使って、(計算機アーキテクチャや、利用しているウィンドウシステムといった) 何らかの外部条件をテストするよう指定することができます。 findmatch() はこれらの条件を自動的にチェックし、 チェックが失敗したエントリを読み飛ばします。

getcaps( )
MIME タイプを mailcap ファイルのエントリに対応付ける辞書を返します。 この辞書は findmatch() 関数に渡されるべきものです。 エントリは辞書のリストとして記憶されますが、この表現形式の 詳細について知っておく必要はないでしょう。

mailcap 情報はシステム上で見つかった全ての mailcap ファイルから 導出されます。ユーザ設定の mailcap ファイル $HOME/.mailcap はシステムの mailcap ファイル /etc/mailcap、 /usr/etc/mailcap、および /usr/local/etc/mailcap の内容を上書きします。

以下に使用例を示します:

>>> import mailcap
>>> d=mailcap.getcaps()
>>> mailcap.findmatch(d, 'video/mpeg', filename='/tmp/tmp1223')
('xmpeg /tmp/tmp1223', {'view': 'xmpeg %s'})
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.13 使用例 Up: 12. インターネット上のデータの操作 Next: 12.4 mailbox


12.4 mailbox -- 様々なメールボックス形式の読み出し

このモジュールでは (Unixの) メイルボックス内のメイルに 簡単かつ一様な方法でアクセスできるようにするクラスを定義しています。

class UnixMailbox( fp[, factory])
全てのメッセージが単一のファイルに収められ、"From " ("From_" として知られています) 行によって分割されているような、 旧来の Unix形式のメイルボックスにアクセスします。 ファイルオブジェクト fp はメイルボックスファイルを指します。 オプションの factory パラメタは新たなメッセージオブジェクト を生成するような呼び出し可能オブジェクトです。factory は、 メイルボックスオブジェクトに対して next() メソッドを実行 した際に、単一の引数、fp を伴って呼び出されます。 この引数の標準の値は rfc822.Message クラスです (rfc822 モジュール - および以下 - を参照してください)。

可搬性を最大限にするために、Unix形式のメイルボックス内にある メッセージは、正確に 'From ' (末尾の空白に注意してください) で始まる文字列が、直前の正しく二つの改行の後にくるような行で 分割されます。現実的には広範なバリエーションがあるため、それ以外の From_ 行について考慮すべきではないのですが、現在の実装では先頭の 二つの改行をチェックしていません。これはほとんどのアプリケーションで うまく動作します。

UnixMailbox クラスでは、ほぼ正確に From_ デリミタにマッチする ような正規表現を用いることで、より厳密に From_ 行のチェックを行う バージョンを実装しています。UnixMailbox ではデリミタ行が "From namevartime" の行に分割されるものと考えます。 可搬性を最大限にするためには、代わりに PortableUnixMailbox クラスを使ってください。このクラスは UnixMailbox と同じですが、 個々のメッセージは "From " 行だけで分割されるものとみなします。

より詳細な情報については、 Unix: Why the Content-Length Format is Bad" >Configuring Netscape Mail on Unix: Why the Content-Length Format is Bad を参照してください。

class PortableUnixMailbox( fp[, factory])
厳密性の低い UnixMailbox のバージョンで、メッセージを分割 する行は "From " のみであると見なします。実際に見られるメイル ボックスのバリエーションに対応するため、 From 行における ``name time'' 部分は無視されます。メイル処理ソフトウェア はメッセージ中の 'From ' で始まる行をクオートするため、 この分割はうまく動作します。

class MmdfMailbox( fp[, factory])
全てのメッセージが単一のファイルに収められ、4 つの control-A 文字 によって分割されているような、MMDF 形式のメイルボックスにアクセスします。 ファイルオブジェクト fp はメイルボックスファイルをさします。 オプションの factory は UnixMailbox クラスにおけるのと 同様です。

class MHMailbox( dirname[, factory])
数字で名前のつけられた別々のファイルに個々のメッセージを収めた ディレクトリである、MH メイルボックスにアクセスします。 メイルボックスディレクトリの名前は dirname で渡します。 factory は UnixMailbox クラスにおけるのと 同様です。

class Maildir( dirname[, factory])
Qmail メイルディレクトリにアクセスします。dirname で 指定された全ての新規および現在のメッセージにアクセスできます。 factory は UnixMailbox クラスにおけるのと 同様です。

class BabylMailbox( fp[, factory])
MMDF メイルボックスと似ている、Babyl メイルボックスにアクセスします。 Babyl 形式では、各メッセージは二つのヘッダからなるセット、 original ヘッダおよび visible ヘッダをを持っています。 original ヘッダは '*** EOOH ***' (End-Of-Original-Headers) だけを含む行の前にあり、visible ヘッダは EOOH 行の後に あります。Babyl 互換のメイルリーダは visible ヘッダのみを表示 し、 BabylMailbox オブジェクトは visible ヘッダのみを 含むようなメッセージを返します。メイルメッセージは EOOH 行で始まり、 '\037\014' だけを含む行で終わります。 factory は UnixMailbox クラスにおけるのと 同様です。

rfc822 モジュールが撤廃されたことにより、 email パッケージを使ってメイルボックスから メッセージオブジェクトを生成するよう推奨されているので 注意してください。 (デフォルトの設定は以前のバージョンとの 互換性のために変更されていません。) 安全に移行を行うには、以下のちょっとしたコードを使います:

import email
import email.Errors
import mailbox

def msgfactory(fp):
    try:
        return email.message_from_file(fp)
    except email.Errors.MessageParseError:
        # Don't return None since that will
    # stop the mailbox iterator
    return ''

mbox = mailbox.UnixMailbox(fp, msgfactory)

上のラッパはメイルボックス内にある不正な形式の MIME メッセージに 対して防御性がある反面、メイルボックスの next() メソッド が空文字列を渡す場合に備えなければなりません。逆に、もし メイルボックス内には正しい形式の MIME メッセージしか入っていないと 分かっているのなら、単に以下のようにします:

import email
import mailbox

mbox = mailbox.UnixMailbox(fp, email.message_from_file)

参考資料:

mbox - file containing mail messages
伝統的な ``mbox'' メイルボックス形式に関する記述です。
maildir - directory for incoming mail messages
``maildir'' メイルボックス形式の記述です。
Configuring Netscape Mail on Unix: Why the Content-Length Format is Bad
メイルボックスファイルに記録されている Content-Length: ヘッダに依存した場合に発生する問題についての記述です。

  • 12.4.1 Mailbox オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.3 mailcap Up: 12. インターネット上のデータの操作 Next: 12.4.1 Mailbox オブジェクト


12.4.1 Mailbox オブジェクト

メイルボックスオブジェクトの実装はすべて反復可能なオブジェクトであり、 外部に公開されているメソッドを一つもっています。このメソッドは メイルボックスオブジェクトから生成されるイテレータによって使われ、 直接利用することもできます。

next( )
メイルボックスオブジェクトのコンストラクタに渡された、オプションの factory 引数を使って、メイルボックス中の次のメッセージを 生成して返します。標準の設定では、factory は rfc822.Message オブジェクトです (rfc822 モジュールを参照してください)。 メイルボックスの実装により、このオブジェクトの fp 属性は 真のファイルオブジェクトかもしれないし、 複数のメイルメッセージが単一のファイルに収められているなどの場合に、 メッセージ間の境界を注意深く扱うためにファイルオブジェクトをシミュレート するクラスのインスタンスであるかもしれません。 次のメッセージがない場合、このメソッドは None を返します。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.4 mailbox Up: 12.4 mailbox Next: 12.5 mhlib


12.5 mhlib -- MH のメイルボックスへのアクセス機構

mhlib モジュールは MH フォルダおよびその内容に対する Python インタフェースを提供します。

このモジュールには、あるフォルダの集まりを表現する MH、 単一のフォルダを表現する Folder、単一のメッセージを表現 する Message、の 3 つのクラスが入っています。

class MH( [path[, profile]])
MH は MH フォルダの集まりを表現します。

class Folder( mh, name)
Folder クラスは単一のフォルダとフォルダ内のメッセージ群を 表現します。

class Message( folder, number[, name])
Message オブジェクトはフォルダ内の個々のメッセージを表現 します。メッセージクラスは mimetools.Message から 導出されています。

  • 12.5.1 MH オブジェクト
  • 12.5.2 Folder オブジェクト
  • 12.5.3 Message オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.4.1 Mailbox オブジェクト Up: 12. インターネット上のデータの操作 Next: 12.5.1 MH オブジェクト


12.5.1 MH オブジェクト

MH インスタンスは以下のメソッドを持っています:

error( format[, ...])
エラーメッセージを出力します - 上書きすることができます。

getprofile( key)
プロファイルエントリ (設定されていなければ None) を返します。

getpath( )
メイルボックスのパス名を返します。

getcontext( )
現在のフォルダ名を返します。

setcontext( name)
現在のフォルダ名を設定します。

listfolders( )
トップレベルフォルダのリストを返します。

listallfolders( )
全てのフォルダを列挙します。

listsubfolders( name)
指定したフォルダの直下にあるサブフォルダのリストを返します。

listallsubfolders( name)
指定したフォルダの下にある全てのサブフォルダのリストを返します。

makefolder( name)
新しいフォルダを生成します。

deletefolder( name)
フォルダを削除します - サブフォルダが入っていてはいけません。

openfolder( name)
新たな開かれたフォルダオブジェクトを返します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.5 mhlib Up: 12.5 mhlib Next: 12.5.2 Folder オブジェクト


12.5.2 Folder オブジェクト

Folder インスタンスは開かれたフォルダを表現し、以下のメソッドを 持っています:

error( format[, ...])
エラーメッセージを出力します - 上書きすることができます。

getfullname( )
フォルダの完全なパス名を返します。

getsequencesfilename( )
フォルダ内のシーケンスファイルの完全なパス名を返します。

getmessagefilename( n)
フォルダ内のメッセージ n の完全なパス名を返します。

listmessages( )
フォルダ内のメッセージの (番号の) リストを返します。

getcurrent( )
現在のメッセージ番号を返します。

setcurrent( n)
現在のメッセージ番号を n に設定します。

parsesequence( seq)
msgs 文を解釈して、メッセージのリストにします。

getlast( )
最新のメッセージを取得します。メッセージがフォルダにない場合には 0 を返します。

setlast( n)
最新のメッセージを設定します (内部使用のみ)。

getsequences( )
フォルダ内のシーケンスからなる辞書を返します。シーケンス名がキーとして 使われ、値はシーケンスに含まれるメッセージ番号のリストになります。

putsequences( dict)
フォルダ内のシーケンスからなる辞書 name: list を返します。

removemessages( list)
リスト中のメッセージをフォルダから削除します。

refilemessages( list, tofolder)
リスト中のメッセージを他のフォルダに移動します。

movemessage( n, tofolder, ton)
一つのメッセージを他のフォルダの指定先に移動します。

copymessage( n, tofolder, ton)
一つのメッセージを他のフォルダの指定先にコピーします。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.5.1 MH オブジェクト Up: 12.5 mhlib Next: 12.5.3 Message オブジェクト


12.5.3 Message オブジェクト

Message クラスは mimetools.Message の メソッドに加え、一つメソッドを持っています:

openmessage( n)
新たな開かれたメッセージオブジェクトを返します (ファイル記述子を 一つ消費します)。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.5.2 Folder オブジェクト Up: 12.5 mhlib Next: 12.6 mimetools


12.6 mimetools -- MIME メッセージを解析するためのツール

リリース 2.3 以降で撤廃された仕様です。 email パッケージを mimetoolsモジュールより 優先して使うべきです。この モジュールは、下位互換性維持のためにのみ 存在しています。

このモジュールは、 rfc822モジュールの Message クラスのサブクラスと、マルチパートMIME や符合化メッセージの操作に 役に立つ多くのユーティリティ関数を定義しています。

これには以下の項目が定義されています：

class Message( fp[, seekable])
Message クラスの新しいインスタンスを返します。これは、 rfc822.Message クラスのサブクラスで、いくつかの追加のメソッドが あります(以下を参照のこと)。 seekable 引数は、 rfc822.Messageの ものと同じ意味を持ちます。

choose_boundary( )
パートの境界として使うことができる見込みが高いユニークな文字列を返します。 その文字列は、 'hostipaddr.uid.pid.timestamp.random' の形をしています。

decode( input, output, encoding)
オープンしたファイルオブジェクト input から、許される MIME encoding を使って符号化されたデータを読んで、オープンされたファイルオブジェクト output に復号化されたデータを書きます。 encoding に許される値は、 'base64', 'quoted-printable', 'uuencode', 'x-uuencode', 'uue', 'x-uue', '7bit', および '8bit'です。'7bit' あるいは '8bit' で符号化された メッセージを復号化しても何も効果がありません。入力が出力に単純にコピーされるだけです。

encode( input, output, encoding)
オープンしたファイルオブジェクト input からデータを読んで、 それを許される MIME encoding を使って符号化して、オープンした ファイルオブジェクト output に書きます。 encoding に許される値は、[methoddecode()のものと同じです。

copyliteral( input, output)
オープンしたファイル inputから行を EOF まで読んで、 それらをオープンしたファイル output に書きます。

copybinary( input, output)
オープンしたファイル inputからブロックを EOF まで読んで、 それらをオープンしたファイル output に書きます。 ブロックの大きさは現在 8192 に固定されています。

参考資料:

emailモジュール:
圧縮電子メール操作パッケージ； mimetools モジュールに委譲。.
rfc822モジュール:
mimetools.Messageのベースクラスを提供する。.
multifileモジュール:
MIME データのような、別個のパーツを含む ファイルの読み込みをサポート。.
http://www.cs.uu.nl/wais/html/na-dir/mail/mime-faq/.html
MIME でよく訊ねられる質問。MIMEの概要に関しては、 この文書の Part 1 の質問 1.1 への答えを見ること。

  • 12.6.1 Message オブジェクトの追加メソッド
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.5.3 Message オブジェクト Up: 12. インターネット上のデータの操作 Next: 12.6.1 Message オブジェクトの追加メソッド


12.6.1 Message オブジェクトの追加メソッド

Message クラスは、rfc822.Message メソッドに加えて、 以下のメソッドを定義しています：

getplist( )
Content-Type: ヘッダのパラメータリストを返します。 これは文字列のリストです。 "key=value"の形のパラメータに対しては、 key は小文字に変換されますが、 value は変換されません。 たとえば、もしメッセージに、ヘッダ "Content-type: text/html; spam=1; Spam=2; Spam" が含まれていれば、 getplist() は、Python リスト ['spam=1', 'spam=2', 'Spam']を返すでしょう。

getparam( name)
与えられた nameの( "name=value" の形に対して getplist() が返す ) 第1パラメータの value を返します。 もし value が、`<...>' あるいは `"..."'のように引用符で囲まれていれば、 これらは除去されます。

getencoding( )
Content-Transfer-Encoding: メッセージヘッダで指定された 符号化方式を返します。もしそのようなヘッダが存在しなければ、 '7bit'を返します。符号化方式文字列は小文字に変換されます。

gettype( )
Content-Type: ヘッダで指定された ("type/subtype"の形での)メッセージ型を返します。 もしそのようなヘッダが存在しなければ、 'text/plain'を返します。 型文字列は小文字に変換されます。

getmaintype( )
Content-Type: ヘッダで指定された主要型を返します。 もしそのようなヘッダが存在しなければ、 'text'を返します。 主要型文字列は小文字に変換されます。

getsubtype( )
Content-Type:ヘッダで指定された下位型を返します。 もしそのようなヘッダが存在しなければ、 'plain'を返します。 下位型文字列は小文字に変換されます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.6 mimetools Up: 12.6 mimetools Next: 12.7 mimetypes


12.7 mimetypes -- ファイル名を MIME 型へマップする

mimetypes モジュールは、ファイル名あるいは URL と、ファイル名拡張子に 関連付けられた MIME 型とを変換します。ファイル名から MIME 型へと、 MIME 型からファイル名拡張子への変換が提供されます； 後者の変換では符号化方式はサポートされていません。

このモジュールは、一つのクラスと多くの便利な関数を提供します。 これらの関数がこのモジュールへの標準のインターフェースですが、 アプリケーションによっては、そのクラスにも関係するかもしれません。

以下で説明されている関数は、このモジュールへの主要なインターフェースを 提供します。たとえモジュールが初期化されていなくても、もしこれらの関数が、 init() がセットアップする情報に依存していれば、これらの関数は、 init() を呼びます。

guess_type( filename[, strict])
filename で与えられるファイル名あるいは URL に基づいて、 ファイルの型を推定します。戻り値は、タプル (type, encoding) です、ここで typeは、 もし型が(拡張子がないあるいは未定義のため)推定できない場合は、 None を、あるいは、 MIME content-type: ヘッダ に利用できる、'type/subtype'の形の文字列です。

encoding は、符合化方式がない場合は None を、あるいは、 符号化に使われるプログラムの名前 (たとえば、compress あるいは gzip)です。 符号化方式は Content-Encoding:ヘッダとして 使うのに適しており、 Content-Transfer-Encoding: ヘッダには適していません。 マッピングはテーブルドリブンです。符号化方式のサフィックスは大/小文字を区別します; データ型サフィックスは、最初大/小文字を区別して試し、 それから大/小文字を区別せずに試します。

省略可能な strictは、既知の MIME 型のリストとして認識されるものが、 IANAとして登録された 正式な型のみに限定されるかどうかを指定するフラグです。 strict が true (デフォール)の時は、IANA 型のみがサポートされます; strict が false のときは、いくつかの追加の、非標準ではあるが、一般的に 使用される MIME 型も認識されます。

guess_all_extensions( type[, strict])
type で与えられる MIME 型に基づいてファイルの拡張子を推定します。 戻り値は、先頭のドット (".")を含む、可能なファイル拡張子すべてを 与える文字列のリストです。拡張子と特別なデータストリームとの関連付けは 保証されませんが、 guess_type()によって MIME型 type とマップされます。

省略可能な strict は guess_type() 関数のものと同じ意味を持ちます。

guess_extension( type[, strict])
type で与えられる MIME 型に基づいてファイルの拡張子を推定します。 戻り値は、先頭のドット (".")を含む、ファイル拡張子を 与える文字列のリストです。拡張子と特別なデータストリームとの関連付けは 保証されませんが、 guess_type()によって MIME型 type とマップされます。 もし typeに対して拡張子が推定できない場合は、 Noneが返されます。

省略可能な strict は guess_type() 関数のものと同じ意味を持ちます。

モジュールの動作を制御するために、いくつかの追加の関数とデータ項目が 利用できます。

init( [files])
内部のデータ構造を初期化します。 もし files が与えられていれば、これはデフォールトの型のマップを 増やすために使われる、一連のファイル名でなければなりません。 もし省略されていれば、使われるファイル名は knownfilesから 取られます。file あるいは knownfiles 内の各ファイル名は、 それ以前に現れる名前より優先されます。 繰り返し init() を呼び出すことは許されています。

read_mime_types( filename)
ファル filename で与えられた型のマップが、もしあればロードします。 型のマップは、先頭の dot (".") を含むファイル名拡張子を、 'type/subtype'の形の文字列にマッピングする辞書として返されます。 もしファイル filename が存在しないか、読み込めなければ、 None が返されます。

add_type( type, ext[, strict])
mime型 type からのマッピングを拡張子 ext に追加します。 拡張子がすでに既知であれば、新しい型が古いものに置き替わります。 その型がすでに既知であれば、その拡張子が、既知の拡張子のリストに追加されます。

strictがある時は、そのマッピングは正式なMIME型に、 そうでなければ、非標準のMIME型に追加されます。

inited
グローバルなデータ構造が初期化されているかどうかを示すフラグ。 これは init() により true に設定されます。

knownfiles
共通にインストールされた型マップファイル名のリスト。これらの ファイルは、普通 mime.typesという名前であり、パッケージごとに 異なる場所にインストールされます。

suffix_map
サフィックスをサフィックスにマップする辞書。これは、符号化方式と 型が同一拡張子で示される符号化ファイルが認識できるように 使用されます。例えば、.tgz 拡張子は、符号化と型が別個に 認識できるように .tar.gzにマップされます。

encodings_map
ファイル名拡張子を符号化方式型にマッピングする辞書

types_map
ファイル名拡張子をMIME型にマップする辞書

common_types
ファイル名拡張子を非標準ではあるが、一般に使われているMIME型に マップする辞書

MimeTypes クラスは、1つ以上のMIME-型 データベースを 必要とするアプリケーションに役に立つでしょう。

class MimeTypes( [filenames])
このクラスは、MIME-型データベースを表現します。デフォールトでは、 このモジュールの他のものと同じデータベースへのアクセスを提供します。 初期データベースは、このモジュールによって提供されるもののコピーで、 追加の mime.types-形式のファイルを、read() あるいは readfp() メソッドを使って、データベースにロードすることで拡張されます。 マッピング辞書も、もしデフォールトのデータが望むものでなければ、 追加のデータをロードする前にクリアされます。

省略可能な filenamesパラメータは、追加のファイルを、デフォールト データベースの"トップに"ロードさせるのに使うことができます。

バージョン2.2 以降で新規追加された 仕様です。

  • 12.7.1 Mime型 オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.6.1 Message オブジェクトの追加メソッド Up: 12. インターネット上のデータの操作 Next: 12.7.1 Mime型 オブジェクト


12.7.1 Mime型 オブジェクト

MimeTypes インスタンスは、mimetypes モジュールの それと非常によく似たインターフェースを提供します。

suffix_map
サフィックスをサフィックスにマップする辞書。これは、符号化方式と 型が同一拡張子で示されるような符号化ファイルが認識できるように 使用されます。例えば、.tgz 拡張子は、符号化方式と型が別個に 認識できるように .tar.gzに対応づけられます。 これは、最初はモジュールで定義されたグローバルな suffix_map の コピーです。

encodings_map
ファイル名拡張子を符号化型にマッピングする辞書。 これは、最初はモジュールで定義されたグローバルな encodings_map の コピーです。

types_map
ファイル名拡張子をMIME型にマッピングするる辞書。 これは、最初はモジュールで定義されたグローバルな types_map の コピーです。

common_types
ファイル名拡張子を非標準ではあるが、一般に使われているMIME型にマップする辞書。 これは、最初はモジュールで定義されたグローバルな common_types の コピーです。

guess_extension( type[, strict])
guess_extension() 関数と同様に、オブジェクトの 一部として保存されたテーブルを使用します。

guess_type( url[, strict])
guess_type() 関数と同様に、オブジェクトの 一部として保存されたテーブルを使用します。

read( path)
MIME情報を、pathという名のファイルからロードします。 これはファイルを解析するのに readfp() を使用します。

readfp( file)
MIME型情報を、オープンしたファイルからロードします。 ファイルは、標準の mime.types ファイルの形式でなければなりません。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.7 mimetypes Up: 12.7 mimetypes Next: 12.8 MimeWriter


12.8 MimeWriter -- 汎用 MIME ファイルライター

リリース 2.3 以降で撤廃された仕様です。 email パッケージを、MimeWriter モジュールよりも優先して使用すべきです。このモジュールは、 下位互換性維持のためだけに存在します。

このモジュールは、クラス MimeWriterを定義します。この MimeWriter クラスは、MIME マルチパートファイルを作成するための 基本的なフォーマッタを実装します。これは出力ファイル内をあちこち移動することも、 大量のバッファスペースを使うこともありません。あなたは、最終のファイルに 現れるであろう順番に、パートを書かなければなりません。 MimeWriter は、あなたが追加するヘッダをバッファして、それらの 順番を並び替えることができるようにします。

class MimeWriter( fp)
MimeWriter クラスの新しいインスタンスを返します。渡される 唯一の引数 fp は、書くために使用するファイルオブジェクトです。 StringIO オブジェクトを使うこともできることに注意して下さい。

  • 12.8.1 MimeWriter オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.7.1 Mime型 オブジェクト Up: 12. インターネット上のデータの操作 Next: 12.8.1 MimeWriter オブジェクト


12.8.1 MimeWriter オブジェクト

MimeWriter インスタンスには以下のメソッドがあります：

addheader( key, value[, prefix])
MIMEメッセージに新しいヘッダ行を追加します。key は、 そのヘッダの名前であり、そして valueで、そのヘッダの値を明示的に 与えます。省略可能な引数 prefixは、ヘッダが挿入される場所を決定します; "0" は最後に追加することを意味し、"1" は先頭への挿入です。 デフォールトは最後に追加することです。

flushheaders( )
今まで集められたヘッダすべてが書かれ(そして忘れられ)るようにします。 これは、もし全く本体が必要でない場合に役に立ちます。例えば、 ヘッダのような情報を保管するために(誤って)使用された、 型 message/rfc822 のサブパート用。

startbody( ctype[, plist[, prefix]])
メッセージの本体に書くのに使用できるファイルのようなオブジェクトを 返します。コンテント-型は、与えられた ctype に設定され、 省略可能なパラメータ plistは、コンテント-型定義のための 追加のパラメータを与えます。 prefix は、そのデフォールトが 先頭への挿入以外は addheader() でのように働きます。

startmultipartbody( subtype[, boundary[, plist[, prefix]]])
メッセージ本体を書くのに使うことができるファイルのようなオブジェクトを 返します。更に、このメソッドはマルチパートのコードを初期化します。ここで、 subtype が、そのマルチパートのサブタイプを、 boundary がユーザ定義の境界仕様を、そして plist が、そのサブタイプ用の省略可能なパラメータを定義します。 prefix は、startbody() でのように働きます。サブパートは、 nextpart()を使って作成するべきです。

nextpart( )
マルチパートメッセージの個々のパートを表す、 MimeWriterの 新しいインスタンスを返します。これは、そのパートを書くのにも、 また複雑なマルチパートを再帰的に作成するのにも使うことができます。 メッセージは、nextpart() を使う前に, 最初 startmultipartbody() で初期化しなければなりません。

lastpart( )
これは、マルチパートメッセージの最後のパートを指定するのに使うことが でき、マルチパートメッセージを書くときは いつでも使うべきです。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.8 MimeWriter Up: 12.8 MimeWriter Next: 12.9 mimify


12.9 mimify -- 電子メイルメッセージの MIME 処理

リリース 2.3 以降で撤廃された仕様です。 mimify モジュールを使うよりも email パッケージを使うべきです。このモジュールは 以前のバージョンとの互換性のために保守されているにすぎません。

mimify モジュールでは電子メイルメッセージから MIME へ、 および MIME から電子メイルメッセージへの変換を行うための二つの関数を 定義しています。電子メイルメッセージは単なるメッセージでも、 MIME 形式でもかまいません。各パートは個別に扱われます。 メッセージ (の一部) の MIME 化 (mimify) の際、7 ビット ASCII 文字を使って表現できない何らかの文字が含まれていた場合、メッセージの quoted-printable への符号化が伴います。メッセージが送信される前に 編集しなければならない場合、MIME 化および非 MIME 化は特に便利です。 典型的な使用法は以下のようになります:

unmimify message
edit message
mimify message
send message

モジュールでは以下のユーザから呼び出し可能な関数と、ユーザが設定可能な 変数を定義しています:

mimify( infile, outfile)
infile を outfile にコピーします。その際、パートを quoted-printable に変換し、必要なら MIME メイルヘッダを追加します。 infile および outfile はファイルオブジェクト (実際には、readline() メソッドを持つ (infile) か、 write (outfile) メソッドを持つあらゆるオブジェクト) か、ファイル名を指す文字列を指定することができます。 infile および outfile が両方とも文字列の場合、 同じ値にすることができます。

unmimify( infile, outfile[, decode_base64])
infile を outfile にコピーします。その際、全ての quoted-printable 化されたパートを復号化します。infile および outfile はファイルオブジェクト (実際には、readline() メソッドを持つ (infile) か、 write (outfile) メソッドを持つあらゆるオブジェクト) か、ファイル名を指す文字列を指定することができます。 decode_base64 引数が与えられており、その値が真である場合、 base64 符号で符号化されているパートも同様に復号化されます。

mime_decode_header( line)
line 内の符号化されたヘッダ行が復号化されたものを 返します。ISO 8859-1 文字セット (Latin-1) だけをサポートします。

mime_encode_header( line)
line 内のヘッダ行が MIME 符号化されたものを返します。

MAXLEN
標準では、非 ASCII 文字 (8 ビット目がセットされている文字) を含む か、MAXLEN 文字 (標準の値は 200 です) よりも長い 部分は quoted-printable 形式で符号化されます。

CHARSET
文字セットがメイルヘッダで指定されていない場合指定しなければ なりません。使われている文字セットを表す文字列は CHARSET に記憶されます。標準の値は ISO-8859-1 (Latin1 (latin-one) としても 知られています)。

このモジュールはコマンドラインから利用することもできます。 以下のような使用法:

mimify.py -e [-l length] [infile [outfile]]
mimify.py -d [-b] [infile [outfile]]
で、それぞれ符号化 (mimify) および復号化 (unmimify) を行います。 標準の設定では infile は標準入力で、putfile は標準出力 です。入出力に同じファイルを指定することもできます。

符号化の際に -l オプションを与えた場合、length で 指定した長さより長い行があれば、その長さに含まれる部分が符号化 されます。

復号化の際に -b オプションが与えられていれば、base64 パート も同様に復号化されます。

参考資料:

quopriモジュール:
MIME quoted-printable 形式ファイルのエンコード およびデコード。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.8.1 MimeWriter オブジェクト Up: 12. インターネット上のデータの操作 Next: 12.10 multifile


12.10 multifile -- 個別の部分を含んだファイル群のサポート

MultiFile オブジェクトはテキストファイルを区分したものを ファイル類似の入力オブジェクトとして扱えるようにし、指定した区切り文字 (delimiter) パタンに遭遇した際に '' が返されるようにします。 このクラスの標準設定は MIME マルチパートメッセージを解釈する上で 便利となるように設計されていますが、サブクラス化を行って幾つかの メソッドを上書きすることで、簡単に汎用目的に対応させることができます。 ます。

class MultiFile( fp[, seekable])
マルチファイル (multi-file) を生成します。このクラスは open() が返すファイルオブジェクトのような、 MultiFile インスタンスが行データを取得するための 入力となるオブジェクトを引数としてインスタンス化を 行わなければなりません。

MultiFile は入力オブジェクトの readline() 、 seek()、および tell() メソッドしか参照せず、 後者の二つのメソッドは個々の MIME パートにランダムアクセスしたい 場合にのみ必要です。MultiFile を seek できないストリーム オブジェクトで使うには、オプションの seekable 引数の値を 偽にしてください; これにより、入力オブジェクトの seek() および tail() メソッドを使わないようになります。

MultiFile の視点から見ると、テキストは三種類の行データ: データ、セクション分割子、終了マーカ、からなることを知っていると 約に立つでしょう。MultiFile は、多重入れ子構造になっている可能性 のある、それぞれが独自のセクション分割子および終了マーカのパターン を持つメッセージパートをサポートするように設計されています。

参考資料:

emailモジュール:
網羅的な電子メイル操作パッケージ; multifile モジュールに取って代わります。.

  • 12.10.1 MultiFile オブジェクト
  • 12.10.2 MultiFile の例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.9 mimify Up: 12. インターネット上のデータの操作 Next: 12.10.1 MultiFile オブジェクト


12.10.1 MultiFile オブジェクト

MultiFile インスタンスには以下のメソッドがあります:

readline( str)
一行データを読みます。その行が (セクション分割子や終了マーカや本物の EOF でない) データの場合、行データを返します。その行がもっとも最近 スタックにプッシュされた境界パターンにマッチした場合、'' を返し、 マッチした内容が終了マーカかそうでないかによって self.last を 1 か 0 に設定します。行がその他のスタックされている境界パターンにマッチ した場合、エラーが送出されます。背後のストリームオブジェクトにおける ファイルの終端に到達した場合、全ての境界がスタックから除去されていない 限りこのメソッドは Error を送出します。

readlines( str)
このパートの残りの全ての行を文字列のリストとして返します。

read( )
次のセクションまでの全ての行を読みます。読んだ内容を単一の (複数行にわたる) 文字列として返します。このメソッドには size 引数をとらないので注意してください！

seek( pos[, whence])
ファイルを seek します。seek する際のインデクスは現在のセクションの 開始位置からの相対位置になります。pis および whence 引数 はファイルの seek における引数と同じように解釈されます。

tell( )
現在のセクションの先頭に対して相対的なファイル位置を返します。

next( )
次のセクションまで行を読み飛ばします (すなわち、セクション分割子 または終了マーカが消費されるまで行データを読みます)。 次のセクションがあった場合には真を、終了マーカが発見された場合 には偽を返します。最も最近スタックにプッシュされた境界パターンを 最有効化します。

is_data( str)
str がデータの場合に真を返し、セクション分割子の可能性がある 場合には偽を返します。このメソッドは行の先頭が (全ての MIME 境界が 持っている) '--' 以外になっているかを調べるように 実装されていますが、導出クラスで上書きできるように宣言されています。

このテストは実際の境界テストにおいて高速性を保つために使われて いるので注意してください; このテストが常に false を返す場合、 テストが失敗するのではなく、単に処理が遅くなるだけです。

push( str)
境界文字列をスタックにプッシュします。この境界文字列の適切に修飾された バージョンが入力ファイル中に見つかった場合、セクション分割子 または終了マーカであると解釈されます。それ以降の全てのデータ読み出し は、pop() を呼んで境界文字列を除去するか、next() を呼んで境界文字列を再有効化しないかぎり、ファイル終端を示す空文字列を 返します。

一つ以上の境界をプッシュすることは可能です。もっとも最近プッシュされた 境界に遭遇すると EOF が返ります; その他の境界に遭遇するとエラーが 送出されます。

pop( )
セクション境界をポップします。この境界はもはや EOF として解釈 されません。

section_divider( str)
境界をセクション分割子にします。標準では、このメソッドは (全ての MIME 境界が持っている) '--' を境界文字列の 先頭に追加しますが、これは導出クラスで上書きできるように宣言 されています。末尾の空白は無視されることから考えて、このメソッド では LF や CR-LF を追加する必要はありません。

end_marker( str)
境界文字列を終了マーカ行にします。標準では、このメソッドは (MIME マルチパートデータのメッセージ終了マーカのように) '--' を境界文字列の先頭に追加し、かつ '--' を境界文字列の末尾に追加しますが、 これは導出クラスで上書きできるように宣言されています。 末尾の空白は無視されることから考えて、このメソッド では LF や CR-LF を追加する必要はありません。

最後に、MultiFile インスタンスは二つの公開されたインスタンス 変数を持っています:

level
現在のパートにおける入れ子の深さです。

last
最後に見つかったファイル終了イベントがメッセージ終了マーカ であった場合に真となります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.10 multifile Up: 12.10 multifile Next: 12.10.2 MultiFile の例


12.10.2 MultiFile の例

import mimetools
import multifile
import StringIO

def extract_mime_part_matching(stream, mimetype):
    """Return the first element in a multipart MIME message on stream
    matching mimetype."""

    msg = mimetools.Message(stream)
    msgtype = msg.gettype()
    params = msg.getplist()

    data = StringIO.StringIO()
    if msgtype[:10] == "multipart/":

        file = multifile.MultiFile(stream)
        file.push(msg.getparam("boundary"))
        while file.next():
            submsg = mimetools.Message(file)
            try:
                data = StringIO.StringIO()
                mimetools.decode(file, data, submsg.getencoding())
            except ValueError:
                continue
            if submsg.gettype() == mimetype:
                break
        file.pop()
    return data.getvalue()
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.10.1 MultiFile オブジェクト Up: 12.10 multifile Next: 12.11 rfc822


12.11 rfc822 -- RFC 2822 準拠のメイルヘッダ読み出し

リリース 2.3 以降で撤廃された仕様です。 rfc822 モジュールを使うよりも email パッケージを使うべきです。このモジュールは 以前のバージョンとの互換性のために保守されているにすぎません。

このモジュールでは、インターネット標準 RFC 2822 12.10で定義されている ``電子メイルメッセージ'' を表現するクラス、 Message を定義しています。 このメッセージはメッセージヘッダ群とメッセージボディの集まり からなります。このモジュールではまた、ヘルパークラス RFC 2822 アドレス群を解釈するための AddressList クラス を定義しています。RFC 2822 メッセージ固有の構文に関する情報 は RFC を参照してください。

mailboxモジュールでは、 多くのエンドユーザメイルプログラムによって生成されるメイルボックス を読み出すためのクラスを提供しています。

class Message( file[, seekable])
Message インスタンスは入力オブジェクトをパラメタに与えて インスタンス化します。入力オブジェクトのメソッドのうち、Message が 依存するのは readline() だけです; 通常のファイル オブジェクトは適格です。インスタンス化を行うと、入力オブジェクト からデリミタ行 (通常は空行 1 行) に到達するまでヘッダを読み出し、 それらをインスタンス中に保持します。ヘッダの後のメッセージ本体は 読み出しません。

このクラスは readline() メソッドをサポートする任意の入力 オブジェクトを扱うことができます。入力オブジェクトが seek および tell できる場合、 rewindbody() メソッドが動作します。 また、不正な行データを入力ストリームにプッシュバックできます。 入力オブジェクトが seek できない一方で、入力行をプッシュバックする unread() メソッドを持っている場合、Message は不正な行データにこのプッシュバックを使います。こうして、 このクラスはバッファされているストリームから来るメッセージを 解釈するのに使うことができます。

オプションの seekable 引数は、lseek() システムコール が動作しないと分かるまでは tell() がバッファされたデータを 無視するような、ある種の stdio ライブラリで回避手段として提供されています。 可搬性を最大にするために、socket オブジェクトによって生成されたファイル のような、seek できないオブジェクトを渡す際には、最初に tell() が呼び出されないようにするために seekable 引数をゼロに設定すべきです。

ファイルとして読み出された入力行データは CR-LF と単一の改行 (line feed) のどちらで終端されていてもかまいません; 行データを記憶する前に、終端の CR-LF は単一の改行と置き換えられます。

ヘッダに対するマッチは全て大小文字に依存しません。例えば、 m['From']、 m['from']、および m['FROM'] は全て同じ結果になります。

class AddressList( field)
RFC 2833 アドレスをカンマで区切ったものとして解釈される 単一の文字列パラメタを使って、AddressList ヘルパークラスを インスタンス化することができます。 (パラメタ None は空のリストを表します。)

quote( str)
str 中のバックスラッシュが 2 つのバックスラッシュに置き換えられ、 二重引用符がバックスラッシュ付きの二重引用符に置き換えられた、 新たな文字列を返します。

unquote( str)
str の 逆クオートされた 新たな文字列を返します。 str が二重引用符で囲われていた場合、二重引用符を剥ぎ取ります。 同様に、 str が三角括弧で囲われていた場合にも剥ぎ取ります。

parseaddr( address)
To: や Cc: といった、アドレスが入っている フィールドの値 address を解析し、含まれている ``実名 (realname)'' 部分および ``電子メールアドレス'' 部分に分けます。それらの情報からなる タプルを返します。解析が失敗した場合には 2 要素のタプル (None, None) を返します。

dump_address_pair( pair)
parseaddr() の逆で、(realname, email_address) 形式の 2 要素のタプルをとり、To: や Cc: ヘッダに 適した文字列値を返します。pair の最初の要素が真値をとらない 場合、二つ目の要素をそのまま返します。

parsedate( date)
RFC 2822 の規則に従っている日付を解析しようと試みます。 しかしながら、メイラによっては RFC 2822 で指定されている ような書式に従わないため、そのような場合には parsedata() は正しい日付を推測しようと試みます。 date は 'Mon, 20 Nov 1995 19:12:08 -0500' のような RFC 2822 様式の日付を収めた文字列です。日付の解析に成功した場合、 parsedate() は time.mktime() にそのまま渡す ことができるような 9 要素のタプルを返します; そうでない場合には None を返します。結果のフィールド 6、7、および 8 は 有用な情報ではありません。

parsedate_tz( date)
parsedate() と同じ機能を実現しますが、None または 10 要素のタプルを返します; 最初の 9 要素は time.mktime() に直接渡すことができるようなタプルで、 10 番目の要素はその日の タイムゾーンにおける UTC (グリニッチ標準時の公式名称) からの オフセットです。(タイムゾーンオフセットの符号は、 同じタイムゾーンにおける time.timezone 変数の符号と反転 しています; 後者の変数が POSIX 標準に従っている一方、 このモジュールは RFC 2822 に従っているからです。) 入力文字列 がタイムゾーン情報を持たない場合、タプルの最後の要素は None になります。結果のフィールド 6、7、および 8 は 有用な情報ではありません。

mktime_tz( tuple)
parsedata_tz() が返す 10 要素のタプルを UTC タイムスタンプ に変換します。タプル内のタイムゾーン要素が None の場合、地域の 時刻を表しているものと家庭します。些細な欠陥: この関数はまず最初の 8 要素を地域における時刻として変換し、次にタイムゾーンの違いに対する 補償を行います; これにより、夏時間の切り替え日前後でちょっとした エラーが生じるかもしれません。通常の利用に関しては心配ありません。

参考資料:

emailモジュール:
網羅的な電子メイル処理パッケージです; rfc822 モジュールを代替します。.
mailboxモジュール:
エンドユーザのメイルプログラムによって生成される、様々な mailbox 形式を読み出すためのクラス群。.
mimetoolsモジュール:
MIME エンコードされたメッセージを処理する rfc822.Message のサブクラス。.

...2822 12.10
このモジュールはもともと RFC 822 に適合していたので、そういう名前に なっています。その後、RFC 2822 が RFC 822 に対する更新として リリースされました。このモジュールは RFC 2822 適合であり、特に RFC 822 からの構文や意味付けに対する変更がなされています。

  • 12.11.1 Message オブジェクト
  • 12.11.2 AddressList オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.10.2 MultiFile の例 Up: 12. インターネット上のデータの操作 Next: 12.11.1 Message オブジェクト


12.11.1 Message オブジェクト

Message インスタンスは以下のメソッドを持っています:

rewindbody( )
メッセージ本体の先頭を seek します。このメソッドはファイルオブジェクト が seek 可能である場合にのみ動作します。

isheader( line)
ある行が正しい RFC 2822 ヘッダである場合、その行の正規化された フィールド名 (インデクス指定の際に使われる辞書キー) を返します; そうでない場合 None を返します (解析をここで一度中断し、 行データを入力ストリームに押し戻すことを意味します)。 このメソッドをサブクラスで上書きすると便利なことがあります。

islast( line)
与えられた line が Message の区切りとなるデリミタであった場合に真を 返します。このデリミタ行は消費され、ファイルオブジェクトの読み位置は その直後になります。標準ではこのメソッドは単にその行が空行かどうか をチェックしますが、サブクラスで上書きすることもできます。

iscomment( line)
与えられた行全体を無視し、単に読み飛ばすときに真を返します。 標準では、これは控えメソッド (stub) であり、常に False を返し ますが、サブクラスで上書きすることもできます。

getallmatchingheaders( name)
name に一致するヘッダからなる行のリストがあれば、それらを 全て返します。各物理行は連続した行内容であるか否かに関わらず 別々のリスト要素になります。name に一致するヘッダがない場合、 空のリストを返します。

getfirstmatchingheader( name)
name に一致する最初のヘッダと、その行に連続する (複数) 行からなる行データのリストを返します。 name に一致するヘッダがない場合 None を返します。

getrawheader( name)
name に一致する最初のヘッダにおけるコロン以降のテキストが入った 単一の文字列を返します。このテキストには、先頭の空白、末尾の改行、 また後続の行がある場合には途中の改行と空白が含まれます。 name に一致するヘッダが存在しない場合には None を返します。

getheader( name[, default])
getrawheader(name) に似ていますが、先頭および末尾の 空白を剥ぎ取ります。途中にある空白は剥ぎ取られません。 オプションの default 引数は、name に一致する ヘッダが存在しない場合に、別のデフォルト値を返すように指定する ために使われます。

get( name[, default])
正規の辞書との互換性をより高めるための getheader() の別名 (alias) です。

getaddr( name)
getheader(name) が返した文字列を解析して、 (full name, email address) からなるペアを返します。 name に一致するヘッダが無い場合、(None, None) が返され ます; そうでない場合、full name および address は (空文字列をとりうる) 文字列になります。

例: m に最初の From: ヘッダに文字列 'jack@cwi.nl (Jack Jansen)' が入っている場合、 m.getaddr('From') はペア ('Jack Jansen', 'jack@cwi.nl') になります。 また、'Jack Jansen <jack@cwi.nl>' であっても、全く同じ結果に なります。

getaddrlist( name)
getaddr(list) に似ていますが、複数のメイルアドレス からなるリストが入ったヘッダ (例えば To: ヘッダ) を 解析し、 (full name, email address) のペア からなるリストを (たとえヘッダには一つしかアドレスが入っていなかった としても) 返します。name に一致するヘッダが無かった場合、 空のリストを返します。

指定された名前に一致する複数のヘッダが存在する場合 (例えば、 複数の Cc: ヘッダが存在する場合)、全てのアドレスを 解析します。指定されたヘッダが連続する行に収められている場合も 解析されます。

getdate( name)
getheader() を使ってヘッダを取得して解析し、 time.mktime() と互換な 9 要素のタプルにします; フィールド 6、7、および 8 は有用な値ではないので注意して下さい。 name に一致するヘッダが存在しなかったり、ヘッダが解析不能 であった場合、None を返します。

日付の解析は妖術のようなものであり、全てのヘッダが標準に従って いるとは限りません。このメソッドは多くの発信源から集められた 膨大な数の電子メールでテストされており、正しく動作することが 分かっていますが、間違った結果を出力してしまう可能性はまだ あります。

getdate_tz( name)
getheader() を使ってヘッダを取得して解析し、10 要素の タプルにします; 最初の 9 要素は time.mktime() と 互換性のあるタプルを形成し、10 番目の要素はその日におけるタイムゾーン の UTC からのオフセットを与える数字になります。getdate() と同様に、name に一致するヘッダがなかったり、解析不能であった 場合、None を返します。

Message インスタンスはまた、限定的なマップ型のインタフェースを 持っています。 すなわち: m[name] は m.getheader(name) に似て いますが、一致するヘッダがない場合 KeyError を送出します; len(m)、 m.get(name[, default])、 m.has_key(name), m.keys()、 m.values() m.items()、および m.setdefault(name[, default]) は期待通りに動作します。ただし setdefault() は標準の設定値 として空文字列をとります。 Message インスタンスはまた、 マップ型への書き込みを行えるインタフェース m[name] = value および del m[name] をサポートしています。 Message オブジェクトでは、 clear()、 copy()、 popitem()、あるいは update() といったマップ型 インタフェースのメソッドはサポートしていません。 (get() および setdefault() のサポートは Python 2.2 でしか追加されていません。)

最後に、Message インスタンスはいくつかの public なインスタンス 変数を持っています:

headers
ヘッダ行のセット全体が、(setitem を呼び出して変更されない限り) 読み出された順番に入れられたリストです。各行は末尾の改行を 含んでいます。ヘッダを終端する空行はリストに含まれません。

fp
インスタンス化の際に渡されたファイルまたはファイル類似オブジェクトです。 この値はメッセージ本体を読み出すために使うことができます。

unixfrom
メッセージに Unix "From " 行がある場合はその行、そうでなければ 空文字列になります。この値は例えば mbox 形式のメイルボックス ファイルのような、あるコンテキスト中のメッセージを再生成するために 必要です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.11 rfc822 Up: 12.11 rfc822 Next: 12.11.2 AddressList オブジェクト


12.11.2 AddressList オブジェクト

AddressList インスタンスは以下のメソッドを持ちます:

__len__( )
アドレスリスト中のアドレスの数を返します。

__str__( )
アドレスリストの正規化 (canonicalize) された文字列表現を返します。 アドレスはカンマで分割された "name" <host@domain> 形式になります。

__add__( alist)
二つの AddressList 被演算子中の双方に含まれるアドレスに ついて、重複を除いた (集合和の) 全てのアドレスを含む新たな AddressList インスタンスを返します。

__iadd__( alist)
__add__() のインプレース演算版です; AddressList インスタンスと右側値 alist との集合和をとり、その結果を インスタンス自体と置き換えます。

__sub__( alist)
左側値のAddressList インスタンスのアドレスのうち、 右側値中に含まれていないもの全てを含む (集合差分の) 新たな AddressList インスタンスを返します。

__isub__( alist)
__sub__() のインプレース演算版で、alist にも 含まれているアドレスを削除します。

最後に、AddressList インスタンスは public なインスタンス変数 を一つ持ちます:

addresslist
アドレスあたり一つの文字列ペアで構成されるタプルからなるリストです。 各メンバ中では、最初の要素は正規化された名前部分で、二つ目は 実際の配送アドレス ("@" で分割されたユーザ名 と ホスト.ドメインからなるペア) です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.11.1 Message オブジェクト Up: 12.11 rfc822 Next: 12.12 base64


12.12 base64 -- MIME base64 形式データのエンコードおよびデコード

このモジュールは任意のバイナリ文字列を(eメールやHTTPのPOSTリクエストの一 部としてで安全に送ることのできるテキスト文字列に変換する)base64形式へエンコー ドおよびデコードする機能を提供します。 エンコードの概要はRFC 1521(MIME(Multipurpose Internet Mail Extensions)Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies, section 5.2, ``Base64 Content-Transfer-Encoding'')で定義されていて、 MIME形式のeメールやインターネットのさまざまな場面で利用されています。 この形式はuuencodeプログラムによる出力とは違うものです。 たとえば、'www.python.org'は、 'd3d3LnB5dGhvbi5vcmc=\n'とエンコードされます。

decode( input, output)
inputの中身をデコードした結果をoutputに出力します。 input、outputともにファイルオブジェクトか、ファイルオブジェ クトと同じインターフェースを持ったオブジェクトである必要があります。 inputは%codeinput.read()が空文字列を返すまで読まれます。

decodestring( s)
文字列sをデコードして結果のバイナリデータを返します。 sには一行以上のbase64形式でエンコードされたデータが含まれている必 要があります。

encode( input, output)
inputの中身をbase64形式でエンコードした結果をoutputに出力します。 input、outputともにファイルオブジェクトか、ファイルオブジェ クトと同じインターフェースを持ったオブジェクトである必要があります。 inputは%codeinput.read()が空文字列を返すまで読まれます。 encode()はエンコードされたデータと改行文字('\n')を出 力します。

encodestring( s)
文字列s(任意のバイナリデータを含むことができます)を base64形式でエンコードした結果の(1行以上の文字列)データを返します。 encodestring()はエンコードされた一行以上のデータと改行文字 ('\n')を出力します。

参考資料:

binasciiモジュール:
ASCII からバイナリへ、バイナリからASCIIへの 変換をサポートするモジュール。.
RFC 1521, MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies
Section 5.2, ``Base64 Content-Transfer-Encoding,'' provides the definition of the base64 encoding.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.11.2 AddressList オブジェクト Up: 12. インターネット上のデータの操作 Next: 12.13 binascii


12.13 binascii -- バイナリデータと ASCIIデータとの間での変換

binascii モジュールにはバイナリと ASCIIコード化された バイナリ表現との間の変換を行うための多数のメソッドが含まれています。 通常、これらの関数を直接使う必要はなく、 uuや binhexといった、ラッパ(wrapper) モジュールを使うことになるでしょう。このモジュールが独立して存在 するのは、Python において大量のデータに対するビット操作が低速 であるという理由からです。

binascii モジュールでは以下の関数を定義します:

a2b_uu( string)
uuencode された 1 行のデータ をバイナリに変換し、変換後のバイナリ データを返します。最後の行を除いて、通常 1 行には(バイナリデータで) 45 バイトが含まれます。入力データの先頭には空白文字が連続していても かまいません。

b2a_uu( data)
バイナリデータを uuencode して 1 行の ASCII 文字列に変換します。 戻り値は変換後の 1 行の文字列で、改行を含みます。data の長さは 45 バイト以下でなければなりません。

a2b_base64( string)
base64 でエンコードされたデータのブロックをバイナリに変換し、 変換後のバイナリデータを返します。一度に 1 行以上のデータを 与えてもかまいません。

b2a_base64( data)
バイナリデータを base64 でエンコードして 1 行の ASCII 文字列に 変換します。戻り値は変換後の 1 行の文字列で、改行文字を含みます。 base64 標準を遵守するためには、data の長さは 57 バイト以下で なくてはなりません。

a2b_qp( string[, header])
quoted-printable 形式のデータをバイナリに変換し、バイナリデータを 返します。一度に 1 行以上のデータを渡すことができます。 オプション引数 header が与えられており、かつその値が真であれば、 アンダースコアは空白文字にデコードされます。

b2a_qp( data[, quotetabs, istext, header])
バイナリデータを quoted-printable 形式でエンコードして 1 行から複数行の ASCII 文字列に変換します。変換後の文字列を返します。 オプション引数 quptetabs が存在し、かつその値が真であれば、 全てのタブおよび空白文字もエンコードされます。オプション引数 header が存在し、かつその値が真であれば、空白文字は RFC1522 に従ってアンダースコアにエンコードされます。オプション引数 header が存在し、かつその値が偽である場合、改行文字も同様にエンコードされます。 そうでない場合、復帰 (linefeed) 文字の変換によってバイナリデータ ストリームが破損してしまうかもしれません。

a2b_hqx( string)
binhex4 形式の ASCII 文字列データを RLE 展開を行わないでバイナリに 変換します。文字列はバイナリのバイトデータを完全に含むような長さか、 または (binhex4 データの最後の部分の場合) 余白のビットがゼロになって いなければなりません。

rledecode_hqx( data)
data に対し、binhex4 標準に従って RLE 展開を行います。 このアルゴリズムでは、あるバイトの後ろに 0x90 がきた場合、 そのバイトの反復を指示しており、さらにその後ろに反復カウントが 続きます。カウントが 0 の場合 0x90 自体を示します。 このルーチンは入力データの末端における反復指定が不完全でない かぎり解凍されたデータを返しますが、不完全な場合、例外 Incomplete が送出されます。

rlecode_hqx( data)
binhex4 方式の RLE 圧縮を data に対して行い、その結果を 返します。

b2a_hqx( data)
バイナリを hexbin4 エンコードして ASCII 文字列に変換し、変換後の 文字列を返します。引数の data はすでに RLE エンコードされて いなければならず、その長さは (最後のフラグメントを除いて) 3 で 割り切れなければなりません。

crc_hqx( data, crc)
data の binhex4 CRC 値を計算します。初期値は crc で、計算 結果を返します。

crc32( data[, crc])
32 ビットチェックサムである CRC-32 を data に対して計算します。 初期値は crc です。これは ZIP ファイルのチェックサムと同じです。 このアルゴリズムはチェックサムアルゴリズムとして設計されたもので、 一般的なハッシュアルゴリズムには向きません。以下のようにして使います:
    print binascii.crc32("hello world")
    # Or, in two pieces:
    crc = binascii.crc32("hello")
    crc = binascii.crc32(" world", crc)
    print crc

b2a_hex( data)
hexlify( data)
バイナリデータ data の16進数表現を返します。data の各 バイトは対応する 2 桁の16進数表現に変換されます。従って、変換結果の 文字列はdata の 2 倍の長さになります。

a2b_hex( hexstr)
unhexlify( hexstr)
16 進数表記の文字列 hexstr の表すバイナリデータを返します。 この関数は b2a_hex() の逆です。hexstr は 16進数字 (大文字でも小文字でもかまいません) を偶数個含んでいなければ なりません。そうでないばあい、例外 TypeError が送出 されます。

exception Error
エラーが発生した際に送出される例外です。通常はプログラムのエラーです。

exception Incomplete
変換するデータが不完全な場合に送出される例外です。通常はプログラムの エラーではなく、多少追加読み込みを行って再度変換 を試みることで対処できます。

参考資料:

base64モジュール:
MIME 電子メールメッセージで使われる base64 エンコードのサポート。.

binhexモジュール:
Machintosh で使われる binhex フォーマットのサポート。.

uuモジュール:
Unixで使われる UU エンコードのサポート。.

quopriモジュール:
MIME 電子メールメッセージで使われる quoted-printable エンコードのサポート。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.12 base64 Up: 12. インターネット上のデータの操作 Next: 12.14 binhex


12.14 binhex -- binhex4 形式ファイルのエンコードおよびデコード

このモジュールは binhex4 形式のファイルに対するエンコードやデコード を行います。binhex4 は Macintosh のファイルを ASCIIで表現できる ようにしたものです。Macintosh 上では、ファイルと finder 情報の両方 のフォークがエンコード (またはデコード) されます。他のプラットフォーム ではデータフォークだけが処理されます。

binhex モジュールでは以下の関数を定義しています:

binhex( input, output)
ファイル名 input のバイナリファイルをファイル名 output の binhex 形式ファイルに変換します。output パラメタはファイル名 でも (write() および close() メソッドをサポートする ような)ファイル様オブジェクトでもかまいません。

hexbin( input[, output])
binhex 形式のファイル input をデコードします。input は ファイル名でも、write() および close() メソッドを サポートするようなファイル様オブジェクトでもかまいません。変換結果 のファイルはファイル名 output になります。この引数が省略された 場合、出力ファイルは binhex ファイルの中から復元されます。

以下の例外も定義されています:

exception Error
binhex 形式を使ってエンコードできなかった場合 (例えば、ファイル名 が filename フィールドに収まらないくらい長かった場合など) や、入力 が正しくエンコードされた binhex 形式のデータでなかった場合に送出 される例外です。

参考資料:

binasciiモジュール:
ASCIIからバイナリ、およびバイナリからASCII への変換をサポートするモジュール。.

  • 12.14.1 注記
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.13 binascii Up: 12. インターネット上のデータの操作 Next: 12.14.1 注記


12.14.1 注記

別のより強力なエンコーダおよびデコーダへのインタフェースが存在します。 詳しくはソースを参照してください。

非 Macintosh プラットフォームでテキストファイルをエンコードしたり デコードしたりする場合でも、Macintosh の改行文字変換 (行末をキヤリッジ リターンとする) が行われます。

このドキュメントを書いている時点では、hexbin() はいつも正しく 動作するわけではないようです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.14 binhex Up: 12.14 binhex Next: 12.15 quopri


12.15 quopri -- MIME quoted-printable 形式データのエンコードおよびデコード

このモジュールは RFC 1521: ``MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies'' で定義されている quoted-printable による伝送のエンコードおよびデコードを行います。 quoted-printable 円コーディングは比較的印字不可能な文字の少ないデータのために設計 されています; 画像ファイルを送るときのように印字不可能な文字がたくさんある 場合には、base64 モジュールで利用できる base64 エンコーディングのほうがよりコンパクトになります。

decode( input, output[,header])
ファイル input の内容をデコードして、デコードされたバイナリ データを ファイル output に書き出します。 input および output はファイルか、ファイルオブジェクトの インタフェースを真似たオブジェクトでなければなりません。 input は input.readline() が空文字列を返すまで 読みつづけられます。オプション引数 header が存在し、かつその 値が真である場合、アンダースコアは空白文字にデコードされます。 これは RFC 1522: ``MIME (Multipurpose Internet Mail Extensions) Part Two: Message Header Extensions for Non-ASCII Text'' で記述されているところの ``Q''-エンコードされたヘッダをデコードするの に使われます。

encode( input, output, quotetabs)
ファイル input の内容をエンコードして、quoted-printable 形式に エンコードされたデータをファイル output に書き出します。 input および output はファイルか、ファイルオブジェクトの インタフェースを真似たオブジェクトでなければなりません。 input は input.readline() が空文字列を返すまで 読みつづけられます。 quotetabs はデータ中に埋め込まれた空白文字やタブを変換するか どうか制御するフラグです; この値が真なら、それらの空白をエンコード します。偽ならエンコードせずそのままにしておきます。行末のスペースや タブは RFC 1521 に従って常に変換されるので注意してください。

decodestring( s[,header])
decode() に似ていますが、文字列を入力として受け取り、 デコードされた文字列を返します。

encodestring( s[, quotetabs])
encode() に似ていますが、文字列を入力として受け取り、 エンコードされた文字列を返します。quotetabs はオプション (デフォルトは 0 です) で、この値はそのままencode() に 渡されます。

参考資料:

mimifyモジュール:
MIME メッセージを処理するための汎用ユーティリティ。.
base64モジュール:
MIME base64 形式データのエンコードおよびデコード.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.14.1 注記 Up: 12. インターネット上のデータの操作 Next: 12.16 uu


12.16 uu -- uuencode形式のエンコードとデコード

このモジュールではファイルをuuencode形式(任意のバイナリデータをASCII文字列 に変換したもの)にエンコード、デコードする機能を提供します。 引数としてファイルが仮定されている所では、ファイルのようなオブジェクトが 利用できます。後方互換性のために、パス名を含む文字列も利用できるようにし ていて、対応するファイルを開いて読み書きします。しかし、このインターフェー スは利用しないでください。呼び出し側でファイルを開いて(Windowsでは 'rb'か'wb'のモードで)利用する方法が推奨されます。

このコードはLance Ellinghouseによって提供され、Jack Jansenによって更新さ れました。

uuモジュールでは以下の関数を定義しています。

encode( in_file, out_file[, name[, mode]])
in_fileをout_fileにエンコードします。 エンコードされたファイルには、デフォルトでデコード時に利用される nameとmodeを含んだヘッダがつきます。省略された場合には、 in_fileから取得された名前か'-' という文字と、0666 がそれぞれデフォルト値として与えられます。

decode( in_file[, out_file[, mode]])
uuencode形式でエンコードされたin_fileをデコードして varout_fileに書き出します。もしout_fileがパス名でかつファイルを 作る必要があるときには、 modeがパーミッションの設定に使われます。 out_fileとmodeのデフォルト値はin_fileのヘッダから取得 されます。しかし、ヘッダで指定されたファイルが既に存在していた場合は、 uu.Errorが起きます。

exception Error( )
Exceptionのサブクラスで、uu.decode()によって、さ まざまな状況で起きる可能性があります。上で紹介された場合以外にも、ヘッダ のフォーマットが間違っている場合や、入力ファイルが途中で区切れた場合に も起きます。

参考資料:

binasciiモジュール:
ASCII からバイナリへ、バイナリからASCIIへの 変換をサポートするモジュール。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.15 quopri Up: 12. インターネット上のデータの操作 Next: 12.17 xdrlib


12.17 xdrlib -- XDR データのエンコードおよびデコード

xdrlib モジュールは外部データ表現標準 (External Data Representation Standard) のサポートを実現します。この標準は 1987 年に Sun Microsystems, Inc. によって書かれ、 RFC 1014 で定義されています。このモジュールでは RFC で記述されている ほとんどのデータ型をサポートしています。

xdrlib モジュールでは 2 つのクラスが定義されています。 一つは変数を XDR 表現にパックするためのクラスで、もう一方は XDR 表現からアンパックするためのものです。2 つの例外クラスが 同様にして定義されています。

class Packer( )
Packer はデータを XDR 表現にパックするためのクラスです。 Packer クラスのインスタンス生成は引数なしで行われます。

class Unpacker( data)
Unpacker は Packer と対をなしていて、文字列バッファから XDR をアンパックするためのクラスです。入力バッファ data を引数に与えてインスタンスを生成します。

参考資料:

RFC 1014, XDR: External Data Representation Standard
この RFC が、かつてこのモジュールが最初に書かれた当時に XDR 標準でであったデータのエンコード方法を定義していました。 現在は RFC 1832 に更新されているようです。

RFC 1832, XDR: External Data Representation Standard
こちらが 新しい方のRFCで、XDR の改訂版が定義されています。

  • 12.17.1 Packer オブジェクト
  • 12.17.2 Unpacker オブジェクト
  • 12.17.3 例外
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.16 uu Up: 12. インターネット上のデータの操作 Next: 12.17.1 Packer オブジェクト


12.17.1 Packer オブジェクト

Packer インスタンスには以下のメソッドがあります:

get_buffer( )
現在のパック処理用バッファを文字列で返します。

reset( )
パック処理用バッファをリセットして、空文字にします。

一般的には、適切な pack_type() メソッドを使えば、 一般に用いられているほとんどの XDR データをパックすることができます。 各々のメソッドは一つの引数をとり、パックしたい値を与えます。 単純なデータ型をパックするメソッドとして、以下のメソッド: pack_uint() 、pack_int() 、 pack_enum() 、 pack_bool() 、pack_uhyper() そして pack_hyper() がサポートされています。

pack_float( value)
単精度 (single-precision) の浮動小数点数 value をパックします。

pack_double( value)
倍精度 (double-precision) の浮動小数点数 value をパックします。

以下のメソッドは文字列、バイト列、不透明データ (opaque data) のパック 処理をサポートします:

pack_fstring( n, s)
固定長の文字列、s をパックします。 n は文字列の長さ ですが、この値自体はデータバッファにはパック されません 。 4 バイトのアラインメントを保証するために、文字列は必要に応じて null バイト列でパディングされます。

pack_fopaque( n, data)
pack_fstring() と同じく、固定長の不透明データストリームを パックします。

pack_string( s)
可変長の文字列 s をパックします。文字列の長さが最初に符号なし 整数でパックされ、続いて pack_fstring() を使って文字列データが パックされます。

pack_opaque( data)
pack_string() と同じく、可変長の不透明データ文字列をパックします。

pack_bytes( bytes)
pack_string() と同じく、可変長のバイトストリームをパックします。

以下のメソッドはアレイやリストのパック処理をサポートします:

pack_list( list, pack_item)
一様な項目からなる list をパックします。このメソッドは サイズ不定、すなわち、全てのリスト内容を網羅するまでサイズが 分からないリストに対して有用です。リストのすべての項目に対し、 最初に符号無し整数 1 がパックされ、続いてリスト中の データがパックされます。pack_item は個々の項目をパック するために呼び出される関数です。リストの末端に到達すると、 符号無し整数 0 がパックされます。

例えば、整数のリストをパックするには、コードは以下のようになるはず です:

import xdrlib
p = xdrlib.Packer()
p.pack_list([1, 2, 3], p.pack_int)

pack_farray( n, array, pack_item)
一様な項目からなる固定長のリスト (array) をパックします。 n はリストの長さです。この値はデータバッファにパック されません が、len(array) が n と 等しくない場合、例外 ValueError が送出されます。 上と同様に、pack_item は個々の要素をパック処理するための 関数です。

pack_array( list, pack_item)
一様の項目からなる可変長の list をパックします。 まず、リストの長さが符号無し整数でパックされ、つづいて各 要素が上の pack_farray() と同じやり方でパックされます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.17 xdrlib Up: 12.17 xdrlib Next: 12.17.2 Unpacker オブジェクト


12.17.2 Unpacker オブジェクト

Unpacker クラスは以下のメソッドを提供します:

reset( data)
文字列バッファを data でリセットします。

get_position( )
データバッファ中の現在のアンパック処理位置を返します。

set_position( position)
データバッファ中のアンパック処理位置を position に設定します。 get_position() および set_position() は注意して 使わなければなりません。

get_buffer( )
現在のアンパック処理用データバッファを文字列で返します。

done( )
アンパック処理を終了させます。全てのデータがまだアンパックされて いなければ、例外 Error が送出されます。

上のメソッドに加えて、Packer でパック処理できるデータ型はいずれも Unpacker でアンパック処理できます。アンパック処理メソッドは unpack_type() の形式をとり、引数をとりません。 これらのメソッドはアンパックされたデータオブジェクトを返します。

unpack_float( )
単精度の浮動小数点数をアンパックします。

unpack_double( )
unpack_float() と同様に、倍精度の浮動小数点数をアンパックします。

上のメソッドに加えて、文字列、バイト列、不透明データをアンパックする 以下のメソッドが提供されています:

unpack_fstring( n)
固定長の文字列をアンパックして返します。n は予想される文字列の 長さです。4 バイトのアラインメントを保証するために null バイトによる パディングが行われているものと仮定して処理を行います。

unpack_fopaque( n)
unpack_fstring() と同様に、固定長の不透明データストリームを アンパックして返します。

unpack_string( )
可変長の文字列をアンパックして返します。最初に文字列の長さが符号無し 整数としてアンパックされ、次に unpack_fstring() を使って 文字列データがアンパックされます。

unpack_opaque( )
unpack_string() と同様に、可変長の不透明データ文字列をアンパック して返します。

unpack_bytes( )
unpack_string() と同様に、可変長のバイトストリームをアンパック して返します。

以下メソッドはアレイおよびリストのアンパック処理をサポートします。

unpack_list( unpack_item)
一様な項目からなるリストをアンパック処理してかえします。リストは 一度に 1 要素づつアンパック処理されます、まず符号無し整数によるフラグ がアンパックされます。もしフラグが 1 なら、要素はアンパックされ、 返り値のリストに追加されます。フラグが 0 であれば、リストの終端 を示します。 unpack_item は個々の項目をアンパック処理するために 呼び出される関数です。

unpack_farray( n, unpack_item)
一様な項目からなる固定長のアレイをアンパックして（リストとして）返します。 n はバッファ内に存在すると期待されるリストの要素数です。 上と同様に、 unpack_item は各要素をアンパックするために使われる 関数です。

unpack_array( unpack_item)
一様な項目からなる可変長の list をアンパックして返します。 まず、リストの長さが符号無し整数としてアンパックされ、続いて各要素が 上の unpack_farray() のようにしてアンパック処理されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.17.1 Packer オブジェクト Up: 12.17 xdrlib Next: 12.17.3 例外


12.17.3 例外

このモジュールでの例外はクラスインスタンスとしてコード されています:

exception Error
ベースとなる例外クラスです。Error public なデータメンバ として msg を持ち、エラーの詳細が収められています。

exception ConversionError
Error から導出されたクラスです。インスタンス変数は塚されて いません。

これらの例外を補足する方法を以下の例に示します:

import xdrlib
p = xdrlib.Packer()
try:
    p.pack_double(8.01)
except xdrlib.ConversionError, instance:
    print 'packing the double failed:', instance.msg

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.17.2 Unpacker オブジェクト Up: 12.17 xdrlib Next: 12.18 netrc


12.18 netrc -- netrc ファイルの処理

バージョン1.5.2 以降で新規追加された 仕様です。

netrc クラスは、Unix ftp プログラムや他の FTP クライアントで用いられる netrc ファイル形式を解析し、カプセル化 (encapsulate) します。

class netrc( [file])
netrc のインスタンスやサブクラスのインスタンスは netrc ファイルのデータをカプセル化します。初期化の際の引数が存在する 場合、解析対象となるファイルの指定になります。引数がない場合、 ユーザのホームディレクトリ下にある .netrc が読み出されます。 解析エラーが発生した場合、ファイル名、行番号、解析を中断したトークン に関する情報の入った NetrcParseError を送出します。

exception NetrcParseError
ソースファイルのテキスト中で文法エラーに遭遇した場合に netrc クラスによって送出される例外です。この例外のインスタンスは 3 つの インスタンス変数を持っています: msg はテキストによる エラーの説明で、filename はソースファイルの名前、 そして lineno はエラーが発見された行番号です。

  • 12.18.1 netrc オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.17.3 例外 Up: 12. インターネット上のデータの操作 Next: 12.18.1 netrc オブジェクト


12.18.1 netrc オブジェクト

netrc インスタンスは以下のメソッドを持っています:

authenticators( host)
host の認証情報として、三要素のタプル (login, account, password) を返します。 与えられた host に対するエントリが netrc ファイルにない場合、 `default' エントリに関連付けられたタプルが返されます。 host に対応するエントリがなく、default エントリもない場合、 None を返します。

__repr__( )
クラスの持っているデータを netrc ファイルの書式に従った文字列で 出力します。(コメントは無視され、エントリが並べ替えられる可能性 があります。)

netrc のインスタンスは以下の公開されたインスタンス変数 を持っています:

hosts
ホスト名を (login, account, password) から なるタプルに対応づけている辞書です。`default' エントリがある場合、 その名前の擬似ホスト名として表現されます。

macros
マクロ名を文字列のリストに対応付けている辞書です。

+ 注意: Passwords are limited to a subset of the ASCII character set. + Versions of this module prior to 2.3 were extremely limited. Starting with + 2.3, all ASCII punctuation is allowed in passwords. However, note that + whitespace and non-printable characters are not allowed in passwords. This + is a limitation of the way the .netrc file is parsed and may be removed in + the future. 注意: 利用可能なパスワードの文字セットは、ASCIIのサブセットのみです。2.3より前の バージョンでは厳しく制限されていましたが、2.3以降ではASCIIの記号を使用することが できます。しかし、空白文字と印刷不可文字を使用することはできません。この制限は .netrcファイルの解析方法によるものであり、将来解除されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.18 netrc Up: 12.18 netrc Next: 12.19 robotparser


12.19 robotparser -- robots.txt のためのパーザ

このモジュールでは単一のクラス、RobotFileParser を提供します。 このクラスは、特定のユーザエージェントが robots.txt ファイルを 公開している Web サイトのある URL を取得可能かどうかの質問に答えます。 robots.txt ファイルの構造に関する詳細は http://www.robotstxt.org/wc/norobots.htmlを参照してください。

class RobotFileParser( )

このクラスでは単一の robots.txt ファイルを読み出し、解釈し、 ファイルの内容に関する質問の回答を得るためのメソッドを定義しています。

set_url( url)
robots.txt ファイルを参照するための URL を設定します。

read( )
robots.txt URL を読み出し、パーザに入力します。

parse( lines)
引数 lines の内容を解釈します。

can_fetch( useragent, url)
解釈された robots.txt ファイル中に記載された規則に従ったとき、 useragent が url を取得してもよい場合には True を 返します。

mtime( )
robots.txt ファイルを最後に取得した時刻を返します。この 値は、定期的に新たな robots.txt をチェックする必要がある、 長時間動作する Web スパイダープログラムを実装する際に便利です。

modified( )
robots.txt ファイルを最後に取得した時刻を現在の時刻に設定します。

以下にRobotFileParser クラスの利用例を示します。

>>> import robotparser
>>> rp = robotparser.RobotFileParser()
>>> rp.set_url("http://www.musi-cal.com/robots.txt")
>>> rp.read()
>>> rp.can_fetch("*", "http://www.musi-cal.com/cgi-bin/search?city=San+Francisco")
False
>>> rp.can_fetch("*", "http://www.musi-cal.com/")
True
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.18.1 netrc オブジェクト Up: 12. インターネット上のデータの操作 Next: 12.20 csv


12.20 csv -- CSV ファイルの読み書き

バージョン2.3 以降で新規追加された 仕様です。

CSV (Comma Separated Values、カンマ区切り値列) と呼ばれる形式は、 スプレッドシートやデータベース間でのデータのインポートやエクスポート における最も一般的な形式です。``CSV 標準'' は存在しないため、 CSV 形式はデータを読み書きする多くのアプリケーション上の操作に応じて 定義されているにすぎません。標準がないということは、異なるアプリケーション によって生成されたり取り込まれたりするデータ間では、しばしば微妙な 違いが発生するということを意味します。こうした違いのために、複数の データ源から得られた CSV ファイルを処理する作業が鬱陶しいものになる ことがあります。とはいえ、デリミタ (delimiter) やクオート文字の 相違はあっても、全体的な形式は十分似通っているため、こうしたデータを 効率的に操作し、データの読み書きにおける細々としたことをプログラマ から隠蔽するような単一のモジュールを書くことは可能です。

csv モジュールでは、CSV 形式で書かれたテーブル状の データを読み書きするためのクラスを実装しています。 このモジュールを使うことで、プログラマは Excel で使われている CSV 形式に関して詳しい知識をもっていなくても、 ``このデータを Excel で 推奨されている形式で書いてください'' とか、 ``データを Excel で 作成されたこのファイルから読み出してください'' と言うことができます。 プログラマはまた、他のアプリケーションが解釈できる CSV 形式を記述したり、 独自の特殊な目的をもった CSV 形式を定義することができます。

csv モジュールの reader および writer オブジェクトはシーケンス型を読み書きします。プログラマは DictReader や DictWriter クラスを使うことで、 データを辞書形式で読み書きすることもできます。

注意: このバージョンの csv モジュールは Unicode 入力をサポート していません。また、現在のところ、 ASCII NUL 文字に関連したいくつかの 問題があります。従って、安全を期すには、全ての入力を一般的には印字可能な ASCII にしなければなりません。これらの制限は将来取り去られる ことになっています。

参考資料:

PEP 305, CSV File API
Python へのこのモジュールの追加を提案している Python 改良案 (PEP: Python Enhancement Proposal)

  • 12.20.1 モジュールの内容
  • 12.20.2 Dialect クラスと書式化パラメタ
  • 12.20.3 reader オブジェクト
  • 12.20.4 writer オブジェクト
  • 12.20.5 使用例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.19 robotparser Up: 12. インターネット上のデータの操作 Next: 12.20.1 モジュールの内容


12.20.1 モジュールの内容

csv モジュールでは以下の関数を定義しています:

reader( csvfile[, dialect='excel'[, fmtparam]])
与えられた csvfile 内の行を反復処理するような reader オブジェクトを返します。csvfile はイテレータプロトコル をサポートし、next メソッドが呼ばれた際に常に文字列を 返すような任意のオブジェクトにすることができます。 csvfile がファイルオブジェクトの場合、ファイルオブジェクトの 形式に違いがあるようなプラットフォームでは 'b' フラグを付けて 開かなければなりません。 オプションとして dialect パラメタを与えることができ、 特定の CSV 表現形式 (dialect) 特有のパラメタの集合を定義するために 使われます。dialect パラメタは Dialect クラスのサブクラス のインスタンスか、list_dialects 関数が返す文字列 の一つにすることができます。別のオプションである fmtparam キーワード引数は、現在の表現形式における個々の書式パラメタを上書きする ために与えることができます。表現形式および書式化パラメタの詳細 については、 12.20.2 節、 ``Dialect クラスと書式化パラメタ'' を参照してください。

読み出されたデータは全て文字列として返されます。データ型の変換が 自動的に行われることはありません。

writer( csvfile[, dialect='excel'[, fmtparam]])
ユーザが与えたデータをデリミタで区切られた文字列に変換し、与えられた ファイルオブジェクトにするための writer オブジェクトを返します。 csvfile は write メソッドを持つ任意のオブジェクトで かまいません。 csvfile がファイルオブジェクトの場合、ファイルオブジェクトの 形式に違いがあるようなプラットフォームでは 'b' フラグを付けて 開かなければなりません。 オプションとして dialect パラメタを与えることができ、 特定の CSV 表現形式 (dialect) 特有のパラメタの集合を定義するために 使われます。dialect パラメタは Dialect クラスのサブクラス のインスタンスか、list_dialects 関数が返す文字列 の一つにすることができます。別のオプションである fmtparam キーワード引数は、現在の表現形式における個々の書式パラメタを上書きする ために与えることができます。表現形式および書式化パラメタの詳細 については、 12.20.2 節、 ``Dialect クラスと書式化パラメタ'' を参照してください。 DB API を実装するモジュールとのインタフェースを可能な限り容易に するために、None は空文字列として書き込まれます。 この処理は可逆な変換ではありませんが、SQL で NULL データ値を CSV にダンプする処理を、cursor.fetch*() 呼び出しによって 返されたデータを前処理することなく簡単に行うことができます。 他の非文字データは、書き出される前に str() を使って 文字列に変換されます。

register_dialect( name, dialect)
dialect を name と関連付けます。 dialect は csv.Dialect のサブクラスでなければなりません。 name は文字列か Unicode オブジェクトでなければなりません。

unregister_dialect( name)
name に関連づけられた表現形式を表現形式レジストリから削除します。 name が表現形式名でない場合には Error を送出します。

get_dialect( name)
name に関連づけられた表現形式を返します。 name が表現形式名でない場合には Error を送出します。

list_dialects( )
登録されている全ての表現形式を返します。

csv モジュールでは以下のクラスを定義しています:

class DictReader( csvfile, fieldnames[, restkey=None[, restval=None[, dialect='excel'[, fmtparam]]]])
fieldnames パラメタで与えられたキーを読み出された情報に対応付ける 他は正規の reader のように動作するオブジェクトを生成します。 読み出された行が fieldnames の配列よりも多くのフィールドを 持っていた場合、残りのフィールドデータは restkey の値をキーと する配列に追加されます。読み出された行が fieldnames の配列 よりも少ないフィールドしか持たない場合、残りのキーはオプションの restval パラメタに指定された値を取ります。その他のパラメタは reader オブジェクトの場合と同様に解釈されます。

class DictWriter( csvfile, fieldnames[, restval=""[, extrasaction='raise'[, dialect='excel'[, fmtparam]]]])
辞書を出力行に対応付ける他は正規の writer のように動作する オブジェクトを生成します。fieldnames パラメタには、 辞書中の writerow() メソッドに渡される値がどの順番で csvfile に書き出されるかを指定します。 オプションの restval パラメタは、fieldnames 内の キーが辞書中にない場合に書き出される値を指定します。 writerow() メソッドに渡された辞書に、 fieldnames 内には 存在しないキーが入っている場合、オプションの extraaction パラメタでどのような動作を行うかを指定します。この値が 'raise' に設定されている場合 ValueError が送出されます。 'ignore' に設定されている場合、辞書の余分の値は無視されます。 その他のパラメタは writer オブジェクトの場合と同様に解釈されます。

class Dialect
Dialect クラスはコンテナクラスで、基本的な用途としては、 その属性を特定の reader や writer インスタンスの パラメタを定義するために用います。

class Sniffer( [sample=16384])
Sniffer クラスは CSV ファイルの書式を推理するために用いられる クラスです。

Sniffer クラスではメソッドを一つ提供しています:

sniff( fileobj)
与えられた sample を解析し、発見されたパラメタを 反映した Dialect サブクラスを返します。 オプションの delimiters パラメタを与えた場合、 有効なデリミタ文字を含んでいるはずの文字列として解釈されます。

has_header( sample)
(CSV 形式と仮定される) サンプルテキストを解析して、 最初の行がカラムヘッダの羅列のように推察される場合 True を返します。

csv モジュールでは以下の定数を定義しています:

QUOTE_ALL
writer オブジェクトに対し、全てのフィールドをクオートするように 指示します。

QUOTE_MINIMAL
writer オブジェクトに対し、現在の delimiter を含む か、あるいは quotechar で始まるフィールドだけをクオートするように 指示します。

QUOTE_NONNUMERIC
writer オブジェクトに対し、全ての非数値フィールドをクオート するように指示します。

QUOTE_NONE
writer オブジェクトに対し、フィールドを決してクオートしない ように指示します。現在の delimiter が出力データ中に現れた 場合、現在設定されている excapechar 文字が前に付けられます。 QUOTE_NONE の効果下にある時には、1 文字からなる文字列 escapechar が定義されていないと、たとえ書き出されるデータ 中に delimiter 文字が入っていなくてもエラーになります。

csv モジュールでは以下の例外を定義しています:

exception Error
全ての関数において、エラーが検出された際に送出される例外です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.20 csv Up: 12.20 csv Next: 12.20.2 Dialect クラスと書式化パラメタ


12.20.2 Dialect クラスと書式化パラメタ

レコードに対する入出力形式の指定をより簡単にするために、 特定の書式化パラメタは表現形式 (dialect) にまとめてグループ化されます。 表現形式は Dialect クラスのサブクラスで、様々なクラス特有の メソッドと、validate() メソッドを一つ持っています。 reader または writer オブジェクトを生成するとき、 プログラマは文字列または Dialect クラスのサブクラスを表現形式 パラメタとして渡さなければなりません。さらに、dialect パラメタ の代りに、プログラマは上で定義されている属性と同じ名前を持つ 個々の書式化パラメタを Dialect クラスに指定することができます。

Dialect は以下の属性をサポートしています:

delimiter
フィールド間を分割するのに用いられる 1 文字からなる文字列です。 デフォルトでは ',' です。

doublequote
フィールド内に現れた quotechar のインスタンスで、クオートではない その文字自身でなければならない文字をどのようにクオートするかを制御します。 True の場合、この文字は二重化されます。 False の場合、 escapechar は 1 文字からなる文字列で なければならず、quotechar の前に置かれます。デフォルトでは True です。

escapechar
quoting が QUOTE_NONE に設定されている場合に、 delimiter をエスケープするために用いられる、 1 文字からなる文字列です。 デフォルトでは None です。

lineterminator
CSV ファイルの各行を終端する際に用いられる文字列です。 デフォルトでは '\r\n' です。

quotechar
delimiter を含むか、quotechar から始まる要素をクオートする際に 用いられる 1 文字からなる文字列です。デフォルトでは '"' です。

quoting
writer によってクオートがいつ生成されるかを制御します。 QUOTE_* 定数のいずれか (12.20.1 節参照) を とることができ、デフォルトではQUOTE_MINIMAL です。

skipinitialspace
True の場合、delimiter の直後に続く空白は無視されます。 デフォルトでは False です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.20.1 モジュールの内容 Up: 12.20 csv Next: 12.20.3 reader オブジェクト


12.20.3 reader オブジェクト

reader オブジェクト(DictReader インスタンス、および reader() 関数によって返されたオブジェクト) は、以下の public なメソッドを持っています:

next( )
reader の反復可能なオブジェクトから、現在の表現形式に基づいて 次の行を解析して返します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.20.2 Dialect クラスと書式化パラメタ Up: 12.20 csv Next: 12.20.4 writer オブジェクト


12.20.4 writer オブジェクト

writer オブジェクト(DictWriter インスタンス、および writer() 関数によって返されたオブジェクト) は、以下の public なメソッドを持っています:

writerow( row)
row パラメタを現在の表現形式に基づいて書式化し、 writer のファイル オブジェクトに書き込みます。

writerows( rows)
rows パラメタ全てを現在の表現形式に基づいて書式化し、 writer の ファイルオブジェクトに書き込みます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.20.3 reader オブジェクト Up: 12.20 csv Next: 12.20.5 使用例


12.20.5 使用例

csv 読み出しの ``Hello, world'' プログラムは以下のようになります。

import csv
reader = csv.reader(file("some.csv"))
for row in reader:
    print row

上に対して、単純な書き込みのプログラム例は以下のようになります。

import csv
writer = csv.writer(file("some.csv", "w"))
for row in someiterable:
    writer.writerow(row)

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.20.4 writer オブジェクト Up: 12.20 csv Next: 13. 構造化マークアップツール


13. 構造化マークアップツール

Python は様々な構造化データマークアップ形式を扱うための、様々な モジュールをサポートしています。これらは 標準化一般マークアップ言語 (SGML) およびハイパーテキストマークアップ 言語 (HTML)、そして可拡張性マークアップ言語 (XML) を扱うための いくつかのインタフェースからなります。

注意すべき重要な点として、xml パッケージは少なくとも一つの SAX に対応した XML パーザが利用可能でなければなりません。 Python 2.3 からは Expat パーザが Python に取り込まれているので、 xml.parsers.expat モジュールは常に利用できます。 また、PyXML 追加パッケージ についても知りたいと思うかもしれません; このパッケージは Python 用の拡張された XML ライブラリセットを提供します。

xml.dom および xml.sax パッケージのドキュメントは Python による DOM および SAX インタフェースへのバインディングに 関する定義です。

HTMLParser | HTML と XHTML を扱えるシンプルなパーザ。
sgmllib | HTML を解析するのに必要な機能だけを備えた SGML パーザ。
htmllib | HTML 文書の解析器。
htmlentitydefs | HTML 一般エンティティの定義。
xml.parsers.expat | Expat による、検証を行わない XML パーザへのインタフェース
xml.dom | Python のための文書オブジェクトモデル API。
xml.dom.minidom | 軽量な文書オブジェクトモデルの実装。
xml.dom.pulldom | SAX イベントからの部分的な DOM ツリー構築のサポート。
xml.sax | SAX2 基底クラスと有用な関数のパッケージ
xml.sax.handler | SAX イベント・ハンドラの基底クラス
xml.sax.saxutils | SAX とともに使う有用な関数とクラスです。
xml.sax.xmlreader | SAX 準拠の XML パーサが実装すべきインターフェースです。
xmllib | XML ドキュメントのパーサ。

参考資料:

Python/XML ライブラリ
Python にバンドルされてくる xml パッケージへの 拡張である PyXML パッケージのホームページです。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.20.5 使用例 Up: Python ライブラリリファレンス Next: 13.1 HTMLParser


13.1 HTMLParser -- HTML および XHTML のシンプルなパーザ

このモジュールでは HTMLParser クラスを定義します。 このクラスは HTML (ハイパーテキスト記述言語、 HyperText Mark-up Language) および XHTML で書式化されているテキストファイルを解釈するための基礎と なります。htmllib にあるパーザと違って、このパーザ は sgmllib の SGML パーザに基づいてはいません。

class HTMLParser( )
HTMLParser クラスは引数なしでインスタンス化します。

HTMLParser インスタンスに HTML データが入力されると、 タグが開始したとき、及び終了したときに関数を呼び出します。 HTMLParser クラスは、ユーザが行いたい動作を提供する ために上書きできるようになっています。

htmllib のパーザと違い、このパーザは終了タグが開始タグと 一致しているか調べたり、外側のタグ要素が閉じるときに内側で明示的 に閉じられていないタグ要素のタグ終了ハンドラを呼び出したりはしません。

HTMLParser インスタンスは以下のメソッドを提供します:

reset( )
インスタンスをリセットします。未処理のデータは全て失われます。 インスタンス化の際に非明示的に呼び出されます。

feed( data)
パーザにテキストを入力します。入力が完全なタグ要素で構成されている 場合に限り処理が行われます; 不完全なデータであった場合、新たに データが入力されるか、close() が呼び出されるまでバッファ されます。

close( )
全てのバッファされているデータについて、その後にファイル終了マーク が続いているとみなして強制的に処理を行います。このメソッドは 入力データの終端で行うべき追加処理を定義するために導出クラスで 上書きすることができますが、再定義を行ったクラスでは常に、 HTMLParser 基底クラスのメソッド close() を 呼び出さなくてはなりません。

getpos( )
現在の行番号およびオフセット値を返します。

get_starttag_text( )
最も最近開かれた開始タグのテキスト部分を返します。このテキストは 必ずしも元データを構造化する上で必須ではありませんが、 ``広く知られている (as deployed)'' HTML を扱ったり、入力を 最小限の変更で再生成 (属性間の空白をそのままにする、など) したり する場合に便利なことがあります。

handle_starttag( tag, attrs)
このメソッドはタグの開始部分を処理するために呼び出されます。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

tag 引数はタグの名前で、小文字に変換されています。 attrs 引数は (name, value) のペアからなる リストで、タグの <> 括弧内にある属性が収められています。 name は小文字に変換され、value 内のエンティティ参照 は変換されます。二重引用符やバックスラッシュは変換しません。例えば、 タグ <A HREF="http://www.cwi.nl/"> を処理する場合、このメソッドは "handle_starttag('a', [('href', 'http://www.cwi.nl/')])"として呼び出されます。

handle_startendtag( tag, attrs)
handle_starttag() と似ていますが、パーザが XHTML 形式の 空タグ (<a .../>) に遭遇した場合に呼び出されます。 この特定の語彙情報 (lexical information) が必要な場合、 このメソッドをサブクラスで上書きすることができます; 標準の実装 では、単に handle_starttag() および handle_endtag() を呼ぶだけです。

handle_endtag( tag)
このメソッドはあるタグ要素の終了タグを処理するために呼び出されます。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。tag 引数はタグの名前で、小文字に変換されています。

handle_data( data)
このメソッドは，他のメソッドに当てはまらない任意のデータを処理するために 呼び出されます。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

handle_charref( ref)
このメソッドはタグ外の "&#ref;" 形式の文字参照 (character reference) を処理するために呼び出されます。 ref には，先頭の"&#" および末尾の";" は 含まれません。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

handle_entityref( name)
このメソッドはタグ外の "&name;" 形式の一般のエンティティ参照 (entity reference) name を処理するために呼び出されます。 name には，先頭の"&" および末尾の";" は 含まれません。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

handle_comment( data)
このメソッドはコメントに遭遇した場合に呼び出されます。comment 引数は文字列で、"<!--" and "-->" デリミタ間の、 デリミタ自体を除いたテキストが収められています。例えば、コメント "<!--text-->" があると、このメソッドは引数 'text' で呼び出されます。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

handle_decl( decl)
パーザが SGML 宣言を読み出した際に呼び出されるメソッドです。 decl パラメタは <!...> 記述内の宣言内容 全体になります。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

handle_pi( data)
処理指令に遭遇した場合に呼び出されます。dataには、処理指令 全体が含まれ、例えば<?proc color='red'>という処理指令の場合、 handle_pi("proc color='red'")のように呼び出されます。 このメソッドは導出クラスで上書きするためのメソッドです; 基底クラスの 実装では何も行いません。

注意: The HTMLParserクラスでは、処理指令にSGMLの構文を使用します。 末尾に"?"がXHTMLの処理指令では、"?"がdataに 含まれます。

exception HTMLParseError
HTML の構文に沿わないパターンを発見したときに送出される例外です。 HTML 構文法上の全てのエラーを発見できるわけではないので注意してください。

  • 13.1.1 HTML パーザアプリケーションの例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13. 構造化マークアップツール Up: 13. 構造化マークアップツール Next: 13.1.1 HTML パーザアプリケーションの例


13.1.1 HTML パーザアプリケーションの例

基礎的な例として、HTMLParser クラスを使い、発見したタグを出力 する、非常に基礎的な HTML パーザを以下に示します。

from HTMLParser import HTMLParser

class MyHTMLParser(HTMLParser):

    def handle_starttag(self, tag, attrs):
        print "Encountered the beginning of a %s tag" % tag

    def handle_endtag(self, tag):
        print "Encountered the end of a %s tag" % tag
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.1 HTMLParser Up: 13.1 HTMLParser Next: 13.2 sgmllib


13.2 sgmllib -- 単純な SGML パーザ

このモジュールでは SGML (Standard Generalized Mark-up Language: 汎用マークアップ言語標準) で書式化されたテキストファイルを解析 するための基礎として働く SGMLParser クラスを定義しています。 実際には、このクラスは完全な SGML パーザを提供しているわけではありません -- このクラスは HTML で用いられているような SGML だけを解析し、 モジュール自体も htmllib モジュールの基礎にするため だけに存在しています。XHTML をサポートし、少し異なったインタフェースを 提供しているもう一つの HTML パーザは、HTMLParser モジュールで使うことができます。

class SGMLParser( )
SGMLParser クラスは引数無しでインスタンス化されます。 このパーザは以下の構成を認識するようにハードコードされています:

  • "<tag attr="value" ...>" と "</tag>" で表されるタグの開始部と終了部。

  • "&#name;" 形式をとる文字の数値参照。

  • "&name;" 形式をとるエンティティ参照。

  • "<!--text-->" 形式をとる SGML コメント。 末尾の ">" とその直前にある "--" の間には スペース、タブ、改行を入れることができます。

SGMLParser インスタンスは以下のインタフェースメソッドを 持っています:

reset( )
インスタンスをリセットします。未処理のデータは全て失われます。 このメソッドはインスタンス生成時に非明示的に呼び出されます。

setnomoretags( )
タグの処理を停止します。以降の入力をリテラル入力 (CDATA) として扱います。(この機能は古い HTML タグ <PAINTEXT> を実装 できるようにするためだけに提供されています)

setliteral( )
リテラルモード (CDATA モード) に移行します。

feed( data)
テキストをパーザに入力します。入力は完全なエレメントから成り立つ 場合に限り処理されます; 不完全なデータは追加のデータが入力されるか、 close() が呼び出されるまでバッファに蓄積されます。

close( )
バッファに蓄積されている全てのデータについて、直後にファイル終了記号 が来た時のようにして強制的に処理します。このメソッドは導出クラスで 再定義して、入力の終了時に追加の処理行うよう定義することができますが、 このメソッドの再定義されたバージョンでは常に close() を呼び出さなければなりません。

get_starttag_text( )
もっとも最近開かれた開始タグのテキストを返します。通常、構造化された データの処理をする上でこのメソッドは必要ありませんが、 ``広く知られている (as deployed)'' HTML を扱ったり、入力を 最小限の変更で再生成 (属性間の空白をそのままにする、など) したり する場合に便利なことがあります。

handle_starttag( tag, method, attributes)
このメソッドは start_tag() か do_tag() のどちらかのメソッドが定義されている開始タグを処理するために呼び出され ます。tag 引数はタグの名前で、小文字に変換されています。 method 引数は開始タグの意味解釈をサポートするために用いられる バインドされたメソッドです。 attributes 引数は (name, value) のペアからなる リストで、タグの <> 括弧内にある属性が収められています。 name は小文字に変換され、 value 内の二重引用符と バックスラッシュも変換されます。例えば、タグ <A HREF="http://www.cwi.nl/"> を処理する場合、このメソッドは "unknown_starttag('a', [('href', 'http://www.cwi.nl/')])"として呼び出されます。基底クラスの実装では、単に method を単一の引数 attributes と共に呼び出します。

handle_endtag( tag, method)
このメソッドは end_tag() メソッドの定義されている 終了タグを処理するために呼び出されます。 tag 引数はタグの名前で、小文字に変換されており、 method 引数は終了タグの意味解釈をサポートするために使われる バインドされたメソッドです。end_tag() メソッドが 終了エレメントとして定義されていない場合、ハンドラは一切呼び出され ません。基底クラスの実装では単に method を呼び出します。

handle_data( data)
このメソッドは何らかのデータを処理するために呼び出されます。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

handle_charref( ref)
このメソッドは "&#ref;" 形式の文字参照 (character reference) を処理するために呼び出されます。 基底クラスの実装では、ref は 0-255 の範囲の 10 進数で なければなりません。このメソッドは文字を ASCII に 変換し、 その文字を引数として handle_data() を 呼び出します。ref が無効な値か、範囲を超えた値である 場合、エラーを処理するために unknown_charref(ref) が呼び出されます。 名前づけされた文字エンティティをサポートするためには このメソッドをサブクラスで上書きしなければなりません。

handle_entityref( ref)
このメソッドは ref を一般エンティティ参照として、 "&ref;" 形式のエンティティ参照を処理するために 呼び出されます。

このメソッドは、エンティティ名を対応する変換文字に対応付けている インスタンス (またはクラス) 変数である entitydefs 中で ref を探します。変換が見つかった場合、変換された文字を 引数にして handle_data() を呼び出します; そうでない場合、 unknown_entityref(ref) を呼び出します。 標準では entitydefs は &amp;、 &apos、 &gt;、 &lt;、および &quot; の変換を定義しています。

handle_comment( comment)
このメソッドはコメントに遭遇した場合に呼び出されます。comment 引数は文字列で、"<!--" and "-->" デリミタ間の、 デリミタ自体を除いたテキストが収められています。例えば、コメント "<!--text-->" があると、このメソッドは引数 'text' で呼び出されます。基底クラスの実装では何も行いません。

handle_decl( data)
パーザが SGML 宣言を読み出した際に呼び出されるメソッドです。 実際には、DOCTYPE は HTML だけに見られる宣言ですが、 パーザは宣言間の相違 (や誤った宣言) を判別しません。DOCTYPE の内部サブセット宣言はサポートされていません。 decl パラメタは <!...> 記述内の宣言内容 全体になります。基底クラスの実装では何も行いません。

report_unbalanced( tag)
個のメソッドは対応する開始エレメントのない終了タグが発見された 時に呼び出されます。

unknown_starttag( tag, attributes)
未知の開始タグを処理するために呼び出されるメソッドです。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

unknown_endtag( tag)
This method is called to process an unknown end tag. 未知の終了タグを処理するために呼び出されるメソッドです。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

unknown_charref( ref)
このメソッドは解決不能な文字参照数値を処理するために呼び出され ます。標準で何が処理可能かは handle_charref() を参照 してください。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

unknown_entityref( ref)
未知のエンティティ参照を処理するために呼び出されるメソッドです。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

上に挙げたメソッドを上書きしたり拡張したりするのとは別に、導出 クラスでは以下の形式のメソッドを定義して、特定のタグを処理する こともできます。入力ストリーム中のタグ名は大小文字の区別に依存 しません; メソッド名中の tag は小文字でなければなりません:

start_tag( attributes)
このメソッドは開始タグ tag を処理するために呼び出されます。 do_tag() よりも高い優先順位があります。 attributes 引数は上の handle_starttag() で記述されて いるのと同じ意味です。

do_tag( attributes)
このメソッドは対応する終了タグのない開始タグ tag を処理するために呼び出されます。attributes 引数は 上の handle_starttag() で記述されているのと同じ 意味です。

end_tag( )
このメソッドは終了タグ tag を処理するために呼び出されます。

パーザは開始されたエレメントのうち、終了タグがまだ見つかっていない
もののスタックを維持しているので注意してください。
start_tag() で処理されたタグだけがスタックにプッシュ
されます。are pushed on this stack.  Definition of an
それらのタグに対する end_tag() メソッドの定義は
オプションです。do_tag() や unknown_tag()
で処理されるタグについては、end_tag() を定義しては
いけません; 定義されていても使われることはありません。
あるタグに対して start_tag および do_tag()
メソッドの両方が存在する場合、start_tag() が優先されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.1.1 HTML パーザアプリケーションの例 Up: 13. 構造化マークアップツール Next: 13.3 htmllib


13.3 htmllib -- HTML 文書の解析器

このモジュールでは、ハイパーテキスト記述言語 (HTML, HyperText Mark-up Language) 形式で書式化されたテキストファイルを解析するための基盤として 役立つクラスを定義しています。このクラスは I/O と直接的には接続 されません -- このクラスにはメソッドを介して文字列形式の入力を 提供する必要があり、出力を生成するには ``フォーマッタ (formatter)'' オブジェクトのメソッドを何度か呼び出さなくてはなりません。

HTMLParser クラスは、機能を追加するために他のクラスの基底クラス として利用するように設計されており、ほとんどのメソッドが拡張したり 上書きしたりできるようになっています。 さらにこのクラスは sgmllibモジュール で定義されている SGMLParser クラスから導出されており、その機能 を拡張しています。HTMLParser の実装は、RFC 1866 で解説されている HTML 2.0 記述言語をサポートします。 formatterでは 2 つのフォーマッタ オブジェクト実装が提供されています; フォーマッタのインタフェースに ついての情報は formatter モジュールのドキュメントを参照 してください。

以下は sgmllib.SGMLParser で定義されているインタフェースの 概要です:

  • インスタンスにデータを与えるためのインタフェースは feed() メソッドで、このメソッドは文字列を引数に取ります。 このメソッドに一度に与えるテキストは必要に応じて多くも少なくも できます; というのは "p.feed(a);p.feed(b)" は "p.feed(a+b)" と同じ効果を持つからです。 与えられたデータが完全な HTML タグ群を含む場合、それらのタグは 即座に処理されます; 不完全な要素はバッファに保存されます。 全ての未処理データを強制的に処理させるには、 close() メソッドを呼び出します。

    例えば、ファイルの全内容を解析するには:

    parser.feed(open('myfile.html').read())
parser.close()
    のようにします。

  • HTML タグに対して意味付けを定義するためのインタフェースはとても 単純です: サブクラスを導出して、start_tag()、 end_tag()、あるいは do_tag() といったメソッドを定義するだけです。 パーザはこれらのメソッドを適切なタイミングで呼び出します: start_tag や do_tag() は <tag ...> の形式の開始タグに遭遇した時に呼び出されます; end_tag() は <tag> の形式の終了タグに 遭遇した時に呼び出されます。<H1> ... </H1> のように 開始タグが終了タグと対応している必要がある場合、クラス中で start_tag() が定義されていなければなりません; <P> のように終了タグが必要ない場合、クラス中では do_tag() を定義しなければなりません。

このモジュールではクラスを一つだけ定義しています:

class HTMLParser( formatter)
基底となる HTML パーザクラスです。HTML 2.0 仕様 (RFC 1866) が要求 している全てのエンティティ名をサポートしています。このクラスでは また、 HTML 2.0 の全てのタグ要素と HTML 3.0 および 3.2 の多くの タグ要素に対するハンドラを定義しています。

参考資料:

formatterモジュール:
抽象化された書式イベントの流れを writer オブジェクト上の特定の出力イベントに変換するための インターフェース。.
HTMLParserモジュール:
HTML パーザのひとつです。やや低いレベル でしか入力を扱えませんが、XHTML を扱うことができるように設計 されています。``広く知られている HTML (HTML as deployed)'' では 使われておらずかつ XHTML では正しくないとされる SGML 構文のいくつか は実装されていません。.
htmlentitydefsモジュール:
HTML 2.0 エンティティに対する置換 テキストの定義。.
sgmllibモジュール:
HTMLParser の基底クラス。.

  • 13.3.1 HTMLParser オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.2 sgmllib Up: 13. 構造化マークアップツール Next: 13.3.1 HTMLParser オブジェクト


13.3.1 HTMLParser オブジェクト

タグメソッドに加えて、HTMLParser クラスではタグメソッド で利用するためのいくつかのメソッドとインスタンス変数を提供しています。

formatter
パーザに関連付けられているフォーマッタインスタンスです。

nofill
ブール値のフラグで、空白文字を縮約したくないときには真、縮約するときには 偽にします。一般的には、この値を真にするのは、<PRE> 要素の 中のテキストのように、文字列データが ``書式化済みの (preformatted)'' 場合だけです。標準の値は偽です。この値は handle_data() および save_end() の操作に影響します。

anchor_bgn( href, name, type)
このメソッドはアンカー領域の先頭で呼び出されます。引数は <A> タグの属性で同じ名前を持つものに対応します。 標準の実装では、ドキュメント内のハイパーリンク (<A> タグの HREF 属性) を列挙したリスト を維持しています。ハイパーリンクのリストはデータ属性 anchorlist で手に入れることができます。

anchor_end( )
このメソッドはアンカー領域の末尾で呼び出されます。標準の 実装では、テキストの注釈マーカを追加します。マーカは anchor_bgn() で作られたハイパーリンクリストの インデクス値です。

handle_image( source, alt[, ismap[, align[, width[, height]]]])
このメソッドは画像を扱うために呼び出されます。標準の実装では、 単に handle_data() に alt の値を渡すだけです。

save_bgn( )
文字列データをフォーマッタオブジェクトに送らずにバッファに保存 する操作を開始します。保存されたデータは save_end() で取得してください。 save_bgn() / save_end() のペアを入れ子構造にすることはできません。

save_end( )
文字列データのバッファリングを終了し、以前 save_bgn() を呼び出した時点から保存されている全てのデータを返します。 nofill フラグが偽の場合、空白文字は全てスペース文字 一文字に置き換えられます。予め save_bgn() を呼ばないで このメソッドを呼び出すと TypeError 例外が送出されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.3 htmllib Up: 13.3 htmllib Next: 13.4 htmlentitydefs


13.4 htmlentitydefs -- HTML 一般エンティティの定義

このモジュールではentitydefs、codepoint2name、entitydefs の三つの辞書を定義しています。 entitydefsはhtmllib モジュールで HTMLParser クラスの entitydefs メンバを定義するために使われます。 このモジュールでは XHTML 1.0 で定義された全てのエンティティを提供しており、 Latin-1 キャラクタセット (ISO-8859-1)の簡単なテキスト置換を行う事ができます。

entitydefs
各 XHTML 1.0 エンティティ定義について、ISO Latin-1 における置換 テキストへの対応付けを行っている辞書です。

name2codepoint
HTMLのエンティティ名をUnicodeのコードポイントに変換するための辞書です。 バージョン2.3 以降で新規追加された 仕様です。

codepoint2name
A dictionary that maps Unicode codepoints to HTML entity names. UnicodeのコードポイントをHTMLのエンティティ名に変換するための辞書です。 バージョン2.3 以降で新規追加された 仕様です。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.3.1 HTMLParser オブジェクト Up: 13. 構造化マークアップツール Next: 13.5 xml.parsers.expat


13.5 xml.parsers.expat -- Expat を使った高速な XML 解析

バージョン2.0 以降で新規追加された 仕様です。

xml.parsers.expat モジュールは、検証 (validation) を 行わない XML パーザ (parser, 解析器)、Expatへの Python インタフェースです。 モジュールは一つの拡張型 xmlparser を提供します。これは XMLパーザの現在の状況を表します。一旦 xmlparser オブジェクトを 生成すると、オブジェクトの様々な属性をハンドラ関数 (handler function) に設定できます。 その後、XML 文書をパーザに入力すると、 XML文書の文字列とマークアップ に応じてハンドラ関数が呼び出されます。

このモジュールでは、Expatパーザへのアクセスを提供するために pyexpatモジュールを使用します。 pyexpatモジュールの直接使用は撤廃されています。

このモジュールは、例外を一つと型オブジェクトを一つ提供しています。

exception ExpatError
Expat がエラーを報告したときに例外を送出します。Expatのエラーを 解釈する上での詳細な情報は、 13.5.2 の ``ExpatError Exceptions,'' を参照してください。

exception error
ExpatErrorへの別名です。

XMLParserType
ParserCreate() 関数から返された戻り値の型を示します。

xml.parsers.expat モジュールには以下の 2 つの関数が収められて います:

ErrorString( errno)
与えられたエラー番号 errno を解説する文字列を返します。

ParserCreate( [encoding[, namespace_separator]])
新しい xmlparser オブジェクトを作成し、返します。 encoding が指定されていた場合、XMLデータで使われている 文字列のエンコード名でなければなりません。Expatは、Pythonのように多くの エンコードをサポートしておらず、またエンコーディングのレパートリを 拡張することはできません; サポートするエンコードは、UTF-8, UTF-16, ISO-8859-1 (Latin1), ASCII です。encodingが 指定されると、文書に対する明示的、非明示的なエンコード指定を 上書き (override) します。

Expat はオプションで XML 名前空間の処理を行うことができます。 これは引数 namespace_separator に値を指定することで 有効になります。 この値は、1文字の文字列でなければなりません; 文字列が誤った長さ を持つ場合には ValueError が送出されます (None は 値の省略と見なされます) 名前空間の処理が可能なとき、名前空間に属する 要素と属性が展開されます。要素のハンドラである StartElementHandler と EndElementHandler に渡された 要素名は、名前空間のURI、名前空間の区切り文字、要素名のローカル部を 連結したものになります。名前空間の区切り文字が 0 バイト (chr(0)) の場合、名前空間の URI とローカル部は区切り文字なしで 連結されます。

たとえば、 namespace_separator に空白文字(" ")がセットされ、 次のような文書が解析されるとします。

<?xml version="1.0"?>
<root xmlns    = "http://default-namespace.org/"
      xmlns:py = "http://www.python.org/ns/">
  <py:elem1 />
  <elem2 xmlns="" />
</root>

StartElementHandler は各要素ごとに次のような文字列を受け取ります。

http://default-namespace.org/ root
http://www.python.org/ns/ elem1
elem2

参考資料:

The Expat XML Parser
Expatプロジェクトのホームページ

  • 13.5.1 XMLParser Objects
  • 13.5.2 ExpatError 例外
  • 13.5.3 例
  • 13.5.4 内容モデルの記述
  • 13.5.5 Expat エラー定数
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.4 htmlentitydefs Up: 13. 構造化マークアップツール Next: 13.5.1 XMLParser Objects


13.5.1 XMLParser Objects

xmlparser オブジェクトは以下のようなメソッドを持ちます。

Parse( data[, isfinal])
文字列 data の内容を解析し、解析されたデータを処理するための 適切な関数を呼び出します。このメソッドを最後に呼び出す時は isfinal を真にしなければなりません。 data は空の文字列を取ることもできます。

ParseFile( file)
file オブジェクトから読み込んだXMLデータを解析します。 file には read(nbytes) メソッドのみが必要です。 このメソッドはデータなくなった場合に空文字列を返さねばなりません。。

SetBase( base)
(XML) 宣言中のシステム識別子中の相対 URI を解決するための、 基底 URI を設定します。相対識別子の解決はアプリケーションに 任されます: この値は関数 ExternalEntityRefHandler や NotationDeclHandler、UnparsedEntityDeclHandler に引数 base としてそのまま渡されます。

GetBase( )
以前の SetBase() によって設定された基底 URI を文字列の形で 返します。SetBase()が呼ばれていないときには None を 返します。

GetInputContext( )
現在のイベントを発生させた入力データを文字列として返します。 データはテキストの入っているエンティティが持っているエンコードに なります。 イベントハンドラがアクティブでないときに呼ばれると、戻り値は Noneとなります。 バージョン2.1 以降で新規追加された 仕様です。

ExternalEntityParserCreate( context[, encoding])
親となるパーザで解析された内容が参照している、外部で解析される エンティティを解析するために使える ``子の'' パーザを作成します。 context パラメータは、以下に記すように ExternalEntityRefHandler() ハンドラ関数に渡される文字列でなければなりません。子のパーザは ordered_attributes、returns_unicode、 specified_attributes が現在のパーザの値に設定されて 生成されます。

xmlparser オブジェクトは次のような属性を持ちます:

buffer_size
buffer_text が真の時に使われるバッファのサイズです。 この値は変更できません。 バージョン2.3 以降で新規追加された 仕様です。

buffer_text
この値を真にすると、xmlparser オブジェクトが Expatから返された もとの内容をバッファに保持するようになります。これにより可能なときに 何度も CharacterDataHandler() を呼び出してしまうようなことを 避けることができます。Expatは通常、文字列のデータを行末ごと大量に破棄 するため、かなりパフォーマンスを改善できるはずです。この属性はデフォルト では偽で、いつでも変更可能です。 バージョン2.3 以降で新規追加された 仕様です。

buffer_used
buffer_text が利用可能なとき、バッファに保持されたバイト数です。 これらのバイトはUTF-8でエンコードされたテキストを表します。この属性は buffer_text が偽の時には意味がありません。 バージョン2.3 以降で新規追加された 仕様です。

ordered_attributes
この属性をゼロ以外の整数にすると、報告される(XMLノードの) 属性を 辞書型ではなくリスト型にします。属性は文書のテキスト中の出現順で示されます。 それぞれの属性は、2つのリストのエントリ: 属性名とその値、が与えられます。 (このモジュールの古いバージョンでも、同じフォーマットが使われています。) デフォルトでは、この属性はデフォルトでは偽となりますが、 いつでも変更可能です。 バージョン2.1 以降で新規追加された 仕様です。

returns_unicode
この属性をゼロ以外の整数にすると、ハンドラ関数に Unicode 文字列が 渡されます。 returns_unicode が 0 の時には、UTF-8でエンコード されたデータを含む 8 ビット文字列がハンドラに渡されます。 バージョン1.6 以降で変更された 仕様: 戻り値の型がいつでも変更できるように変更されたはずです

specified_attributes
ゼロ以外の整数にすると、パーザは文書のインスタンスで特定される 属性だけを報告し、属性宣言から導出された属性は報告しないようになります。 この属性が指定されたアプリケーションでは、XMLプロセッサの振る舞いに 関する標準に従うために必要とされる (文書型) 宣言によって、どのような 付加情報が利用できるのかということについて特に注意を払わなければなりません。 デフォルトで、この属性は偽となりますが、いつでも変更可能です。 バージョン2.1 以降で新規追加された 仕様です。

以下の属性には、 xmlparser オブジェクトで最も最近に起きた エラーに関する値が入っており、また Parse() または ParseFile()メソッドが xml.parsers.expat.ExpatError 例外を送出した際にのみ正しい値となります。

ErrorByteIndex
エラーが発生したバイトのインデクスです。

ErrorCode
エラーを特定する数値によるコードです。この値はErrorString() に 渡したり、 errors オブジェクトで定義された内容と比較できます。

ErrorColumnNumber
エラーの発生したカラム番号です。

ErrorLineNumber
エラーの発生した行番号です。

以下に指定可能なハンドラのリストを示します。 xmlparser オブジェクト o に ハンドラを指定するには、o.handlername = func を使用します。 handlername は、以下のリストに挙げた値をとらねば ならず、また func は正しい数の引数を受理する呼び出し可能な オブジェクトでなければなりません。引数は特に明記しない限り、すべて 文字列となります。

XmlDeclHandler( version, encoding, standalone)
XML 宣言が解析された時に呼ばれます。XML宣言とは、XML勧告の適用 バージョン (オプション)、文書テキストのエンコード、そしてオプションの ``スタンドアロン'' の宣言です。 version と encoding は returns_unicode 属性によって指示された型を示す文字列となり、 standalone は、文書がスタンドアロンであると宣言される場合には 1に、文書がスタンドアロンでない場合には 0 に、 スタンドアロン宣言を省略する場合には -1 になります。 このハンドラは Expat のバージョン1.95.0以降のみ使用できます。 バージョン2.1 以降で新規追加された 仕様です。

StartDoctypeDeclHandler( doctypeName, systemId, publicId, has_internal_subset)
Expatが文書型宣言<!DOCTYPE ...)を解析し始めたときに 呼び出されます。doctypeName は、与えられた値がそのまま Expat に提供されます。systemId と publicId パラメタが 指定されている場合、それぞれシステムと公開識別子を与えます。 省略する時にはNone にします。文書が内部的な文書宣言のサブセット (internal document declaration subset) を持つか、サブセット自体の 場合、has_internal_subset は true になります。 このハンドラには、Expat version 1.2以上が必要です。

EndDoctypeDeclHandler( )
Expatが文書型宣言の解析を終えたときに呼び出されます。 このハンドラには、Expat version 1.2以上が必要です。

ElementDeclHandler( name, model)
それぞれの要素型宣言ごとに呼び出されます。nameは要素型の名前であり、 model は内容モデル (content model) の表現です。

AttlistDeclHandler( elname, attname, type, default, required)
ひとつの要素型で宣言される属性ごとに呼び出されます。属性リストの宣言が 3つの属性を宣言したとすると、このハンドラはひとつの属性に1度づつ、 3度呼び出されます。 elname は要素名であり、これに対して宣言が適用され、attnameが 宣言された属性名となります。 属性型は文字列で、type として渡され ます; 取りえる値は、'CDATA', 'ID','IDREF', ... です。 defaultは、属性が文書のインスタンスによって指定されていないときに 使用されるデフォルト値を与えます。デフォルト値(#IMPLIED values)が 存在しないときにはNoneを与えます。文書のインスタンスによって属性値が 与えられる必要のあるときにはrequiredがtrueになります。 このメソッドはExpat version 1.95.0 以上が必要です。

StartElementHandler( name, attributes)
要素の開始を処理するごとに呼び出されます。name は要素名を格納した 文字列で、attributes はその値に属性名を対応付ける辞書型です。

EndElementHandler( name)
要素の終端を処理するごとに呼び出されます。

ProcessingInstructionHandler( target, data)
Called for every processing instruction. 処理命令を処理するごとに呼び出されます。

CharacterDataHandler( data)
文字データを処理するときに呼びだされます。このハンドラは通常の文字データ、 CDATAセクション、無視できる空白文字列のために呼び出されます。 これらを識別しなければならないアプリケーションは、要求された情報を 収集するために StartCdataSectionHandler, EndCdataSectionHandler, and ElementDeclHandlerコールバックメソッドを使用できます。

UnparsedEntityDeclHandler( entityName, base, systemId, publicId, notationName)
解析されていない (NDATA) エンティティ宣言を処理するために呼び出されます。 このハンドラは Expat ライブラリのバージョン1.2のためだけに存在します; より最近のバージョンでは、 代わりにEntityDeclHandlerを使用してください (根底にある Expat ライブラリ内の関数は、撤廃されたものであると宣言されています)。

EntityDeclHandler( entityName, is_parameter_entity, value, base, systemId, publicId, notationName)
エンティティ宣言ごとに呼び出されます。パラメタと内部エンティティに ついて、value はエンティティ宣言の宣言済みの内容を与える文字列 となります; 外部エンティティの時にはNone となります。解析済み エンティティの場合、notationName パラメタは None となり、 解析されていないエンティティの時には記法 (notation) 名となります。 is_parameter_entity は、エンティティがパラメタエンティティの 場合真に、一般エンティティ (general entitiy) の場合には偽になります (ほとんどのアプリケーションでは、一般エンティティのことしか気に する必要がありません)。 このハンドラは Expat ライブラリのバージョン1.95.0 以降でのみ使用できます。 バージョン2.1 以降で新規追加された 仕様です。

NotationDeclHandler( notationName, base, systemId, publicId)
記法の宣言 (notation declaration) で呼び出されます。 notationName, base, systemId, および publicId を与える場合、文字列にします。public な識別子が省略された場合、 publicId は None になります。

StartNamespaceDeclHandler( prefix, uri)
要素が名前空間宣言を含んでいる場合に呼び出されます。名前空間宣言は、 宣言が配置されている要素に対して StartElementHandler が 呼び出される前に処理されます。

EndNamespaceDeclHandler( prefix)
名前空間宣言を含んでいたエレメントの終了タグに到達したときに 呼び出されます。このハンドラは、要素に関する名前空間宣言ごとに、 StartNamespaceDeclHandler とは逆の順番で一度だけ呼び 出され、各名前空間宣言のスコープが開始されたことを示します。 このハンドラは、要素が終了する際、対応する EndElementHandler が呼ばれた後に呼び出されます。

CommentHandler( data)
コメントで呼び出されます。data はコメントのテキストで、 先頭の `<!--' と末尾の `-->' を除きます。

StartCdataSectionHandler( )
CDATA セクションの開始時に呼び出されます。CDATA セクションの 構文的な開始と終了位置を識別できるようにするには、このハンドラと StartCdataSectionHandler が必要です。

EndCdataSectionHandler( )
CDATA セクションの終了時に呼び出されます。

DefaultHandler( data)
XML 文書中で、適用可能なハンドラが指定されていない 文字すべてに対して呼び出されます。この文字とは、検出されたことが 報告されるが、ハンドラは指定されていないような コンストラクト (construct) の一部である文字を意味します。

DefaultHandlerExpand( data)
DefaultHandler と同じですが、内部エンティティの 展開を禁止しません。エンティティ参照はデフォルトハンドラに 渡されません。

NotStandaloneHandler( )
XML 文書がスタンドアロンの文書として宣言されていない場合に呼び出されます。 外部サブセットやパラメタエンティティへの参照が存在するが、XML 宣言が XML 宣言中で standalone 変数を yes に設定していない場合に 起きます。このハンドラが 0 を返すと、パーザは XML_ERROR_NOT_STANDALONE を送出します。 このハンドラが設定されていなければ、パーザは前述の事態で 例外を送出しません。

ExternalEntityRefHandler( context, base, systemId, publicId)
外部エンティティの参照時に呼び出されます。base は現在の基底 (base) で、以前の SetBase() で設定された値になっています。 public、および system の識別子である、systemId とpublicId が指定されている場合、値は文字列です; public 識別子が指定されていない 場合、 publicId は None になります。 context の値は不明瞭なものであり、以下に記述するようにしか 使ってはなりません。

外部エンティティが解析されるようにするには、このハンドラを実装 しなければなりません。このハンドラは、 ExternalEntityParserCreate(context) を使って 適切なコールバックを指定し、子パーザを生成して、 エンティティを解析する役割を担います。このハンドラは整数を 返さねばなりません; 0 を返した場合、パーザは XML_ERROR_EXTERNAL_ENTITY_HANDLING エラーを送出します。 そうでないばあい、解析を継続します。

このハンドラが与えられておらず、 DefaultHandler コールバックが指定されていれば、 外部エンティティはDefaultHandler で報告されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.5 xml.parsers.expat Up: 13.5 xml.parsers.expat Next: 13.5.2 ExpatError 例外


13.5.2 ExpatError 例外

ExpatError 例外はいくつかの興味深い属性を備えています:

code
特定のエラーにおける Expat の内部エラー番号です。この値は このモジュールのerrors オブジェクトで定義されている 定数のいずれかに一致します。 バージョン2.1 以降で新規追加された 仕様です。

lineno
エラーが検出された場所の行番号です。最初の行の番号は 1 です。 バージョン2.1 以降で新規追加された 仕様です。

offset
エラーが発生した場所の行内でのオフセットです。最初のカラムの番号は 0 です。 バージョン2.1 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.5.1 XMLParser Objects Up: 13.5 xml.parsers.expat Next: 13.5.3 例


13.5.3 例

以下のプログラムでは、与えられた引数を出力するだけの三つのハンドラを 定義しています。

import xml.parsers.expat

# 3 handler functions
def start_element(name, attrs):
    print 'Start element:', name, attrs
def end_element(name):
    print 'End element:', name
def char_data(data):
    print 'Character data:', repr(data)

p = xml.parsers.expat.ParserCreate()

p.StartElementHandler = start_element
p.EndElementHandler = end_element
p.CharacterDataHandler = char_data

p.Parse("""<?xml version="1.0"?>
<parent id="top"><child1 name="paul">Text goes here</child1>
<child2 name="fred">More text</child2>
</parent>""")

このプログラムの出力は以下のようになります:

Start element: parent {'id': 'top'}
Start element: child1 {'name': 'paul'}
Character data: 'Text goes here'
End element: child1
Character data: '\n'
Start element: child2 {'name': 'fred'}
Character data: 'More text'
End element: child2
Character data: '\n'
End element: parent

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.5.2 ExpatError 例外 Up: 13.5 xml.parsers.expat Next: 13.5.4 内容モデルの記述


13.5.4 内容モデルの記述

内容モデルは入れ子になったタプルを使って記述されています。 各タプルには 4 つの値: 型、限定詞 (quantifier)、名前、そして子の タプル、が収められています。子のタプルは単に内容モデルを 記述したものです。

最初の二つのフィールドの値は xml.parsers.expat モジュールの model オブジェクトで定義されている定数です。これらの定数は 二つのグループ: モデル型 (model type) グループと限定子 (quantifier) グループ、に取りまとめられます。

以下にモデル型グループにおける定数を示します:

XML_CTYPE_ANY
モデル名で指定された要素は ANY の内容モデルを持つと 宣言されます。

XML_CTYPE_CHOICE
指定されたエレメントはいくつかのオプションから選択できるようになって います; (A | B | C) のような内容モデルで用いられます。

XML_CTYPE_EMPTY
EMPTY であると宣言されている要素はこのモデル型を持ちます。

XML_CTYPE_MIXED

XML_CTYPE_NAME

XML_CTYPE_SEQ
順々に続くようなモデルの系列を表すモデルがこのモデル型で表されます。 (A, B, C) のようなモデルで用いられます。

限定子グループにおける定数を以下に示します:

XML_CQUANT_NONE
修飾子 (modifier) が指定されていません。従って A のように、 厳密に一つだけです。

XML_CQUANT_OPT
このモデルはオプションです: A? のように、一つか全くないかです。

XML_CQUANT_PLUS
このモデルは (A+ のように) 一つかそれ以上あります。

XML_CQUANT_REP
このモデルは A* のようにゼロ回以上あります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.5.3 例 Up: 13.5 xml.parsers.expat Next: 13.5.5 Expat エラー定数


13.5.5 Expat エラー定数

以下の定数は xml.parsers.expat モジュールにおける errors オブジェクトで提供されています。これらの定数は、 エラーが発生した際に送出される ExpatError 例外オブジェクトのいくつかの属性を解釈する上で便利です。

errors オブジェクトは以下の属性を持ちます:

XML_ERROR_ASYNC_ENTITY

XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF
属性値中のエンティティ参照が、内部エンティティではなく外部エンティティ を参照しました。

XML_ERROR_BAD_CHAR_REF
文字参照が、XML では正しくない (illegal) 文字を参照しました (例えば 0 や `&#0;')。

XML_ERROR_BINARY_ENTITY_REF
エンティティ参照が、記法 (notation) つきで宣言されている エンティティを参照したため、解析できません。

XML_ERROR_DUPLICATE_ATTRIBUTE
一つの属性が一つの開始タグ内に一度より多く使われています。

XML_ERROR_INCORRECT_ENCODING

XML_ERROR_INVALID_TOKEN
入力されたバイトが文字に適切に関連付けできない際に送出されます; 例えば、UTF-8 入力ストリームにおける NUL バイト (値 0) などです。

XML_ERROR_JUNK_AFTER_DOC_ELEMENT
空白以外の何かがドキュメント要素の後にあります。

XML_ERROR_MISPLACED_XML_PI
入力データの先頭以外の場所に XML 定義が見つかりました。

XML_ERROR_NO_ELEMENTS
このドキュメントには要素が入っていません (XML では全てのドキュメントは 確実にトップレベルの要素を一つ持つよう要求しています)。

XML_ERROR_NO_MEMORY
Expat が内部メモリを確保できませんでした。

XML_ERROR_PARAM_ENTITY_REF
パラメタエンティティが許可されていない場所で見つかりました。

XML_ERROR_PARTIAL_CHAR

XML_ERROR_RECURSIVE_ENTITY_REF
エンティティ参照中に、同じエンティティへの別の参照が入っていました; おそらく違う名前で参照しているか、間接的に参照しています。

XML_ERROR_SYNTAX
何らかの仕様化されていない構文エラーに遭遇しました。

XML_ERROR_TAG_MISMATCH
終了タグが最も内側で開かれている開始タグに一致しません。

XML_ERROR_UNCLOSED_TOKEN
何らかの (開始タグのような) トークン が閉じられないまま、 ストリームの終端や次のトークンに遭遇しました。

XML_ERROR_UNDEFINED_ENTITY
定義されていないエンティティへの参照が行われました。

XML_ERROR_UNKNOWN_ENCODING
ドキュメントのエンコードが Expat でサポートされていません。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.5.4 内容モデルの記述 Up: 13.5 xml.parsers.expat Next: 13.6 xml.dom


13.6 xml.dom -- 文書オブジェクトモデル (DOM) API

バージョン2.0 以降で新規追加された 仕様です。

文書オブジェクトモデル、または ``DOM'' は、ワールドワイドウェブ コンソーシアム (World Wide Web Consortium, W3C) による、XML ドキュメントにアクセスしたり変更を加えたりするための、プログラミング 言語間共通の API です。DOM 実装によって、XML ドキュメントは ツリー構造として表現されます。また、クライアントコード側で ツリー構造をゼロから構築できるようになります。さらに、 前述の構造に対して、よく知られたインタフェースをもつ一連の オブジェクトを通したアクセス手段も提供します。

DOM はランダムアクセスを行うアプリケーションで非常に有用です。 SAX では、一度に閲覧することができるのはドキュメントのほんの 一部分です。ある SAX 要素に注目している際には、別の要素をアクセス することはできません。またテキストノードに注目しているときには、 その中に入っている要素をアクセスすることができません。 SAX によるアプリケーションを書くときには、プログラムがドキュメント内の どこを処理しているのかを追跡するよう、コードのどこかに記述する 必要があります。SAX 自体がその作業を行ってくれることはありません。 さらに、XML ドキュメントに対する先読み (look ahead) が必要だと すると不運なことになります。

アプリケーションによっては、ツリーにアクセスできなければ イベント駆動モデルを実現できません。もちろん、何らかのツリーを SAX イベントに応じて自分で構築することもできるでしょうが、 DOM ではそのようなコードを書かなくてもよくなります。 DOM は XML データに対する標準的なツリー表現なのです。

文書オブジェクトモデルは、W3C によっていくつかの段階、W3C の用語で 言えば ``レベル (level)'' で定義されています。 Python においては、 DOM API への対応付け は実質的には DOM レベル 2 勧告に基づいています。 現在はドラフト形式でのみ入手できる レベル 3 仕様への対応付けは、 Python XML 分科会 (Special Interest Group) により、 PyXML パッケージ の一部として 開発中です。 DOM レベル 3 サポートの現在の状態についての情報は、 PyXML パッケージに同梱されているドキュメントを参照してください。

DOM アプリケーションは、普通は XML を DOM に解析するところから始まり ます。どのようにして解析を行うかについては DOM レベル 1 では全く カバーしておらず、レベル 2 では限定的な改良だけが行われました: レベル 2 ではDocument を生成するメソッドを提供する DOMImplementation オブジェクトクラスがありますが、 実装に依存しない方法で XML リーダ(reader)/パーザ(parser)/文書ビルダ (Document builder) にアクセスする方法はありません。また、既存の Document オブジェクトなしにこれらのメソッドにアクセスする ような、よく定義された方法もありません。 Python では、各々の DOM 実装で getDOMImplementation() が定義されているはずです。 DOM レベル 3 ではロード(Load)/ストア(Store) 仕様が追加され、リーダの インタフェースにを定義していますが、Python 標準ライブラリではまだ 利用することができません。

DOM 文書オブジェクトを生成したら、そのプロパティとメソッドを使って XML 文書の一部にアクセスできます。これらのプロパティは DOM 仕様で定義されています; 本リファレンスマニュアルでは、 Python において DOM 仕様がどのように解釈されているかを記述しています。

W3C から提供されている仕様は、 DOM API を Java、ECMAScript、および OMG IDL で定義しています。ここで定義されている Python での対応づけは、 大部分がこの仕様の IDL 版に基づいていますが、厳密な準拠は必要と されていません (実装で IDL の厳密な対応付けをサポートするのは自由 ですが)。API への対応付けに関する詳細な議論は 13.6.3 、 ``適合性'' を参照してください。

参考資料:

Document Object Model (DOM) Level 2 Specification
Python DOM API が準拠している W3C 勧告。
Document Object Model (DOM) Level 1 Specification
xml.dom.minidom でサポートされている W3C の DOM に関する勧告。
PyXML
完全な機能をもった DOM 実装を必要とするユーザは PyXML パッケージを利用すべきです。
CORBA Scripting with Python
このドキュメントでは OMG IDL から Python への対応付けを 記述しています。

  • 13.6.1 モジュールの内容
  • 13.6.2 DOM 内のオブジェクト
    • 13.6.2.1 DOMImplementation オブジェクト
    • 13.6.2.2 Node オブジェクト
    • 13.6.2.3 NodeList オブジェクト
    • 13.6.2.4 DocumentType オブジェクト
    • 13.6.2.5 Document オブジェクト
    • 13.6.2.6 Element オブジェクト
    • 13.6.2.7 Attr オブジェクト
    • 13.6.2.8 NamedNodeMap Objects
    • 13.6.2.9 Comment オブジェクト
    • 13.6.2.10 Text オブジェクトおよび CDATASection オブジェクト
    • 13.6.2.11 ProcessingInstruction オブジェクト
    • 13.6.2.12 例外
  • 13.6.3 適合性
    • 13.6.3.1 型の対応付け
    • 13.6.3.2 アクセサメソッド
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.5.5 Expat エラー定数 Up: 13. 構造化マークアップツール Next: 13.6.1 モジュールの内容


13.6.1 モジュールの内容

xml.dom には、以下の関数が収められています:

registerDOMImplementation( name, factory)
ファクトリ関数 (factory function) factory を名前 name で 登録します。ファクトリ関数は DOMImplementation インタフェース を実装するオブジェクトを返さなければなりません。ファクトリ関数は 毎回同じオブジェクトを返すこともでき、呼び出されるたびに、特定の実装 (例えば実装が何らかのカスタマイズをサポートしている場合) における、 適切な新たなオブジェクトを返すこともできます。

getDOMImplementation( [name[, features]])
適切な DOM 実装を返します name は、よく知られた DOM 実装の モジュール名か、None になります。None でない場合、 対応するモジュールを import して、import が成功した場合 DOMImplementation オブジェクトを返します。name が与えられ ておらず、環境変数 PYTHON_DOM が設定されていた場合、 DOM 実装を見つけるのに環境変数が使われます。

name が与えられない場合、 利用可能な実装を調べて、 指定された機能 (feature) セットを持つものを探します。 実装が見つからなければ ImportError を送出します。 features のリストは (feature, version) の ペアからなる配列で、利用可能な DOMImplementation オブジェクト の hasFeature() メソッドに渡されます。

いくつかの便利な定数も提供されています:

EMPTY_NAMESPACE
DOM 内のノードに名前空間が何も関連づけられていないことを示すために 使われる値です。この値は通常、ノードの namespaceURI の値 として見つかったり、名前空間特有のメソッドに対する namespaceURI パラメタとして使われます。 バージョン2.2 以降で新規追加された 仕様です。

XML_NAMESPACE
Namespaces in XML (4 節) で定義されている、予約済みプレフィクス (reserved prefix) xml に関連付けられた名前空間 URI です。 バージョン2.2 以降で新規追加された 仕様です。

XMLNS_NAMESPACE
Document Object Model (DOM) Level 2 Core Specification (1.1.8 節) で定義されている、名前空間宣言への名前空間 URI です。 バージョン2.2 以降で新規追加された 仕様です。

XHTML_NAMESPACE
XHTML 1.0: The Extensible HyperText Markup Language (3.1.1 節) で定義されている、XHTML 名前空間 URI です。 バージョン2.2 以降で新規追加された 仕様です。

加えて、 xml.dom には基底となる Node クラスと DOM 例外クラスが収められています。このモジュールで提供されている Node クラスは DOM 仕様で定義されているメソッドや属性は 何ら実装していません; これらは具体的な DOM 実装において提供 しなければなりません。このモジュールの一部として提供されている Node クラスでは、具体的な Node オブジェクトの nodeType 属性として使う定数を提供しています; これらの 定数は、DOM 仕様に適合するため、クラスではなくモジュールのレベルに 配置されています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6 xml.dom Up: 13.6 xml.dom Next: 13.6.2 DOM 内のオブジェクト


13.6.2 DOM 内のオブジェクト

DOM について最も明確に限定しているドキュメントは W3C による DOM 仕様です。

DOM 属性は単純な文字列としてだけではなく、ノードとして操作される かもしれないので注意してください。とはいえ、そうしなければならない 場合はかなり稀なので、今のところ記述されていません。

インタフェース | 節 | 目的
DOMImplementation | 13.6.2 | 根底にある実装へのインタフェース。
Node | 13.6.2 | ドキュメント内の大部分のオブジェクトのに対する基底インタフェース。
NodeList | 13.6.2 | ノードの配列に対するインタフェース。
DocumentType | 13.6.2 | ドキュメントを処理するために必要な宣言についての情報。
Document | 13.6.2 | ドキュメント全体を表現するオブジェクト。
Element | 13.6.2 | ドキュメント階層内の要素ノード。
Attr | 13.6.2 | 階層ノード上の属性値。
Comment | 13.6.2 | ソースドキュメント内のコメント表現。
Text | 13.6.2 | ドキュメント内のテキスト記述を含むノード。
ProcessingInstruction | 13.6.2 | 処理命令 (processing instruction) 表現。

さらに追加の節として、 Python で DOM を利用するために定義されている 例外について記述しています。

  • 13.6.2.1 DOMImplementation オブジェクト
  • 13.6.2.2 Node オブジェクト
  • 13.6.2.3 NodeList オブジェクト
  • 13.6.2.4 DocumentType オブジェクト
  • 13.6.2.5 Document オブジェクト
  • 13.6.2.6 Element オブジェクト
  • 13.6.2.7 Attr オブジェクト
  • 13.6.2.8 NamedNodeMap Objects
  • 13.6.2.9 Comment オブジェクト
  • 13.6.2.10 Text オブジェクトおよび CDATASection オブジェクト
  • 13.6.2.11 ProcessingInstruction オブジェクト
  • 13.6.2.12 例外
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.1 モジュールの内容 Up: 13.6 xml.dom Next: 13.6.2.1 DOMImplementation オブジェクト


13.6.3 適合性

この節では適合性に関する要求と、Python DOM API、W3C DOM 勧告、 および OMG IDL の Python API への対応付けとの間の関係について 述べます。

  • 13.6.3.1 型の対応付け
  • 13.6.3.2 アクセサメソッド
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.2.12 例外 Up: 13.6 xml.dom Next: 13.6.3.1 型の対応付け


13.7 xml.dom.minidom -- 軽量な DOM 実装

バージョン2.0 以降で新規追加された 仕様です。

xml.dom.minidom は、軽量な文書オブジェクトモデルインタフェース の実装です。この実装では、完全な DOM よりも 単純で、かつ十分に小さくなるよう意図しています。

DOM アプリケーションは典型的に、XML を DOM に解析 (parse) することで 開始します。xml.dom.minidom では、以下のような解析用の関数 を介して行います:

from xml.dom.minidom import parse, parseString

dom1 = parse('c:\\temp\\mydata.xml') # parse an XML file by name

datasource = open('c:\\temp\\mydata.xml')
dom2 = parse(datasource)   # parse an open file

dom3 = parseString('<myxml>Some data<empty/> some more data</myxml>')

parse() 関数はファイル名か、開かれたファイルオブジェクト を引数にとることができます。

parse( filename_or_file, parser)
与えられた入力から Document を返します。 filename_or_file はファイル名でもファイルオブジェクトでもかまいません。parser を指定する場合、SAX2 パーザオブジェクトでなければなりません。 この関数はパーザの文書ハンドラを変更し、名前空間サポートを有効に します; (エンティティリゾルバ (entity resolver) のような) 他のパーザ設定 は前もっておこなわなければなりません。

XML データを文字列で持っている場合、parseString() を 代わりに使うことができます:

parseString( string[, parser])
string を表現する Document を返します。このメソッドは 文字列に対する StringIO オブジェクトを生成して、その オブジェクトを parse に渡します。

これらの関数は両方とも、文書の内容を表現する Document オブジェクトを 返します。

parse() や parseString() といった関数が行うのは、 XML パーザを、何らかの SAX パーザからくる解析イベント (parse event) を受け取って DOM ツリーに変換できるような ``DOM ビルダ (DOM builder)'' に結合することです。関数は誤解を招くような名前になっているかも しれませんが、インタフェースについて学んでいるときには理解しやすい でしょう。文書の解析はこれらの関数が戻るより前に完結します; 要するに、 これらの関数自体はパーザ実装を提供しないということです。

``DOM 実装'' オブジェクトのメソッドを呼び出して Document を 生成することもできます。このオブジェクトは、xml.dom パッケージ、またはxml.dom.minidom モジュールの getDOMImplementation() 関数を呼び出して取得できます。 xml.dom.minidom モジュールの実装を使うと、常に minidom 実装の Document インスタンスを返します。一方、 xml.dom 版の関数では、別の実装によるインスタンスを 返すかもれません (PyXML package がインストールされているとそうなるでしょう)。Document を取得したら、DOM を構成するために子ノードを追加していくことができます:

from xml.dom.minidom import getDOMImplementation

impl = getDOMImplementation()

newdoc = impl.createDocument(None, "some_tag", None)
top_element = newdoc.documentElement
text = newdoc.createTextNode('Some textual content.')
top_element.appendChild(text)

DOM 文書オブジェクトを手にしたら、XML 文書のプロパティやメソッドを 使って、文書の一部にアクセスすることができます。これらのプロパティは DOM 仕様で定義されています。文書オブジェクトの主要なプロパティは documentElement プロパティです。このプロパティは XML 文書の主要な要素: 他の全ての要素を保持する要素、を与えます。 以下にプログラム例を示します:

dom3 = parseString("<myxml>Some data</myxml>")
assert dom3.documentElement.tagName == "myxml"

DOM を使い終えたら、後片付けを行わなければなりません。 Python のバージョンによっては、循環的に互いを参照するオブジェクト に対するガベージコレクションをサポートしていないため、この操作が 必要となります。この制限が全てのバージョンの Python から除去される までは、循環参照オブジェクトが消去されないものとしてコードを 書くのが無難です。

DOM を片付けるには、 unlink() メソッドを呼び出します:

dom1.unlink()
dom2.unlink()
dom3.unlink()

unlink() は、 DOM API に対する xml.dom.minidom 特有の拡張です。ノードに対して unlink() を呼び出した後は、 ノードとその下位ノードは本質的には無意味なものとなります。

参考資料:

Document Object Model (DOM) Level 1 Specification
xml.dom.minidom でサポートされている DOM の W3C 勧告。

  • 13.7.1 DOM オブジェクト
  • 13.7.2 DOM の例
  • 13.7.3 minidom と DOM 標準
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.3.2 アクセサメソッド Up: 13. 構造化マークアップツール Next: 13.7.1 DOM オブジェクト


13.7.1 DOM オブジェクト

Python の DOM API 定義は xml.dom モジュールドキュメント の一部として与えられています。この節では、xml.dom の API と xml.dom.minidom との違いについて列挙します。

unlink( )
DOM との内部的な参照を破壊して、循環参照ガベージコレクションを 持たないバージョンの Python でもガベージコレクションされるように します。循環参照ガベージコレクションが利用できても、このメソッドを 使えば、大量のメモリをすぐに使えるようにできるため、必要なくなったら すぐにこのメソッドを DOM オブジェクトに対して呼ぶのが良い習慣です。 このメソッドは Document オブジェクトに対してだけ呼び出せば よいのですが、あるノードの子ノードを放棄するために子ノードに対して 呼び出してもかまいません。

writexml( writer)
XML を writer オブジェクトに書き込みます。 writer は、ファイルオブジェクトインタフェースの write() に該当する メソッドを持たなければなりません。

バージョン2.1 以降で新規追加された 仕様: 美しい出力をサポートするため、新たなキーワード引数 indent、addindent、および newl が追加されました

バージョン2.3 以降で新規追加された 仕様: Document ノードに対して、追加のキーワード引数 encoding を使って、XML ヘッダの encoding フィールドを指定できるように なりました

toxml( [encoding])
DOM が表現している XML を文字列にして返します。

バージョン2.3 以降で新規追加された 仕様: encoding 引数

引数がなければ、 XML ヘッダは encoding を指定せず、 文書内の全ての文字をデフォルトエンコード方式で表示できない場合、 結果は Unicode 文字列となります。この文字列を UTF-8 以外の エンコード方式でエンコードするのは不正であり、なぜなら UTF-8 が XML のデフォルトエンコード方式だからです。

明示的な encoding 引数があると、結果は指定されたエンコード 方式によるバイト文字列となります。引数を常に指定するよう推奨します。 表現不可能なテキストデータの場合に UnicodeError が送出されるのを 避けるため、encoding 引数は "utf-8" に指定するべきです。

toprettyxml( [indent[, newl]])

美しく出力されたバージョンの文書を返します。indent は インデントを行うための文字で、デフォルトはタブです; newl には行末で出力される文字列を指定し、デフォルトは
n です。

バージョン2.1 以降で新規追加された 仕様です。

バージョン2.3 以降で新規追加された 仕様: encoding 引数の追加; toxml を参照

以下の標準 DOM メソッドは、xml.dom.minidom では特別な 注意をする必要があります:

cloneNode( deep)
このメソッドは Python 2.0 にパッケージされているバージョンの xml.dom.minidom にはありましたが、これには深刻な 障害があります。以降のリリースでは修正されています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.7 xml.dom.minidom Up: 13.7 xml.dom.minidom Next: 13.7.2 DOM の例


13.7.2 DOM の例

以下のプログラム例は、かなり現実的な単純なプログラムの例です。 特にこの例に関しては、DOM の柔軟性をあまり活用してはいません。

import xml.dom.minidom

document = """\
<slideshow>
<title>Demo slideshow</title>
<slide><title>Slide title</title>
<point>This is a demo</point>
<point>Of a program for processing slides</point>
</slide>

<slide><title>Another demo slide</title>
<point>It is important</point>
<point>To have more than</point>
<point>one slide</point>
</slide>
</slideshow>
"""

dom = xml.dom.minidom.parseString(document)

def getText(nodelist):
    rc = ""
    for node in nodelist:
        if node.nodeType == node.TEXT_NODE:
            rc = rc + node.data
    return rc

def handleSlideshow(slideshow):
    print "<html>"
    handleSlideshowTitle(slideshow.getElementsByTagName("title")[0])
    slides = slideshow.getElementsByTagName("slide")
    handleToc(slides)
    handleSlides(slides)
    print "</html>"

def handleSlides(slides):
    for slide in slides:
       handleSlide(slide)

def handleSlide(slide):
    handleSlideTitle(slide.getElementsByTagName("title")[0])
    handlePoints(slide.getElementsByTagName("point"))

def handleSlideshowTitle(title):
    print "<title>%s</title>" % getText(title.childNodes)

def handleSlideTitle(title):
    print "<h2>%s</h2>" % getText(title.childNodes)

def handlePoints(points):
    print "<ul>"
    for point in points:
        handlePoint(point)
    print "</ul>"

def handlePoint(point):
    print "<li>%s</li>" % getText(point.childNodes)

def handleToc(slides):
    for slide in slides:
        title = slide.getElementsByTagName("title")[0]
        print "<p>%s</p>" % getText(title.childNodes)

handleSlideshow(dom)
Download as text (original file name: minidom-example.py).

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.7.1 DOM オブジェクト Up: 13.7 xml.dom.minidom Next: 13.7.3 minidom と DOM


13.7.3 minidom と DOM 標準

xml.dom.minidom モジュールは、本質的には DOM 1.0 互換の DOM に、いくつかの DOM 2 機能 (主に名前空間 機能) を追加したものです。

Python における DOM インタフェースは率直なものです。以下の 対応付け規則が適用されます:

  • インタフェースはインスタンスオブジェクトを介してアクセスされます。 アプリケーション自身から、クラスをインスタンス化してはなりません; Document オブジェクト上で利用可能な生成関数 (creator function) を使わなければなりません。導出インタフェースでは基底インタフェースの 全ての演算 (および属性) に加え、新たな演算をサポートします。

  • 演算はメソッドとして使われます。DOM では in パラメタ のみを使うので、引数は通常の順番 (左から右へ) で渡されます。 オプション引数はありません。void 演算はNone を返します。

  • IDL 属性はインスタンス属性に対応付けられます。OMG IDL 言語 における Python への対応付けとの互換性のために、属性 foo はアクセサメソッド _get_foo() および _set_foo() でもアクセスできます。 readonly 属性は変更しては なりません; とはいえ、これは実行時には強制されません。

  • short int 、 unsigned int 、 unsigned long long 、および boolean 型は、全て Python 整数 オブジェクトに対応付けられます。

  • DOMString 型は Python 文字列型に対応付けられます。 xml.dom.minidom ではバイト文字列 (byte string) および Unicode 文字列のどちらかに対応づけられますが、通常 Unicode 文字列 を生成します。DOMString 型の値は、W3C の DOM 仕様で、IDL null 値になってもよいとされている場所では None に なることもあります。

  • const 宣言を行うと、 (xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE のように) 対応するスコープ内の変数に対応付けを行います; これらは変更してはなりません。

  • DOMException は現状では xml.dom.minidom でサポートされていません。その代わり、xml.dom.minidom は、TypeError や AttributeError といった 標準の Python 例外を使います。

  • NodeList オブジェクトは Python の組み込みリスト型を 使って実装されています。 Python 2.2 からは、これらのオブジェクトは DOM 仕様で定義されたインタフェースを提供していますが、それ以前の バージョンの Python では、公式の API をサポートしていません。 しかしながら、これらの API は W3C 勧告で定義されたインタフェース よりも ``Python 的な'' ものになっています。

以下のインタフェースは xml.dom.minidom では全く実装 されていません:

  • DOMTimeStamp

  • DocumentType (added in Python 2.1)

  • DOMImplementation (added in Python 2.1)

  • CharacterData

  • CDATASection

  • Notation

  • Entity

  • EntityReference

  • DocumentFragment

これらの大部分は、ほとんどの DOM のユーザにとって一般的な用途として有用 とはならないような XML 文書内の情報を反映しています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.7.2 DOM の例 Up: 13.7 xml.dom.minidom Next: 13.8 xml.dom.pulldom


13.8 xml.dom.pulldom -- 部分的な DOM ツリー構築のサポート

バージョン2.0 以降で新規追加された 仕様です。

xml.dom.pulldom では、SAX イベントから、文書の文書オブジェクト モデル表現の選択された一部分だけを構築できるようにします。

class PullDOM( [documentFactory])
xml.sax.handler.ContentHandler 実装です ...

class DOMEventStream( stream, parser, bufsize)
...

class SAX2DOM( [documentFactory])
xml.sax.handler.ContentHandler 実装です ...

parse( stream_or_string[, parser[, bufsize]])
...

parseString( string[, parser])
...

default_bufsize
parse() の bufsize パラメタのデフォルト値です。 バージョン2.1 以降で変更された 仕様: この変数の値は parse() を呼び出す前に 変更することができ、その場合新たな値が効果を持つようになります

  • 13.8.1 DOMEventStream オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.7.3 minidom と DOM Up: 13. 構造化マークアップツール Next: 13.8.1 DOMEventStream オブジェクト


13.8.1 DOMEventStream オブジェクト

getEvent( )
...

expandNode( node)
...

reset( )
...
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.8 xml.dom.pulldom Up: 13.8 xml.dom.pulldom Next: 13.9 xml.sax


13.9 xml.sax -- SAX2 パーサのサポート

バージョン2.0 以降で新規追加された 仕様です。

xml.sax パッケージはPython 用の Simple API for XML (SAX) イン ターフェースを実装した数多くのモジュールを提供しています。またパッケー ジには SAX 例外と SAX API 利用者が頻繁に利用するであろう有用な関数群も 含まれています。

その関数群は以下の通りです:

make_parser( [parser_list])
SAX XMLReader オブジェクトを作成して返します。パーサには最初 に見つかったものが使われます。parser_list を指定する場合は、 create_parser() 関数を含んでいるモジュール名のシーケンス を与える必要があります。parser_list のモジュールはデフォルトの パーサのリストに優先して使用されます。

parse( filename_or_stream, handler[, error_handler])
SAX パーサを作成してドキュメントをパースします。 filename_or_stream として指定するドキュメントはファイル名、ファ イル・オブジェクトのいずれでもかまいません。handler パラメータ には SAX ContentHandler のインスタンスを指定します。 error_handler には SAX ErrorHandler のインスタンスを指 定します。これが指定されていないときは、すべてのエラーで SAXParseException 例外が発生します。関数の戻り値はなく、 すべての処理は handler に渡されます。

parseString( string, handler[, error_handler])
parse() に似ていますが、こちらはパラメータ string で指定されたバッファをパースします。

典型的な SAX アプリケーションでは3種類のオブジェクト(リーダ、ハンドラ、 入力元)が用いられます(ここで言うリーダとはパーサを指しています)。言い 換えると、プログラムはまず入力元からバイト列、あるいは文字列を読み込み、 一連のイベントを発生させます。発生したイベントはハンドラ・オブジェクト によって振り分けられます。さらに言い換えると、リーダがハンドラのメソッ ドを呼び出すわけです。つまり SAX アプリケーションには、リーダ・オブジェ クト、(作成またはオープンされる)入力元のオブジェクト、ハンドラ・オブジェ クト、そしてこれら3つのオブジェクトを連携させることが必須なのです。前 処理の最後の段階でリーダは入力をパースするために呼び出されます。パース の過程で入力データの構造、構文にもとづいたイベントにより、ハンドラ・オ ブジェクトのメソッドが呼び出されます。

これらのオブジェクトは(通常アプリケーション側でインスタンスを作成しな い)インターフェースに相当するものです。Python はインターフェースという 明確な概念を提供していないため、形としてはクラスが用いられています。し かし提供されるクラスを継承せずに、アプリケーション側で独自に実装するこ とも可能です。InputSource、Locator、Attributes、 AttributesNS、XMLReader の各インターフェースは xml.sax.xmlreader モジュールで定義されています。ハンドラ・ インターフェースは xml.sax.handler で定義されています。し ばしばアプリケーション側で直接インスタンスが作成される InputSource とハンドラ・クラスは利便性のため xml.sax にも含まれています。これらのインターフェースに関しては後に解説します。

このほかに xml.sax は次の例外クラスも提供しています。

exception SAXException( msg[, exception])
XML エラーと警告をカプセル化します。このクラスには XML パーサとアプ リケーションで発生するエラーおよび警告の基本的な情報を持たせることが できます。また機能追加や地域化のためにサブクラス化することも可能です。 なお ErrorHandler で定義されているハンドラがこの例外のインス タンスを受け取ることに注意してください。実際に例外を発生させることは 必須でなく、情報のコンテナとして利用されることもあるからです。

インスタンスを作成する際 msg はエラー内容を示す可読データにし てください。オプションの exception パラメータは None も しくはパース用コードで補足、渡って来る情報でなければなりません。

このクラスはSAX 例外の基底クラスになります。

exception SAXParseException( msg, exception, locator)
パースエラー時に発生する SAXException のサブクラスです。 パースエラーに関する情報として、このクラスのインスタンスが SAX ErrorHandler インターフェースのメソッドに渡されます。このク ラスは SAXException 同様 SAX Locator インターフェー スもサポートしています。

exception SAXNotRecognizedException( msg[, exception])
SAX XMLReader が認識できない機能やプロパティに遭遇したとき発 生させる SAXException のサブクラスです。SAX アプリケーショ ンや拡張モジュールにおいて同様の目的にこのクラスを利用することもでき ます。

exception SAXNotSupportedException( msg[, exception])
SAX XMLReader が要求された機能をサポートしていないとき発生さ せる SAXException のサブクラスです。SAX アプリケーション や拡張モジュールにおいて同様の目的にこのクラスを利用することもできま す。

参考資料:

SAX: The Simple API for XML
SAX API 定義に関し中心となっているサイトです。Java に よる実装とオンライン・ドキュメントが提供されています。実装 と SAX API の歴史に関する情報のリンクも掲載されています。

xml.sax.handlerモジュール:
アプリケーションが提供するオブジェクトの インターフェース定義.

xml.sax.saxutilsモジュール:
SAX アプリケーション向けの有用な関数群.

xml.sax.xmlreaderモジュール:
パーサが提供するオブジェクトのインター フェース定義.

  • 13.9.1 SAXException オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.8.1 DOMEventStream オブジェクト Up: 13. 構造化マークアップツール Next: 13.9.1 SAXException オブジェクト


13.9.1 SAXException オブジェクト

SAXException 例外クラスは以下のメソッドをサポートしています。

getMessage( )
エラー状態を示す可読メッセージを返します。

getException( )
カプセル化した例外オブジェクトまたは None を返します。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.9 xml.sax Up: 13.9 xml.sax Next: 13.10 xml.sax.handler


13.10 xml.sax.handler -- SAX ハンドラの基底クラス

バージョン2.0 以降で新規追加された 仕様です。

SAX API はコンテント・ハンドラ、DTD ハンドラ、エラー・ハンドラ、エンティ ティ・リゾルバという4つのハンドラを規定しています。通常アプリケーショ ン側で実装する必要があるのは、これらのハンドラが発生させるイベントのう ち、処理したいものへのインターフェースだけです。インターフェースは1つ のオブジェクトにまとめることも、複数のオブジェクトに分けることも可能で す。ハンドラはすべてのメソッドがデフォルトで実装されるように、 xml.sax で提供される基底クラスを継承しなくてはなりません。

class ContentHandler
アプリケーションにとって最も重要なメインの SAX コールバック・インター フェースです。このインターフェースで発生するイベントの順序はドキュメ ント内の情報の順序を反映しています。

class DTDHandler
DTD イベントのハンドラです。

未構文解析エンティティや属性など、パースに必要な DTD イベントの抽出 だけをおこなうインターフェースです。

class EntityResolver
エンティティ解決用の基本インターフェースです。このインターフェースを 実装したオブジェクトを作成しパーサに登録することで、パーサはすべての 外部エンティティを解決するメソッドを呼び出すようになります。

class ErrorHandler
エラーや警告メッセージをアプリケーションに通知するためにパーサが使用 するインターフェースです。このオブジェクトのメソッドが、エラーをただ ちに例外に変換するか、あるいは別の方法で処理するかの制御をしています。

これらのクラスに加え、xml.sax.handler は機能やプロパティ名の シンボル定数を提供しています。

feature_namespaces
値: "http://xml.org/sax/features/namespaces"
true: 名前空間の処理を有効にする。
false: オプションで名前空間の処理を無効にする (暗黙に namespace-prefixes も無効にする - デフォルト )。
アクセス: (パース時) リードオンリー; (パース時以外) 読み書き可

feature_namespace_prefixes
値: "http://xml.org/sax/features/namespace-prefixes"
true: 名前空間宣言で用いられているオリジナルのプリフィックス名と属性 を通知する。
false: 名前空間宣言で用いられている属性を通知しない。 オプションでオリジナルのプリフィックス名も通知しない(デフォルト)。
アクセス: (パース時) リードオンリー; (パース時以外) 読み書き可

feature_string_interning
値: "http://xml.org/sax/features/string-interning" true: すべての要素名、プリフィックス、属性、名前、名前空間、URI、 ローカル名を組込みの intern 関数を使ってシンボルに登録する。
false: 名前のすべてを必ずしもシンボルに登録しない(デフォルト)。
アクセス: (パース時) リードオンリー; (パース時以外) 読み書き可

feature_validation
値: "http://xml.org/sax/features/validation"
true: すべての妥当性検査エラーを通知する(external-general-entities とexternal-parameter-entities が暗黙の前提になっている)。
false: 妥当性検査エラーを通知しない。
アクセス: (パース時) リードオンリー; (パース時以外) 読み書き可

feature_external_ges
値: "http://xml.org/sax/features/external-general-entities"
true: 外部一般(テキスト)エンティティの取り込みをおこなう。
false: 外部一般エンティティを取り込まない。
アクセス: (パース時) リードオンリー; (パース時以外) 読み書き可

feature_external_pes
値: "http://xml.org/sax/features/external-parameter-entities"
true: 外部 DTD サブセットを含むすべての外部パラメータ・エンティティ の取り込みをおこなう。
false: 外部パラーメタ・エンティティおよび外部 DTD サブセットを取り込 まない。
アクセス: (パース時) リードオンリー; (パース時以外) 読み書き可

all_features
すべての機能の一覧。

property_lexical_handler
値: "http://xml.org/sax/properties/lexical-handler"
data type: xml.sax.sax2lib.LexicalHandler (Python 2 では未サポート)
description: コメントなど字句解析イベント用のオプション拡張ハンドラ。
アクセス: 読み書き可

property_declaration_handler
Value: "http://xml.org/sax/properties/declaration-handler"
data type: xml.sax.sax2lib.DeclHandler (Python 2 では未サポート)
description: ノーテーションや未解析エンティティをのぞく DTD 関連イベン ト用のオプション拡張ハンドラ。
access: read/write

property_dom_node
Value: "http://xml.org/sax/properties/dom-node"
data type: org.w3c.dom.Node (Python 2 では未サポート)
description: パース時は DOM イテレータにおけるカレント DOM ノード、 非パース時はルート DOM ノードを指す。
アクセス: (パース時) リードオンリー; (パース時以外) 読み書き可

property_xml_string
値: "http://xml.org/sax/properties/xml-string"
データ型: 文字列
説明: カレント・イベントの元になったリテラル文字列
アクセス: リードオンリー

all_properties
既知のプロパティ名の全リスト。

  • 13.10.1 ContentHandler オブジェクト
  • 13.10.2 DTDHandler オブジェクト
  • 13.10.3 EntityResolver オブジェクト
  • 13.10.4 ErrorHandler オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.9.1 SAXException オブジェクト Up: 13. 構造化マークアップツール Next: 13.10.1 ContentHandler オブジェクト


13.10.1 ContentHandler オブジェクト

ContentHandler はアプリケーション側でサブクラス化して利用する ことが前提になっています。パーサは入力ドキュメントのイベントにより、そ れぞれに対応する以下のメソッドを呼び出します。

setDocumentLocator( locator)
アプリケーションにドキュメント・イベントの発生位置を通知するためにパー サから呼び出されます。

SAX パーサによるロケータの提供は強く推奨されています(必須ではありま せん)。もし提供する場合は、DocumentHandler インターフェースのどのメ ソッドよりも先にこのメソッドが呼び出されるようにしなければなりません。

アプリケーションはパーサがエラーを通知しない場合でもロケータによって、 すべてのドキュメント関連イベントの終了位置を知ることが可能になります。 典型的な利用方法としては、アプリケーション側でこの情報を使い独自のエ ラーを発生させること(文字コンテンツがアプリケーション側で決めた規則 に沿っていない場合等)があげられます。しかしロケータが返す情報は検索 エンジンなどで利用するものとしてはおそらく不充分でしょう。

ロケータが正しい情報を返すのは、インターフェースからイベントの呼出し が実行されている間だけです。それ以外のときは使用すべきでありません。

startDocument( )
ドキュメントの開始通知を受け取ります。

SAX パーサはこのインターフェースやDTDHandler のどのメソッド (setDocumentLocator()を除く)よりも先にこのメソッドを一度だ け呼び出します。

endDocument( )
ドキュメントの終了通知を受け取ります。

SAX パーサはこのメソッドを一度だけ、パース過程の最後に呼び出します。 パーサは(回復不能なエラーで)パース処理を中断するか、あるいは入力の 最後に到達するまでこのメソッドを呼び出しません。

startPrefixMapping( prefix, uri)
プリフィックスと URI の名前空間の関連付けを開始します。

このイベントから返る情報は通常の名前空間処理では使われません。SAX XML リーダは feature_namespaces 機能が有効になっている場合(デ フォルト)、要素と属性名のプリフィックスを自動的に置換するようになっ ています。

しかしアプリケーション側でプリフィックスを文字データや属性値の中で扱 う必要が生じることもあります。この場合プリフィックスの自動展開は保証 されないため、必要に応じ startPrefixMapping() や endPrefixMapping() イベントからアプリケーションに提供される 情報を用いてプリフィックスの展開をおこないます。

startPrefixMapping() と endPrefixMapping() イベン
  トは相互に正しい入れ子関係になることが保証されていないので注意が必要
  です。すべての startPrefixMapping() は対応する
  startElement() の前に発生し、endPrefixMapping() イ
  ベントは対応する endElement() の後で発生しますが、その順序
  は保証されていません。

endPrefixMapping( prefix)
プリフィックスと URI の名前空間の関連付けを終了します。

詳しくは startPrefixMapping() を参照してください。このイベ
  ントは常に対応する endElement() の後で発生しますが、複数の
  endPrefixMapping() イベントの順序は特に保証されません。

startElement( name, attrs)
非名前空間モードで要素の開始を通知します。

name パラーメータには要素型の raw XML 1.0名を文字列として、 attrs パラメータには要素の属性を保持する Attributes インターフェース オブジェクトをそれぞれ指定します。attrs として渡されたオブジェ クトはパーサで再利用することも可能ですが、属性のコピーを保持するた めにこれを参照し続けるのは確実な方法ではありません。属性のコピーを保 持したいときは attrs オブジェクトの copy() メソッドを 用いてください。

endElement( name)
非名前空間モードで要素の終了を通知します。

name パラメータには startElement() イベント同様の要素 型名を指定します。

startElementNS( name, qname, attrs)
名前空間モードで要素の開始を通知します。

name パラーメータには要素型を (uri, localname) のタプルとして、qname パラメータにはソース・ ドキュメントで用いられている raw XML 1.0名、attrs には要素の属 性を保持する AttributesNS インターフェース のインスタンスをそれぞれ指定します。要 素に関連付けられた名前空間がないときは、name コンポーネントの uri が None になります。attrs として渡されたオブジェ クトはパーサで再利用することも可能ですが、属性のコピーを保持するた めにこれを参照し続けるのは確実な方法ではありません。属性のコピーを保 持したいときは attrs オブジェクトの copy() メソッドを 用いてください。

feature_namespace_prefixes 機能が有効になっていなければ、パー サで qname を None にセットすることも可能です。

endElementNS( name, qname)
非名前空間モードで要素の終了を通知します。

name パラメータには startElementNS() イベント同様の要素 型を指定します。qname パラメータも同じです。

characters( content)
文字データの通知を受け取ります。

パーサは文字データのチャンクごとにこのメソッドを呼び出して通知します。 SAX パーサは一連の文字データを単一のチャンクとして返す場合と複数のチャ ンクに分けて返す場合がありますが、ロケータの情報が正しく保たれるよう に、一つのイベントの文字データは常に同じ外部エンティティのものでなけ ればなりません。

content はユニコード文字列、バイト文字列のどちらでもかまいませ んが、expat リーダ・モジュールは常にユニコード文字列を生成す るようになっています。

注意: Python XML SIG が提供していた初期 SAX 1 では、このメソッドにもっ と JAVA 風のインターフェースが用いられています。しかし Python で採用 されている大半のパーサでは古いインターフェースを有効に使うことができ ないため、よりシンプルなものに変更されました。古いコードを新しいイン ターフェースに変更するには、古い offset と length パラメー タでスライスせずに、content を指定するようにしてください。

ignorableWhitespace( )
要素コンテンツに含まれる無視可能な空白文字の通知を受け取ります。

妥当性検査をおこなうパーサは無視可能な空白文字(W3C XML 1.0 勧告のセ クション 2.10 参照)のチャンクごとに、このメソッドを使って通知しなけ ればなりません。妥当性検査をしないパーサもコンテンツモデルの利用とパー スが可能な場合、このメソッドを利用することが可能です。

SAX パーサは一連の空白文字を単一のチャンクとして返す場合と複数のチャ ンクに分けて返す場合がありますが、ロケータの情報が正しく保たれるよう に、一つのイベントの文字データは常に同じ外部エンティティのものでなけ ればなりません。

processingInstruction( target, data)
処理命令の通知を受け取ります。

パーサは処理命令が見つかるたびにこのメソッドを呼び出します。処理命令 はメインのドキュメント要素の前や後にも発生することがあるので注意して ください。

SAX パーサがこのメソッドを使って XML 宣言(XML 1.0 のセクション 2.8)や テキスト宣言(XML 1.0 のセクション 4.3.1)の通知をすることはありません。

skippedEntity( name)
スキップしたエンティティの通知を受け取ります。

パーサはエンティティをスキップするたびにこのメソッドを呼び出します。 妥当性検査をしないプロセッサは(外部 DTD サブセットで宣言されているな どの理由で)宣言が見当たらないエンティティをスキップします。すべての プロセッサは feature_external_ges および feature_external_pes 属性の値によっては外部エンティティをスキッ プすることがあります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.10 xml.sax.handler Up: 13.10 xml.sax.handler Next: 13.10.2 DTDHandler オブジェクト


13.10.2 DTDHandler オブジェクト

DTDHandler インスタンスは以下のメソッドを提供します。

notationDecl( name, publicId, systemId)
表記法宣言イベントの通知を捕捉します。

unparsedEntityDecl( name, publicId, systemId, ndata)
未構文解析エンティティ宣言イベントの通知を受け取ります Handle an unparsed entity declaration event.

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.10.1 ContentHandler オブジェクト Up: 13.10 xml.sax.handler Next: 13.10.3 EntityResolver オブジェクト


13.10.3 EntityResolver オブジェクト

resolveEntity( publicId, systemId)
エンティティのシステム識別子を解決し、文字列として読み込んだシステム 識別子あるいは InputSource オブジェクトのいずれかを返します。デフォ ルトの実装では systemId を返します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.10.2 DTDHandler オブジェクト Up: 13.10 xml.sax.handler Next: 13.10.4 ErrorHandler オブジェクト


13.10.4 ErrorHandler オブジェクト

このインターフェースのオブジェクトは XMLReader からのエラーや 警告の情報を受け取るために使われます。このインターフェースを実装したオ ブジェクトを作成し XMLReader に登録すると、パーサは警告やエラー の通知のためにそのオブジェクトのメソッドを呼び出すようになります。エラー には警告、回復可能エラー、回復不能エラーの3段階があります。すべてのメ ソッドは SAXParseException だけをパラメータとして受け取り ます。受け取った例外オブジェクトを raise することで、エラーや警告は例 外に変換されることもあります。

error( exception)
パーサが回復可能なエラーを検知すると呼び出されます。このメソッドが例 外を raise しないとパースは継続されますが、アプリケーション側では エラー以降のドキュメント情報を期待していないこともあります。パー サが処理を継続した場合、入力ドキュメント内のほかのエラーを見つけるこ とができます。

fatalError( exception)
パーサが回復不能なエラーを検知すると呼び出されます。このメソッドが return した後、すぐにパースを停止することが求められています。

warning( exception)
パーサが軽微な警告情報をアプリケーションに通知するために呼び出されま す。このメソッドが return した後もパースを継続し、ドキュメント情報を アプリケーションに送り続けるよう求められています。このメソッドで例外 を発生させた場合、パースは中断されてしまいます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.10.3 EntityResolver オブジェクト Up: 13.10 xml.sax.handler Next: 13.11 xml.sax.saxutils


13.11 xml.sax.saxutils -- SAX ユーティリティ

バージョン2.0 以降で新規追加された 仕様です。

モジュール xml.sax.saxutils には SAX アプリケーションの作成に 役立つ多くの関数やクラスも含まれており、直接利用したり、基底クラスとし て使うことができます。

escape( data[, entities])
文字列データ内の "&"、"<"、">" をエス ケープします。

オプションの entities パラメータに辞書を渡すことで、そのほ かの文字をエスケープさせることも可能です。辞書のキーと値はすべて文字列 で、キーに指定された文字は対応する値に置換されます。

unescape( data[, entities])
エスケープされた文字列 "&amp;"、"&lt;"、 "&gt;" を元の文字に戻します。

オプションの entities パラメータに辞書を渡すことで、そのほ かの文字をエスケープさせることも可能です。辞書のキーと値はすべて文字列 で、キーに指定された文字は対応する値に置換されます。 バージョン2.3 以降で新規追加された 仕様です。

quoteattr( data[, entities])
escape() に似ていますが、data は属性値の作成に使わ れます。戻り値はクォート済みの data で、置換する文字の追加も可 能です。quoteattr() はクォートすべき文字を data の 文脈から判断し、クォートすべき文字を残さないように文字列をエンコード します。

data の中にシングル・クォート、ダブル・クォートがあれば、両方 ともエンコードし、全体をダブルクォートで囲みます。戻り値の文字列はその ままで属性値として利用できます。:

>>> print "<element attr=%s>" % quoteattr("ab ' cd \" ef")
<element attr="ab ' cd &quot; ef">

この関数は参照具象構文を使って、 HTML や SGML の属性値を生成するのに 便利です。 バージョン2.2 以降で新規追加された 仕様です。

class XMLGenerator( [out[, encoding]])
このクラスは ContentHandler インターフェースの実装で、SAX イ ベントを XML ドキュメントに書き戻します。つまり、 XMLGenerator をコンテント・ハンドラとして用いると、パースし たオリジナル・ドキュメントの複製が作れるのです。out に指定する のはファイル風のオブジェクトで、デフォルトは sys.stdout です。 encoding は出力ストリームのエンコーディングで、デフォルトは 'iso-8859-1' です。

class XMLFilterBase( base)
このクラスは XMLReader とクライアント・アプリケーションのイ ベント・ハンドラとの間に位置するものとして設計されています。デフォル トでは何もせず、ただリクエストをリーダに、イベントをハンドラに、それ ぞれ加工せず渡すだけです。しかし、サブクラスでメソッドをオーバーライ ドすると、イベント・ストリームやリクエストを加工してから渡すように変 更可能です。

prepare_input_source( source[, base])
この関数は引き数に入力ソース、オプションとして URL を取り、読み取り 可能な解決済み InputSource オブジェクトを返します。入力ソー スは文字列、ファイル風オブジェクト、InputSource のいずれでも 良く、この関数を使うことで、パーサは様々な source パラメータを parse() に渡すことが可能になります。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.10.4 ErrorHandler オブジェクト Up: 13. 構造化マークアップツール Next: 13.12 xml.sax.xmlreader


13.12 xml.sax.xmlreader -- XML パーサのインターフェース

バージョン2.0 以降で新規追加された 仕様です。

各 SAX パーサは Python モジュールとして XMLReader インターフェー スを実装しており、関数 create_parser() を提供しています。こ の関数は新たなパーサ・オブジェクトを生成する際、 xml.sax.make_parser() から引き数なしで呼び出されます。

class XMLReader( )
SAX パーサが継承可能な基底クラスです。

class IncrementalParser( )

入力ソースをパースする際、すべてを一気に処理しないで、途中でドキュメ ントのチャンクを取得したいことがあります。SAX リーダは通常、ファイル 全体を一気に読み込まずチャンク単位で処理するのですが、全体の処理が終 わるまで parse() は return しません。つまり、 IncrementalParser インターフェースは parse() にこのような排 他的挙動を望まないときに使われます。

パーサのインスタンスが作成されると、feed メソッドを通じてすぐに、デー タを受け入れられるようになります。close メソッドの呼出しでパースが終 わると、パーサは新しいデータを受け入れられるように、reset メソッドを 呼び出されなければなりません。

これらのメソッドをパース処理の途中で呼び出すことはできません。つまり、 パースが実行された後で、パーサから return する前に呼び出す必要がある のです。

なお、SAX 2.0 ドライバを書く人のために、XMLReader インターフェースの parse メソッドがデフォルトで、IncrementalParser の feed、close、 reset メソッドを使って実装されています。

class Locator( )

SAX イベントとドキュメントの位置を関連付けるインターフェースです。 locator オブジェクトは DocumentHandler メソッドを呼び出している間 だけ正しい情報を返し、それ以外とのときに呼び出すと、予測できない結果 が返ります。情報を取得できない場合、メソッドは None を返すこ ともあります。

class InputSource( [systemId])
XMLReader がエンティティを読み込むために必要な情報をカプセ ル化します。

このクラスには公開識別子、システム識別子、(場合によっては文字エンコー ディング情報を含む)バイト・ストリーム、そしてエンティティの文字スト リームなどの情報が含まれます。

アプリケーションは XMLReader.parse() メソッドに渡す引き数、 または EntityResolver.resolveEntity の戻り値としてこのオブジェトを作 成します。

InputSource はアプリケーション側に属します。 XMLReader はアプリケーションから渡された InputSource オブジェクトの変更を許していませんが、コピーを作り、それを変更するこ とは可能です。

class AttributesImpl( attrs)
Attributes interface ( 13.12.5 参照)の実装です。辞書風のオブジェクトで、 startElement() 内で要素の属性表示をおこないます。多くの辞書 風オブジェクト操作に加え、ほかにもインターフェースに記述されているメ ソッドを、多数サポートしています。このクラスのオブジェクトはリーダ によってインスタンスを作成しなければなりません。また、attrs は 属性名と属性値を含む辞書風オブジェクトでなければなりません。

class AttributesNSImpl( attrs, qnames)
AttributesImpl を名前空間認識型に改良したクラスで、 startElementNS() に渡されます。AttributesImpl の派 生クラスですが、namespaceURI と localname、この2つのタプ ルを解釈します。さらに、元のドキュメントに出てくる修飾名を返す多くの メソッドを提供します。このクラスは AttributesNS interface ( section 13.12.6 参照) の実装です。

  • 13.12.1 XMLReader オブジェクト
  • 13.12.2 IncrementalParser オブジェクト
  • 13.12.3 Locator オブジェクト
  • 13.12.4 InputSource オブジェクト
  • 13.12.5 The Attributes インターフェース
  • 13.12.6 AttributesNS インターフェース
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.11 xml.sax.saxutils Up: 13. 構造化マークアップツール Next: 13.12.1 XMLReader オブジェクト


13.12.1 XMLReader オブジェクト

XMLReader は次のメソッドをサポートします。:

parse( source)
入力ソースを処理し、SAX イベントを発生させます。source オブジェ クトにはシステム識別子(入力ソースを特定する文字列 - 一般にファイル 名やURL)、ファイル風オブジェクト、または InputSource オブジェ クトを指定できます。parse() から return された段階で、入力 データの処理は完了、パーサ・オブジェクトは破棄ないしリセットされます。 なお、現在の実装はバイト・ストリームのみをサポートしており、文字スト リームの処理は将来の課題になっています。

getContentHandler( )
現在の ContentHandler を返します。

setContentHandler( handler)
現在の ContentHandler をセットします。ContentHandler がセットされていない場合、コンテント・イベントは破棄されます。

getDTDHandler( )
現在の DTDHandler を返します。

setDTDHandler( handler)
現在の DTDHandler をセットします。DTDHandler がセッ トされていない場合、DTD イベントは破棄されます。

getEntityResolver( )
現在の EntityResolver を返します。

setEntityResolver( handler)
現在の EntityResolver をセットします。EntityResolver がセットされていない場合、外部エンティティとして解決されるべきものが、 システム識別子として解釈されてしまうため、該当するものがなければ結果 的にエラーとなります。

getErrorHandler( )
現在の ErrorHandler を返します。

setErrorHandler( handler)
現在のエラー・ハンドラをセットします。ErrorHandler がセット されていない場合、エラーは例外を発生し、警告が表示されます。

setLocale( locale)
アプリケーションにエラーや警告のロカール設定を許可します。

SAX パーサにとって、エラーや警告の地域化は必須ではありません。しかし、 パーサは要求されたロカールをサポートしていない場合、SAX 例外を発生さ せなければなりません。アプリケーションはパースの途中でロカールを変更 することもできます。

getFeature( featurename)
機能 featurename の現在の設定を返します。その機能が認識できな いときは、SAXNotRecognizedException を発生させます。広く 使われている機能名の一覧はモジュール xml.sax.handler に書か れています。

setFeature( featurename, value)
機能名 featurename に値 value をセットします。その機能が 認識できないときは、SAXNotRecognizedException を発生させ ます。また、パーサが指定された機能や設定をサポートしていないとき は、SAXNotSupportedException を発生させます。

getProperty( propertyname)
属性名 propertyname の現在の値を返します。その属性が認識でき ないときは、 SAXNotRecognizedException を発生させます。 広く使われている属性名の一覧はモジュール xml.sax.handler に 書かれています。

setProperty( propertyname, value)
属性名 propertyname に値 value をセットします。その機能 が認識できないときは、SAXNotRecognizedException を発生さ せます。また、パーサが指定された機能や設定をサポートしていないときは、 SAXNotSupportedException is raised を発生させます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.12 xml.sax.xmlreader Up: 13.12 xml.sax.xmlreader Next: 13.12.2 IncrementalParser オブジェクト


13.12.2 IncrementalParser オブジェクト

IncrementalParser のインスタンスは次の追加メソッドを提供します。:

feed( data)
data のチャンクを処理します。

close( )
ドキュメントの終わりを決定します。終わりに達した時点でドキュメントが 整形式であるかどうかを判別、ハンドラを起動後、パース時に使用した資源 を解放します。

reset( )
このメソッドは close が呼び出された後、次のドキュメントをパース可能 にするため、パーサのリセットするのに呼び出されます。close 後、reset を呼び出さずに parse や feed を呼び出した場合の戻り値は未定義です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.12.1 XMLReader オブジェクト Up: 13.12 xml.sax.xmlreader Next: 13.12.3 Locator オブジェクト


13.12.3 Locator オブジェクト

Locator のインスタンスは次のメソッドを提供します。:

getColumnNumber( )
現在のイベントが終了する列番号を返します。

getLineNumber( )
現在のイベントが終了する行番号を返します。

getPublicId( )

現在の文書イベントの公開識別子を返します。
getSystemId( )
現在のイベントのシステム識別子を返します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.12.2 IncrementalParser オブジェクト Up: 13.12 xml.sax.xmlreader Next: 13.12.4 InputSource オブジェクト


13.12.4 InputSource オブジェクト

setPublicId( id)
この InputSource の公開識別子をセットします。

getPublicId( )
この InputSource の公開識別子を返します。

setSystemId( id)
この InputSource のシステム識別子をセットします。

getSystemId( )
この InputSource のシステム識別子を返します。

setEncoding( encoding)
この InputSource の文字エンコーディングをセットします。

指定するエンコーディングは XML エンコーディング宣言として定義された 文字列でなければなりません(セクション 4.3.3 の XML 勧告を参照)。

InputSource のエンコーディング属性は、InputSource が たとえ文字ストリームを含んでいたとしても、無視されます。

getEncoding( )
この InputSource の文字エンコーディングを取得します。

setByteStream( bytefile)
この入力ソースのバイトストリーム(Python のファイル風オブジェクトです が、バイト列と文字の相互変換はサポートしません)を設定します。

なお、文字ストリームが指定されてもSAX パーサは無視し、バイト・ストリー ムを使って指定された URI に接続しようとします。

アプリケーション側でバイト・ストリームの文字エンコーディングを知って いる場合は、setEncoding メソッドを使って指定する必要があります。

getByteStream( )
この入力ソースのバイトストリームを取得します。

getEncoding メソッドは、このバイト・ストリームの文字エンコーディング を返します。認識できないときは None を返します。

setCharacterStream( charfile)
この入力ソースの文字ストリームをセットします(ストリームは Python 1.6 の Unicode-wrapped なファイル風オブジェクトで、ユニコード文字列への 変換をサポートしていなければなりません)。

なお、文字ストリームが指定されても SAX パーサは無視、システム識別子 とみなし、バイト・ストリームを使って URI に接続しようとします。

getCharacterStream( )
この入力ソースの文字ストリームを取得します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.12.3 Locator オブジェクト Up: 13.12 xml.sax.xmlreader Next: 13.12.5 The Attributes インターフェース


13.12.5 The Attributes インターフェース

Attributes オブジェクトは copy()、get()、
has_key()、items()、 keys()、
values() などを含む、マッピング・プロトコルの一部を実装したも
のです。さらに次のメソッドも提供されています。:

getLength( )
属性の数を返す。

getNames( )
属性の名前を返す。

getType( name)
属性名 name のタイプを返す。通常は 'CDATA'。

getValue( name)
属性 name の値を返す。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.12.4 InputSource オブジェクト Up: 13.12 xml.sax.xmlreader Next: 13.12.6 AttributesNS インターフェース


13.12.6 AttributesNS インターフェース

このインターフェースは Attributes interface (セクション 13.12.5参照) のサブタイプです。 Attributes インターフェー スがサポートしているすべてのメソッドは AttributesNS オブジェク トでも利用可能です。

そのほか、次のメソッドがサポートされています。:

getValueByQName( name)
修飾名の値を返す。

getNameByQName( name)
修飾名 name に対応する (namespace, localname) のペアを返す。

getQNameByName( name)
(namespace, localname) のペアに対応する修飾名を返す。

getQNames( )
すべての属性の修飾名を返す。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.12.5 The Attributes インターフェース Up: 13.12 xml.sax.xmlreader Next: 13.13 xmllib


13.13 xmllib -- XML ドキュメントのパーサ

リリース 2.0 以降で撤廃された仕様です。 代わりに xml.sax を使ってください。新しい XML パッケージは XML 1.0 をフルにサポートしています。

バージョン1.5.2 以降で変更された 仕様: 名前空間のサポートを追加

このモジュールには XML (Extensible Markup Language) 形式で記述されたテ キストファイルのパースに必要な基本機能を提供する XMLParser ク ラスが定義されています。

class XMLParser( )
XMLParser XMLParser クラスのインスタンス生成は引数を指定せずにおこ ないます。 13.1

このクラスは次のインターフェース・メソッドとインスタンス変数を提供して います。

attributes
要素名のマッピングへのマッピング・オブジェクトで、デフォルトは空の辞書 です。このデフォルト変数はすべての XMLParser インスタンスで 共有されるため、継承せずにオーバーライドする必要があります。なお、要素 名のマッピングの方は、その要素に妥当な属性名とそのデフォルトの属性値を マッピングしており、デフォルト値がない場合は None になります。

elements
要素名からタプルへのマッピングです。タプルには要素の開始タグと終了タグ をそれぞれ処理する関数、または unknown_starttag() や unknown_endtag() 呼出された場合に使用する None が含ま れます。デフォルトは空の辞書になっています。このデフォルト変数はすべての XMLParser インスタンスで共有されるため、継承せずにオーバーライ ドする必要があります。

entitydefs
エンティティ名からその値へのマッピングです。デフォルトで 'lt'、 'gt'、 'amp'、 'quot'、 and 'apos' の定義 がされています。

reset( )
インスタンスをリセットします。同時に未処理のデータはすべて失われます。 このメソッドはインスタンス生成時、暗黙裡に呼び出されます。

setnomoretags( )
タグの処理を中止します。このメソッドの呼び出し以降、すべての入力はリテラ ル(CDATA)として扱われます。

setliteral( )
リテラルモード(CDATA mode)に入ります。このモードは最後に処理した開始タ グに対応する終了タグが見つかった時点で自動的に終了します。

feed( data)
テキストをパーサに送ります。完全なタグで構成された部分までを処理し、不 完全なタグは次のデータが来るか close() が呼び出されるまでバッ ファリングされます。

close( )
現在バッファリング中のデータの前に end-of-file ファイルが来たものと強 制的にみなします。このメソッドは派生クラスにおいて、入力終了時におこな う追加処理のために再定義されることもありますが、再定義したメソッドの中 で必ずこの close() を呼び出さなければなりません。

translate_references( data)
data の中にある実体参照と文字参照をすべて変換し、変換後 の文字列を返します。

getnamespace( )
現在有効な名前空間の短縮名から名前空間 URI へのマッピングを返します。

handle_xml( encoding, standalone)
このメソッドは "<?xml ...?>" タグを処理します。引数はタグ中のエン コーディングの値とスタンドアロン宣言です。エンコーディングとスタンドア ロン属性はともにオプションです。デフォルトはそれぞれ None と文 字列 'no' になります。

handle_doctype( tag, pubid, syslit, data)

このメソッドは "<!DOCTYPE...>" 宣言を 処理します。引数にはルート要素のタグ名、公式公開識別子(指定されていない場合は None)、システム識別 子、および内部 DTD サブセットを処理せずそのまま文字列で指定します(指定 されていない場合は None)。

handle_starttag( tag, method, attributes)
このメソッドはインスタンス変数 elements にハンドラが定義され ている開始タグを処理します。tag はタグ名で、method は開始 タグの意味解析サポートに使われる関数(メソッド)です。attributes は <> タグ内に記述されている属性名がキー、属性値を値として持つ 辞書になります。文字およびエンティティの参照は解釈されます。たとえば、 開始タグ <A HREF="http://www.cwi.nl/"> に対するこのメドッドの呼 出しは handle_starttag('A', self.elements['A'][0], {'HREF': 'http://www.cwi.nl/'}) となります。基本的な実装は単純で、引数に attributes を使い、method を呼び出すだけのものです。

handle_endtag( tag, method)
このメソッドはインスタンス変数 elements にハンドラが定義され ている終了タグを処理します。tag はタグ名で、method は終了 タグの意味解析サポートに使われる関数(メソッド)です。たとえば、終了タグ </A> に対するこのメドッドの呼出しは handle_endtag('A', self.elements['A'][1]) となります。基本的な実装は単純で、method を呼び出すだけのものです。

handle_data( data)
これは任意のデータを処理するメソッドです。派生クラスでオーバライドして 使います。基底クラスの実装では何もおこないません。

handle_charref( ref)
このメソッドは "&#ref;" 形式の文字参照を処理します。 ref は10進数または頭に"x"を付けた16進数のどちらでもか まいません。基本実装おいて ref の値として許される範囲は0から255 までに限定されています。この値が ASCII に変換された後、その文字列を 引数にしてメソッド handle_data() が呼び出されます。ref の値が許容範囲外のときは、エラーハンドリングのために unknown_charref(ref) が呼び出されます。ASCII 範囲外の 文字をサポートするには、サブクラスでこのメソッドをオーバーライドする必 要があります。

handle_comment( comment)
コメントを検出すると、このメソッドが呼び出されます。引数 comment は、デリミタ "<!--" から "-->" の間にある文字列であり、 デリミタ自体は含まれません。たとえばコメント "<!--text-->" を処理する 場合、引数は 'text' でこのメソッドが呼び出されます。このメソッドは デフォルトでは何もしません。

handle_cdata( data)
CDATA 要素を検出すると、このメソッドが呼び出されます。引数 data は、デリミタ "<![CDATA[" と "]]>" の間にある文字列であり、デリ ミタ自体は含まれません。たとえばエンティティ "<![CDATA[text]]>" を処理する 場合、引数は 'text' でこのメソッドが呼び出されます。このメソッドは デフォルトでは何もしないため、オーバーライドして使用します。

handle_proc( name, data)
処理命令 (PI) を検出すると、このメソッドが呼び出されます。引数 name は処理命令のターゲット、data は、処理命令ターゲットと 終了デリミタの間にある文字列であり、デリミタ自体は含まれません。たとえ ば命令 "<?XML text?>" を処理する場合、引数は 'XML' と 'text' の2つでこのメソッドが呼び出されます。このメソッドはデフォ ルトでは何もしません。なおドキュメントの冒頭に現れる "<?xml ..?>" は handle_xml() で処理されます。

handle_special( data)
宣言を検出すると、このメソッドが呼び出されます。引数 data は、デ リミタ "<!" と ">" の間にある文字列であり、デリミタ自体は含 まれません。たとえばエンティティ宣言 "<!ENTITY text>" を処理する場合、引数は 'ENTITY text' でこの メソッドが呼び出されます。このメソッドはデフォルトでは何もしないため、 オーバーライドして使用します。なおドキュメントの冒頭に現れる "<!DOCTYPE ...>" は別途処理しなければなりません。

syntax_error( message)
シンタックスエラーが発生すると、このメソッドが呼び出されます。引数 message はエラー内容を知らせるテキストです。このメソッドはデフォ ルトで RuntimeError 例外を発生させます。メソッドをオーバラ イドして、return するように変えることも可能です。なお、このメソッドが 呼び出されるのは回復可能なエラーの場合だけです。回復不能なエラー発生し たときは、syntax_error() を呼び出すことなく RuntimeError が発生します。

unknown_starttag( tag, attributes)
未知の開始タグを検出すると、このメドッドが呼び出されます。派生クラスで オーバライドして使います。基底クラスの実装では何もおこないません。

unknown_endtag( tag)
未知の終了タグを検出すると、このメドッドが呼び出されます。派生クラスで オーバライドして使います。基底クラスの実装では何もおこないません。

unknown_charref( ref)
解決できない文字参照を検出すると、このメドッドが呼び出されます。派 生クラスでオーバライドして使います。基底クラスの実装では何もおこないま せん。

unknown_entityref( ref)
解決できない実体参照を検出すると、このメドッドが呼び出されます。派生ク ラスでオーバライドして使います。基底クラスの実装では syntax_error() でエラーを通知するようになっています。

参考資料:

Extensible Markup Language (XML) 1.0
World Wide Web Consortium (W3C) が送出した XML の仕様書で、XML のシンタックスと処理に必要な内容が定義され ています。仕様書の翻訳など、そのほかの文献は http://www.w3.org/XML/ で参照できます。

Python and XML Processing
Python XML トピックガイドは Python で XML を扱 うための情報と XML 関連情報源へのリンクを数多く提供してい ます。

SIG for XML Processing in Python
Python XML Special Interest Group は Python で XML を扱うための開発に多大な貢献をしています。

... ないます。13.1
実際には、パーサに非標準的な形式のドキュメントを許容す るための、いくつかのキーワード引数を指定できるようになっており、その 内容は次の通りです。これらのデフォルト値はすべて 0 (false) で すが、最後のキーワード引数だけは 1 (true)になっています。 accept_unquoted_attributes (特定の属性がクォートされていなくても 受け入れるようにする)、 accept_missing_endtag_name (</> のようなタグ名なしの終了タグを許容する)、map_case (タグや属性 名が大文字で書かれていても、小文字で解釈する)、 accept_utf8 (UTF-8 文字列の入力を許容する。これは XML 標準規格で必須とされている内容ですが、 Python は今のところ UTF-8 を適切に処理できないため、デフォルトでは無 効になっています。)、 translate_attribute_references (属性値と して使われている文字列や実体参照はそれ以上解釈しない。)

  • 13.13.1 XML 名前空間
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.12.6 AttributesNS インターフェース Up: 13. 構造化マークアップツール Next: 13.13.1 XML 名前空間


13.13.1 XML 名前空間

このモジュールは XML 名前空間勧告に定義された名前空間をサポートします。

XML 名前空間に定義されたタグ名と属性名は、名前空間(名前空間を定義した URL)の後ににスペース置き、それに続くタグ名または属性名として扱われます。 たとえば、タグが <html xmlns='http://www.w3.org/TR/REC-html40'> の場合、タグ名は 'http://www.w3.org/TR/REC-html40 html' として 処理され、この要素の中にタグ <html:a href='http://frob.com'> が 現れた場合、タグ名は 'http://www.w3.org/TR/REC-html40 a' で、属 性名は 'http://www.w3.org/TR/REC-html40 href' となります。

古い XML 名前空間勧告ドラフトに基いたものも処理可能ですが、警告が発せ られます。

参考資料:

Namespaces in XML
この W3 コンソーシアム 勧告には、XML 名前空間の正確なシンタ クスと処理に必要な内容について述べられています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.13 xmllib Up: 13.13 xmllib Next: 14. マルチメディアサービス


14. マルチメディアサービス

この章で記述されているモジュールは、主にマルチメディアアプリケーションに 役立つさまざまなアルゴリズムまたはインターフェイスを実装しています。 これらのモジュールはインストール時の自由裁量に応じて利用できます。

以下に概要を示します。

audioop | 生のオーディオデータの操作
imageop | 生の画像データを操作する。
aifc | AIFFあるいはAIFCフォーマットのオーディオファイルの読み書き
sunau | Sun AUサウンドフォーマットへのインターフェース
wave | WAVサウンドフォーマットへのインターフェイス
chunk | IFFチャンクデータの読み込み。
colorsys | RGB 他の色体系間の変換。
rgbimg | ``SGI RGB''フォーマットの画像ファイルを読み書きします(ですが、このモジュールはSGI特有のものではありません !)。
imghdr | ファイルやバイトストリームに含まれる画像の形式を決定する。
sndhdr | サウンドファイルの識別
ossaudiodev | OSS互換オーディオデバイスへのアクセス。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.13.1 XML 名前空間 Up: Python ライブラリリファレンス Next: 14.1 audioop


14.1 audioop -- 生のオーディオデータの操作

audioopモジュールにはサウンドデータに対する便利な操作が定義されています。

このモジュールは、Python文字列で保存された、8、16、32ビットサイズの符合付き整数型からなるサウンドデータを処理します。

このデータはalとsunaudiodevモジュールで使用されるのと同じフォーマットです。

特に断わらない限り数値項目は整数です。

このモジュールはu-LAWとIntel/DVI ADPCMエンコードをサポートしています。

複雑な操作のうちいくつかは16ビットのサンプルに対してのみ働きますが、それ以外は常にサンプルサイズ（バイト数）を操作のパラメータとして渡します。

このモジュールは以下の変数と関数を定義しています：

exception error
この例外はサウンドサンプルの未知のバイト数など、全てのエラーに対して発生します。

add( fragment1, fragment2, width)
パラメータとして渡された2つのサンプルの和のデータを返します。

widthはサンプルサイズのバイト数で、1、2、4のうちのどれかです。 2つのデータは同じサンプルサイズでなければなりません。

adpcm2lin( adpcmfragment, width, state)
Intel/DVI ADPCMフォーマットのデータをlinearフォーマットにデコードします。 ADPCMフォーマットについての詳細はlin2adpcm()の説明を参照して下さい。 widthで指定したサイズで(sample, newstate)のタプルを返します。

adpcm32lin( adpcmfragment, width, state)
3ビットの新しいADPCMフォーマットのデータをデコードします。 詳しくはlin2adpcm3()を参照して下さい。

avg( fragment, width)
データ内の全サンプルの平均値を返します。

avgpp( fragment, width)
データ内の全サンプルの最大振幅の平均値を返します。 フィルタリングされていないなら、このルーチンが役立つかどうか疑問です。

bias( fragment, width, bias)
もとのデータのサンプル一つ一つにバイアスを加えたデータを返します。

cross( fragment, width)
引数として渡されたデータ内のゼロ-クロスポイントの数を返します。

findfactor( fragment, reference)
rms(add(fragment, mul(reference, -F)))が最小となるようなFを返します。つまり、referenceに掛けるとfragmentにできるだけ一致するような値を返します。 fragmentとreferenceは両方とも2バイトのサンプルでなければなりません。

このルーチンの実行に要する時間はlen(fragment)に比例します。

findfit( fragment, reference)
referenceがfragment（より長いデータ）の一部に一致するか確かめます。 これは（概念的には）fragmentから断片を切り出して、findfactor()を使って一番ふさわしいものを計算し、結果を最小にすることで実現しています。 fragmentとreferenceは両方とも2バイトのサンプルでなければなりません。 (offset, factor)のタプルを返します。offsetは最適な一致箇所が始まるfragmentのオフセット値（整数）で、factorはfindfactor()で返される数値（浮動小数点数）です。

findmax( fragment, length)
fragmentを長さlengthのサンプル（バイトではありません！）にスライスして、最大レベルをもつサンプルを探します。つまり、rms(fragment[i*2:(i+length)*2])が最大となるようなiを返します。 データは2バイトのサンプルでなければなりません。

このルーチンの実行に要する時間はlen(fragment)に比例します。

getsample( fragment, width, index)
データからindexのサンプルの値を返します。

lin2lin( fragment, width, newwidth)
サンプルサイズを1、2、4バイトフォーマットの間で変換します。

lin2adpcm( fragment, width, state)
サンプルを4ビットのIntel/DVI ADPCMフォーマットにエンコードします。 ADPCMフォーマットは、（さまざまな）あるステップで区切られたサンプルと次のサンプルとの差である4ビットの数値を利用したコード化スキームです。 Intel/DVI ADPCMアルゴリズムは国際MIDI協会に採用されているので、標準に なると言っていいでしょう。

stateはエンコードの情報を含んだタプルです。 (adpcmfrag, newstate)のタプルを返します。newstateは次にlin2adpcm()を呼び出す時に渡さなければなりません。 最初の呼び出しではstateとしてNoneを渡します。 adpcmfragはADPCMでコード化された、バイト当たり2つの4ビット値です。

lin2adpcm3( fragment, width, state)
これはサンプル当たり3ビットのみを使う新しいADPCMフォーマットです。 これはIntel/DVI ADPCMフォーマットと互換性がなく、出力は提供されていません（作者の怠慢によるものです）。 使うとがっかりします。

lin2ulaw( fragment, width)
オーディオデータのサンプルをu-LAWフォーマットにエンコードし、Python文字列として返します。 u-LAWはオーディオエンコードフォーマットで、8ビットのみのサンプルで約14ビットのダイナミックレンジが得られます。 他でも使われていますが、Sunのオーディオハードウェアで使われています。

minmax( fragment, width)
サウンドデータ内の全サンプルの最小値と最大値からなるタプルを返します。

max( fragment, width)
データ内の全サンプルの絶対値の最大値を返します。

maxpp( fragment, width)
サウンドデータの最大振幅の最大値を返します。

mul( fragment, width, factor)
元のデータ内の全サンプルに浮動小数点数factorを掛けたデータを返します。 オーバーフローした分は無視します。

ratecv( fragment, width, nchannels, inrate, outrate, state[, weightA[, weightB]])
入力したデータのフレームレートを変換します。

stateは変換の情報を含むタプルです。 (newfragment, newstate)を返します。 newstateは次にratecv()を呼び出す時に渡さなければなりません。

最初の呼び出しではstateとしてNoneを渡します。

引数weightAとweightBはシンプルなデジタルフィルターのためのパラメータで、デフォルトではそれぞれ1、0です。

reverse( fragment, width)
データ内のサンプルの順序を逆転したデータを返します。

rms( fragment, width)
データの標準偏差を返します。つまり、

これはオーディオ信号の大きさを示します。

tomono( fragment, width, lfactor, rfactor)
ステレオデータをモノラルデータに変換します。 2つのチャンネルを足してモノラルの信号にする前に、左チャンネルはlfactor倍、右チャンネルはrfactor倍されます。

tostereo( fragment, width, lfactor, rfactor)
モノラルのデータからステレオのデータを作ります。 左チャンネルのサンプルはモノラルのサンプルをlfactor倍、右チャンネルはrfactor倍して、ステレオデータのサンプルを算出します。

ulaw2lin( fragment, width)
u-LAWフォーマットのサウンドデータをlinearフォーマットのサウンドデータにエンコードします。 u-LAWフォーマットは常に8ビットのサンプルを使うので、widthは出力データのサンプルサイズを示します。

mul()やmax()はモノラルとステレオの区別をつけずに、全サンプルを等しく扱います。 これが問題なら、初めにステレオデータを2つのモノラルデータに分割して、あとで結合するといいでしょう。 どうしたらいいか、例を挙げます。

def mul_stereo(sample, width, lfactor, rfactor):
    lsample = audioop.tomono(sample, width, 1, 0)
    rsample = audioop.tomono(sample, width, 0, 1)
    lsample = audioop.mul(lsample, width, lfactor)
    rsample = audioop.mul(rsample, width, rfactor)
    lsample = audioop.tostereo(lsample, width, 1, 0)
    rsample = audioop.tostereo(rsample, width, 0, 1)
    return audioop.add(lsample, rsample, width)

もしネットワークパケットを構築してADPCMフォーマットを使って、プロトコールの説明なしにしたいなら（つまりパケットの損失を我慢できるなら）、データだけでなくstateも送信するべきです。 注意してほしいのは、（コーダーによって返される）最後のstateでなく、initialのstate（lin2adpcm()に渡す引数）をコーダーに渡すことです。 もしバイナリでstateを保存するのにstruct.struct()を使いたいなら、最初の要素（最初の値）を16ビットで、2番目の要素（前のサンプルとの差）を8ビットでコード化します。

ここのADPCMコーダーは他のADPCMコーダーに対しては試していません。 それぞれの標準のものとの間で操作できない場合は、私が仕様を誤解していることも十分あり得ます。

find*()ルーチンは、一見、滑稽に見えるかもしれません。 これらは最初、エコーを取り消すためのものでした。 これを合理的に速く実行するには、出力サンプルのレベルの一番大きい部分を取り出し、その場所の入力サンプル内での位置をみつけ、入力サンプルから出力サンプル全体を減算します：

def echocancel(outputdata, inputdata):
    pos = audioop.findmax(outputdata, 800)    # 1/10秒
    out_test = outputdata[pos*2:]
    in_test = inputdata[pos*2:]
    ipos, factor = audioop.findfit(in_test, out_test)
    # Optional (for better cancellation):
    # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
    #              out_test)
    prefill = '\0'*(pos+ipos)*2
    postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
    outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill
    return audioop.add(inputdata, outputdata, 2)
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14. マルチメディアサービス Up: 14. マルチメディアサービス Next: 14.2 imageop


14.2 imageop -- 生の画像データを操作する

imageopモジュールは画像に関する便利な演算がふくまれています。Python文字列に保存されている8または32ビットのピクセルから構成される画像を操作します。これはgl.lrectwrite()とimgfileモジュールが使用しているものと同じフォーマットです。

モジュールは次の変数と関数を定義しています:

exception error
この例外はピクセル当りの未知のビット数などのすべてのエラーで発生させられます。

crop( image, psize, width, height, x0, y0, x1, y1)
imageの選択された部分を返します。imageはwidth×heightの大きさで、psizeバイトのピクセルから構成されなければなりません。x0、y0、x1およびy1はgl.lrectread()パラメータと同様です。すなわち、境界は新画像に含まれます。新しい境界は画像の内部である必要はありません。旧画像の外側になるピクセルは値をゼロに設定されます。x0がvarx1より大きければ、新画像は鏡像反転されます。y軸についても同じことが適用されます。

scale( image, psize, width, height, newwidth, newheight)
imageを大きさnewwidth×newheightに伸縮させて返します。補間は行われません。ばかばかしいほど単純なピクセルの複製と間引きを行い伸縮させます。そのため、コンピュータで作った画像やディザ処理された画像は伸縮した後見た目が良くありません。

tovideo( image, psize, width, height)
垂直ローパスフィルタ処理を画像全体に行います。それぞれの目標ピクセルを垂直に並んだ二つの元ピクセルから計算することで行います。このルーチンの主な用途としては、画像がインターレース走査のビデオ装置に表示された場合に極端なちらつきを抑えるために用います。そのため、この名前があります。

grey2mono( image, width, height, threshold)
全ピクセルを二値化することによって、深さ8ビットのグレースケール画像を深さ1ビットの画像へ変換します。処理後の画像は隙間なく詰め込まれ、おそらくmono2grey()の引数としてしか使い道がないでしょう。

dither2mono( image, width, height)
(ばかばかしいほど単純な)ディザ処理アルゴリズムを用いて、8ビットグレースケール画像を1ビットのモノクロ画像に変換します。

mono2grey( image, width, height, p0, p1)
1ビットモノクロが象画像を8ビットのグレースケールまたはカラー画像に変換します。入力で値ゼロの全てのピクセルは出力では値p0を取り、値0の入力ピクセルは出力では値p1を取ります。白黒のモノクロ画像をグレースケールへ変換するためには、値0と255をそれぞれ渡してください。

grey2grey4( image, width, height)
ディザ処理を行わずに、8ビットグレースケール画像を4ビットグレースケール画像へ変換します。

grey2grey2( image, width, height)
ディザ処理を行わずに、8ビットグレースケール画像を2ビットグレースケール画像に変換します。

dither2grey2( image, width, height)
ディザ処理を行い、8ビットグレースケール画像を2ビットグレースケール画像へ変換します。dither2mono()については、ディザ処理アルゴリズムは現在とても単純です。

grey42grey( image, width, height)
4ビットグレースケール画像を8ビットグレースケール画像へ変換します。

grey22grey( image, width, height)
2ビットグレースケール画像を8ビットグレースケール画像へ変換します。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.1 audioop Up: 14. マルチメディアサービス Next: 14.3 aifc


14.3 aifc -- AIFFおよびAIFCファイルの読み書き

このモジュールはAIFFとAIFF-Cファイルの読み書きをサポートします。 AIFF（Audio Interchange File Format）はデジタルオーディオサンプルをファ イルに保存するためのフォーマットです。 AIFF-CはAIFFの新しいバージョンで、オーディオデータの圧縮に対応していま す。

注意： 操作のいくつかはIRIX上でのみ動作します； そういう操作ではIRIXでのみ利用できるclモジュールをインポート しようとして、ImportErrorを発生します。

オーディオファイルには、オーディオデータについて記述したパラメータがたく さん含まれています。 サンプリングレートあるいはフレームレートは、1秒あたりのオーディオサンプ ル数です。 チャンネル数は、モノラル、ステレオ、4チャンネルかどうかを示します。 フレームはそれぞれ、チャンネルごとに一つのサンプルからなります。 サンプルサイズは、一つのサンプルの大きさをバイト数で示したものです。 したがって、一つのフレームはnchannels*samplesizeバイト からなり、1秒間ではnchannels*samplesize*framerate バイトで構成されます。

例えば、CD品質のオーディオは2バイト（16ビット）のサンプルサイズを 持っていて、2チャンネル（ステレオ）であり、44,100フレーム／秒のフレーム レートを持っています。そのため、フレームサイズは4バイト（2*2）で、 1秒間では2*2*44100バイト（176,400バイト）になります。

aifcモジュールは以下の関数を定義しています：

open( file[, mode])
AIFFあるいはAIFF-Cファイルを開き、後述するメソッドを持つインスタンスを返 します。 引数fileはファイルを示す文字列か、ファイルオブジェクトのいずれかで す。 modeは、読み込み用に開くときには'r'か'rb'のどちらか で、書き込み用に開くときには'w'か'wb'のどちらかでなければ なりません。 もし省略されたら、file.modeが存在すればそれが使用され、なけ れば'rb'が使われます。 書き込み用にこのメソッドを使用するときには、これから全部でどれだけのサン プル数を書き込むのか分からなかったり、writeframesraw()と setnframes()を使わないなら、 ファイルオブジェクトはシーク可能でなければなりません。

ファイルがopen()によって読み込み用に開かれたときに返されるオ ブジェクトには、以下のメソッドがあります：

getnchannels( )
オーディオチャンネル数（モノラルなら1、ステレオなら2）を返します。

getsampwidth( )
サンプルサイズをバイト数で返します。

getframerate( )
サンプリングレート（1秒あたりのオーディオフレーム数）を返します。

getnframes( )
ファイルの中のオーディオフレーム数を返します。

getcomptype( )
オーディオファイルで使用されている圧縮形式を示す4文字の文字列を返しま す。AIFFファイルでは'NONE'が返されます。

getcompname( )
オーディオファイルの圧縮形式を人に判読可能な形にしたものを返します。 AIFFファイルでは'not compressed'が返されます。

getparams( )
以上の全ての値を上の順に並べたタプルを返します。

getmarkers( )
オーディオファイルのマーカーのリストを返します。 一つのマーカーは三つの要素のタプルです。 要素の1番目はマークID（整数）、2番目はマーク位置のフレーム数をデータの始 めから数えた値（整数）、3番目はマークの名称（文字列）です。

getmark( id)
与えられたidのマークの要素をgetmarkers()で述べたタプルで 返します。

readframes( nframes)
オーディオファイルの次のnframes個のフレームを読み込んで返します。 返されるデータは、全チャンネルの圧縮されていないサンプルをフレームごとに 文字列にしたものです。

rewind( )
読み込むポインタをデータの始めに巻き戻します。 次にreadframes()を使用すると、データの始めから読み込みます。

setpos( pos)
指定したフレーム数の位置にポインタを設定します。

tell( )
現在のポインタのフレーム位置を返します。

close( )
AIFFファイルを閉じます。 このメソッドを呼び出したあとでは、オブジェクトはもう使用できません。

ファイルがopen()によって書き込み用に開かれたときに返されるオ ブジェクトには、readframes()とsetpos()を除く上述の全て のメソッドがあります。 さらに以下のメソッドが定義されています。 get*()メソッドは、対応するset*()を呼び出したあとでのみ 呼び出し可能です。 最初にwriteframes()あるいはwriteframesraw()を呼び出す 前に、フレーム数を除く全てのパラメータが設定されていなければなりません。

aiff( )
AIFFファイルを作ります。 デフォルトではAIFF-Cファイルが作られますが、ファイル名が'.aiff'で 終わっていればAIFFファイルが作られます。

aifc( )
AIFF-Cファイルを作ります。 デフォルトではAIFF-Cファイルが作られますが、ファイル名が'.aiff'で 終わっていればAIFFファイルが作られます。

setnchannels( nchannels)
オーディオファイルのチャンネル数を設定します。

setsampwidth( width)
オーディオのサンプルサイズをバイト数で設定します。

setframerate( rate)
サンプリングレートを1秒あたりのフレーム数で設定します。

setnframes( nframes)
オーディオファイルに書き込まれるフレーム数を設定します。 もしこのパラメータが設定されていなかったり正しくなかったら、ファイルは シークに対応していなければなりません。

setcomptype( type, name)
圧縮形式を設定します。 もし設定しなければ、オーディオデータは圧縮されません。 AIFFファイルは圧縮できません。 変数nameは圧縮形式を人に判読可能にしたもので、変数typeは4文字の文字列で なければなりません。 現在のところ、以下の圧縮形式がサポートされています： NONE, ULAW, ALAW, G722。

setparams( nchannels, sampwidth, framerate, com ptype, compname)
上の全パラメータを一度に設定します。 引数はそれぞれのパラメータからなるタプルです。 つまり、setparams()の引数として、getparams()を呼び出し た結果を使うことができます。

setmark( id, pos, name)
指定したID（1以上）、位置、名称でマークを加えます。 このメソッドは、close()の前ならいつでも呼び出すことができます。

tell( )
出力ファイルの現在の書き込み位置を返します。 setmark()との組み合わせで使うと便利です。

writeframes( data)
出力ファイルにデータを書き込みます。 このメソッドは、オーディオファイルのパラメータを設定したあとでのみ呼び出 し可能です。

writeframesraw( data)
オーディオファイルのヘッダ情報が更新されないことを除いて、 writeframes()と同じです。

close( )
AIFFファイルを閉じます。 ファイルのヘッダ情報は、オーディオデータの実際のサイズを反映して更新され ます。 このメソッドを呼び出したあとでは、オブジェクトはもう使用できません。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.2 imageop Up: 14. マルチメディアサービス Next: 14.4 sunau


14.4 sunau -- Sun AUファイルの読み書き

sunauモジュールは、Sun AUサウンドフォーマットへの便利なインター フェースを提供します。このモジュールは、aifcモジュールや waveモジュールと互換性のあるインターフェースを備えています。

オーディオファイルはヘッダとそれに続くデータから構成されます。 ヘッダのフィールドは以下の通りです：

フィールド | 内容
magic word | 4バイト文字列 ".snd"。
header size | infoを含むヘッダのサイズをバイト数で示したもの。
data size | データの物理サイズをバイト数で示したもの。
encoding | オーディオサンプルのエンコード形式。
sample rate | サンプリングレート。
# of channels | サンプルのチャンネル数。
info | オーディオファイルについての説明をASCII文字列で示した もの（null バイトで埋められます）。

infoフィールド以外の全てのヘッダフィールドは4バイトの大きさです。 ヘッダフィールドはbig-endianでエンコードされた、計32ビットの符合なし整数 です。

sunauモジュールは以下の関数を定義しています：

open( file, mode)
fileが文字列ならその名前のファイルを開き、そうでないならファイル のようにシーク可能なオブジェクトとして扱います。modeは以下のうち のいずれかです。

'r'
読み込みのみのモード。
'w'
書き込みのみのモード。
読み込み／書き込み両方のモードで開くことはできない ことに注意して下さい。

'r'のmodeはAU_readオブジェクトを 返し、'w'と'wb'のmodeはAU_writeオブジェク トを返します。

openfp( file, mode)
open()と同義。後方互換性のために残されています。

sunauモジュールは以下の例外を定義しています：

exception Error
Sun AUの仕様や実装に対する不適切な操作により何か実行不可能となった時に発 生するエラー。

sunauモジュールは以下のデータアイテムを定義しています：

AUDIO_FILE_MAGIC
big-endianで保存された正規のSun AUファイルは全てこの整数で始まります。 これは文字列".snd"を整数に変換したものです。

AUDIO_FILE_ENCODING_MULAW_8
AUDIO_FILE_ENCODING_LINEAR_8
AUDIO_FILE_ENCODING_LINEAR_16
AUDIO_FILE_ENCODING_LINEAR_24
AUDIO_FILE_ENCODING_LINEAR_32
AUDIO_FILE_ENCODING_ALAW_8
AUヘッダのencodingフィールドの値で、このモジュールでサポートしているもの です。

AUDIO_FILE_ENCODING_FLOAT
AUDIO_FILE_ENCODING_DOUBLE
AUDIO_FILE_ENCODING_ADPCM_G721
AUDIO_FILE_ENCODING_ADPCM_G722
AUDIO_FILE_ENCODING_ADPCM_G723_3
AUDIO_FILE_ENCODING_ADPCM_G723_5
AUヘッダのencodingフィールドの値のうち既知のものとして追加されているもの ですが、このモジュールではサポートされていません。

  • 14.4.1 AU_read オブジェクト
  • 14.4.2 AU_write オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.3 aifc Up: 14. マルチメディアサービス Next: 14.4.1 AU_read オブジェクト


14.4.1 AU_read オブジェクト

上述のopen()によって返されるAU_readオブジェクトには、以下の メソッドがあります：

close( )
ストリームを閉じ、このオブジェクトのインスタンスを使用できなくします。 （これはオブジェクトのガベージコレクション時に自動的に呼び出されます。）

getnchannels( )
オーディオチャンネル数（モノラルなら1、ステレオなら2）を返 します。

getsampwidth( )
サンプルサイズをバイト数で返します。

getframerate( )
サンプリングレートを返します。

getnframes( )
オーディオフレーム数を返します。

getcomptype( )
圧縮形式を返します。'ULAW'、'ALAW'、'NONE'が サポートされている形式です。

getcompname( )
getcomptype()を人に判読可能な形にしたものです。 上述の形式に対して、それぞれ'CCITT G.711 u-law'、 'CCITT G.711 A-law'、'not compressed'がサポートされて います。

getparams( )
get*()メソッドが返すのと同じ(nchannels, sampwidth, framerate, nframes, comptype, compname)のタプルを返します。

readframes( n)
n個のオーディオフレームの値を読み込んで、バイト ごとに文字に変換した文字列を返します。 データはlinear形式で返されます。もし元のデータがu-LAW形式なら、変換され ます。

rewind( )
ファイルのポインタをオーディオストリームの先頭に戻します。

以下の2つのメソッドは共通の``位置''を定義しています。``位置''は他の関数 とは独立して実装されています。

setpos( pos)
ファイルのポインタを指定した位置に設定します。 tell()で返される値をposとして使用しなければなりません。

tell( )
ファイルの現在のポインタ位置を返します。 返される値はファイルの実際の位置に対して何も操作はしません。

以下の2つのメソッドはaifcモジュールとの互換性のために定義さ れていますが、何も面白いことはしません。

getmarkers( )
Noneを返します。

getmark( id)
エラーを発生します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.4 sunau Up: 14.4 sunau Next: 14.4.2 AU_write オブジェクト


14.4.2 AU_write オブジェクト

上述のopen()によって返されるWave_writeオブジェクトには、 以下のメソッドがあります：

setnchannels( n)
チャンネル数を設定します。

setsampwidth( n)
サンプルサイズを（バイト数で）設定します。

setframerate( n)
フレームレートを設定します。

setnframes( n)
フレーム数を設定します。あとからフレームが書き込まれるとフレー ム数は変更されます。

setcomptype( type, name)
圧縮形式とその記述を設定します。 'NONE'と'ULAW'だけが、出力時にサポートされている形式です。

setparams( tuple)
tupleは(nchannels, sampwidth, framerate, nframes, comptype, compname) で、それぞれset*()のメソッドの値にふさわしいものでなければなり ません。全ての変数を設定します。

tell( )
ファイルの中の現在位置を返します。AU_read.tell()と AU_read.setpos()メソッドでお断りしたことがこのメソッドにも当 てはまります。

writeframesraw( data)
nframesの修正なしにオーディオフレームを書き込みます。

writeframes( data)
オーディオフレームを書き込んでnframesを修正します。

close( )
nframesが正しいか確認して、ファイルを閉じます。 このメソッドはオブジェクトの削除時に呼び出されます。

writeframes()やwriteframesraw()メソッドを呼び出したあ とで、どんなパラメータを設定しようとしても不正となることに注意して下さ い。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.4.1 AU_read オブジェクト Up: 14.4 sunau Next: 14.5 wave


14.5 wave -- WAVファイルの読み書き

waveモジュールは、WAVサウンドフォーマットへの便利なインター フェイスを提供するモジュールです。

このモジュールは圧縮／展開をサポートしていませんが、モノラル／ステレオ には対応しています。

waveモジュールは、以下の関数と例外を定義しています。

open( file[, mode])
fileが文字列ならその名前のファイルを開き、そうでないならファイル のようにシーク可能なオブジェクトとして扱います。modeは以下のうち のいずれかです。

'r', 'rb'
  読み込みのみのモード。
'w', 'wb'
  書き込みのみのモード。
WAVファイルに対して読み込み／書き込み両方のモードで開くことはできない ことに注意して下さい。 'r'と'rb'のmodeはWave_readオブジェクトを 返し、'w'と'wb'のmodeはWave_writeオブジェク トを返します。 modeが省略されていて、ファイルのようなオブジェクトがfileとし て渡されると、file.modeがmodeのデフォルト値として使わ れます（必要であれば、さらにフラグ"b"が付け加えられます）。

openfp( file, mode)
open()と同義。後方互換性のために残されています。

exception Error
WAVの仕様を犯したり、実装の欠陥に遭遇して何か実行不可能となった時に発生 するエラー。

  • 14.5.1 Wave_read オブジェクト
  • 14.5.2 Wave_write オブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.4.2 AU_write オブジェクト Up: 14. マルチメディアサービス Next: 14.5.1 Wave_read オブジェクト


14.5.1 Wave_read オブジェクト

open()によって返されるWave_readオブジェクトには、以下のメソッ ドがあります：

close( )
ストリームを閉じ、このオブジェクトのインスタンスを使用できなくします。 これはオブジェクトのガベージコレクション時に自動的に呼び出されます。

getnchannels( )
オーディオチャンネル数（モノラルなら1、ステレオなら2）を返 します。

getsampwidth( )
サンプルサイズをバイト数で返します。

getframerate( )
サンプリングレートを返します。

getnframes( )
オーディオフレーム数を返します。

getcomptype( )
圧縮形式を返します（'NONE'だけがサポートされている形式です）。

getcompname( )
getcomptype()を人に判読可能な形にしたものです。 通常、'NONE'に対して'not compressed'が返されます。

getparams( )
get*()メソッドが返すのと同じ(nchannels, sampwidth, framerate, nframes, comptype, compname)のタプルを返します。

readframes( n)
現在のポインタからn個のオーディオフレームの値を読み込んで、バイト ごとに文字に変換して文字列を返します。

rewind( )
ファイルのポインタをオーディオストリームの先頭に戻します。

以下の2つのメソッドはaifcモジュールとの互換性のために定義さ れていますが、何も面白いことはしません。

getmarkers( )
Noneを返します。

getmark( id)
エラーを発生します。

以下の2つのメソッドは共通の``位置''を定義しています。``位置''は他の関数 とは独立して実装されています。

setpos( pos)
ファイルのポインタを指定した位置に設定します。

tell( )
ファイルの現在のポインタ位置を返します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.5 wave Up: 14.5 wave Next: 14.5.2 Wave_write オブジェクト


14.5.2 Wave_write オブジェクト

open()によって返されるWave_writeオブジェクトには、以下のメ ソッドがあります：

close( )
nframesが正しいか確認して、ファイルを閉じます。 このメソッドはオブジェクトの削除時に呼び出されます。

setnchannels( n)
チャンネル数を設定します。

setsampwidth( n)
サンプルサイズをnバイトに設定します。

setframerate( n)
サンプリングレートをnに設定します。

setnframes( n)
フレーム数をnに設定します。あとからフレームが書き込まれるとフレー ム数は変更されます。

setcomptype( type, name)
圧縮形式とその記述を設定します。

setparams( tuple)
tupleは(nchannels, sampwidth, framerate, nframes, comptype, compname) で、それぞれset*()のメソッドの値にふさわしいものでなければなり ません。全ての変数を設定します。

tell( )
ファイルの中の現在位置を返します。Wave_read.tell()と Wave_read.setpos()メソッドでお断りしたことがこのメソッドにも当 てはまります。

writeframesraw( data)
nframesの修正なしにオーディオフレームを書き込みます。

writeframes( data)
オーディオフレームを書き込んでnframesを修正します。

writeframes()やwriteframesraw()メソッドを呼び出したあ とで、どんなパラメータを設定しようとしても不正となることに注意して下さ い。そうするとwave.Errorを発生します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.5.1 Wave_read オブジェクト Up: 14.5 wave Next: 14.6 chunk


14.6 chunk -- IFFチャンクデータの読み込み

このモジュールはEA IFF 85チャンクを使用しているファイルの読み込みのため のインターフェースを提供します。 14.1 このフォーマットは少なくとも、AudioInterchange File Format (AIFF/AIFF-C) とRealMedia File Format(RMFF)で使われています。 WAVEオーディオファイルフォーマットも厳密に対応しているので、このモジュー ルで読み込みできます。 チャンクは以下の構造を持っています：

Offset値 | 長さ | 内容
0 | 4 | チャンクID
4 | 4 | big-endianで示したチャンクのサイズで、ヘッダは含みませ ん
8 | n | バイトデータで、nはこれより先のフィールドのサイズ
8 + n | 0 or 1 | nが奇数ならチャンクの整頓のために埋められるバイト

IDはチャンクの種類を識別する4バイトの文字列です。

サイズフィールド（big-endianでエンコードされた32ビット値）は、8バイトの ヘッダを含まないチャンクデータのサイズを示します。

普通、IFFタイプのファイルは1個かそれ以上のチャンクからなります。 このモジュールで定義されるChunkクラスの使い方として提案している のは、それぞれのチャンクの始めにインスタンスを作り、終わりに達するまでそ のインスタンスから読み取り、その後で新しいインスタンスを作るということで す。 ファイルの終わりで新しいインスタンスを作ろうとすると、 EOFErrorの例外が発生して失敗します。

class Chunk( file[, align, bigendian, inclheader])
チャンクを表現するクラス。 引数fileはファイルのようなオブジェクトであることが想定されていま す。 このクラスのインスタンスは特別にそのように認められています。 必要とされるメソッドはread()だけです。 もしseek()とtell()メソッドが呼び出されて例外を発生させ なかったら、これらのメソッドも動作します。 これらのメソッドが呼び出されて例外を発生させても、オブジェクトを変化させ ないようになっています。

省略可能な引数alignがtrueなら、チャンクデータが偶数個で2バイトごと に整頓されていると想定します。 もしalignがfalseなら、チャンクデータが奇数個になっていると想定しま す。 デフォルト値はtrueです。

もし省略可能な引数bigendianがfalseなら、チャンクサイズは little-endianであると想定します。 この引数の設定はWAVEオーディオファイルで必要です。デフォルト値はtrueで す。

もし省略可能な引数inclheaderがtrueなら、チャンクのヘッダから得られ るサイズはヘッダのサイズを含んでいると想定します。 デフォルト値はfalseです。

Chunkオブジェクトには以下のメソッドが定義されています：

getname( )
チャンクの名前（ID）を返します。 これはチャンクの始めの4バイトです。

getsize( )
チャンクのサイズを返します。

close( )
オブジェクトを閉じて、チャンクの終わりまで飛びます。 これは元のファイル自体は閉じません。

残りの以下のメソッドは、close()メソッドを呼び出した後に呼び出す と例外IOErrorを発生します。

isatty( )
Falseを返します。

seek( pos[, whence])
チャンクの現在位置を設定します。 引数whenceは省略可能で、デフォルト値は0（ファイルの絶対位 置）です；他に1（現在位置から相対的にシークします）と2 （ファイルの末尾から相対的にシークします）の値を取ります。 何も値は返しません。 もし元のファイルがシークに対応していなければ、前方へのシークのみが可能で す。

tell( )
チャンク内の現在位置を返します。

read( [size])
チャンクから最大でsizeバイト（sizeバイトを読み込むまで、少な くともチャンクの最後に行き着くまで）読み込みます。 もし引数sizeが負か省略されたら、チャンクの最後まで全てのデータを読 み込みます。 バイト値は文字列のオブジェクトとして返されます。 チャンクの最後に行き着いたら、空文字列を返します。

skip( )
チャンクの最後まで飛びます。 さらにチャンクのread()を呼び出すと、''が返されます。 もしチャンクの内容に興味がないなら、このメソッドを呼び出してファイルポイ ンタを次のチャンクの始めに設定します。

... のインターフェースを提供します。14.1
``EA IFF 85'' Standard for Interchange Format Files, Jerry Morrison, Electronic Arts, January 1985.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.5.2 Wave_write オブジェクト Up: 14. マルチメディアサービス Next: 14.7 colorsys


14.7 colorsys -- 色体系間の変換

colorsys モジュールは、計算機のディスプレイモニタで 使われている RGB (Red Green Blue) 色空間で表された色と、他の 3 種類の色座標系: YIQ, HLS (Hue Lightness Saturation: 色相、彩度、 飽和) および HSV (Hue Saturation Value: 色相、彩度、明度) との 間の双方向の色値変換を定義します。 これらの色空間における色座標系は全て浮動小数点数で表されます。 YIQ 空間では、Y 軸は 0 から 1 ですが、 I および Q 軸は正の値も 負の値もとり得ます。他の色空間では、各軸は全て 0 から 1 の値を とります。

色空間に関するより詳細な情報は http://www.inforamp.net/%7epoynton/ColorFAQ.htmlにあります。

colorsys モジュールでは、以下の関数が定義されています:

rgb_to_yiq( r, g, b)
RGB から YIQ に変換します。

yiq_to_rgb( y, i, q)
YIQ から RGB に変換します。

rgb_to_hls( r, g, b)
RGB から HLS に変換します。

hls_to_rgb( h, l, s)
HLS から RGB に変換します。

rgb_to_hsv( r, g, b)
RGB から HSV に変換します。

hsv_to_rgb( h, s, v)
HSV から RGB に変換します。

サンプルコード:

>>> import colorsys
>>> colorsys.rgb_to_hsv(.3, .4, .2)
(0.25, 0.5, 0.4)
>>> colorsys.hsv_to_rgb(0.25, 0.5, 0.4)
(0.3, 0.4, 0.2)
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.6 chunk Up: 14. マルチメディアサービス Next: 14.8 rgbimg


14.8 rgbimg -- ``SGI RGB''ファイルを読み書きする

rgbimgモジュールはPythonプログラムが(.rgbとしても知られる)SGI imglib画像ファイルにアクセスできるようにします。モジュールは完全にはほど遠いが、場合によっては寿分といえる機能を持っているためとにかく提供されています。現在、カラーマップファイルがサポートされていません。

注意: このモジュールはデフォルトでは32ビットプラットホームでのみ構築されます。他のプラットホームで適切な動作をすることは期待できません。

モジュールは次の変数と関数を定義しています:

exception error
例えば未サポートのファイル形式などのようなすべてのエラーに対してこの例外が発生します。

sizeofimage( file)
この関数はタプル(x, y)を返します。ここで、xとyは画素単位の画像の大きさです。4バイトRGBAピクセル、3バイトRGBピクセル、および、1バイトグレースケールピクセルが現在サポートされています。

longimagedata( file)
この関数は特定ファイルの画像を読み込んでデコードし、Python文字列としてそれを返します。その文字列は4バイトRGBピクセルです。左下のピクセルが文字列の先頭です。例えば、このフォーマットはgl.lrectwrite()へ渡すために適しています。

longstoimage( data, x, y, z, file)
この関数はdataのRGBAデータを画像ファイルfileへ書き込みます。xとyは画像の大きさを表します。セーブされた画像が1バイトのグレースケールの場合は、zは1です。セーブされた画像が3バイトのRGBデータの場合は3です。セーブされた画像が4バイトのRGBA データの場合は4です。入力画像は常にピクセル当たり4バイト含んでいます。gl.lrectread()が返すフォーマットがあります。

ttob( flag)
この関数はグローバルなフラグを設定します。そのフラグは画像のスキャン行が下から上に向かって読み込みや書き込みが行われるのか(フラグは0で、SGI GLと互換性があります)、あるいは上から下に向かって読み込みや書き込みがお壊れるのか(フラグは1で、Xと互換性があります)を定義します。デフォルトは、0です。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.7 colorsys Up: 14. マルチメディアサービス Next: 14.9 imghdr


14.9 imghdr -- 画像の形式を決定する

imghdrモジュールはファイルやバイトストリームに含まれる画像の形式を決定します。

imghdrモジュールは次の関数を定義しています:

what( filename[, h])
filenameという名前のファイル内の画像データをテストし、画像形式を表す文字列を返します。オプションのhが与えられた場合は、filenameは無視され、テストするバイトストリームを含んでいるとhは仮定されます。

以下にwhat()からの戻り値とともにリストするように、次の画像形式が認識されます:

Value | Image format
'rgb' | SGI ImgLib Files
'gif' | GIF 87a and 89a Files
'pbm' | Portable Bitmap Files
'pgm' | Portable Graymap Files
'ppm' | Portable Pixmap Files
'tiff' | TIFF Files
'rast' | Sun Raster Files
'xbm' | X Bitmap Files
'jpeg' | JPEG data in JFIF format
'bmp' | BMP files
'png' | Portable Network Graphics

この変数に追加することで、あなたはimghdrが認識できるファイル形式のリストを拡張できます:

tests
個別のテストを行う関数のリスト。それぞれの関数は二つの引数をとります: バイトストリームとオープンされたファイルのようにふるまうオブジェクト。what()がバイトストリームとともに呼び出されたときは、ファイルのようにふるまうオブジェクトはNoneでしょう。

テストが成功した場合は、テスト関数は画像形式を表す文字列を返すべきです。あるいは、失敗した場合はNoneを返すべきです。

例:

>>> import imghdr
>>> imghdr.what('/tmp/bass.gif')
'gif'
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.8 rgbimg Up: 14. マルチメディアサービス Next: 14.10 sndhdr


14.10 sndhdr -- サウンドファイルの識別

sndhdrモジュールには、ファイルに保存されたサウンドデータの形式 を識別するのに便利な関数が定義されています。 どんな形式のサウンドデータがファイルに保存されているのか識別可能な場合、 これらの関数は(type、sampling_rate、 channels、frames、bits_per_sample)のタプルを返しま す。 typeはデータの形式を示す文字列で、'aifc'、'aiff'、 'au'、'hcom'、'sndr'、'sndt'、'voc'、 'wav'、'8svx'、'sb'、'ub'、'ul'のうち の一つです。 sampling_rateは実際のサンプリングレート値で、未知の場合や読 み取ることが出来なかった場合は0です。 同様に、channelsはチャンネル数で、識別できない場合や読 み取ることが出来なかった場合は0です。framesはフレーム数で、識別できない場合は -1です。 タプルの最後の要素bits_per_sampleはサンプルサイズを示すビット数 ですが、A-LAWなら'A'、u-LAWなら 'U'です。

what( filename)
whathdr()を使って、ファイルfilenameに保存されたサウン ドデータの形式を識別します。 識別可能なら上記のタプルを返し、識別できない場合はNoneを返します 。

whathdr( filename)
ファイルのヘッダ情報をもとに、保存されたサウンドデータの形式を識別し ます。 ファイル名はfilenameで渡されます。 識別可能なら上記のタプルを返し、識別できない場合はNoneを 返します。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.9 imghdr Up: 14. マルチメディアサービス Next: 14.11 ossaudiodev


14.11 ossaudiodev -- OSS互換オーディオデバイスへのアクセス

利用可能な条件: Linux, FreeBSD, おそらく他の Unix 系システムでも.

このモジュールを使うとOSS (Open Sound System) オーディオインターフェース にアクセスできます。 OSSはオープンソースあるいは商用のUnixで広く利用可能で、Linux (カーネル 2.4まで) とFreeBSDで標準のオーディオインターフェースとなっています。

参考資料:

オープンサウンドシステムプログラマーズガイド
OSS C APIのための公式ドキュメント

このモジュールではOSSデバイスドライバーで提供される多くの定数を定義して います;定数のリストについてはLinuxかFreeBSDの<sys/soundcard.h>を 参照してください。

ossaudiodevには以下の変数と関数が定義されています:

exception error
この例外は特定のエラーを発生します。 引数は何が誤っているかを示す文字列です。

(もしossaudiodevがopen()、write()、 ioctl()などのシステムコールからエラーを受け取ったら IOErrorを発生します。 ossaudiodevモジュールによって直接検出されたエラーは ossaudiodev.errorになります。)

open( [device, ]mode)
オーディオデバイスを開いて、OSSオーディオデバイスオブジェクトを返しま す。 このオブジェクトはread()、write()、fileno() などのようにファイルのような多くのメソッドをサポートしています。 (しかし伝統的なUnixのread/writeの構文とOSSオーディオデバイスのものとの あいだには微妙な違いがあります) 。 また、オーディオ特有の多くのメソッドがあります;メソッドの完全なリストに ついては下記を参照してください。

呼び出しの文法が普通と異なることに注意してください:最初の引数が 省略可能で、2番目が必須です。 これはossaudiodevにとって替わられた古いlinuxaudiodevと の互換性のためという歴史的な産物です。

deviceは使用するオーディオデバイスファイルネームです。 もしこれが指定されないなら、このモジュールは使うデバイスとして最初に環境 変数AUDIODEVを参照します。 みつからなければ、/dev/dspを参照します。

modeは、読み込みのみ (再生) のアクセスの'r'、書き込みのみ ( 録音) のアクセスの'w'、それら両方の'rw'のうちのどれか1つで す。 多くのサウンドカードでは一つのプロセスで同時にレコーダかプレーヤしか持て ないので、操作が必要なときだけデバイスを開くのが良い考えです。 また、いくつかのサウンドカードは半二重 (half-duplex) です: これらでは読み込みあるいは書き込みで開けますが、同時に両方では開けませ ん。

openmixer( [device])
ミキサーデバイスを開いて、OSSミキサーデバイスオブジェクトを返します。 deviceは使用するミキサーデバイスのファイルネームです。 もしこれが指定されないなら、このモジュールは使うデバイスとして最初に環境 変数AUDIODEVを参照します。 みつからなければ、/dev/mixerを参照します。

  • 14.11.1 オーディオデバイスオブジェクト
  • 14.11.2 ミキサーデバイスオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.10 sndhdr Up: 14. マルチメディアサービス Next: 14.11.1 オーディオデバイスオブジェクト


14.11.1 オーディオデバイスオブジェクト

デバイスの設定

デバイスを設定するために、3つの関数を正しい順序で呼び出さなければなりま せん。

  1. setfmt()で出力フォーマットを設定し、
  2. channels()でチャンネル数を設定し、
  3. speed()でサンプリングレートを設定します。

open()で返されるオーディオデバイスオブジェクトには以下のメ ソッドがあります:

close( )
このメソッドはデバイスを明示的に閉じます。 他にデバイスを参照しているものがあって、オブジェクトをすぐに閉じることが できない場合に便利です。 閉じられたオブジェクトを再び使うことはできません。

fileno( )
デバイスに関連付けられたファイルディスクリプタを返します。

read( size)
オーディオ入力からサンプル数sizeを読み込んで、Python文字列として返 します。 この関数は必要なデータが得られるまでブロックします。

write( data)
Python文字列のdataをオーディオデバイスに書き込んで、書き込まれたバ イト数を返します。 もしオーディオデバイスがブロックモードで開かれたら、文字列全体が書き込ま れます。 もしデバイスが非ブロックモードで開かれたら、書き込まれないデータがあるか もしれません--writeall()を参照してください。

writeall( data)
Python文字列のdata全体をオーディオデバイスに書き込みます。 もしデバイスがブロックモードで開かれたらwrite()と同様に働きま す;非ブロックモードでは、デバイスにデータを与える前にデバイスが利用可能 になるまで待ちます。 書き込まれたデータの量は与えたデータと常に同じ量なので、Noneを返 します。

シンプルなI/Oコントロール:

nonblock( )
デバイスを非ブロックモードにします。 いったん非ブロックモードにしたら、ブロックモードに戻すことはできません。

I/Oコントロールに失敗したらIOErrorが発生します。

getfmts( )
サウンドカードでサポートされるオーディオ出力フォーマットのビットマスクを 返します。 典型的なLinuxシステムでは以下のフォーマットがあります:

フォーマット | 説明
AFMT_MU_LAW | 対数エンコーディング。 これは/dev/audioのデフォルトのフォーマットで、Sunの.auファイルで 使われているフォーマットです。
AFMT_A_LAW | 対数エンコーディング
AFMT_IMA_ADPCM | Interactive Multimedia Association で定められた4:1の圧縮フォーマット。
AFMT_U8 | 符号なし8ビットオーディオ。
AFMT_S16_LE | 符号なし16ビットオーディオでリトルエンディアン (Intelプロセッサで使われ るフォーマット)
AFMT_S16_BE | 符号なし16ビットオーディオでビッグエンディアン (68k、PowerPC、Sparcで使 われるフォーマット)
AFMT_S8 | 符号つき8ビットオーディオ。
AFMT_U16_LE | 符号つき16ビットリトルエンディアンオーディオ
AFMT_U16_BE | 符号つき16ビットビッグエンディアンオーディオ
たいていのシステムではこれらのフォーマットのうちのいくつかだけをサポート しています。 多くのデバイスではAFMT_U8だけをサポートしています;現在使われ ている最も一般的なフォーマットはAFMT_S16_LEです。

setfmt( format)
現在のオーディオフォーマットをformatにします-- formatについてはgetfmts()のリストを参照してください。 また、現在のオーディオフォーマットを返すのにも使えます-- これは``オーディオフォーマット''としてAFMT_QUERYを渡すことで できます。 デバイスに設定されたオーディオフォーマットが返されますが、設定するよう要 求したフォーマットではないかもしれません。

channels( num_channels)
出力チャンネル数をnum_channelsに設定します。 値1はモノラル、2はステレオを示します。 いくつかのデバイスでは2つより多いチャンネルを持つものもありますし、 ハイエンドなデバイスではモノラルをサポートしないものもあります。 デバイスに設定されたチャンネル数を返します。

speed( samplerate)
サンプリングレートを1秒あたりsamplerateに設定し、実際に設定された レートを返します。 たいていのサウンドデバイスでは任意のサンプリングレートをサポートしていま せん。 一般的なレートは以下の通りです:

8000--デフォルトのレート 11025--声の録音 22050 44100--オーディオCD品質 (2チャンネルで16ビット/サンプル) 96000--DVD品質

sync( )
サウンドデバイスがバッファ内の全てのバイトを再生するまで待って、それから 制御が戻ります。 これはサウンドデバイスが閉じられるときにも起こります。 OSSの文書ではsync()を使うよりもデバイスを単純に閉じて、再び開く ことを推奨しています。

reset( )
再生あるいは録音を中止して、デバイスをコマンド待ちの状態にします。 OSSの文書ではreset()を呼び出した後にデバイスを閉じて、再び開く ことを推奨しています。

post( )
簡単なsync()のように使われます。post()のI/Oコントロー ルによってオーディオデバイスにオーディオ出力にポーズがある--つまり、短 いサウンドエフェクトの後や、ユーザの入力待ちの前、あるいはディスクI/Oの 前であることを伝えます。

便利なメソッド

setparameters( samplerate,num_channels,format,emulate)
サウンドデバイスを一つのメソッドで初期化します。 samplerate、channels、formatは speed()、channels()、setfmt()で述べたものでな ければなりません。 もしemulateがTrueなら、もっともマッチするフォーマットを見つけよう としますが、そうでないなら、指定したフォーマットをデバイスがサポートしな ければValueErrorを発生します。 デフォルトではサポートしないフォーマットに対してValueErrorを発生します。

bufsize( )
ハードウェアのバッファサイズをサンプル数で返します。

obufcount( )
ハードウェアバッファにある、再生されるサンプル数を返します。

obuffree( )
ブロックすることなしにハードウェアのキューに書き込んで再生できるサンプル 数を返します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.11 ossaudiodev Up: 14.11 ossaudiodev Next: 14.11.2 ミキサーデバイスオブジェクト


14.11.2 ミキサーデバイスオブジェクト

ファイルに似たインターフェース

close( )
このメソッドは、開かれたミキサーデバイスファイルを閉じます。 ファイルを閉じた後でミキサーを使おうとすると、IOErrorを発生します。

fileno( )
開いたミキサーデバイスファイルのファイルハンドルナンバーを返します。

ミキサーインターフェース

controls( )
このメソッドは、利用可能なミキサーコントロールを指定するビットマスクを返 します (``コントロール''はミックス可能な特定の``チャンネル''で、たとえば SOUND_MIXER_PCMあるいはSOUND_MIXER_SYNTHです) 。 このビットマスクは全ての利用可能なミキサーチャンネルのサブセットを示しま す --定数SOUND_MIXER_*はモジュールレベルで定義されています。 例えば、もし現在のミキサーオブジェクトがPCMミキサーをサポートしているか 調べるには、以下のPythonコードを実行します:

mixer=ossaudiodev.openmixer()
if mixer.channels() & (1 << ossaudiodev.SOUND_MIXER_PCM):
    # PCM is supported
    <code>

たいていの目的では、SOUND_MIXER_VOLUME (マスターボリューム) とSOUND_MIXER_PCMチャンネルで十分です-- しかし、サウンドチャンネルを選ぶときに、ミキサーを使用するコードはフレキ シブルでなければなりません。 例えば、Gravis UltrasoundではSOUND_MIXER_VOLUMEは存在しませ ん。

stereocontrols( )
ステレオミキサーチャンネルを示すビットマスクを返します。 もしビットがセットされていたら対応するチャンネルはステレオで、もしセット されていないならそのチャンネルはモノラルか、ミキサーでサポートされていな いかどちらかです (そのどちらかを調べるにはchannels()を組み合わ せて使います) 。

ビットマスクのデータを得る例としては、関数channels()のコードの 例を参照してください。

reccontrols( )
録音に使用できるミキサーコントロールを特定するビットマスクを返します。 ビットマスクから読み取る例としては、controls()のコードの例を参 照してください。

get( channel)
与えられたミキサーのチャンネルのボリュームを返します。 返される値は2要素のタプル(left_volume,right_volume)です。 ボリュームの値は0 (無音) から100 (最大) で示されます。 もしチャンネルがモノラルでも2要素のタプルが返されますが、2つの要素の値は 同じになります。

もし未知のチャンネルが指定されたら、errorが発生します。

set( channel, (left, right))
与えられたミキサーチャンネルのボリュームを(left,right)に設定しま す。 leftとrightは整数で、0 (無音) から100 (最大) の間でなけれ ばなりません。 成功したら、新しいボリューム値が2要素のタプルで返されます。 あるサウンドカードではミキサーの分解能の限界のため、指定したボリューム値 と厳密には同じにならないかもしれません。

もし不正なミキサーのチャンネルが指定されたら、IOErrorが発生 します; 引数のフォーマットが正しくないならTypeErrorが発生し、指定し たボリューム値が範囲外ならerrorが発生します。

get_recsrc( )
このメソッドは、現在録音のソースとして使われているチャンネルを示すビット マスクを返します。

set_recsrc( bitmask)
録音のソースを指定するのにこの関数を使います。 成功したら、新たな録音のソースを示すビットマスクを返します; 不正なソースが指定されたらIOErrorが発生します。 現在の録音のソースとしてマイク入力を設定する方法は以下の通りです:

mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.11.1 オーディオデバイスオブジェクト Up: 14.11 ossaudiodev Next: 15. 暗号関連のサービス


15. 暗号関連のサービス

この章で記述されているモジュールでは、暗号の本質に関わる様々な アルゴリズムを実装しています。これらは必要に応じてインストール することで使えます。概要を以下に示します:

hmac | Python で実装された、メッセージ認証のための鍵付き ハッシュ化 (HMAC: Keyed-Hashing for Message Authentication) アルゴリズム。
md5 | RSA's MD5 message digest algorithm.
sha | NISTのセキュアハッシュアルゴリズム、SHA。
mpz | 多倍精度における算術演算を実現する GNU MP ライブラリへのインタフェース。
rotor | エニグマ暗号機のような暗号化と復号化。

あなたがハードコアなサイバーパンクなら、さらに A.M. Kuchling の書いた暗号化モジュールに興味を持つかもしれません。このパッケージ では組み込みの DES および IDEA 暗号を追加し、PGP 暗号化されたファイル の読み込みや復号化を行うためのモジュールなどを提供します。 これらのモジュールは Python と一緒には配布されず、別に入手できます。 詳細は http://www.amk.ca/python/code/crypto.html を見てください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 14.11.2 ミキサーデバイスオブジェクト Up: Python ライブラリリファレンス Next: 15.1 hmac


15.1 hmac -- メッセージ認証のための鍵付きハッシュ化

バージョン2.2 以降で新規追加された 仕様です。

このモジュールでは RFC 2104 で記述されている HMAC アルゴリズム を実装しています。

new( key[, msg[, digestmod]])
新たな hmac オブジェクトを返します。msg が存在すれば、 メソッド呼び出し updatemsg を行います。 digestmod は HMAC オブジェクトが使うダイジェストモジュール です。標準では md5 モジュールになっています。

HMAC オブジェクトは以下のメソッドを持っています:

update( msg)
hmac オブジェクトを文字列 msg で更新します。繰り返し呼び出し を行うと、それらの引数を全て結合した引数で単一の呼び出しをした 際と同じに等価になります: すなわち m.update(a); m.update(b) は m.update(a + b) と等価です。

digest( )
これまで update() メソッドに渡された文字列のダイジェスト値 を返します。個の値は 16 バイトの文字列 (md5 の場合) か、 20 バイトの文字列 (sha の場合) で、NULL バイトを含む 非 ASCII 文字が含まれることがあります。

hexdigest( )
digest() と似ていますが、ダイジェスト値が md5 のときで長さ 32 文字 (sha のときで 40文字) の 16進数字 のみを含む文字列で返されます。この値は電子メールやその他の非バイナリ 環境で値をやり取りする際に使うことができます。

copy( )
hmac オブジェクトの (``クローン'' の)　コピーを返します。このコピー は最初の部分文字列が共通になっている文字列のダイジェスト値を効率 よく計算するために使うことができます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 15. 暗号関連のサービス Up: 15. 暗号関連のサービス Next: 15.2 md5


15.2 md5 -- MD5 メッセージダイジェストアルゴリズム

このモジュールは RSA 社の MD5 メッセージダイジェスト アルゴリズムへのインタフェースを実装しています。 (Internet RFC 1321 も参照してください)。利用方法は極めて単純 です。まず md5 オブジェクトを new() を使って生成します。 後は update() メソッドを使って、生成されたオブジェクトに 任意の文字列データを入力します。オブジェクトに入力された文字列 データ全体の digest (``fingerprint'' として知られる強力な 128-bit チェックサム) は digest() を使っていつでも調べる ことができます。

例えば、文字列 'Nobody inspects the spammish repetition' のダイジェストを得るためには以下のようにします:

>>> import md5
>>> m = md5.new()
>>> m.update("Nobody inspects")
>>> m.update(" the spammish repetition")
>>> m.digest()
'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'

もっと詰めて書くと以下のようになります:

>>> md5.new("Nobody inspects the spammish repetition").digest()
'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'

以下の値はモジュールの中で定数として与えられており、new() で返される md5 オブジェクトの属性としても与えられます:

digest_size
返されるダイジェスト値のバイト数で表した長さ。常に 16 です。

md5 クラスオブジェクトは以下のメソッドをサポートします:

new( [arg])
新たな md5 オブジェクトを返します。もし arg が存在するなら、 update(arg) を呼び出します。

md5( [arg])
下位互換性のために、new() の別名として提供されています。

md5 オブジェクトは以下のメソッドをサポートします:

update( arg)
文字列 arg を入力として md5 オブジェクトを更新します。 このメソッドを繰り返して呼び出す操作は、それぞれの呼び出し時の引数 arg を結合したデータを引数として一回の呼び出す操作と同等 になります: つまり、m.update(a); m.update(b) は m.update(a+b) と同等です。

digest( )
これまで update() で与えてきた文字列入力のダイジェストを 返します。返り値は 16 バイトの文字列で、null バイトを含む非 ASCII 文字が入っているかもしれません。

hexdigest( )
digest() に似ていますが、ダイジェストは長さ 32 の文字列 になり、16 進表記文字しか含みません。この文字列は電子メールやその 他のバイナリを受け付けない環境でダイジェストを安全にやりとりする ために使うことができます。

copy( )
md5 オブジェクトのコピー (``クローン'') を返します。冒頭の部分文字列が 共通な複数の文字列のダイジェストを効率よく計算する際に使うことができます。

参考資料:

shaモジュール:
Secure Hash Algorithm (SHA) を実装した類似のモジュール。 SHA アルゴリズムはより安全なハッシュアルゴリズムだと考えられています。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 15.1 hmac Up: 15. 暗号関連のサービス Next: 15.3 sha


15.3 sha -- SHA-1 メッセージダイジェストアルゴリズム

このモジュールは、SHA-1 として知られている、 NISTのセキュアハッシュアルゴリズムへのインターフェースを 実装しています。SHA-1 はオリジナルの SHA ハッシュアルゴリズムを改善した バージョンです。md5 モジュールと同じように使用します。: sha オブジェクトを生成するために new() を使い、 update() メソッドを使って、このオブジェクトに任意の文字列を入力し、 それまでに入力した文字列全体の digest をいつでも調べることができます。 SHA-1 のダイジェストは MD5 の 128 bit とは異なり、 160 bit です。

new( [string])
新たな sha オブジェクトを返します。もし string が存在するなら、update(string) を呼び出します。

以下の値はモジュールの中で定数として与えられており、new() で返される sha オブジェクトの属性としても与えられます:

blocksize
ハッシュ関数に入力されるブロックのサイズ。 このサイズは常に 1 です。 このサイズは、任意の文字列をハッシュできるようにするために使われます。

digest_size
返されるダイジェスト値をバイト数で表した長さ。常に 20 です。

sha オブジェクトには md5 オブジェクトと同じメソッドがあります。

update( arg)
文字列 arg を入力として sha オブジェクトを更新します。 このメソッドを繰り返し呼び出す(操作は、それぞれの呼び出し時の引数を結合した データを引数として一回の呼び出す操作と同等になります。つまり、 m.update(a); m.update(b) は m.update(a+b) と同等です。

digest( )
これまで update() メソッド で与えてきた文字列のダイジェストを返します。 戻り値は 20 バイトの文字列で、nullバイトを含む非 ASCII 文字が入っているか もしれません。

hexdigest( )
digits() と似ていますが、ダイジェストは長さ40の文字列になり、16進表記数字しか含みません。 電子メールやその他のバイナリを受け付けない環境で安全に値をやりとりするために使うことができます。

copy( )
sha オブジェクトのコピー(``クローン'')を返します。 冒頭の部分文字列が共通な複数の文字列のダイジェストを効率よく計算する際に使う ことができます。

参考資料:

セキュアハッシュスタンダード
セキュアハッシュアルゴリズムは NIST のドキュメント FIPS PUB 180-1 で定義されています。 セキュアハッシュスタンダード, 1995年4月出版。

プレインテキスト(少なくとも一つの図が省略されています)と http://csrc.nist.gov/publications/fips/fips180-1/fip180-1.pdfにある PDF でオンラインから入手できます。

暗号ツールキット (セキュアハッシュ)
NISTからはられているセキュアハッシュに関するさまざまな情報へのリンク
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 15.2 md5 Up: 15. 暗号関連のサービス Next: 15.4 mpz


15.4 mpz -- GNU 多倍長整数

リリース 2.2 以降で撤廃された仕様です。 この節の末尾にある参考文献を読んで下さい。同様の機能を提供するパッケージについての情報があります。このモジュールは Python 2.3 で除去されます。

このモジュールはオプションです。モジュールを含むように設定して Python を 構築した際にのみ利用可能であり、GNU MP ソフトウェアがインストールされて いることが必要です。

このモジュールは GNU MP ライブラリの一部の機能へのインタフェースを 実装しています。GNU MP ライブラリは多倍精度の整数および有理数 に対する算術演算ルーチンを定義しています。整数だけの インタフェース (mpz_*()) が提供されています。 特に注釈のない限り、GNU MP ドキュメントに記述されている内容が 適用されます。

有理数のサポート は Python で実装されて います。例えば、Python ソースコード配布中の Demos/classes/Rat.py で提供されている Rat モジュール を参照してください。

一般的に、mpz 型の数値は他の標準の Python 数値と同様に使う ことができます。例えば、+、*、などといった組み込み演算子 や、abs(), int() ..., divmod(), pow() といった、標準の組み込み関数を使うことができます。 注意してください: ライブラリには mpz_xor() が なく、私にとっても必要ないので、ビット単位のxor 演算は and、invert、or を組み合わせて実装 されています。

mpz 型の数値は mpz() を呼び出して生成します (厳密な解説に ついては下を参照してください)。mpz 型の数値は以下のように印字されます: mpz(value)

mpz( value)
新しい mpz 型数値を生成します。value は通常の整数、長整数、 その他の mpz 型数値、そして文字列にすることもできます。文字列の 場合、引数は 256 進数の桁からなるアレイとして解釈され、最下桁 が前で、値は正の数になります。下で記述されている binary() を参照してください。

MPZType
mpz() およびこのモジュール中の他のほとんどの関数が返す オブジェクトの型です。

個のモジュールでは多くの 外部 関数が定義されています。 mpz 型でない引数はまず mpz 型の値に変換され、関数は mpz 型の数値 を返します。

powm( base, exponent, modulus)
pow(base, exponent) % modulus を返します。 exponent == 0 の場合、mpz(1) を返します。 C ライブラリ関数とは対照的に、この関数は負の指数を扱うことが できます。

gcd( op1, op2)
op1 および op2 の最大公約数を返します。

gcdext( a, b)
a*s + b*t == g == gcd(a, b) であるようなタプル (g, s, t) を返します。

sqrt( op)
op の平方根を返します。結果はゼロの向きに丸められます。

sqrtrem( op)
root*root + remainder == op となるようなタプル (root, remainder) を返します。

divm( numerator, denominator, modulus)
q * denominator % modulus == numerator となる値 q を返します。この関数は gcdext() を使って Python で実装することもできます。

mpz 数値型は一つのメソッドを持ちます:

binary( )
mpz 型の数値をバイナリ文字列に変換します。数値は 256 進数の桁からなる アレイに記憶されます。最小の桁が先頭になります。

mpz 型の数値はゼロまたはそれ以上の値をもたなければなりません。 そうでない場合 ValueError が送出されます。

参考資料:

General Multiprecision Python
このプロジェクトでは多倍精度の算術演算を Python で行えるようにする 新たな数値型を構築中です。彼らの最初の試みも GNU MP ライブラリに 基づいています。

mxNumber -- Extended Numeric Types for Python
もう一つの GNU MP ライブラリに対するラッパです。Windows に移植された GNU MP ライブラリを含みます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 15.3 sha Up: 15. 暗号関連のサービス Next: 15.5 rotor


15.5 rotor -- エニグマ暗号機のような暗号化と復号化

リリース 2.3 以降で撤廃された仕様です。 この暗号化アルゴリズムは安全ではありません。

このモジュールは Lance Ellinghouseに よって寄与されたロータによる暗号化アルゴリズムを実装しています。 この設計は第二次世界大戦中メッセージを暗号化するために用いられた エニグマ暗号機からきたものです。ロータは単純に文字の入れ替えです。 例えば `A' をロータの起点とすると、このロータは `A' を `L' に、 `B' を `Z' に、`C' を `G' に、等に関連付けるでしょう。暗号化 を行うためには、複数の異なるロータを選び、ロータの起点を既知の 位置に設定します; それらの初期位置が暗号化の鍵となります。 文字を暗号化するには、原文の文字を最初のロータによって入れ替え、 次にその結果を二つ目のロータで入れ替えます。そして全てのロータ で入れ替え終わるまでこれを続けます。結果として得られた文字が 暗号文になります。次に最終段ロータの起点位置を一つだけずらし、 `A' を `B' にします; 最終段ロータの起点位置が完全に一周したら、 最終段から 2 段目のロータを一つだけずらし、同じ手続きを再帰的に 繰り返します。別の言い方をすれば、一つの文字を暗号化した後は、 ロータを車の距離計と同じ要領で一つ進めるということです。 復号化の作業も同様です。ただし、置き換えを反転し、操作を逆に 行います。

個のモジュールで利用可能な関数は以下のとおりです:

newrotor( key[, numrotors])
ロータオブジェクトを返します key はロータオブジェクトの 暗号化キー文字列です; ヌル文字以外の任意のバイナリデータを含む ことができます。暗号化キーはロータの置き換え順列をランダムに 生成し、初期位置を決めるために使われます。numrotors は 返されるロータオブジェクト中におけるロータ置き換えの数です。 省略される場合、標準の値として 6 が使われます。

ロータオブジェクトは以下のメソッドを持っています:

setkey( key)
ロータの暗号化キーを key にします、暗号化キーにヌル文字を入れては いけません。

encrypt( plaintext)
ロータオブジェクトを初期状態に再初期化し、plaintext を暗号化して、暗号文を含む文字列を返します。暗号文は常に もとの平文と同じ長さになります。

encryptmore( plaintext)
ロータオブジェクトを再初期化せずに plaintext を暗号化し、 暗号文を含む文字列を返します。

decrypt( ciphertext)
ロータオブジェクトを初期状態に再初期化し、ciphertext を復号化して、平文を含む文字列を返します。平文は常に 暗号文と同じ長さになります。

decryptmore( ciphertext)
ロータオブジェクトを再初期化せずに ciphertext を復号化し、 平文を含む文字列を返します。

利用法の例:

>>> import rotor
>>> rt = rotor.newrotor('key', 12)
>>> rt.encrypt('bar')
'\xab4\xf3'
>>> rt.encryptmore('bar')
'\xef\xfd$'
>>> rt.encrypt('bar')
'\xab4\xf3'
>>> rt.decrypt('\xab4\xf3')
'bar'
>>> rt.decryptmore('\xef\xfd$')
'bar'
>>> rt.decrypt('\xef\xfd$')
'l(\xcd'
>>> del rt

このモジュールのコードはオリジナルのエニグマ暗号機の厳密な シミュレーションではありません; これはオリジナルのロータ暗号化 手続きを異なる方法で実装しています。 オリジナルのエニグマとの最も重要な違いは、エニグマでは異なる ロータは実際には 5 から 6 個しか存在せず、一文字あたり 2 回づつ ロータを適用していたことです; 暗号化キーはロータを暗号機に 配置する順番でした。Python の rotor モジュールでは、 与えられたキーはまず乱数生成器を初期化するために使います; 次にロータの順列およびその初期位置がランダムに決定されます。 オリジナルの暗号機ではアルファベット文字だけを暗号化していたのに 対し、このモジュールは 8 ビットの任意のバイナリデータを扱う ことができ、またバイナリ出力を生成します。このモジュールは また、任意の数のロータを扱うことができます。

オリジナルのエニグマ暗号は 1944 年に解読されました。 ここで実装されているバージョンを解読するのは、おそらくそれよりかなり 困難ですが、非常に高い技術を持ち、確信犯の攻撃者が暗号を解読するのは 不可能ではありません。従って、NSA からあなたのファイルを守りたいと 思うなら、このロータ暗号は全く安全とはいえませんが、行きずりの来訪者 にあなたのファイルを覗き見する気力を無くさせるためにはおそらくちょうど よいでしょう。そして Unix の crypt コマンドを使うよりも やや安全かもしれません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 15.4 mpz Up: 15. 暗号関連のサービス Next: 16. Tkを用いたグラフィカルユーザインターフェイス


16. Tkを用いたグラフィカルユーザインターフェイス

Tk/Tclは長らくPythonの欠くことのできない一部となっていて、頑健でプラットホームに依存しないウィンドウ・ツールキットです。PythonプログラマがTk/Tclを利用するには、Tkinterモジュールとその拡張であるTixモジュールを使います。

TkinterモジュールはTcl/Tkの上に作られた軽量なオブジェクト指向レイヤです。Tkinterを使うために、Tclコードを書く必要はありません。しかし、Tkドキュメントと、時々はTclドキュメントを調べる必要はあります。TkinterはPythonクラスとしてTkウィジェットを実装する一連のラッパーです。それに加えて、内部モジュール_tkinterはPythonとTclに相互作用を許すスレッドセーフ・メカニズムを提供します。

TkはPythonにとってただ一つのGUIと言う訳ではありませんが、もっともよく使われているものです。Python用の他のGUIツールキットに関するこれ以上の情報については、16.6章``他のユーザインターフェイスモジュールとパッケージ''を参照してください。

Tkinter | グラフィカルユーザインターフェイスのためのTcl/Tkへのインターフェイス
Tix | Tkinter用のTk拡張ウィジェット
ScrolledText | 垂直スクロールバーを持つテキストウィジェット。
turtle | タートルグラフィックスのための環境。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 15.5 rotor Up: Python ライブラリリファレンス Next: 16.1 Tkinter


16.1 Tkinter -- Tcl/TkへのPythonインターフェイス

Tkinterモジュール(``Tk interface'')は、Tk GUIツールキットに対する標準のPythonインターフェイスです。WindowsとMacintoshシステム上と同じく、ほとんどのUnixプラットホームでTkとTkinterは利用できます。(Tk自体はPythonの一部ではありません。ActiveStateによって保守されています。)

参考資料:

Python Tkinter Resources
Python Tkinter Topic Guideは、PythonからTkの使うことについての情報と他のTkに関する情報源へのリンクを非常にたくさん提供しています。

An Introduction to Tkinter
Fredrik Lundhのオンライン・リファレンス資料

Tkinter reference: a GUI for Python
オンライン・リファレンス資料

Tkinter for JPython
Tkinterに対するJythonインターフェイス

Python and Tkinter Programming
John Graysonによる解説書(ISBN 1-884777-81-3)。

  • 16.1.1 Tkinterモジュール
  • 16.1.2 Tkinter Life Preserver
    • 16.1.2.1 この節の使い方
    • 16.1.2.2 簡単なHello Worldプログラム
  • 16.1.3 Tcl/Tkに(非常に)さっと目を通す
  • 16.1.4 基本的なTkをTkinterへマッピングする
  • 16.1.5 TkとTkinterはどのように関係なのか
  • 16.1.6 便利なリファレンス
    • 16.1.6.1 オプションの設定
    • 16.1.6.2 Packer
    • 16.1.6.3 Packer Options
    • 16.1.6.4 ウィジェット変数を結びつける
    • 16.1.6.5 ウィンドウマネージャ
    • 16.1.6.6 Tkオプションデータ型
    • 16.1.6.7 バインドとイベント
    • 16.1.6.8 index パラメータ
    • 16.1.6.9 画像
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16. Tkを用いたグラフィカルユーザインターフェイス Up: 16. Tkを用いたグラフィカルユーザインターフェイス Next: 16.1.1 Tkinterモジュール


16.1.1 Tkinterモジュール

ほとんどの場合、本当に必要となるのはTkinterモジュールだけですが、それに加えて、たくさんの追加モジュールが利用できます。Tkインターフェイスは_tkinterと言う名前のバイナリモジュール内に存在します。このモジュールにはTkへの低レベルのインターフェイスが含まれており、アプリケーションプログラマは決して直接使うべきではありません。たいてい共有ライブラリ(またはDLL)ですが、時にはPythonインタープリタに静的にリンクされることもあります。

Tkインターフェイス・モジュールに加えて、Tkinterには多くのPythonモジュールが含まれています。最も重要なモジュールが二つあり、Tkinterモジュール自身とTkconstantsと呼ばれるモジュールです。前者は自動的に後者をインポートします。従って、Tkinterを使うためには、一つのモジュールをインポートするだけで良いのです:

import Tkinter

あるいは、より多くの場合には:

from Tkinter import *

class Tk( screenName=None, baseName=None, className='Tk')
Tkクラスは引数なしでインスタンス化されます。これはTkのトップレベル・ウィジェットを作り出し、多くの場合にアプリケーションのメインウィンドウとなります。それぞれのインスタンスは、それ自身に対応するTclインタープリタを持っています。

Tkサポートを提供する他のモジュールには次のものが含まれています:

ScrolledText
垂直スクロールバー付きのテキストウィジェット。

tkColorChooser
ユーザが色を選択するためのダイアログ。

tkCommonDialog
ここにリストされている他のモジュール内で定義されるダイアログのためのベースクラス。

tkFileDialog
ユーザがオープンまたはセーブするためのファイルを指定できるようにするコモンダイアログ。

tkFont
フォントの扱いを補助するためのユーティリティ。

tkMessageBox
標準的なTkダイアログボックスへのアクセス。

tkSimpleDialog
基本的なダイアログと便利な機能。

Tkdnd
Tkinterのためのドラッグアンドドロップのサポート。これは実験的なもので、Tk DNDに置き替えられると使うことは推奨されなくなるはずです。

turtle
Tkウィンドウでのタートルグラフィックス。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1 Tkinter Up: 16.1 Tkinter Next: 16.1.2 Tkinter Life Preserver


16.1.2 Tkinter Life Preserver

この節はTkまたはTkinterのどちらかのすべてを網羅したチュートリアルを意図したものではありません。むしろ、システムについて学びはじめるための説明を提供する間に合わせのようなものです。

謝辞:

  • TkinterはSteen LumholtとGuido van Rossumによって作成されました。
  • TkはJohn OusterhoutによってBerkeleyに在籍中に作成されました。
  • このLife PreserverはVirginia大学のMatt Conway他によって書かれました。
  • htmlレンダリングおよび多くの編集は、Ken ManheimerによってFrameMakerバージョンから生成されました。
  • Fredrik Lundhは現行のTk 4.2に合わせるためにクラスインターフェイスについての詳しい説明を書き、改訂しました。
  • Mike ClarksonはドキュメンテーションをLATEXへ変換し、リファレンスマニュアルのユーザインターフェイスの章をコンパイルしました。

  • 16.1.2.1 この節の使い方
  • 16.1.2.2 簡単なHello Worldプログラム
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.1 Tkinterモジュール Up: 16.1 Tkinter Next: 16.1.2.1 この節の使い方


16.1.3 Tcl/Tkに(非常に)さっと目を通す

クラス階層は複雑に見えますが、実際の実務ではアプリケーションプログラマはほとんど常に階層のもっとも底辺にあるクラスを参照します。

注釈:

  • これらのクラスは一つの名前空間に関数をまとめる目的で提供されます。それらは独立してインスタンス化されることを意図しています。

  • Tkクラスはアプリケーション内で一度だけインスタンス化されるように意図されています。アプリケーションプログラマが明示的にインスタンス化する必要はなく、他のクラスがインスタンス化されたときにすぐシステムが作成します。

  • Widgetクラスはインスタンス化されることを意図しておらず、``本物の''ウィジェットを作るためにサブクラス化することだけを意図しています(C++では、これは`抽象クラス'と呼ばれています)。

このリファレンス資料を使うために、Tkの短い進行を読む方法とTkコマンドのいろいろな部分を識別する方法を知る必要があるということはままあるでしょう。 (下に説明してあるものとTkinterにおける同等なものについては、節 16.1.4を参照してください。)

TkスクリプトはTclプログラムです。すべてのTclプログラムのように、Tkスクリプトは空白で区切られたトークンを並べたものです。Tkウィジェットはウィジェットのクラス、その設定を行うオプションと、それに役立つことをさせるアクションです。

Tkにおけるウィジェットを作るには、コマンドは常に次のような形式です:

                classCommand newPathname options

classCommand
どの種類のウィジェットを作るかを表します(ボタン、ラベル、メニュー、...)

newPathname
このウィジェットの新しい名前です。Tkのすべての名前はただ一つしか存在することが許されません。これを必ず実行するのを助けるために、ちょうどファイルシステム内のファイルのように、Tkのウィジェットにはパス名のある名前が付けられます。トップレベルウィジェットルートは. (ピリオド)と呼ばれていて、子はさらにピリオドで区切られています。例として、.myApp.controlPanel.okButtonはウィジェットの名前です。

options
ウィジェットの見た目や場合によっては振る舞いを設定します。オプションはフラグと値のリスト形式で渡されます。unixシェルコマンドのフラグのように、フラグは`-'の後に続きます。また、値は一語以上ある場合には引用符内に置かれます。

例として:

    button   .fred   -fg red -text "hi there"
       ^       ^     \_____________________/
       |       |                |
     class    new            options
    command  widget  (-opt val -opt val ...)

一旦作られたら、ウィジェットへのパス名は新しいコマンドとなります。この新しいwidget commandは、actionを実行する新しいウィジェットを得るためのプログラマのハンドルです。CではこれをsomeAction(fred, someOptions)と表し、C++ではfred.someAction(someOptions)と表すでしょう。そして、Tkでは:

    .fred someAction someOptions

とします。オブジェクト名.fredがドットから始まっていることに注意してください。

あなたが期待するように、someActionに対する正当な値はウィジェットのクラスに依存します: fredがボタンなら.fred disableは機能しますが(fredはグレーになります)、fredがラベルなら機能しません(Tkではラベルの無効化をサポートしていません)。

someOptionsの正当な値はアクション依存です。disableのようないくつかのアクションは引数を必要としませんが、テキストエントリボックスのdeleteコマンドのような他のものは、削除するテキストの範囲を指定するための引数を必要とします。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.2.2 簡単なHello Worldプログラム Up: 16.1 Tkinter Next: 16.1.4 基本的なTkをTkinterへマッピングする


16.1.4 基本的なTkをTkinterへマッピングする

Tkのクラスコマンドは、Tkinterのクラスコンストラクタに対応します。

    button .fred                =====>  fred = Button()

オブジェクトの親は作成時に与えられた新しい名前の中に暗に示されます。Tkinterでは、親は明示的に指定されます。

    button .panel.fred          =====>  fred = Button(panel)

Tkの設定オプションは値に続くハイフン付きのタグのリストに入れて与えられます。Tkinterでは、オプションはインスタンス・コンストラクタのキーワード引数とconfigure呼び出しに対するキーワード引数として指定されるか、または既に作成されたインスタンスに対する辞書形式でのインスタンス・インデックスとして指定されます。節 16.1.6を参照してください。

    button .fred -fg red        =====>  fred = Button(panel, fg = "red")
    .fred configure -fg red     =====>  fred["fg"] = red
                                OR ==>  fred.config(fg = "red")

Tkでは、ウィジェット上でアクションを実行するために、コマンドとしてウィジェット名を用います。そして、場合によっては引数(オプション)を付けて、それにアクション名を続けます。Tkinterでは、ウィジェットのアクションを呼び出すために、クラスインスタンスに対してメソッドを呼び出します。与えられたウィジェットが実行できるアクション(メソッド)は、Tkinter.pyモジュールの中にリストされています。

    .fred invoke                =====>  fred.invoke()

ウィジェットをpacker (ジオメトリマネージャ)に渡すためには、オプションの引数付きでpackを呼び出します。Tkinterでは、Packクラスがこの機能をすべて持っており、packコマンドのいろいろな形式がメソッドとして実装されています。Tkinterの全ウィジェットはPackerからサブクラス化されており、従って、すべてのpackするメソッドを継承しています。Formジオメトリマネージャに関する追加情報については、Tixモジュールのドキュメンテーションを参照してください。

    pack .fred -side left       =====>  fred.pack(side = "left")

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.3 Tcl/Tkに(非常に)さっと目を通す Up: 16.1 Tkinter Next: 16.1.5 TkとTkinterはどのように関係なのか


16.1.5 TkとTkinterはどのように関係なのか

注意: これはグラフィック・イメージから導き出されました。このドキュメントの続きのバージョンで、そのイメージはより直接的に用いられるでしょう。

上から下に:

あなたのアプリはここです(Python)
PythonアプリケーションはTkinterを呼び出します。

Tkinter (Pythonモジュール)
この呼び出し(例えば、ボタンウィジェットの作成)は、Tkinterモジュール内で実装されています。それはPythonで書かれています。このPython関数はそのコマンドと引数を解析し、Pythonスクリプトの代わりにまるでTkスクリプトから来たように見える形式に変換します。

tkinter (C)
これらのコマンドと引数はtkinter内のC関数へ渡されます - 小文字であることに注意 - 拡張モジュール。

Tk Widgets (C and Tcl)
Tkライブラリを構成するC関数を含む他のCモジュールを、このC関数は呼び出すことができます。TkはCといくらかのTclで実装されています。TkウィジェットのTcl部分は、ウィジェットへあるデフォルトの振る舞いをバインドするために使われます。そして、PythonのTkinterモジュールがインポートされた時点で一度だけ実行されます(この段階をユーザが見たりすることはありません)。

Tk (C)
TkウィジェットのTk部分は最終的なマッピングを実装します...

Xlib (C)
スクリーン上にグラフィックスを描くためのXlibライブラリ。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.4 基本的なTkをTkinterへマッピングする Up: 16.1 Tkinter Next: 16.1.6 便利なリファレンス


16.1.6 便利なリファレンス

  • 16.1.6.1 オプションの設定
  • 16.1.6.2 Packer
  • 16.1.6.3 Packer Options
  • 16.1.6.4 ウィジェット変数を結びつける
  • 16.1.6.5 ウィンドウマネージャ
  • 16.1.6.6 Tkオプションデータ型
  • 16.1.6.7 バインドとイベント
  • 16.1.6.8 index パラメータ
  • 16.1.6.9 画像
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.5 TkとTkinterはどのように関係なのか Up: 16.1 Tkinter Next: 16.1.6.1 オプションの設定


16.2 Tix -- Tkの拡張ウィジェット

Tix (Tk Interface Extension)モジュールは豊富な追加ウィジェットを提供します。標準Tkライブラリには多くの有用なウィジェットがありますが、完全では決してありません。Tixライブラリは標準Tkに欠けている一般的に必要とされるウィジェットの大部分を提供します: HList、ComboBox、Control (別名SpinBox)および各種のスクロール可能なウィジェット。Tixには、一般的に幅広い用途に役に立つたくさんのウィジェットも含まれています: NoteBook、FileEntry、PanedWindowなど。それらは40以上あります。

これら全ての新しいウィジェットと使うと、より便利でより直感的なユーザインターフェイス作成し、あなたは新しい相互作用テクニックをアプリケーションに導入することができます。アプリケーションとユーザに特有の要求に合うように、大部分のアプリケーションウィジェットを選ぶことによって、アプリケーションを設計できます。

参考資料:

Tix Homepage
Tixのホームページ。 ここには追加ドキュメントとダウンロードへのリンクがあります。
Tix Man Pages
manページと参考資料のオンライン版。
Tix Programming Guide
プログラマ用参考資料のオンライン版。
Tix Development Applications
TixとTkinterプログラムの開発のためのTixアプリケーション。TideアプリケーションはTkまたはTkinterに基づいて動作します。また、リモートでTix/Tk/Tkinterアプリケーションを変更やデバグするためのインスペクタTixInspectが含まれます。

  • 16.2.1 Tixを使う
  • 16.2.2 Tixウィジェット
    • 16.2.2.1 基本ウィジェット
    • 16.2.2.2 ファイルセレクタ
    • 16.2.2.3 ハイアラキカルリストボックス
    • 16.2.2.4 タビュラーリストボックス
    • 16.2.2.5 管理ウィジェット
    • 16.2.2.6 画像タイプ
    • 16.2.2.7 その他のウィジェット
    • 16.2.2.8 ジオメトリマネージャを作る
  • 16.2.3 Tixコマンド
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.6.9 画像 Up: 16. Tkを用いたグラフィカルユーザインターフェイス Next: 16.2.1 Tixを使う


16.2.1 Tixを使う

class Tix( screenName[, baseName[, className]])
たいていはアプリケーションのメインウィンドウを表すTixのトップレベルウィジェット。それにはTclインタープリタが付随します。

TixモジュールのクラスはTkinterモジュールのクラスをサブクラス化します。前者は後者をインポートします。だから、Tkinterと一緒にTixを使うためにやらなければならないのは、モジュールを一つインポートすることだけです。一般的に、Tixをインポートし、トップレベルでのTkinter.Tkの呼び出しをTix.Tkに置き換えるだけでよいのです:

import Tix
from Tkconstants import *
root = Tix.Tk()

Tixを使うためには、通常Tkウィジェットのインストールと平行して、Tixウィジェットをインストールしなければなりません。インストールをテストするために、次のことを試してください:

import Tix
root = Tix.Tk()
root.tk.eval('package require Tix')

これが失敗した場合は、先に進む前に解決しなければならない問題がTkのインストールにあることになります。インストールされたTixライブラリを指定するためには環境変数TIX_LIBRARYを使ってください。Tk動的オブジェクトライブラリ(tk8183.dllまたはlibtk8183.so)を含むディレクトリと同じディレクトリに、動的オブジェクトライブラリ(tix8183.dllまたはlibtix8183.so)があるかどうかを確かめてください。動的オブジェクトライブラリのあるディレクトリには、pkgIndex.tcl (大文字、小文字を区別します)という名前のファイルも含まれているべきで、それには次の一行が含まれます:

package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix]

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.2 Tix Up: 16.2 Tix Next: 16.2.2 Tixウィジェット


16.2.2 Tixウィジェット

"TixTixhttp://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htmは40個以上のウィジェットクラスをTkinterのレパートリーに導入します。標準配布のDemo/tixディレクトリには、Tixウィジェットのデモがあります。

  • 16.2.2.1 基本ウィジェット
  • 16.2.2.2 ファイルセレクタ
  • 16.2.2.3 ハイアラキカルリストボックス
  • 16.2.2.4 タビュラーリストボックス
  • 16.2.2.5 管理ウィジェット
  • 16.2.2.6 画像タイプ
  • 16.2.2.7 その他のウィジェット
  • 16.2.2.8 ジオメトリマネージャを作る
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.2.1 Tixを使う Up: 16.2 Tix Next: 16.2.2.1 基本ウィジェット


16.2.3 Tixコマンド

class tixCommand( )
tixコマンドはTixの内部状態とTixアプリケーション・コンテキストのいろいろな要素へのアクセスを提供します。これらのメソッドによって操作される情報の大部分は、特定のウィンドウというよりむしろアプリケーション全体かスクリーンあるいはディスプレイに関するものです。

現在の設定を見るための一般的な方法は、

import Tix
root = Tix.Tk()
print root.tix_configure()

tix_configure( [cnf,] **kw)
Tixアプリケーション・コンテキストの設定オプションを問い合わせたり、変更したりします。オプションが指定されなければ、利用可能なオプションすべてのディクショナリを返します。オプションが値なしで指定された場合は、メソッドは指定されたオプションを説明するリストを返します(このリストはオプションが指定されていない場合に返される値に含まれている、指定されたオプションに対応するサブリストと同一です)。一つ以上のオプション-値のペアが指定された場合は、メソッドは与えられたオプションが与えられた値を持つように変更します。この場合は、メソッドは空文字列を返します。オプションは設定オプションのどれでも構いません。

tix_cget( option)
optionによって与えられた設定オプションの現在の値を返します。オプションは設定オプションのどれでも構いません。

tix_getbitmap( name)
ビットマップディレクトリの一つの中のname.xpmまたはnameと言う名前のビットマップファイルの場所を見つけ出します(tix_addbitmapdir()メソッドを参照してください)。tix_getbitmap()を使うことで、アプリケーションにビットマップファイルのパス名をハードコーディングすることを避けることができます。成功すれば、文字"@"を先頭に付けたビットマップファイルの完全なパス名を返します。戻り値をTkとTixウィジェットのbitmapオプションを設定するために使うことができます。

tix_addbitmapdir( directory)
Tixはtix_getimage()とtix_getbitmap()メソッドが画像ファイルを検索するディレクトリのリストを保持しています。標準ビットマップディレクトリは$TIX_LIBRARY/bitmapsです。tix_addbitmapdir()メソッドはdirectoryをこのリストに追加します。そのメソッドを使うことによって、アプリケーションの画像ファイルをtix_getimage()またはtix_getbitmap()メソッドを使って見つけることができます。

tix_filedialog( [dlgclass])
このアプリケーションからの異なる呼び出しの間で共有される可能性があるファイル選択ダイアログを返します。最初に呼ばれた時に、このメソッドはファイル選択ダイアログ・ウィジェットを作成します。このダイアログはその後のすべてのtix_filedialog()への呼び出しで返されます。オプションのdlgclassパラメータは、要求されているファイル選択ダイアログ・ウィジェットの型を指定するために文字列として渡されます。指定可能なオプションはtix、FileSelectDialogあるいはtixExFileSelectDialogです。

tix_getimage( self, name)
ビットマップディレクトリの一つの中のname.xpm、name.xbmまたはname.ppmという名前の画像ファイルの場所を見つけ出します(上のtix_addbitmapdir()メソッドを参照してください)。同じ名前(だが異なる拡張子)のファイルが一つ以上ある場合は、画像のタイプがXディスプレイの深さに応じて選択されます。xbm画像はモノクロディスプレイの場合に選択され、カラー画像はカラーディスプレイの場合に選択されます。tix_getimage()を使うことによって、アプリケーションに画像ファイルのパス名をハードコーディングすることを避けられます。成功すれば、このメソッドは新たに作成した画像の名前を返し、TkとTixウィジェットのimageオプションを設定するためにそれを使うことができます。

tix_option_get( name)
Tixのスキーム・メカニズムによって保持されているオプションを得ます。

tix_resetoptions( newScheme, newFontSet[, newScmPrio])
TixアプリケーションのスキームとフォントセットをnewSchemeとnewFontSetそれぞれへと再設定します。これはこの呼び出し後に作成されたそれらのウィジェットだけに影響します。そのため、Tixアプリケーションのどんなウィジェットを作成する前にresetoptionsメソッドを呼び出すのが最も良いのです。

オプション・パラメータnewScmPrioを、Tixスキームによって設定されるTkオプションの優先度レベルを再設定するために与えることができます。

TkがXオプションデータベースを扱う方法のため、Tixがインポートされ初期化された後に、カラースキームとフォントセットをtix_config()メソッドを使って再設定することができません。その代わりに、tix_resetoptions()メソッドを使わなければならないのです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.2.2.8 ジオメトリマネージャを作る Up: 16.2 Tix Next: 16.3 ScrolledText


16.3 ScrolledText -- スクロールするテキストウィジェット

利用可能な条件: Tk.

ScrolledTextモジュールは``正しい動作''をするように設定された垂直スクロールバーをもつ基本的なテキストウィジェットを実装する同じ名前のクラスを提供します。ScrolledTextクラスを使うことは、テキストウィジェットとスクロールバーを直接設定するより簡単です。コンストラクタはTkinter.Textクラスのものを同じです。

テキストウィジェットとスクロールバーはFrameの中に一緒にpackされ、GridとPackジオメトリマネージャのメソッドはFrameオブジェクトから得られます。これによって、もっとも標準的なジオメトリマネージャの振る舞いにするために、直接ScrolledTextウィジェットを使えるようになります。

特定の制御が必要ならば、以下の属性が利用できます:

frame
テキストとスクロールバーウィジェットを取り囲むフレーム。

vbar
スクロールバーウィジェット。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.2.3 Tixコマンド Up: 16. Tkを用いたグラフィカルユーザインターフェイス Next: 16.4 turtle


16.4 turtle -- Tkのためのタートルグラフィックス

利用可能な条件: Tk.

turtleモジュールはオブジェクト指向と手続き指向の両方の方法でタートルグラフィックス・プリミティブを提供します。グラフィックスの基礎としてTkinterを使っているために、Tkをサポートしたpythonのバージョンが必要です。

手続き型インターフェイスでは、関数のどれかが呼び出されたときに自動的に作られるペンとキャンバスを使います。

turtleモジュールは次の関数を定義しています:

degrees( )
角度を計る単位を度にします。

radians( )
角度を計る単位をラジアンにします。

reset( )
スクリーンを消去し、ペンを中心に持って行き、変数をデフォルト値に設定します。

clear( )
スクリーンを消去します。

tracer( flag)
トレースをon/offにします(フラグが真かどうかに応じて)。トレースとは、線に沿って矢印のアニメーションが付き、線がよりゆっくりと引かれることを意味します。

forward( distance)
distanceステップだけ前に進みます。

backward( distance)
distanceステップだけ後ろに進みます。

left( angle)
angle単位だけ左に回ります。単位のデフォルトは度ですが、degrees()とradians()関数を使って設定できます。

right( angle)
angle単位だけ右に回ります。単位のデフォルトは度ですが、degrees()とradians()関数を使って設定できます。

up( )
ペンを上げます -- 線を引くことを止めます。

down( )
ペンを下げます -- 移動したときに線を引きます。

width( width)
線幅をwidthに設定します。

color( s)
color( (r, g, b))
color( r, g, b)
ペンの色を設定します。最初の形式では、色は文字列としてTkの色の仕様の通りに指定されます。二番目の形式は色をRGB値(それぞれは範囲[0..1])のタプルとして指定します。三番目の形式では、色は三つに別れたパラメータとしてRGB値(それぞれは範囲[0..1])を与えて指定しています。

write( text[, move])
現在のペンの位置にtextを書き込みます。moveが真ならば、ペンはテキストの右下の角へ移動します。デフォルトでは、moveは偽です。

fill( flag)
完全な仕様はかなり複雑ですが、推奨する使い方は: 塗りつぶしたい経路を描く前にfill(1)を呼び出し、経路を描き終えたときにfill(0)を呼び出します。

circle( radius[, extent])
半径radius、中心がタートルの左 varradiusユニットの円を描きます。extentは円のどの部分を描くかを決定します: 与えられなければ、デフォルトで完全な円になります。

extentが完全な円である場合は、弧の一つの端点は、現在のペンの位置です。radiusが正の場合、弧は反時計回りに描かれます。そうでなければ、時計回りです。

goto( x, y)
goto( (x, y))
座標x, yへ移動します。座標は二つの別個の引数か、2-タプルのどちらかで指定することができます。

このモジュールはfrom math import *も実行します。従って、タートルグラフィックスのために役に立つ追加の定数と関数については、mathモジュールのドキュメントを参照してください。

demo( )
モジュールをちょっとばかり試しています。

exception Error
このモジュールによって捕捉されたあらゆるエラー対して発生した例外。

例として、demo()関数のコードを参照してください。

このモジュールは次のクラスを定義します:

class Pen( )
ペンを定義します。上記のすべての関数は与えられたペンのメソッドとして呼び出されます。このコンストラクタは線を描くキャンバスを自動的に作成します。

class RawPen( canvas)
キャンバスcanvasに描くペンを定義します。これは``実際の''プログラムでグラフィックスを作成するためにモジュールを使いたい場合に役に立ちます。

  • 16.4.1 PenとRawPenオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.3 ScrolledText Up: 16. Tkを用いたグラフィカルユーザインターフェイス Next: 16.4.1 PenとRawPenオブジェクト


16.4.1 PenとRawPenオブジェクト

PenとRawPenオブジェクトは、demo()がメソッドとしは除かれますが、与えられたペンを操作する上記のすべてのグローバル関数を持っています。

メソッドになって強力になっているメソッドはdegrees()だけです。

degrees( [fullcircle])
fullcircleはデフォルトで360です。たとえfullcircleにラジアンで2* [image] 、あるいは度で400を与えようとも、これはペンがどんな角度単位でも取ることができるようにしています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.4 turtle Up: 16.4 turtle Next: 16.5 Idle


16.5 Idle

IdleはTkinter GUIツールキットをつかって作られたPython IDEです。

IDLEは次のような特徴があります:

  • Tkinter GUIツールキットを使って、100% ピュア Pythonでコーディングされています

  • クロス-プラットホーム: WindowsとUnixで動作します (Mac OSでは、現在Tcl/Tkに問題があります)

  • 多段Undo、Python対応の色づけや他にもたくさんの機能(例えば、自動的な字下げや呼び出し情報の表示)をもつマルチ-ウィンドウ・テキストエディタ

  • Pythonシェルウィンドウ(別名、対話インタープリタ)

  • デバッガ(完全ではりませんが、ブレークポイントの設定や値の表示、ステップ実行ができます)

  • 16.5.1 メニュー
    • 16.5.1.1 Fileメニュー
    • 16.5.1.2 Editメニュー
    • 16.5.1.3 Windowsメニュー
    • 16.5.1.4 Debugメニュー(Pythonシェルウィンドウ内のみ)
  • 16.5.2 基本的な編集とナビゲーション
    • 16.5.2.1 自動的な字下げ
    • 16.5.2.2 Python Shellウィンドウ
  • 16.5.3 構文の色づけ
    • 16.5.3.1 コマンドラインの使い方
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.4.1 PenとRawPenオブジェクト Up: 16. Tkを用いたグラフィカルユーザインターフェイス Next: 16.5.1 メニュー


16.5.1 メニュー

  • 16.5.1.1 Fileメニュー
  • 16.5.1.2 Editメニュー
  • 16.5.1.3 Windowsメニュー
  • 16.5.1.4 Debugメニュー(Pythonシェルウィンドウ内のみ)
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.5 Idle Up: 16.5 Idle Next: 16.5.1.1 Fileメニュー


16.5.2 基本的な編集とナビゲーション

  • Backspaceは左側を削除し、Delは右側を削除します
  • 矢印キーとPage Up/Page Downはそれぞれ移動します
  • Home/Endは行の始め/終わりへ移動します
  • C-Home/C-Endはファイルの始め/終わりへ移動します
  • C-B、C-P、C-A、C-E、C-D、C-Lを含む、いくつかのEmacsバインディングも動作します

  • 16.5.2.1 自動的な字下げ
  • 16.5.2.2 Python Shellウィンドウ
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.5.1.4 Debugメニュー(Pythonシェルウィンドウ内のみ) Up: 16.5 Idle Next: 16.5.2.1 自動的な字下げ


16.5.3 構文の色づけ

色づけはバックグランド``スレッド''で適用され、そのため時折色付けされないテキストが見えます。カラースキームを変えるには、config.txtの[Colors]節を編集してください。

Pythonの構文の色:

キーワード
オレンジ
文字列
緑
コメント
赤
定義
青

シェルの色:
コンソールの出力
茶色
stdout
青
stderr
暗い緑
stdin
黒

  • 16.5.3.1 コマンドラインの使い方
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.5.2.2 Python Shellウィンドウ Up: 16.5 Idle Next: 16.5.3.1 コマンドラインの使い方


16.6 他のグラフィカルユーザインターフェイスパッケージ

Tkinterへ付け加えられるたくさんの拡張ウィジェットがあります。

Pythonメガウィジェット
Tkinterモジュールを使いPythonで高レベルの複合ウィジェットを構築するためのツールキットです。基本クラスとこの基礎の上に構築された柔軟で拡張可能なメガウィジェットから構成されています。これらのメガウィジェットはノートブック、コンボボックス、選択ウィジェット、ペインウィジェット、スクロールするウィジェット、ダイアログウィンドウなどを含みます。BLTに対するPmw.Bltインターフェイスを持ち、busy、graph、stripchart、tabsetおよびvectorコマンドが利用できます。

Pmwの最初のアイディアは、Michael McLennanによるTk itcl拡張[incr Tk]とMark Ulfertsによる[incr Widgets]から得ました。メガウィジェットのいくつかはitclからPythonへ直接変換したものです。[incr Widgets]が提供するウィジェットとほぼ同等のものを提供します。そして、Tixと同様にほぼ完成しています。しかしながら、ツリーを描くためのTixの高速なHListウィジェットが欠けています。

Tkinter3000 Widget Construction Kit (WCK)
は、新しい Tkinter ウィジェットを、Python で書けるようにするライブラリで す。WCK フレームワークは、ウィジェットの生成、設定、スクリーンの外観、イ ベント操作における、完全な制御を提供します。Tk/Tcl レイヤーを通してデー タ転送する必要がなく、直接 Python のデータ構造を操作することができるので、 WCK ウィジェットは非常に高速で軽量になり得ます。

TkはPythonに対する唯一のGUIではありませんが、もっとも一般的に使われているものです。

wxWindows
Qt、Tk、MotifおよびGTK+のもっとも魅力のある性質を一つのパッケージに結合したGUIツールキットです。C++で実装されています。wxWindowsは二種類のUnix実装をサポートしています: GTK+とMotif。Windowsでは、標準的なMicrosoft Foundation Classes (MFC)の外観を持っています。なぜなら、Win32ウィジェットを使っているからです。Tkinterに依存しないPythonクラスブラウザがあります。

wxWindowsはTkinterよりさらにウィジェットが豊富で、そのへヘルプシステム、洗練されたHTMLと画像ビューアおよび他の専門分野別のウィジェット、多数のドキュメントと印刷機能を持っています。

PyQt
PyQtはsipでラップされたQtツールキットへのバインディングです。QtはUnix、WindowsおよびMac OS Xで利用できる大規模なC++ GUIツールキットです。sipはPythonクラスとしてC++ライブラリに対するバインディングを生成するためのツールキットで、特にPython用に設計されています。オンライン・マニュアルはhttp://www.opendocspublishing.com/pyqt/ (正誤表はhttp://www.valdyas.org/python/book.htmlにあります)で手に入ります。
PyKDE
PyKDEはsipでラップされたKDEデスクトップライブラリに対するインターフェイスです。KDEはUnixコンピュータ用のデスクトップ環境です。グラフィカル・コンポーネントはQtに基づいています。
FXPy
FOX GUIへのインターフェイスを提供するPython拡張モジュールです。FOXは、グラフィカルユーザインターフェイスを簡単かつ効率良く開発するためのC++ベースのツールキットです。それは幅広く、成長しているコントロール・コレクションで、3Dグラフィックスの操作のためのOpenGLウィジェットと同様に、ドラッグアンドドロップ、選択のような最新の機能を提供します。FOXはアイコン、画像およびステータスライン・ヘルプやツールチップのようなユーザにとって便利な機能も実装しています。

FOXはすでに大規模なコントロール・コレクションを提供していますが、単に既存のコントロールを使って望みの振る舞いを追加または再定義する派生クラスを作成することによってプログラマが簡単に追加コントロールとGUI要素を構築できるようにするために、FOXはC++を利用しています。

PyGTK
GTKウィジェットセットのための一連のバインディングです。Cのものより少しだけ高レベルなオブジェクト指向インターフェイスを提供します。普通はC APIを使ってやらなければならない型キャストとリファレンス・カウントをすべて自動的に行います。GNOMEに対しても、バインディングがあります。チュートリアルが手に入ります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.5.3.1 コマンドラインの使い方 Up: 16. Tkを用いたグラフィカルユーザインターフェイス Next: 17. 制限実行 (restricted execution)


17. 制限実行 (restricted execution)

警告: Python 2.3 では、既知の容易に修正できないセキュリティーホール のために、これらのモジュールは無効にされています。 rexec や Bastion モジュールを使った古いコード を読むときに助けになるよう、モジュールのドキュメントだけは 残されています。

制限実行 (restricted execution) とは、信頼できるコード と信頼できないコードを区別できるようにするための Python における 基本的なフレームワークです。このフレームワークは、信頼できる Python コード (スーパバイザ (supervisor)) が、 パーミッションに制限のかけられた ``拘束セル (padded cell)'' を生成し、このセル中で信頼のおけないコードを実行するという概念に 基づいています。信頼のおけないコードはこの拘束セルを破ることが できず、信頼されたコードで提供され、管理されたインタフェースを 介してのみ、傷つきやすいシステムリソースとやりとりすることができます。 ``制限実行'' という用語は、``安全な Python (safe-Python)'' を裏から支えるものです。というのは、真の安全を定義する ことは難しく、制限された環境を生成する方法によって決められるからです。 制限された環境は入れ子にすることができ、このとき内側のセルは より縮小されることはあるが決して拡大されることのない特権を持った サブセルを生成します。

Python の制限実行モデルの興味深い側面は、信頼されないコードに 提供されるインタフェースが、信頼されるコードに提供されるそれらと 同じ名前を持つということです。このため、制限された環境で動作 するよう設計されたコードを書く上で特殊なインタフェースを学ぶ 必要がありません。また、拘束セルの厳密な性質はスーパバイザによって 決められるため、アプリケーションによって異なる制限を課すことが できます。例えば、信頼されないコードが指定したディレクトリ内の 何らかのファイルを読み出すが決して書き込まないということが ``安全'' と考えられるかもしれません。この場合、スーパバイザは組み込みの open() 関数について、mode パラメタが 'w' の時に例外を送出するように再定義できます。また例えば、``安全'' とは、 filename パラメタに対して chroot() に似た 操作を施して、ルートパスがファイルシステム上の何らかの安全な ``砂場 (sandbox)'' 領域に対する相対パスになるようにすることかも しれません。この場合でも、信頼されないコードは依然として、 もとの呼び出しインタフェースを持ったままの組み込みのopen() 関数を制限環境中に見出します。ここでは、関数に対する意味付け (semantics) は同じですが、許可されないパラメタが使われようとしている とスーパバイザが判断した場合には IOError が送出されます。

Python のランタイムシステムは、特定のコードブロックが制限実行モード かどうかを、グローバル変数の中の __builtins__ オブジェクトの一意性をもとに判断します: オブジェクトが 標準の __builtin__ モジュール (の辞書) の場合、 コードは非制限下にあるとみなされます。それ以外は制限下にあると みなされます。

制限実行モードで動作する Python コードは、拘束セルから侵出しないように 設計された数多くの制限に直面します。例えば、関数オブジェクト 属性 func_globals や、クラスおよびインスタンスオブジェクトの 属性 __dict__ は利用できません。

二つのモジュールが、制限実行環境を立ち上げるためのフレームワークを 提供しています:

rexec | 基本的な制限実行フレームワーク。
Bastion | オブジェクトに対するアクセスの制限を提供する。

参考資料:

Grail Home Page
Python で書かれたインターネットブラウザ Grail です。Python で書かれたアプレットをサポートするために、上記のモジュールを使っています。Grail における Python 制限実行モードの利用に関する詳しい情報は、Web サイトで入手することができます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.6 他のグラフィカルユーザインターフェイスパッケージ Up: Python ライブラリリファレンス Next: 17.1 rexec


17.1 rexec -- 制限実行のフレームワーク

バージョン2.3 以降で変更された 仕様: Disabled module

警告: このドキュメントは、rexecモジュールを使用している古い コードを読む際の参照用として残されています。

このモジュールには RExec クラスが含まれています。このクラスは、 r_eval()、 r_execfile()、 r_exec()および r_import() メソッドをサポートし、これらは標準の Python 関数 eval()、 execfile() および exec と import 文の制限されたバージョンです。 この制限された環境で実行されるコードは、安全であると見なされた モジュールや関数だけにアクセスします；RExec をサブクラス化すれば、 望むように能力を追加および削除できます。

警告: rexec モジュールは、下記のように動作するべく設計されては いますが、注意深く書かれたコードなら利用できてしまうかもしれない、 既知の脆弱性がいくつかあります。従って、``製品レベル'' のセキュリティ を要する状況では、rexec の動作をあてにするべきではありません。 製品レベルのセキュリティを求めるなら、サブプロセスを介した実行や、 あるいは処理するコードとデータの両方に対する非常に注意深い ``浄化'' が必要でしょう。上記の代わりに、rexec の既知の 脆弱性に対するパッチ当ての手伝いも歓迎します。

注意: RExec クラスは、プログラムコードによる ディスクファイルの読み書きや TCP/IP ソケットの利用といった、 安全でない操作の実行を防ぐことができます。しかし、 プログラムコードよる非常に大量のメモリや処理時間の消費に対して 防御することはできません。

class RExec( [hooks[, verbose]])
RExec クラスのインスタンスを返します。

hooks は、RHooks クラスあるいはそのサブクラスの インスタンスです。hooks が省略されているか None であれば、 デフォルトの RHooks クラスがインスタンス化されます。 rexec モジュールが (組み込みモジュールを含む) あるモジュールを 探したり、あるモジュールのコードを読んだりする時は常に、 rexec がじかにファイルシステムに出て行くことはありません。 その代わり、あらかじめ RHooks クラスに渡しておいたり、 コンストラクタで生成された RHooks インスタンスのメソッドを 呼び出します。

(実際には、RExec オブジェクトはこれらを呼び出しません -- 呼び出しは、RExec オブジェクトの一部であるモジュールローダ オブジェクトによって行われます。 これによって別のレベルの柔軟性が実現されます。この柔軟性は、制限された 環境内でimport 機構を変更する時に役に立ちます。 )

代替の RHooks オブジェクトを提供することで、モジュールを インポートする際に行われるファイルシステムへのアクセスを制御する ことができます。このとき、各々のアクセスが行われる順番を制御する 実際のアルゴリズムは変更されません。 例えば、RHooks オブジェクトを置き換えて、ILU のような ある種の RPC メカニズムを介することで、全てのファイルシステムの要求を どこかにあるファイルサーバに渡すことができます。 Grail のアプレットローダは、アプレットを URL からディレクトリ上に import する際にこの機構を使っています。

もし verboseが true であれば、追加のデバッグ出力が標準出力に 送られます。

制限された環境で実行するコードも、やはり sys.exit() 関数を 呼ぶことができることを知っておくことは大事なことです。制限された コードがインタプリタから抜けだすことを許さないためには、いつでも、 制限されたコードが、SystemExit 例外をキャッチする try/except 文とともに実行するように、呼び出しを防御します。 制限された環境から sys.exit()関数を除去するだけでは不十分です - 制限されたコードは、やはり raise SystemExit を使うことができてしまいます。 SystemExitを取り除くことも、合理的なオプションではありません； いくつかのライブラリコードはこれを使っていますし、これが利用できなくなると 中断してしまうでしょう。

参考資料:

Grail のホームページ
Grail は すべて Python で書かれた Web ブラウザです。これは、 rexecモジュールを、Python アプレットをサポートするのに 使っていて、このモジュールの使用例として使うことが できます。

  • 17.1.1 RExec オブジェクト
  • 17.1.2 制限された環境を定義する
  • 17.1.3 例
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 17. 制限実行 (restricted execution) Up: 17. 制限実行 (restricted execution) Next: 17.1.1 RExec オブジェクト


17.1.1 RExec オブジェクト

RExec インスタンスは以下のメソッドをサポートします：

r_eval( code)
code は、Python の式を含む文字列か、あるいはコンパイルされた コードオブジェクトのどちらかでなければなりません。そしてこれらは制限された 環境の __main__ モジュールで評価されます。式あるいはコード オブジェクトの値が返されます。

r_exec( code)
code は、1行以上の Python コードを含む文字列か、コンパイルされた コードオブジェクトのどちらかでなければなりません。そしてこれらは、 制限された環境の __main__ モジュールで実行されます。

r_execfile( filename)
ファイル filename 内の Python コードを、制限された環境の __main__ モジュールで実行します。

名前が "s_" で始まるメソッドは、"r_"で始まる関数と同様ですが、 そのコードは、標準 I/O ストリーム sys.stdin、 sys.stderr および sys.stdout の制限されたバージョンへの アクセスが許されています。

s_eval( code)
code は、Python 式を含む文字列でなければなりません。そして 制限された環境で評価されます。

s_exec( code)
code は、1行以上のPython コードを含む文字列でなければなりません。そして 制限された環境で実行されます。

s_execfile( code)
ファイル filename に含まれた Python コードを制限された環境で 実行します。

RExec オブジェクトは、制限された環境で実行されるコードによって 暗黙のうちに呼ばれる、さまざまなメソッドもサポートしなければなりません。 これらのメソッドをサブクラス内でオーバライドすることによって、制限された環境が 強制するポリシを変更します。

r_import( modulename[, globals[, locals[, fromlist]]])
モジュール modulename をインポートし、もしそのモジュールが 安全でないとみなされるなら、ImportError 例外を発生します。

r_open( filename[, mode[, bufsize]])
open() が制限された環境で呼ばれるとき、呼ばれるメソッドです。 引数は open()のものと同じであり、ファイルオブジェクト (あるいはファイルオブジェクトと互換性のあるクラスインスタンス)が 返されます。 RExecのデフォルトの動作は、任意のファイルを 読み取り用にオープンすることを許可しますが、ファイルに書き込もうとする ことは許しません。より制限の少ない r_open()の実装については、 以下の例を見て下さい。

r_reload( module)
モジュールオブジェクト module を再ロードして、それを再解析し再初期化します。

r_unload( module)
モジュールオブジェクト moduleをアンロードします (それを制限された環境の sys.modules 辞書から取りのぞきます)。

および制限された標準 I/O ストリームへのアクセスが可能な同等のもの：

s_import( modulename[, globals[, locals[, fromlist]]])
モジュール modulename をインポートし、もしそのモジュールが 安全でないとみなされるなら、ImportError 例外を発生します。

s_reload( module)
モジュールオブジェクト module を再ロードして、それを再解析し再初期化します。

s_unload( module)
モジュールオブジェクト moduleをアンロードします。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 17.1 rexec Up: 17.1 rexec Next: 17.1.2 制限された環境を定義する


17.1.2 制限された環境を定義する

RExec クラスには以下のクラス属性があります。それらは、 __init__() メソッドが使います。それらを既存の インスタンス上で変更しても何の効果もありません；そうする代わりに、 RExec のサブクラスを作成して、そのクラス定義でそれらに 新しい値を割り当てます。そうすると、新しいクラスのインスタンスは、 これらの新しい値を使用します。これらの属性のすべては、文字列のタプルです。

nok_builtin_names
制限された環境で実行するプログラムでは利用できないであろう、 組み込み関数の名前を格納しています。 RExecに対する値は、 ('open', 'reload', '__import__') です。 (これは例外です。というのは、組み込み関数のほとんど大多数は 無害だからです。この変数をオーバライドしたいサブクラスは、 基本クラスからの値から始めて、 追加した許されない関数を連結して いかなければなりません - 危険な関数が新しく Python に追加された時は、 それらも、このモジュールに追加します。)

ok_builtin_modules
安全にインポートできる組み込みモジュールの名前を格納しています。 RExecに対する値は、 ('audioop', 'array', 'binascii', 'cmath', 'errno', 'imageop', 'marshal', 'math', 'md5', 'operator', 'parser', 'regex', 'rotor', 'select', 'sha', '_sre', 'strop', 'struct', 'time') です。この変数をオーバーライドする場合も、 同様な注意が適用されます - 基本クラスからの値を使って始めます。

ok_path
importが制限された環境で実行される時に検索される ディレクトリーを格納しています。 RExecに対する値は、(モジュールがロードされた時は) 制限されないコードの sys.path と同一です。

ok_posix_names
制限された環境で実行するプログラムで利用できる、 os モジュール内の関数の名前を格納しています。 RExecに対する値は、 ('error', 'fstat', 'listdir', 'lstat', 'readlink', 'stat', 'times', 'uname', 'getpid', 'getppid', 'getcwd', 'getuid', 'getgid', 'geteuid', 'getegid') です。

ok_sys_names
制限された環境で実行するプログラムで利用できる、 sys モジュール内の関数名と変数名を格納しています。 RExecに対する値は、 ('ps1', 'ps2', 'copyright', 'version', 'platform', 'exit', 'maxint')です。

ok_file_types
モジュールがロードすることを許されているファイルタイプを格納しています。 各ファイルタイプは、impモジュールで定義された整数定数です。 意味のある値は、PY_SOURCE、PY_COMPILED および C_EXTENSION です。RExecに対する値は、(C_EXTENSION, PY_SOURCE)です。サブクラスで PY_COMPILEDを追加することは推奨されません； 攻撃者が、バイトコンパイルしたでっちあげのファイル(.pyc)を、 例えば、あなたの公開 FTP サーバの /tmp に書いたり、 /incoming にアップロードしたりして、とにかくあなたのファイルシステム内に 置くことで、制限された実行モードから抜け出ることができるかもしれないからです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 17.1.1 RExec オブジェクト Up: 17.1 rexec Next: 17.1.3 例


17.1.3 例

標準の RExec クラスよりも、若干、もっと緩めたポリシを 望んでいるとしましょう。例えば、もし /tmp 内のファイルへの書き込みを 喜んで許すならば、RExec クラスを次のように サブクラス化できます：

class TmpWriterRExec(rexec.RExec):
    def r_open(self, file, mode='r', buf=-1):
        if mode in ('r', 'rb'):
            pass
        elif mode in ('w', 'wb', 'a', 'ab'):
            # ファイル名をチェックします :  /tmp/ で始まらなければなりません
            if file[:5]!='/tmp/':
                raise IOError, " /tmp 以外へは書き込みできません"
            elif (string.find(file, '/../') >= 0 or
                 file[:3] == '../' or file[-3:] == '/..'):
                raise IOError, "ファイル名の '..' は禁じられています"
        else: raise IOError, "open() モードが正しくありません"
        return open(file, mode, buf)
上のコードは、完全に正しいファイル名でも、時には禁止する場合があることに 注意して下さい；例えば、制限された環境でのコードでは、/tmp/foo/../bar というファイルはオープンできないかもしれません。これを修正するには、 r_open() メソッドが、そのファイル名を /tmp/barに単純化 しなければなりません。そのためには、ファイル名を分割して、それにさまざまな 操作を行う必要があります。セキュリティが重大な場合には、 より複雑で、微妙なセキュリティホールを抱え込むかもしれない、一般性のある コードよりも、 制限が余りにあり過ぎるとしても単純なコードを書く方が、 望ましいでしょう。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 17.1.2 制限された環境を定義する Up: 17.1 rexec Next: 17.2 Bastion


17.2 Bastion -- オブジェクトに対するアクセスの制限

バージョン2.3 以降で変更された 仕様: Disabled module

警告: このドキュメントは、Bastionモジュールを使用している古いコードを読む際の 参照用として残されています。

辞書によると、バスティアン (bastion、要塞) とは、``防衛された 領域や地点''、または ``最後の砦と考えられているもの'' であり、 オブジェクトの特定の属性へのアクセスを禁じる方法を提供する このモジュールにふさわしい名前です。制限モード下のプログラム に対して、あるオブジェクトにおける特定の安全な属性へのアクセス を許可し、かつその他の安全でない属性へのアクセスを拒否する には、要塞オブジェクトは常に rexec モジュールと共に 使われなければなりません。

Bastion( object[, filter[, name[, class]]])
オブジェクト object を保護し、オブジェクトに対する要塞 オブジェクトを返します。オブジェクトの属性に対するアクセスの試みは 全て、filter 関数によって認可されなければなりません; アクセス が拒否された場合 AttributeError 例外が送出されます。

filter が存在する場合、この関数は属性名を含む文字列を受理 し、その属性に対するアクセスが許可される場合には真を返さなければ なりません; filter が偽を返す場合、アクセスは拒否されます。 標準のフィルタは、アンダースコア ("_") で始まる全ての 関数に対するアクセスを拒否します。name の値が与えられた場合、 要塞オブジェクトの文字列表現は "<Bastion for name>" に なります; そうでない場合、"repr(object)" が使われます。

class が存在する場合、BastionClass のサブクラスで なくてはなりません; 詳細は bastion.py のコードを参照して ください。稀に BastionClass の標準設定を上書きする必要 ほとんどないはずです。

class BastionClass( getfunc, name)
実際に要塞オブジェクトを実装しているクラスです。このクラスは Bastion() によって使われる標準のクラスです。 getfunc 引数は関数で、唯一の引数である属性の名前を 与えて呼び出した際、制限された実行環境に対して、開示すべき属性の値を 返します。name は BastionClass インスタンスの repr() を構築するために使われます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 17.1.3 例 Up: 17. 制限実行 (restricted execution) Next: 18. Python言語サービス


18. Python言語サービス

PythonにはPython言語を使って作業するときに役に立つモジュールがたくさん提供されています。これらのモジュールはトークンの切り出し、パース、構文解析、バイトコードのディスアセンブリおよびその他のさまざまな機能をサポートしています。

これらのモジュールには、次のものが含まれています:

parser | Pythonソースコードに対する解析木へのアクセス。
symbol | Constants representing internal nodes of the parse tree.
token | Constants representing terminal nodes of the parse tree.
keyword | 文字列がPythonのキーワードか否かを調べます。
tokenize | Pythonソースコードのための字句解析器。
tabnanny | ディレクトリツリー内のPythonのソースファイルで問題となる空白を検出するツール。
pyclbr | Pythonクラスデスクリプタの情報抽出サポート
py_compile | Pythonソースファイルをバイトコードファイルへコンパイル。
compileall | ディレクトリに含まれるPythonソースファイルを、一括してバイトコンパイルします。
dis | Pythonバイトコードの逆アセンブラ。
distutils | 現在インストールされている Python に追加するためのモジュール構築、 および実際のインストールを支援する。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 17.2 Bastion Up: Python ライブラリリファレンス Next: 18.1 parser


18.1 parser -- Python解析木にアクセスする

parserモジュールはPythonの内部パーサとバイトコード・コンパイラへのインターフェイスを提供します。このインターフェイスの第一の目的は、PythonコードからPythonの式の解析木を編集したり、これから実行可能なコードを作成したりできるようにすることです。これは任意のPythonコードの断片を文字列として構文解析や変更を行うより良い方法です。なぜなら、構文解析がアプリケーションを作成するコードと同じ方法で実行されるからです。その上、高速です。

このモジュールについて注意すべきことが少しあります。それは作成したデータ構造を利用するために重要なことです。この文書はPythonコードの解析木を編集するためのチュートリアルではありませんが、parserモジュールを使った例をいくつか示しています。

もっとも重要なことは、内部パーサが処理するPythonの文法についてよく理解しておく必要があるということです。言語の文法に関する完全な情報については、Python言語リファレンスを参照してください。標準のPythonディストリビューションに含まれるファイルGrammar/Grammarの中で定義されている文法仕様から、パーサ自身は作成されています。このモジュールが作成するASTオブジェクトの中に格納される解析木は、下で説明するexpr()またはsuite()関数によって作られるときに内部パーサから実際に出力されるものです。sequence2ast()が作るASTオブジェクトは忠実にこれらの構造をシミュレートしています。言語の形式文法が改訂されるために、``正しい''と考えられるシーケンスの値がPythonのあるバージョンから別のバージョンで変化することがあるということに注意してください。しかし、Pythonのあるバージョンから別のバージョンへテキストのソースのままコードを移せば、目的のバージョンで正しい解析木を常に作成できます。ただし、インタープリタの古いバージョンへ移行する際に、最近の言語コンストラクトをサポートしていないことがあるという制限だけがあります。ソースコードが常に前方互換性があるのに対して、一般的に解析木はあるバージョンから別のバージョンへの互換性がありません。

ast2list()またはast2tuple()から返されるシーケンスのそれぞれの要素は単純な形式です。文法の非終端要素を表すシーケンスは常に一より大きい長さを持ちます。最初の要素は文法の生成規則を識別する整数です。これらの整数はCヘッダファイルInclude/graminit.hとPythonモジュールsymbolの中の特定のシンボル名です。シーケンスに付け加えられている各要素は、入力文字列の中で認識されたままの形で生成規則の構成要素を表しています: これらは常に親と同じ形式を持つシーケンスです。この構造の注意すべき重要な側面は、if_stmtの中のキーワードifのような親ノードの型を識別するために使われるキーワードがいかなる特別な扱いもなくノードツリーに含まれているということです。例えば、ifキーワードはタプル(1, 'if')と表されます。ここで、1は、ユーザが定義した変数名と関数名を含むすべてのNAMEトークンに対応する数値です。行番号情報が必要なときに返される別の形式では、同じトークンが(1, 'if', 12)のように表されます。ここでは、12が終端記号の見つかった行番号を表しています。

終端要素は同じ方法で表現されますが、子の要素や識別されたソーステキストの追加は全くありません。上記のifキーワードの例が代表的なものです。終端記号のいろいろな型は、CヘッダファイルInclude/token.hとPythonモジュールtokenで定義されています。

ASTオブジェクトはこのモジュールの機能をサポートするために必要ありませんが、三つの目的から提供されています: アプリケーションが複雑な解析木を処理するコストを償却するため、Pythonのリストやタプル表現に比べてメモリ空間を保全する解析木表現を提供するため、解析木を操作する追加モジュールをCで作ることを簡単にするため。ASTオブジェクトを使っていることを隠すために、簡単な``ラッパー''クラスをPythonで作ることができます。

parserモジュールは二、三の別々の目的のために関数を定義しています。もっとも重要な目的はASTオブジェクトを作ることと、ASTオブジェクトを解析木とコンパイルされたコードオブジェクトのような他の表現に変換することです。しかし、ASTオブジェクトで表現された解析木の型を調べるために役に立つ関数もあります。

参考資料:

symbolモジュール:
解析木の内部ノードを表す便利な定数。.
tokenモジュール:
便利な解析木の葉のノードを表す定数とノード値をテストするための関数。.

  • 18.1.1 ASTオブジェクトを作成する
  • 18.1.2 ASTオブジェクトを変換する
  • 18.1.3 ASTオブジェクトに対する問い合わせ
  • 18.1.4 例外とエラー処理
  • 18.1.5 ASTオブジェクト
  • 18.1.6 例
    • 18.1.6.1 compile()のエミュレーション
    • 18.1.6.2 情報発見
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18. Python言語サービス Up: 18. Python言語サービス Next: 18.1.1 ASTオブジェクトを作成する


18.1.1 ASTオブジェクトを作成する

ASTオブジェクトはソースコードあるいは解析木から作られます。ASTオブジェクトをソースから作るときは、'eval'と'exec'形式を作成するために別々の関数が使われます。

expr( source)
まるで"compile(source, 'file.py', 'eval')"への入力であるかのように、expr()関数はパラメータsourceを構文解析します。解析が成功した場合は、ASTオブジェクトは内部解析木表現を保持するために作成されます。そうでなければ、適切な例外を発生させます。

suite( source)
まるで"compile(source, 'file.py', 'exec')"への入力であるかのように、suite()関数はパラメータsourceを構文解析します。解析が成功した場合は、ASTオブジェクトは内部解析木表現を保持するために作成されます。そうでなければ、適切な例外を発生させます。

sequence2ast( sequence)
この関数はシーケンスとして表現された解析木を受け取り、可能ならば内部表現を作ります。木がPythonの文法に合っていることと、すべてのノードがPythonのホストバージョンで有効なノード型であることを確認した場合は、ASTオブジェクトが内部表現から作成されて呼び出し側へ返されます。内部表現の作成に問題があるならば、あるいは木が正しいと確認できないならば、ParserError例外を発生します。この方法で作られたASTオブジェクトが正しくコンパイルできると決めつけない方がよいでしょう。ASTオブジェクトがcompileast()へ渡されたとき、コンパイルによって送出された通常の例外がまだ発生するかもしれません。これは(MemoryError例外のような)構文に関係していない問題を示すのかもしれないし、del f(0)を解析した結果のようなコンストラクトが原因であるかもしれません。このようなコンストラクトはPythonのパーサを逃れますが、バイトコードインタープリタによってチェックされます。

終端トークンを表すシーケンスは、(1, 'name')形式の二つの要素のリストか、または(1, 'name', 56)形式の三つの要素のリストです。三番目の要素が存在する場合は、有効な行番号だとみなされます。行番号が指定されるのは、入力木の終端記号の一部に対してです。

tuple2ast( sequence)
これはsequence2ast()と同じ関数です。このエントリポイントは後方互換性のために維持されています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.1 parser Up: 18.1 parser Next: 18.1.2 ASTオブジェクトを変換する


18.1.2 ASTオブジェクトを変換する

作成するために使われた入力に関係なく、ASTオブジェクトはリスト木またはタプル木として表される解析木へ変換されるか、または実行可能なオブジェクトへコンパイルされます。解析木は行番号情報を持って、あるいは持たずに抽出されます。

ast2list( ast[, line_info])
この関数は呼び出し側からastにASTオブジェクトを受け取り、解析木と等価なPythonのリストを返します。結果のリスト表現はインスペクションあるいはリスト形式の新しい解析木の作成に使うことができます。リスト表現を作るためにメモリが利用できる限り、この関数は失敗しません。解析木がインスペクションのためだけにつかわれるならば、メモリの消費量と断片化を減らすためにast2tuple()を代わりに使うべきです。リスト表現が必要とされるとき、この関数はタプル表現を取り出して入れ子のリストに変換するよりかなり高速です。

line_infoが真ならば、トークンを表すリストの三番目の要素として行番号情報がすべての終端トークンに含まれます。与えられた行番号はトークンが終わる行を指定していることに注意してください。フラグが偽または省略された場合は、この情報は省かれます。

ast2tuple( ast[, line_info])
この関数は呼び出し側からastにASTオブジェクトを受け取り、解析木と等価なPythonのタプルを返します。リストの代わりにタプルを返す以外は、この関数はast2list()と同じです。

line_infoが真ならば、トークンを表すリストの三番目の要素として行番号情報がすべての終端トークンに含まれます。フラグが偽または省略された場合は、この情報は省かれます。

compileast( ast[, filename = '<ast>'])
exec文の一部として使える、あるいは、組み込みeval()関数への呼び出しとして使えるコードオブジェクトを生成するために、PythonバイトコードコンパイラをASTオブジェクトに対して呼び出すことができます。この関数はコンパイラへのインターフェイスを提供し、filenameパラメータで指定されるソースファイル名を使って、astからパーサへ内部解析木を渡します。filenameに与えられるデフォルト値は、ソースがASTオブジェクトだったことを示唆しています。

ASTオブジェクトをコンパイルすることは、コンパイルに関する例外を引き起こすことになるかもしれません。例としては、del f(0)の解析木によって発生させられるSyntaxErrorがあります: この文はPythonの形式文法としては正しいと考えられますが、正しい言語コンストラクトではありません。この状況に対して発生するSyntaxErrorは、実際にはPythonバイトコンパイラによって通常作り出されます。これがparserモジュールがこの時点で例外を発生できる理由です。解析木のインスペクションを行うことで、コンパイルが失敗するほとんどの原因をプルグラムによって診断することができます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.1.1 ASTオブジェクトを作成する Up: 18.1 parser Next: 18.1.3 ASTオブジェクトに対する問い合わせ


18.1.3 ASTオブジェクトに対する問い合わせ

ASTが式またはsuiteとして作成されたかどうかをアプリケーションが決定できるようにする二つの関数が提供されています。これらの関数のどちらも、ASTがexpr()またはsuite()を通してソースコードから作られたかどうか、あるいは、sequence2ast()を通して解析木から作られたかどうかを決定できません。

isexpr( ast)
astが'eval'形式を表している場合に、この関数は真を返します。そうでなければ、偽を返します。これは役に立ちます。なぜならば、通常は既存の組み込み関数を使ってもコードオブジェクトに対してこの情報を問い合わせることができないからです。このどちらのようにもcompileast()によって作成されたコードオブジェクトに問い合わせることはできませんし、そのコードオブジェクトは組み込みcompile()関数によって作成されたコードオブジェクトと同じであることに注意してください。

issuite( ast)
ASTオブジェクトが(通常``suite''として知られる)'exec'形式を表しているかどうかを報告するという点で、この関数はisexpr()に酷似しています。追加の構文が将来サポートされるかもしれないので、この関数が"not isexpr(ast)"と等価であるとみなすのは安全ではありません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.1.2 ASTオブジェクトを変換する Up: 18.1 parser Next: 18.1.4 例外とエラー処理


18.1.4 例外とエラー処理

parserモジュールは例外を一つ定義していますが、Pythonランタイム環境の他の部分が提供する別の組み込み例外を発生させることもあります。各関数が発生させる例外の情報については、それぞれ関数を参照してください。

exception ParserError
parserモジュール内部で障害が起きたときに発生する例外。普通の構文解析中に発生する組み込みのSyntaxErrorではなく、一般的に妥当性確認が失敗した場合に引き起こされます。例外の引数としては、障害の理由を説明する文字列である場合と、sequence2ast()へ渡される解析木の中の障害を引き起こすシーケンスを含むタプルと説明用の文字列である場合があります。モジュール内の他の関数の呼び出しは単純な文字列値を検出すればよいだけですが、sequence2ast()の呼び出しはどちらの例外の型も処理できる必要があります。

普通は構文解析とコンパイル処理によって発生する例外を、関数compileast()、expr()およびsuite()が発生させることに注意してください。このような例外には組み込み例外MemoryError、OverflowError、SyntaxErrorおよびSystemErrorが含まれます。こうした場合には、これらの例外が通常その例外に関係する全ての意味を伝えます。詳細については、各関数の説明を参照してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.1.3 ASTオブジェクトに対する問い合わせ Up: 18.1 parser Next: 18.1.5 ASTオブジェクト


18.1.5 ASTオブジェクト

ASTオブジェクト間の順序と等値性の比較がサポートされています。(pickleモジュールを使った)ASTオブジェクトのピクルス化もサポートされています。

ASTType
expr()、suite()とsequence2ast()が返すオブジェクトの型。

ASTオブジェクトは次のメソッドを持っています:

compile( [filename])
compileast(ast, filename)と同じ。

isexpr( )
isexpr(ast)と同じ。

issuite( )
issuite(ast)と同じ。

tolist( [line_info])
ast2list(ast, line_info)と同じ。

totuple( [line_info])
ast2tuple(ast, line_info)と同じ。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.1.4 例外とエラー処理 Up: 18.1 parser Next: 18.1.6 例


18.1.6 例

parserモジュールを使うと、バイトコードが生成される前にPythonのソースコードの解析木に演算を行えるようになります。また、モジュールは情報発見のために解析木のインスペクションを提供しています。例が二つあります。簡単な例では組み込み関数compile()のエミュレーションを行っており、複雑な例では情報を得るための解析木の使い方を示しています。

  • 18.1.6.1 compile()のエミュレーション
  • 18.1.6.2 情報発見
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.1.5 ASTオブジェクト Up: 18.1 parser Next: 18.1.6.1 compile()のエミュレーション


18.2 symbol -- Python解析木と共に使われる定数

このモジュールは解析木の内部ノードの数値を表す定数を提供します。ほとんどのPython定数とは違い、これらは小文字の名前を使います。言語の文法のコンテキストにおける名前の定義については、PythonディストリビューションのファイルGrammar/Grammarを参照してください。名前がマップする特定の数値はPythonのバージョン間で変わります。

このモジュールには、データオブジェクトも一つ付け加えられています:

sym_name
ディクショナリはこのモジュールで定義されている定数の数値を名前の文字列へマップし、より人が読みやすいように解析木を表現します。

参考資料:

parserモジュール:
parserモジュールの二番目の例で、symbolモジュールの使い方を示しています。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.1.6.2 情報発見 Up: 18. Python言語サービス Next: 18.3 token


18.3 token -- Python解析木と共に使われる定数

このモジュールは解析木の葉ノード(終端記号)の数値を表す定数を提供します。言語の文法のコンテキストにおける名前の定義については、PythonディストリビューションのファイルGrammar/Grammarを参照してください。名前がマップする特定の数値は、Pythonのバージョン間で変わります。

このモジュールは一つのデータオブジェクトといくつかの関数も提供します。関数はPythonのCヘッダファイルの定義を反映します。

tok_name
辞書はこのモジュールで定義されている定数の数値を名前の文字列へマップし、より人が読みやすいように解析木を表現します。

ISTERMINAL( x)
終端トークンの値に対して真を返します。

ISNONTERMINAL( x)
非終端トークンの値に対して真を返します。

ISEOF( x)
xが入力の終わりを示すマーカーならば、真を返します。

参考資料:

parserモジュール:
parserモジュールの二番目の例で、symbolモジュールの使い方を示しています。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.2 symbol Up: 18. Python言語サービス Next: 18.4 keyword


18.4 keyword -- Pythonキーワードチェック

このモジュールでは、Pythonプログラムで文字列がキーワードか否かをチェック する機能を提供します。

iskeyword( s)
sがPythonのキーワードであれば真を返します。

kwlist
インタープリタで定義している全てのキーワードのシーケンス。特定の __future__宣言がなければ有効ではないキーワードでもこのリストに は含まれます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.3 token Up: 18. Python言語サービス Next: 18.5 tokenize


18.5 tokenize -- Pythonソースのためのトークナイザ

tokenizeモジュールでは、Python で実装された Python ソースコードの字句解析器を提供します。さらに、このモジュールの 字句解析器はコメントもトークンとして返します。このため、この モジュールはスクリーン上で表示する際の色付け機能 (colorizers) を含む ``清書出力器 (pretty-printer)'' を実装する上で便利です。

第一のエントリポイントはジェネレータです:

generate_tokens( readline)
generate_tokens() ジェネレータは一つの引数readline を必要とします。この引数は呼び出し可能オブジェクトで、組み込みファイル オブジェクトにおける readline() メソッドと同じインタフェース を提供していなければなりません ( 2.3.8 節を参照して ください)。この関数は呼び出しのたびに入力内の一行を文字列で返さなければ なりません。

ジェネレータは 5 要素のタプルを返し、タプルは以下のメンバ: トークン型; トークン文字列; ソースコード中でトークンが始まる行と列を示す 整数の2要素のタプル(srow, scol); ソースコード中で トークンが終わる行と列を示す整数の2要素のタプル (srow, scol); そして、トークンが見つかった行、から なります。渡される行は論理行です; 連続する行は一行に含められ ます。 バージョン2.2 以降で新規追加された 仕様です。

後方互換性のために古いエントリポイントが残されています:

tokenize( readline[, tokeneater])
tokenize()関数は二つのパラメータを取ります: 一つは入力ストリームを表し、もう一つはtokenize()のための 出力メカニズムを与えます。

最初のパラメータ、readline は、組み込みファイルオブジェクト のreadline()メソッドと同じインタフェイスを提供する呼び出し 可能オブジェクトでなければなりません ( 2.3.8 節を参照)。 この関数は呼び出しのたびに入力内の一行を文字列で返さなければ なりません。

二番目のパラメータtokeneaterも呼び出し可能オブジェクトで なければなりません。この関数は各トークンに対して一度だけ呼び出され、 generate_tokens() が生成するタプルに対応する 5 つの引数 をとります。

token モジュールの全ての定数はtokenize でも 公開されており、これに加え、以下の二つのトークン値が tokenize() の tokeneater 関数に渡される可能性があります:

COMMENT
コメントであることを表すために使われるトークン値です。
NL
終わりではない改行を表すために使われるトークン値。NEWLINEトークンは Pythonコードの論理行の終わりを表します。NLトークンはコードの論理行が 複数の物理行にわたって続いているときに作られます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.4 keyword Up: 18. Python言語サービス Next: 18.6 tabnanny


18.6 tabnanny -- あいまいなインデントの検出

差し当たり、このモジュールはスクリプトとして呼び出すことを意図しています。しかし、IDE上にインポートして下で説明する関数check()を使うことができます。

警告: このモジュールが提供するAPIを将来のリリースで変更する確率が高いです。このような変更は後方互換性がないかもしれません。

check( file_or_dir)
file_or_dirがディレクトリであってシンボリックリンクでないときに、file_or_dirという名前のディレクトリツリーを再帰的に下って行き、この通り道に沿ってすべての.pyファイルを変更します。file_or_dirが通常のPythonソースファイルの場合には、問題のある空白をチェックします。診断メッセージはprint文を使って標準出力に書き込まれます。

verbose
冗長なメッセージをプリントするかどうかを示すフラグ。スクリプトとして呼び出された場合は、-vオプションによって増加します。

filename_only
問題のある空白を含むファイルのファイル名のみをプリントするかどうかを示すフラグ。スクリプトとして呼び出された場合は、-qオプションによって真に設定されます。

exception NannyNag
あいまいなインデントを検出した場合にtokeneater()によって発生させられます。check()で捕捉され処理されます。

tokeneater( type, token, start, end, line)
この関数は関数tokenize.tokenize()へのコールバックパラメータとしてcheck()によって使われます。

参考資料:

tokenizeモジュール:
Pythonソースコードの字句解析器。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.5 tokenize Up: 18. Python言語サービス Next: 18.7 pyclbr


18.7 pyclbr -- Python クラスブラウザーサポート

このpyclbrはモジュールで定義されたクラス、メソッド、および トップレベルの関数について、限られた量の情報を定義するのに使われます。 このクラスによって提供される情報は、伝統的な 3 ペイン形式の クラスブラウザーを実装するのに十分なだけの量になります。 情報はモジュールのインポートによらず、ソースコードから抽出します。 このため、このモジュールは信用できないソースコードに対して利用しても 安全です。この制限から、多くの標準モジュールやオプションの拡張 モジュールを含む、Python で実装されていないモジュールに対して 利用することはできません。

readmodule( module[, path])
モジュールを読み込み、辞書マッピングクラスを返し、 クラス記述オブジェクトに名前をつけます。 パラメタmoduleはモジュール名を表す文字列でなくてはなりません; パッケージ内のモジュール名でもかまいません。 path パラメタは配列型でなくてはならず、 モジュールのソースコード がある場所を特定する際に sys.path の値に補完する形で使われます。

readmodule_ex( module[, path])
readmodule() に似ていますが、返される辞書は、クラス名から クラス記述オブジェクトへの対応付けに加えて、トップレベル関数から 関数記述オブジェクトへの対応付けも行っています。さらに、読み出し対象の モジュールがパッケージの場合、返される辞書はキー '__path__' を持ち、その値はパッケージの検索パスが入ったリストになります。

  • 18.7.1 クラス記述オブジェクト
  • 18.7.2 関数記述オブジェクト (Function Descriptor Object)
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.6 tabnanny Up: 18. Python言語サービス Next: 18.7.1 クラス記述オブジェクト


18.7.1 クラス記述オブジェクト

クラス記述オブジェクトは、readmodule() や readmodule()_ex が返す辞書の値として 使われており、以下のデータメンバを提供しています。

module
クラス記述オブジェクトが記述している対象のクラスを定義している モジュールの名前です。

name
クラスの名前です。

super
クラス記述オブジェクトが記述しようとしている対象クラスの、直接の基底 クラス群について記述しているクラス記述オブジェクトのリストです。 スーパクラスとして挙げられているが readmodule() が見つけ られなかったクラスは、クラス記述オブジェクトではなくクラス名として リストに挙げられます。

methods
メソッド名を行番号に対応付ける辞書です。

file
クラスを定義している class 文が入っているファイルの名前です。

lineno
file で指定されたファイル内にある class 文の数です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.7 pyclbr Up: 18.7 pyclbr Next: 18.7.2 関数記述オブジェクト (Function Descriptor


18.7.2 関数記述オブジェクト (Function Descriptor Object)

readmodule_ex() の返す辞書内でキーに対応する値として使われて いる関数記述オブジェクトは、以下のデータメンバを提供しています:

module
関数記述オブジェクトが記述している対象の関数を定義している モジュールの名前です。

name
関数の名前です。

file
関数を定義してる def 文が入っているファイルの名前です。

lineno
file で指定されたファイル内にある def 文の数です。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.7.1 クラス記述オブジェクト Up: 18.7 pyclbr Next: 18.8 py_compile


18.8 py_compile -- Pythonソースファイルのコンパイル

py_compileモジュールには、ソースファイルからバイトコードファイ ルを作る関数と、モジュールのソースファイルがスクリプトとして呼び出される 時に使用される関数が定義されています。

頻繁に必要となるわけではありませんが、共有ライブラリとしてモジュールをイ ンストールする場合や、特にソースコードのあるディレクトリにバイトコードの キャッシュファイルを書き込む権限がないユーザがいるときには、この関数は役 に立ちます。

exception PyCompileError
ファイルをコンパイル中にエラーが発生すると、PyCompileError例外が送出されます。

compile( file[, cfile[, dfile[, doraise]]])
ソースファイルをバイトコードにコンパイルして、バイトコードのキャッシュ ファイルに書き出します。 ソースコードはファイル名fileで渡します。 バイトコードはファイルcfileに書き込まれ、デフォルトではfile + 'c'（使用しているインタープリタで最適化が可能なら 'o'）です。 もしdfileが指定されたら、fileの代わりにソースファイルの名前 としてエラーメッセージの中で使われます。 doraise = Trueの場合、コンパイル中にエラーが発生するとPyCompileError を送出します。doraise = Falseの場合(デフォルト)はエラーメッセージは sys.stderrに出力し、例外は送出しません。

main( [args])
いくつか複数のソースファイルをコンパイルします。 argsで（あるいはargsで指定されなかったらコマンドラインで）指 定されたファイルをコンパイルし、できたバイトコードを通常の方法で保存しま す。 この関数はソースファイルの存在するディレクトリを検索しません；指定された ファイルをコンパイルするだけです。

このモジュールがスクリプトとして実行されると、main()がコマン ドラインで指定されたファイルを全てコンパイルします。

参考資料:

compileallモジュール:
ディレクトリツリー内のPythonソースファイルを全てコンパイルするライブラリ。.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.7.2 関数記述オブジェクト (Function Descriptor Up: 18. Python言語サービス Next: 18.9 compileall


18.9 compileall -- Pythonライブラリをバイトコンパイル

このモジュールは、指定したディレクトリに含まれるPythonソースをコンパイル する関数を定義しています。Pythonライブラリをインストールする時、ソースフ ァイルを事前にコンパイルしておく事により、ライブラリのインストール先ディ レクトリに書き込み権限をもたないユーザでもキャッシュされたバイトコードフ ァイルを利用する事ができるようになります。

このモジュールのソースコードは、Pytonソースファイルをコンパイルするスク リプトとしても利用する事ができます。コンパイルするディレクトリは、 sys.pathで指定されたディレクトリ、またはコマンドラインで指定され たディレクトリとなります。

compile_dir( dir[, maxlevels[, ddir[, force[, rx[, quiet]]]]])

dirで指定されたディレクトリを再帰的に下降し、見つかった .pyを全てコンパイルします。maxlevelsは、下降する最大の深 さ（デフォルトは10）を指定します。ddirには、エラーメッ セージで使用されるファイル名の、親ディレクトリ名を指定する事ができま す。forceが真の場合、モジュールはファイルの更新日付に関わりなく 再コンパイルされます。

rxには、検索対象から除外するファイル名の正規表現式を指定します。 絶対パス名をこの正規表現でsearchし、一致した場合にはコンパイル 対象から除外します。

quietが真の場合、通常処理では標準出力に何も表示しません。

compile_path( [skip_curdir[, maxlevels[, force]]])

sys.pathに含まれる、全ての.pyファイルをバイトコンパイル します。skip_curdirが真（デフォルト）の時、カレントディレクトリ は検索されません。maxlevelsとforceはデフォルトでは0 で、compile_dir()に渡されます。

参考資料:

py_compileモジュール:
Byte-compile a single source file.
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.8 py_compile Up: 18. Python言語サービス Next: 18.10 dis


18.10 dis -- Pythonバイトコードの逆アセンブラ

disモジュールはPythonバイトコードを逆アセンブルしてバイトコードの解析を助けます。Pythonアセンブラがないため、このモジュールがPythonアセンブリ言語を定義しています。このモジュールが入力として受け取るPythonバイトコードはファイルInclude/opcode.hに定義されており、コンパイラとインタプリタが使用しています。

例: 関数myfuncを考えると:

def myfunc(alist):
    return len(alist)

次のコマンドをmyfunc()の逆アセンブリを得るために使うことができます:

>>> dis.dis(myfunc)
  2           0 LOAD_GLOBAL              0 (len)
              3 LOAD_FAST                0 (alist)
              6 CALL_FUNCTION            1
              9 RETURN_VALUE
             10 LOAD_CONST               0 (None)
             13 RETURN_VALUE

(``2''は行番号です)。

disモジュールは次の関数と定数を定義します:

dis( [bytesource])
bytesourceオブジェクトを逆アセンブルします。bytesourceはモジュール、クラス、関数、あるいはコードオブジェクトのいずれかを示します。モジュールに対しては、すべての関数を逆アセンブルします。クラスに対しては、すべてのメソッドを逆アセンブルします。単一のコードシーケンスに対しては、バイトコード命令ごとに一行をプリントします。オブジェクトが与えられない場合は、最後のトレースバックを逆アセンブルします。

distb( [tb])
トレースバックのスタックの先頭の関数を逆アセンブルします。Noneが渡された場合は最後のトレースバックを使います。例外を引き起こした命令が表示されます。

disassemble( code[, lasti])
コードオブジェクトを逆アセンブルします。lastiが与えられた場合は、最後の命令を示します。出力は次のようなカラムに分割されます:

  1. 各行の最初の命令に対する行番号。
  2. 現在の命令。"-->"として示されます。
  3. ラベル付けされた命令。">>"とともに表示されます。
  4. the address of the instruction,
  5. 命令のアドレス。
  6. 演算コード名。
  7. 演算パラメータ。
  8. 括弧の中のパラメータのインタプリテーション。

パラメータインタープリテーションはローカルおよびグルーバル変数名、定数値、分岐目標、そして比較演算子を認識します。

disco( code[, lasti])
disassembleの別名。よりタイプしやすく、以前のPythonリリースと互換性があります。

opname
演算名。一連のバイトコードを使ってインデキシングできます。

cmp_op
すべての比較演算名。

hasconst
定数腹メータを持つ一連のバイトコード。

hasfree
自由変数にアクセスする一連のバイトコード。

hasname
名前によって属性にアクセスする一連のバイトコード。

hasjrel
相対ジャンプターゲットをもつ一連のバイトコード。

hasjabs
絶対ジャンプターゲットをもつ一連のバイトコード。

haslocal
ローカル変数にアクセスする一連のバイトコード。

hascompare
ブール演算の一連のバイトコード。

  • 18.10.1 Pythonバイトコード命令
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.9 compileall Up: 18. Python言語サービス Next: 18.10.1 Pythonバイトコード命令


18.10.1 Pythonバイトコード命令

現在Pythonコンパイラは次のバイトコード命令を生成します。

STOP_CODE
コンパイラにend-of-code(コードの終わり)を知らせます。インタプリタでは使われません。

POP_TOP
top-of-stack (TOS)(スタックの先頭)の項目を取り除きます。

ROT_TWO
スタックの先頭から二つの項目を入れ替えます。

ROT_THREE
スタックの二番目と三番目の項目の位置を一つ上げ、先頭を三番目へ下げます。

ROT_FOUR
スタックの二番目、三番目および四番目の位置を一つ上げ、先頭を四番目に下げます。

DUP_TOP
スタックの先頭に参照の複製を作ります。

一項演算はスタックの先頭を取り出して演算を適用し、結果をスタックへプッシュし戻します。

UNARY_POSITIVE
TOS = +TOSを実行します。

UNARY_NEGATIVE
TOS = -TOSを実行します。

UNARY_NOT
TOS = not TOSを実行します。

UNARY_CONVERT
TOS = `TOS`を実行します。

UNARY_INVERT
TOS = ~TOSを実行します。

GET_ITER
TOS = iter(TOS)を実行します。

二項演算はスタックからスタックの先頭(TOS)と先頭から二番目のスタック項目を取り除きます。演算を実行し、スタックへ結果をプッシュし戻します。

BINARY_POWER
TOS = TOS1 ** TOSを実行します。

BINARY_MULTIPLY
TOS = TOS1 * TOSを実行します。

BINARY_DIVIDE
from __future__ import divisionが有効でないとき、TOS = TOS1 / TOSを実行します。

BINARY_FLOOR_DIVIDE
TOS = TOS1 // TOSを実行します。

BINARY_TRUE_DIVIDE
from __future__ import divisionが有効でないとき、TOS = TOS1 / TOSを実行します。

BINARY_MODULO
TOS = TOS1 % TOSを実行します。

BINARY_ADD
TOS = TOS1 + TOSを実行します。

BINARY_SUBTRACT
TOS = TOS1 - TOSを実行します。

BINARY_SUBSCR
TOS = TOS1[TOS]を実行します。

BINARY_LSHIFT
TOS = TOS1 << TOSを実行します。

BINARY_RSHIFT
TOS = TOS1 >> TOSを実行します。

BINARY_AND
TOS = TOS1 & TOSを実行します。

BINARY_XOR
TOS = TOS1 ^ TOSを実行します。

BINARY_OR
TOS = TOS1 | TOSを実行します。

インプレース演算はTOSとTOS1を取り除いて結果をスタックへプッシュするという点で二項演算と似ています。しかし、TOS1がインプレース演算をサポートしている場合には演算が直接TOS1に行われます。また、演算結果のTOSは元のTOS1と同じオブジェクトになることが多いですが、常に同じというわけではありません。

INPLACE_POWER
インプレースにTOS = TOS1 ** TOSを実行します。

INPLACE_MULTIPLY
インプレースにTOS = TOS1 * TOSを実行します。

INPLACE_DIVIDE
from __future__ import divisionが有効でないとき、インプレースにTOS = TOS1 / TOSを実行します。

INPLACE_FLOOR_DIVIDE
インプレースにTOS = TOS1 // TOSを実行します。

INPLACE_TRUE_DIVIDE
from __future__ import divisionが有効でないとき、インプレースにTOS = TOS1 / TOSを実行します。

INPLACE_MODULO
インプレースにTOS = TOS1 % TOSを実行します。

INPLACE_ADD
インプレースにTOS = TOS1 + TOSを実行します。

INPLACE_SUBTRACT
インプレースにTOS = TOS1 - TOSを実行します。

INPLACE_LSHIFT
インプレースにTOS = TOS1 << TOSを実行します。

INPLACE_RSHIFT
インプレースにTOS = TOS1 >> TOSを実行します。

INPLACE_AND
インプレースにTOS = TOS1 & TOSを実行します。

INPLACE_XOR
インプレースにTOS = TOS1 ^ TOSを実行します。

INPLACE_OR
インプレースにTOS = TOS1 | TOSを実行します。

スライス演算は三つまでのパラメータを取ります。

SLICE+0
TOS = TOS[:]を実行します。

SLICE+1
TOS = TOS1[TOS:]を実行します。

SLICE+2
TOS = TOS1[:TOS]を実行します。

SLICE+3
TOS = TOS2[TOS1:TOS]を実行します。

スライス代入はさらに別のパラメータを必要とします。どんな文もそうであるように、スタックに何もプッシュしません。

STORE_SLICE+0
TOS[:] = TOS1を実行します。

STORE_SLICE+1
TOS1[TOS:] = TOS2を実行します。

STORE_SLICE+2
TOS1[:TOS] = TOS2を実行します。

STORE_SLICE+3
TOS2[TOS1:TOS] = TOS3を実行します。

DELETE_SLICE+0
del TOS[:]を実行します。

DELETE_SLICE+1
del TOS1[TOS:]を実行します。

DELETE_SLICE+2
del TOS1[:TOS]を実行します。

DELETE_SLICE+3
del TOS2[TOS1:TOS]を実行します。

STORE_SUBSCR
TOS1[TOS] = TOS2を実行します。

DELETE_SUBSCR
del TOS1[TOS]を実行します。

その他の演算。

PRINT_EXPR
対話モードのための式文を実行します。TOSはスタックから取り除かれプリントされます。非対話モードにおいては、式文はPOP_STACKで終了しています。

PRINT_ITEM
sys.stdoutに束縛されたファイル互換のオブジェクトへTOSをプリントします。print文に、各項目に対するこのような命令が一つあります。

PRINT_ITEM_TO
PRINT_ITEMと似ていますが、TOSから二番目の項目をTOSにあるファイル互換オブジェクトへプリントします。これは拡張print文で使われます。

PRINT_NEWLINE
sys.stdoutへ改行をプリントします。これはprint文がコンマで終わっていない場合にprint文の最後の演算として生成されます。

PRINT_NEWLINE_TO
PRINT_NEWLINEと似ていますが、TOSのファイル互換オブジェクトに改行をプリントします。これは拡張print文で使われます。

BREAK_LOOP
break文があるためループを終了します。

CONTINUE_LOOP target
continue文があるためループを継続します。targetはジャンプするアドレスです(アドレスはFOR_ITER命令であるべきです)。

LOAD_LOCALS
現在のスコープのローカルな名前空間(locals)への参照をスタックにプッシュします。これはクラス定義のためのコードで使われます: クラス本体が評価された後、localsはクラス定義へ渡されます。

RETURN_VALUE
関数の呼び出し元へTOSを返します。

YIELD_VALUE
TOSをポップし、それをジェネレータからyieldします。

IMPORT_STAR
"_"で始まっていないすべてのシンボルをモジュールTOSから直接ローカル名前空間へロードします。モジュールはすべての名前をロードした後にポップされます。この演算コードはfrom module import *を実行します。

EXEC_STMT
exec TOS2,TOS1,TOSを実行します。コンパイラは見つからないオプションのパラメータをNoneで埋めます。

POP_BLOCK
ブロックスタックからブロックを一つ取り除きます。フレームごとにブロックのスタックがあり、ネストしたループ、try文などを意味しています。

END_FINALLY
finally節を終わらせます。インタプリタは例外を再び発生させなければならないかどうか、あるいは、関数が返り外側の次のブロックに続くかどうかを思い出します。

BUILD_CLASS
新しいクラスオブジェクトを作成します。TOSはメソッド辞書、TOS1は基底クラスの名前のタプル、TOS2はクラス名です。

次の演算コードはすべて引数を要求します。引数はより重要なバイトを下位にもつ2バイトです。

STORE_NAME namei
name = TOSを実行します。nameiはコードオブジェクトの属性co_namesにおけるnameのインデックスです。コンパイラは可能ならばSTORE_LOCALまたはSTORE_GLOBALを使おうとします。

DELETE_NAME namei
del nameを実行します。ここで、nameiはコードオブジェクトのco_names属性へのインデックスです。

UNPACK_SEQUENCE count
TOSをcount個のへ個別の値に分け、右から左にスタックに置かれます。

DUP_TOPX count
count個の項目を同じ順番を保ちながら複製します。実装上の制限から、countは1から5の間(5を含む)でなければいけません。

STORE_ATTR namei
TOS.name = TOS1を実行します。ここで、nameiはco_namesにおける名前のインデックスです。

DELETE_ATTR namei
co_namesへのインデックスとしてnameiを使い、del TOS.nameを実行します。

STORE_GLOBAL namei
STORE_NAMEとして機能しますが、グローバルとして名前を記憶します。

DELETE_GLOBAL namei
DELETE_NAMEとして機能しますが、グルーバル名を削除します。

LOAD_CONST consti
"co_consts[consti]"をスタックにプッシュします。

LOAD_NAME namei
"co_names[namei]"に関連付けられた値をスタックにプッシュします。

BUILD_TUPLE count
スタックからcount個の項目を消費するタプルを作り出し、できたタプルをスタックにプッシュします。

BUILD_LIST count
BUILD_TUPLEとして機能しますが、リストを作り出します。

BUILD_MAP zero
スタックに新しい空の辞書オブジェクトをプッシュします。引数は無視され、コンパイラによってゼロに設定されます。

LOAD_ATTR namei
TOSをgetattr(TOS, co_names[namei])と入れ替えます。

COMPARE_OP opname
ブール演算を実行します。演算名はcmp_op[opname]にあります。

IMPORT_NAME namei
モジュールco_names[namei]をインポートします。モジュールオブジェクトはスタックへプッシュされます。現在の名前空間は影響されません: 適切なimport文に対して、それに続くSTORE_FAST命令が名前空間を変更します。

IMPORT_FROM namei
属性co_names[namei]をTOSに見つかるモジュールからロードします。作成されたオブジェクトはスタックにプッシュされ、その後STORE_FAST命令によって記憶されます。

JUMP_FORWARD delta
バイトコードカウンタをdeltaだけ増加させます。

JUMP_IF_TRUE delta
TOSが真ならば、deltaだけバイトコードカウンタを増加させます。TOSはスタックに残されます。

JUMP_IF_FALSE delta
TOSが偽ならば、deltaだけバイトコードカウンタを増加させます。TOSは変更されません。

JUMP_ABSOLUTE target
バイトコードカウンタをtargetに設定します。

FOR_ITER delta
TOSはイテレータです。そのnext()メソッドを呼び出します。これが新しい値を作り出すならば、それを(その下にイテレータを残したまま)スタックにプッシュします。イテレータが尽きたことを示した場合は、TOSがポップされます。そして、バイトコードカウンタがdeltaだけ増やされます。

LOAD_GLOBAL namei
グルーバル名co_names[namei]をスタック上にロードします。

SETUP_LOOP delta
ブロックスタックにループのためのブロックをプッシュします。ブロックは現在の命令からdeltaバイトの大きさを占めます。

SETUP_EXCEPT delta
try-except節からtryブロックをブロックスタックにプッシュします。deltaは最初のexceptブロックを指します。

SETUP_FINALLY delta
try-except節からtryブロックをブロックスタックにプッシュします。deltaはfinallyブロックを指します。

LOAD_FAST var_num
ローカルなco_varnames[var_num]への参照をスタックにプッシュします。

STORE_FAST var_num
TOSをローカルなco_varnames[var_num]の中に保存します。

DELETE_FAST var_num
ローカルなco_varnames[var_num]を削除します。

LOAD_CLOSURE i
セルと自由変数記憶領域のスロットiに含まれるセルへの参照をプッシュします。iがco_cellvarsの長さより小さければ、変数の名前はco_cellvars[i]です。そうでなければ、それはco_freevars[i - len(co_cellvars)]です。

LOAD_DEREF i
セルと自由変数記憶領域のスロットiに含まれるセルをロードします。セルが持つオブジェクトへの参照をスタックにプッシュします。

STORE_DEREF i
セルと自由変数記憶領域のスロットiに含まれるセルへTOSを保存します。

SET_LINENO lineno
このオペコードは廃止されました。

RAISE_VARARGS argc
例外を発生させます。argcはraise文へ与えるパラメータの数を0から3の範囲で示します。ハンドラはTOS2としてトレースバック、TOS1としてパラメータ、そしてTOSとして例外を見つけられます。

CALL_FUNCTION argc
関数を呼び出します。argcの低位バイトは位置パラメータを示し、高位バイトはキーワードパラメータの数を示します。オペコードは最初にキーワードパラメータをスタック上に見つけます。それぞれのキーワード引数に対して、その値はキーの上にあります。スタック上のキーワードパラメータの下に位置パラメータはあり、先頭に最も右のパラメータがあります。スタック上のパラメータの下には、呼び出す関数オブジェクトがあります。

MAKE_FUNCTION argc
新しい関数オブジェクトをスタックにプッシュします。TOSは関数に関連付けられたコードです。関数オブジェクトはTOSの下にあるargcデフォルトパラメータをもつように定義されます。

MAKE_CLOSURE argc
新しい関数オブジェクトを作り出し、そのfunc_closureスロットを設定し、それをスタックにプッシュします。TOSは関数に関連付けられたコードです。コードオブジェクトがN個の自由変数を持っているならば、スタック上の次のN個の項目はこれらの変数に対するセルです。関数はセルの前にあるargcデフォルトパラメータも持っています。

BUILD_SLICE argc
スライスオブジェクトをスタックにプッシュします。argcは2あるいは3でなければなりません。2ならばslice(TOS1, TOS)がプッシュされます。3ならばslice(TOS2, TOS1, TOS)がプッシュされます。これ以上の情報については、slice()組み込み関数を参照してください。

EXTENDED_ARG ext
大きすぎてデフォルトの二バイトに当てはめることができない引数をもつあらゆるオペコードの前に置かれます。extは二つの追加バイトを保持し、その後ろのオペコードの引数と一緒になって取られます。それらは四バイト引数を構成し、extはその最上位バイトです。

CALL_FUNCTION_VAR argc
関数を呼び出します。argcはCALL_FUNCTIONのように解釈実行されます。スタックの先頭の要素は変数引数リストを含んでおり、その後にキーワードと位置引数が続きます。

CALL_FUNCTION_KW argc
関数を呼び出します。argcはCALL_FUNCTIONのように解釈実行されます。スタックの先頭の要素はキーワード引数辞書を含んでおり、その後に明示的なキーワードと位置引数が続きます。

CALL_FUNCTION_VAR_KW argc
関数を呼び出します。argcはCALL_FUNCTIONのように解釈実行されます。スタックの先頭の要素はキーワード引数辞書を含んでいおり、その後に変数引数のタプルが続き、さらに明示的なキーワードと位置引数が続きます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.10 dis Up: 18.10 dis Next: 18.11 distutils


18.11 distutils -- Python モジュールの構築とインストール

distutils パッケージは、現在インストールされている Python に 追加するためのモジュール構築、および実際のインストールを支援します。 新規のモジュールは 100%-pure Python でも、C で書かれた拡張モジュールでも、 あるいは Python と C 両方のコードが入っているモジュールからなる Python パッケージでもかまいません。

このパッケージは、Python ドキュメンテーション パッケージに含まれている これとは別の 2つのドキュメントで詳しく説明されています。distutils の機能を使って新しいモジュールを配布する方法は、 Python モジュールを配布する に書かれています。 Python モジュールをインストールする方法は、 モジュールの作者が distutils パッケージを使っている場合でもいない場合でも、 Python モジュールをインストールする に書かれています。

参考資料:

Python モジュールを配布する
このマニュアルは Python モジュールの開発者およびパッケージ担当に向けたものです。 ここでは、現在インストールされている Python に簡単に追加できる distutilsベースのパッケージをどうやって用意するかについて 説明しています。

Python モジュールをインストールする
現在インストールされている Python にモジュールを追加するための 情報が書かれた ``管理者'' 向けのマニュアルです。 この文書を読むのに Python プログラマである必要はありません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.10.1 Pythonバイトコード命令 Up: 18. Python言語サービス Next: 19. Python コンパイラパッケージ


19. Python コンパイラパッケージ

Python compiler パッケージは Python のソースコードを分析したり Python バイトコードを生成するためのツールです。compiler は Python のソースコードから抽象的な構文木を生成し、その構文木から Python バイトコードを生成するライブラリをそなえています。

compiler パッケージは、Python で書かれた Python ソースコードからバイトコードへの変換プログラムです。 これは組み込みの構文解析器をつかい、そこで得られた 具体的な構文木に対して標準的な parser モジュールを使用します。 この構文木から抽象構文木 AST (Abstract Syntax Tree) が生成され、 その後 Python バイトコードが得られます。

このパッケージの機能は、Python インタプリタに内蔵されている 組み込みのコンパイラがすべて含んでいるものです。これはその機能と 正確に同じものになるよう意図してつくられています。なぜ同じことをする コンパイラをもうひとつ作る必要があるのでしょうか? このパッケージは いろいろな目的に使うことができるからです。これは組み込みのコンパイラよりも 簡単に変更できますし、これが生成する AST は Python ソースコードを 解析するのに有用です。

この章では compiler パッケージのいろいろなコンポーネントが どのように動作するのかを説明します。そのため説明はリファレンスマニュアル的なものと、 チュートリアル的な要素がまざったものになっています。

以下のモジュールは compiler パッケージの一部です:

compiler
compiler.ast
compiler.visitor

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.11 distutils Up: Python ライブラリリファレンス Next: 19.1 基本的なインターフェイス


19.1 基本的なインターフェイス

このパッケージのトップレベルでは 4つの関数が定義されています。 compiler モジュールを import すると、これらの関数および このパッケージに含まれている一連のモジュールが使用可能になります。

parse( buf)
buf 中の Python ソースコードから得られた抽象構文木 AST を返します。 ソースコード中にエラーがある場合、この関数は SyntaxError を発生させます。 返り値は compiler.ast.Module インスタンスであり、 この中に構文木が格納されています。

parseFile( path)
path で指定されたファイル中の Python ソースコードから得られた 抽象構文木 AST を返します。これは parse(open(path).read()) と等価な働きをします。

walk( ast, visitor[, verbose])
ast に格納された抽象構文木の各ノードを先行順序 (pre-order) で たどっていきます。各ノードごとに visitor インスタンスの 該当するメソッドが呼ばれます。

compile( source, filename, mode, flags=None, dont_inherit=None)
文字列 source、Python モジュール、文あるいは式を exec 文あるいは eval() 関数で実行可能なバイトコードオブジェクトに コンパイルします。この関数は組み込みの compile() 関数を 置き換えるものです。

filename は実行時のエラーメッセージに使用されます。

mode は、モジュールをコンパイルする場合は 'exec'、 (対話的に実行される) 単一の文をコンパイルする場合は 'single'、 式をコンパイルする場合には 'eval' を渡します。

引数 flags および dont_inherit は将来的に使用される文に 影響しますが、いまのところはサポートされていません。

compileFile( source)
ファイル source をコンパイルし、.pyc ファイルを生成します。

compiler パッケージは以下のモジュールを含んでいます: ast、 consts,、 future、 misc、 pyassem、 pycodegen、 symbols、 transformer、 そして visitor。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 19. Python コンパイラパッケージ Up: 19. Python コンパイラパッケージ Next: 19.2 制限


19.2 制限

compiler パッケージにはエラーチェックにいくつか問題が存在します。 構文エラーはインタープリタの 2つの別々のフェーズによって認識されます。 ひとつはインタープリタのパーザによって認識されるもので、 もうひとつはコンパイラによって認識されるものです。 compiler パッケージはインタープリタのパーザに依存しているので、 最初の段階のエラーチェックは労せずして実現できています。 しかしその次の段階は、実装されてはいますが、その実装は不完全です。 たとえば compiler パッケージは引数に同じ名前が 2度以上出てきていても エラーを出しません: def f(x, x): ...

compiler の将来のバージョンでは、これらの問題は修正される予定です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 19.1 基本的なインターフェイス Up: 19. Python コンパイラパッケージ Next: 19.3 Python 抽象構文


19.3 Python 抽象構文

compiler.ast モジュールは Python の抽象構文木 AST を定義します。 AST では各ノードがそれぞれの構文要素をあらわします。 木の根は Module オブジェクトです。

抽象構文木 AST は、パーズされた Python ソースコードに対する 高水準のインターフェイスを提供します。Python インタプリタにおける parser モジュールと コンパイラは C で書かれおり、具体的な構文木を使っています。 具体的な構文木は Python のパーザ中で使われている構文と密接に関連しています。 ひとつの要素に単一のノードを割り当てる代わりに、ここでは Python の 優先順位に従って、何層にもわたるネストしたノードがしばしば使われています。

抽象構文木 AST は、compiler.transformer (変換器) モジュールに よって生成されます。transformer は組み込みの Python パーザに依存しており、 これを使って具体的な構文木をまず生成します。つぎにそこから抽象構文木 AST を 生成します。

transformer モジュールは、実験的な Python-to-C コンパイラ用に Greg Steinと Bill Tuttによって作られました。 現行のバージョンではいくつもの修正と改良がなされていますが、 抽象構文木 AST と transformer の基本的な構造は Stein と Tutt によるものです。

  • 19.3.1 AST ノード
  • 19.3.2 代入ノード
  • 19.3.3 サンプル
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 19.2 制限 Up: 19. Python コンパイラパッケージ Next: 19.3.1 AST ノード


19.3.1 AST ノード

compiler.ast モジュールは、各ノードのタイプとその要素を記述した テキストファイルからつくられます。各ノードのタイプはクラスとして表現され、 そのクラスは抽象基底クラス compiler.ast.Node を継承し 子ノードの名前属性を定義しています。

class Node( )

Node インスタンスはパーザジェネレータによって自動的に作成されます。 ある特定の Node インスタンスに対する推奨されるインターフェイスとは、 子ノードにアクセスするために public な (訳注: 公開された) 属性を使うことです。 public な属性は単一のノード、あるいは一連のノードのシーケンスに 束縛されている (訳注: バインドされている) かもしれませんが、 これは Node のタイプによって違います。 たとえば Class ノードの bases 属性は 基底クラスのノードのリストに束縛されており、doc 属性は 単一のノードのみに束縛されている、といった具合です。

各 Node インスタンスは lineno 属性をもっており、 これは None かもしれません。 XXX どういったノードが使用可能な lineno をもっているかの規則は定かではない。

Node オブジェクトはすべて以下のメソッドをもっています:

getChildren( )
子ノードと子オブジェクトを、これらが出てきた順で、平らなリスト形式にして返します。 とくにノードの順序は、 Python 文法中に現れるものと同じになっています。 すべての子が Node インスタンスなわけではありません。 たとえば関数名やクラス名といったものは、ただの文字列として表されます。

getChildNodes( )
子ノードをこれらが出てきた順で平らなリスト形式にして返します。 このメソッドは getChildren() に似ていますが、 Node インスタンスしか返さないという点で異なっています。

Node クラスの一般的な構造を説明するため、 以下に 2つの例を示します。while 文は以下のような文法規則により 定義されています:

while_stmt:     "while" expression ":" suite
               ["else" ":" suite]

While ノードは 3つの属性をもっています: test、 body、 および else_ です。(ある属性にふさわしい名前が Python の予約語としてすでに使われているとき、その名前を属性名にすることは できません。そのため、ここでは名前が正規のものとして受けつけられるように アンダースコアを後につけてあります、そのため else_ は else のかわりです。)

if 文はもっとこみ入っています。なぜならこれは いくつもの条件判定を含む可能性があるからです。

if_stmt: 'if' test ':' suite ('elif' test ':' suite)* ['else' ':' suite]

If ノードでは、tests および else_ の 2つだけの属性が定義されています。tests 属性には条件式とその後の動作の タプルがリスト形式で入っています。おのおのの if/elif 節ごとに 1タプルです。各タプルの最初の要素は条件式で、2番目の要素はもしその式が 真ならば実行されるコードをふくんだ Stmt ノードになっています。

If の getChildren() メソッドは、 子ノードの平らなリストを返します。if/elif 節が 3つあって else 節がない場合なら、getChildren() は 6要素のリストを 返すでしょう: 最初の条件式、最初の Stmt、2番目の条件式…といった具合です。

以下の表は compiler.ast で定義されている Node サブクラスと、 それらのインスタンスに対して使用可能なパブリックな属性です。 ほとんどの属性の値じたいは Node インスタンスか、インスタンスのリストです。 この値がインスタンス型以外の場合、その型は備考の中で記されています。 これら属性の順序は、 getChildren() および getChildNodes() が返す順です。

ノードの型 | 属性 | 値
Add | left | 左側の項
 | right | 右側の項
And | nodes | 項のリスト
AssAttr |  | 代入先をあらわす属性
 | expr | ドット(.) の左側の式
 | attrname | 属性名をあらわす文字列
 | flags | XXX
AssList | nodes | 代入先のリスト要素のリスト
AssName | name | 代入先の名前
 | flags | XXX
AssTuple | nodes | 代入先のタプル要素のリスト
Assert | test | 検査される条件式
 | fail | AssertionError の値
Assign | nodes | 代入先のリスト、代入記号(=)ごとにひとつ
 | expr | 代入する値
AugAssign | node |
 | op |
 | expr |
Backquote | expr |
Bitand | nodes |
Bitor | nodes |
Bitxor | nodes |
Break |  |
CallFunc | node | 呼ばれる側をあらわす式
 | args | 引数のリスト
 | star_args | *-arg 拡張引数の値
 | dstar_args | **-arg 拡張引数の値
Class | name | クラス名をあらわす文字列
 | bases | 基底クラスのリスト
 | doc | doc string、文字列あるいは None
 | code | クラス文の本体
Compare | expr |
 | ops |
Const | value |
Continue |  |
Dict | items |
Discard | expr |
Div | left |
 | right |
Ellipsis |  |
Exec | expr |
 | locals |
 | globals |
For | assign |
 | list |
 | body |
 | else_ |
From | modname |
 | names |
Function | name | def で定義される名前をあらわす文字列
 | argnames | 引数をあわらす文字列のリスト
 | defaults | デフォルト値のリスト
 | flags | xxx
 | doc | doc string、文字列あるいは None
 | code | 関数の本体
Getattr | expr |
 | attrname |
Global | names |
If | tests |
 | else_ |
Import | names |
Invert | expr |
Keyword | name |
 | expr |
Lambda | argnames |
 | defaults |
 | flags |
 | code |
LeftShift | left |
 | right |
List | nodes |
ListComp | expr |
 | quals |
ListCompFor | assign |
 | list |
 | ifs |
ListCompIf | test |
Mod | left |
 | right |
Module | doc | doc string、文字列あるいは None
 | node | モジュール本体、Stmt インスタンス
Mul | left |
 | right |
Name | name |
Not | expr |
Or | nodes |
Pass |  |
Power | left |
 | right |
Print | nodes |
 | dest |
Printnl | nodes |
 | dest |
Raise | expr1 |
 | expr2 |
 | expr3 |
Return | value |
RightShift | left |
 | right |
Slice | expr |
 | flags |
 | lower |
 | upper |
Sliceobj | nodes | 文のリスト
Stmt | nodes |
Sub | left |
 | right |
Subscript | expr |
 | flags |
 | subs |
TryExcept | body |
 | handlers |
 | else_ |
TryFinally | body |
 | final |
Tuple | nodes |
UnaryAdd | expr |
UnarySub | expr |
While | test |
 | body |
 | else_ |
Yield | value |

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 19.3 Python 抽象構文 Up: 19.3 Python 抽象構文 Next: 19.3.2 代入ノード


19.3.2 代入ノード

代入をあらわすのに使われる一群のノードが存在します。 ソースコードにおけるそれぞれの代入文は、抽象構文木 AST では 単一のノード Assign になっています。 nodes 属性は各代入の対象にたいするノードのリストです。 これが必要なのは、たとえば a = b = 2 のように 代入が連鎖的に起こるためです。 このリスト中における各 Node は、 次のうちどれかのクラスになります: AssAttr、 AssList、 AssName、 または AssTuple。

代入対象の各ノードには代入されるオブジェクトの種類が記録されています。 AssName は a = 1 などの単純な変数名、 AssAttr は a.x = 1 などの属性に対する代入、 AssList および AssTuple はそれぞれ、 a, b, c = a_tuple などのようなリストとタプルの展開をあらわします。

代入対象ノードはまた、そのノードが代入で使われるのか、それとも del 文で使われるのかをあらわす属性 flags も持っています。 AssName は del x などのような del 文をあらわすのにも 使われます。

ある式がいくつかの属性への参照をふくんでいるときは、 代入あるいは del 文はただひとつだけの AssAttr ノードをもちます - 最終的な属性への参照としてです。それ以外の属性への参照は AssAttr インスタンスの expr 属性にある Getattr ノードによってあらわされます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 19.3.1 AST ノード Up: 19.3 Python 抽象構文 Next: 19.3.3 サンプル


19.3.3 サンプル

この節では、Python ソースコードに対する抽象構文木 AST の かんたんな例をいくつかご紹介します。これらの例では parse() 関数をどうやって使うか、AST の repr 表現は どんなふうになっているか、そしてある AST ノードの属性に アクセスするにはどうするかを説明します。

最初のモジュールでは単一の関数を定義しています。 かりにこれは /tmp/doublelib.py に格納されていると仮定しましょう。

"""This is an example module.

This is the docstring.
"""

def double(x):
    "Return twice the argument"
    return x * 2

以下の対話的インタプリタのセッションでは、 見やすさのため 長い AST の repr を整形しなおしてあります。 AST の repr では qualify されていないクラス名が使われています。 repr 表現からインスタンスを作成したい場合は、 compiler.ast モジュールから それらのクラス名を import しなければなりません。

>>> import compiler
>>> mod = compiler.parseFile("/tmp/doublelib.py")
>>> mod
Module('This is an example module.\n\nThis is the docstring.\n',
       Stmt([Function('double', ['x'], [], 0, 'Return twice the argument',
       Stmt([Return(Mul((Name('x'), Const(2))))]))]))
>>> from compiler.ast import *
>>> Module('This is an example module.\n\nThis is the docstring.\n',
...    Stmt([Function('double', ['x'], [], 0, 'Return twice the argument',
...    Stmt([Return(Mul((Name('x'), Const(2))))]))]))
Module('This is an example module.\n\nThis is the docstring.\n',
       Stmt([Function('double', ['x'], [], 0, 'Return twice the argument',
       Stmt([Return(Mul((Name('x'), Const(2))))]))]))
>>> mod.doc
'This is an example module.\n\nThis is the docstring.\n'
>>> for node in mod.node.nodes:
...     print node
...
Function('double', ['x'], [], 0, 'Return twice the argument',
         Stmt([Return(Mul((Name('x'), Const(2))))]))
>>> func = mod.node.nodes[0]
>>> func.code
Stmt([Return(Mul((Name('x'), Const(2))))])

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 19.3.2 代入ノード Up: 19.3 Python 抽象構文 Next: 19.4 Visitor を使って AST


19.4 Visitor を使って AST をわたり歩く

visitor パターンは ... compiler パッケージは、Python のイントロスペクション機能を利用して visitor のために必要な大部分のインフラを省略した、visitor パターンの変種を使っています。

visit されるクラスは、visitor を受け入れるようにプログラムされている必要はありません。 visitor が必要なのはただそれがとくに興味あるクラスに対して visit メソッドを 定義することだけです。それ以外はデフォルトの visit メソッドが処理します。

XXX The magic visit() method for visitors.

walk( tree, visitor[, verbose])

class ASTVisitor( )

ASTVisitor は構文木を正しい順序でわたり歩くようにします。 それぞれのノードはまず preorder() の呼び出しではじまります。 各ノードに対して、これは `visitNodeType' という名前のメソッドに対する preorder() 関数への visitor 引数をチェックします。 ここで NodeType の部分はそのノードのクラス名です。たとえば While ノードなら、visitWhile() が呼ばれるわけです。 もしそのメソッドが存在している場合、それはそのノードを第一引数として呼び出されます。

ある特定のノード型に対する visitor メソッドでは、 その子ノードをどのようにわたり歩くかが制御できます。 ASTVisitor は visitor に visit メソッドを追加することで、 その visitor 引数を修正します。特定のノード型に対する visitor が 存在しない場合、 default() メソッドが呼び出されます。

ASTVisitor オブジェクトには以下のようなメソッドがあります:

XXX 追加の引数を記述

default( node[, ...])

dispatch( node[, ...])

preorder( tree, visitor)

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 19.3.3 サンプル Up: 19. Python コンパイラパッケージ Next: 19.5 バイトコード生成


19.5 バイトコード生成

バイトコード生成器はバイトコードを出力する visitor です。 visit メソッドが呼ばれるたびにこれは emit() メソッドを 呼び出し、バイトコードを出力します。基本的なバイトコード生成器は モジュール、クラス、および関数によって拡張できます。 アセンブラがこれらの出力された命令を低レベルのバイトコードに変換します。 これはコードオブジェクトからなる定数のリスト生成や、 分岐のオフセット計算といった処理をおこないます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 19.4 Visitor を使って AST Up: 19. Python コンパイラパッケージ Next: 20. SGI IRIX 特有のサービス


20. SGI IRIX 特有のサービス

この章で記述されているモジュールは、SGI の IRIX オペレーティングシステム (バージョン4と5) 特有の機能へのインターフェイスを提供します。

al | SGIのオーディオ機能。
AL | alモジュールで使われる定数。
cd | Silicon GraphicsシステムのCD-ROMへのインターフェース
fl | グラフィカルユーザーインターフェースのためのFORMSライブラリ。
FL | flモジュールで使用される定数。
flp | 保存されたFORMSデザインをロードする関数。
fm | SGIワークステーションの Font Manager インターフェース。
gl | Silicon Graphics のGraphics Library の関数。
DEVICE | glモジュールで使われる定数。
GL | glモジュールで使われる定数。
imgfile | SGI imglib ファイルのサポート。
jpeg | JPEGファイルの読み書きを行います。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 19.5 バイトコード生成 Up: Python ライブラリリファレンス Next: 20.1 al


20.1 al -- SGIのオーディオ機能

利用可能な条件: IRIX.

このモジュールを使うと、SGI IndyとIndigoワークステーションのオーディオ装 置にアクセスできます。 詳しくはIRIXのmanページのセクション3Aを参照してください。 ここに書かれた関数が何をするかを理解するには、manページを読む必要が あります！ IRIXのリリース4.0.5より前のものでは使えない関数もあります。 お使いのプラットフォームで特定の関数が使えるかどうか、マニュアルで確認し てください。

このモジュールで定義された関数とメソッドは全て、名前に"AL"の接頭辞 を付けたCの関数と同義です。

Cのヘッダーファイル<audio.h>のシンボル定数は標準モジュール ALに定義されています。 下記を参照してください。

警告: オーディオライブラリの現在のバージョンは、不正な引数が渡されるとエラース テイタスが返るのではなく、coreを吐き出すことがあります。 残念ながら、この現象が確実に起こる環境は述べられていないし、確認する ことは難しいので、Pythonインターフェースでこの種の問題に対して防御する ことはできません。 （一つの例は過大なキューサイズを特定することです -- 上限については記載 されていません。）

このモジュールには、以下の関数が定義されています：

openport( name, direction[, config])
引数nameとdirectionは文字列です。 省略可能な引数configは、newconfig()で返されるコンフィ ギュレーションオブジェクトです。 返り値はaudio port objectです；オーディオポートオブジェクトの メソッドは下に書かれています。

newconfig( )
返り値は新しいaudio configuration objectです；オーディオコンフィ ギュレーションオブジェクトのメソッドは下に書かれています。

queryparams( device)
引数deviceは整数です。 返り値はALqueryparams()で返されるデータを含む整数のリストで す。

getparams( device, list)
引数deviceは整数です。 引数listはqueryparams()で返されるようなリストです； queryparams()を適切に（！）修正して使うことができます。

setparams( device, list)
引数deviceは整数です。 引数listはqueryparams()で返されるようなリストです。

  • 20.1.1 コンフィギュレーションオブジェクト
  • 20.1.2 ポートオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20. SGI IRIX 特有のサービス Up: 20. SGI IRIX 特有のサービス Next: 20.1.1 コンフィギュレーションオブジェクト


20.1.1 コンフィギュレーションオブジェクト

newconfig()で返されるコンフィギュレーションオブジェクト には以下のメソッドがあります：

getqueuesize( )
キューサイズを返します。

setqueuesize( size)
キューサイズを設定します。

getwidth( )
サンプルサイズを返します。

setwidth( width)
サンプルサイズを設定します。

getchannels( )
チャンネル数を返します。

setchannels( nchannels)
チャンネル数を設定します。

getsampfmt( )
サンプルのフォーマットを返します。

setsampfmt( sampfmt)
サンプルのフォーマットを設定します。

getfloatmax( )
浮動小数点数でサンプルデータの最大値を返します。

setfloatmax( floatmax)
浮動小数点数でサンプルデータの最大値を設定します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.1 al Up: 20.1 al Next: 20.1.2 ポートオブジェクト


20.1.2 ポートオブジェクト

openport()で返されるポートオブジェクトには以下のメソッドがあ ります：

closeport( )
ポートを閉じます。

getfd( )
ファイルディスクリプタを整数で返します。

getfilled( )
バッファに存在するサンプルの数を返します。

getfillable( )
バッファの空きに入れることのできるサンプルの数を返します。

readsamps( nsamples)
必要ならブロックして、キューから指定のサンプル数を読み込みます。 生データを文字列として （例えば、サンプルサイズが2バイトならサンプル当たり2バイトがbig-endian （high byte、low byte）で）返します。

writesamps( samples)
必要ならブロックして、キューにサンプルを書き込みます。 サンプルはreadsamps()で返される値のようにエンコードされていなけ ればなりません。

getfillpoint( )
`fill point'を返します。

setfillpoint( fillpoint)
`fill point'を設定します。

getconfig( )
現在のポートのコンフィギュレーションを含んだコンフィギュレーションオブ ジェクトを返します。

setconfig( config)
コンフィギュレーションを引数に取り、そのコンフィギュレーションに設定しま す。

getstatus( list)
最後のエラーについてのステイタスの情報を返します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.1.1 コンフィギュレーションオブジェクト Up: 20.1 al Next: 20.2 AL


20.2 AL -- alモジュールで使われる定数

利用可能な条件: IRIX.

このモジュールには、組み込みモジュールal（上記参照）を使用す るのに必要とされるシンボリック定数が定義されています。 定数の名前はCのincludeファイル<audioio.h>で 接頭辞"AL_"を除いたものと同じです。

定義されている名前の完全なリストについてはモジュールのソースを参照してく ださい。 お勧めの使い方は以下の通りです：

import al
from AL import *
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.1.2 ポートオブジェクト Up: 20. SGI IRIX 特有のサービス Next: 20.3 cd


20.3 cd -- SGIシステムのCD-ROMへのアクセス

利用可能な条件: IRIX.

このモジュールはSilicon Graphics CD ライブラリへのインターフェースを提供 します。 Silicon Graphics システムだけで利用可能です。

ライブラリは以下のように使われます。

CD-ROMデバイスをopen()で開き、 createparser()でCDからデータをパースするためのパーザを作りま す。 open()で返されるオブジェクトはCDからデータを読み込むのに使わ れますが、CD-ROMデバイスのステータス情報や、CDの情報、たとえば目次などを 得るのにも使われます。 CDから得たデータはパーザに渡され、パーザはフレームをパースし、あらかじめ 加えられたコールバック関数を呼び出します。

オーディオCDはトラックtracksあるいはプログラムprograms（同じ 意味で、どちらかの用語が使われます）に分けられます。 トラックはさらにインデックスindicesに分けられます。 オーディオCDは、CD上の各トラックのスタート位置を示す 目次table of contentsを持っています。 インデックス0は普通、トラックの始まりの前のポーズです。 目次から得られるトラックのスタート位置は通常、インデックス1のスタート位 置です。

CD上の位置は2通りの方法で得ることができます。 それはフレームナンバーと、分、秒、フレームの3つの値からなるタプ ルの2つです。 ほとんどの関数は後者を使います。 位置はCDの開始位置とトラックの開始位置の両方に相対的になります。

モジュールcdは、以下の関数と定数を定義しています：

createparser( )
不透明なパーザオブジェクトを作って返します。 パーザオブジェクトのメソッドは下に記載されています。

msftoframe( minutes, seconds, frames)
絶対的なタイムコードである(minutes, seconds, frames)の3つ組の表現を、相当するCDのフレームナンバーに変換しま す。

open( [device[, mode]])
CD-ROMデバイスを開きます。 不透明なプレーヤーオブジェクトを返します； プレーヤーオブジェクトのメソッドは下に記載されています。 デバイスdeviceはSCSIデバイスファイルの名前で、例えば '/dev/scsi/sc0d4l0'あるいはNoneです。 もし省略したり、Noneなら、ハードウエアが検索されてCD-ROMデバイス を割り当てます。 modeは、省略しないなら'r'にすべきです。

このモジュールでは以下の変数を定義しています：

exception error
様々なエラーについて発生する例外です。

DATASIZE
オーディオデータの1フレームのサイズです。 これはaudioタイプのコールバックへ渡されるオーディオデータのサイ ズです。

BLOCKSIZE
オーディオデータが読み取られていないフレーム1つのサイズです。

以下の変数はgetstatus()で返されるステータス情報です：

READY
オーディオCDがロードされて、ドライブが操作可能であることを示します。

NODISC
ドライブにCDがロードされていないことを示します。

CDROM
ドライブにCD-ROMがロードされていることを示します。 続いてplayあるいはreadの操作をすると、I/Oエラーを返します。

ERROR
ディスクや目次を読み込もうとしているときに起こるエラー。

PLAYING
ドライブがオーディオCDをCDプレーヤーモードでオーディオ端子から再生 していることを示します。

PAUSED
ドライブがCDプレーヤーモードで、再生を一時停止していることを示します。

STILL
PAUSEDと同じですが、古いモデル（non 3301）である Toshiba CD-ROMドライブのものです。 このドライブはもうSGIから出荷されていません。

audio
pnum
index
ptime
atime
catalog
ident
control
これらは整数の定数で、パーザのいろいろなタイプのコールバックを示していま す。コールバックはCDパーザオブジェクトのaddcallback()で設定でき ます（下記参照）。

  • 20.3.1 プレーヤーオブジェクト
  • 20.3.2 パーザオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.2 AL Up: 20. SGI IRIX 特有のサービス Next: 20.3.1 プレーヤーオブジェクト


20.3.1 プレーヤーオブジェクト

プレーヤーオブジェクト（open()で返されます）には以下のメソッ ドがあります：

allowremoval( )
CD-ROMドライブのイジェクトボタンのロックを解除して、ユーザがCDキャディを 排出するのを許可します。

bestreadsize( )
メソッドreadda()のパラメータnum_framesとして最適の値を返 します。 最適値はCD-ROMドライブからの連続したデータフローが許可される値が定義され ます。

close( )
プレーヤーオブジェクトと関連付けられたリソースを解放します。 close()を呼び出したあとでは、そのオブジェクトに対するメソッドは 使用できません。

eject( )
CD-ROMドライブからキャディを排出します。

getstatus( )
CD-ROMドライブの現在の状態に関する情報を返します。 返される情報は以下の値からなるタプルです： state、track、rtime、atime、ttime、 first、last、scsi_audio、cur_block。 rtimeは現在のトラックの初めからの相対的な時間； atimeはディスクの初めからの相対的な時間； ttimeはディスクの全時間です。 それぞれの値の詳細については、マニュアルページ CDgetstatus(3dm)を参照してください。 stateの値は以下のうちのどれか一つです： ERROR、NODISC、READY、 PLAYING、PAUSED、STILL、 CDROM。

gettrackinfo( track)
特定のトラックについての情報を返します。 返される情報は、トラックの開始時刻とトラックの時間の長さの二つの要素から なるタプルです。

msftoblock( min, sec, frame)
分、秒、フレームの3つからなる絶対的なタイムコードを、与えられたCD-ROMド ライブの相当する論理ブロック番号に変換します。 時刻を比較するにはmsftoblock()よりもmsftoframe()を 使うべきです。 論理ブロック番号は、CD-ROMドライブによって必要とされるオフセット値が違う ため、フレームナンバーと異なります。

play( start, play)
CD-ROMドライブのオーディオCDの特定のトラックから再生を開始します。 CD-ROMドライブのヘッドフォン端子と（備えているなら）オーディオ端子から出 力されます。 ディスクの最後で再生は停止します。 startは再生を開始するCDのトラックナンバーです； playが0なら、CDは最初の一時停止状態になります。 その状態からメソッドtogglepause()で再生を開始できます。

playabs( minutes, seconds, frames, play)
play()と似ていますが、開始位置をトラックナンバーの代わりに分、 秒、フレームで与えます。

playtrack( start, play)
play()と似ていますが、トラックの終わりで再生を停止します。

playtrackabs( track, minutes, seconds, frames, play)
play()と似ていますが、指定した絶対的な時刻から再生を開始して、 指定したトラックで終了します。

preventremoval( )
CD-ROMドライブのイジェクトボタンをロックして、ユーザがCDキャディを排出で きないようにします。

readda( num_frames)
CD-ROMドライブにマウントされたオーディオCDから、指定したフレーム数を読み 込みます。 オーディオフレームのデータを示す文字列を返します。 この文字列はそのままパーザオブジェクトのメソッドparseframe()へ 渡すことができます。

seek( minutes, seconds, frames)
CD-ROMから次にデジタルオーディオデータを読み込む開始位置のポインタを設定 します。 ポインタはminutes、seconds、framesで指定した絶対的なタ イムコードの位置に設定されます。 返される値はポインタが設定された論理ブロック番号です。

seekblock( block)
CD-ROMから次にデジタルオーディオデータを読み込む開始位置のポインタを設定 します。 ポインタは指定した論理ブロック番号に設定されます。 返される値はポインタが設定された論理ブロック番号です。

seektrack( track)
CD-ROMから次にデジタルオーディオデータを読み込む開始位置のポインタを設定 します。 ポインタは指定したトラックに設定されます。 返される値はポインタが設定された論理ブロック番号です。

stop( )
現在実行中の再生を停止します。

togglepause( )
再生中ならCDを一時停止し、一時停止中なら再生します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.3 cd Up: 20.3 cd Next: 20.3.2 パーザオブジェクト


20.3.2 パーザオブジェクト

パーザオブジェクト（createparser()で返されます）には以下のメ ソッドがあります：

addcallback( type, func, arg)
パーザにコールバックを加えます。 デジタルオーディオストリームの8つの異なるデータタイプのためのコールバッ クをパーザは持っています。 これらのタイプのための定数はcdモジュールのレベルで定義されてい ます（上記参照）。 コールバックは以下のように呼び出されます： func(arg, type, data)、ここでargはユーザが与え た引数、typeはコールバックの特定のタイプ、dataはこの typeのコールバックに渡されるデータです。 データのタイプは以下のようにコールバックのタイプによって決まります：

Type | Value
audio | al.writesamps()へそのまま渡すことのできる文字列。
pnum | プログラム（トラック）ナンバーを示す整数。
index | インデックスナンバーを示す整数。
ptime | プログラムの時間を示す分、秒、フレームからなるタプル。
atime | 絶対的な時刻を示す分、秒、フレームからなるタプル。
catalog | CDのカタログナンバーを示す13文字の文字列。
ident | 録音のISRC識別番号を示す12文字の文字列。 文字列は2文字の国別コード、3文字の所有者コード、2文字の年号、5文字のシリ アルナンバーからなります。
control | CDのサブコードデータのコントロールビットを示す整数。

deleteparser( )
パーザを消去して、使用していたメモリを解放します。 この呼び出しのあと、オブジェクトは使用できません。 オブジェクトへの最後の参照が削除されると、自動的にこのメソッドが呼び出さ れます。

parseframe( frame)
readda()などから返されたデジタルオーディオCDのデータの1つあるい はそれ以上のフレームをパースします。 データ内にどういうサブコードがあるかを決定します。 その前のフレームからサブコードが変化していたら、parseframe() は対応するタイプのコールバックを起動して、フレーム内のサブコードデータを コールバックに渡します。 Cの関数とは違って、1つ以上のデジタルオーディオデータのフレームをこの メソッドに渡すことができます。

removecallback( type)
指定したtypeのコールバックを削除します。

resetparser( )
サブコードを追跡しているパーザのフィールドをリセットして、初期状態にしま す。 ディスクを交換したあと、resetparser()を呼び出さなければなりませ ん。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.3.1 プレーヤーオブジェクト Up: 20.3 cd Next: 20.4 fl


20.4 fl -- グラフィカルユーザーインターフェースのためのFORMSライブラリ

利用可能な条件: IRIX.

このモジュールは、Mark OvermarsによるFORMS Library へのインターフェースを提供します。 FORMSライブラリのソースはanonymous ftp "ftp.cs.ruu.nl"の SGI/FORMSディレクトリから入手できます。 最新のテストはバージョン2.0bで行いました。

ほとんどの関数は接頭辞の"fl_"を取ると、対応するCの関数名になりま す。 ライブラリで使われる定数は後述のFLモジュールで 定義されています。

Pythonでこのオブジェクトを作る方法はCとは少し違っています： ライブラリに保持された`現在のフォーム'に新しいFORMSオブジェクトを加える のではなく、フォームにFORMSオブジェクトを加えるには、フォームを示す Pythonオブジェクトのメソッドで全て行います。 したがって、Cの関数のfl_addto_form()と fl_end_form()に相当するものはPythonにはありませんし、 fl_bgn_form()に相当するものとしてはfl.make_form() を呼び出します。

用語のちょっとした混乱に注意してください： FORMSではフォームの中に置くことができるボタン、スライダーなどに objectの用語を使います。 Pythonでは全ての値が`オブジェクト'です。 FORMSへのPythonのインターフェースによって、2つの新しいタイプのPythonオブ ジェクト：フォームオブジェクト（フォーム全体を示します）とFORMSオブジェ クト（ボタン、スライダーなどの一つひとつを示します）を作ります。 おそらく、混乱するほどのことではありません。

FORMSへのPythonインターフェースに`フリーオブジェクト'はありませんし、 Pythonでオブジェクトクラスを書いて加える簡単な方法もありません。 しかし、GLイベントハンドルへのFORMSインターフェースが利用可能で、純粋な GLウィンドウにFORMSを組み合わせることができます。

注意： flをインポートすると、GLの関数foreground()と FORMSのルーチンfl_init()を呼び出します。

  • 20.4.1 flモジュールに定義されている関数
  • 20.4.2 フォームオブジェクト
  • 20.4.3 FORMSオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.3.2 パーザオブジェクト Up: 20. SGI IRIX 特有のサービス Next: 20.4.1 flモジュールに定義されている関数


20.4.1 flモジュールに定義されている関数

flモジュールには以下の関数が定義されています。 これらの関数の働きに関する詳しい情報については、FORMSドキュメントで対応 するCの関数の説明を参照してください。

make_form( type, width, height)
与えられたタイプ、幅、高さでフォームを作ります。 これはformオブジェクトを返します。このオブジェクトは後述のメソッド を持ちます。

do_forms( )
標準のFORMSのメインループです。 ユーザからの応答が必要なFORMSオブジェクトを示すPythonオブジェクト、ある いは特別な値FL.EVENTを返します。

check_forms( )
FORMSイベントを確認します。 do_forms()が返すもの、あるいはユーザからの応答をすぐに必要と するイベントがないならNoneを返します。

set_event_call_back( function)
イベントのコールバック関数を設定します。

set_graphics_mode( rgbmode, doublebuffering)
グラフィックモードを設定します。

get_rgbmode( )
現在のRGBモードを返します。 これはCのグローバル変数fl_rgbmodeの値です。

show_message( str1, str2, str3)
3行のメッセージとOKボタンのあるダイアログボックスを表示します。

show_question( str1, str2, str3)
3行のメッセージとYES、NOのボタンのあるダイアログボックスを表示します。 ユーザによってYESが押されたら1、NOが押されたら0を返しま す。

show_choice( str1, str2, str3, but1[, but2[, but3]])
3行のメッセージと最大3つまでのボタンのあるダイアログボックスを表示しま す。 ユーザによって押されたボタンの数値を返します（それぞれ1、2 、3）。

show_input( prompt, default)
1行のプロンプトメッセージと、ユーザが入力できるテキストフィールドを持つ ダイアログボックスを表示します。 2番目の引数はデフォルトで表示される入力文字列です。 ユーザが入力した文字列が返されます。

show_file_selector( message, directory, pattern, default)
ファイル選択ダイアログを表示します。 ユーザによって選択されたファイルの絶対パス、あるいはユーザがCancelボタン を押した場合はNoneを返します。

get_directory( )
get_pattern( )
get_filename( )
これらの関数は最後にユーザがshow_file_selector()で選択した ディレクトリ、パターン、ファイル名（パスの末尾のみ）を返します。

qdevice( dev)
unqdevice( dev)
isqueued( dev)
qtest( )
qread( )
qreset( )
qenter( dev, val)
get_mouse( )
tie( button, valuator1, valuator2)
これらの関数は対応するGL関数へのFORMSのインターフェースです。 fl.do_events()を使っていて、自分で何かGLイベントを操作したい ときにこれらを使います。 FORMSが扱うことのできないGLイベントが検出されたら fl.do_forms()が特別の値FL.EVENTを返すので、 fl.qread()を呼び出して、キューからイベントを読み込むべきで す。 対応するGLの関数は使わないでください！

color( )
mapcolor( )
getmcolor( )
FORMSドキュメントにあるfl_color()、 fl_mapcolor()、fl_getmcolor() の記述を参照してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.4 fl Up: 20.4 fl Next: 20.4.2 フォームオブジェクト


20.4.2 フォームオブジェクト

フォームオブジェクト（上で述べたmake_form()で返されます）には 下記のメソッドがあります。 各メソッドは名前の接頭辞に"fl_"を付けたCの関数に対応します；また、 最初の引数はフォームのポインタです； 説明はFORMSの公式文書を参照してください。

全てのadd_*()メソッドは、FORMSオブジェクトを示すPythonオブジェ クトを返します。 FORMSオブジェクトのメソッドを以下に記載します。 ほとんどのFORMSオブジェクトは、そのオブジェクトの種類ごとに特有のメソッ ドもいくつか持っています。

show_form( placement, bordertype, name)
フォームを表示します。

hide_form( )
フォームを隠します。

redraw_form( )
フォームを再描画します。

set_form_position( x, y)
フォームの位置を設定します。

freeze_form( )
フォームを固定します。

unfreeze_form( )
固定したフォームの固定を解除します。

activate_form( )
フォームをアクティベートします。

deactivate_form( )
フォームをディアクティベートします。

bgn_group( )
新しいオブジェクトのグループを作ります；グループオブジェクトを返します。

end_group( )
現在のオブジェクトのグループを終了します。

find_first( )
フォームの中の最初のオブジェクトを見つけます。

find_last( )
フォームの中の最後のオブジェクトを見つけます。

add_box( type, x, y, w, h, name)
フォームにボックスオブジェクトを加えます。 特別な追加のメソッドはありません。

add_text( type, x, y, w, h, name)
フォームにテキストオブジェクトを加えます。 特別な追加のメソッドはありません。

add_clock( type, x, y, w, h, name)
フォームにクロックオブジェクトを加えます。
メソッド： get_clock()。

add_button( type, x, y, w, h, name)
フォームにボタンオブジェクトを加えます。
メソッド： get_button()、 set_button()。

add_lightbutton( type, x, y, w, h, name)
フォームにライトボタンオブジェクトを加えます。
メソッド： get_button()、 set_button()。

add_roundbutton( type, x, y, w, h, name)
フォームにラウンドボタンオブジェクトを加えます。
メソッド： get_button()、 set_button()。

add_slider( type, x, y, w, h, name)
フォームにスライダーオブジェクトを加えます。
メソッド：
set_slider_value()、
get_slider_value()、
set_slider_bounds()、
get_slider_bounds()、
set_slider_return()、
set_slider_size()、
set_slider_precision()、
set_slider_step()。

add_valslider( type, x, y, w, h, name)
フォームにバリュースライダーオブジェクトを加えます。
メソッド：
set_slider_value()、
get_slider_value()、
set_slider_bounds()、
get_slider_bounds()、
set_slider_return()、
set_slider_size()、
set_slider_precision()、
set_slider_step()。

add_dial( type, x, y, w, h, name)
フォームにダイアルオブジェクトを加えます。
メソッド：
set_dial_value()、
get_dial_value()、
set_dial_bounds()、
get_dial_bounds()。

add_positioner( type, x, y, w, h, name)
フォームに2次元ポジショナーオブジェクトを加えます。
メソッド：
set_positioner_xvalue()、
set_positioner_yvalue()、
set_positioner_xbounds()、
set_positioner_ybounds()、
get_positioner_xvalue()、
get_positioner_yvalue()、
get_positioner_xbounds()、
get_positioner_ybounds()。

add_counter( type, x, y, w, h, name)
フォームにカウンタオブジェクトを加えます。
メソッド：
set_counter_value()、
get_counter_value()、
set_counter_bounds()、
set_counter_step(),
set_counter_precision()、
set_counter_return()。

add_input( type, x, y, w, h, name)
フォームにインプットオブジェクトを加えます。
メソッド：
set_input()、
get_input()、
set_input_color()、
set_input_return()。

add_menu( type, x, y, w, h, name)
フォームにメニューオブジェクトを加えます。
メソッド：
set_menu()、
get_menu()、
addto_menu()。

add_choice( type, x, y, w, h, name)
フォームにチョイスオブジェクトを加えます。
メソッド：
set_choice()、
get_choice()、
clear_choice()、
addto_choice()、
replace_choice()、
delete_choice()、
get_choice_text()、
set_choice_fontsize()、
set_choice_fontstyle()。

add_browser( type, x, y, w, h, name)
フォームにブラウザオブジェクトを加えます。
メソッド：
set_browser_topline()、
clear_browser()、
add_browser_line()、
addto_browser()、
insert_browser_line()、
delete_browser_line()、
replace_browser_line()、
get_browser_line()、
load_browser()、
get_browser_maxline()、
select_browser_line()、
deselect_browser_line()、
deselect_browser()、
isselected_browser_line()、
get_browser()、
set_browser_fontsize()、
set_browser_fontstyle()、
set_browser_specialkey()。

add_timer( type, x, y, w, h, name)
フォームにタイマーオブジェクトを加えます。
メソッド： set_timer()、 get_timer()。

フォームオブジェクトには以下のデータ属性があります；FORMSドキュメントを 参照してください：

名称 | Cの型 | 意味
window | int (read-only) | GLウィンドウのid
w | float | フォームの幅
h | float | フォームの高さ
x | float | フォーム左肩のx座標
y | float | フォーム左肩のy座標
deactivated | int | フォームがディアクティベートされているなら非ゼロ
visible | int | フォームが可視なら非ゼロ
frozen | int | フォームが固定されているなら非ゼロ
doublebuf | int | ダブルバッファリングがオンなら非ゼロ

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.4.1 flモジュールに定義されている関数 Up: 20.4 fl Next: 20.4.3 FORMSオブジェクト


20.4.3 FORMSオブジェクト

FORMSオブジェクトの種類ごとに特有のメソッドの他に、全てのFORMSオブジェク トは以下のメソッドも持っています：

set_call_back( function, argument)
オブジェクトのコールバック関数と引数を設定します。 オブジェクトがユーザからの応答を必要とするときには、コールバック関数は2 つの引数、オブジェクトとコールバックの引数とともに呼び出されます。 （コールバック関数のないFORMSオブジェクトは、ユーザからの応答を必要とす るときにはfl.do_forms()あるいはfl.check_forms()に よって返されます。） 引数なしにこのメソッドを呼び出すと、コールバック関数を削除します。

delete_object( )
オブジェクトを削除します。

show_object( )
オブジェクトを表示します。

hide_object( )
オブジェクトを隠します。

redraw_object( )
オブジェクトを再描画します。

freeze_object( )
オブジェクトを固定します。

unfreeze_object( )
固定したオブジェクトの固定を解除します。

FORMSオブジェクトには以下のデータ属性があります；FORMSドキュメントを参照 してください。

名称 | Cの型 | 意味
objclass | int (read-only) | オブジェクトクラス
type | int (read-only) | オブジェクトタイプ
boxtype | int | ボックスタイプ
x | float | 左肩のx座標
y | float | 左肩のy座標
w | float | 幅
h | float | 高さ
col1 | int | 第1の色
col2 | int | 第2の色
align | int | 配置
lcol | int | ラベルの色
lsize | float | ラベルのフォントサイズ
label | string | ラベルの文字列
lstyle | int | ラベルのスタイル
pushed | int (read-only) | （FORMSドキュメント参照）
focus | int (read-only) | （FORMSドキュメント参照）
belowmouse | int (read-only) | （FORMSドキュメント参照）
frozen | int (read-only) | （FORMSドキュメント参照）
active | int (read-only) | （FORMSドキュメント参照）
input | int (read-only) | （FORMSドキュメント参照）
visible | int (read-only) | （FORMSドキュメント参照）
radio | int (read-only) | （FORMSドキュメント参照）
automatic | int (read-only) | （FORMSドキュメント参照）

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.4.2 フォームオブジェクト Up: 20.4 fl Next: 20.5 FL


20.5 FL -- flモジュールで使用される定数

利用可能な条件: IRIX.

このモジュールには、組み込みモジュールflを使うのに必要なシン ボル定数が定義されています（上記参照）；これらは名前の接頭辞"FL_"が 省かれていることを除いて、Cのヘッダファイル<forms.h>に定義されて いるものと同じです。 定義されている名称の完全なリストについては、モジュールのソースをご覧くだ さい。 お勧めする使い方は以下の通りです：

import fl
from FL import *

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.4.3 FORMSオブジェクト Up: 20. SGI IRIX 特有のサービス Next: 20.6 flp


20.6 flp -- 保存されたFORMSデザインをロードする関数

利用可能な条件: IRIX.

このモジュールには、FORMSライブラリ（上記のflモジュールを参 照してください）とともに配布される`フォームデザイナー' （fdesign）プログラムで作られたフォームの定義を読み込む関数が 定義されています。

詳しくはPythonライブラリソースのディレクトリの中のflp.docを参照し てください。

XXX　完全な説明をここに書いて！

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.5 FL Up: 20. SGI IRIX 特有のサービス Next: 20.7 fm


20.7 fm -- Font Manager インターフェース

利用可能な条件: IRIX.

このモジュールはIRIS Font Managerライブラリへのアクセスを提供しま す。 Silicon Graphics マシン上だけで利用可能です。 次も参照してください：4Sight User's Guide, section 1, chapter 5: ``Using the IRIS Font Manager''。 このモジュールは、まだ IRIS Font Managerへの完全なインターフェースではあ りません。 サポートされていない機能は次のものです： matrix operations; cache operations; character operations（代わりに string operations を使ってく ださい）; font info のうちのいくつか; individual glyph metrics; printer matching。

以下の操作をサポートしています：

init( )
関数を初期化します。 fminit()を呼び出します。 この関数は fmモジュールを最初にインポートすると自動的に呼び出さ れるので、普通、呼び出す必要はありません。

findfont( fontname)
フォントハンドルオブジェクトを返します。 fmfindfont(fontname)を呼び出します。

enumerate( )
利用可能なフォント名のリストを返します。 この関数はfmenumerate()へのインターフェースです。

prstr( string)
現在のフォントを使って文字列をレンダリングします（下のフォントハンドルメ ソッドsetfont()を参照）。 fmprstr(string)を呼び出します。

setpath( string)
フォントの検索パスを設定します。 fmsetpath(string)を呼び出します。 （XXX 機能しない！？！）

fontpath( )
現在のフォント検索パスを返します。

フォントハンドルオブジェクトは以下の操作をサポートします：

scalefont ( フォントハンドルメソッド)( factor)
このフォントを拡大／縮小したハンドルを返します。 fmscalefont(fh, factor)を呼び出します。

setfont ( フォントハンドルメソッド)( )
このフォントを現在のフォントに設定します。 注意：フォントハンドルオブジェクトが削除されると、設定は告知なしに元に戻 ります。 fmsetfont(fh)を呼び出します。

getfontname ( フォントハンドルメソッド)( )
このフォントの名前を返します。 fmgetfontname(fh)を呼び出します。

getcomment ( フォントハンドルメソッド)( )
このフォントに関連付けられたコメント文字列を返します。 コメント文字列が何もなければ例外を返します。 fmgetcomment(fh)を呼び出します。

getfontinfo ( フォントハンドルメソッド)( )
このフォントに関連したデータを含むタプルを返します。 これはfmgetfontinfo()へのインターフェースです。 以下の数値を含むタプルを返します： (printermatched、fixed_width、xorig、 yorig、xsize、ysize、height、 nglyphs)。

getstrwidth ( フォントハンドルメソッド)( string)
このフォントでstringを描いたときの幅をピクセル数で返します。 fmgetstrwidth(fh, string)を呼び出します。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.6 flp Up: 20. SGI IRIX 特有のサービス Next: 20.8 gl


20.8 gl -- Graphics Library インターフェース

利用可能な条件: IRIX.

このモジュールはSilicon GraphicsのGraphics Libraryへのアクセスを 提供します。 Silicon Graphicsマシン上だけで利用可能です。

警告: GLライブラリの不適切な呼び出しによっては、Pythonインタープリタがコアを吐 き出すことがあります。 特に、GLのほとんどの関数では最初のウィンドウを開く前に呼び出すのは安全で はありません。

このモジュールはとても大きいので、ここに全てを記述することはできません が、以下の説明で出発点としては十分でしょう。 Cの関数のパラメータは、以下のような決まりに従ってPythonに翻訳されます：

  • 全て（short、long、unsigned）の整数値（int）はPythonの整数に相当します。
  • 全ての浮動小数点数と倍精度浮動小数点数はPythonの浮動小数点数に相当しま す。 たいていの場合、Pythonの整数も使えます。
  • 全ての配列はPythonの一次元のリストに相当します。 たいていの場合、タプルも使えます。
  • 全ての文字列と文字の引数は、Pythonの文字列に相当します。例えば、 winopen('Hi There!') と rotate(900, 'z')。
  • 配列である引数の長さを特定するためだけに使われる全て （short、long、unsigned）の整数値の引数あるいは返り値は、無視されます。 例えば、Cの呼び出しで、

    lmdef(deftype, index, np, props)

    これはPythonでは、こうなります。

    lmdef(deftype, index, props)

  • 出力のための引数は、引数のリストから省略されています； 代わりにこれらは関数の返り値として渡されます。 もし１つ以上の値が返されるのなら、返り値はタプルです。 もしCの関数が通常の返り値（先のルールによって省略されません）と、出力の ための引数の両方を取るなら、返り値はタプルの最初に来ます。 例：Cの呼び出しで、

    getmcolor(i, &red, &green, &blue)

    これはPythonではこうなります。

    red, green, blue = getmcolor(i)

以下の関数は一般的でないか、引数に特別な決まりを持っています：

varray( argument)
v3d()の呼び出しに相当しますが、それよりも速いです。 argumentは座標のリスト（あるいはタプル）です。 各座標は(x, y, z)あるいは (x, y)のタプルでなければなりません。 座標は２次元あるいは３次元が可能ですが、全て同次元でなければなりません。 ですが、浮動小数点数と整数を混合して使えます。 座標は（マニュアルページにあるように）必要であればz = 0.0と 仮定して、常に３次元の精密な座標に変換され、各座標についてv3d()が 呼び出されます。

nvarray( )
n3fとv3fの呼び出しに相当しますが、それらよりも速いです。 引数は法線と座標とのペアからなる配列（リストあるいはタプル）です。 各ペアは座標と、その座標からの法線とのタプルです。 各座標と各法線は(x, y, z)からなるタプルでなけれ ばなりません。 ３つの座標が渡されなければなりません。 浮動小数点数と整数を混合して使えます。 各ペアについて、法線に対してn3f()が呼び出され、座標に対して v3f()が呼び出されます。

vnarray( )
nvarray()と似ていますが、各ペアは始めに座標を、２番目に法線を持っ ています。

nurbssurface( s_k, t_k, ctl, s_ord, t_ord, type)
nurbs（非均一有理Bスプライン）曲面を定義します。 ctl[][]の次元は以下のように計算されます： [len(s_k) - s_ord]、 [len(t_k) - t_ord]。

nurbscurve( knots, ctlpoints, order, type)
nurbs（非均一有理Bスプライン）曲線を定義します。 ctlpointsの長さは、len(knots) - orderです。

pwlcurve( points, type)
区分線形曲線（piecewise-linear curve）を定義します。 pointsは座標のリストです。 typeはN_STでなければなりません。

pick( n)
select( n)
これらの関数はただ一つの引数を取り、pick/selectに使うバッファのサイズを 設定します。

endpick( )
endselect( )
これらの関数は引数を取りません。 pick/selectに使われているバッファの大きさを示す整数のリストを返します。 バッファがあふれているのを検出するメソッドはありません。

小さいですが完全なPythonのGLプログラムの例をここに挙げます：

import gl, GL, time

def main():
    gl.foreground()
    gl.prefposition(500, 900, 500, 900)
    w = gl.winopen('CrissCross')
    gl.ortho2(0.0, 400.0, 0.0, 400.0)
    gl.color(GL.WHITE)
    gl.clear()
    gl.color(GL.RED)
    gl.bgnline()
    gl.v2f(0.0, 0.0)
    gl.v2f(400.0, 400.0)
    gl.endline()
    gl.bgnline()
    gl.v2f(400.0, 0.0)
    gl.v2f(0.0, 400.0)
    gl.endline()
    time.sleep(5)

main()

参考資料:

PyOpenGL: PythonのOpenGLとの結合
OpenGLへのインターフェースが利用できます； 詳しくはPyOpenGLプロジェクト http://pyopengl.sourceforge.net/から情報を入手できま す。 これは、SGIのハードウェアが1996年頃より前である必要がないので、OpenGLの 方が良い選択かもしれません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.7 fm Up: 20. SGI IRIX 特有のサービス Next: 20.9 DEVICE


20.9 DEVICE -- glモジュールで使われる定数

利用可能な条件: IRIX.

このモジュールには、Silicon GraphicsのGraphics Libraryで使われる 定数が定義されています。これらはCのプログラマーがヘッダーファイル <gl/device.h>の中から使っているものです。 詳しくはモジュールのソースファイルをご覧ください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.8 gl Up: 20. SGI IRIX 特有のサービス Next: 20.10 GL


20.10 GL -- glモジュールで使われる定数

利用可能な条件: IRIX.

このモジュールにはSilicon GraphicsのGraphics Libraryで使われる Cのヘッダーファイル<gl/gl.h>の定数が定義されています。 詳しくはモジュールのソースファイルをご覧ください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.9 DEVICE Up: 20. SGI IRIX 特有のサービス Next: 20.11 imgfile


20.11 imgfile -- SGI imglib ファイルのサポート

利用可能な条件: IRIX.

imgfile モジュールは、Python プログラムが SGI imglib 画像 ファイル (.rgb ファイルとしても知られています) にアクセスできる ようにします。このモジュールは完全なものにはほど遠いですが、その機能 はある状況で十分役に立つものなので、ライブラリで提供されています。 現在、カラーマップ形式のファイルはサポートされていません。

このモジュールでは以下の変数および関数が定義されています:

exception error
この例外は、サポートされていないファイル形式の場合のような全てのエラーで 送出されます。

getsizes( file)
この関数はタプル (x, y, z) を返します。 x および y は画像のサイズをピクセルで表したもので、 z はピクセルあたりのバイト長です。3 バイトの RGB ピクセルと 1 バイトのグレイスケールピクセルのみが現在サポートされています。

read( file)
この関数は指定されたファイル上の画像を読み出して復号化し、Python 文字列として返します。この文字列は 1 バイトのグレイスケールピクセル か、4 バイトの RGBA ピクセルによるものです。左下のピクセルが文字列 中の最初のピクセルになります。これは gl.lrectwrite() に渡すのに適した形式です。

readscaled( file, x, y, filter[, blur])
この関数は read と同じですが、x および y のサイズに スケールされた画像を返します。filter および blur パラメタが省略された場合、単にピクセルデータを捨てたり複製したりする ことによってスケール操作が行われるので、処理結果は、特に計算機上で 合成した画像の場合にはおよそ完璧とはいえないものになります。

そうする代わりに、スケール操作後に画像を平滑化するために用いる フィルタを指定することができます。サポートされているフィルタの 形式は 'impulse'、'box'、 'triangle'、 'quadratic'、および 'gaussian' です。フィルタを 指定する場合、blur はオプションのパラメタで、フィルタの 不明瞭化度を指定します。標準の値は 1.0 です。

readscaled() は正しいアスペクト比をまったく維持しようと しないので、それはユーザの責任になります。

ttob( flag)
この関数は画像のスキャンラインの読み書きを下から上に向かって 行う (フラグがゼロの場合で、SGI GL 互換です) か、上から下に向かって 行う (フラグが 1 の場合で、X 互換です) かを決定する大域的なフラグを 設定します。標準の値はゼロです。

write( file, data, x, y, z)
この関数は data 中の RGB またはグレイスケールのデータ を画像ファイル file に書き込みます。x および y には画像のサイズを与え、z は 1 バイトグレイスケール画像 の場合には 1 で、RGB 画像の場合には 3 (4 バイトの値として記憶され、 下位 3 バイトが使われます) です。これらは gl.lrectread() が返すデータの形式です。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.10 GL Up: 20. SGI IRIX 特有のサービス Next: 20.12 jpeg


20.12 jpeg -- JPEGファイルの読み書きを行う

利用可能な条件: IRIX.

このjpegモジュールはIndependent JPEG Group (IJG) によって書かれたJEPG圧縮及び展開アルゴリズムを提供します。 JPEG形式は写真等の画像圧縮で標準的に利用され、ISO 10918で定義されてます。 JPEG、あるいはIndependent JPEG Groupソフトウェアの詳細は、 標準JPEG、若しくは提供されるソフトウェアのドキュメントを参照してください。

JPEGファイルを扱うポータブルなインタフェースはFredrik Lundhによる Python Imaging Library (PIL)があります。また、PILの情報は http://www.pythonware.com/products/pil/で見つけることができます。

モジュールjpegでは、一つの例外といくつかの関数を定義しています。

exception error
関数compress()またはdecompress()のエラーで 上げられる例外です。

compress( data, w, h, b)
イメージファイルの幅w、高さh、1ピクセルあたりのバイト数bを 引数として扱います。データはSGI GL順になっていて、 最初のピクセルは左下端になります。 また、これはgl.lrectread()が返す値をすぐにcompress()に かけるためです。現在は、1バイト若しくは4バイトのピクセルを 取り扱うことができます、前者はグレースケール、後者はRGBカラーを扱います。 compress()は、圧縮されたJFIF形式のイメージが 含まれた文字列を返します。

decompress( data)
データは圧縮されたJFIF形式のイメージが含まれた文字列で、 この関数はタプル(data, width, height, bytesperpixel)を返します。また、そのデータは gl.lrectwrite()を通過します。

setoption( name, value)
compress()とdecompress()を呼ぶための様々な オプションをセットします。次のオプションが利用できます:

オプション | 効果
'forcegray' | 入力がRGBでも強制的にグレースケールを出力します。
'quality' | 圧縮後イメージの品質を0から100の間の値で指定します (デフォルトは75です)。これは圧縮にのみ影響します。
'optimize' | ハフマンテーブルを最適化します。時間がかかりますが、高圧縮になります。 これは圧縮にのみ影響します。
'smooth' | 圧縮されていないイメージ上でインターブロックスムーシングを行います。 低品質イメージに役立ちます。これは展開にのみ影響します。

参考資料:

JPEG Still Image Data Compression Standard
The canonical reference for the JPEG image format, by Pennebaker and Mitchell.

Information Technology - Digital Compression and Coding of Continuous-tone Still Images - Requirements and Guidelines
The ISO standard for JPEG is also published as ITU T.81. This is available online in PDF form.

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.11 imgfile Up: 20. SGI IRIX 特有のサービス Next: 21. SunOS 特有のサービス


21. SunOS 特有のサービス

この章では、SunOSオペレーティングシステム バージョン4及び5(Solarisバージョン2)に固有の機能を解説します。

  • 21.1 sunaudiodev -- Sunオーディオハードウェアへのアクセス
    • 21.1.1 オーディオデバイスオブジェクト
  • 21.2 SUNAUDIODEV -- sunaudiodevで使われる定数
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 20.12 jpeg Up: Python ライブラリリファレンス Next: 21.1 sunaudiodev


21.1 sunaudiodev -- Sunオーディオハードウェアへのアクセス

利用可能な条件: SunOS.

このモジュールを使うと、Sunのオーディオインターフェースにアクセスでき ます。 Sunオーディオハードウェアは、 1秒あたり8kのサンプリングレート、 u-LAWフォーマットでオーディオデータを録音、再生できます。 完全な説明文書はマニュアルページaudio(7I)にあります。

モジュール SUNAUDIODEVには、このモジュールで使われる定数が定義されています。

このモジュールには、以下の変数と関数が定義されています：

exception error
この例外は、全てのエラーについて発生します。 引数は誤りを説明する文字列です。

open( mode)
この関数はオーディオデバイスを開き、Sunオーディオデバイスのオブジェクト を返します。 こうすることで、オブジェクトがI/Oに使用できるようになります。 パラメータmodeは次のうちのいずれか一つで、 録音のみには'r'、再生のみには'w'、 録音と再生両方には'rw'、コントロールデバイスへのアクセスには 'control'です。 レコーダーやプレーヤーには同時に１つのプロセスしかアクセスが許されていな いので、必要な動作についてだけデバイスをオープンするのがいい考えです。 詳しくはaudio(7I)を参照してください。 マニュアルページにあるように、このモジュールは環境変数 AUDIODEVの中のベースオーディオデバイスファイルネームを初めに参照 します。 見つからない場合は/dev/audioを参照します。 コントロールデバイスについては、ベースオーディオデバイスに``ctl''を 加えて扱われます。

  • 21.1.1 オーディオデバイスオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 21. SunOS 特有のサービス Up: 21. SunOS 特有のサービス Next: 21.1.1 オーディオデバイスオブジェクト


21.1.1 オーディオデバイスオブジェクト

オーディオデバイスオブジェクトはopen()で返され、このオブジェ クトには以下のメソッドが定義されています （controlオブジェクトは除きます。これにはgetinfo()、 setinfo()、fileno()、drain()だけが定義されて います）：

close( )
このメソッドはデバイスを明示的に閉じます。 オブジェクトを削除しても、それを参照しているものがあって、すぐに閉じてく れない場合に便利です。 閉じられたデバイスを使うことはできません。

fileno( )
デバイスに関連づけられたファイルディスクリプタを返します。 これは、後述のSIGPOLLの通知を組み立てるのに使われます。

drain( )
このメソッドは全ての出力中のプロセスが終了するまで待って、それから制御が 戻ります。 このメソッドの呼び出しはそう必要ではありません： オブジェクトを削除すると自動的にオーディオデバイスを閉じて、暗黙のうちに 吐き出します。

flush( )
このメソッドは全ての出力中のものを捨て去ります。 ユーザの停止命令に対する反応の遅れ（1秒までの音声のバッファリングによっ て起こります）を避けるのに使われます。

getinfo( )
このメソッドは入出力のボリューム値などの情報を引き出して、オーディオス テータスのオブジェクト形式で返します。 このオブジェクトには何もメソッドはありませんが、現在のデバイスの状態を示 す多くの属性が含まれます。 属性の名称と意味は<sun/audioio.h>とaudio(7I)に記載があ ります。 メンバー名は相当するCのものとは少し違っています： ステータスオブジェクトは１つの構造体です。 その中の構造体であるplayのメンバーには名前の初めに"o_"がつ いていて、recordには"i_"がついています。 そのため、Cのメンバーであるplay.sample_rateは o_sample_rateとして、record.gainはi_gainとして 参照され、 monitor_gainはそのままmonitor_gainで参照されます。

ibufcount( )
このメソッドは録音側でバッファリングされるサンプル数を返します。 つまり、プログラムは同じ大きさのサンプルに対するread()の 呼び出しをブロックしません。

obufcount( )
このメソッドは再生側でバッファリングされるサンプル数を返します。 残念ながら、この数値はブロックなしに書き込めるサンプル数を調べるのには 使えません。というのは、カーネルの出力キューの長さは可変だからです。

read( size)
このメソッドはオーディオ入力からsizeのサイズのサンプルを読み込ん で、Pythonの文字列として返します。 この関数は必要なデータが得られるまで他の操作をブロックします。

setinfo( status)
このメソッドはオーディオデバイスのステータスパラメータを設定します。 パラメータstatusはgetinfo()で返されたり、 プログラムで変更されたオーディオステータスオブジェクトです。

write( samples)
パラメータとしてオーディオサンプルをPython文字列を受け取り、再生します。 もし十分なバッファの空きがあればすぐに制御が戻り、そうでないならブロック されます。

オーディオデバイスはSIGPOLLを介して様々なイベントの非同期通知に対応して います。 Pythonでこれをどのようにしたらできるか、例を挙げます：

def handle_sigpoll(signum, frame):
    print 'I got a SIGPOLL update'

import fcntl, signal, STROPTS

signal.signal(signal.SIGPOLL, handle_sigpoll)
fcntl.ioctl(audio_obj.fileno(), STROPTS.I_SETSIG, STROPTS.S_MSG)

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 21.1 sunaudiodev Up: 21.1 sunaudiodev Next: 21.2 SUNAUDIODEV


21.2 SUNAUDIODEV -- sunaudiodevで使われる定数

利用可能な条件: SunOS.

これはsunaudiodevに付随する モジュールで、MIN_GAIN、MAX_GAIN、 SPEAKERなどの便利なシンボル定数を定義しています。 定数の名前はCのincludeファイル<sun/audioio.h>のものと同じで、 初めの文字列 "AUDIO_"を除いたものです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 21.1.1 オーディオデバイスオブジェクト Up: 21. SunOS 特有のサービス Next: 22. MS Windows 特有のサービス


22. MS Windows 特有のサービス

この章では、MS Windows プラットフォーム上でのみ利用可能な モジュール群について記述します。

msvcrt | MS VC++実行時システムの雑多な有用ルーチン群。
_winreg | Windows レジストリを操作するためのルーチンおよびオブジェクト。
winsound | Windows の音声再生機構へのアクセス。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 21.2 SUNAUDIODEV Up: Python ライブラリリファレンス Next: 22.1 msvcrt - MS


22.1 msvcrt - MS VC++実行時システムの有用なルーチン群

利用可能な条件: Windows.

このモジュールの関数は、 Windows プラットフォームの便利な機能の いくつかに対するアクセス機構を提供しています。高レベルモジュール のいくつかは、提供するサービスを Windows で実装するために、これらの 関数を使っています。例えば、 getpass モジュールは 関数 getpass() を実装するためにこのモジュールの関数を 使います。

ここに挙げた関数の詳細なドキュメントについては、プラットフォーム API ドキュメントで見つけることができます。

  • 22.1.1 ファイル操作関連
  • 22.1.2 コンソール I/O 関連
  • 22.1.3 その多の関数
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 22. MS Windows 特有のサービス Up: 22. MS Windows 特有のサービス Next: 22.1.1 ファイル操作関連


22.1.1 ファイル操作関連

locking( fd, mode, nbytes)
C 言語による実行時システムにおけるファイル記述子 fd に基づいて、 ファイルの一部にロックをかけます。ロックされるファイルの領域は、 現在のファイル位置から nbytes バイトで、ファイルの末端まで 延長することができます。mode は 以下に列挙する LK_* のいずれか一つでなければなりません。 一つのファイルの複数の領域を同時にロックすることは可能ですが、 領域が重複してはなりません。連接する領域をまとめて指定することは できません; それらの領域は個別にロック解除しなければなりません。

LK_LOCK
LK_RLCK
指定されたバイト列にロックをかけます。指定領域がロックできなかった 場合、プログラムは 1 秒後に再度ロックを試みます。10 回 再試行した後でもロックをかけられない場合、IOError が送出されます。

LK_NBLCK
LK_NBRLCK
指定されたバイト列にロックをかけます。指定領域がロックできなかった 場合、IOError が送出されます。

LK_UNLCK
指定されたバイト列のロックを解除します。指定領域はあらかじめロック されていなければなりません。

setmode( fd, flags)
ファイル記述子 fd に対して、行末文字の変換モードを設定します。 テキストモードに設定するには、flags を os.O_TEXT にします; バイナリモードにするには os.O_BINARY にします。

open_osfhandle( handle, flags)
C 言語による実行時システムにおけるファイル記述子をファイルハンドル handle から生成します。flags パラメタは os.O_APPEND、 os.O_RDONLY、および os.O_TEXT をビット単位で OR したものになります。 返されるファイル記述子は os.fdopen() でファイルオブジェクト を生成するために使うことができます。

get_osfhandle( fd)
ファイル記述子 fd のファイルハンドルを返します。fd が認識できない場合、 IOError を送出します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 22.1 msvcrt - MS Up: 22.1 msvcrt - MS Next: 22.1.2 コンソール I/O 関連


22.1.2 コンソール I/O 関連

kbhit( )
読み出し待ちの打鍵イベントが存在する場合に真を返します。

getch( )
打鍵を読み取り、読み出された文字を返します。コンソールには 何もエコーバックされません。この関数呼び出しは読み出し可能な 打鍵がない場合にはブロックしますが、文字を読み出せるように するために Enter の打鍵を待つ必要はありません。 打鍵されたキーが特殊機能キー (function key) である場合、この 関数は '\000' または '\xe0' を返します; キーコードは次に関数を呼び出した際に返されます。この関数で Control-C の打鍵を読み出すことはできません。

getche( )
getch() に似ていますが、打鍵した字が印字可能な文字の 場合エコーバックされます。

putch( char)
キャラクタ char をバッファリングを行わないでコンソールに 出力します。

ungetch( char)
キャラクタ char をコンソールバッファに ``押し戻し (push back)'' ます; これにより、押し戻された 文字は getch() や getche() で次に 読み出される文字になります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 22.1.1 ファイル操作関連 Up: 22.1 msvcrt - MS Next: 22.1.3 その多の関数


22.1.3 その多の関数

heapmin( )
malloc() されたヒープ領域を強制的に消去させて、未使用の メモリブロックをオペレーティングシステムに返します。この関数は Windows NT 上でのみ動作します。失敗した場合、 IOError を送出します。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 22.1.2 コンソール I/O 関連 Up: 22.1 msvcrt - MS Next: 22.2 _winreg - Windows


22.2 _winreg - Windows レジストリへのアクセス

利用可能な条件: Windows.

バージョン2.0 以降で新規追加された 仕様です。

これらの関数は Windows レジストリ API を Python で使えるようにします。 プログラマがレジストリハンドルのクローズを失念した場合でも、確実に ハンドルがクローズされるようにするために、整数値をレジストリハンドル として使う代わりにハンドルオブジェクトが使われます。

このモジュールは Windows レジストリ操作のための非常に低レベルの インタフェースを使えるようにします; 将来、より高レベルの レジストリ API インタフェースを提供するような、新たな winreg モジュールが作られるよう期待します。

このモジュールでは以下の関数を提供します:

CloseKey( hkey)
以前開かれたレジストリキーを閉じます。 hkey 引数には以前開かれたレジストリキーを特定します。

このメソッド (または handle.Close()) を使って hkey が 閉じられなかった場合、Python が hkey オブジェクトを破壊 する際に閉じられるので注意してください。

ConnectRegistry( computer_name, key)
他の計算機上にある既定のレジストリハンドル接続を確立し、 ハンドルオブジェクト (handle object) を返します。

computer_name はリモートコンピュータの名前で、 r"\\computername" の形式をとります。None の場合、ローカルの計算機が使われます。

key は接続したい既定のハンドルです。

戻り値は開かれたキーのハンドルです。 関数が失敗した場合、EnvironmentError 例外が 送出されます。

CreateKey( key, sub_key)
特定のキーを生成するか開き、ハンドルオブジェクト を返します。

key はすでに開かれたキーか、既定の HKEY_* 定数の うちの一つです。

sub_key はこのメソッドが開く、または新規作成するキーの 名前です。

key が既定のキーの一つなら、sub_key は None でかまいません。この場合、返されるハンドルは関数に渡されたのと 同じキーハンドルです。

キーがすでに存在する場合、この関数は既に存在するキーを開きます。

戻り値は開かれたキーのハンドルです。この関数が失敗した場合、 EnvironmentError 例外が送出されます。

DeleteKey( key, sub_key)
特定のキーを削除します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は文字列で、key パラメタによって特定された キーのサブキーでなければなりません。この値は None で あってはならず、キーはサブキーを持っていてはなりません。

このメソッドはサブキーをもつキーを削除することはできません。

このメソッドの実行が成功すると、キー全体が、その値すべてを含めて 削除されます。このメソッドが失敗した場合、 EnvironmentError 例外が送出されます。

DeleteValue( key, value)
レジストリキーから指定された名前つきの値を削除します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つでなければなりません。

value は削除したい値を指定するための文字列です。

EnumKey( key, index)
開かれているレジストリキーのサブキーを列挙し、文字列で返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つでなければなりません。

index は整数値で、取得するキーのインデクスを特定します。

この関数は呼び出されるたびに一つのサブキーの名前を取得します。 この関数は通常、これ以上サブキーがないことを示す EnvironmentError 例外が送出されるまで繰り返し呼び 出されます。

EnumValue( key, index)
開かれているレジストリキーの値を列挙し、タプルで返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つでなければなりません。

index は整数値で、取得する値のインデクスを特定します。

この関数は呼び出されるたびに一つの値の名前を取得します。 この関数は通常、これ以上値がないことを示す EnvironmentError 例外が送出されるまで繰り返し呼び 出されます。

結果は 3 要素のタプルになります:

Index | Meaning
0 | 値の名前を特定する文字列
1 | 値のデータを保持するためのオブジェクトで、その型は背後の レジストリ型に依存します
2 | 値のデータ型を特定する整数です

FlushKey( key)

キーのすべての属性をレジストリに書き込みます。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つでなければなりません。

キーを変更するために RegFlushKey を呼ぶ必要はありません。 レジストリの変更は怠惰なフラッシュ機構 (lazy flusher) を使って フラッシュされます。また、システムの遮断時にもディスクにフラッシュ されます。CloseKey() と違って、FlushKey() メソッドはレジストリに全てのデータを書き終えたときにのみ返ります。 アプリケーションは、レジストリへの変更を絶対に確実にディスク上に 反映させる必要がある場合にのみ、FlushKey() を呼ぶべきです。

FlushKey() を呼び出す必要があるかどうか分からない場合、 おそらくその必要はありません。

RegLoadKey( key, sub_key, file_name)
指定されたキーの下にサブキーを生成し、サブキーに指定されたファイル のレジストリ情報を記録します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は記録先のサブキーを指定する文字列です。

file_name はレジストリデータを読み出すためのファイル名です。 このファイルは SaveKey() 関数で生成されたファイルでなくては なりません。ファイル割り当てテーブル (FAT) ファイルシステム下では、 ファイル名は拡張子を持っていてはなりません。

この関数を呼び出しているプロセスが SE_RESTORE_PRIVILEGE 特権を持たない場合には LoadKey() は失敗します。 この特権はファイル許可とは違うので注意してください - 詳細は Win32 ドキュメンテーションを参照してください。

key が ConnectRegistry() によって返されたハンドル の場合、fileName に指定されたパスは遠隔計算機に対する相対パス 名になります。

Win32 ドキュメンテーションでは、key は HKEY_USER または HKEY_LOCAL_MACHINE ツリー内になければならない とされています。これは正しいかもしれないし、そうでないかもしれません。

OpenKey( key, sub_key[, res = 0][, sam = KEY_READ])
指定されたキーを開き、ハンドルオブジェクト を返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は開きたいサブキーを特定する文字列です。

res 予約されている整数値で、ゼロでなくてはなりません。 標準の値はゼロです。

sam は必要なキーへのセキュリティアクセスを記述する、 アクセスマスクを指定する整数です。標準の値は KEY_READ です。

指定されたキーへの新しいハンドルが返されます。

この関数が失敗すると 、EnvironmentError が送出されます。

OpenKeyEx( )
OpenKeyEx() の機能は OpenKey() を標準の引数で使うことで提供されています。

QueryInfoKey( key)
キーに関数情報をタプルとして返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

結果は以下の 3 要素からなるタプルです:

インデクス | 意味
0 | このキーが持つサブキーの数を表す整数。
1 | このキーが持つ値の数を表す整数。
2 | 最後のキーの変更が (あれば) いつだったかを表す長整数で、 1600 年 1 月 1 日からの 100 ナノ秒単位で数えたもの。

QueryValue( key, sub_key)
キーに対する、名前付けられていない値を文字列で取得します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は値が関連付けられているサブキーの名前を保持する文字列 です。この引数が None または空文字列の場合、この関数は key で特定されるキーに対して SetValue() メソッドで 設定された値を取得します。

レジストリ中の値は名前、型、およびデータから構成されています。 このメソッドはあるキーのデータ中で、名前 NULL をもつ最初の値を取得します。 しかし背後の API 呼び出しは型情報を返しません。非常に、非常に、非常に 不完全な実装です。この関数を使うべきではありません！！！

QueryValueEx( key, value_name)
開かれたレジストリキーに関連付けられている、指定した名前の値に対して、 型およびデータを取得します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

value_name は要求する値を指定する文字列です。

結果は 2 つの要素からなるタプルです:

インデクス | 意味
0 | レジストリ要素の名前。
1 | この値のレジストリ型を表す整数。

SaveKey( key, file_name)
指定されたキーと、そのサブキー全てを指定したファイルに保存します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

file_name はレジストリデータを保存するファイルの名前です、 このファイルはすでに存在していてはいけません。このファイル名が 拡張子を含んでいる場合、LoadKey()、 ReplaceKey() または RestoreKey() メソッドは、ファイル割り当てテーブル (FAT) 型ファイルシステムを使うことができません。

key が遠隔の計算機上にあるキーを表す場合、file_name で記述されているパスは遠隔の計算機に対して相対的なパスになります。 このメソッドの呼び出し側は SeBackupPrivilege セキュリティ特権を保有していなければなりません。この特権は ファイルパーミッションとは異なります - 詳細は Win32 ドキュメンテーションを参照してください。

この関数は security_attributes を NULL にして API に渡します。

SetValue( key, sub_key, type, value)
値を指定したキーに関連付けます。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は値が関連付けられているサブキーの名前を表す文字列です。

type はデータの型を指定する整数です。現状では、この値は REG_SZ でなければならず、これは文字列だけが サポートされていることを示します。他のデータ型をサポートするには SetValueEx() を使ってください。

value は新たな値を指定する文字列です。

sub_key 引数で指定されたキーが存在しなければ、 SetValue 関数で生成されます。

値の長さは利用可能なメモリによって制限されます。(2048 バイト以上の) 長い値はファイルに保存して、そのファイル名を設定レジストリに保存 するべきです。そうすればレジストリを効率的に動作させる役に立ちます。

key 引数に指定されたキーは KEY_SET_VALUE アクセスで開かれていなければなりません。

SetValueEx( key, value_name, reserved, type, value)
開かれたレジストリキーの値フィールドにデータを記録します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は値が関連付けられているサブキーの名前を表す文字列です。

type はデータの型を指定する整数です。 値はこのモジュールで定義されている以下の定数のうちの一つでなければ なりません:

定数 | 意味
REG_BINARY | 何らかの形式のバイナリデータ。
REG_DWORD | 32 ビットの数。
REG_DWORD_LITTLE_ENDIAN | 32 ビットのリトルエンディアン形式の数。
REG_DWORD_BIG_ENDIAN | 32 ビットのビッグエンディアン形式の数。
REG_EXPAND_SZ | 環境変数を参照している、ヌル文字で終端された文字列。 ("%PATH%")。
REG_LINK | Unicode のシンボリックリンク。
REG_MULTI_SZ | ヌル文字で終端された文字列からなり、二つのヌル文字で終端されている配列 (Python はこの終端の処理を自動的に行います)。
REG_NONE | 定義されていない値の形式。
REG_RESOURCE_LIST | デバイスドライバリソースのリスト。
REG_SZ | ヌルで終端された文字列。

reserved は何もしません - API には常にゼロが渡されます。

value は新たな値を指定する文字列です。

このメソッドではまた、指定されたキーに対して、さらに別の値や型情報を 設定することができます。key 引数で指定されたキーは KEY_SET_VALUE アクセスで開かれていなければなりません。

キーを開くには、 CreateKeyEx() または OpenKey() メソッドを使ってください。

値の長さは利用可能なメモリによって制限されます。(2048 バイト以上の) 長い値はファイルに保存して、そのファイル名を設定レジストリに保存 するべきです。そうすればレジストリを効率的に動作させる役に立ちます。

  • 22.2.1 レジストリハンドルオブジェクト
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 22.1.3 その多の関数 Up: 22. MS Windows 特有のサービス Next: 22.2.1 レジストリハンドルオブジェクト


22.2.1 レジストリハンドルオブジェクト

このオブジェクトは Windows の HKEY オブジェクトをラップし、 オブジェクトが破壊されたときに自動的にハンドルを閉じます。 オブジェクトの Close() メソッドと CloseKey() 関数 のどちらも、後始末がきちんと行われることを保証するために呼び出す ことができます。

このモジュールのレジストリ関数は全て、これらのハンドル オブジェクトの一つを返します。

このモジュールのレジストリ関数でハンドルオブジェクトを受理する ものは全て整数も受理しますが、ハンドルオブジェクトを利用する ことを推奨します。

ハンドルオブジェクトは __nonzero__() の意味構成を持ちます - すなわち、

    if handle:
        print "Yes"
は、ハンドルが現在有効な (閉じられたり切り離されたりしていない) 場合 には Yes となります。

ハンドルオブジェクトはまた、比較の意味構成もサポートしています。 このため、背後の Windows ハンドル値が同じものを複数のハンドルオブジェクト が参照している場合、それらの比較は真になります。

ハンドルオブジェクトは (例えば組み込みの int() 関数を 使って) 整数に変換することができます。この場合、背後の Windows ハンドル値が返されます、また、 Detach() 目祖度 を使って整数のハンドル値を返させると同時に、ハンドルオブジェクト から Windows ハンドルを切り離すこともできます。

Close( )
背後の Windows ハンドルを閉じます。

ハンドルがすでに閉じられていてもエラーは送出されません。

Detach( )
ハンドルオブジェクトから Windows ハンドルを切り離します。

切り離される以前にそのハンドルを保持していた整数 (または 64 ビット Windows の場合には長整数) オブジェクトが返されます。 ハンドルがすでに切り離されていたり閉じられていたりした場合、 ゼロが返されます。

この関数を呼び出した後、ハンドルは確実に無効化されますが、 閉じられるわけではありません。背後の Win32 ハンドルがハンドル オブジェクトよりも長く維持される必要がある場合にはこの 関数を呼び出すとよいでしょう。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 22.2 _winreg - Windows Up: 22.2 _winreg - Windows Next: 22.3 winsound


22.3 winsound -- Windows 用の音声再生インタフェース

利用可能な条件: Windows.

バージョン1.5.2 以降で新規追加された 仕様です。

winsound モジュールは Windows プラットフォーム上で提供されて いる基本的な音声再生機構へのアクセス手段を提供します。このモジュールでは 2 つの関数といくつかの定数が定義されています。

Beep( frequency, duration)
PC のスピーカを鳴らします。 引数 frequency は鳴らす音の周波数の指定で、単位は Hz です。 値は 37 から 32.767 でなくてはなりません。 引数 duration は音を何ミリ秒鳴らすかの指定です。 システムがスピーカを鳴らすことができない場合、例外 RuntimeError が送出されます。 注意: Windows 95 および 98 では、Windows の関数 Beep() は存在しますが役に立ちません (この関数は引数を無視します)。これらの ケースでは、Python はポートを直接操作して Beep() をシミュレートします (バージョン 2.1 で追加されました) 。この機能が 全てのシステムで動作するかどうかはわかりません。 バージョン1.6 以降で新規追加された 仕様です。

PlaySound( sound, flags)
プラットフォームの API から関数 PlaySound() を呼び出します。 引数 sound はファイル名、音声データの文字列、または None をとり得ます。sound の解釈は flags の値に依存します。この値は 以下に述べる定数をビット単位で OR して組み合わせたものになります。 システムのエラーが発生した場合、例外 RuntimeError が送出されます。

MessageBeep( [type=MB_OK])
根底にある MessageBeep() 関数をプラットフォームの API から 呼び出します。この関数は音声をレジストリの指定に従って再生します。 type 引数はどの音声を再生するかを指定します; とり得る値は -1 、 MB_ICONASTERISK 、 MB_ICONEXCLAMATION 、 MB_ICONHAND 、 MB_ICONQUESTION 、および MB_OK で、 全て以下に記述されています。 値 -1 は ``単純なビープ音'' を再生します; この値は他の場合で音声を再生することができなかった 際の最終的な代替音です。 バージョン2.3 以降で新規追加された 仕様です。

SND_FILENAME
sound パラメタが WAV ファイル名であることを示します。 SND_ALIAS と同時に使ってはいけません。

SND_ALIAS
引数 sound はレジストリにある音声データに関連付けられた名前で あることを示します。指定した名前がレジストリ上にない場合、定数 SND_NODEFAULT が同時に指定されていない限り、システム標準の 音声データが再生されます。標準の音声データが登録されていない場合、 例外 RuntimeError が送出されます。 SND_FILENAME と同時に使ってはいけません。

全ての Win32 システムは少なくとも以下の名前をサポートします; ほとんどの システムでは他に多数あります:

PlaySound() name | 対応するコントロールパネルでの音声名
'SystemAsterisk' | Asterisk
'SystemExclamation' | Exclamation
'SystemExit' | Exit Windows
'SystemHand' | Critical Stop
'SystemQuestion' | Question

例えば以下のように使います:

import winsound
# Play Windows exit sound.
winsound.PlaySound("SystemExit", winsound.SND_ALIAS)

# Probably play Windows default sound, if any is registered (because
# "*" probably isn't the registered name of any sound).
winsound.PlaySound("*", winsound.SND_ALIAS)

SND_LOOP
音声データを繰り返し再生します。システムがブロックしないようにするため、 SND_ASYNC フラグを同時に使わなくてはなりません。 SND_MEMORY と同時に使うことはできません。

SND_MEMORY
PlaySound() の引数 sound が文字列の形式をとった WAV ファイルのメモリ上のイメージであることを示します。 注意: このモジュールはメモリ上のイメージを非同期に再生する機能をサポート していません。従って、このフラグと SND_ASYNC を組み合わせると 例外 RuntimeError が送出されます。

SND_PURGE
指定した音声の全てのインスタンスについて再生処理を停止します。

SND_ASYNC
音声を非同期に再生するようにして、関数呼び出しを即座に返します。

SND_NODEFAULT
指定した音声が見つからなかった場合にシステム標準の音声を鳴らさないように します。

SND_NOSTOP
現在鳴っている音声を中断させないようにします。

SND_NOWAIT
サウンドドライバがビジー状態にある場合、関数がすぐ返るようにします。

MB_ICONASTERISK
音声 SystemDefault を再生します。

MB_ICONEXCLAMATION
音声 SystemExclamation を再生します。

MB_ICONHAND
音声 SystemHand を再生します。

MB_ICONQUESTION
音声 SystemQuestion を再生します。

MB_OK
音声 SystemDefault を再生します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 22.2.1 レジストリハンドルオブジェクト Up: 22. MS Windows 特有のサービス Next: A. ドキュメント化されていないモジュール


A. ドキュメント化されていないモジュール

現在ドキュメント化されていないが、ドキュメント化すべきモジュールを 以下にざっと列挙します。どうぞこれらのドキュメントを寄稿してください！ (電子メールで docs@python.org に送ってください)。

この章のアイデアと元の文章内容は Fredrik Lundh のポストによる ものです; この章の特定の内容は実際には改訂されてきています。

  • A.1 フレームワーク
  • A.2 雑多な有用ユーティリティ
  • A.3 プラットフォーム特有のモジュール
  • A.4 マルチメディア関連
  • A.5 撤廃されたもの
  • A.6 SGI 特有の拡張モジュール
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 22.3 winsound Up: Python ライブラリリファレンス Next: A.1 フレームワーク


A.1 フレームワーク

フレームワークは記述するのが難しくなりがちですが、そうする価値は あります。

test
-- 回帰テストフレームワークです。Python 本体の回帰テストのためのもの ですが、他の Python ライブラリに対しても有用です。単一のモジュールと いうよりはパッケージです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: A. ドキュメント化されていないモジュール Up: A. ドキュメント化されていないモジュール Next: A.2 雑多な有用ユーティリティ


A.2 雑多な有用ユーティリティ

以下のいくつかは非常に古く、かつ／またはあまり頑健ではありません。 ``hmm.'' マーク付きです。

bdb
-- 汎用の Python デバッガ基底クラスです (pdb で使われています)。

ihooks
-- import フックのサポートです (rexec のためのものです; 撤廃されるかもしれません)。

platform
-- このモジュールでは、プラットフォームを識別するためのデータを 可能な限り多く取得しようとします。これにより、関数 API を介して 情報を取得できるようにします。 コマンドラインから呼び出された場合、このモジュールはプラットフォーム 情報を一つの文字列に繋げて sys.stdout に出力します。 出力形式はファイル名の一部として使うことができます。 バージョン2.3 以降で新規追加された 仕様です。

smtpd
-- RFC 821 に適合するための最低限の要求を満たした SMTP デーモン実装 です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: A.1 フレームワーク Up: A. ドキュメント化されていないモジュール Next: A.3 プラットフォーム特有のモジュール


A.3 プラットフォーム特有のモジュール

これらのモジュールは os.path モジュールを実装するために 用いられていますが、ここで触れる内容を超えてドキュメントされていません。 これらはもう少しドキュメント化する必要があります。

ntpath
-- Win32、 Win64、 WinCE、 および OS/2 プラットフォームにおける os.path 実装です。

posixpath
-- POSIXにおける os.path 実装です。

bsddb185
-- まだBerkeleyDB 1.85を使用しているシステムで後方互換性を保つためのモ ジュール。通常、特定のBSD Unixベースのシステムでのみ利用可能。直接使用し ないで下さい。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: A.2 雑多な有用ユーティリティ Up: A. ドキュメント化されていないモジュール Next: A.4 マルチメディア関連


A.4 マルチメディア関連

audiodev
-- 音声データを再生するためのプラットフォーム非依存の API です。

linuxaudiodev
-- Linux 音声デバイスで音声データを再生します。Python 2.3 では ossaudiodev モジュールと置き換えられました。

sunaudio
-- Sun 音声データヘッダを解釈します (撤廃されるか、ツール/デモに なるかもしれません)。

toaiff
-- "任意の" 音声ファイルを AIFF ファイルに変換します; おそらく ツールかデモになるはずです。外部プログラム sox が必要です。

ossaudiodev
-- Open Sound System API を介して音声データを再生します。 このモジュールは Linux、いくつかの BSD 系、およびいくつかの 商用 Unix プラットフォームで利用できます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: A.3 プラットフォーム特有のモジュール Up: A. ドキュメント化されていないモジュール Next: A.5 撤廃されたもの


A.5 撤廃されたもの

これらのモジュールは通常 import して利用できません; 利用できるように するには作業を行わなければなりません。

Python で書かれたものは、標準ライブラリの一部としてインストール されている lib-old/ ディレクトリの中にインストールされます。 利用するには、PYTHONPATH を使うなどして、lib-old/ ディレクトリを sys.path に追加しなければなりません。

撤廃された拡張モジュールのうち C で書かれたものは、標準の設定では ビルドされません。Unixでこれらのモジュールを有効にするには、 ビルドツリー内の Modules/Setup の適切な行のコメントアウトを 外して、モジュールを静的リンクするなら Python をビルドしなおし、 動的にロードされる拡張を使うなら共有オブジェクトをビルドして インストールする必要があります。

addpack
-- パッケージへの別のアプローチです。組み込みのパッケージサポートを 使ってください。

cmp
-- ファイル比較関数です。新しい filecmp を使ってください。

cmpcache
-- 古い cmp モジュールのキャッシュ化版です。filecmp を使ってください。

codehack
-- 関数コードオブジェクトからか数名や行番号を抽出します (現在ではこれらは属性: co.co_name, func.func_name, co.co_firstlineno としてアクセスできます)。

dircmp
-- ディレクトリ間の差分 (diff) ツールを構築するためのクラスです (デモかツールになるかもしれません)。
リリース 2.0 以降で撤廃された仕様です。 filecmp モジュールが dircmp に置き換わります。

dump
-- 変数を再構築する Python コードを出力します。

fmt
-- テキスト書式化処理の抽象化モジュールです (低速すぎます)。

lockfile
-- FCNTL ファイルロック機構へのラッパです (fcntl.lockf()/flock() を使ってください。; fcntl を参照してください)。

newdir
-- 新たな dir() 関数です。 (現在では標準の dir() が同じくらい改良されました)。

Para
-- fmt の補助モジュールです。

poly
-- 多項式です。

regex
-- Emacs 形式の正規表現サポートです; 古いコード内で未だに使われている かもしれません (拡張モジュールです) 。ドキュメントは Python 1.6 Documentation を参照してください。

regsub
-- regex で利用するための、正規表現に基づいた文字列置換 ユーティリティです (拡張モジュールです)。ドキュメントは Python 1.6 Documentation を参照してください。

tb
-- 局所変数のダンプを伴うトレースバック印字のためのモジュールです (pdb.pm() または traceback を使ってください)。

timing
-- 高い精度で経過時間を計測します (time.clock() を使って ください)。 (拡張モジュールです。)

tzparse
-- タイムゾーン指定を解釈します (完成していません; 将来は 消滅するモジュールで、TZ 環境変数が設定されていないと 動作しません)。

util
-- 他のどこにも分類しようがない有用な関数群です。

whatsound
-- 音声ファイルを識別します; sndhdr を使ってください。

zmod
-- 数学的な ``体'' の性質を計算します。

以下のモジュールは撤廃されましたが、ツールやスクリプトとして 復活しているようです:

find
-- ディレクトリツリー内からパターンに合致するファイルを探します。

grep
-- Python による grep 実装です。

packmail
-- 自己展開形式の Unix シェルアーカイブを生成します。

以下のモジュールはこのマニュアルの以前のバージョンでドキュメント されていましたが、現在では撤廃されたものと考えられています。 これらのドキュメントのソースは、まだドキュメントソースアーカイブ から取得可能です。

ni
-- ``パッケージ内の'' モジュールを import します。今では基本的なパッケージ のサポートは組み込みになっています。組み込みのサポートはこのモジュールで 提供されていた内容に非常に近いものとなっています。

rand
-- 乱数生成器への古いインタフェースです。

soundex
-- 共有キーと同じような名前縮約アルゴリズムです。特定のアルゴリズムは 公開されているどのアルゴリズムとも一致しないようです。 (拡張モジュールです。)

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: A.4 マルチメディア関連 Up: A. ドキュメント化されていないモジュール Next: A.6 SGI 特有の拡張モジュール


A.6 SGI 特有の拡張モジュール

以下は SGI 特有のモジュールで、現在のバージョンの SGI の実情が 反映されていないかもしれません。

cl
-- SGI 圧縮ライブラリへのインタフェースです。

sv
-- SGI Indigo 上の ``simple video'' ボード(旧式のハードウェアです) へのインタフェースです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: A.5 撤廃されたもの Up: A. ドキュメント化されていないモジュール Next: B. バグ報告


B. バグ報告

Python is a mature programming language which has established a reputation for stability. In order to maintain this reputation, the developers would like to know of any deficiencies you find in Python or its documentation.

Before submitting a report, you will be required to log into SourceForge; this will make it possible for the developers to contact you for additional information if needed. It is not possible to submit a bug report anonymously.

All bug reports should be submitted via the Python Bug Tracker on SourceForge (http://sourceforge.net/bugs/?group_id=5470). The bug tracker offers a Web form which allows pertinent information to be entered and submitted to the developers.

The first step in filing a report is to determine whether the problem has already been reported. The advantage in doing so, aside from saving the developers time, is that you learn what has been done to fix it; it may be that the problem has already been fixed for the next release, or additional information is needed (in which case you are welcome to provide it if you can!). To do this, search the bug database using the search box near the bottom of the page.

If the problem you're reporting is not already in the bug tracker, go back to the Python Bug Tracker (http://sourceforge.net/bugs/?group_id=5470). Select the ``Submit a Bug'' link at the top of the page to open the bug reporting form.

The submission form has a number of fields. The only fields that are required are the ``Summary'' and ``Details'' fields. For the summary, enter a very short description of the problem; less than ten words is good. In the Details field, describe the problem in detail, including what you expected to happen and what did happen. Be sure to include the version of Python you used, whether any extension modules were involved, and what hardware and software platform you were using (including version information as appropriate).

The only other field that you may want to set is the ``Category'' field, which allows you to place the bug report into a broad category (such as ``Documentation'' or ``Library'').

Each bug report will be assigned to a developer who will determine what needs to be done to correct the problem. You will receive an update each time action is taken on the bug.

参考資料:

How to Report Bugs Effectively
Article which goes into some detail about how to create a useful bug report. This describes what kind of information is useful and why it is useful.

Bug Writing Guidelines
Information about writing a good bug report. Some of this is specific to the Mozilla project, but describes general good practices.

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: A.6 SGI 特有の拡張モジュール Up: Python ライブラリリファレンス Next: C. 歴史とライセンス


C. 歴史とライセンス

  • C.1 History of the software
  • C.2 Terms and conditions for accessing or otherwise using Python
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: B. バグ報告 Up: Python ライブラリリファレンス Next: C.1 History of the


C.1 History of the software

Python was created in the early 1990s by Guido van Rossum at Stichting Mathematisch Centrum (CWI, see http://www.cwi.nl/) in the Netherlands as a successor of a language called ABC. Guido remains Python's principal author, although it includes many contributions from others.

In 1995, Guido continued his work on Python at the Corporation for National Research Initiatives (CNRI, see http://www.cnri.reston.va.us/) in Reston, Virginia where he released several versions of the software.

In May 2000, Guido and the Python core development team moved to BeOpen.com to form the BeOpen PythonLabs team. In October of the same year, the PythonLabs team moved to Digital Creations (now Zope Corporation; see http://www.zope.com/). In 2001, the Python Software Foundation (PSF, see http://www.python.org/psf/) was formed, a non-profit organization created specifically to own Python-related Intellectual Property. Zope Corporation is a sponsoring member of the PSF.

All Python releases are Open Source (see http://www.opensource.org/ for the Open Source Definition). Historically, most, but not all, Python releases have also been GPL-compatible; the table below summarizes the various releases.

Release | Derived from | Year | Owner | GPL compatible?
0.9.0 thru 1.2 | n/a | 1991-1995 | CWI | yes
1.3 thru 1.5.2 | 1.2 | 1995-1999 | CNRI | yes
1.6 | 1.5.2 | 2000 | CNRI | no
2.0 | 1.6 | 2000 | BeOpen.com | no
1.6.1 | 1.6 | 2001 | CNRI | no
2.1 | 2.0+1.6.1 | 2001 | PSF | no
2.0.1 | 2.0+1.6.1 | 2001 | PSF | yes
2.1.1 | 2.1+2.0.1 | 2001 | PSF | yes
2.2 | 2.1.1 | 2001 | PSF | yes
2.1.2 | 2.1.1 | 2002 | PSF | yes
2.1.3 | 2.1.2 | 2002 | PSF | yes
2.2.1 | 2.2 | 2002 | PSF | yes
2.2.2 | 2.2.1 | 2002 | PSF | yes
2.2.3 | 2.2.2 | 2002-2003 | PSF | yes
2.3 | 2.2.2 | 2002-2003 | PSF | yes
2.3.1 | 2.3 | 2002-2003 | PSF | yes
2.3.2 | 2.3.1 | 2003 | PSF | yes

注意: GPL-compatible doesn't mean that we're distributing Python under the GPL. All Python licenses, unlike the GPL, let you distribute a modified version without making your changes open source. The GPL-compatible licenses make it possible to combine Python with other software that is released under the GPL; the others don't.

Thanks to the many outside volunteers who have worked under Guido's direction to make these releases possible.

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: C. 歴史とライセンス Up: C. 歴史とライセンス Next: C.2 Terms and conditions


C.2 Terms and conditions for accessing or otherwise using Python

PSF LICENSE AGREEMENT FOR PYTHON 2.3.3

  1. This LICENSE AGREEMENT is between the Python Software Foundation (``PSF''), and the Individual or Organization (``Licensee'') accessing and otherwise using Python 2.3.3 software in source or binary form and its associated documentation.

  2. Subject to the terms and conditions of this License Agreement, PSF hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python 2.3.3 alone or in any derivative version, provided, however, that PSF's License Agreement and PSF's notice of copyright, i.e., ``Copyright © 2001-2003 Python Software Foundation; All Rights Reserved'' are retained in Python 2.3.3 alone or in any derivative version prepared by Licensee.

  3. In the event Licensee prepares a derivative work that is based on or incorporates Python 2.3.3 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python 2.3.3.

  4. PSF is making Python 2.3.3 available to Licensee on an ``AS IS'' basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.3.3 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 2.3.3 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 2.3.3, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between PSF and Licensee. This License Agreement does not grant permission to use PSF trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party.

  8. By copying, installing or otherwise using Python 2.3.3, Licensee agrees to be bound by the terms and conditions of this License Agreement.

BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0

BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1

  1. This LICENSE AGREEMENT is between BeOpen.com (``BeOpen''), having an office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization (``Licensee'') accessing and otherwise using this software in source or binary form and its associated documentation (``the Software'').

  2. Subject to the terms and conditions of this BeOpen Python License Agreement, BeOpen hereby grants Licensee a non-exclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use the Software alone or in any derivative version, provided, however, that the BeOpen Python License is retained in the Software, alone or in any derivative version prepared by Licensee.

  3. BeOpen is making the Software available to Licensee on an ``AS IS'' basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  5. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  6. This License Agreement shall be governed by and interpreted in all respects by the law of the State of California, excluding conflict of law provisions. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between BeOpen and Licensee. This License Agreement does not grant permission to use BeOpen trademarks or trade names in a trademark sense to endorse or promote products or services of Licensee, or any third party. As an exception, the ``BeOpen Python'' logos available at http://www.pythonlabs.com/logos.html may be used according to the permissions granted on that web page.

  7. By copying, installing or otherwise using the software, Licensee agrees to be bound by the terms and conditions of this License Agreement.

CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1

  1. This LICENSE AGREEMENT is between the Corporation for National Research Initiatives, having an office at 1895 Preston White Drive, Reston, VA 20191 (``CNRI''), and the Individual or Organization (``Licensee'') accessing and otherwise using Python 1.6.1 software in source or binary form and its associated documentation.

  2. Subject to the terms and conditions of this License Agreement, CNRI hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python 1.6.1 alone or in any derivative version, provided, however, that CNRI's License Agreement and CNRI's notice of copyright, i.e., ``Copyright © 1995-2001 Corporation for National Research Initiatives; All Rights Reserved'' are retained in Python 1.6.1 alone or in any derivative version prepared by Licensee. Alternately, in lieu of CNRI's License Agreement, Licensee may substitute the following text (omitting the quotes): ``Python 1.6.1 is made available subject to the terms and conditions in CNRI's License Agreement. This Agreement together with Python 1.6.1 may be located on the Internet using the following unique, persistent identifier (known as a handle): 1895.22/1013. This Agreement may also be obtained from a proxy server on the Internet using the following URL: http://hdl.handle.net/1895.22/1013.''

  3. In the event Licensee prepares a derivative work that is based on or incorporates Python 1.6.1 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python 1.6.1.

  4. CNRI is making Python 1.6.1 available to Licensee on an ``AS IS'' basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  7. This License Agreement shall be governed by the federal intellectual property law of the United States, including without limitation the federal copyright law, and, to the extent such U.S. federal law does not apply, by the law of the Commonwealth of Virginia, excluding Virginia's conflict of law provisions. Notwithstanding the foregoing, with regard to derivative works based on Python 1.6.1 that incorporate non-separable material that was previously distributed under the GNU General Public License (GPL), the law of the Commonwealth of Virginia shall govern this License Agreement only as to issues arising under or with respect to Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between CNRI and Licensee. This License Agreement does not grant permission to use CNRI trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party.

  8. By clicking on the ``ACCEPT'' button where indicated, or by copying, installing or otherwise using Python 1.6.1, Licensee agrees to be bound by the terms and conditions of this License Agreement.

ACCEPT

CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2

Copyright © 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, The Netherlands. All rights reserved.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Stichting Mathematisch Centrum or CWI not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: C.1 History of the Up: C. 歴史とライセンス Next: D. 日本語訳について


D. 日本語訳について

  • D.1 このドキュメントについて
  • D.2 翻訳者一覧 (敬称略)
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: C.2 Terms and conditions Up: Python ライブラリリファレンス Next: D.1 このドキュメントについて


D.1 このドキュメントについて

この文書は、Pythonドキュメント翻訳プロジェクトによる Python Library Reference Release 2.3.3 の日本語訳版です。日本語訳に対する質問や提案などが ありましたら、Pythonドキュメント翻訳プロジェクトのメーリングリスト

http://www.python.jp/mailman/listinfo/python-doc-jp

または、プロジェクトのバグ管理ページ

http://sourceforge.jp/tracker/?atid=116&group_id=11&func=browse

までご報告ください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: D. 日本語訳について Up: D. 日本語訳について Next: D.2 翻訳者一覧 (敬称略)


D.2 翻訳者一覧 (敬称略)

Akihiro Takizawa, Aoki Nobuaki, Atsuo Ishimoto, G.Yoshida, Hiroyuki Yoshimura, Minami Masanori, Shinsei Nakano, Sumiya Sakoda, YASOZUMI Daisuke, Yasushi Iwata, Yasushi MASUDA, Hiroshi Ayukawa, ippei-at-mbd.nifty.com, sakito, umi-at-venus.dti.ne.jp, ふるかわとおる, 浦郷圭介, 梶山大輔, 根岸史郎, 山中裕史, 山本昇, 新山祐介, 森若和雄

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: D.1 このドキュメントについて Up: D. 日本語訳について Next: Module Index


Module Index

This index only lists modules documented in this manual. The Global Module Index lists all modules that are documented in this set of manuals.

Some module names are followed by an annotation indicating what platform they are available on.

__builtin__
__future__
__main__
_winreg (Windows)
aifc
AL (IRIX)
al (IRIX)
anydbm
array
asynchat
asyncore
atexit
audioop
base64
BaseHTTPServer
Bastion
binascii
binhex
bisect
bsddb (Unix, Windows)
bz2
calendar
cd (IRIX)
cgi
CGIHTTPServer
cgitb
chunk
cmath
cmd
code
codecs
codeop
colorsys
commands (Unix)
compileall
compiler.ast
compiler.visitor
compiler
ConfigParser
Cookie
copy
copy_reg
cPickle
crypt (Unix)
cStringIO
csv
curses.ascii
curses.panel
curses.textpad
curses.wrapper
curses
datetime
dbhash (Unix, Windows)
dbm (Unix)
DEVICE (IRIX)
difflib
dircache
dis
distutils
dl (Unix)
doctest
DocXMLRPCServer
dumbdbm
dummy_thread
dummy_threading
email.Charset
email.Encoders
email.Generator
email.Header
email.Iterators
email.Message
email.Parser
email.Utils
email
encodings.idna
errno
exceptions
fcntl (Unix)
filecmp
fileinput
FL (IRIX)
fl (IRIX)
flp (IRIX)
fm (IRIX)
fnmatch
formatter
fpectl (Unix)
fpformat
ftplib
gc
gdbm (Unix)
getopt
getpass
gettext
GL (IRIX)
gl (IRIX)
glob
gopherlib
grp (Unix)
gzip
heapq
hmac
hotshot.stats
hotshot
htmlentitydefs
htmllib
HTMLParser
httplib
imageop
imaplib
imgfile (IRIX)
imghdr
imp
inspect
itertools
jpeg (IRIX)
keyword
linecache
locale
logging
mailbox
mailcap
marshal
math
md5
mhlib
mimetools
mimetypes
MimeWriter
mimify
mmap
mpz
msvcrt (Windows)
multifile
mutex
netrc
new
nis (UNIX)
nntplib
operator
optparse
os.path
os
ossaudiodev (Linux, FreeBSD, おそらく他の Unix 系システムでも)
parser
pdb
pickle
pipes (Unix)
pkgutil
popen2 (Unix, Windows)
poplib
posix (Unix)
posixfile (Unix)
pprint
profile
pstats
pty (IRIX, Linux)
pwd (Unix)
py_compile
pyclbr
pydoc
Queue
quopri
random
re
readline (Unix)
repr
resource (Unix)
rexec
rfc822
rgbimg
rlcompleter (Unix)
robotparser
rotor
sched
ScrolledText (Tk)
select
sets
sgmllib
sha
shelve
shlex
shutil
signal
SimpleHTTPServer
SimpleXMLRPCServer
site
smtplib
sndhdr
socket
SocketServer
stat
statcache
statvfs
string
StringIO
stringprep
struct
sunau
SUNAUDIODEV (SunOS)
sunaudiodev (SunOS)
symbol
sys
syslog (Unix)
tabnanny
tarfile
telnetlib
tempfile
TERMIOS (Unix)
termios (Unix)
test.test_support
test
textwrap
thread
threading
time
timeit
Tix
Tkinter
token
tokenize
traceback
tty (Unix)
turtle (Tk)
types
unicodedata
unittest
urllib2
urllib
urlparse
user
UserDict
UserList
UserString
uu
warnings
wave
weakref
webbrowser
whichdb
whrandom
winsound (Windows)
xdrlib
xml.dom.minidom
xml.dom.pulldom
xml.dom
xml.parsers.expat
xml.sax.handler
xml.sax.saxutils
xml.sax.xmlreader
xml.sax
xmllib
xmlrpclib
xreadlines
zipfile
zlib

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: D.2 翻訳者一覧 (敬称略) Up: Python ライブラリリファレンス Next: 索引


索引

記号 | _ | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | t | u | v | w | x | y | z

記号

.ini
file
.pdbrc
file
.pythonrc.py
file
% formatting
% interpolation
== 演算子
\POSIX
file object
I/O control, [リンク]
threads

_ (アンダースコア)

__abs__() (モジュール operator)
__add__() (AddressList のメソッド)
__add__() (モジュール operator)
__and__() (モジュール operator)
__bases__ (class の属性)
__builtin__ (組み込み モジュール)
__call__() (Generator のメソッド)
__class__ (instance の属性)
__cmp__() (instance method)
__concat__() (モジュール operator)
__contains__() (Message のメソッド)
__contains__() (モジュール operator)
__copy__() (copy protocol)
__deepcopy__() (copy protocol)
__delitem__() (Message のメソッド)
__delitem__() (モジュール operator)
__delslice__() (モジュール operator)
__dict__ (instance attribute)
__dict__ (object の属性)
__displayhook__ (モジュール sys)
__div__() (モジュール operator)
__eq__() (Charset のメソッド)
__eq__() (Header のメソッド)
__eq__() (モジュール operator)
__excepthook__ (モジュール sys)
__floordiv__() (モジュール operator)
__future__ (標準 モジュール)
__ge__() (モジュール operator)
__getinitargs__() (copy protocol), [リンク]
__getitem__() (Message のメソッド)
__getitem__() (モジュール operator)
__getslice__() (モジュール operator)
__getstate__() (copy protocol), [リンク]
__gt__() (モジュール operator)
__iadd__() (AddressList のメソッド)
__import__() (built-in function)
__init__() (instance constructor)
__init__() (NullTranslations のメソッド)
__init__() (Textbox のメソッド)
__inv__() (モジュール operator)
__invert__() (モジュール operator)
__isub__() (AddressList のメソッド)
__iter__() (container のメソッド)
__iter__() (iterator のメソッド)
__le__() (モジュール operator)
__len__() (AddressList のメソッド)
__len__() (Message のメソッド)
__lshift__() (モジュール operator)
__lt__() (モジュール operator)
__main__ (組み込み モジュール)
__members__ (object の属性)
__methods__ (object の属性)
__mod__() (モジュール operator)
__mul__() (モジュール operator)
__ne__() (Header のメソッド), [リンク]
__ne__() (モジュール operator)
__neg__() (モジュール operator)
__not__() (モジュール operator)
__or__() (モジュール operator)
__pos__() (モジュール operator)
__pow__() (モジュール operator)
__repeat__() (モジュール operator)
__repr__() (netrc のメソッド)
__rshift__() (モジュール operator)
__setitem__() (Message のメソッド)
__setitem__() (モジュール operator)
__setslice__() (モジュール operator)
__setstate__() (copy protocol), [リンク]
__stderr__ (モジュール sys)
__stdin__ (モジュール sys)
__stdout__ (モジュール sys)
__str__() (AddressList のメソッド)
__str__() (Charset のメソッド)
__str__() (date のメソッド)
__str__() (datetime のメソッド)
__str__() (Header のメソッド)
__str__() (Message のメソッド)
__str__() (time のメソッド)
__sub__() (AddressList のメソッド)
__sub__() (モジュール operator)
__truediv__() (モジュール operator)
__unicode__() (Header のメソッド)
__xor__() (モジュール operator)
_exit() (モジュール os)
_getframe() (モジュール sys)
_locale (組み込み モジュール)
_parse() (NullTranslations のメソッド)
_structure() (モジュール email.Iterators)
_urlopener (モジュール urllib)
_winreg (拡張 モジュール)

A

A-LAW, [リンク]
a2b_base64() (モジュール binascii)
a2b_hex() (モジュール binascii)
a2b_hqx() (モジュール binascii)
a2b_qp() (モジュール binascii)
a2b_uu() (モジュール binascii)
ABDAY_1 ... ABDAY_7 (モジュール locale)
ABMON_1 ... ABMON_12 (モジュール locale)
abort() (FTP のメソッド)
abort() (モジュール os)
above() (Textbox のメソッド)
abs() (built-in function)
abs() (モジュール operator)
abspath() (モジュール os.path)
AbstractBasicAuthHandler (urllib2 内の クラス)
AbstractDigestAuthHandler (urllib2 内の クラス)
AbstractFormatter (formatter 内の クラス)
AbstractWriter (formatter 内の クラス)
ac_in_buffer_size (モジュール asyncore)
ac_out_buffer_size (モジュール asyncore)
accept() (dispatcher のメソッド)
accept() (socket のメソッド)
accept2dyear (モジュール time)
access() (モジュール os)
acos() (モジュール cmath)
acos() (モジュール math)
acosh() (モジュール cmath)
acquire() (Condition のメソッド)
acquire() (lock のメソッド)
acquire() (Semaphore のメソッド)
acquire() (Textbox のメソッド)
acquire() (Timer のメソッド), [リンク]
acquire_lock() (モジュール imp)
ACTIONS (Textbox の属性)
activate_form() (form のメソッド)
activeCount() (モジュール threading)
add() (Stats のメソッド)
add() (TarFile のメソッド)
add() (モジュール audioop)
add() (モジュール operator)
add_alias() (モジュール email.Charset)
add_box() (form のメソッド)
add_browser() (form のメソッド)
add_button() (form のメソッド)
add_charset() (モジュール email.Charset)
add_choice() (form のメソッド)
add_clock() (form のメソッド)
add_codec() (モジュール email.Charset)
add_counter() (form のメソッド)
add_data() (Request のメソッド)
add_dial() (form のメソッド)
add_fallback() (NullTranslations のメソッド)
add_flowing_data() (formatter のメソッド)
add_handler() (OpenerDirector のメソッド)
add_header() (Message のメソッド)
add_header() (Request のメソッド)
add_history() (モジュール readline)
add_hor_rule() (formatter のメソッド)
add_input() (form のメソッド)
add_label_data() (formatter のメソッド)
add_lightbutton() (form のメソッド)
add_line_break() (formatter のメソッド)
add_literal_data() (formatter のメソッド)
add_menu() (form のメソッド)
add_parent() (BaseHandler のメソッド)
add_password() (HTTPPasswordMgr のメソッド)
add_payload() (Message のメソッド)
add_positioner() (form のメソッド)
add_roundbutton() (form のメソッド)
add_section() (SafeConfigParser のメソッド)
add_slider() (form のメソッド)
add_text() (form のメソッド)
add_timer() (form のメソッド)
add_type() (モジュール mimetypes)
add_valslider() (form のメソッド)
addcallback() (CD parser のメソッド)
addch() (window のメソッド)
addError() (TestResult のメソッド)
addFailure() (TestResult のメソッド)
addfile() (TarFile のメソッド)
addFilter() (Textbox のメソッド), [リンク]
addHandler() (Textbox のメソッド)
addheader() (MimeWriter のメソッド)
addinfo() (Profile のメソッド)
addLevelName() (モジュール logging)
addnstr() (window のメソッド)
address_family (SocketServer protocol)
address_string() (BaseHTTPRequestHandler のメソッド)
addresslist (AddressList の属性)
AddressList (rfc822 内の クラス)
addstr() (window のメソッド)
addSuccess() (TestResult のメソッド)
addTest() (TestSuite のメソッド)
addTests() (TestSuite のメソッド)
adler32() (モジュール zlib)
ADPCM, Intel/DVI
adpcm2lin() (モジュール audioop)
adpcm32lin() (モジュール audioop)
AF_INET (モジュール socket)
AF_INET6 (モジュール socket)
AF_UNIX (モジュール socket)
AI_* (モジュール socket)
aifc() (aifc のメソッド)
aifc (標準 モジュール)
AIFF, [リンク]
aiff() (aifc のメソッド)
AIFF-C, [リンク]
AL (標準 モジュール), [リンク]
al (組み込み モジュール)
alarm() (モジュール signal)
all_errors (モジュール ftplib)
all_features (モジュール xml.sax.handler)
all_properties (モジュール xml.sax.handler)
allocate_lock() (モジュール thread)
allow_reuse_address (SocketServer protocol)
allowremoval() (CD player のメソッド)
alt() (モジュール curses.ascii)
ALT_DIGITS (モジュール locale)
altsep (モジュール os)
altzone (モジュール time)
anchor_bgn() (HTMLParser のメソッド)
anchor_end() (HTMLParser のメソッド)
and 演算子, [リンク]
and_() (モジュール operator)
annotate() (モジュール dircache)
anydbm (標準 モジュール)
api_version (モジュール sys)
apop() (POP3 のメソッド)
append() (array のメソッド)
append() (Header のメソッド)
append() (IMAP4_stream のメソッド)
append() (list method)
append() (Template のメソッド)
appendChild() (Node のメソッド)
apply() (non-essential built-in functions)
arbitrary precision integers
aRepr (モジュール repr)
argv (モジュール sys)
arithmetic
ArithmeticError
array() (モジュール array)
array (組み込み モジュール)
arrays
ArrayType (モジュール array)
article() (NNTPDataError のメソッド)
AS_IS (モジュール formatter)
as_string() (Message のメソッド)
ascii() (モジュール curses.ascii)
ascii_letters (モジュール string)
ascii_lowercase (モジュール string)
ascii_uppercase (モジュール string)
asctime() (モジュール time)
asin() (モジュール cmath)
asin() (モジュール math)
asinh() (モジュール cmath)
assert 実行文
assert_() (TestCase のメソッド)
assert_line_data() (formatter のメソッド)
assertAlmostEqual() (TestCase のメソッド)
assertEqual() (TestCase のメソッド)
AssertionError
assertNotAlmostEqual() (TestCase のメソッド)
assertNotEqual() (TestCase のメソッド)
assertRaises() (TestCase のメソッド)
assignment
extended slice
slice
subscript
ast2list() (モジュール parser)
ast2tuple() (モジュール parser)
astimezone() (datetime のメソッド)
ASTType (モジュール parser)
ASTVisitor (compiler.visitor 内の クラス)
async_chat (asynchat 内の クラス)
asynchat (標準 モジュール)
asyncore (組み込み モジュール)
atan() (モジュール cmath)
atan() (モジュール math)
atan2() (モジュール math)
atanh() (モジュール cmath)
atexit (標準 モジュール)
atime (モジュール cd)
atof() (モジュール locale)
atof() (モジュール string)
atoi() (モジュール locale)
atoi() (モジュール string)
atol() (モジュール string)
attach() (Message のメソッド)
AttlistDeclHandler() (xmlparser のメソッド)
AttributeError
attributes (Node の属性)
attributes (XMLParser の属性)
AttributesImpl (xml.sax.xmlreader 内の クラス)
AttributesNSImpl (xml.sax.xmlreader 内の クラス)
attroff() (window のメソッド)
attron() (window のメソッド)
attrset() (window のメソッド)
audio (モジュール cd)
Audio Interchange File Format
AUDIO_FILE_ENCODING_ADPCM_G721 (モジュール sunau)
AUDIO_FILE_ENCODING_ADPCM_G722 (モジュール sunau)
AUDIO_FILE_ENCODING_ADPCM_G723_3 (モジュール sunau)
AUDIO_FILE_ENCODING_ADPCM_G723_5 (モジュール sunau)
AUDIO_FILE_ENCODING_ALAW_8 (モジュール sunau)
AUDIO_FILE_ENCODING_DOUBLE (モジュール sunau)
AUDIO_FILE_ENCODING_FLOAT (モジュール sunau)
AUDIO_FILE_ENCODING_LINEAR_16 (モジュール sunau)
AUDIO_FILE_ENCODING_LINEAR_24 (モジュール sunau)
AUDIO_FILE_ENCODING_LINEAR_32 (モジュール sunau)
AUDIO_FILE_ENCODING_LINEAR_8 (モジュール sunau)
AUDIO_FILE_ENCODING_MULAW_8 (モジュール sunau)
AUDIO_FILE_MAGIC (モジュール sunau)
AUDIODEV (environment variable), [リンク]
AUDIODEV (環境変数), [リンク]
audioop (組み込み モジュール)
authenticate() (IMAP4_stream のメソッド)
authenticators() (netrc のメソッド)
avg() (モジュール audioop)
avgpp() (モジュール audioop)

B

b2a_base64() (モジュール binascii)
b2a_hex() (モジュール binascii)
b2a_hqx() (モジュール binascii)
b2a_qp() (モジュール binascii)
b2a_uu() (モジュール binascii)
BabylMailbox (mailbox 内の クラス)
backslashreplace_errors_errors() (モジュール codecs)
backward() (モジュール turtle)
BadStatusLine
Balloon (Tix 内の クラス)
base64
encoding
base64 (標準 モジュール)
BaseCookie (Cookie 内の クラス)
BaseHandler (urllib2 内の クラス)
BaseHTTPRequestHandler (BaseHTTPServer 内の クラス)
BaseHTTPServer (標準 モジュール)
basename() (モジュール os.path)
basestring() (built-in function)
basicConfig() (モジュール logging)
Bastion() (モジュール Bastion)
Bastion (標準 モジュール)
BastionClass (Bastion 内の クラス)
baudrate() (モジュール curses)
bdb (標準 モジュール)
beep() (モジュール curses)
Beep() (モジュール winsound)
below() (Textbox のメソッド)
Benchmarking
benchmarking
bestreadsize() (CD player のメソッド)
betavariate() (モジュール random)
bgn_group() (form のメソッド)
bias() (モジュール audioop)
bidirectional() (モジュール unicodedata)
binary
data, packing
binary() (mpz のメソッド)
binary() (モジュール xmlrpclib)
binary semaphores
binascii (組み込み モジュール)
bind() (dispatcher のメソッド)
bind() (socket のメソッド)
bind (widgets)
bindtextdomain() (モジュール gettext)
binhex() (モジュール binhex)
binhex (標準 モジュール), [リンク]
bisect() (モジュール bisect)
bisect (標準 モジュール)
bisect_left() (モジュール bisect)
bisect_right() (モジュール bisect)
bit-string
operations
bkgd() (window のメソッド)
bkgdset() (window のメソッド)
BLOCKSIZE (モジュール cd)
blocksize (モジュール sha)
body() (NNTPDataError のメソッド)
body_encode() (Charset のメソッド)
body_encoding (モジュール email.Charset)
body_line_iterator() (モジュール email.Iterators)
BOM (モジュール codecs)
BOM_BE (モジュール codecs)
BOM_LE (モジュール codecs)
BOM_UTF16 (モジュール codecs)
BOM_UTF16_BE (モジュール codecs)
BOM_UTF16_LE (モジュール codecs)
BOM_UTF32 (モジュール codecs)
BOM_UTF32_BE (モジュール codecs)
BOM_UTF32_LE (モジュール codecs)
BOM_UTF8 (モジュール codecs)
bool() (built-in function)
Boolean
operations, [リンク]
type
values
boolean() (モジュール xmlrpclib)
Boolean オブジェクト
BooleanType (モジュール types)
border() (window のメソッド)
bottom() (Textbox のメソッド)
bottom_panel() (モジュール curses.panel)
BoundedSemaphore() (モジュール threading)
box() (window のメソッド)
break_long_words (TextWrapper の属性)
BROWSER (environment variable), [リンク]
BROWSER (環境変数), [リンク]
bsddb (拡張 モジュール)
bsddb (組み込み モジュール), [リンク], [リンク]
BsdDbShelf (shelve 内の クラス)
btopen() (モジュール bsddb)
buffer() (non-essential built-in functions)
buffer() (組み込み関数), [リンク]
buffer オブジェクト
buffer size, I/O
buffer_info() (array のメソッド)
buffer_size (xmlparser の属性)
buffer_text (xmlparser の属性)
buffer_used (xmlparser の属性)
BufferingHandler (logging 内の クラス)
BufferType (モジュール types)
bufsize() (audio device のメソッド)
build_opener() (モジュール urllib2)
built-in
constants
exceptions
functions
types, [リンク]
builtin_module_names (モジュール sys)
BuiltinFunctionType (モジュール types)
BuiltinMethodType (モジュール types)
ButtonBox (Tix 内の クラス)
byte-code
file, [リンク], [リンク]
byteorder (モジュール sys)
byteswap() (array のメソッド)
bz2 (組み込み モジュール)
BZ2Compressor (bz2 内の クラス)
BZ2Decompressor (bz2 内の クラス)
BZ2File (bz2 内の クラス)

C

C
language, [リンク]
structures
C_BUILTIN (モジュール imp)
C_EXTENSION (モジュール imp)
CacheFTPHandler (urllib2 内の クラス)
calcsize() (モジュール struct)
calendar() (モジュール calendar)
calendar (標準 モジュール)
call() (TarInfo のメソッド)
callable() (built-in function)
CallableProxyType (モジュール weakref)
can_change_color() (モジュール curses)
can_fetch() (RobotFileParser のメソッド)
cancel() (scheduler のメソッド)
cancel() (Timer のメソッド)
CannotSendHeader
CannotSendRequest
capitalize() (string のメソッド)
capitalize() (モジュール string)
capwords() (モジュール string)
cat() (モジュール nis)
catalog (モジュール cd)
category() (モジュール unicodedata)
cbreak() (モジュール curses)
cd (組み込み モジュール)
CDROM (モジュール cd)
ceil() (in module math)
ceil() (モジュール math)
center() (string のメソッド)
center() (モジュール string)
CGI
debugging
exceptions
protocol
security
tracebacks
cgi (標準 モジュール)
cgi_directories (CGIHTTPRequestHandler の属性)
CGIHTTPRequestHandler (CGIHTTPServer 内の クラス)
CGIHTTPServer (標準 モジュール), [リンク]
cgitb (標準 モジュール)
CGIXMLRPCRequestHandler (SimpleXMLRPCServer 内の クラス)
chain() (モジュール itertools)
chaining
comparisons
channels() (audio device のメソッド)
CHAR_MAX (モジュール locale)
character
CharacterDataHandler() (xmlparser のメソッド)
characters() (ContentHandler のメソッド)
Charset (email.Charset 内の クラス)
charset() (NullTranslations のメソッド)
CHARSET (モジュール mimify)
chdir() (モジュール os)
check() (IMAP4_stream のメソッド)
check() (モジュール tabnanny)
check_forms() (モジュール fl)
checkcache() (モジュール linecache)
CheckList (Tix 内の クラス)
checksum
Cyclic Redundancy Check
MD5
SHA
childerr (Popen4 の属性)
childNodes (Node の属性)
chmod() (モジュール os)
choice() (モジュール random)
choice() (モジュール whrandom)
choose_boundary() (モジュール mimetools)
chown() (モジュール os)
chr() (built-in function)
chroot() (モジュール os)
Chunk (chunk 内の クラス)
chunk (標準 モジュール)
cipher
DES, [リンク]
Enigma
IDEA
circle() (モジュール turtle)
Class browser
classmethod() (built-in function)
classobj() (モジュール new)
ClassType (モジュール types)
clear() (dictionary method)
clear() (Event のメソッド)
clear() (window のメソッド)
clear() (モジュール turtle)
clear_memo() (Pickler のメソッド)
clearcache() (モジュール linecache)
clearok() (window のメソッド)
client_address (BaseHTTPRequestHandler の属性)
clock() (モジュール time)
clone() (Generator のメソッド)
clone() (Template のメソッド)
cloneNode() (HTMLParser のメソッド)
cloneNode() (Node のメソッド)
close() (aifc のメソッド), [リンク]
Close() (ASTVisitor のメソッド)
close() (AU_read のメソッド)
close() (AU_write のメソッド)
close() (audio device のメソッド), [リンク]
close() (BaseHandler のメソッド)
close() (BZ2File のメソッド)
close() (CD player のメソッド)
close() (Chunk のメソッド)
close() (dispatcher のメソッド)
close() (file のメソッド)
close() (FileHandler のメソッド)
close() (FTP のメソッド)
close() (HTMLParser のメソッド)
close() (HTTPSConnection のメソッド)
close() (IMAP4_stream のメソッド)
close() (IncrementalParser のメソッド)
close() (MemoryHandler のメソッド)
close() (mixer device のメソッド)
close() (NTEventLogHandler のメソッド)
close() (OpenerDirector のメソッド)
close() (Profile のメソッド)
close() (Queue のメソッド), [リンク]
close() (SGMLParser のメソッド)
close() (socket のメソッド)
close() (SocketHandler のメソッド)
close() (StringIO のメソッド)
close() (SysLogHandler のメソッド)
close() (TarFile のメソッド)
close() (TarInfo のメソッド)
close() (Telnet のメソッド)
close() (Textbox のメソッド)
close() (Wave_read のメソッド)
close() (Wave_write のメソッド)
close() (XMLParser のメソッド)
close() (ZipFile のメソッド)
close() (モジュール fileinput)
close() (モジュール os)
close_when_done() (async_chat のメソッド)
closed (file の属性)
CloseKey() (モジュール _winreg)
closelog() (モジュール syslog)
closeport() (audio port のメソッド)
clrtobot() (window のメソッド)
clrtoeol() (window のメソッド)
cmath (組み込み モジュール)
Cmd (cmd 内の クラス)
cmd (標準 モジュール), [リンク]
cmdloop() (Cmd のメソッド)
cmp() (built-in function)
cmp() (モジュール filecmp)
cmp() (組み込み関数)
cmp_op (モジュール dis)
cmpfiles() (モジュール filecmp)
code (ExpatError の属性)
code() (モジュール new)
code (標準 モジュール)
code オブジェクト, [リンク], [リンク]
Codecs
decode
encode
codecs (標準 モジュール)
coded_value (Morsel の属性)
codeop (標準 モジュール)
codepoint2name (モジュール htmlentitydefs)
CODESET (モジュール locale)
CodeType (モジュール types)
coerce() (non-essential built-in functions)
collect() (モジュール gc)
collect_incoming_data() (async_chat のメソッド)
color() (モジュール fl)
color() (モジュール turtle)
color_content() (モジュール curses)
color_pair() (モジュール curses)
colorsys (標準 モジュール)
COLUMNS (environment variable), [リンク]
COLUMNS (環境変数), [リンク]
combine() (datetime のメソッド)
combining() (モジュール unicodedata)
ComboBox (Tix 内の クラス)
command (BaseHTTPRequestHandler の属性)
CommandCompiler (codeop 内の クラス)
commands (標準 モジュール)
comment (ZipInfo の属性)
COMMENT (モジュール tokenize)
commenters (shlex の属性)
CommentHandler() (xmlparser のメソッド)
common (dircmp の属性)
Common Gateway Interface
common_dirs (dircmp の属性)
common_files (dircmp の属性)
common_funny (dircmp の属性)
common_types (モジュール mimetypes), [リンク]
commonprefix() (モジュール os.path)
compare() (Differ のメソッド)
comparing
objects
comparison
operator
comparisons
chaining
compile() (AST のメソッド)
compile() (built-in function)
Compile (codeop 内の クラス)
compile() (モジュール compiler)
compile() (モジュール py_compile)
compile() (モジュール re)
compile() (組み込み関数), [リンク], [リンク], [リンク]
compile_command() (モジュール code)
compile_command() (モジュール codeop)
compile_dir() (モジュール compileall)
compile_path() (モジュール compileall)
compileall (標準 モジュール)
compileast() (モジュール parser)
compileFile() (モジュール compiler)
compiler (モジュール)
compiler.ast (モジュール)
compiler.visitor (モジュール)
complete() (Completer のメソッド)
completedefault() (Cmd のメソッド)
complex() (built-in function)
complex() (組み込み関数)
complex number
literals
complex number オブジェクト
ComplexType (モジュール types)
compress() (BZ2Compressor のメソッド)
compress() (Compress のメソッド)
compress() (モジュール bz2)
compress() (モジュール jpeg)
compress() (モジュール zlib)
compress_size (ZipInfo の属性)
compress_type (ZipInfo の属性)
CompressionError
compressobj() (モジュール zlib)
COMSPEC (environment variable)
COMSPEC (環境変数)
concat() (モジュール operator)
concatenation
operation
Condition (threading 内の クラス)
Condition() (モジュール threading)
ConfigParser (ConfigParser 内の クラス)
ConfigParser (標準 モジュール)
configuration
file
file, debugger
file, path
file, user
confstr() (モジュール os)
confstr_names (モジュール os)
conjugate() (complex number method)
connect() (dispatcher のメソッド)
connect() (FTP のメソッド)
connect() (HTTPSConnection のメソッド)
connect() (SMTP のメソッド)
connect() (socket のメソッド)
connect_ex() (socket のメソッド)
ConnectRegistry() (モジュール _winreg)
constants
built-in
constructor() (モジュール copy_reg)
container
iteration over
contains() (モジュール operator)
content type
MIME
ContentHandler (xml.sax.handler 内のクラス)
context_diff() (モジュール difflib)
Control (Tix 内の クラス)
control (モジュール cd)
controlnames (モジュール curses.ascii)
controls() (mixer device のメソッド)
ConversionError
conversions
numeric
convert() (Charset のメソッド)
Cookie (標準 モジュール)
CookieError
Coordinated Universal Time
copy() (dictionary method)
copy() (hmac のメソッド)
copy() (IMAP4_stream のメソッド)
copy() (in copy)
copy() (md5 のメソッド)
copy() (sha のメソッド)
copy() (Template のメソッド)
copy() (モジュール shutil)
copy (標準 モジュール), [リンク]
copy2() (モジュール shutil)
copy_reg (標準 モジュール)
copybinary() (モジュール mimetools)
copyfile() (モジュール shutil)
copyfileobj() (モジュール shutil)
copying files
copyliteral() (モジュール mimetools)
copymessage() (Folder のメソッド)
copymode() (モジュール shutil)
copyright (モジュール sys)
copystat() (モジュール shutil)
copytree() (モジュール shutil)
cos() (モジュール cmath)
cos() (モジュール math)
cosh() (モジュール cmath)
cosh() (モジュール math)
count() (array のメソッド)
count() (list method)
count() (string のメソッド)
count() (モジュール itertools)
count() (モジュール string)
countOf() (モジュール operator)
countTestCases() (TestCase のメソッド)
cPickle (組み込み モジュール), [リンク]
CPU time
CRC (ZipInfo の属性)
crc32() (モジュール binascii)
crc32() (モジュール zlib)
crc_hqx() (モジュール binascii)
create() (IMAP4_stream のメソッド)
create_socket() (dispatcher のメソッド)
create_system (ZipInfo の属性)
create_version (ZipInfo の属性)
createAttribute() (Document のメソッド)
createAttributeNS() (Document のメソッド)
createComment() (Document のメソッド)
createElement() (Document のメソッド)
createElementNS() (Document のメソッド)
CreateKey() (モジュール _winreg)
createLock() (Textbox のメソッド)
createparser() (モジュール cd)
createProcessingInstruction() (Document のメソッド)
createTextNode() (Document のメソッド)
critical() (Textbox のメソッド)
critical() (モジュール logging)
CRNCYSTR (モジュール locale)
crop() (モジュール imageop)
cross() (モジュール audioop)
crypt() (モジュール crypt)
crypt (組み込み モジュール), [リンク]
crypt(3)
cryptography, [リンク]
cStringIO (組み込み モジュール)
csv
csv (標準 モジュール)
ctermid() (モジュール os)
ctime() (date のメソッド)
ctime() (datetime のメソッド)
ctime() (モジュール time)
ctrl() (モジュール curses.ascii)
cunifvariate() (モジュール random)
curdir (モジュール os)
currentThread() (モジュール threading)
curs_set() (モジュール curses)
curses (標準 モジュール)
curses.ascii (標準 モジュール)
curses.panel (標準 モジュール)
curses.textpad (標準 モジュール)
curses.wrapper (標準 モジュール)
cursyncup() (window のメソッド)
cwd() (FTP のメソッド)
cycle() (モジュール itertools)
Cyclic Redundancy Check

D

D_FMT (モジュール locale)
D_T_FMT (モジュール locale)
data
packing binary
tabular
data (Binary の属性)
data (Comment の属性)
data (MutableString の属性)
data (ProcessingInstruction の属性)
data (Text の属性)
data (UserDict の属性)
data (UserList の属性)
database
Unicode
databases
DatagramHandler (logging 内の クラス)
DATASIZE (モジュール cd)
date() (datetime のメソッド)
date (datetime 内の クラス)
date (datetime 内のクラス)
date() (NNTPDataError のメソッド)
date_time (ZipInfo の属性)
date_time_string() (BaseHTTPRequestHandler のメソッド)
datetime (datetime 内の クラス)
datetime (datetime 内のクラス)
datetime (組み込み モジュール)
day (date の属性)
day (datetime の属性)
DAY_1 ... DAY_7 (モジュール locale)
daylight (モジュール time)
Daylight Saving Time
DbfilenameShelf (shelve 内の クラス)
dbhash (標準 モジュール), [リンク]
dbm (組み込み モジュール), [リンク], [リンク], [リンク]
deactivate_form() (form のメソッド)
debug (IMAP4_stream の属性)
debug (shlex の属性)
debug() (Template のメソッド)
debug() (TestCase のメソッド)
debug() (Textbox のメソッド)
debug (ZipFile の属性)
debug() (モジュール doctest)
debug() (モジュール logging)
debug=0 (TarFile の属性)
DEBUG_COLLECTABLE (モジュール gc)
DEBUG_INSTANCES (モジュール gc)
DEBUG_LEAK (モジュール gc)
DEBUG_OBJECTS (モジュール gc)
DEBUG_SAVEALL (モジュール gc)
DEBUG_STATS (モジュール gc)
DEBUG_UNCOLLECTABLE (モジュール gc)
debugger, [リンク]
configuration file
debugging
CGI
decimal() (モジュール unicodedata)
decode
Codecs
decode() (Binary のメソッド)
decode() (ServerProxy のメソッド)
decode() (string のメソッド)
decode() (TextWrapper のメソッド)
decode() (モジュール base64)
decode() (モジュール email.Utils)
decode() (モジュール mimetools)
decode() (モジュール quopri)
decode() (モジュール uu)
decode_header() (モジュール email.Header)
decode_params() (モジュール email.Utils)
decode_rfc2231() (モジュール email.Utils)
DecodedGenerator (email.Generator 内の クラス)
decodestring() (モジュール base64)
decodestring() (モジュール quopri)
decomposition() (モジュール unicodedata)
decompress() (BZ2Decompressor のメソッド)
decompress() (Decompress のメソッド)
decompress() (モジュール bz2)
decompress() (モジュール jpeg)
decompress() (モジュール zlib)
decompressobj() (モジュール zlib)
decrypt() (rotor のメソッド)
decryptmore() (rotor のメソッド)
dedent() (モジュール textwrap)
deepcopy() (in copy)
def_prog_mode() (モジュール curses)
def_shell_mode() (モジュール curses)
default() (ASTVisitor のメソッド)
default() (Cmd のメソッド)
default_bufsize (モジュール xml.dom.pulldom)
default_open() (BaseHandler のメソッド)
DefaultHandler() (xmlparser のメソッド)
DefaultHandlerExpand() (xmlparser のメソッド)
defaults() (SafeConfigParser のメソッド)
defaultTestLoader (モジュール unittest)
defaultTestResult() (TestCase のメソッド)
defpath (モジュール os)
degrees() (RawPen のメソッド)
degrees() (モジュール math)
degrees() (モジュール turtle)
del 実行文, [リンク]
del_param() (Message のメソッド)
delattr() (built-in function)
delay_output() (モジュール curses)
delch() (window のメソッド)
dele() (POP3 のメソッド)
delete() (FTP のメソッド)
delete() (IMAP4_stream のメソッド)
delete_object() (FORMS object のメソッド)
deletefolder() (MH のメソッド)
DeleteKey() (モジュール _winreg)
deleteln() (window のメソッド)
deleteparser() (CD parser のメソッド)
DeleteValue() (モジュール _winreg)
delimiter (Dialect の属性)
delitem() (モジュール operator)
delslice() (モジュール operator)
demo() (モジュール turtle)
DeprecationWarning
dereference=False (TarFile の属性)
derwin() (window のメソッド)
DES
cipher, [リンク]
descriptor, file
Detach() (ASTVisitor のメソッド)
deterministic profiling
DEVICE (標準 モジュール)
dgettext() (モジュール gettext)
Dialect (csv 内のクラス)
dict() (built-in function)
dictionary
type, operations on
dictionary オブジェクト
DictionaryType (モジュール types)
DictMixin (UserDict 内の クラス)
DictReader (csv 内の クラス)
DictType (モジュール types)
DictWriter (csv 内の クラス)
diff_files (dircmp の属性)
Differ (difflib 内の クラス)
Differ (difflib 内のクラス)
difflib (標準 モジュール)
digest() (hmac のメソッド)
digest() (md5 のメソッド)
digest() (sha のメソッド)
digest_size (モジュール md5)
digest_size (モジュール sha)
digit() (モジュール unicodedata)
digits (モジュール string)
dir() (built-in function)
dir() (FTP のメソッド)
dircache (標準 モジュール)
dircmp (filecmp 内の クラス)
directory
changing
creating
deleting, [リンク]
site-packages
site-python
traversal
walking
DirList (Tix 内の クラス)
dirname() (モジュール os.path)
DirSelectBox (Tix 内の クラス)
DirSelectDialog (Tix 内の クラス)
DirTree (Tix 内の クラス)
dis() (モジュール dis)
dis (標準 モジュール)
disable() (モジュール gc)
disable() (モジュール logging)
disassemble() (モジュール dis)
discard_buffers() (async_chat のメソッド)
disco() (モジュール dis)
dispatch() (ASTVisitor のメソッド)
dispatcher (asyncore 内の クラス)
displayhook() (モジュール sys)
distb() (モジュール dis)
distutils (標準 モジュール)
dither2grey2() (モジュール imageop)
dither2mono() (モジュール imageop)
div() (モジュール operator)
division
integer
long integer
divm() (モジュール mpz)
divmod() (built-in function)
dl (拡張 モジュール)
dllhandle (モジュール sys)
dngettext() (モジュール gettext)
do_command() (Textbox のメソッド)
do_forms() (モジュール fl)
do_GET() (SimpleHTTPRequestHandler のメソッド)
do_HEAD() (SimpleHTTPRequestHandler のメソッド)
do_POST() (CGIHTTPRequestHandler のメソッド)
doc_header (Cmd の属性)
DocCGIXMLRPCRequestHandler (DocXMLRPCServer 内の クラス)
docmd() (SMTP のメソッド)
docstrings
doctest (標準 モジュール)
DocTestSuite() (モジュール doctest)
DOCTYPE declaration
documentation
generation
online
documentElement (Document の属性)
DocXMLRPCRequestHandler (DocXMLRPCServer 内の クラス)
DocXMLRPCServer (DocXMLRPCServer 内の クラス)
DocXMLRPCServer (標準 モジュール)
DOMEventStream (xml.dom.pulldom 内の クラス)
DOMException
DomstringSizeErr
done() (Unpacker のメソッド)
doRollover() (RotatingFileHandler のメソッド)
DOTALL (モジュール re)
doublequote (Dialect の属性)
doupdate() (モジュール curses)
down() (モジュール turtle)
drain() (audio device のメソッド)
dropwhile() (モジュール itertools)
dst() (datetime のメソッド)
dst() (time のメソッド), [リンク]
DTDHandler (xml.sax.handler 内のクラス)
dumbdbm (標準 モジュール), [リンク]
DumbWriter (formatter 内の クラス)
dummy_thread (標準 モジュール)
dummy_threading (標準 モジュール)
dump() (Pickler のメソッド)
dump() (モジュール marshal)
dump() (モジュール pickle)
dump_address_pair() (モジュール email.Utils)
dump_address_pair() (モジュール rfc822)
dump_stats() (Stats のメソッド)
dumps() (モジュール marshal)
dumps() (モジュール pickle)
dup() (posixfile method)
dup() (モジュール os)
dup2() (posixfile method)
dup2() (モジュール os)
DuplicateSectionError

E

e (モジュール cmath)
e (モジュール math)
E2BIG (モジュール errno)
EACCES (モジュール errno)
EADDRINUSE (モジュール errno)
EADDRNOTAVAIL (モジュール errno)
EADV (モジュール errno)
EAFNOSUPPORT (モジュール errno)
EAGAIN (モジュール errno)
EAI_* (モジュール socket)
EALREADY (モジュール errno)
EBADE (モジュール errno)
EBADF (モジュール errno)
EBADFD (モジュール errno)
EBADMSG (モジュール errno)
EBADR (モジュール errno)
EBADRQC (モジュール errno)
EBADSLT (モジュール errno)
EBFONT (モジュール errno)
EBUSY (モジュール errno)
ECHILD (モジュール errno)
echo() (モジュール curses)
echochar() (window のメソッド)
ECHRNG (モジュール errno)
ECOMM (モジュール errno)
ECONNABORTED (モジュール errno)
ECONNREFUSED (モジュール errno)
ECONNRESET (モジュール errno)
EDEADLK (モジュール errno)
EDEADLOCK (モジュール errno)
EDESTADDRREQ (モジュール errno)
edit() (Textbox のメソッド)
EDOM (モジュール errno)
EDOTDOT (モジュール errno)
EDQUOT (モジュール errno)
EEXIST (モジュール errno)
EFAULT (モジュール errno)
EFBIG (モジュール errno)
ehlo() (SMTP のメソッド)
EHOSTDOWN (モジュール errno)
EHOSTUNREACH (モジュール errno)
EIDRM (モジュール errno)
EILSEQ (モジュール errno)
EINPROGRESS (モジュール errno)
EINTR (モジュール errno)
EINVAL (モジュール errno)
EIO (モジュール errno)
EISCONN (モジュール errno)
EISDIR (モジュール errno)
EISNAM (モジュール errno)
eject() (CD player のメソッド)
EL2HLT (モジュール errno)
EL2NSYNC (モジュール errno)
EL3HLT (モジュール errno)
EL3RST (モジュール errno)
ElementDeclHandler() (xmlparser のメソッド)
elements (XMLParser の属性)
ELIBACC (モジュール errno)
ELIBBAD (モジュール errno)
ELIBEXEC (モジュール errno)
ELIBMAX (モジュール errno)
ELIBSCN (モジュール errno)
Ellinghouse, Lance, [リンク]
Ellipsis (built-in exception)
EllipsisType (モジュール types)
ELNRNG (モジュール errno)
ELOOP (モジュール errno)
email (標準 モジュール)
email.Charset (標準 モジュール)
email.Encoders (標準 モジュール), [リンク]
email.Generator (標準 モジュール)
email.Header (標準 モジュール)
email.Iterators (標準 モジュール)
email.Message (標準 モジュール)
email.Parser (標準 モジュール)
email.Utils (標準 モジュール)
EMFILE (モジュール errno)
emit() (BufferingHandler のメソッド)
emit() (DatagramHandler のメソッド)
emit() (FileHandler のメソッド)
emit() (HTTPHandler のメソッド)
emit() (NTEventLogHandler のメソッド)
emit() (RotatingFileHandler のメソッド)
emit() (SMTPHandler のメソッド)
emit() (SocketHandler のメソッド)
emit() (StreamHandler のメソッド)
emit() (SysLogHandler のメソッド)
emit() (Textbox のメソッド)
EMLINK (モジュール errno)
Empty
empty() (Queue のメソッド)
empty() (scheduler のメソッド)
EMPTY_NAMESPACE (モジュール xml.dom)
emptyline() (Cmd のメソッド)
EMSGSIZE (モジュール errno)
EMULTIHOP (モジュール errno)
enable() (モジュール cgitb)
enable() (モジュール gc)
ENAMETOOLONG (モジュール errno)
ENAVAIL (モジュール errno)
enclose() (window のメソッド)
encode
Codecs
encode() (Binary のメソッド)
encode() (Header のメソッド)
encode() (ServerProxy のメソッド), [リンク]
encode() (string のメソッド)
encode() (TextWrapper のメソッド)
encode() (モジュール base64)
encode() (モジュール email.Utils)
encode() (モジュール mimetools)
encode() (モジュール quopri)
encode() (モジュール uu)
encode_7or8bit() (モジュール email.Encoders), [リンク]
encode_base64() (モジュール email.Encoders), [リンク]
encode_noop() (モジュール email.Encoders), [リンク]
encode_quopri() (モジュール email.Encoders), [リンク]
encode_rfc2231() (モジュール email.Utils)
encoded_header_len() (Charset のメソッド)
EncodedFile() (モジュール codecs)
encodePriority() (SysLogHandler のメソッド)
encodestring() (モジュール base64)
encodestring() (モジュール quopri)
encoding
base64
quoted-printable
encoding (file の属性)
encodings.idna (標準 モジュール)
encodings_map (モジュール mimetypes), [リンク]
encrypt() (rotor のメソッド)
encryptmore() (rotor のメソッド)
end() (Repr のメソッド)
end_group() (form のメソッド)
end_headers() (BaseHTTPRequestHandler のメソッド)
end_marker() (MultiFile のメソッド)
end_paragraph() (formatter のメソッド)
EndCdataSectionHandler() (xmlparser のメソッド)
EndDoctypeDeclHandler() (xmlparser のメソッド)
endDocument() (ContentHandler のメソッド)
endElement() (ContentHandler のメソッド)
EndElementHandler() (xmlparser のメソッド)
endElementNS() (ContentHandler のメソッド)
endheaders() (HTTPSConnection のメソッド)
EndNamespaceDeclHandler() (xmlparser のメソッド)
endpick() (モジュール gl)
endpos (MatchObject の属性)
endPrefixMapping() (ContentHandler のメソッド)
endselect() (モジュール gl)
endswith() (string のメソッド)
endwin() (モジュール curses)
ENETDOWN (モジュール errno)
ENETRESET (モジュール errno)
ENETUNREACH (モジュール errno)
ENFILE (モジュール errno)
Enigma
cipher
ENOANO (モジュール errno)
ENOBUFS (モジュール errno)
ENOCSI (モジュール errno)
ENODATA (モジュール errno)
ENODEV (モジュール errno)
ENOENT (モジュール errno)
ENOEXEC (モジュール errno)
ENOLCK (モジュール errno)
ENOLINK (モジュール errno)
ENOMEM (モジュール errno)
ENOMSG (モジュール errno)
ENONET (モジュール errno)
ENOPKG (モジュール errno)
ENOPROTOOPT (モジュール errno)
ENOSPC (モジュール errno)
ENOSR (モジュール errno)
ENOSTR (モジュール errno)
ENOSYS (モジュール errno)
ENOTBLK (モジュール errno)
ENOTCONN (モジュール errno)
ENOTDIR (モジュール errno)
ENOTEMPTY (モジュール errno)
ENOTNAM (モジュール errno)
ENOTSOCK (モジュール errno)
ENOTTY (モジュール errno)
ENOTUNIQ (モジュール errno)
enter() (scheduler のメソッド)
enterabs() (scheduler のメソッド)
entities (DocumentType の属性)
ENTITY declaration
EntityDeclHandler() (xmlparser のメソッド)
entitydefs (XMLParser の属性)
entitydefs (モジュール htmlentitydefs)
EntityResolver (xml.sax.handler 内のクラス)
enumerate() (built-in function)
enumerate() (モジュール fm)
enumerate() (モジュール threading)
EnumKey() (モジュール _winreg)
EnumValue() (モジュール _winreg)
environ (モジュール os)
environ (モジュール posix)
environment variables
setting
EnvironmentError
ENXIO (モジュール errno)
演算子
==
and, [リンク]
in, [リンク]
is
is not
not
not in, [リンク]
or, [リンク]
eof (shlex の属性)
EOFError
EOPNOTSUPP (モジュール errno)
EOVERFLOW (モジュール errno)
EPERM (モジュール errno)
EPFNOSUPPORT (モジュール errno)
epilogue (モジュール email.Message)
EPIPE (モジュール errno)
epoch
EPROTO (モジュール errno)
EPROTONOSUPPORT (モジュール errno)
EPROTOTYPE (モジュール errno)
eq() (モジュール operator)
ERA (モジュール locale)
ERA_D_FMT (モジュール locale)
ERA_D_T_FMT (モジュール locale)
ERA_YEAR (モジュール locale)
ERANGE (モジュール errno)
erase() (window のメソッド)
erasechar() (モジュール curses)
EREMCHG (モジュール errno)
EREMOTE (モジュール errno)
EREMOTEIO (モジュール errno)
ERESTART (モジュール errno)
EROFS (モジュール errno)
ERR (モジュール curses)
errcode (ServerProxy の属性)
errmsg (ServerProxy の属性)
errno (標準 モジュール)
errno (組み込み モジュール), [リンク]
Error, [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク]
error, [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク]
error() (ErrorHandler のメソッド)
error() (Folder のメソッド)
error() (MH のメソッド)
error() (OpenerDirector のメソッド)
error() (Textbox のメソッド)
Error (uu 内の 例外)
ERROR (モジュール cd)
error() (モジュール logging)
error_leader() (shlex のメソッド)
error_message_format (BaseHTTPRequestHandler の属性)
error_perm
error_proto, [リンク]
error_reply
error_temp
ErrorByteIndex (xmlparser の属性)
ErrorCode (xmlparser の属性)
errorcode (モジュール errno)
ErrorColumnNumber (xmlparser の属性)
ErrorHandler (xml.sax.handler 内のクラス)
errorlevel=0 (TarFile の属性)
ErrorLineNumber (xmlparser の属性)
Errors
logging
errors (TestResult の属性)
ErrorString() (モジュール xml.parsers.expat)
escape (shlex の属性)
escape() (モジュール cgi)
escape() (モジュール re)
escape() (モジュール xml.sax.saxutils)
escapechar (Dialect の属性)
escapedquotes (shlex の属性)
ESHUTDOWN (モジュール errno)
ESOCKTNOSUPPORT (モジュール errno)
ESPIPE (モジュール errno)
ESRCH (モジュール errno)
ESRMNT (モジュール errno)
ESTALE (モジュール errno)
ESTRPIPE (モジュール errno)
ETIME (モジュール errno)
ETIMEDOUT (モジュール errno)
ETOOMANYREFS (モジュール errno)
ETXTBSY (モジュール errno)
EUCLEAN (モジュール errno)
EUNATCH (モジュール errno)
EUSERS (モジュール errno)
eval() (built-in function)
eval() (組み込み関数), [リンク], [リンク], [リンク], [リンク]
Event (threading 内の クラス)
Event() (モジュール threading)
event scheduling
events (widgets)
EWOULDBLOCK (モジュール errno)
EX_CANTCREAT (モジュール os)
EX_CONFIG (モジュール os)
EX_DATAERR (モジュール os)
EX_IOERR (モジュール os)
EX_NOHOST (モジュール os)
EX_NOINPUT (モジュール os)
EX_NOPERM (モジュール os)
EX_NOTFOUND (モジュール os)
EX_NOUSER (モジュール os)
EX_OK (モジュール os)
EX_OSERR (モジュール os)
EX_OSFILE (モジュール os)
EX_PROTOCOL (モジュール os)
EX_SOFTWARE (モジュール os)
EX_TEMPFAIL (モジュール os)
EX_UNAVAILABLE (モジュール os)
EX_USAGE (モジュール os)
exc_clear() (モジュール sys)
exc_info() (モジュール sys)
exc_traceback (モジュール sys)
exc_type (モジュール sys)
exc_value (モジュール sys)
except 実行文
excepthook() (in module sys)
excepthook() (モジュール sys)
Exception
exception() (Textbox のメソッド)
exception() (モジュール logging)
exceptions
built-in
in CGI scripts
exceptions (標準 モジュール)
EXDEV (モジュール errno)
exec 実行文
exec_prefix (モジュール sys)
execfile() (built-in function)
execfile() (組み込み関数)
execl() (モジュール os)
execle() (モジュール os)
execlp() (モジュール os)
execlpe() (モジュール os)
executable (モジュール sys)
execv() (モジュール os)
execve() (モジュール os)
execvp() (モジュール os)
execvpe() (モジュール os)
ExFileSelectBox (Tix 内の クラス)
EXFULL (モジュール errno)
exists() (モジュール os.path)
exit() (モジュール sys)
exit() (モジュール thread)
exitfunc (in sys)
exitfunc (モジュール sys)
exp() (モジュール cmath)
exp() (モジュール math)
expand() (MatchObject のメソッド)
expand_tabs (TextWrapper の属性)
expandNode() (DOMEventStream のメソッド)
expandtabs() (string のメソッド)
expandtabs() (モジュール string)
expanduser() (モジュール os.path)
expandvars() (モジュール os.path)
Expat
ExpatError
expect() (Telnet のメソッド)
expovariate() (モジュール random)
expr() (モジュール parser)
expunge() (IMAP4_stream のメソッド)
extend() (array のメソッド)
extend() (list method)
extend_path() (モジュール pkgutil)
extended slice
assignment
operation
Extensible Markup Language
extensions_map (SimpleHTTPRequestHandler の属性)
External Data Representation, [リンク]
external_attr (ZipInfo の属性)
ExternalEntityParserCreate() (xmlparser のメソッド)
ExternalEntityRefHandler() (xmlparser のメソッド)
extra (ZipInfo の属性)
extract() (TarFile のメソッド)
extract_stack() (モジュール traceback)
extract_tb() (モジュール traceback)
extract_version (ZipInfo の属性)
ExtractError
extractfile() (TarFile のメソッド)
extsep (モジュール os)

F

F_BAVAIL (モジュール statvfs)
F_BFREE (モジュール statvfs)
F_BLOCKS (モジュール statvfs)
F_BSIZE (モジュール statvfs)
F_FAVAIL (モジュール statvfs)
F_FFREE (モジュール statvfs)
F_FILES (モジュール statvfs)
F_FLAG (モジュール statvfs)
F_FRSIZE (モジュール statvfs)
F_NAMEMAX (モジュール statvfs)
F_OK (モジュール os)
fabs() (モジュール math)
fail() (TestCase のメソッド)
failIf() (TestCase のメソッド)
failIfAlmostEqual() (TextTestRunner のメソッド)
failIfEqual() (TextTestRunner のメソッド)
failUnless() (TextTestRunner のメソッド)
failUnlessAlmostEqual() (TextTestRunner のメソッド)
failUnlessEqual() (TextTestRunner のメソッド)
failUnlessRaises() (TextTestRunner のメソッド)
failureException (TestCase の属性)
failures (TestResult の属性)
False, [リンク]
false
False (built-in exception)
False (Built-in object)
FancyURLopener (urllib 内の クラス)
fatalError() (ErrorHandler のメソッド)
faultCode (ServerProxy の属性)
faultString (ServerProxy の属性)
fcntl() (in module fcntl)
fcntl() (モジュール fcntl)
fcntl (組み込み モジュール), [リンク]
fdatasync() (モジュール os)
fdopen() (モジュール os)
feature_external_ges (モジュール xml.sax.handler)
feature_external_pes (モジュール xml.sax.handler)
feature_namespace_prefixes (モジュール xml.sax.handler)
feature_namespaces (モジュール xml.sax.handler)
feature_string_interning (モジュール xml.sax.handler)
feature_validation (モジュール xml.sax.handler)
feed() (HTMLParser のメソッド)
feed() (IncrementalParser のメソッド)
feed() (SGMLParser のメソッド)
feed() (XMLParser のメソッド)
fetch() (IMAP4_stream のメソッド)
fifo (asynchat 内の クラス)
file
.ini
.pdbrc
.pythonrc.py
byte-code, [リンク], [リンク]
configuration
copying
debugger configuration
large files
mime.types
path configuration
temporary
user configuration
file() (built-in function)
file (class descriptor の属性)
file (function descriptor の属性)
file() (posixfile method)
file() (組み込み関数)
file control
\UNIX
file descriptor
file name
temporary
file object
\POSIX
file オブジェクト
file_offset (ZipInfo の属性)
file_open() (FileHandler のメソッド)
file_size (ZipInfo の属性)
filecmp (標準 モジュール)
fileConfig() (モジュール logging)
FileEntry (Tix 内の クラス)
FileHandler (logging 内の クラス)
FileHandler (urllib2 内の クラス)
FileInput (fileinput 内の クラス)
fileinput (標準 モジュール)
filelineno() (モジュール fileinput)
filename (ZipInfo の属性)
filename() (モジュール fileinput)
filename_only (モジュール tabnanny)
filenames
pathname expantion
wildcard expansion
fileno() (audio device のメソッド), [リンク]
fileno() (file のメソッド)
fileno() (mixer device のメソッド)
fileno() (Profile のメソッド)
fileno() (socket のメソッド)
fileno() (SocketServer protocol)
fileno() (Telnet のメソッド)
fileopen() (モジュール posixfile)
FileSelectBox (Tix 内の クラス)
FileType (モジュール types)
fill() (TextWrapper のメソッド)
fill() (モジュール textwrap)
fill() (モジュール turtle)
filter() (built-in function)
filter() (Filter のメソッド)
Filter (logging 内の クラス)
filter() (Textbox のメソッド), [リンク]
filter() (モジュール curses)
filter() (モジュール fnmatch)
filterwarnings() (モジュール warnings)
find() (Queue のメソッド)
find() (string のメソッド)
find() (モジュール gettext)
find() (モジュール string)
find_first() (form のメソッド)
find_last() (form のメソッド)
find_longest_match() (SequenceMatcher のメソッド)
find_module() (モジュール imp)
find_prefix_at_end() (モジュール asynchat)
find_user_password() (HTTPPasswordMgr のメソッド)
findall() (RegexObject のメソッド)
findall() (モジュール re)
findCaller() (Textbox のメソッド)
findfactor() (モジュール audioop)
findfile() (モジュール test.test_support)
findfit() (モジュール audioop)
findfont() (モジュール fm)
finditer() (RegexObject のメソッド)
finditer() (モジュール re)
findmatch() (モジュール mailcap)
findmax() (モジュール audioop)
finish() (SocketServer protocol)
finish_request() (SocketServer protocol)
first() (dbhash のメソッド)
first() (fifo のメソッド)
first() (Queue のメソッド)
firstChild (Node の属性)
firstkey() (モジュール gdbm)
firstweekday() (モジュール calendar)
fix() (モジュール fpformat)
fix_sentence_endings (TextWrapper の属性)
FL (標準 モジュール)
fl (組み込み モジュール)
flag_bits (ZipInfo の属性)
flags() (posixfile method)
flags (RegexObject の属性)
flash() (モジュール curses)
flatten() (Generator のメソッド)
flattening
objects
float() (built-in function)
float() (組み込み関数), [リンク]
floating point
literals
floating point オブジェクト
FloatingPointError, [リンク]
FloatType (モジュール types)
flock() (モジュール fcntl)
floor() (in module math)
floor() (モジュール math)
floordiv() (モジュール operator)
flp (標準 モジュール)
flush() (audio device のメソッド)
flush() (BufferingHandler のメソッド)
flush() (BZ2Compressor のメソッド)
flush() (Compress のメソッド)
flush() (Decompress のメソッド)
flush() (file のメソッド)
flush() (MemoryHandler のメソッド)
flush() (Queue のメソッド)
flush() (StreamHandler のメソッド)
flush() (Textbox のメソッド)
flush() (writer のメソッド)
flush_softspace() (formatter のメソッド)
flushheaders() (MimeWriter のメソッド)
flushinp() (モジュール curses)
FlushKey() (モジュール _winreg)
fm (組み込み モジュール)
fmod() (モジュール math)
fnmatch() (モジュール fnmatch)
fnmatch (標準 モジュール)
fnmatchcase() (モジュール fnmatch)
Folder (mhlib 内の クラス)
Font Manager, IRIS
fontpath() (モジュール fm)
forget() (モジュール statcache)
forget() (モジュール test.test_support)
forget_dir() (モジュール statcache)
forget_except_prefix() (モジュール statcache)
forget_prefix() (モジュール statcache)
fork() (モジュール os)
fork() (モジュール pty)
forkpty() (モジュール os)
Form (Tix 内の クラス)
format() (Formatter のメソッド)
format() (PrettyPrinter のメソッド)
format() (Textbox のメソッド)
format() (モジュール locale)
format_exception() (モジュール traceback)
format_exception_only() (モジュール traceback)
format_list() (モジュール traceback)
format_stack() (モジュール traceback)
format_tb() (モジュール traceback)
formataddr() (モジュール email.Utils)
formatdate() (モジュール email.Utils)
formatException() (Formatter のメソッド)
formatter (HTMLParser の属性)
Formatter (logging 内の クラス)
formatter (標準 モジュール), [リンク]
formatTime() (Formatter のメソッド)
formatting, string (%)
formatwarning() (モジュール warnings)
FORMS Library
forward() (モジュール turtle)
found_terminator() (async_chat のメソッド)
fp (AddressList の属性)
fpathconf() (モジュール os)
fpectl (拡張 モジュール)
fpformat (標準 モジュール)
frame (ScrolledText の属性)
frame オブジェクト
FrameType (モジュール types)
freeze_form() (form のメソッド)
freeze_object() (FORMS object のメソッド)
frexp() (モジュール math)
from_splittable() (Charset のメソッド)
frombuf() (TarInfo のメソッド)
fromchild (Popen4 の属性)
fromfd() (モジュール socket)
fromfile() (array のメソッド)
fromkeys() (dictionary method)
fromlist() (array のメソッド)
fromordinal() (date のメソッド)
fromordinal() (datetime のメソッド)
fromstring() (array のメソッド)
fromtimestamp() (date のメソッド)
fromtimestamp() (datetime のメソッド)
fromunicode() (array のメソッド)
fromutc() (time のメソッド)
fstat() (モジュール os)
fstatvfs() (モジュール os)
fsync() (モジュール os)
FTP
ftplib (standard module)
protocol, [リンク]
FTP (ftplib 内の クラス)
ftp_open() (FTPHandler のメソッド)
ftp_proxy (environment variable)
ftp_proxy (環境変数)
FTPHandler (urllib2 内の クラス)
ftplib (標準 モジュール)
ftpmirror.py
ftruncate() (モジュール os)
Full
full() (Queue のメソッド)
func_code (function object attribute)
function() (モジュール new)
functions
built-in
FunctionTestCase (unittest 内の クラス)
FunctionType (モジュール types)
funny_files (dircmp の属性)
FutureWarning

G

G.722
gaierror
gammavariate() (モジュール random)
garbage (モジュール gc)
gather() (Textbox のメソッド)
gauss() (モジュール random)
gc (拡張 モジュール)
gcd() (モジュール mpz)
gcdext() (モジュール mpz)
gdbm (組み込み モジュール), [リンク], [リンク]
ge() (モジュール operator)
generate_tokens() (モジュール tokenize)
Generator (email.Generator 内の クラス)
GeneratorType (モジュール types)
get() (AddressList のメソッド)
get() (dictionary method)
get() (Message のメソッド)
get() (mixer device のメソッド)
get() (Queue のメソッド)
get() (SafeConfigParser のメソッド), [リンク]
get() (モジュール webbrowser)
get_all() (Message のメソッド)
get_begidx() (モジュール readline)
get_body_encoding() (Charset のメソッド)
get_boundary() (Message のメソッド)
get_buffer() (Packer のメソッド)
get_buffer() (Unpacker のメソッド)
get_charset() (Message のメソッド)
get_charsets() (Message のメソッド)
get_close_matches() (モジュール difflib)
get_completer() (モジュール readline)
get_completer_delims() (モジュール readline)
get_content_charset() (Message のメソッド)
get_content_maintype() (Message のメソッド)
get_content_subtype() (Message のメソッド)
get_content_type() (Message のメソッド)
get_data() (Request のメソッド)
get_debug() (モジュール gc)
get_default_type() (Message のメソッド)
get_dialect() (モジュール csv)
get_directory() (モジュール fl)
get_endidx() (モジュール readline)
get_filename() (Message のメソッド)
get_filename() (モジュール fl)
get_full_url() (Request のメソッド)
get_grouped_opcodes() (SequenceMatcher のメソッド)
get_history_length() (モジュール readline)
get_host() (Request のメソッド)
get_ident() (モジュール thread)
get_line_buffer() (モジュール readline)
get_magic() (モジュール imp)
get_main_type() (Message のメソッド)
get_matching_blocks() (SequenceMatcher のメソッド)
get_method() (Request のメソッド)
get_mouse() (モジュール fl)
get_nowait() (Queue のメソッド)
get_objects() (モジュール gc)
get_opcodes() (SequenceMatcher のメソッド)
get_option() (Textbox のメソッド)
get_osfhandle() (モジュール msvcrt)
get_output_charset() (Charset のメソッド)
get_param() (Message のメソッド)
get_params() (Message のメソッド)
get_pattern() (モジュール fl)
get_payload() (Message のメソッド)
get_position() (Unpacker のメソッド)
get_recsrc() (mixer device のメソッド)
get_referents() (モジュール gc)
get_referrers() (モジュール gc)
get_request() (SocketServer protocol)
get_rgbmode() (モジュール fl)
get_selector() (Request のメソッド)
get_socket() (Telnet のメソッド)
get_starttag_text() (HTMLParser のメソッド)
get_starttag_text() (SGMLParser のメソッド)
get_subtype() (Message のメソッド)
get_suffixes() (モジュール imp)
get_terminator() (async_chat のメソッド)
get_threshold() (モジュール gc)
get_token() (shlex のメソッド)
get_type() (Message のメソッド)
get_type() (Request のメソッド)
get_unixfrom() (Message のメソッド)
getacl() (IMAP4_stream のメソッド)
getaddr() (AddressList のメソッド)
getaddresses() (モジュール email.Utils)
getaddrinfo() (モジュール socket)
getaddrlist() (AddressList のメソッド)
getallmatchingheaders() (AddressList のメソッド)
getatime() (モジュール os.path)
getattr() (built-in function)
getAttribute() (Element のメソッド)
getAttributeNode() (Element のメソッド)
getAttributeNodeNS() (Element のメソッド)
getAttributeNS() (Element のメソッド)
GetBase() (xmlparser のメソッド)
getbegyx() (window のメソッド)
getboolean() (SafeConfigParser のメソッド)
getByteStream() (InputSource のメソッド)
getcaps() (モジュール mailcap)
getch() (window のメソッド)
getch() (モジュール msvcrt)
getchannels() (audio configuration のメソッド)
getCharacterStream() (InputSource のメソッド)
getche() (モジュール msvcrt)
getcheckinterval() (モジュール sys)
getChildNodes() (Node のメソッド)
getChildren() (Node のメソッド)
getColumnNumber() (Locator のメソッド)
getcomments() (モジュール inspect)
getcompname() (aifc のメソッド)
getcompname() (AU_read のメソッド)
getcompname() (Wave_read のメソッド)
getcomptype() (aifc のメソッド)
getcomptype() (AU_read のメソッド)
getcomptype() (Wave_read のメソッド)
getconfig() (audio port のメソッド)
getContentHandler() (XMLReader のメソッド)
getcontext() (MH のメソッド)
getctime() (モジュール os.path)
getcurrent() (Folder のメソッド)
getcwd() (モジュール os)
getdate() (AddressList のメソッド)
getdate_tz() (AddressList のメソッド)
getdecoder() (モジュール codecs)
getdefaultencoding() (モジュール sys)
getdefaultlocale() (モジュール locale)
getdefaulttimeout() (モジュール socket)
getdlopenflags() (モジュール sys)
getdoc() (モジュール inspect)
getDOMImplementation() (モジュール xml.dom)
getDTDHandler() (XMLReader のメソッド)
getEffectiveLevel() (Textbox のメソッド)
getegid() (モジュール os)
getElementsByTagName() (Document のメソッド)
getElementsByTagName() (Element のメソッド)
getElementsByTagNameNS() (Document のメソッド)
getElementsByTagNameNS() (Element のメソッド)
getencoder() (モジュール codecs)
getEncoding() (InputSource のメソッド)
getencoding() (Message のメソッド)
getEntityResolver() (XMLReader のメソッド)
getenv() (モジュール os)
getErrorHandler() (XMLReader のメソッド)
geteuid() (モジュール os)
getEvent() (DOMEventStream のメソッド)
getEventCategory() (NTEventLogHandler のメソッド)
getEventType() (NTEventLogHandler のメソッド)
getException() (SAXException のメソッド)
getfd() (audio port のメソッド)
getFeature() (XMLReader のメソッド)
getfile() (モジュール inspect)
getfilesystemencoding() (モジュール sys)
getfillable() (audio port のメソッド)
getfilled() (audio port のメソッド)
getfillpoint() (audio port のメソッド)
getfirst() (FieldStorage のメソッド)
getfirstmatchingheader() (AddressList のメソッド)
getfloat() (SafeConfigParser のメソッド)
getfloatmax() (audio configuration のメソッド)
getfmts() (audio device のメソッド)
getfqdn() (モジュール socket)
getframerate() (aifc のメソッド)
getframerate() (AU_read のメソッド)
getframerate() (Wave_read のメソッド)
getfullname() (Folder のメソッド)
getgid() (モジュール os)
getgrall() (モジュール grp)
getgrgid() (モジュール grp)
getgrnam() (モジュール grp)
getgroups() (モジュール os)
getheader() (AddressList のメソッド)
getheader() (HTTPSConnection のメソッド)
gethostbyaddr() (in module socket)
gethostbyaddr() (モジュール socket)
gethostbyname() (モジュール socket)
gethostbyname_ex() (モジュール socket)
gethostname() (in module socket)
gethostname() (モジュール socket)
getinfo() (audio device のメソッド)
getinfo() (ZipFile のメソッド)
GetInputContext() (xmlparser のメソッド)
getint() (SafeConfigParser のメソッド)
getitem() (モジュール operator)
getkey() (window のメソッド)
getlast() (Folder のメソッド)
getLength() (Attributes のメソッド)
getLevelName() (モジュール logging)
getline() (モジュール linecache)
getLineNumber() (Locator のメソッド)
getlist() (FieldStorage のメソッド)
getloadavg() (モジュール os)
getlocale() (モジュール locale)
getLogger() (モジュール logging)
getlogin() (モジュール os)
getmaintype() (Message のメソッド)
getmark() (aifc のメソッド)
getmark() (AU_read のメソッド)
getmark() (Wave_read のメソッド)
getmarkers() (aifc のメソッド)
getmarkers() (AU_read のメソッド)
getmarkers() (Wave_read のメソッド)
getmaxyx() (window のメソッド)
getmcolor() (モジュール fl)
getmember() (TarFile のメソッド)
getmembers() (TarFile のメソッド)
getmembers() (モジュール inspect)
getMessage() (SAXException のメソッド)
getmessagefilename() (Folder のメソッド)
getMessageID() (NTEventLogHandler のメソッド)
getmodule() (モジュール inspect)
getmoduleinfo() (モジュール inspect)
getmodulename() (モジュール inspect)
getmouse() (モジュール curses)
getmtime() (モジュール os.path)
getname() (Chunk のメソッド)
getName() (Thread のメソッド)
getNameByQName() (AttributesNS のメソッド)
getnameinfo() (モジュール socket)
getNames() (Attributes のメソッド)
getnames() (TarFile のメソッド)
getnamespace() (XMLParser のメソッド)
getnchannels() (aifc のメソッド)
getnchannels() (AU_read のメソッド)
getnchannels() (Wave_read のメソッド)
getnframes() (aifc のメソッド)
getnframes() (AU_read のメソッド)
getnframes() (Wave_read のメソッド)
getopt() (モジュール getopt)
getopt (標準 モジュール)
GetoptError
getoutput() (モジュール commands)
getpagesize() (モジュール resource)
getparam() (Message のメソッド)
getparams() (aifc のメソッド)
getparams() (AU_read のメソッド)
getparams() (Wave_read のメソッド)
getparams() (モジュール al)
getparyx() (window のメソッド)
getpass() (モジュール getpass)
getpass (標準 モジュール)
getpath() (MH のメソッド)
getpeername() (socket のメソッド)
getpgrp() (モジュール os)
getpid() (モジュール os)
getplist() (Message のメソッド)
getpos() (HTMLParser のメソッド)
getppid() (モジュール os)
getpreferredencoding() (モジュール locale)
getprofile() (MH のメソッド)
getProperty() (XMLReader のメソッド)
getprotobyname() (モジュール socket)
getPublicId() (InputSource のメソッド)
getPublicId() (Locator のメソッド)
getpwall() (モジュール pwd)
getpwnam() (モジュール pwd)
getpwuid() (モジュール pwd)
getQNameByName() (AttributesNS のメソッド)
getQNames() (AttributesNS のメソッド)
getqueuesize() (audio configuration のメソッド)
getquota() (IMAP4_stream のメソッド)
getquotaroot() (IMAP4_stream のメソッド)
getrawheader() (AddressList のメソッド)
getreader() (モジュール codecs)
getrecursionlimit() (モジュール sys)
getrefcount() (モジュール sys)
getresponse() (HTTPSConnection のメソッド)
getrlimit() (モジュール resource)
getrusage() (モジュール resource)
getsampfmt() (audio configuration のメソッド)
getsample() (モジュール audioop)
getsampwidth() (aifc のメソッド)
getsampwidth() (AU_read のメソッド)
getsampwidth() (Wave_read のメソッド)
getsequences() (Folder のメソッド)
getsequencesfilename() (Folder のメソッド)
getservbyname() (モジュール socket)
getsignal() (モジュール signal)
getsize() (Chunk のメソッド)
getsize() (モジュール os.path)
getsizes() (モジュール imgfile)
getslice() (モジュール operator)
getsockname() (socket のメソッド)
getsockopt() (socket のメソッド)
getsourcefile() (モジュール inspect)
getstate() (モジュール random)
getstatus() (audio port のメソッド)
getstatus() (CD player のメソッド)
getstatus() (モジュール commands)
getstatusoutput() (モジュール commands)
getstr() (window のメソッド)
getSubject() (SMTPHandler のメソッド)
getsubtype() (Message のメソッド)
getSystemId() (InputSource のメソッド)
getSystemId() (Locator のメソッド)
getsyx() (モジュール curses)
gettarinfo() (TarFile のメソッド)
gettempdir() (モジュール tempfile)
gettempprefix() (モジュール tempfile)
getTestCaseNames() (TestLoader のメソッド)
gettext() (GNUTranslations のメソッド)
gettext() (NullTranslations のメソッド)
gettext() (モジュール gettext)
gettext (標準 モジュール)
gettimeout() (socket のメソッド)
gettrackinfo() (CD player のメソッド)
getType() (Attributes のメソッド)
gettype() (Message のメソッド)
getuid() (モジュール os)
getuser() (モジュール getpass)
getValue() (Attributes のメソッド)
getvalue() (StringIO のメソッド)
getValueByQName() (AttributesNS のメソッド)
getweakrefcount() (モジュール weakref)
getweakrefs() (モジュール weakref)
getwelcome() (FTP のメソッド)
getwelcome() (NNTPDataError のメソッド)
getwelcome() (POP3 のメソッド)
getwidth() (audio configuration のメソッド)
getwin() (モジュール curses)
getwindowsversion() (モジュール sys)
getwriter() (モジュール codecs)
getyx() (window のメソッド)
GL (標準 モジュール)
gl (組み込み モジュール)
glob() (モジュール glob)
glob (標準 モジュール), [リンク]
globals() (built-in function)
gmtime() (モジュール time)
GNOME
gnu_getopt() (モジュール getopt)
Gopher
protocol, [リンク], [リンク]
gopher_open() (GopherHandler のメソッド)
gopher_proxy (environment variable)
gopher_proxy (環境変数)
GopherError
GopherHandler (urllib2 内の クラス)
gopherlib (標準 モジュール)
goto() (モジュール turtle)
Graphical User Interface
Greenwich Mean Time
grey22grey() (モジュール imageop)
grey2grey2() (モジュール imageop)
grey2grey4() (モジュール imageop)
grey2mono() (モジュール imageop)
grey42grey() (モジュール imageop)
group() (MatchObject のメソッド)
group() (NNTPDataError のメソッド)
groupdict() (MatchObject のメソッド)
groupindex (RegexObject の属性)
groups() (MatchObject のメソッド)
grp (組み込み モジュール)
gt() (モジュール operator)
guess_all_extensions() (モジュール mimetypes)
guess_extension() (MimeTypes のメソッド)
guess_extension() (モジュール mimetypes)
guess_type() (MimeTypes のメソッド)
guess_type() (モジュール mimetypes)
GUI
gzip (標準 モジュール)
GzipFile (gzip 内の クラス)

H

halfdelay() (モジュール curses)
handle() (BaseHTTPRequestHandler のメソッド)
handle() (SocketServer protocol)
handle() (Textbox のメソッド), [リンク]
handle_accept() (dispatcher のメソッド)
handle_authentication_request() (AbstractBasicAuthHandler のメソッド)
handle_authentication_request() (AbstractDigestAuthHandler のメソッド)
handle_cdata() (XMLParser のメソッド)
handle_charref() (HTMLParser のメソッド)
handle_charref() (SGMLParser のメソッド)
handle_charref() (XMLParser のメソッド)
handle_close() (async_chat のメソッド)
handle_close() (dispatcher のメソッド)
handle_comment() (HTMLParser のメソッド)
handle_comment() (SGMLParser のメソッド)
handle_comment() (XMLParser のメソッド)
handle_connect() (dispatcher のメソッド)
handle_data() (HTMLParser のメソッド)
handle_data() (SGMLParser のメソッド)
handle_data() (XMLParser のメソッド)
handle_decl() (HTMLParser のメソッド)
handle_decl() (SGMLParser のメソッド)
handle_doctype() (XMLParser のメソッド)
handle_endtag() (HTMLParser のメソッド)
handle_endtag() (SGMLParser のメソッド)
handle_endtag() (XMLParser のメソッド)
handle_entityref() (HTMLParser のメソッド)
handle_entityref() (SGMLParser のメソッド)
handle_error() (dispatcher のメソッド)
handle_error() (SocketServer protocol)
handle_expt() (dispatcher のメソッド)
handle_image() (HTMLParser のメソッド)
handle_one_request() (BaseHTTPRequestHandler のメソッド)
handle_pi() (HTMLParser のメソッド)
handle_proc() (XMLParser のメソッド)
handle_read() (async_chat のメソッド)
handle_read() (dispatcher のメソッド)
handle_request() (SimpleXMLRPCRequestHandler のメソッド)
handle_request() (SocketServer protocol)
handle_special() (XMLParser のメソッド)
handle_startendtag() (HTMLParser のメソッド)
handle_starttag() (HTMLParser のメソッド)
handle_starttag() (SGMLParser のメソッド)
handle_starttag() (XMLParser のメソッド)
handle_write() (async_chat のメソッド)
handle_write() (dispatcher のメソッド)
handle_xml() (XMLParser のメソッド)
handleError() (SocketHandler のメソッド), [リンク]
handleError() (Textbox のメソッド)
handler() (モジュール cgitb)
has_colors() (モジュール curses)
has_data() (Request のメソッド)
has_extn() (SMTP のメソッド)
has_header() (Sniffer のメソッド)
has_ic() (モジュール curses)
has_il() (モジュール curses)
has_ipv6 (モジュール socket)
has_key() (dictionary method)
has_key() (Message のメソッド)
has_key() (Queue のメソッド)
has_key() (モジュール curses)
has_option() (SafeConfigParser のメソッド)
has_option() (Textbox のメソッド)
has_section() (SafeConfigParser のメソッド)
hasattr() (built-in function)
hasAttributes() (Node のメソッド)
hasChildNodes() (Node のメソッド)
hascompare (モジュール dis)
hasconst (モジュール dis)
hasFeature() (DOMImplementation のメソッド)
hasfree (モジュール dis)
hash() (built-in function)
hashopen() (モジュール bsddb)
hasjabs (モジュール dis)
hasjrel (モジュール dis)
haslocal (モジュール dis)
hasname (モジュール dis)
have_unicode (モジュール test.test_support)
head() (NNTPDataError のメソッド)
Header (email.Header 内の クラス)
header_encode() (Charset のメソッド)
header_encoding (モジュール email.Charset)
header_offset (ZipInfo の属性)
headers
MIME, [リンク]
headers (AddressList の属性)
headers (BaseHTTPRequestHandler の属性)
headers (ServerProxy の属性)
heapify() (モジュール heapq)
heapmin() (モジュール msvcrt)
heappop() (モジュール heapq)
heappush() (モジュール heapq)
heapq (標準 モジュール)
heapreplace() (モジュール heapq)
helo() (SMTP のメソッド)
help
online
help() (built-in function)
help() (NNTPDataError のメソッド)
herror
hex() (built-in function)
hexadecimal
literals
hexbin() (モジュール binhex)
hexdigest() (hmac のメソッド)
hexdigest() (md5 のメソッド)
hexdigest() (sha のメソッド)
hexdigits (モジュール string)
hexlify() (モジュール binascii)
hexversion (モジュール sys)
hidden() (Textbox のメソッド)
hide() (Textbox のメソッド)
hide_form() (form のメソッド)
hide_object() (FORMS object のメソッド)
HierarchyRequestErr
HIGHEST_PROTOCOL (モジュール pickle)
hline() (window のメソッド)
HList (Tix 内の クラス)
hls_to_rgb() (モジュール colorsys)
hmac (標準 モジュール)
HOME (environment variable), [リンク]
HOME (環境変数), [リンク]
hosts (netrc の属性)
hotshot (標準 モジュール)
hotshot.stats (標準 モジュール)
hour (datetime の属性)
hour (time の属性)
hsv_to_rgb() (モジュール colorsys)
HTML, [リンク], [リンク]
htmlentitydefs (標準 モジュール)
htmllib (標準 モジュール), [リンク]
HTMLParseError
HTMLParser (class in htmllib)
HTMLParser (htmllib 内の クラス)
HTMLParser (HTMLParser 内の クラス)
HTMLParser (標準 モジュール)
htonl() (モジュール socket)
htons() (モジュール socket)
HTTP
httplib (standard module)
protocol, [リンク], [リンク], [リンク], [リンク]
http_error_301() (HTTPRedirectHandler のメソッド)
http_error_302() (HTTPRedirectHandler のメソッド)
http_error_303() (HTTPRedirectHandler のメソッド)
http_error_307() (HTTPRedirectHandler のメソッド)
http_error_401() (HTTPBasicAuthHandler のメソッド)
http_error_401() (HTTPDigestAuthHandler のメソッド)
http_error_407() (ProxyBasicAuthHandler のメソッド)
http_error_407() (ProxyDigestAuthHandler のメソッド)
http_error_\varnnn() (BaseHandler のメソッド)
http_error_default() (BaseHandler のメソッド)
http_open() (HTTPHandler のメソッド)
HTTP_PORT (モジュール httplib)
http_proxy (environment variable)
http_proxy (環境変数)
HTTPBasicAuthHandler (urllib2 内の クラス)
HTTPConnection (httplib 内の クラス)
httpd
HTTPDefaultErrorHandler (urllib2 内の クラス)
HTTPDigestAuthHandler (urllib2 内の クラス)
HTTPError
HTTPException
HTTPHandler (logging 内の クラス)
HTTPHandler (urllib2 内の クラス)
httplib (標準 モジュール)
HTTPPasswordMgr (urllib2 内の クラス)
HTTPPasswordMgrWithDefaultRealm (urllib2 内の クラス)
HTTPRedirectHandler (urllib2 内の クラス)
https_open() (HTTPSHandler のメソッド)
HTTPS_PORT (モジュール httplib)
HTTPSConnection (httplib 内の クラス)
HTTPServer (BaseHTTPServer 内の クラス)
HTTPSHandler (urllib2 内の クラス)
hypertext
hypot() (モジュール math)

I

I (モジュール re)
I/O control
\POSIX, [リンク]
buffering, [リンク], [リンク]
tty, [リンク]
\UNIX
ibufcount() (audio device のメソッド)
id() (built-in function)
id() (TestCase のメソッド)
idcok() (window のメソッド)
IDEA
cipher
ident (モジュール cd)
identchars (Cmd の属性)
Idle
idlok() (window のメソッド)
IEEE-754
if 実行文
ifilter() (モジュール itertools)
ifilterfalse() (モジュール itertools)
ignorableWhitespace() (ContentHandler のメソッド)
ignore() (Stats のメソッド)
ignore_errors() (モジュール codecs)
ignore_zeros=False (TarFile の属性)
IGNORECASE (モジュール re)
ihave() (NNTPDataError のメソッド)
ihooks (標準 モジュール)
IllegalKeywordArgument
imageop (組み込み モジュール)
imap() (モジュール itertools)
IMAP4
protocol
IMAP4 (imaplib 内の クラス)
IMAP4.abort
IMAP4.error
IMAP4.readonly
IMAP4_SSL
protocol
IMAP4_SSL (imaplib 内の クラス)
IMAP4_stream
protocol
IMAP4_stream (imaplib 内の クラス)
imaplib (標準 モジュール)
imgfile (組み込み モジュール)
imghdr (標準 モジュール)
immedok() (window のメソッド)
ImmutableSet (sets 内の クラス)
imp (組み込み モジュール), [リンク]
import 実行文, [リンク]
Import module
ImportError
ImproperConnectionState
in 演算子, [リンク]
in_table_a1() (モジュール stringprep)
in_table_b1() (モジュール stringprep)
in_table_c11() (モジュール stringprep)
in_table_c11_c12() (モジュール stringprep)
in_table_c12() (モジュール stringprep)
in_table_c21() (モジュール stringprep)
in_table_c21_c22() (モジュール stringprep)
in_table_c22() (モジュール stringprep)
in_table_c3() (モジュール stringprep)
in_table_c4() (モジュール stringprep)
in_table_c5() (モジュール stringprep)
in_table_c6() (モジュール stringprep)
in_table_c7() (モジュール stringprep)
in_table_c8() (モジュール stringprep)
in_table_c9() (モジュール stringprep)
in_table_d1() (モジュール stringprep)
in_table_d2() (モジュール stringprep)
INADDR_* (モジュール socket)
inch() (window のメソッド)
Incomplete
IncompleteRead
IncrementalParser (xml.sax.xmlreader 内の クラス)
indentation
Independent JPEG Group
index() (array のメソッド)
index() (list method)
index() (string のメソッド)
index (モジュール cd)
index() (モジュール string)
IndexError
indexOf() (モジュール operator)
IndexSizeErr
inet_aton() (モジュール socket)
inet_ntoa() (モジュール socket)
inet_ntop() (モジュール socket)
inet_pton() (モジュール socket)
infile (shlex の属性)
Infinity, [リンク]
info() (NullTranslations のメソッド)
info() (Textbox のメソッド)
info() (モジュール logging)
infolist() (ZipFile のメソッド)
InfoSeek Corporation
ini file
init() (モジュール fm)
init() (モジュール mimetypes)
init_builtin() (モジュール imp)
init_color() (モジュール curses)
init_frozen() (モジュール imp)
init_pair() (モジュール curses)
inited (モジュール mimetypes)
initial_indent (TextWrapper の属性)
initscr() (モジュール curses)
input() (built-in function)
input() (モジュール fileinput)
input() (組み込み関数)
input_charset (モジュール email.Charset)
input_codec (モジュール email.Charset)
InputOnly (Tix 内の クラス)
InputSource (xml.sax.xmlreader 内の クラス)
InputType (モジュール cStringIO)
insch() (window のメソッド)
insdelln() (window のメソッド)
insert() (array のメソッド)
insert() (list method)
insert_text() (モジュール readline)
insertBefore() (Node のメソッド)
insertln() (window のメソッド)
insnstr() (window のメソッド)
insort() (モジュール bisect)
insort_left() (モジュール bisect)
insort_right() (モジュール bisect)
inspect (標準 モジュール)
insstr() (window のメソッド)
install() (NullTranslations のメソッド)
install() (モジュール gettext)
install_opener() (モジュール urllib2)
instance() (モジュール new)
instancemethod() (モジュール new)
InstanceType (モジュール types)
instr() (window のメソッド)
instream (shlex の属性)
int() (built-in function)
int() (組み込み関数)
Int2AP() (モジュール imaplib)
integer
arbitrary precision
division
division, long
literals
literals, long
types, operations on
integer オブジェクト
Integrated Developement Environment
Intel/DVI ADPCM
interact() (InteractiveConsole のメソッド)
interact() (Telnet のメソッド)
interact() (モジュール code)
InteractiveConsole (code 内の クラス)
InteractiveInterpreter (code 内の クラス)
intern() (non-essential built-in functions)
internal_attr (ZipInfo の属性)
Internaldate2tuple() (モジュール imaplib)
internalSubset (DocumentType の属性)
Internet
Internet Config
interpolation, string (%)
InterpolationDepthError
InterpolationError
InterpolationMissingOptionError
InterpolationSyntaxError
interpreter prompts
interrupt_main() (モジュール thread)
intro (Cmd の属性)
IntType (モジュール types)
InuseAttributeErr
inv() (モジュール operator)
InvalidAccessErr
InvalidCharacterErr
InvalidModificationErr
InvalidStateErr
InvalidURL
invert() (モジュール operator)
ioctl() (モジュール fcntl)
IOError
IP_* (モジュール socket)
IPPORT_* (モジュール socket)
IPPROTO_* (モジュール socket)
IPV6_* (モジュール socket)
IRIS Font Manager
IRIX
threads
is 演算子
is not 演算子
is_() (モジュール operator)
is_builtin() (モジュール imp)
IS_CHARACTER_JUNK() (モジュール difflib)
is_data() (MultiFile のメソッド)
is_empty() (fifo のメソッド)
is_frozen() (モジュール imp)
is_jython (モジュール test.test_support)
IS_LINE_JUNK() (モジュール difflib)
is_linetouched() (window のメソッド)
is_multipart() (Message のメソッド)
is_not() (モジュール operator)
is_resource_enabled() (モジュール test.test_support)
is_tarfile() (モジュール tarfile)
is_wintouched() (window のメソッド)
is_zipfile() (モジュール zipfile)
isabs() (モジュール os.path)
isAlive() (Thread のメソッド)
isalnum() (string のメソッド)
isalnum() (モジュール curses.ascii)
isalpha() (string のメソッド)
isalpha() (モジュール curses.ascii)
isascii() (モジュール curses.ascii)
isatty() (Chunk のメソッド)
isatty() (file のメソッド)
isatty() (モジュール os)
isblank() (モジュール curses.ascii)
isblk() (TarInfo のメソッド)
isbuiltin() (モジュール inspect)
isCallable() (モジュール operator)
ischr() (TarInfo のメソッド)
isclass() (モジュール inspect)
iscntrl() (モジュール curses.ascii)
iscode() (モジュール inspect)
iscomment() (AddressList のメソッド)
isctrl() (モジュール curses.ascii)
isDaemon() (Thread のメソッド)
isdatadescriptor() (モジュール inspect)
isdev() (TarInfo のメソッド)
isdigit() (string のメソッド)
isdigit() (モジュール curses.ascii)
isdir() (TarInfo のメソッド)
isdir() (モジュール os.path)
isenabled() (モジュール gc)
isEnabledFor() (Textbox のメソッド)
isendwin() (モジュール curses)
ISEOF() (モジュール token)
isexpr() (AST のメソッド)
isexpr() (モジュール parser)
isfifo() (TarInfo のメソッド)
isfile() (TarInfo のメソッド)
isfile() (モジュール os.path)
isfirstline() (モジュール fileinput)
isframe() (モジュール inspect)
isfunction() (モジュール inspect)
isgraph() (モジュール curses.ascii)
isheader() (AddressList のメソッド)
isinstance() (built-in function)
iskeyword() (モジュール keyword)
islast() (AddressList のメソッド)
isleap() (モジュール calendar)
islice() (モジュール itertools)
islink() (モジュール os.path)
islnk() (TarInfo のメソッド)
islower() (string のメソッド)
islower() (モジュール curses.ascii)
isMappingType() (モジュール operator)
ismeta() (モジュール curses.ascii)
ismethod() (モジュール inspect)
ismethoddescriptor() (モジュール inspect)
ismodule() (モジュール inspect)
ismount() (モジュール os.path)
ISNONTERMINAL() (モジュール token)
isNumberType() (モジュール operator)
isocalendar() (date のメソッド)
isocalendar() (datetime のメソッド)
isoformat() (date のメソッド)
isoformat() (datetime のメソッド)
isoformat() (time のメソッド)
isoweekday() (date のメソッド)
isoweekday() (datetime のメソッド)
isprint() (モジュール curses.ascii)
ispunct() (モジュール curses.ascii)
isqueued() (モジュール fl)
isreadable() (PrettyPrinter のメソッド)
isreadable() (モジュール pprint)
isrecursive() (PrettyPrinter のメソッド)
isrecursive() (モジュール pprint)
isreg() (TarInfo のメソッド)
isReservedKey() (Morsel のメソッド)
isroutine() (モジュール inspect)
isSameNode() (Node のメソッド)
isSequenceType() (モジュール operator)
isSet() (Event のメソッド)
isspace() (string のメソッド)
isspace() (モジュール curses.ascii)
isstdin() (モジュール fileinput)
issubclass() (built-in function)
issuite() (AST のメソッド)
issuite() (モジュール parser)
issym() (TarInfo のメソッド)
ISTERMINAL() (モジュール token)
istitle() (string のメソッド)
istraceback() (モジュール inspect)
isupper() (string のメソッド)
isupper() (モジュール curses.ascii)
isxdigit() (モジュール curses.ascii)
item() (NamedNodeMap のメソッド)
item() (NodeList のメソッド)
items() (dictionary method)
items() (Message のメソッド)
items() (SafeConfigParser のメソッド), [リンク]
itemsize (array の属性)
iter() (built-in function)
iterator protocol
iteritems() (dictionary method)
iterkeys() (dictionary method)
itertools (標準 モジュール)
itervalues() (dictionary method)
izip() (モジュール itertools)

J

Jansen, Jack
JFIF, [リンク]
実行文
assert
del, [リンク]
except
exec
if
import, [リンク]
print
raise
try
実行文 (続き)
while
join() (string のメソッド)
join() (Thread のメソッド)
join() (モジュール os.path)
join() (モジュール string)
joinfields() (モジュール string)
jpeg (組み込み モジュール)
js_output() (BaseCookie のメソッド)
js_output() (Morsel のメソッド)
jumpahead() (モジュール random)

K

環境変数
AUDIODEV, [リンク]
BROWSER, [リンク]
COLUMNS, [リンク]
COMSPEC
ftp_proxy
gopher_proxy
HOME, [リンク]
http_proxy
KDEDIR
LANG, [リンク], [リンク], [リンク], [リンク]
LANGUAGE, [リンク]
LC_ALL, [リンク]
LC_MESSAGES, [リンク]
LINES, [リンク]
LNAME
LOGNAME, [リンク]
PAGER
PATH, [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク]
PYTHON_DOM
PYTHONPATH, [リンク], [リンク], [リンク]
PYTHONSTARTUP, [リンク], [リンク]
PYTHONY2K, [リンク], [リンク]
TEMP
TIX_LIBRARY
TMP
環境変数 (続き)
TMPDIR
TZ, [リンク], [リンク], [リンク], [リンク], [リンク]
USER
USERNAME
Wimp$ScrapDir
kbhit() (モジュール msvcrt)
KDEDIR (environment variable)
KDEDIR (環境変数)
key (Morsel の属性)
KeyboardInterrupt
KeyError
keyname() (モジュール curses)
keypad() (window のメソッド)
keys() (dictionary method)
keys() (Message のメソッド)
keys() (Queue のメソッド)
keyword (標準 モジュール)
kill() (モジュール os)
killchar() (モジュール curses)
killpg() (モジュール os)
knee (モジュール)
knownfiles (モジュール mimetypes)
Kuchling, Andrew
kwlist (モジュール keyword)

L

L (モジュール re)
LabelEntry (Tix 内の クラス)
LabelFrame (Tix 内の クラス)
LambdaType (モジュール types)
LANG (environment variable), [リンク], [リンク], [リンク], [リンク]
LANG (環境変数), [リンク], [リンク], [リンク], [リンク]
language
C, [リンク]
LANGUAGE (environment variable), [リンク]
LANGUAGE (環境変数), [リンク]
large files
last() (dbhash のメソッド)
last (MultiFile の属性)
last() (NNTPDataError のメソッド)
last() (Queue のメソッド)
last_traceback (モジュール sys)
last_type (モジュール sys)
last_value (モジュール sys)
lastChild (Node の属性)
lastcmd (Cmd の属性)
lastgroup (MatchObject の属性)
lastindex (MatchObject の属性)
lastpart() (MimeWriter のメソッド)
LC_ALL (environment variable), [リンク]
LC_ALL (モジュール locale)
LC_ALL (環境変数), [リンク]
LC_COLLATE (モジュール locale)
LC_CTYPE (モジュール locale)
LC_MESSAGES (environment variable), [リンク]
LC_MESSAGES (モジュール locale)
LC_MESSAGES (環境変数), [リンク]
LC_MONETARY (モジュール locale)
LC_NUMERIC (モジュール locale)
LC_TIME (モジュール locale)
ldexp() (モジュール math)
le() (モジュール operator)
leapdays() (モジュール calendar)
leaveok() (window のメソッド)
left() (モジュール turtle)
left_list (dircmp の属性)
left_only (dircmp の属性)
len() (built-in function)
len() (組み込み関数), [リンク]
length (NamedNodeMap の属性)
length (NodeList の属性)
letters (モジュール string)
level (MultiFile の属性)
library (モジュール dbm)
light-weight processes
lin2adpcm() (モジュール audioop)
lin2adpcm3() (モジュール audioop)
lin2lin() (モジュール audioop)
lin2ulaw() (モジュール audioop)
line-buffered I/O
linecache (標準 モジュール)
lineno (class descriptor の属性)
lineno (ExpatError の属性)
lineno (function descriptor の属性)
lineno (shlex の属性)
lineno() (モジュール fileinput)
LINES (environment variable), [リンク]
LINES (環境変数), [リンク]
linesep (モジュール os)
lineterminator (Dialect の属性)
link() (モジュール os)
linkname (TarInfo の属性)
list
type, operations on
list() (built-in function)
list() (IMAP4_stream のメソッド)
list() (NNTPDataError のメソッド)
list() (POP3 のメソッド)
list() (TarFile のメソッド)
list オブジェクト, [リンク]
list_dialects() (モジュール csv)
listallfolders() (MH のメソッド)
listallsubfolders() (MH のメソッド)
listdir() (モジュール dircache)
listdir() (モジュール os)
listen() (dispatcher のメソッド)
listen() (socket のメソッド)
listen() (モジュール logging)
listfolders() (MH のメソッド)
listmessages() (Folder のメソッド)
ListNoteBook (Tix 内の クラス)
listsubfolders() (MH のメソッド)
ListType (モジュール types)
literals
complex number
floating point
hexadecimal
integer
literals (続き)
long integer
numeric
octal
ljust() (string のメソッド)
ljust() (モジュール string)
LK_LOCK (モジュール msvcrt)
LK_NBLCK (モジュール msvcrt)
LK_NBRLCK (モジュール msvcrt)
LK_RLCK (モジュール msvcrt)
LK_UNLCK (モジュール msvcrt)
LNAME (environment variable)
LNAME (環境変数)
load() (BaseCookie のメソッド)
load() (Unpickler のメソッド)
load() (モジュール hotshot.stats)
load() (モジュール marshal)
load() (モジュール pickle)
load_compiled() (モジュール imp)
load_dynamic() (モジュール imp)
load_module() (モジュール imp)
load_source() (モジュール imp)
loads() (モジュール marshal)
loads() (モジュール pickle)
loadTestsFromModule() (TestLoader のメソッド)
loadTestsFromName() (TestLoader のメソッド)
loadTestsFromNames() (TestLoader のメソッド)
loadTestsFromTestCase() (TestLoader のメソッド)
LOCALE (モジュール re)
locale (標準 モジュール)
localeconv() (モジュール locale)
localName (Attr の属性)
localName (Node の属性)
locals() (built-in function)
localtime() (モジュール time)
Locator (xml.sax.xmlreader 内の クラス)
lock() (mutex のメソッド)
lock() (posixfile method)
Lock() (モジュール threading)
lock_held() (モジュール imp)
locked() (lock のメソッド)
lockf() (in module fcntl)
lockf() (モジュール fcntl)
locking() (モジュール msvcrt)
LockType (モジュール thread)
log() (Textbox のメソッド)
log() (モジュール cmath)
log() (モジュール math)
log10() (モジュール cmath)
log10() (モジュール math)
log_data_time_string() (BaseHTTPRequestHandler のメソッド)
log_error() (BaseHTTPRequestHandler のメソッド)
log_message() (BaseHTTPRequestHandler のメソッド)
log_request() (BaseHTTPRequestHandler のメソッド)
logging
Errors
logging (標準 モジュール)
login() (FTP のメソッド)
login() (IMAP4_stream のメソッド)
login() (SMTP のメソッド)
login_cram_md5() (IMAP4_stream のメソッド)
LOGNAME (environment variable), [リンク]
LOGNAME (環境変数), [リンク]
lognormvariate() (モジュール random)
logout() (IMAP4_stream のメソッド)
LogRecord (logging 内の クラス)
long
integer division
integer literals
long() (built-in function)
long() (組み込み関数), [リンク]
long integer オブジェクト
longimagedata() (モジュール rgbimg)
longname() (モジュール curses)
longstoimage() (モジュール rgbimg)
LongType (モジュール types)
lookup() (モジュール codecs)
lookup() (モジュール unicodedata)
lookup_error() (モジュール codecs)
LookupError
loop() (モジュール asyncore)
lower() (string のメソッド)
lower() (モジュール string)
lowercase (モジュール string)
lseek() (モジュール os)
lshift() (モジュール operator)
lstat() (モジュール os)
lstrip() (string のメソッド)
lstrip() (モジュール string)
lsub() (IMAP4_stream のメソッド)
lt() (モジュール operator)
Lundh, Fredrik

M

M (モジュール re)
macros (netrc の属性)
mailbox (標準 モジュール), [リンク]
mailcap (標準 モジュール)
Maildir (mailbox 内の クラス)
main() (モジュール py_compile)
main() (モジュール unittest)
major() (モジュール os)
make_form() (モジュール fl)
make_header() (モジュール email.Header)
make_msgid() (モジュール email.Utils)
make_parser() (モジュール xml.sax)
makedev() (モジュール os)
makedirs() (モジュール os)
makefile() (socket のメソッド)
makefolder() (MH のメソッド)
makeLogRecord() (モジュール logging), [リンク]
makePickle() (SocketHandler のメソッド)
makeRecord() (Textbox のメソッド)
makeSocket() (DatagramHandler のメソッド)
makeSocket() (SocketHandler のメソッド)
maketrans() (モジュール string)
map() (built-in function)
map_table_b2() (モジュール stringprep)
map_table_b3() (モジュール stringprep)
mapcolor() (モジュール fl)
mapping
types, operations on
mapping オブジェクト
maps() (モジュール nis)
marshal (組み込み モジュール)
marshalling
objects
masking
operations
match() (RegexObject のメソッド)
match() (モジュール nis)
match() (モジュール re)
math (組み込み モジュール), [リンク], [リンク]
max() (built-in function)
max (date の属性)
max (datetime の属性)
max (time の属性)
max (timedelta の属性)
max() (モジュール audioop)
max() (組み込み関数)
MAX_INTERPOLATION_DEPTH (モジュール ConfigParser)
maxdict (Repr の属性)
maxint (モジュール sys)
MAXLEN (モジュール mimify)
maxlevel (Repr の属性)
maxlist (Repr の属性)
maxlong (Repr の属性)
maxother (Repr の属性)
maxpp() (モジュール audioop)
maxstring (Repr の属性)
maxtuple (Repr の属性)
maxunicode (モジュール sys)
MAXYEAR (モジュール datetime)
MB_ICONASTERISK (モジュール winsound)
MB_ICONEXCLAMATION (モジュール winsound)
MB_ICONHAND (モジュール winsound)
MB_ICONQUESTION (モジュール winsound)
MB_OK (モジュール winsound)
md5() (モジュール md5)
md5 (組み込み モジュール)
MemoryError
MemoryHandler (logging 内の クラス)
Message (email.Message 内の クラス)
Message (in module mimetools)
Message (mhlib 内の クラス)
Message (mimetools 内の クラス)
Message (rfc822 内の クラス)
message digest, MD5
message_from_file() (モジュール email.Parser)
message_from_string() (モジュール email.Parser)
MessageBeep() (モジュール winsound)
MessageClass (BaseHTTPRequestHandler の属性)
meta() (モジュール curses)
Meter (Tix 内の クラス)
method オブジェクト
methods (class descriptor の属性)
MethodType (モジュール types)
MH (mhlib 内の クラス)
mhlib (標準 モジュール)
MHMailbox (mailbox 内の クラス)
microsecond (datetime の属性)
microsecond (time の属性)
MIME
base64 encoding
content type
headers, [リンク]
quoted-printable encoding
mime_decode_header() (モジュール mimify)
mime_encode_header() (モジュール mimify)
MIMEAudio (email.Generator 内の クラス)
MIMEBase (email.Generator 内の クラス)
MIMEImage (email.Generator 内の クラス)
MIMEMessage (email.Generator 内の クラス)
MIMEMultipart (email.Generator 内の クラス)
MIMENonMultipart (email.Generator 内の クラス)
MIMEText (email.Generator 内の クラス)
mimetools (標準 モジュール), [リンク]
MimeTypes (mimetypes 内の クラス)
mimetypes (標準 モジュール)
MimeWriter (MimeWriter 内の クラス)
MimeWriter (標準 モジュール)
mimify() (モジュール mimify)
mimify (標準 モジュール)
min() (built-in function)
min (date の属性)
min (datetime の属性)
min (time の属性)
min (timedelta の属性)
min() (組み込み関数)
minmax() (モジュール audioop)
minor() (モジュール os)
minute (datetime の属性)
minute (time の属性)
MINYEAR (モジュール datetime)
mirrored() (モジュール unicodedata)
misc_header (Cmd の属性)
MissingSectionHeaderError
mkd() (FTP のメソッド)
mkdir() (モジュール os)
mkdtemp() (モジュール tempfile)
mkfifo() (モジュール os)
mknod() (モジュール os)
mkstemp() (モジュール tempfile)
mktemp() (モジュール tempfile)
mktime() (モジュール time)
mktime_tz() (モジュール email.Utils)
mktime_tz() (モジュール rfc822)
mmap() (モジュール mmap)
mmap (組み込み モジュール)
MmdfMailbox (mailbox 内の クラス)
mod() (モジュール operator)
mode (file の属性)
mode (TarInfo の属性)
modf() (モジュール math)
modified() (RobotFileParser のメソッド)
module
search path, [リンク], [リンク]
module (class descriptor の属性)
module (function descriptor の属性)
module() (モジュール new)
modules (モジュール sys)
ModuleType (モジュール types)
MON_1 ... MON_12 (モジュール locale)
mono2grey() (モジュール imageop)
month (date の属性)
month (datetime の属性)
month() (モジュール calendar)
monthcalendar() (モジュール calendar)
monthrange() (モジュール calendar)
more() (simple_producer のメソッド)
Morsel (Cookie 内の クラス)
mouseinterval() (モジュール curses)
mousemask() (モジュール curses)
move() (Queue のメソッド)
move() (Textbox のメソッド)
move() (window のメソッド)
move() (モジュール shutil)
movemessage() (Folder のメソッド)
MP, GNU library
mpz() (モジュール mpz)
mpz (組み込み モジュール)
MPZType (モジュール mpz)
msftoblock() (CD player のメソッド)
msftoframe() (モジュール cd)
msg() (Telnet のメソッド)
msg (モジュール httplib)
MSG_* (モジュール socket)
msvcrt (組み込み モジュール)
mt_interact() (Telnet のメソッド)
mtime() (RobotFileParser のメソッド)
mtime (TarInfo の属性)
mul() (モジュール audioop)
mul() (モジュール operator)
MultiFile (multifile 内の クラス)
multifile (標準 モジュール)
MULTILINE (モジュール re)
mutable
sequence types
sequence types, operations on
MutableString (UserString 内の クラス)
mutex (mutex 内の クラス)
mutex (標準 モジュール)
mvderwin() (window のメソッド)
mvwin() (window のメソッド)

N

name (Attr の属性)
name (class descriptor の属性)
name (DocumentType の属性)
name (file の属性)
name (function descriptor の属性)
name (TarInfo の属性)
name (モジュール os)
name() (モジュール unicodedata)
name2codepoint (モジュール htmlentitydefs)
NamedTemporaryFile() (モジュール tempfile)
NameError
namelist() (ZipFile のメソッド)
nameprep() (モジュール encodings.idna)
NamespaceErr
namespaces
XML
namespaceURI (Node の属性)
NaN, [リンク]
NannyNag
napms() (モジュール curses)
National Security Agency
ndiff() (モジュール difflib)
ne() (モジュール operator)
neg() (モジュール operator)
netrc (netrc 内の クラス)
netrc (標準 モジュール)
NetrcParseError
Network News Transfer Protocol
new() (モジュール hmac)
new() (モジュール md5)
new() (モジュール sha)
new (組み込み モジュール)
new_alignment() (writer のメソッド)
new_font() (writer のメソッド)
new_margin() (writer のメソッド)
new_module() (モジュール imp)
new_panel() (モジュール curses.panel)
new_spacing() (writer のメソッド)
new_styles() (writer のメソッド)
newconfig() (モジュール al)
newgroups() (NNTPDataError のメソッド)
newlines (file の属性)
newnews() (NNTPDataError のメソッド)
newpad() (モジュール curses)
newrotor() (モジュール rotor)
newwin() (モジュール curses)
next() (csv reader のメソッド)
next() (dbhash のメソッド)
next() (file のメソッド)
next() (iterator のメソッド)
next() (mailbox のメソッド)
next() (MultiFile のメソッド)
next() (NNTPDataError のメソッド)
next() (Queue のメソッド)
next() (TarFile のメソッド)
nextfile() (モジュール fileinput)
nextkey() (モジュール gdbm)
nextpart() (MimeWriter のメソッド)
nextSibling (Node の属性)
ngettext() (GNUTranslations のメソッド)
ngettext() (NullTranslations のメソッド)
ngettext() (モジュール gettext)
NI_* (モジュール socket)
nice() (モジュール os)
nis (拡張 モジュール)
NIST
nl() (モジュール curses)
NL (モジュール tokenize)
nl_langinfo() (モジュール locale)
nlst() (FTP のメソッド)
NNTP
protocol
NNTP (nntplib 内の クラス)
NNTPDataError (nntplib 内の クラス)
NNTPError (nntplib 内の クラス)
nntplib (標準 モジュール)
NNTPPermanentError (nntplib 内の クラス)
NNTPProtocolError (nntplib 内の クラス)
NNTPReplyError (nntplib 内の クラス)
NNTPTemporaryError (nntplib 内の クラス)
nocbreak() (モジュール curses)
NoDataAllowedErr
Node (compiler.ast 内の クラス)
nodelay() (window のメソッド)
nodeName (Node の属性)
nodeType (Node の属性)
nodeValue (Node の属性)
NODISC (モジュール cd)
noecho() (モジュール curses)
NOEXPR (モジュール locale)
nofill (HTMLParser の属性)
nok_builtin_names (RExec の属性)
noload() (Unpickler のメソッド)
NoModificationAllowedErr
nonblock() (audio device のメソッド)
None (built-in exception)
None (Built-in object)
NoneType (モジュール types)
nonl() (モジュール curses)
noop() (IMAP4_stream のメソッド)
noop() (POP3 のメソッド)
NoOptionError
noqiflush() (モジュール curses)
noraw() (モジュール curses)
normalize() (Node のメソッド)
normalize() (モジュール locale)
normalize() (モジュール unicodedata)
normalvariate() (モジュール random)
normcase() (モジュール os.path)
normpath() (モジュール os.path)
NoSectionError
not 演算子
not in 演算子, [リンク]
not_() (モジュール operator)
NotANumber
notationDecl() (DTDHandler のメソッド)
NotationDeclHandler() (xmlparser のメソッド)
notations (DocumentType の属性)
NotConnected
NoteBook (Tix 内の クラス)
NotFoundErr
notify() (Condition のメソッド)
notifyAll() (Condition のメソッド)
notimeout() (window のメソッド)
NotImplemented (built-in exception)
NotImplementedError
NotStandaloneHandler() (xmlparser のメソッド)
NotSupportedErr
noutrefresh() (window のメソッド)
now(tz=None)() (datetime のメソッド)
NSA
NSIG (モジュール signal)
NTEventLogHandler (logging 内の クラス)
ntohl() (モジュール socket)
ntohs() (モジュール socket)
ntransfercmd() (FTP のメソッド)
NullFormatter (formatter 内の クラス)
NullWriter (formatter 内の クラス)
numeric
conversions
literals
object
types, operations on
numeric() (モジュール unicodedata)
numeric オブジェクト
Numerical Python
nurbscurve() (モジュール gl)
nurbssurface() (モジュール gl)
nvarray() (モジュール gl)

O

O_APPEND (モジュール os)
O_BINARY (モジュール os)
O_CREAT (モジュール os)
O_DSYNC (モジュール os)
O_EXCL (モジュール os)
O_NDELAY (モジュール os)
O_NOCTTY (モジュール os)
O_NONBLOCK (モジュール os)
O_RDONLY (モジュール os)
O_RDWR (モジュール os)
O_RSYNC (モジュール os)
O_SYNC (モジュール os)
O_TRUNC (モジュール os)
O_WRONLY (モジュール os)
object
numeric
object() (built-in function)
objects
comparing
flattening
marshalling
persistent
pickling
serializing
obufcount() (audio device のメソッド), [リンク]
obuffree() (audio device のメソッド)
オブジェクト
Boolean
buffer
code, [リンク], [リンク]
complex number
dictionary
file
floating point
frame
integer
list, [リンク]
long integer
mapping
method
numeric
sequence
socket
string
traceback, [リンク]
tuple
type
Unicode
xrange, [リンク]
oct() (built-in function)
octal
literals
octdigits (モジュール string)
offset (ExpatError の属性)
OK (モジュール curses)
ok_builtin_modules (RExec の属性)
ok_file_types (RExec の属性)
ok_path (RExec の属性)
ok_posix_names (RExec の属性)
ok_sys_names (RExec の属性)
onecmd() (Cmd のメソッド)
open() (built-in function)
open() (IMAP4_stream のメソッド)
open() (OpenerDirector のメソッド)
open() (TarFile のメソッド)
open() (Telnet のメソッド)
open() (Template のメソッド)
open() (URLopener のメソッド)
open() (モジュール aifc)
open() (モジュール anydbm)
open() (モジュール cd)
open() (モジュール codecs)
open() (モジュール dbhash)
open() (モジュール dbm)
open() (モジュール dl)
open() (モジュール dumbdbm)
open() (モジュール gdbm)
open() (モジュール gzip)
open() (モジュール os)
open() (モジュール ossaudiodev)
open() (モジュール posixfile)
open() (モジュール shelve)
open() (モジュール sunau)
open() (モジュール sunaudiodev)
open() (モジュール tarfile)
open() (モジュール wave)
open() (モジュール webbrowser), [リンク]
open_new() (モジュール webbrowser), [リンク]
open_osfhandle() (モジュール msvcrt)
open_unknown() (URLopener のメソッド)
opendir() (モジュール dircache)
OpenerDirector (urllib2 内の クラス)
openfolder() (MH のメソッド)
openfp() (モジュール sunau)
openfp() (モジュール wave)
OpenGL
OpenKey() (モジュール _winreg)
OpenKeyEx() (モジュール _winreg)
openlog() (モジュール syslog)
openmessage() (Message のメソッド)
openmixer() (モジュール ossaudiodev)
openport() (モジュール al)
openpty() (モジュール os)
openpty() (モジュール pty)
operation
concatenation
extended slice
repetition
slice
subscript
operations
bit-string
Boolean, [リンク]
masking
shifting
operations on
dictionary type
integer types
list type
mapping types
mutable sequence types
numeric types
sequence types, [リンク]
operator
comparison
operator (組み込み モジュール)
opname (モジュール dis)
OptionMenu (Tix 内の クラス)
options() (SafeConfigParser のメソッド)
optionxform() (SafeConfigParser のメソッド)
optparse (標準 モジュール)
or 演算子, [リンク]
or_() (モジュール operator)
ord() (built-in function)
ordered_attributes (xmlparser の属性)
os (標準 モジュール), [リンク], [リンク]
os.path (標準 モジュール)
OSError
ossaudiodev (組み込み モジュール)
output() (BaseCookie のメソッド)
output() (Morsel のメソッド)
output_charset (モジュール email.Charset)
output_codec (モジュール email.Charset)
OutputString() (Morsel のメソッド)
OutputType (モジュール cStringIO)
OverflowError
overlay() (window のメソッド)
Overmars, Mark
overwrite() (window のメソッド)

P

P_DETACH (モジュール os)
P_NOWAIT (モジュール os)
P_NOWAITO (モジュール os)
P_OVERLAY (モジュール os)
P_WAIT (モジュール os)
pack() (モジュール struct)
pack_array() (Packer のメソッド)
pack_bytes() (Packer のメソッド)
pack_double() (Packer のメソッド)
pack_farray() (Packer のメソッド)
pack_float() (Packer のメソッド)
pack_fopaque() (Packer のメソッド)
pack_fstring() (Packer のメソッド)
pack_list() (Packer のメソッド)
pack_opaque() (Packer のメソッド)
pack_string() (Packer のメソッド)
package
Packer (xdrlib 内の クラス)
packing
binary data
packing (widgets)
PAGER (environment variable)
PAGER (環境変数)
pair_content() (モジュール curses)
pair_number() (モジュール curses)
PanedWindow (Tix 内の クラス)
pardir (モジュール os)
parent (BaseHandler の属性)
parentNode (Node の属性)
paretovariate() (モジュール random)
parse() (Parser のメソッド)
parse() (RobotFileParser のメソッド)
Parse() (xmlparser のメソッド)
parse() (XMLReader のメソッド)
parse() (モジュール cgi)
parse() (モジュール compiler)
parse() (モジュール xml.dom.minidom)
parse() (モジュール xml.dom.pulldom)
parse() (モジュール xml.sax)
parse_and_bind() (モジュール readline)
parse_header() (モジュール cgi)
parse_multipart() (モジュール cgi)
parse_qs() (モジュール cgi)
parse_qsl() (モジュール cgi)
parseaddr() (モジュール email.Utils)
parseaddr() (モジュール rfc822)
parsedate() (モジュール email.Utils)
parsedate() (モジュール rfc822)
parsedate_tz() (モジュール email.Utils)
parsedate_tz() (モジュール rfc822)
ParseFile() (xmlparser のメソッド)
parseFile() (モジュール compiler)
ParseFlags() (モジュール imaplib)
parseframe() (CD parser のメソッド)
Parser (email.Parser 内の クラス)
parser (組み込み モジュール)
ParserCreate() (モジュール xml.parsers.expat)
ParserError
parsesequence() (Folder のメソッド)
parsestr() (Parser のメソッド)
parseString() (モジュール xml.dom.minidom)
parseString() (モジュール xml.dom.pulldom)
parseString() (モジュール xml.sax)
parsing
Python source code
URL
ParsingError
partial() (IMAP4_stream のメソッド)
pass_() (POP3 のメソッド)
path
configuration file
module search, [リンク], [リンク]
operations
path (BaseHTTPRequestHandler の属性)
PATH (environment variable), [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク]
path (モジュール os)
path (モジュール sys)
PATH (環境変数), [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク], [リンク]
Path browser
pathconf() (モジュール os)
pathconf_names (モジュール os)
pathname2url() (モジュール urllib)
pathsep (モジュール os)
pattern (RegexObject の属性)
pause() (モジュール signal)
PAUSED (モジュール cd)
Pdb (class in pdb)
pdb (標準 モジュール)
Pen (turtle 内の クラス)
PendingDeprecationWarning
Performance
persistence
persistent
objects
pformat() (PrettyPrinter のメソッド)
pformat() (モジュール pprint)
PGP
pi (モジュール cmath)
pi (モジュール math)
pick() (モジュール gl)
pickle() (モジュール copy_reg)
pickle (標準 モジュール), [リンク], [リンク], [リンク], [リンク], [リンク]
PickleError
Pickler (pickle 内の クラス)
pickling
objects
PicklingError
pid (Popen4 の属性)
PIL (the Python Imaging Library)
pipe() (モジュール os)
pipes (標準 モジュール)
PKG_DIRECTORY (モジュール imp)
pkgutil (標準 モジュール)
platform (モジュール sys)
play() (CD player のメソッド)
playabs() (CD player のメソッド)
PLAYING (モジュール cd)
PlaySound() (モジュール winsound)
playtrack() (CD player のメソッド)
playtrackabs() (CD player のメソッド)
plock() (モジュール os)
pm() (モジュール pdb)
pnum (モジュール cd)
poll() (LogRecord のメソッド)
poll() (Popen4 のメソッド)
poll() (モジュール select)
pop() (array のメソッド)
pop() (dictionary method)
pop() (fifo のメソッド)
pop() (list method)
pop() (MultiFile のメソッド)
POP3
protocol
POP3 (poplib 内の クラス)
pop_alignment() (formatter のメソッド)
pop_font() (formatter のメソッド)
pop_margin() (formatter のメソッド)
pop_source() (shlex のメソッド)
pop_style() (formatter のメソッド)
popen() (in module os)
popen() (モジュール os)
popen2() (モジュール os)
popen2() (モジュール popen2)
popen2 (標準 モジュール)
Popen3 (popen2 内の クラス)
popen3() (モジュール os)
popen3() (モジュール popen2)
Popen4 (popen2 内の クラス)
popen4() (モジュール os)
popen4() (モジュール popen2)
popitem() (dictionary method)
poplib (標準 モジュール)
PopupMenu (Tix 内の クラス)
PortableUnixMailbox (mailbox 内の クラス)
pos (MatchObject の属性)
pos() (モジュール operator)
posix (組み込み モジュール)
posix=True (TarFile の属性)
posixfile (組み込み モジュール)
post() (audio device のメソッド)
post() (NNTPDataError のメソッド)
post_mortem() (モジュール pdb)
postcmd() (Cmd のメソッド)
postloop() (Cmd のメソッド)
pow() (built-in function)
pow() (モジュール math)
pow() (モジュール operator)
powm() (モジュール mpz)
pprint() (PrettyPrinter のメソッド)
pprint() (モジュール pprint)
pprint (標準 モジュール)
prcal() (モジュール calendar)
preamble (モジュール email.Message)
precmd() (Cmd のメソッド)
prefix (Attr の属性)
prefix (Node の属性)
prefix (モジュール sys)
preloop() (Cmd のメソッド)
preorder() (ASTVisitor のメソッド)
prepare_input_source() (モジュール xml.sax.saxutils)
prepend() (Template のメソッド)
Pretty Good Privacy
PrettyPrinter (pprint 内の クラス)
preventremoval() (CD player のメソッド)
previous() (dbhash のメソッド)
previous() (Queue のメソッド)
previousSibling (Node の属性)
print 実行文
print_callees() (Stats のメソッド)
print_callers() (Stats のメソッド)
print_directory() (モジュール cgi)
print_environ() (モジュール cgi)
print_environ_usage() (モジュール cgi)
print_exc() (Timer のメソッド)
print_exc() (モジュール traceback)
print_exception() (モジュール traceback)
print_form() (モジュール cgi)
print_last() (モジュール traceback)
print_stack() (モジュール traceback)
print_stats() (Stats のメソッド)
print_tb() (モジュール traceback)
printable (モジュール string)
printdir() (ZipFile のメソッド)
printf-style formatting
Priority Queue
prmonth() (モジュール calendar)
process
group, [リンク]
id
id of parent
killing, [リンク]
signalling, [リンク]
process_request() (SocketServer protocol)
processes, light-weight
processingInstruction() (ContentHandler のメソッド)
ProcessingInstructionHandler() (xmlparser のメソッド)
processor time
Profile (hotshot 内の クラス)
profile (標準 モジュール)
profile function
profiler
profiling, deterministic
prompt (Cmd の属性)
prompt_user_passwd() (FancyURLopener のメソッド)
prompts, interpreter
propagate (モジュール logging)
property() (built-in function)
property_declaration_handler (モジュール xml.sax.handler)
property_dom_node (モジュール xml.sax.handler)
property_lexical_handler (モジュール xml.sax.handler)
property_xml_string (モジュール xml.sax.handler)
protocol
CGI
FTP, [リンク]
Gopher, [リンク], [リンク]
HTTP, [リンク], [リンク], [リンク], [リンク]
IMAP4
IMAP4_SSL
IMAP4_stream
iterator
NNTP
POP3
SMTP
Telnet
protocol_version (BaseHTTPRequestHandler の属性)
PROTOCOL_VERSION (IMAP4_stream の属性)
proxy() (モジュール weakref)
proxyauth() (IMAP4_stream のメソッド)
ProxyBasicAuthHandler (urllib2 内の クラス)
ProxyDigestAuthHandler (urllib2 内の クラス)
ProxyHandler (urllib2 内の クラス)
ProxyType (モジュール weakref)
ProxyTypes (モジュール weakref)
prstr() (モジュール fm)
ps1 (モジュール sys)
ps2 (モジュール sys)
pstats (標準 モジュール)
pthreads
ptime (モジュール cd)
pty (標準 モジュール), [リンク]
publicId (DocumentType の属性)
PullDOM (xml.dom.pulldom 内の クラス)
punctuation (モジュール string)
push() (async_chat のメソッド)
push() (fifo のメソッド)
push() (InteractiveConsole のメソッド)
push() (MultiFile のメソッド)
push_alignment() (formatter のメソッド)
push_font() (formatter のメソッド)
push_margin() (formatter のメソッド)
push_source() (shlex のメソッド)
push_style() (formatter のメソッド)
push_token() (shlex のメソッド)
push_with_producer() (async_chat のメソッド)
put() (Queue のメソッド)
put_nowait() (Queue のメソッド)
putch() (モジュール msvcrt)
putenv() (モジュール os)
putheader() (HTTPSConnection のメソッド)
putp() (モジュール curses)
putrequest() (HTTPSConnection のメソッド)
putsequences() (Folder のメソッド)
putwin() (window のメソッド)
pwd() (FTP のメソッド)
pwd (組み込み モジュール), [リンク]
pwlcurve() (モジュール gl)
py_compile (標準 モジュール)
PY_COMPILED (モジュール imp)
PY_FROZEN (モジュール imp)
PY_RESOURCE (モジュール imp)
PY_SOURCE (モジュール imp)
pyclbr (標準 モジュール)
PyCompileError
pydoc (標準 モジュール)
pyexpat (組み込み モジュール)
PyOpenGL
Python Editor
Python Imaging Library
PYTHON_DOM (environment variable)
PYTHON_DOM (環境変数)
PYTHONPATH (environment variable), [リンク], [リンク], [リンク]
PYTHONPATH (環境変数), [リンク], [リンク], [リンク]
PYTHONSTARTUP (environment variable), [リンク], [リンク]
PYTHONSTARTUP (環境変数), [リンク], [リンク]
PYTHONY2K (environment variable), [リンク], [リンク]
PYTHONY2K (環境変数), [リンク], [リンク]
PyZipFile (zipfile 内のクラス)

Q

qdevice() (モジュール fl)
qenter() (モジュール fl)
qiflush() (モジュール curses)
qread() (モジュール fl)
qreset() (モジュール fl)
qsize() (Queue のメソッド)
qtest() (モジュール fl)
QueryInfoKey() (モジュール _winreg)
queryparams() (モジュール al)
QueryValue() (モジュール _winreg)
QueryValueEx() (モジュール _winreg)
Queue (Queue 内の クラス)
Queue (標準 モジュール)
quick_ratio() (SequenceMatcher のメソッド)
quit() (FTP のメソッド)
quit() (NNTPDataError のメソッド)
quit() (POP3 のメソッド)
quit() (SMTP のメソッド)
quopri (標準 モジュール)
quote() (モジュール email.Utils)
quote() (モジュール rfc822)
quote() (モジュール urllib)
QUOTE_ALL (モジュール csv)
QUOTE_MINIMAL (モジュール csv)
QUOTE_NONE (モジュール csv)
QUOTE_NONNUMERIC (モジュール csv)
quote_plus() (モジュール urllib)
quoteattr() (モジュール xml.sax.saxutils)
quotechar (Dialect の属性)
quoted-printable
encoding
quotes (shlex の属性)
quoting (Dialect の属性)

R

r_eval() (RExec のメソッド)
r_exec() (RExec のメソッド)
r_execfile() (RExec のメソッド)
r_import() (RExec のメソッド)
R_OK (モジュール os)
r_open() (RExec のメソッド)
r_reload() (RExec のメソッド)
r_unload() (RExec のメソッド)
radians() (モジュール math)
radians() (モジュール turtle)
RADIXCHAR (モジュール locale)
raise 実行文
randint() (モジュール random)
randint() (モジュール whrandom)
random() (モジュール random)
random() (モジュール whrandom)
random (標準 モジュール)
randrange() (モジュール random)
range() (built-in function)
Rat (demo module)
ratecv() (モジュール audioop)
ratio() (SequenceMatcher のメソッド)
rational numbers
raw() (モジュール curses)
raw_input() (built-in function)
raw_input() (InteractiveConsole のメソッド)
raw_input() (組み込み関数)
RawConfigParser (ConfigParser 内の クラス)
RawPen (turtle 内の クラス)
re (MatchObject の属性)
re (標準 モジュール), [リンク], [リンク], [リンク]
read() (array のメソッド)
read() (audio device のメソッド), [リンク]
read() (BZ2File のメソッド)
read() (Chunk のメソッド)
read() (file のメソッド)
read() (HTTPSConnection のメソッド)
read() (IMAP4_stream のメソッド)
read() (LogRecord のメソッド)
read() (MimeTypes のメソッド)
read() (MultiFile のメソッド)
read() (Queue のメソッド)
read() (RobotFileParser のメソッド)
read() (SafeConfigParser のメソッド)
read() (StreamReader のメソッド)
read() (ZipFile のメソッド)
read() (モジュール imgfile)
read() (モジュール os)
read_all() (Telnet のメソッド)
read_byte() (Queue のメソッド)
read_eager() (Telnet のメソッド)
read_history_file() (モジュール readline)
read_init_file() (モジュール readline)
read_lazy() (Telnet のメソッド)
read_mime_types() (モジュール mimetypes)
read_sb_data() (Telnet のメソッド)
read_some() (Telnet のメソッド)
read_token() (shlex のメソッド)
read_until() (Telnet のメソッド)
read_very_eager() (Telnet のメソッド)
read_very_lazy() (Telnet のメソッド)
readable() (async_chat のメソッド)
readable() (dispatcher のメソッド)
readda() (CD player のメソッド)
reader() (モジュール csv)
ReadError
readfp() (MimeTypes のメソッド)
readfp() (SafeConfigParser のメソッド)
readframes() (aifc のメソッド)
readframes() (AU_read のメソッド)
readframes() (Wave_read のメソッド)
readline() (BZ2File のメソッド)
readline() (file のメソッド)
readline() (IMAP4_stream のメソッド)
readline() (MultiFile のメソッド)
readline() (Queue のメソッド)
readline() (StreamReader のメソッド)
readline (組み込み モジュール)
readlines() (BZ2File のメソッド)
readlines() (file のメソッド)
readlines() (MultiFile のメソッド)
readlines() (StreamReader のメソッド)
readlink() (モジュール os)
readmodule() (モジュール pyclbr)
readmodule_ex() (モジュール pyclbr)
readsamps() (audio port のメソッド)
readscaled() (モジュール imgfile)
READY (モジュール cd)
Real Media File Format
real_quick_ratio() (SequenceMatcher のメソッド)
realpath() (モジュール os.path)
reason (モジュール httplib)
reccontrols() (mixer device のメソッド)
recent() (IMAP4_stream のメソッド)
rectangle() (モジュール curses.textpad)
recv() (dispatcher のメソッド)
recv() (socket のメソッド)
recvfrom() (socket のメソッド)
redirect
redirect_request() (HTTPRedirectHandler のメソッド)
redraw_form() (form のメソッド)
redraw_object() (FORMS object のメソッド)
redrawln() (window のメソッド)
redrawwin() (window のメソッド)
reduce() (built-in function)
ref() (モジュール weakref)
ReferenceError, [リンク]
ReferenceType (モジュール weakref)
refilemessages() (Folder のメソッド)
refill_buffer() (async_chat のメソッド)
refresh() (window のメソッド)
register() (LogRecord のメソッド)
register() (モジュール atexit)
register() (モジュール codecs)
register() (モジュール webbrowser)
register_dialect() (モジュール csv)
register_error() (モジュール codecs)
register_function() (SimpleXMLRPCRequestHandler のメソッド)
register_function() (SimpleXMLRPCServer のメソッド)
register_instance() (SimpleXMLRPCRequestHandler のメソッド)
register_instance() (SimpleXMLRPCServer のメソッド)
register_introspection_functions() (SimpleXMLRPCRequestHandler のメソッド), [リンク]
register_multicall_functions() (SimpleXMLRPCRequestHandler のメソッド), [リンク]
registerDOMImplementation() (モジュール xml.dom)
RegLoadKey() (モジュール _winreg)
relative
URL
release() (Condition のメソッド)
release() (lock のメソッド)
release() (Semaphore のメソッド)
release() (Textbox のメソッド)
release() (Timer のメソッド), [リンク]
release_lock() (モジュール imp)
reload() (built-in function)
reload() (組み込み関数), [リンク], [リンク]
remove() (array のメソッド)
remove() (list method)
remove() (モジュール os)
remove_option() (SafeConfigParser のメソッド)
remove_option() (Textbox のメソッド)
remove_section() (SafeConfigParser のメソッド)
removeAttribute() (Element のメソッド)
removeAttributeNode() (Element のメソッド)
removeAttributeNS() (Element のメソッド)
removecallback() (CD parser のメソッド)
removeChild() (Node のメソッド)
removedirs() (モジュール os)
removeFilter() (Textbox のメソッド), [リンク]
removeHandler() (Textbox のメソッド)
removemessages() (Folder のメソッド)
rename() (FTP のメソッド)
rename() (IMAP4_stream のメソッド)
rename() (モジュール os)
renames() (モジュール os)
reorganize() (モジュール gdbm)
repeat() (Timer のメソッド)
repeat() (モジュール itertools)
repeat() (モジュール operator)
repetition
operation
replace() (date のメソッド)
replace() (datetime のメソッド)
replace() (string のメソッド)
replace() (Textbox のメソッド)
replace() (time のメソッド)
replace() (モジュール string)
replace_errors() (モジュール codecs)
replace_header() (Message のメソッド)
replace_whitespace (TextWrapper の属性)
replaceChild() (Node のメソッド)
report() (dircmp のメソッド)
report_full_closure() (dircmp のメソッド)
report_partial_closure() (dircmp のメソッド)
report_unbalanced() (SGMLParser のメソッド)
repr() (built-in function)
repr() (Repr のメソッド)
Repr (repr 内の クラス)
repr() (モジュール repr)
repr (標準 モジュール)
repr1() (Repr のメソッド)
request() (HTTPSConnection のメソッド)
Request (urllib2 内の クラス)
request_queue_size (SocketServer protocol)
request_version (BaseHTTPRequestHandler の属性)
RequestHandlerClass (SocketServer protocol)
requires() (モジュール test.test_support)
reserved (ZipInfo の属性)
reset() (audio device のメソッド)
reset() (DOMEventStream のメソッド)
reset() (HTMLParser のメソッド)
reset() (IncrementalParser のメソッド)
reset() (Packer のメソッド)
reset() (SGMLParser のメソッド)
reset() (StreamReader のメソッド)
reset() (StreamWriter のメソッド)
reset() (Template のメソッド)
reset() (Unpacker のメソッド)
reset() (XMLParser のメソッド)
reset() (モジュール statcache)
reset() (モジュール turtle)
reset_prog_mode() (モジュール curses)
reset_shell_mode() (モジュール curses)
resetbuffer() (InteractiveConsole のメソッド)
resetlocale() (モジュール locale)
resetparser() (CD parser のメソッド)
resetwarnings() (モジュール warnings)
resize() (Queue のメソッド)
resolution (date の属性)
resolution (datetime の属性)
resolution (time の属性)
resolution (timedelta の属性)
resolveEntity() (EntityResolver のメソッド)
resource (組み込み モジュール)
ResourceDenied
response() (IMAP4_stream のメソッド)
ResponseNotReady
responses (BaseHTTPRequestHandler の属性)
restore() (モジュール difflib)
retr() (POP3 のメソッド)
retrbinary() (FTP のメソッド)
retrieve() (URLopener のメソッド)
retrlines() (FTP のメソッド)
returns_unicode (xmlparser の属性)
reverse() (array のメソッド)
reverse() (list method)
reverse() (モジュール audioop)
reverse_order() (Stats のメソッド)
rewind() (aifc のメソッド)
rewind() (AU_read のメソッド)
rewind() (Wave_read のメソッド)
rewindbody() (AddressList のメソッド)
RExec (rexec 内の クラス)
rexec (標準 モジュール), [リンク]
rfc822 (標準 モジュール), [リンク]
rfile (BaseHTTPRequestHandler の属性)
rfind() (string のメソッド)
rfind() (モジュール string)
rgb_to_hls() (モジュール colorsys)
rgb_to_hsv() (モジュール colorsys)
rgb_to_yiq() (モジュール colorsys)
rgbimg (組み込み モジュール)
right() (モジュール turtle)
right_list (dircmp の属性)
right_only (dircmp の属性)
rindex() (string のメソッド)
rindex() (モジュール string)
rjust() (string のメソッド)
rjust() (モジュール string)
rlcompleter (標準 モジュール)
rlecode_hqx() (モジュール binascii)
rledecode_hqx() (モジュール binascii)
RLIMIT_AS (モジュール resource)
RLIMIT_CORE (モジュール resource)
RLIMIT_CPU (モジュール resource)
RLIMIT_DATA (モジュール resource)
RLIMIT_FSIZE (モジュール resource)
RLIMIT_MEMLOCK (モジュール resource)
RLIMIT_NOFILE (モジュール resource)
RLIMIT_NPROC (モジュール resource)
RLIMIT_OFILE (モジュール resource)
RLIMIT_RSS (モジュール resource)
RLIMIT_STACK (モジュール resource)
RLIMIT_VMEM (モジュール resource)
RLock() (モジュール threading)
rmd() (FTP のメソッド)
rmdir() (モジュール os)
RMFF
rms() (モジュール audioop)
rmtree() (モジュール shutil)
rnopen() (モジュール bsddb)
RobotFileParser (robotparser 内の クラス)
robotparser (標準 モジュール)
robots.txt
RotatingFileHandler (logging 内の クラス)
rotor (組み込み モジュール)
round() (built-in function)
rpop() (POP3 のメソッド)
rset() (POP3 のメソッド)
rshift() (モジュール operator)
rstrip() (string のメソッド)
rstrip() (モジュール string)
RTLD_LAZY (モジュール dl)
RTLD_NOW (モジュール dl)
ruler (Cmd の属性)
run() (Profile のメソッド)
run() (scheduler のメソッド)
run() (TestCase のメソッド)
run() (TestSuite のメソッド)
run() (Thread のメソッド)
run() (モジュール pdb)
run() (モジュール profile)
Run script
run_suite() (モジュール test.test_support)
run_unittest() (モジュール test.test_support)
runcall() (Profile のメソッド)
runcall() (モジュール pdb)
runcode() (InteractiveConsole のメソッド)
runctx() (Profile のメソッド)
runeval() (モジュール pdb)
runsource() (InteractiveConsole のメソッド)
RuntimeError
RuntimeWarning
RUSAGE_BOTH (モジュール resource)
RUSAGE_CHILDREN (モジュール resource)
RUSAGE_SELF (モジュール resource)

S

S (モジュール re)
s_eval() (RExec のメソッド)
s_exec() (RExec のメソッド)
s_execfile() (RExec のメソッド)
S_IFMT() (モジュール stat)
S_IMODE() (モジュール stat)
s_import() (RExec のメソッド)
S_ISBLK() (モジュール stat)
S_ISCHR() (モジュール stat)
S_ISDIR() (モジュール stat)
S_ISFIFO() (モジュール stat)
S_ISLNK() (モジュール stat)
S_ISREG() (モジュール stat)
S_ISSOCK() (モジュール stat)
s_reload() (RExec のメソッド)
s_unload() (RExec のメソッド)
SafeConfigParser (ConfigParser 内の クラス)
saferepr() (モジュール pprint)
same_files (dircmp の属性)
samefile() (モジュール os.path)
sameopenfile() (モジュール os.path)
samestat() (モジュール os.path)
sample() (モジュール random)
save_bgn() (HTMLParser のメソッド)
save_end() (HTMLParser のメソッド)
SaveKey() (モジュール _winreg)
SAX2DOM (xml.dom.pulldom 内の クラス)
SAXException (xml.sax 内の 例外)
SAXNotRecognizedException (xml.sax 内の 例外)
SAXNotSupportedException (xml.sax 内の 例外)
SAXParseException (xml.sax 内の 例外)
scale() (モジュール imageop)
scanf() (モジュール re)
sched (標準 モジュール)
scheduler (sched 内の クラス)
sci() (モジュール fpformat)
scroll() (window のメソッド)
ScrolledText (標準 モジュール)
scrollok() (window のメソッド)
search
path, module, [リンク], [リンク]
search() (IMAP4_stream のメソッド)
search() (RegexObject のメソッド)
search() (モジュール re)
SEARCH_ERROR (モジュール imp)
second (datetime の属性)
second (time の属性)
section_divider() (MultiFile のメソッド)
sections() (SafeConfigParser のメソッド)
Secure Hash Algorithm
security
CGI
seed() (whrandom のメソッド)
seed() (モジュール random)
seed() (モジュール whrandom)
seek() (BZ2File のメソッド)
seek() (CD player のメソッド)
seek() (Chunk のメソッド)
seek() (file のメソッド)
seek() (MultiFile のメソッド)
seek() (Queue のメソッド)
SEEK_CUR (モジュール posixfile)
SEEK_END (モジュール posixfile)
SEEK_SET (モジュール posixfile)
seekblock() (CD player のメソッド)
seektrack() (CD player のメソッド)
select() (IMAP4_stream のメソッド)
Select (Tix 内の クラス)
select() (モジュール gl)
select() (モジュール select)
select (組み込み モジュール)
Semaphore (threading 内の クラス)
Semaphore() (モジュール threading)
semaphores, binary
send() (DatagramHandler のメソッド)
send() (dispatcher のメソッド)
send() (HTTPSConnection のメソッド)
send() (IMAP4_stream のメソッド)
send() (socket のメソッド)
send() (SocketHandler のメソッド)
send_error() (BaseHTTPRequestHandler のメソッド)
send_flowing_data() (writer のメソッド)
send_header() (BaseHTTPRequestHandler のメソッド)
send_hor_rule() (writer のメソッド)
send_label_data() (writer のメソッド)
send_line_break() (writer のメソッド)
send_literal_data() (writer のメソッド)
send_paragraph() (writer のメソッド)
send_query() (モジュール gopherlib)
send_response() (BaseHTTPRequestHandler のメソッド)
send_selector() (モジュール gopherlib)
sendall() (socket のメソッド)
sendcmd() (FTP のメソッド)
sendmail() (SMTP のメソッド)
sendto() (socket のメソッド)
sep (モジュール os)
sequence
iteration
types, mutable
types, operations on, [リンク]
types, operations on mutable
sequence オブジェクト
sequence2ast() (モジュール parser)
sequenceIncludes() (モジュール operator)
SequenceMatcher (difflib 内の クラス)
SequenceMatcher (difflib 内のクラス)
SerialCookie (Cookie 内の クラス)
serializing
objects
serve_forever() (SocketServer protocol)
server
WWW, [リンク]
server_activate() (SocketServer protocol)
server_address (SocketServer protocol)
server_bind() (SocketServer protocol)
server_version (BaseHTTPRequestHandler の属性)
server_version (SimpleHTTPRequestHandler の属性)
ServerProxy (xmlrpclib 内の クラス)
set() (Event のメソッド)
set() (mixer device のメソッド)
set() (Morsel のメソッド)
set() (SafeConfigParser のメソッド)
Set (sets 内の クラス)
set_boundary() (Message のメソッド)
set_call_back() (FORMS object のメソッド)
set_charset() (Message のメソッド)
set_completer() (モジュール readline)
set_completer_delims() (モジュール readline)
set_debug() (モジュール gc)
set_debuglevel() (FTP のメソッド)
set_debuglevel() (HTTPSConnection のメソッド)
set_debuglevel() (NNTPDataError のメソッド)
set_debuglevel() (POP3 のメソッド)
set_debuglevel() (SMTP のメソッド)
set_debuglevel() (Telnet のメソッド)
set_default_type() (Message のメソッド)
set_event_call_back() (モジュール fl)
set_form_position() (form のメソッド)
set_graphics_mode() (モジュール fl)
set_history_length() (モジュール readline)
set_location() (Queue のメソッド)
set_option_negotiation_callback() (Telnet のメソッド)
set_param() (Message のメソッド)
set_pasv() (FTP のメソッド)
set_payload() (Message のメソッド)
set_position() (Unpacker のメソッド)
set_pre_input_hook() (モジュール readline)
set_proxy() (Request のメソッド)
set_recsrc() (mixer device のメソッド)
set_seq1() (SequenceMatcher のメソッド)
set_seq2() (SequenceMatcher のメソッド)
set_seqs() (SequenceMatcher のメソッド)
set_server_documentation() (DocXMLRPCRequestHandler のメソッド), [リンク]
set_server_name() (DocXMLRPCRequestHandler のメソッド), [リンク]
set_server_title() (DocXMLRPCRequestHandler のメソッド), [リンク]
set_spacing() (formatter のメソッド)
set_startup_hook() (モジュール readline)
set_terminator() (async_chat のメソッド)
set_threshold() (モジュール gc)
set_trace() (モジュール pdb)
set_type() (Message のメソッド)
set_unixfrom() (Message のメソッド)
set_url() (RobotFileParser のメソッド)
set_userptr() (Textbox のメソッド)
setacl() (IMAP4_stream のメソッド)
setattr() (built-in function)
setAttribute() (Element のメソッド)
setAttributeNode() (Element のメソッド)
setAttributeNodeNS() (Element のメソッド)
setAttributeNS() (Element のメソッド)
SetBase() (xmlparser のメソッド)
setblocking() (socket のメソッド)
setByteStream() (InputSource のメソッド)
setcbreak() (モジュール tty)
setchannels() (audio configuration のメソッド)
setCharacterStream() (InputSource のメソッド)
setcheckinterval() (モジュール sys)
setcomptype() (aifc のメソッド)
setcomptype() (AU_write のメソッド)
setcomptype() (Wave_write のメソッド)
setconfig() (audio port のメソッド)
setContentHandler() (XMLReader のメソッド)
setcontext() (MH のメソッド)
setcurrent() (Folder のメソッド)
setDaemon() (Thread のメソッド)
setdefault() (dictionary method)
setdefaultencoding() (モジュール sys)
setdefaulttimeout() (モジュール socket)
setdlopenflags() (モジュール sys)
setDocumentLocator() (ContentHandler のメソッド)
setDTDHandler() (XMLReader のメソッド)
setegid() (モジュール os)
setEncoding() (InputSource のメソッド)
setEntityResolver() (XMLReader のメソッド)
setErrorHandler() (XMLReader のメソッド)
seteuid() (モジュール os)
setFeature() (XMLReader のメソッド)
setfillpoint() (audio port のメソッド)
setfirstweekday() (モジュール calendar)
setfloatmax() (audio configuration のメソッド)
setfmt() (audio device のメソッド)
setFormatter() (Textbox のメソッド)
setframerate() (aifc のメソッド)
setframerate() (AU_write のメソッド)
setframerate() (Wave_write のメソッド)
setgid() (モジュール os)
setgroups() (モジュール os)
setinfo() (audio device のメソッド)
setitem() (モジュール operator)
setkey() (rotor のメソッド)
setlast() (Folder のメソッド)
setLevel() (Textbox のメソッド), [リンク]
setliteral() (SGMLParser のメソッド)
setliteral() (XMLParser のメソッド)
setLocale() (XMLReader のメソッド)
setlocale() (モジュール locale)
setLoggerClass() (モジュール logging)
setlogmask() (モジュール syslog)
setmark() (aifc のメソッド)
setMaxConns() (CacheFTPHandler のメソッド)
setmode() (モジュール msvcrt)
setName() (Thread のメソッド)
setnchannels() (aifc のメソッド)
setnchannels() (AU_write のメソッド)
setnchannels() (Wave_write のメソッド)
setnframes() (aifc のメソッド)
setnframes() (AU_write のメソッド)
setnframes() (Wave_write のメソッド)
setnomoretags() (SGMLParser のメソッド)
setnomoretags() (XMLParser のメソッド)
setoption() (モジュール jpeg)
setparameters() (audio device のメソッド)
setparams() (aifc のメソッド)
setparams() (AU_write のメソッド)
setparams() (Wave_write のメソッド)
setparams() (モジュール al)
setpath() (モジュール fm)
setpgid() (モジュール os)
setpgrp() (モジュール os)
setpos() (aifc のメソッド)
setpos() (AU_read のメソッド)
setpos() (Wave_read のメソッド)
setprofile() (モジュール sys)
setprofile() (モジュール threading)
setProperty() (XMLReader のメソッド)
setPublicId() (InputSource のメソッド)
setqueuesize() (audio configuration のメソッド)
setquota() (IMAP4_stream のメソッド)
setraw() (モジュール tty)
setrecursionlimit() (モジュール sys)
setregid() (モジュール os)
setreuid() (モジュール os)
setrlimit() (モジュール resource)
sets (標準 モジュール)
setsampfmt() (audio configuration のメソッド)
setsampwidth() (aifc のメソッド)
setsampwidth() (AU_write のメソッド)
setsampwidth() (Wave_write のメソッド)
setscrreg() (window のメソッド)
setsid() (モジュール os)
setslice() (モジュール operator)
setsockopt() (socket のメソッド)
setstate() (モジュール random)
setSystemId() (InputSource のメソッド)
setsyx() (モジュール curses)
setTarget() (MemoryHandler のメソッド)
setTimeout() (CacheFTPHandler のメソッド)
settimeout() (socket のメソッド)
settrace() (モジュール sys)
settrace() (モジュール threading)
setuid() (モジュール os)
setup() (SocketServer protocol)
setUp() (TestCase のメソッド)
setupterm() (モジュール curses)
SetValue() (モジュール _winreg)
SetValueEx() (モジュール _winreg)
setwidth() (audio configuration のメソッド)
SGML
sgmllib (標準 モジュール), [リンク]
SGMLParser (in module sgmllib)
SGMLParser (sgmllib 内の クラス)
sha (組み込み モジュール)
Shelf (shelve 内の クラス)
shelve (標準 モジュール), [リンク]
shifting
operations
shlex (shlex 内の クラス)
shlex (標準 モジュール)
shortDescription() (TestCase のメソッド)
shouldFlush() (BufferingHandler のメソッド)
shouldFlush() (MemoryHandler のメソッド)
show() (Textbox のメソッド)
show_choice() (モジュール fl)
show_file_selector() (モジュール fl)
show_form() (form のメソッド)
show_input() (モジュール fl)
show_message() (モジュール fl)
show_object() (FORMS object のメソッド)
show_question() (モジュール fl)
showsyntaxerror() (InteractiveConsole のメソッド)
showtraceback() (InteractiveConsole のメソッド)
showwarning() (モジュール warnings)
shuffle() (モジュール random)
shutdown() (IMAP4_stream のメソッド)
shutdown() (socket のメソッド)
shutdown() (モジュール logging)
shutil (標準 モジュール)
SIG* (モジュール signal)
SIG_DFL (モジュール signal)
SIG_IGN (モジュール signal)
signal() (モジュール signal)
signal (組み込み モジュール), [リンク]
Simple Mail Transfer Protocol
simple_producer (asynchat 内の クラス)
SimpleCookie (Cookie 内の クラス)
SimpleHTTPRequestHandler (SimpleHTTPServer 内の クラス)
SimpleHTTPServer (標準 モジュール), [リンク]
SimpleXMLRPCRequestHandler (SimpleXMLRPCServer 内の クラス)
SimpleXMLRPCServer (SimpleXMLRPCServer 内の クラス)
SimpleXMLRPCServer (標準 モジュール)
sin() (モジュール cmath)
sin() (モジュール math)
sinh() (モジュール cmath)
sinh() (モジュール math)
site (標準 モジュール)
site-packages
directory
site-python
directory
sitecustomize (モジュール), [リンク]
size() (FTP のメソッド)
size() (Queue のメソッド)
size (TarInfo の属性)
sizeofimage() (モジュール rgbimg)
skip() (Chunk のメソッド)
skipinitialspace (Dialect の属性)
skippedEntity() (ContentHandler のメソッド)
slave() (NNTPDataError のメソッド)
sleep() (モジュール time)
slice
assignment
operation
slice() (built-in function)
slice() (組み込み関数), [リンク]
SliceType (モジュール types)
SmartCookie (Cookie 内の クラス)
SMTP
protocol
SMTP (smtplib 内の クラス)
SMTPConnectError
SMTPDataError
SMTPException
SMTPHandler (logging 内の クラス)
SMTPHeloError
smtplib (標準 モジュール)
SMTPRecipientsRefused
SMTPResponseException
SMTPSenderRefused
SMTPServerDisconnected
SND_ALIAS (モジュール winsound)
SND_ASYNC (モジュール winsound)
SND_FILENAME (モジュール winsound)
SND_LOOP (モジュール winsound)
SND_MEMORY (モジュール winsound)
SND_NODEFAULT (モジュール winsound)
SND_NOSTOP (モジュール winsound)
SND_NOWAIT (モジュール winsound)
SND_PURGE (モジュール winsound)
sndhdr (標準 モジュール)
sniff() (Sniffer のメソッド)
Sniffer (csv 内の クラス)
SO_* (モジュール socket)
SOCK_DGRAM (モジュール socket)
SOCK_RAW (モジュール socket)
SOCK_RDM (モジュール socket)
SOCK_SEQPACKET (モジュール socket)
SOCK_STREAM (モジュール socket)
socket() (IMAP4_stream のメソッド)
socket() (in module socket)
socket (SocketServer protocol)
socket() (モジュール socket)
socket (組み込み モジュール), [リンク], [リンク]
socket オブジェクト
socket_type (SocketServer protocol)
SocketHandler (logging 内の クラス)
SocketServer (標準 モジュール)
SocketType (モジュール socket)
softspace (file の属性)
SOL_* (モジュール socket)
SOMAXCONN (モジュール socket)
sort() (IMAP4_stream のメソッド)
sort() (list method)
sort_stats() (Stats のメソッド)
sortTestMethodsUsing (TestLoader の属性)
source (shlex の属性)
sourcehook() (shlex のメソッド)
span() (MatchObject のメソッド)
spawn() (モジュール pty)
spawnl() (モジュール os)
spawnle() (モジュール os)
spawnlp() (モジュール os)
spawnlpe() (モジュール os)
spawnv() (モジュール os)
spawnve() (モジュール os)
spawnvp() (モジュール os)
spawnvpe() (モジュール os)
specified_attributes (xmlparser の属性)
speed() (audio device のメソッド)
split() (RegexObject のメソッド)
split() (string のメソッド)
split() (モジュール os.path)
split() (モジュール re)
split() (モジュール shlex)
split() (モジュール string)
splitdrive() (モジュール os.path)
splitext() (モジュール os.path)
splitfields() (モジュール string)
splitlines() (string のメソッド)
sprintf-style formatting
sqrt() (モジュール cmath)
sqrt() (モジュール math)
sqrt() (モジュール mpz)
sqrtrem() (モジュール mpz)
ssl() (IMAP4_stream のメソッド)
ssl() (モジュール socket)
ST_ATIME (モジュール stat)
ST_CTIME (モジュール stat)
ST_DEV (モジュール stat)
ST_GID (モジュール stat)
ST_INO (モジュール stat)
ST_MODE (モジュール stat)
ST_MTIME (モジュール stat)
ST_NLINK (モジュール stat)
ST_SIZE (モジュール stat)
ST_UID (モジュール stat)
stack viewer
stackable
streams
StandardError
standend() (window のメソッド)
standout() (window のメソッド)
starmap() (モジュール itertools)
start() (MatchObject のメソッド)
start() (Profile のメソッド)
start() (Thread のメソッド)
start_color() (モジュール curses)
start_new_thread() (モジュール thread)
startbody() (MimeWriter のメソッド)
StartCdataSectionHandler() (xmlparser のメソッド)
StartDoctypeDeclHandler() (xmlparser のメソッド)
startDocument() (ContentHandler のメソッド)
startElement() (ContentHandler のメソッド)
StartElementHandler() (xmlparser のメソッド)
startElementNS() (ContentHandler のメソッド)
startfile() (モジュール os)
startmultipartbody() (MimeWriter のメソッド)
StartNamespaceDeclHandler() (xmlparser のメソッド)
startPrefixMapping() (ContentHandler のメソッド)
startswith() (string のメソッド)
startTest() (TestResult のメソッド)
starttls() (SMTP のメソッド)
stat() (NNTPDataError のメソッド)
stat() (POP3 のメソッド)
stat() (モジュール os)
stat() (モジュール statcache)
stat (標準 モジュール), [リンク]
stat_float_times() (モジュール os)
statcache (標準 モジュール)
staticmethod() (built-in function)
Stats (profile 内の クラス)
status() (IMAP4_stream のメソッド)
status (モジュール httplib)
statvfs() (モジュール os)
statvfs (標準 モジュール), [リンク]
StdButtonBox (Tix 内の クラス)
stderr (モジュール sys)
stdin (モジュール sys)
stdout (モジュール sys)
Stein, Greg
stereocontrols() (mixer device のメソッド)
STILL (モジュール cd)
stop() (CD player のメソッド)
stop() (Profile のメソッド)
stop() (TestResult のメソッド)
StopIteration
stopListening() (モジュール logging)
stopTest() (TestResult のメソッド)
storbinary() (FTP のメソッド)
store() (IMAP4_stream のメソッド)
STORE_ACTIONS (Textbox の属性)
storlines() (FTP のメソッド)
str() (built-in function)
str() (モジュール locale)
strcoll() (モジュール locale)
StreamError
StreamHandler (logging 内の クラス)
StreamReader (codecs 内の クラス)
StreamReaderWriter (codecs 内の クラス)
StreamRecoder (codecs 内の クラス)
streams
stackable
StreamWriter (codecs 内の クラス)
strerror() (モジュール os)
strftime() (date のメソッド)
strftime() (datetime のメソッド)
strftime() (time のメソッド)
strftime() (モジュール time)
strict_errors() (モジュール codecs)
string
documentation
formatting
interpolation
string (MatchObject の属性)
string (標準 モジュール), [リンク], [リンク], [リンク]
string オブジェクト
StringIO (StringIO 内の クラス)
StringIO (標準 モジュール)
stringprep (標準 モジュール)
StringType (モジュール types)
StringTypes (モジュール types)
strip() (string のメソッド)
strip() (モジュール string)
strip_dirs() (Stats のメソッド)
stripspaces (Textbox の属性)
strptime() (モジュール time)
struct (組み込み モジュール), [リンク], [リンク]
struct_time (モジュール time)
structures
C
strxfrm() (モジュール locale)
sub() (RegexObject のメソッド)
sub() (モジュール operator)
sub() (モジュール re)
subdirs (dircmp の属性)
subn() (RegexObject のメソッド)
subn() (モジュール re)
subpad() (window のメソッド)
subscribe() (IMAP4_stream のメソッド)
subscript
assignment
operation
subsequent_indent (TextWrapper の属性)
subwin() (window のメソッド)
suffix_map (モジュール mimetypes), [リンク]
suite() (モジュール parser)
suiteClass (TestLoader の属性)
sum() (built-in function)
sunau (標準 モジュール)
SUNAUDIODEV (標準 モジュール), [リンク]
sunaudiodev (組み込み モジュール), [リンク]
super() (built-in function)
super (class descriptor の属性)
supports_unicode_filenames (モジュール os.path)
swapcase() (string のメソッド)
swapcase() (モジュール string)
sym() (TarInfo のメソッド)
sym_name (モジュール symbol)
symbol (標準 モジュール)
symbol table
symlink() (モジュール os)
sync() (audio device のメソッド)
sync() (dbhash のメソッド)
sync() (Queue のメソッド), [リンク]
sync() (モジュール gdbm)
syncdown() (window のメソッド)
syncok() (window のメソッド)
syncup() (window のメソッド)
syntax_error() (XMLParser のメソッド)
SyntaxErr
SyntaxError
SyntaxWarning
sys (組み込み モジュール)
sys_version (BaseHTTPRequestHandler の属性)
sysconf() (モジュール os)
sysconf_names (モジュール os)
syslog() (モジュール syslog)
syslog (組み込み モジュール)
SysLogHandler (logging 内の クラス)
system() (モジュール os)
system.listMethods() (ServerProxy のメソッド)
system.methodHelp() (ServerProxy のメソッド)
system.methodSignature() (ServerProxy のメソッド)
SystemError
SystemExit
systemId (DocumentType の属性)

T

T_FMT (モジュール locale)
T_FMT_AMPM (モジュール locale)
tabnanny (標準 モジュール)
tabular
data
tagName (Element の属性)
takewhile() (モジュール itertools)
tan() (モジュール cmath)
tan() (モジュール math)
tanh() (モジュール cmath)
tanh() (モジュール math)
TAR_GZIPPED (モジュール tarfile)
TAR_PLAIN (モジュール tarfile)
TarError
TarFile (tarfile 内の クラス)
TarFile (tarfile 内のクラス)
tarfile (標準 モジュール)
TarFileCompat (tarfile 内の クラス)
target (ProcessingInstruction の属性)
TarInfo (tarfile 内の クラス)
tb_lineno() (モジュール traceback)
tcdrain() (モジュール termios)
tcflow() (モジュール termios)
tcflush() (モジュール termios)
tcgetattr() (モジュール termios)
tcgetpgrp() (モジュール os)
TCP_* (モジュール socket)
tcsendbreak() (モジュール termios)
tcsetattr() (モジュール termios)
tcsetpgrp() (モジュール os)
tearDown() (TestCase のメソッド)
tell() (aifc のメソッド), [リンク]
tell() (AU_read のメソッド)
tell() (AU_write のメソッド)
tell() (BZ2File のメソッド)
tell() (Chunk のメソッド)
tell() (file のメソッド)
tell() (MultiFile のメソッド)
tell() (Queue のメソッド)
tell() (Wave_read のメソッド)
tell() (Wave_write のメソッド)
Telnet (telnetlib 内の クラス)
telnetlib (標準 モジュール)
TEMP (environment variable)
TEMP (環境変数)
tempdir (モジュール tempfile)
tempfile (標準 モジュール)
Template (pipes 内の クラス)
template (モジュール tempfile)
tempnam() (モジュール os)
temporary
file
file name
TemporaryFile() (モジュール tempfile)
termattrs() (モジュール curses)
TERMIOS (標準 モジュール)
termios (組み込み モジュール), [リンク]
termname() (モジュール curses)
test() (mutex のメソッド)
test() (モジュール cgi)
test (標準 モジュール)
test.test_support (標準 モジュール)
testandset() (mutex のメソッド)
TestCase (unittest 内の クラス)
TestFailed
TESTFN (モジュール test.test_support)
TestLoader (unittest 内の クラス)
testMethodPrefix (TestLoader の属性)
testmod() (モジュール doctest)
tests (モジュール imghdr)
TestSkipped
testsource() (モジュール doctest)
testsRun (TestResult の属性)
TestSuite (unittest 内の クラス)
testzip() (ZipFile のメソッド)
Textbox (curses.textpad 内の クラス)
textdomain() (モジュール gettext)
TextTestRunner (unittest 内の クラス)
textwrap (標準 モジュール)
TextWrapper (textwrap 内の クラス)
THOUSEP (モジュール locale)
Thread (threading 内の クラス)
Thread (threading 内のクラス)
thread (組み込み モジュール)
threading (標準 モジュール)
threads
\POSIX
IRIX
tie() (モジュール fl)
tigetflag() (モジュール curses)
tigetnum() (モジュール curses)
tigetstr() (モジュール curses)
time() (datetime のメソッド)
time (datetime 内の クラス)
time (datetime 内のクラス)
time() (モジュール time)
time (組み込み モジュール)
Time2Internaldate() (モジュール imaplib)
timedelta (datetime 内の クラス)
timedelta (datetime 内のクラス)
timegm() (モジュール calendar)
timeit() (Timer のメソッド)
timeit (標準 モジュール)
timeout
timeout() (window のメソッド)
Timer (threading 内の クラス)
Timer (threading 内のクラス)
Timer (timeit 内の クラス)
times() (モジュール os)
timetuple() (date のメソッド)
timetuple() (datetime のメソッド)
timetz() (datetime のメソッド)
timezone (モジュール time)
title() (string のメソッド)
Tix
Tix (Tix 内の クラス)
Tix (標準 モジュール)
tix_addbitmapdir() (tixCommand のメソッド)
tix_cget() (tixCommand のメソッド)
tix_configure() (tixCommand のメソッド)
tix_filedialog() (tixCommand のメソッド)
tix_getbitmap() (tixCommand のメソッド)
tix_getimage() (tixCommand のメソッド)
TIX_LIBRARY (environment variable)
TIX_LIBRARY (環境変数)
tix_option_get() (tixCommand のメソッド)
tix_resetoptions() (tixCommand のメソッド)
tixCommand (Tix 内の クラス)
Tk
Tk (Tkinter 内の クラス)
Tk Option Data Types
Tkinter
Tkinter (標準 モジュール)
TList (Tix 内の クラス)
TMP (environment variable)
TMP (環境変数)
TMP_MAX (モジュール os)
TMPDIR (environment variable)
TMPDIR (環境変数)
tmpfile() (モジュール os)
tmpnam() (モジュール os)
to_splittable() (Charset のメソッド)
ToASCII() (モジュール encodings.idna)
tobuf() (TarInfo のメソッド)
tochild (Popen4 の属性)
today() (date のメソッド)
today() (datetime のメソッド)
tofile() (array のメソッド)
togglepause() (CD player のメソッド)
tok_name (モジュール token)
token (shlex の属性)
token (標準 モジュール)
tokeneater() (モジュール tabnanny)
tokenize() (モジュール tokenize)
tokenize (標準 モジュール)
tolist() (array のメソッド)
tolist() (AST のメソッド)
tomono() (モジュール audioop)
toordinal() (date のメソッド)
toordinal() (datetime のメソッド)
top() (POP3 のメソッド)
top() (Textbox のメソッド)
top_panel() (モジュール curses.panel)
toprettyxml() (HTMLParser のメソッド)
tostereo() (モジュール audioop)
tostring() (array のメソッド)
totuple() (AST のメソッド)
touchline() (window のメソッド)
touchwin() (window のメソッド)
tounicode() (array のメソッド)
ToUnicode() (モジュール encodings.idna)
tovideo() (モジュール imageop)
toxml() (HTMLParser のメソッド)
tparm() (モジュール curses)
trace function
traceback (標準 モジュール)
traceback オブジェクト, [リンク]
tracebacklimit (モジュール sys)
tracebacks
in CGI scripts
TracebackType (モジュール types)
tracer() (モジュール turtle)
transfercmd() (FTP のメソッド)
translate() (string のメソッド)
translate() (モジュール string)
translate_references() (XMLParser のメソッド)
translation() (モジュール gettext)
Tree (Tix 内の クラス)
True, [リンク]
true
True (built-in exception)
truediv() (モジュール operator)
truncate() (file のメソッド)
truth
value
truth() (モジュール operator)
try 実行文
ttob() (モジュール imgfile)
ttob() (モジュール rgbimg)
tty
I/O control, [リンク]
tty (標準 モジュール)
ttyname() (モジュール os)
tuple() (built-in function)
tuple オブジェクト
tuple2ast() (モジュール parser)
TupleType (モジュール types)
turnoff_sigfpe() (モジュール fpectl)
turnon_sigfpe() (モジュール fpectl)
turtle (標準 モジュール)
Tutt, Bill
type
Boolean
operations on dictionary
operations on list
type() (built-in function)
type (TarInfo の属性)
type() (組み込み関数), [リンク]
type オブジェクト
typeahead() (モジュール curses)
typecode (array の属性)
TYPED_ACTIONS (Textbox の属性)
typed_subpart_iterator() (モジュール email.Iterators)
TypeError
types
built-in, [リンク]
mutable sequence
operations on integer
operations on mapping
operations on mutable sequence
operations on numeric
operations on sequence, [リンク]
types (標準 モジュール), [リンク], [リンク]
types_map (モジュール mimetypes), [リンク]
TypeType (モジュール types)
TZ (environment variable), [リンク], [リンク], [リンク], [リンク], [リンク]
TZ (環境変数), [リンク], [リンク], [リンク], [リンク], [リンク]
tzinfo (datetime の属性)
tzinfo (datetime 内のクラス)
tzinfo (time の属性)
tzname() (datetime のメソッド)
tzname() (time のメソッド), [リンク]
tzname (モジュール time)
tzset() (モジュール time)

U

U (モジュール re)
u-LAW, [リンク], [リンク], [リンク]
ugettext() (GNUTranslations のメソッド)
ugettext() (NullTranslations のメソッド)
uid() (IMAP4_stream のメソッド)
uid, gid (TarInfo の属性)
uidl() (POP3 のメソッド)
ulaw2lin() (モジュール audioop)
umask() (モジュール os)
uname() (モジュール os)
uname, gname (TarInfo の属性)
UnboundLocalError
UnboundMethodType (モジュール types)
unbuffered I/O
UNC paths
and os.makedirs()
unconsumed_tail (Queue の属性)
unctrl() (モジュール curses)
unctrl() (モジュール curses.ascii)
undoc_header (Cmd の属性)
unescape() (モジュール xml.sax.saxutils)
unfreeze_form() (form のメソッド)
unfreeze_object() (FORMS object のメソッド)
ungetch() (モジュール curses)
ungetch() (モジュール msvcrt)
ungetmouse() (モジュール curses)
ungettext() (GNUTranslations のメソッド)
ungettext() (NullTranslations のメソッド)
unhexlify() (モジュール binascii)
unichr() (built-in function)
Unicode, [リンク]
database
unicode() (built-in function)
UNICODE (モジュール re)
Unicode オブジェクト
unicodedata (標準 モジュール)
UnicodeDecodeError
UnicodeEncodeError
UnicodeError
UnicodeTranslateError
UnicodeType (モジュール types)
unidata_version (モジュール unicodedata)
unified_diff() (モジュール difflib)
uniform() (モジュール random)
uniform() (モジュール whrandom)
UnimplementedFileMode
unittest (標準 モジュール)
\UNIX
file control
I/O control
unixfrom (AddressList の属性)
UnixMailbox (mailbox 内の クラス)
unknown_charref() (SGMLParser のメソッド)
unknown_charref() (XMLParser のメソッド)
unknown_endtag() (SGMLParser のメソッド)
unknown_endtag() (XMLParser のメソッド)
unknown_entityref() (SGMLParser のメソッド)
unknown_entityref() (XMLParser のメソッド)
unknown_open() (BaseHandler のメソッド)
unknown_open() (UnknownHandler のメソッド)
unknown_starttag() (SGMLParser のメソッド)
unknown_starttag() (XMLParser のメソッド)
UnknownHandler (urllib2 内の クラス)
UnknownProtocol
UnknownTransferEncoding
unlink() (HTMLParser のメソッド)
unlink() (モジュール os)
unlock() (mutex のメソッド)
unmimify() (モジュール mimify)
unpack() (モジュール struct)
unpack_array() (Unpacker のメソッド)
unpack_bytes() (Unpacker のメソッド)
unpack_double() (Unpacker のメソッド)
unpack_farray() (Unpacker のメソッド)
unpack_float() (Unpacker のメソッド)
unpack_fopaque() (Unpacker のメソッド)
unpack_fstring() (Unpacker のメソッド)
unpack_list() (Unpacker のメソッド)
unpack_opaque() (Unpacker のメソッド)
unpack_string() (Unpacker のメソッド)
Unpacker (xdrlib 内の クラス)
unparsedEntityDecl() (DTDHandler のメソッド)
UnparsedEntityDeclHandler() (xmlparser のメソッド)
Unpickler (pickle 内の クラス)
UnpicklingError
unqdevice() (モジュール fl)
unquote() (モジュール email.Utils)
unquote() (モジュール rfc822)
unquote() (モジュール urllib)
unquote_plus() (モジュール urllib)
unregister() (LogRecord のメソッド)
unregister_dialect() (モジュール csv)
unsubscribe() (IMAP4_stream のメソッド)
untouchwin() (window のメソッド)
unused_data (Queue の属性)
up() (モジュール turtle)
update() (dictionary method)
update() (hmac のメソッド)
update() (md5 のメソッド)
update() (sha のメソッド)
update_panels() (モジュール curses.panel)
upper() (string のメソッド)
upper() (モジュール string)
uppercase (モジュール string)
URL, [リンク], [リンク], [リンク], [リンク]
parsing
relative
url (ServerProxy の属性)
url2pathname() (モジュール urllib)
urlcleanup() (モジュール urllib)
urldefrag() (モジュール urlparse)
urlencode() (モジュール urllib)
URLError
urljoin() (モジュール urlparse)
urllib (標準 モジュール), [リンク]
urllib2 (標準 モジュール)
urlopen() (モジュール urllib)
urlopen() (モジュール urllib2)
URLopener (urllib 内の クラス)
urlparse() (モジュール urlparse)
urlparse (標準 モジュール), [リンク]
urlretrieve() (モジュール urllib)
urlsplit() (モジュール urlparse)
urlunparse() (モジュール urlparse)
urlunsplit() (モジュール urlparse)
use_env() (モジュール curses)
use_rawinput (Cmd の属性)
user
configuration file
effective id
id
id, setting
USER (environment variable)
user() (POP3 のメソッド)
user (標準 モジュール)
USER (環境変数)
UserDict (UserDict 内の クラス)
UserDict (標準 モジュール)
UserList (UserList 内の クラス)
UserList (標準 モジュール)
USERNAME (environment variable)
USERNAME (環境変数)
userptr() (Textbox のメソッド)
UserString (UserString 内の クラス)
UserString (標準 モジュール)
UserWarning
UTC
utcfromtimestamp() (datetime のメソッド)
utcnow() (datetime のメソッド)
utcoffset() (datetime のメソッド)
utcoffset() (time のメソッド), [リンク]
utctimetuple() (datetime のメソッド)
utime() (モジュール os)
uu (標準 モジュール), [リンク]

V

value
truth
value (Morsel の属性)
value_decode() (BaseCookie のメソッド)
value_encode() (BaseCookie のメソッド)
ValueError
values
Boolean
values() (dictionary method)
values() (Message のメソッド)
varray() (モジュール gl)
vars() (built-in function)
vbar (ScrolledText の属性)
VERBOSE (モジュール re)
verbose (モジュール tabnanny)
verbose (モジュール test.test_support)
verify() (SMTP のメソッド)
verify_request() (SocketServer protocol)
version (URLopener の属性)
version (モジュール curses)
version (モジュール httplib)
version (モジュール sys)
version_info (モジュール sys)
version_string() (BaseHTTPRequestHandler のメソッド)
vline() (window のメソッド)
vnarray() (モジュール gl)
voidcmd() (FTP のメソッド)
volume (ZipInfo の属性)
vonmisesvariate() (モジュール random)

W

W_OK (モジュール os)
wait() (Condition のメソッド)
wait() (Event のメソッド)
wait() (Popen4 のメソッド)
wait() (モジュール os)
waitpid() (モジュール os)
walk() (Message のメソッド)
walk() (モジュール compiler)
walk() (モジュール compiler.visitor)
walk() (モジュール os)
walk() (モジュール os.path)
warn() (モジュール warnings)
warn_explicit() (モジュール warnings)
Warning
warning() (ErrorHandler のメソッド)
warning() (Textbox のメソッド)
warning() (モジュール logging)
warnings
warnings (標準 モジュール)
warnoptions (モジュール sys)
wasSuccessful() (TestResult のメソッド)
wave (標準 モジュール)
WeakKeyDictionary (weakref 内の クラス)
weakref (拡張 モジュール)
WeakValueDictionary (weakref 内の クラス)
webbrowser (標準 モジュール)
weekday() (date のメソッド)
weekday() (datetime のメソッド)
weekday() (モジュール calendar)
weibullvariate() (モジュール random)
WEXITSTATUS() (モジュール os)
wfile (BaseHTTPRequestHandler の属性)
what() (モジュール imghdr)
what() (モジュール sndhdr)
whathdr() (モジュール sndhdr)
whichdb() (モジュール whichdb)
whichdb (標準 モジュール)
while 実行文
whitespace (shlex の属性)
whitespace (モジュール string)
whitespace_split (shlex の属性)
whrandom (標準 モジュール)
whseed() (モジュール random)
WichmannHill (random 内の クラス)
width (TextWrapper の属性)
width() (モジュール turtle)
WIFEXITED() (モジュール os)
WIFSIGNALED() (モジュール os)
WIFSTOPPED() (モジュール os)
Wimp$ScrapDir (environment variable)
Wimp$ScrapDir (環境変数)
window() (Textbox のメソッド)
window manager (widgets)
Windows ini file
WindowsError
WinSock
winsound (組み込み モジュール)
winver (モジュール sys)
WNOHANG (モジュール os)
wordchars (shlex の属性)
World Wide Web, [リンク], [リンク], [リンク]
wrap() (TextWrapper のメソッド)
wrap() (モジュール textwrap)
wrapper() (モジュール curses.wrapper)
writable() (async_chat のメソッド)
writable() (dispatcher のメソッド)
write() (array のメソッド)
write() (audio device のメソッド), [リンク]
write() (BZ2File のメソッド)
write() (file のメソッド)
write() (Generator のメソッド)
write() (InteractiveConsole のメソッド)
write() (LogRecord のメソッド)
write() (Queue のメソッド)
write() (SafeConfigParser のメソッド)
write() (StreamWriter のメソッド)
write() (Telnet のメソッド)
write() (ZipFile のメソッド)
write() (モジュール imgfile)
write() (モジュール os)
write() (モジュール turtle)
write_byte() (Queue のメソッド)
write_history_file() (モジュール readline)
writeall() (audio device のメソッド)
writeframes() (aifc のメソッド)
writeframes() (AU_write のメソッド)
writeframes() (Wave_write のメソッド)
writeframesraw() (aifc のメソッド)
writeframesraw() (AU_write のメソッド)
writeframesraw() (Wave_write のメソッド)
writelines() (BZ2File のメソッド)
writelines() (file のメソッド)
writelines() (StreamWriter のメソッド)
writepy() (PyZipFile のメソッド)
writer (formatter の属性)
writer() (モジュール csv)
writerow() (csv writer のメソッド)
writerows() (csv writer のメソッド)
writesamps() (audio port のメソッド)
writestr() (ZipFile のメソッド)
writexml() (HTMLParser のメソッド)
WrongDocumentErr
WSTOPSIG() (モジュール os)
WTERMSIG() (モジュール os)
WWW, [リンク], [リンク], [リンク]
server, [リンク]

X

X (モジュール re)
X_OK (モジュール os)
xatom() (IMAP4_stream のメソッド)
XDR, [リンク]
xdrlib (標準 モジュール)
xgtitle() (NNTPDataError のメソッド)
xhdr() (NNTPDataError のメソッド)
XHTML
XHTML_NAMESPACE (モジュール xml.dom)
XML
namespaces
xml.dom (標準 モジュール)
xml.dom.minidom (標準 モジュール)
xml.dom.pulldom (標準 モジュール)
xml.parsers.expat (標準 モジュール)
xml.sax (標準 モジュール)
xml.sax.handler (標準 モジュール)
xml.sax.saxutils (標準 モジュール)
xml.sax.xmlreader (標準 モジュール)
XML_NAMESPACE (モジュール xml.dom)
xmlcharrefreplace_errors_errors() (モジュール codecs)
XmlDeclHandler() (xmlparser のメソッド)
XMLFilterBase (xml.sax.saxutils 内の クラス)
XMLGenerator (xml.sax.saxutils 内の クラス)
xmllib (標準 モジュール)
XMLNS_NAMESPACE (モジュール xml.dom)
XMLParser (xmllib 内の クラス)
XMLParserType (モジュール xml.parsers.expat)
XMLReader (xml.sax.xmlreader 内の クラス)
xmlrpclib (標準 モジュール)
xor() (モジュール operator)
xover() (NNTPDataError のメソッド)
xpath() (NNTPDataError のメソッド)
xrange() (built-in function)
xrange() (組み込み関数), [リンク]
xrange オブジェクト, [リンク]
XRangeType (モジュール types)
xreadlines() (BZ2File のメソッド)
xreadlines() (file のメソッド)
xreadlines() (モジュール xreadlines)
xreadlines (拡張 モジュール)

Y

Y2K
year (date の属性)
year (datetime の属性)
Year 2000
Year 2038
YESEXPR (モジュール locale)
yiq_to_rgb() (モジュール colorsys)

Z

ZeroDivisionError
zfill() (string のメソッド)
zfill() (モジュール string)
zip() (built-in function)
ZIP_DEFLATED (モジュール zipfile)
ZIP_STORED (モジュール zipfile)
ZipFile (zipfile 内の クラス)
ZipFile (zipfile 内のクラス)
zipfile (標準 モジュール)
ZipInfo (zipfile 内の クラス)
zlib (組み込み モジュール)

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index
Previous: Module Index Up: Python ライブラリリファレンス Next: この文書について...


Python リファレンスマニュアル

Guido van Rossum

PythonLabs
Email: docs@python.org

Fred L. Drake, Jr., editor

リリース 2.3.3
平成16年6月28日

日本語訳: Python ドキュメント翻訳プロジェクト

  • 序
  • 目次
  • 1. 導入
    • 1.1 本マニュアルにおける表記法
  • 2. 字句解析
    • 2.1 行構造
      • 2.1.1 論理行 (logical line)
      • 2.1.2 物理行 (physical line)
      • 2.1.3 コメント
      • 2.1.4 エンコード宣言 (encoding declaration)
      • 2.1.5 明示的な行継続
      • 2.1.6 非明示的な行継続
      • 2.1.7 空行
      • 2.1.8 インデント
      • 2.1.9 トークン間の空白
    • 2.2 その他のトークン
    • 2.3 識別子 (identifier) およびキーワード (keyword)
      • 2.3.1 キーワード (keyword)
      • 2.3.2 予約済みの識別子種 (reserved classes of identifiers)
    • 2.4 リテラル (literal)
      • 2.4.1 文字列リテラル
      • 2.4.2 文字列リテラルの結合 (concatenation)
      • 2.4.3 数値リテラル
      • 2.4.4 整数および長整数リテラル
      • 2.4.5 浮動小数点数リテラル
      • 2.4.6 虚数 (imaginary) リテラル
    • 2.5 演算子 (operator)
    • 2.6 デリミタ (delimiter)
  • 3. データモデル
    • 3.1 オブジェクト、値、および型
    • 3.2 標準型の階層
    • 3.3 特殊メソッド名
      • 3.3.1 基本的なカスタマイズ
      • 3.3.2 属性値アクセスをカスタマイズする
      • 3.3.3 クラス生成をカスタマイズする
      • 3.3.4 呼び出し可能オブジェクトをエミュレートする
      • 3.3.5 コンテナをエミュレートする
      • 3.3.6 配列型エミュレーションで使われるその他のメソッド
      • 3.3.7 数値型をエミュレーションする
      • 3.3.8 型強制規則 (coercion rule)
  • 4. 実行モデル
    • 4.1 名前づけと束縛 (naming and binding)
      • 4.1.1 動的な機能とのやりとり
    • 4.2 例外
  • 5. 式 (expression)
    • 5.1 算術変換 (arithmetic conversion)
    • 5.2 アトム、原子的要素 (atom)
      • 5.2.1 識別子 (identifier、または名前 (name))
      • 5.2.2 リテラル
      • 5.2.3 丸括弧形式 (parenthesized form)
      • 5.2.4 リスト表現
      • 5.2.5 辞書表現
      • 5.2.6 文字列変換
    • 5.3 一次語 (primary)
      • 5.3.1 属性参照
      • 5.3.2 添字表記 (subscription)
      • 5.3.3 スライス表記 (slicing)
      • 5.3.4 呼び出し (call)
    • 5.4 べき乗演算 (power operator)
    • 5.5 単項算術演算 (unary arithmetic operation)
    • 5.6 二項算術演算 (binary arithmetic operation)
    • 5.7 シフト演算 (shifting operation)
    • 5.8 ビット単位演算の二項演算 (binary bit-wise operation)
    • 5.9 比較 (comparison)
    • 5.10 ブール演算 (boolean operation)
    • 5.11 ラムダ (lambda)
    • 5.12 式のリスト
    • 5.13 評価順序
    • 5.14 まとめ
  • 6. 単純文 (simple statement)
    • 6.1 式文 (expression statement)
    • 6.2 Assert 文 (assert statement)
    • 6.3 代入文 (assignment statement)
      • 6.3.1 累算代入文 (augmented assignment statement)
    • 6.4 pass 文
    • 6.5 del 文
    • 6.6 print 文
    • 6.7 return 文
    • 6.8 yield 文
    • 6.9 raise 文
    • 6.10 break 文
    • 6.11 continue 文
    • 6.12 import 文
      • 6.12.1 future 文 (future statement)
    • 6.13 global 文
    • 6.14 exec 文
  • 7. 複合文 (compound statement)
    • 7.1 if 文
    • 7.2 while 文
    • 7.3 for 文
    • 7.4 try 文
    • 7.5 関数定義
    • 7.6 クラス定義
  • 8. トップレベル要素
    • 8.1 完全な Python プログラム
    • 8.2 ファイル入力
    • 8.3 対話的入力
    • 8.4 式入力
  • A. 歴史とライセンス
    • A.1 History of the software
    • A.2 Terms and conditions for accessing or otherwise using Python
  • B. 日本語訳について
    • B.1 このドキュメントについて
    • B.2 翻訳者一覧 (敬称略)
  • 索引
  • この文書について...
Up One Level Next Page Python リファレンスマニュアル Contents Index
Up: Python ドキュメントインデクス Next: 序


1. 導入

このリファレンスマニュアルは、Python プログラミング言語自体に関する 記述です。チュートリアルとして書かれたものではありません。

私は本マニュアルをできるだけ正確に書こうとする一方で、文法や 字句解析以外の全てについて、形式化された仕様記述ではなく英語を 使うことにしました。そうすることで、このドキュメントが平均的な 読者にとってより読みやすくなっているはずですが、ややあいまいな 部分も残っていることでしょう。 従って、もし読者のあなたが火星から来ている人で、このドキュメントだけ から Python を再度実装しようとしているのなら、色々と推測しなければ ならないことがあり、実際にはおそらく全く別の言語を実装する羽目に なるでしょう。 逆に、あなたが Python を利用しており、Python 言語のある特定の領域に おいて、厳密な規則が何か疑問に思った場合、その答えはこのドキュメント で確実に見つけられることでしょう。

もしより形式化された言語定義をお望みなら、あなたの時間を提供して いただいてかまいません -- もしくは、クローン生成装置でも発明して ください :-) 。

実装に関する詳細を言語リファレンスのドキュメントに載せすぎるのは 危険なことです -- 実装は変更されるかもしれず、同じ言語でも異なる 実装は異なった動作をするかもしれないからです。一方、広く使われている Python 実装は現在のところ唯一 (今や第二の実装が存在しますが！) なので、 特定のクセについては、特に実装によって何らかの制限が加えられている 場合には、触れておく価値があります。従って、このテキスト全体にわたって 短い ``実装に関する注釈 (imprementation notes)'' がちりばめられて います。

Python 実装はいずれも、数々の組み込みモジュールと標準モジュールが 付属します。これらはここではドキュメント化されていませんが、 Python ライブラリリファレンス でドキュメント化されています。いくつかの組み込みモジュールについて は、言語定義と重要なかかわりをもっているときについて触れています。

  • 1.1 本マニュアルにおける表記法
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 目次 Up: Python リファレンスマニュアル Next: 1.1 本マニュアルにおける表記法


1.1 本マニュアルにおける表記法

字句解析と構文に関する記述では、BNF 文法記法に手を加えたものを 使っています。この記法では、以下のような記述形式をとります:

name:           lc_letter (lc_letter | "_")*
lc_letter:      "a"..."z"

最初の行は、name が lc_letter の後ろに ゼロ個または それ以上の lc_letter とアンダースコアが続いたものであることを 示しています。 そして、lc_letter は "a" から "z" までの 何らかの文字一字であることを示します (この規則は、このドキュメントに 記述されている字句規則と構文規則において定義されている名前 (name) で 一貫して使われています)。

各規則は name (規則によって定義されているものの名前) とコロン一つから 始まります。垂直線 (|) は、複数の選択項目を分かち書きするときに 使います; この記号は、この記法において最も結合優先度の低い演算子です。 アスタリスク (*) は、直前にくる要素のゼロ個以上の繰り返しを 表します; 同様に、プラス (+) は一個以上の繰り返しで、角括弧 ([ ]) に囲われた字句は、字句がゼロ個か一個出現する (別の言い方をすれば、囲いの中の字句はオプションである) ことを示し ます。* および + 演算子の結合範囲は可能な限り狭く なっています; 字句のグループ化には丸括弧を使います。 リテラル文字列はクオートで囲われます。空白はトークンを分割している ときのみ意味を持ちます。規則は通常、一行中に収められています; 多数の選択肢のある規則は、最初の行につづいて、垂直線の後ろに 各々別の行として記述されます。

(上の例のような) 字句定義では、他に二つの慣習が使われています: 三つのドットで区切られている二つのリテラル文字は、二つの文字の ASCII 文字コードにおける (包含的な) 範囲から文字を一字選ぶ ことを示します。各カッコ中の字句 (<...>) は、定義済みの シンボルを記述する非形式的なやりかたです; 例えば、 `制御文字' を書き表す必要があるときなどに使われることがあります。

字句と構文規則の定義の間で使われている表記はほとんど同じですが、 その意味には大きな違いがあります: 字句定義は入力ソース中の個々の 文字を取り扱いますが、構文定義は字句解析で生成された一連の トークンを取り扱います。次節 (``字句解析'') における BNF はすべて 字句定義のためのものです; それ以降の章では、構文定義のために 使っています。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 1. 導入 Up: 1. 導入 Next: 2. 字句解析


2. 字句解析

Python で書かれたプログラムは パーザ (parser) に読み込まれます。 パーザへの入力は、字句解析器 (lexical analyzer) によって生成 された一連の トークン (token) からなります。この章では、字句解析器 がファイルをトークン列に分解する方法について解説します。

Python は 7-bit の ASCII 文字セットをプログラムのテキストに 使います。 バージョン2.3 以降で新規追加された 仕様: エンコード宣言を使って、文字列リテラルやコメントに ASCII ではない文字セットが使われていることを明示できます。 以前のバージョンとの互換性のために、Python は 8-bit 文字が見つかっても 警告を出すだけにとどめます; こうした警告は、エンコーディングを明示 したり、バイナリデータの場合には文字ではなくエスケープシーケンス を使うことで解決できます。

実行時の文字セットは、プログラムが接続されている I/O デバイスにもより ますが、通常 ASCIIのサブセットです。

将来のバージョンとの互換性に関する注意: 8-bit 文字に対する文字セットを ISO Latin-1 (ラテン語系アルファベットを 用いるほとんどの西欧言語をカバーするASCII の上位セット) とみなし たい気にもなるかもしれません。しかし、おそらく Unicode を編集できる テキストエディタが将来一般的になるはずです。こうしたエディタでは 一般的に UTF-8 エンコードを使いますが、UTF-8 エンコードは ASCII の上位セットではあるものの、文字序数 (ordinal) 128-255 の扱いが 非常に異なります。この問題に関してはまだ合意が得られていませんが、 Latin-1 と UTF-8 のどちらかとみなすのは、たとえ現在の実装が Latin-1 びいきのように思えたとしても賢明とはいえません。これはソースコード 文字セットと実行時の文字セットのどちらにも該当します。

  • 2.1 行構造
    • 2.1.1 論理行 (logical line)
    • 2.1.2 物理行 (physical line)
    • 2.1.3 コメント
    • 2.1.4 エンコード宣言 (encoding declaration)
    • 2.1.5 明示的な行継続
    • 2.1.6 非明示的な行継続
    • 2.1.7 空行
    • 2.1.8 インデント
    • 2.1.9 トークン間の空白
  • 2.2 その他のトークン
  • 2.3 識別子 (identifier) およびキーワード (keyword)
    • 2.3.1 キーワード (keyword)
    • 2.3.2 予約済みの識別子種 (reserved classes of identifiers)
  • 2.4 リテラル (literal)
    • 2.4.1 文字列リテラル
    • 2.4.2 文字列リテラルの結合 (concatenation)
    • 2.4.3 数値リテラル
    • 2.4.4 整数および長整数リテラル
    • 2.4.5 浮動小数点数リテラル
    • 2.4.6 虚数 (imaginary) リテラル
  • 2.5 演算子 (operator)
  • 2.6 デリミタ (delimiter)
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 1.1 本マニュアルにおける表記法 Up: Python リファレンスマニュアル Next: 2.1 行構造


2.1 行構造

Python プログラムは多数の 論理行 (logical lines) に分割されます。

  • 2.1.1 論理行 (logical line)
  • 2.1.2 物理行 (physical line)
  • 2.1.3 コメント
  • 2.1.4 エンコード宣言 (encoding declaration)
  • 2.1.5 明示的な行継続
  • 2.1.6 非明示的な行継続
  • 2.1.7 空行
  • 2.1.8 インデント
  • 2.1.9 トークン間の空白
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2. 字句解析 Up: 2. 字句解析 Next: 2.1.1 論理行 (logical line)


2.1.1 論理行 (logical line)

論理行の終端は、トークン NEWLINE で表されます。構文上許されている場合 (複合文: compound statement 中の実行文: statement) を除いて、実行文は 論理行間にまたがることはできません。 論理行は一行またはそれ以上の 物理行(physical line) からなり、 物理行の末尾には明示的または非明示的な 行連結(line joining) 規則が続きます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.1 行構造 Up: 2.1 行構造 Next: 2.1.2 物理行 (physical line)


2.1.2 物理行 (physical line)

物理行とは、利用しているプラットフォームで行終端として取り決めている 文字列で終端されたものです。Unixでは、行終端は ASCII LF (行送り: linefeed) 文字です。 Windows では、 ASCII 配列の CR LF (復帰: return に続いて 行送り) です。Macintosh では、 ASCII CR (復帰) 文字です。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.1.1 論理行 (logical line) Up: 2.1 行構造 Next: 2.1.3 コメント


2.1.3 コメント

コメントは文字列リテラル内に入っていないハッシュ文字 (#) から 始まり、同じ物理行の末端で終わります。非明示的な行継続規則が適用されて いない限り、コメントは論理行を終端させます。 コメントは構文上無視されます; コメントはトークンになりません。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.1.2 物理行 (physical line) Up: 2.1 行構造 Next: 2.1.4 エンコード宣言 (encoding declaration)


2.1.4 エンコード宣言 (encoding declaration)

Python スクリプト中の最初の行か、二行目にあるコメントが正規表現 coding[=:]\s*([\w-_.]+) にマッチする場合、コメントは エンコード宣言 (encoding declaration) として処理されます; 表現に対する最初のマッチグループがソースコードファイルのエンコードを 指定します。エンコード宣言式として推奨する形式は、GNU Emacs が 認識できる形式

# -*- coding: <encoding-name> -*-

または、Bram Moolenar による VIM が認識できる形式

# vim:fileencoding=<encoding-name>

です。さらに、ファイルの先頭のバイト列が UTF-8 バイトオーダ記号 ('\xef\xbb\xbf') の場合、ファイルのエンコードは UTF-8 と宣言されているものとします (この機能は Microsoft の notepad やその他のエディタでサポートされています)。

エンコードが宣言されている場合、Python はそのエンコード名を認識 できなければなりません。宣言されたエンコードは全ての字句解析、特に文字列の終端を検出する際や Unicode リテラルの内容を翻訳する上で用いられます。 文字列リテラルは文法的な解析を行うために Unicode に変換され、 解釈が行われる前に元のエンコードに戻されます。エンコード宣言は 宣言全体が一行に収まっていなければなりません。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.1.3 コメント Up: 2.1 行構造 Next: 2.1.5 明示的な行継続


2.1.5 明示的な行継続

二つまたはそれ以上の物理行を論理行としてつなげるためには、 バックスラッシュ文字 (\) を使って以下のようにします: 物理行が文字列リテラルやコメント中の文字でないバックスラッシュで 終わっている場合、後続する行とつなげて一つの論理行を構成し、 バックスラッシュおよびバックスラッシュの後ろにある行末文字を 削除します。例えば:

if 1900 < year < 2100 and 1 <= month <= 12 \
   and 1 <= day <= 31 and 0 <= hour < 24 \
   and 0 <= minute < 60 and 0 <= second < 60:   # Looks like a valid date
        return 1

となります。

バックスラッシュで終わる行にはコメントを入れることはできません。 また、バックスラッシュを使ってコメントを継続することはできません。 バックスラッシュが文字列リテラル中にある場合を除き、バックスラッシュの 後ろにトークンを継続することはできません (すなわち、物理行内の文字列 リテラル以外のトークンをバックスラッシュを使って分断することは できません)。上記以外の場所では、文字列リテラル外にあるバックスラッシュ はどこにあっても不正となります。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.1.4 エンコード宣言 (encoding declaration) Up: 2.1 行構造 Next: 2.1.6 非明示的な行継続


2.1.6 非明示的な行継続

丸括弧 (parentheses)、角括弧 (square bracket) 、および 波括弧 (curly brace) 内の式は、バックスラッシュを使わずに 一行以上の物理行に分割することができます。 例えば:

month_names = ['Januari', 'Februari', 'Maart',      # These are the
               'April',   'Mei',      'Juni',       # Dutch names
               'Juli',    'Augustus', 'September',  # for the months
               'Oktober', 'November', 'December']   # of the year

非明示的に継続された行にはコメントを含めることができます。 継続行のインデントは重要ではありません。空の継続行を書くことが できます。非明示的な継続行中には、NEWLINE トークンは存在しません。 非明示的な行の継続は、三重クオートされた文字列 (下記参照) でも発生します; この場合には、コメントを含めることができません。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.1.5 明示的な行継続 Up: 2.1 行構造 Next: 2.1.7 空行


2.1.7 空行

スペース、タブ、フォームフィード、およびコメントのみを含む論理行は 無視されます (すなわち、NEWLINE トークンは生成されません)。 文を対話的に入力している際には、空行の扱いは行読み込み-評価-出力 (read-eval-print) ループの実装によって異なるかもしれません。 標準的な実装では、完全な空行でできた論理行 (すなわち、空白文字も コメントも全く含まない空行) は、複数行からなる実行文の終端を示します。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.1.6 非明示的な行継続 Up: 2.1 行構造 Next: 2.1.8 インデント


2.1.8 インデント

論理行の行頭にある、先頭の空白 (スペースおよびタブ) の連なりは、 その行のインデントレベルを計算するために使われます。インデントレベルは、 実行文のグループ化方法を決定するために用いられます。

まず、タブは (左から右の方向に) 1 つから 8 つのスペースで置き換えられ、 置き換え後の文字列の終わりの位置までの文字数が 8 の倍数になるように 調整されます (Unixで使われている規則と同じになるよう意図されています)。 次に、空白文字でない最初の文字までのスペースの総数から、その行の インデントを決定します。バックスラッシュを使ってインデントを複数の 物理行に分割することはできません; 最初のバックスラッシュまでの空白が インデントを決定します。

プラットフォーム間の互換性に関する注意: 非 UNIX プラットフォームにおけるテキストエディタの性質上、一つの ソースファイル内でタブとインデントを混在させて使うのは賢明では ありません。また、プラットフォームによっては、最大インデントレベルを 明示的に制限しているかもしれません。

フォームフィード文字が行の先頭にあっても構いません; フォームフィード 文字は上のインデントレベル計算時には無視されます。フォームフィード 文字が先頭の空白中の他の場所にある場合、その影響は未定義です (例えば、スペースの数を 0 にリセットするかもしれません)。

連続する行における各々のインデントレベルは、 INDENT および DEDENT トークンを生成するために使われます。 トークンの生成はスタックを用いて以下のように行われます。

ファイル中の最初の行を読み出す前に、スタックにゼロが一つ積まれ (push され) ます; このゼロは決して除去 (pop) されることはありません。 スタックの先頭に積まれてゆく数字は、常にスタックの末尾から先頭にかけて 厳密に増加するようになっています。各論理行の開始位置において、 その行のインデントレベル値がスタックの先頭の値と比較されます。値が 等しければ何もしません。インデントレベル値がスタック上の値よりも 大きければ、インデントレベル値はスタックに積まれ、INDENT トークンが 一つ生成されます。インデントレベル値がスタック上の値よりも小さい場合、 その値はスタック内のいずれかの値と等しくなければなりません ; スタック上のインデントレベル値よりも大きい値はすべて除去され、 値が一つ除去されるごとに DEDENT トークンが一つ生成されます。ファイルの 末尾では、スタックに残っているゼロより大きい値は全て除去され、 値が一つ除去されるごとに DEDENT トークンが一つ生成されます。

以下の例に正しく (しかし当惑させるように) インデントされた Python コードの一部を示します:

def perm(l):
        # Compute the list of all permutations of l
    if len(l) <= 1:
                  return [l]
    r = []
    for i in range(len(l)):
             s = l[:i] + l[i+1:]
             p = perm(s)
             for x in p:
              r.append(l[i:i+1] + x)
    return r

以下の例は、様々なインデントエラーになります:

 def perm(l):                       # error: first line indented
for i in range(len(l)):             # error: not indented
    s = l[:i] + l[i+1:]
        p = perm(l[:i] + l[i+1:])   # error: unexpected indent
        for x in p:
                r.append(l[i:i+1] + x)
            return r                # error: inconsistent dedent

(実際は、最初の 3 つのエラーはパーザによって検出されます; 最後の エラーのみが字句解析器で見つかります -- return r の インデントは、スタックから逐次除去されていくどのインデントレベル値とも 一致しません)

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.1.7 空行 Up: 2.1 行構造 Next: 2.1.9 トークン間の空白


2.1.9 トークン間の空白

論理行の先頭や文字列の内部にある場合を除き、空白文字であるスペース、 タブ、およびフォームフィードは、トークンを分割するために自由に 利用することができます。二つのトークンを並べて書くと別のトークンと してみなされてしまうような場合には、トークンの間に空白が必要と なります (例えば、ab は一つのトークンですが、 a b は二つのトークンと なります)。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.1.8 インデント Up: 2.1 行構造 Next: 2.2 その他のトークン


2.2 その他のトークン

NEWLINE、INDENT、および DEDENT の他、以下のトークンのカテゴリ: 識別子 (identifier)、キーワード(keyword)、リテラル、 演算子 (operator) 、デリミタ (delimiter) が存在します。 空白文字 (上で述べた行終端文字以外) はトークンではありませんが、 トークンを区切る働きがあります。 トークンの解析にあいまいさが生じた場合、トークンは左から右に読んで 不正でないトークンを構築できる最長の文字列を含むように構築されます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.1.9 トークン間の空白 Up: 2. 字句解析 Next: 2.3 識別子 (identifier) およびキーワード


2.3 識別子 (identifier) およびキーワード (keyword)

識別子 (または 名前 (name)) は、以下の字句定義で記述されます:

identifier ::= (letter|"_") (letter | digit | "_")*
letter ::= lowercase | uppercase
lowercase ::= "a"..."z"
uppercase ::= "A"..."Z"
digit ::= "0"..."9"
Download entire grammar as text.

識別子の長さには制限がありません。大小文字は区別されます。

  • 2.3.1 キーワード (keyword)
  • 2.3.2 予約済みの識別子種 (reserved classes of identifiers)
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.2 その他のトークン Up: 2. 字句解析 Next: 2.3.1 キーワード (keyword)


2.3.1 キーワード (keyword)

以下の識別子は、予約語、または Python 言語における キーワード (keyword) として使われ、通常の識別子として 使うことはできません。キーワードは厳密に下記の通りに綴らなければ なりません:

and       del       for       is        raise
assert    elif      from      lambda    return
break     else      global    not       try
class     except    if        or        while
continue  exec      import    pass      yield
def       finally   in        print

識別子 as は import 文における構文の一部として 使われることがありますが、現在のところ予約語ではありません。

将来の Python のバージョンでは、識別子 as と None はともにキーワードになる予定です。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.3 識別子 (identifier) およびキーワード Up: 2.3 識別子 (identifier) およびキーワード Next: 2.3.2 予約済みの識別子種 (reserved classes


2.3.2 予約済みの識別子種 (reserved classes of identifiers)

ある種の (キーワードを除く) 識別子には、特殊な意味があります。 これらの識別子種は、先頭や末尾にあるアンダースコア文字のパターンで 区別されます:

_*
この識別子は "from module import *" で import されません。 対話インタプリタでは、最も最近行われた値評価の結果を記憶するために 特殊な識別子 "_" が使われます; この識別子は __builtin__ モジュール内に記憶されます。対話モードでない場合、"_" には 特殊な意味はなく、定義されていません。 6.12 節、 ``import 文'' を参照してください。

注意: 名前 "_" は、しばしば国際化 (internationalization) と共に 用いられます; この慣習についての詳しい情報は、 gettext module を 参照してください。

__*__
システムで定義された (system-defined) 名前です。これらの名前は インタプリタと (標準ライブラリを含む) 実装上で定義されています; アプリケーション側では、この名前規約を使って別の名前を定義しようと すべきではありません。この種の名前のうち、Python で定義されている 名前のセットは、将来のバージョンで拡張される可能性があります。 3.3 節、``特殊なメソッド名'' を参照してください。

__*
クラスプライベート (class-private) な名前です。このカテゴリに属する 名前は、クラス定義のコンテキスト上で用いられた場合、基底クラスと 導出クラスの ``プライベートな'' 属性間で名前衝突が起こるのを防ぐために 書き直されます。 5.2.1 節、``識別子 (名前)'' を参照してください。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.3.1 キーワード (keyword) Up: 2.3 識別子 (identifier) およびキーワード Next: 2.4 リテラル (literal)


2.4 リテラル (literal)

リテラル (literal) とは、いくつかの組み込み型の定数を表記したものです。

  • 2.4.1 文字列リテラル
  • 2.4.2 文字列リテラルの結合 (concatenation)
  • 2.4.3 数値リテラル
  • 2.4.4 整数および長整数リテラル
  • 2.4.5 浮動小数点数リテラル
  • 2.4.6 虚数 (imaginary) リテラル
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.3.2 予約済みの識別子種 (reserved classes Up: 2. 字句解析 Next: 2.4.1 文字列リテラル


2.4.1 文字列リテラル

文字列リテラルは以下の字句定義で記述されます:

stringliteral ::= [stringprefix](shortstring | longstring)
stringprefix ::= "r" | "u" | "ur" | "R" | "U" | "UR" | "Ur" | "uR"
shortstring ::= "'" shortstringitem* "'" | '"' shortstringitem* '"'
longstring ::= "'''" longstringitem* "'''"
| '"""' longstringitem* '"""'
shortstringitem ::= shortstringchar | escapeseq
longstringitem ::= longstringchar | escapeseq
shortstringchar ::= <any ASCII character except "\" or newline or the quote>
longstringchar ::= <any ASCII character except "\">
escapeseq ::= "\" <any ASCII character>
Download entire grammar as text.

上記の生成規則で示されていない文法的な制限が一つあります。それは 文字列リテラルの stringprefix と残りの部分の間に 空白を入れてはならないということです。

より平易な説明: 文字列リテラルは、対応する一重引用符 (') または 二重引用符 (") で囲われます。また、対応する三連の一重引用符 や二重引用符で囲うこともできます (通常、三重クオート文字列: triple-quoted string として 参照されます)。バックスラッシュ (\) 文字を使って、 ある文字を例えば改行文字やバックスラッシュ自体、クオート文字といった 別の意味を持つようにエスケープすることができます。 文字列リテラルの前には、オプションとして "r" または "R" 一文字を接頭してもかまいません; このような文字列は raw 文字列 (raw string) と呼ばれ、バックスラッシュによるエスケープシーケンスの 解釈規則が異なります。"u" や "U" を接頭すると、 文字列は Unicode 文字列 (Unicode string) になります。Unicode 文字列は Unicode コンソーシアムおよび ISO 10646 で定義されている Unicode 文字セット を使います。Unicode 文字列では、文字セットに加えて、以下で説明するような エスケープシーケンスを利用できます。二つの接頭文字を組み合わせることも できます; この場合、"u" は "r" より前に出現しなくては なりません。

三重クオート文字列中には、三連のエスケープされないクオート文字で 文字列を終端してしまわないかぎり、エスケープされていない改行やクオートを 書くことができます (さらに、それらはそのまま文字列中に残ります)。 (ここでいう ``クオート'' とは、文字列の囲みを開始するときに使った文字 を示し、' か " のいずれかです)。

"r" または "R" 接頭文字がつかないかぎり、 文字列中のエスケープシーケンスは標準 C で使われているのと同様の 法則にしたがって解釈されます。以下に Python で認識されるエスケープ シーケンスを示します:

エスケープシーケンス | 意味 | 備考
\newline | 無視 |
\\ | バックスラッシュ (\) |
\' | 一重引用符 (') |
\" | 二重引用符 (") |
\a | ASCII 端末ベル (BEL) |
\b | ASCII バックスペース (BS) |
\f | ASCII フォームフィード (FF) |
\n | ASCII 行送り (LF) |
\N{name} | Unicode データベース中で名前 name を持つ文字 (Unicode のみ) |
\r | ASCII 復帰 (CR) |
\t | ASCII 水平タブ (TAB) |
\uxxxx | 16-bit の 16 進数値 xxxx を持つ文字 (Unicode のみ) | (1)
\Uxxxxxxxx | 32-bit の 16 進数値 xxxxxxxx を持つ文字 (Unicode のみ) | (2)
\v | ASCII 水平タブ (VT) |
\ooo | 8 進数値 ooo を持つ ASCII 文字 | (3)
\xhh | 16 進数値 hh を持つ ASCII 文字 | (4)

備考:

(1)
サロゲートペアの断片を形成する個々のコード単位は、このエスケープ シーケンスでエンコードすることができます。
(2)
Unicode 文字はすべてこの方法でエンコードできますが、 Python が 16-bit コード単位を扱うようにコンパイルされている (デフォルトの設定です) 場合、基本多言語面 (Basic Multilingual Plane, BMP) 外の文字はサロゲートペア (surrogate pair) を使ってエンコードする ことになります。サロゲートペアの断片を形成する個々のコード単位は このエスケープシーケンスを使ってエンコードすることができます。
(3)
標準 C と同じく、最大で 3 桁の 8 進数まで受理します。
(4)
標準 C とは違い、最大で二桁の 16 進数しか受理されません。

標準の C とは違い、認識されなかったエスケープシーケンスはそのまま 文字列中に残されます。すなわち。 バックスラッシュも文字列中に残ります。 (この挙動はデバッグの 際に便利です: エスケープシーケンスを誤入力した場合、その結果として 出力に失敗しているのが用意にわかります) テーブル中で ``(Unicode のみ)'' と書かれたエスケープシーケンスは、非 Unicode 文字列リテラル中では認識されないエスケープシーケンスのカテゴリに 分類されるので注意してください。

接頭文字 "r" または "R" がある場合、バックスラッシュ の後にくる文字はそのまま文字列中に入り、バックスラッシュは全て 文字列中に残されます。例えば、文字列リテラル r"\n" は二つの文字: バックスラッシュと小文字の "n" からなる文字列を表すことに なります。引用符はバックスラッシュでエスケープすることができますが、 バックスラッシュ自体も残ってしまいます; 例えば、r"\"" は不正でない 文字列リテラルで、バックスラッシュと二重引用符からなる文字列を表します; r"\" は正しくない文字列リテラルです (raw 文字列を奇数個連なった バックスラッシュで終わらせることはできません)。厳密にいえば、 (バックスラッシュが直後のクオート文字をエスケープしてしまうため) raw 文字列を単一のバックスラッシュで終わらせることはできない ということになります。また、バックスラッシュの直後に改行がきても、 行継続を意味するのではなく 、それら二つの文字として解釈されるので 注意してください。

"r" および "R" 接頭文字を "u" や "U" と合わせて使った場合、\uXXXX エスケープ シーケンスは処理されますが、その他のバックスラッシュは すべて文字列中に残されます 。例えば、文字列リテラル ur"\u0062\n" は、3つの Unicode 文字: `LATIN SMALL LETTER B' (ラテン小文字 B)、`REVERSE SOLIDUS' (逆向き斜線)、 および `LATIN SMALL LETTER N' (ラテン小文字 N) を表します。 バックスラッシュの前にバックスラッシュをつけてエスケープすることは できます; しかし、バックスラッシュは両方とも文字列中に残されます。 その結果、\uXXXX エスケープシーケンスは、バックスラッシュが 奇数個連なっている場合にのみ認識されます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.4 リテラル (literal) Up: 2.4 リテラル (literal) Next: 2.4.2 文字列リテラルの結合 (concatenation)


2.4.2 文字列リテラルの結合 (concatenation)

複数の文字列リテラルは、互いに異なる引用符を使っていても (空白文字で区切って) 隣接させることができ、その意味は各々の文字列を 結合したものと同じになります。したがって、"hello" 'world' は "helloworld" と同じになります。この機能を使うと、長い文字列を 分離して、複数行にまたがらせる際に便利です。また、部分文字列ごとに コメントを追加することもできます。例えば:

re.compile("[A-Za-z_]"       # letter or underscore
           "[A-Za-z0-9_]*"   # letter, digit or underscore
          )

この機能は文法レベルで定義されていますが、スクリプトをコンパイルする 際の処理として実現されることに注意してください。実行時に文字列表現を 結合したければ、 `+' 演算子を使わなければなりません。また、リテラルの 結合においては、結合する各要素に異なる引用符形式を使える (raw 文字列 と三重引用符を混ぜることさえできます) ので注意してください。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.4.1 文字列リテラル Up: 2.4 リテラル (literal) Next: 2.4.3 数値リテラル


2.4.3 数値リテラル

数値リテラルは 4 種類あります: 整数 (plain integer)、長整数 (long integer)、浮動小数点数 (floating point number)、そして虚数 (imaginary number) です。複素数のためのリテラルはありません (複素数は実数と 虚数の和で作ることができます)。

数値リテラルには符号が含まれていないことに注意してください; -1 のような句は、実際には単項演算子 (unary operator) `-' とリテラル 1 を組み合わせたものです。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.4.2 文字列リテラルの結合 (concatenation) Up: 2.4 リテラル (literal) Next: 2.4.4 整数および長整数リテラル


2.4.4 整数および長整数リテラル

整数および長整数リテラルは以下の字句定義で記述されます:

longinteger ::= integer ("l" | "L")
integer ::= decimalinteger | octinteger | hexinteger
decimalinteger ::= nonzerodigit digit* | "0"
octinteger ::= "0" octdigit+
hexinteger ::= "0" ("x" | "X") hexdigit+
nonzerodigit ::= "1"..."9"
octdigit ::= "0"..."7"
hexdigit ::= digit | "a"..."f" | "A"..."F"
Download entire grammar as text.

長整数を表す末尾の文字は小文字の "l" でも大文字の "L" でもかまいませんが、"l" は "1" に良く似ているので、 常に "L" を使うよう強く勧めます。

整数で表現できる最大の値よりも大きい整数の 10 進表現リテラル (例えば 32-bit 整数を使っている場合には 2147483647) は、 長整数として表現できる値であれば受理されます。8 進および 16 進数 のリテラルも同様にふるまいますが、整数で表現できる最大の値よりも大きく、 かつ (32-bit 算術演算を使う計算機では) 符号無しの 32-bit の整数で表現 できる最大の値、4294967296 までの間では、符号無し 32-bit 整数としての 値から 4294967296 を引いて得られる負の整数値になります。 値がメモリ上に収まるかどうかという問題を除けば、長整数リテラルには値域の 制限がありません。例えば、0xdeadbeef は 32-bit の計算機では -559038737 という値とみなされ、0xdeadbeeffeed は 244837814107885L であるとみなされます。

整数リテラル (最初の行) と長整数リテラル (二行目および三行目) の例を 以下に示します:

7     2147483647                        0177    0x80000000
3L    79228162514264337593543950336L    0377L   0x100000000L
      79228162514264337593543950336             0xdeadbeeffeed

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.4.3 数値リテラル Up: 2.4 リテラル (literal) Next: 2.4.5 浮動小数点数リテラル


2.4.5 浮動小数点数リテラル

浮動小数点数リテラルは以下の字句定義で記述されます:

floatnumber ::= pointfloat | exponentfloat
pointfloat ::= [intpart] fraction | intpart "."
exponentfloat ::= (intpart | pointfloat) exponent
intpart ::= digit+
fraction ::= "." digit+
exponent ::= ("e" | "E") ["+" | "-"] digit+
Download entire grammar as text.

浮動小数点数における整数部と指数部は 8 進数のように見えることも ありますが、10 を基数として解釈されるので注意してください。 例えば、"077e010" は正しい表記であり、"77e10" と同じ数を 表します。 浮動小数点数リテラルの取りうる値の範囲は実装に依存します。 浮動小数点数リテラルの例をいくつか示します:

3.14    10.    .001    1e100    3.14e-10    0e0

数値リテラルには符号が含まれていないことに注意してください; -1 のような句は、実際には単項演算子 (unary operator) `-' とリテラル 1 を組み合わせたものです。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.4.4 整数および長整数リテラル Up: 2.4 リテラル (literal) Next: 2.4.6 虚数 (imaginary) リテラル


2.4.6 虚数 (imaginary) リテラル

虚数リテラルは以下のような字句定義で記述されます:

imagnumber ::= (floatnumber | intpart) ("j" | "J")
Download entire grammar as text.

虚数リテラルは、実数部が 0.0 の複素数を表します。複素数は二つ組の 浮動小数点型の数値で表され、それぞれの数値は浮動小数点型と同じ定義域の 範囲を持ちます。実数部がゼロでない浮動小数点を生成するには、(3+4j) のように虚数リテラルに浮動小数点数を加算します。以下に虚数リテラルの 例をいくつか示します:

3.14j   10.j    10j     .001j   1e100j  3.14e-10j

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.4.5 浮動小数点数リテラル Up: 2.4 リテラル (literal) Next: 2.5 演算子 (operator)


2.5 演算子 (operator)

以下のトークンは演算子です:

+       -       *       **      /       //      %
<<      >>      &       |       ^       ~
<       >       <=      >=      ==      !=      <>

比較演算子 <> と != は、同じ演算子について別の書き方をした ものです。書き方としては != を推奨します; <> は時代遅れの 書き方です。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.4.6 虚数 (imaginary) リテラル Up: 2. 字句解析 Next: 2.6 デリミタ (delimiter)


2.6 デリミタ (delimiter)

以下のトークンは文法上のデリミタとして働きます:

(       )       [       ]       {       }
,       :       .       `       =       ;
+=      -=      *=      /=      //=     %=
&=      |=      ^=      >>=     <<=     **=

浮動小数点数や虚数リテラル中にピリオドがあってもかまいません。 ピリオド三つの列はスライス表記における省略符号 (ellipsis) として 特別な意味を持っています。リスト後半の累算代入演算子 (augmented assignment operator) は、字句的にはデリミタとして振舞いますが、 演算も行います。

以下の印字可能 ASCII 文字は、他のトークンの一部として特殊な意味を 持っていたり、字句解析器にとって重要な意味を持っています:

'       "       #       \

以下の印字可能 ASCII 文字は、Python では使われていません。これらの 文字が文字列リテラルやコメントの外にある場合、無条件にエラーとなります:

@       $       ?
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.5 演算子 (operator) Up: 2. 字句解析 Next: 3. データモデル


3. データモデル

  • 3.1 オブジェクト、値、および型
  • 3.2 標準型の階層
  • 3.3 特殊メソッド名
    • 3.3.1 基本的なカスタマイズ
    • 3.3.2 属性値アクセスをカスタマイズする
      • 3.3.2.1 新しい形式のクラスのための別の属性アクセス
      • 3.3.2.2 デスクリプタ (descriptor) の実装
      • 3.3.2.3 デスクリプタを呼び出す
      • 3.3.2.4 __slots__
    • 3.3.3 クラス生成をカスタマイズする
    • 3.3.4 呼び出し可能オブジェクトをエミュレートする
    • 3.3.5 コンテナをエミュレートする
    • 3.3.6 配列型エミュレーションで使われるその他のメソッド
    • 3.3.7 数値型をエミュレーションする
    • 3.3.8 型強制規則 (coercion rule)
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 2.6 デリミタ (delimiter) Up: Python リファレンスマニュアル Next: 3.1 オブジェクト、値、および型


3.1 オブジェクト、値、および型

Python における オブジェクト (object) とは、データを抽象的に 表したものです。Python プログラムにおけるデータは全て、オブジェクトま たはオブジェクト間の関係として表されます。(ある意味では、プログラムコー ドもまたオブジェクトとして表されます。これはフォン・ノイマン: Von Neumann の ``プログラム記憶方式コンピュータ: stored program computer'' のモデルに適合します。)

オブジェクトはアイデンティティ値 (identity) 、型 (type) 、そして値 (value) を持ちます。オブジェクトが一度生成されると、そのオブジェクトの アイデンティティ値 は決して変化することがありません; アイデンティ ティ値をオブジェクトのメモリ上のアドレスと考えてもかまいません。 演算子 `is' は、二つのオブジェクト間のアイデンティティ値を比 較します; 関数 id() は、オブジェクトのアイデ ンティティ値を表す整数 (現在の実装ではオブジェクトのメモリ上のアドレス) を返します。 オブジェクトの 型 もまた変わることがありません。 3.1オブジェクトの型は、そのオブジェクトのサポートする操作 (``長さを持っているか？'' など) を決定し、その型のオブジェクトが 取りうる値について定義しています。 type() 関数は、オブジェクトの型 (型自体も一つのオブジェクトです) を返します。オブジェクトによっては、 値 (value) を変えることができます。値を変えることができる オブジェクトは 変更可能 (mutable) であるといいます; 値を 一度設定すると、その後は変えることができないオブジェクトは 変更不能 (immutable) であると呼びます。 (変更不能なコンテナオブジェクトが変更可能なオブジェクトへの参照を 含んでいる場合、その値は後者のオブジェクトの変更によって変わる 場合があります; その場合でも、コンテナの含んでいるオブジェクトの 集まりは変わらないため、コンテナは変更不能と考えます。したがって、 変更不能性 (immutability) は、厳密には変更できない値を持っている こととは違い、もっと微妙な概念です。) オブジェクトの変更可能性は型で決定されます; 例えば、数値、文字列、 およびタプルは変更不能であり、辞書やリストは変更可能です。

オブジェクトを明示的に破壊することはできません; しかし、オブジェクト に到達不能 (unreachable) になると、ガベージコレクション (garbage-collection) によって処理されます。実装では、ごみ収集を遅らせたり、全く行わない ようにすることができます -- 到達可能なオブジェクトをごみ収集処理して しまわないかぎり、どう実装するかは実装品質の問題です。 (実装上の注意: 現在の実装では参照カウント (reference-counting) 手順を 使っており、(オプションとして) 循環参照を行っているごみオブジェクトを 遅延検出します。この実装ではほとんどのオブジェクトを到達不能になると 同時に処理することができますが、循環参照を含むごみオブジェクトの収集が 確実に行われるよう保証しているわけではありません。循環参照を持つごみ オブジェクト収集の制御については、 Python ライブラリリファレンス を 参照してください。)

実装のトレース機能やデバッグ機能を使えば、通常は収集されてしまう ようなオブジェクトを生かしておくことがあるので注意してください。 また、 `try...except' 文を使って例外を捕捉できる ようにすると、オブジェクトを生かしておくことがあります。

オブジェクトによっては、開かれたファイルやウィンドウといった、 ``外部 (external) の'' リソースに対する参照を行っています。 これらのリソースは、オブジェクトがごみ収集された際に解放される ものと理解されていますが、ごみ収集が行われる保証はないので、 こうしたオブジェクトでは外部リソースを明示的に解放する 方法、大抵は close() メソッドを提供しています。 こうしたオブジェクトは明示的に close するよう強く奨めます。 操作をする際には、`try...finally' 文を使うと 便利です。

他のオブジェクトに対する参照をもつオブジェクトもあります; これらは コンテナ (container) と呼ばれます。コンテナオブジェクトの例 として、タプル、リスト、および辞書が挙げられます。オブジェクトへの 参照自体がコンテナの値の一部です。ほとんどの場合、コンテナの値と いうと、コンテナに入っているオブジェクトの値のことを指し、それら オブジェクトのアイデンティティではありません; しかしながら、 コンテナの変更可能性について述べる場合、今まさにコンテナに入っている オブジェクトのアイデンティティのことを指します。したがって、 (タプルのように) 変更不能なオブジェクトが変更可能なオブジェクト への参照を含む場合、その値が変化するのは変更可能なオブジェクトが 変更された時、ということになります。

型はオブジェクトの動作のほとんど全てに影響します。オブジェクトの アイデンティティが重要かどうかでさえ、ある意味では型に左右されます: 変更不能な型では、新たな値を計算するような操作を行うと、実際には同じ 型と値を持った既存のオブジェクトへの参照を返すことがありますが、 変更可能なオブジェクトではそのような動作は起こりえません。例えば、 "a = 1; b = 1" とすると、 a と b は値 1 を持つ 同じオブジェクトを参照するときもあるし、そうでないときもあります。 これは実装に依存します。しかし、 "c = []; d = []" とすると、 c と d はそれぞれ 二つの異なった、互いに一意な、新たに作成された空のリストを参照する ことが保証されています。 ("c = d = []" とすると、 c と d の両方に同じ オブジェクトを代入します)

... もまた変わることがありません。3.1
Python 2.2 以降、型とクラスの段階的な統合が始まっている ため、このドキュメントで主張されている内容が 100% 正確で完全と いうわけではなくなりました: 例えば、場合によっては、ある管理された 条件下でなら、オブジェクトの型を変更することができます。 このマニュアルに大幅な改訂が施されるまでは、このドキュメントでの 記述は、``旧クラス型 (classic class)'' に関してのみ 信頼できる内容と考えねばなりません。Python 2.2 および 2.3 では、 互換性のためにクラシックなクラスがまだデフォルトとなっています。
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3. データモデル Up: 3. データモデル Next: 3.2 標準型の階層


3.2 標準型の階層

以下は Python に組み込まれている型のリストです。(C、Java、または 実装に使われているその他の言語で書かれた) 拡張モジュールでは、 その他に新たな型を定義することができます。将来のバージョンの Python では、型の階層に新たな型 (整数を使って効率的に記憶される 有理数型、など) を追加することができるかもしれません。

以下に説明する型のいくつかには、`特殊属性 (special attribute)' と題された段落が連ねられています。これらの属性は実装へのアクセス 手段を提供するもので、一般的な用途に利用するためのものではありません。 特殊属性の定義は将来変更される可能性があります。

None
この型には単一の値しかありません。この値を持つオブジェクトはただ 一つしか存在しません。このオブジェクトは組み込み名 None でアクセスされます。このオブジェクトは、様々な状況で値が 存在しないことをしめします。例えば、明示的に値を返さない関数 は None を返します。None の真値 (truth value) は 偽 (false) です。

NotImplemented
この型には単一の値しかありません。この値を持つオブジェクトはただ 一つしか存在しません。このオブジェクトは組み込み名 NotImplemented でアクセスされます。数値演算に関するメソッドや拡張比較 (rich comparison) メソッドは、被演算子が該当する演算を行うための実装をもたない場合、 この値を返すことがあります。(演算子によっては、インタプリタが 関連のある演算を試したり、他の代替操作を行います。) 真値は真 (true) です。

Ellipsis
この型には単一の値しかありません。この値を持つオブジェクトはただ 一つしか存在しません。このオブジェクトは組み込み名 Ellipsis でアクセスされます。スライス内に "..." 構文がある場合に 使われます。真値は真 (true)です。

Numbers
数値リテラルによって作成されたり、算術演算や組み込みの算術関数に よって返されるオブジェクトです。数値オブジェクトは変更不能です; 一度値が生成されると、二度と変更されることはありません。Python の数値オブジェクトはいうまでもなく数学で言うところの数値と 強く関係していますが、コンピュータ内で数値を表現する際に伴う 制限を受けています。

Python は整数、浮動小数点数、複素数の間で区別を行っています:

整数型 (integer)

整数型は、全ての数 (whole numbers) を表す数学的集合内における要素を 表現する型です。

以下に三つの整数型を示します:

(通常の) 整数型 (plain integer)
-2147483648 から 2147483647 までの整数を表現します (基本ワードサイズ: natural word size がより大きなマシンではより大きな定義域になることも あります。より小さくなることはありません。) 演算の結果が定義域を超えた値になった場合、結果は通常長整数で 返されます (場合によっては、 OverflowError が送出され ます) 。 シフト演算やマスク演算のために、整数は 32 ビット以上の 2 の補数で 表されたバイナリ表現を持つ (すなわち、4294967296 の異なったビット パターン全てが異なる値を持つ) と仮定されています。

長整数型 (long integer)
長整数は無限の定義域を持ち、利用可能な (仮想) メモリサイズの制限 のみをうけます。長整数はシフト演算やマスク演算のためにバイナリ表現を もつものと仮定されます。負の数は符号ビットが左に無限に延びているような 錯覚を与える 2 の補数表現の変型で表されます。

ブール型 (boolean)
ブール型は、真値 False または True を表現します。ブール型の オブジェクトは False と True を表現する二つのオブジェクト だけです。ブール型は整数のサブタイプで、ほとんどの演算コンテキストに おいてブール型値はそれぞれ 0 または 1 のように振舞います。 ただし、文字列に変換されたときのみ、それぞれ文字列 "False" および "True" が返されます。

整数表現に関する規則は、シフト演算やマスク演算において、負の整数 も含めて最も有意義な解釈ができるように、かつ通常の整数と長整数 との間で定義域を切り替える際にできるだけ混乱しないように決められて います。左シフト以外の演算では、演算結果がオーバフローを起こさずに 整数の定義域の値になる場合は、長整数を使った場合でも、被演算子に 整数と長整数を混合した場合でも同じ結果になります。

浮動小数点数型 (floating point number)
この型は計算機レベルで倍精度とされている浮動小数点数を 表現します。表現可能な値の範囲やオーバフローの扱いは、 根底にある計算機アーキテクチャ (と C または Java 実装) 次第です。 Python は単精度の浮動小数点数をサポートしません; 単精度の 数を使う理由は、通常プロセッサやメモリ使用量の節約ですが、 こうした節約は Python でオブジェクトを扱う際のオーバヘッドに比べれば 微々たるものにすぎません。従って、わざわざ浮動小数点型を 2 つも 定義してPython 言語を難解にする理由はどこにもないのです。

複素数型 (complex number)
この型は、計算機レベルで倍精度とされている浮動小数点を 2 つ一組 にして複素数を表現します。浮動小数点について述べたのと同じ性質 が当てはまります。複素数 z の実数部および虚数部は、 それぞれ読み出し専用属性 z.real および z.imag で取り出すことができます。

配列型 (sequence)
この型は、有限の順序集合 (ordered set) を表現します。要素は非負の 整数でインデクス化されています。組み込み関数 len() を使うと、配列の要素数を返します。 配列の長さが n の場合、インデクスは 0, 1, ..., n-1 からなる集合です。配列 a の要素 i は a[i] で選択します。

配列はスライス操作 (slice) もサポートしています: a[i:j] とすると、 i <= k < j であるインデクス k をもつ全ての要素を選択します。 式表現としてスライスを用いた場合、スライスは同じ型をもつ新たな配列を 表します。新たな配列内では、インデクス集合が 0 から始まるように インデクスの値を振りなおします。

配列によっては、 第三の ``ステップ (step)'' パラメタを持つ ``拡張スライス (extended slice)'' もサポートしています: a[i:j:k] は、 x = i + n*k, n >= 0 かつ i <= x < j であるような インデクス x を持つような a 全ての要素を選択します。

配列は、変更可能なものか、そうでないかで区別されています:

変更不能な配列 (immutable sequence)
変更不能な配列型のオブジェクトは、一度生成されるとその値を 変更することができません。 (オブジェクトに他のオブジェクトへの 参照が入っている場合、参照されているオブジェクトは変更可能な オブジェクトでもよく、その値は変更される可能性があります; しかし、変更不能なオブジェクトが直接参照しているオブジェクトの 集合自体は、変更することができません。)

以下の型は変更不能な配列型です:

文字列型 (string)
文字列の各要素は文字 (character) です。文字型 (character type) は存在しません; 単一の文字は、要素が一つだけの文字列として 表現されます。各文字は (少なくとも) 8-bit のバイト列を表現します。 組み込み関数 chr() および ord() を使うと、文字と非負の整数で表された バイト値の間で変換を行えます。0-127 の値を持つバイト値は、通常 同じ ASCII 値をもつ文字を表現していますが、値をどう解釈するかは プログラムにゆだねられています。文字列データ型はまた、例えば ファイルから読み出されたデータを記憶するといった用途で、バイト値の アレイを表現するために用いられます。

(ネイティブの文字セットが ASCIIでないシステムでは、chr() や ord() が ASCII と EBCDIC との間で対応付けを行っており、 文字列間の比較で ASCII 順が守られる限り、文字列の内部表現として EBCDIC を使ってもかまいません。誰か他にもっとましなルールをお持ちですか?)

Unicode 文字列型
Unicode オブジェクトの各要素は Unicode コード単位です。 Unicode コード単位とは、単一の Unicode オブジェクトで、Unicode 序数を 表現する 16-bit または 32-bit の値を保持できるものです (この序数の最大値は sys.maxunicode で与えられており、コンパイル時に Python がどう設定されているかに依存します)。 Unicode オブジェクト内 にサロゲートペア (surrogate pair) があってもよく、Python は サロゲートペアを二つの別々の Unicode 要素として報告します。 組み込み関数 unichr() および ord() は、コード単位と非負の整数で表された Unicode 標準 3.0 で定義された Unicode 序数との間で変換を行います。 他の文字エンコード形式との相互変換は、 Unicode メソッド encode および組み込み関数 unicode()で行うことができます。

タプル型 (tuple)
タプルの要素は任意の Python オブジェクトにできます。 二つまたはそれ以上の要素からなるタプルは、個々の要素を表現する 式をカンマで区切って構成します。単一の要素からなるタプル (単集合 `singleton') を作るには、要素を表現する式の直後に カンマをつけます (単一の式だけではタプルを形成しません。 これは、式をグループ化するのに丸括弧を使えるようにしなければ ならないからです) 。要素の全くない丸括弧の対を作ると空のタプルに なります。

変更可能な配列型 (mutable sequence)
変更可能な配列は、作成した後で変更することができます。 変更可能な配列では、添字表記やスライス表記を使って指定された要素に 代入を行うことができ、del (delete) 文を使って要素を 削除することができます。

Python に最初から組み込まれている変更可能な配列型は、今のところ 一つだけです:

リスト型 (list)
リストの要素は任意の Python オブジェクトにできます。リストは、 角括弧の中にカンマで区切られた式を並べて作ります。 (長さが 0 や 1 の配列を作るために特殊な場合分けは必要ないことに 注意してください。)

拡張モジュール arrayでは、別の 変更可能な配列型を提供しています。

マップ型 (mapping)
任意のインデクス集合でインデクス化された、有限のオブジェクトからなる 集合を表現します。添字表記 a[k] は、k でインデクス指定 された要素を a から選択します; 選択された要素は式の中で 使うことができ、代入や del 文の対象にすることができます。 組み込み関数 len() は、マップ内の要素数を返します。

Python に最初から組み込まれているマップ型は、今のところ 一つだけです:

辞書型 (dictionary)
ほとんどどんな値でもインデクスとして使えるような、 有限個のオブジェクトからなる集合を表します。キー値 (key) として使えない 値は、リストや辞書を含む値や、アイデンティティではなく値でオブジェクトが 比較される、その他の変更可能な型です。これは、辞書型を効率的に 実装する上で、キーのハッシュ値が一定であることが必要だからです。 数値型をキーに使う場合、キー値は通常の数値比較における規則に 従います: 二つの値が等しくなる場合 (例えば 1 と 1.0)、 互いに同じ辞書のエントリを表すインデクスとして使うことができます。

辞書は変更可能な型です; 辞書は {...} 表記で生成します ( 5.2.5 節, ``辞書表現'' を参照してください)。

拡張モジュール dbm、 gdbm、および bsddbでは、別のマップ型を提供 しています。

呼び出し可能型 (callable type)
関数呼び出し操作 ( 5.3.4 節、``呼び出し (call)'' 参照) を行うことができる型です:

ユーザ定義関数 (user-defined function)
ユーザ定義関数オブジェクトは、関数定義を行うことで生成されます ( 7.5 節、``関数定義'' 参照)。関数は、仮引数 (formal parameter) リストと同じ数の要素が入った引数リストと ともに呼び出されます。

特殊属性: func_doc または __doc__ は 関数のドキュメンテーション文字列です。ドキュメンテーションがない 場合は None になります; func_name または __name__ は関数の名前です; __module__ は、関数が定義されているモジュールの名前です。 モジュール名がない場合は None になります; func_defaults はデフォルト値を持つ引数に対するデフォルト値が 収められたタプルで、デフォルト値を持つ引数がない場合には None になります; func_code はコンパイルされた関数本体を表現する コードオブジェクトです; func_globals は関数のグローバル変数 の入った辞書 (への参照) です -- この辞書は、関数が定義されている モジュールのグローバルな名前空間を決定します; func_dict または __dict__ には、任意の関数属性をサポートするための名前空間が 収められています; func_closure は、 None または 関数の個々の自由変数（引数以外の変数）に対して値を結び付けている セル (cell) 群からなるタプルになります。

上記のうち、func_code 、 func_defaults 、 func_doc/__doc__ 、および func_dict/__dict__ は書き込み可能な属性です; 他の属性は変更できません。関数定義に関するその他の情報は、 関数のコードオブジェクトから得られます; 後述の内部型 (internal type) に関する説明を参照してください。

ユーザ定義メソッド (user-defined method)
ユーザ定義のメソッドオブジェクトは、クラスやクラスインスタンス (あるいは None) を任意の呼び出し可能オブジェクト (通常は ユーザ定義関数) と結合し (combine) ます。

読み出し専用の特殊属性: im_self は クラスインスタンスオブジェクトで、im_func は関数オブジェクト です; im_class は結合メソッド (bound method) において im_self が属しているクラスか、あるいは非結合メソッド (unbound method) において、要求されたメソッドを定義している クラスです; __doc__ はメソッドのドキュメンテーション文字列 (im_func.__doc__ と同じ) です; __name__ はメソッドの 名前 (im_func.__name__ と同じ) です; __module__ は メソッドが定義されているモジュールの名前になるか、モジュール名が ない場合は None になります。 バージョン2.2 以降で変更された 仕様: メソッドを定義しているクラスを参照するために im_self が使われていました

メソッドもまた、根底にある関数オブジェクトの任意の関数属性 に (値の設定はできませんが) アクセスできます。

クラスの属性を (おそらくクラスのインスタンスを介して) 取得する際には、 その属性がユーザ定義の関数オブジェクト、非結合 (unbound) のユーザ定義 メソッドオブジェクト、あるいはクラスメソッドオブジェクトであれば、 ユーザ定義メソッドオブジェクトが生成されることがあります。 属性がユーザ定義メソッドオブジェクトの場合、属性を取得する対象の オブジェクトが属するクラスがもとのメソッドオブジェクトが定義されている クラスと同じクラスであるか、またはそのサブクラスであれば、新たな メソッドオブジェクトだけが生成されます。 それ以外の場合には、もとのメソッドオブジェクトがそのまま使われます。

クラスからユーザ定義関数オブジェクトを取得する方法でユーザ定義 メソッドオブジェクトを生成すると、 im_self 属性は None になり、メソッドオブジェクトは非結合 (unbound) であるといいます。クラスのインスタンスからユーザ定義関数 オブジェクトを取得する方法でユーザ定義メソッドオブジェクトを 生成すると、im_self 属性はインスタンスになり、 メソッドオブジェクトは結合 (bound) であるといいます。 どちらの場合も、新たなメソッドの im_class 属性は、 メソッドの取得が行われたクラスになり、im_func 属性は もとの関数オブジェクトになります。

クラスやインスタンスから他のユーザ定義メソッドオブジェクトを 取得する方法でユーザ定義メソッドオブジェクトを生成した場合、 その動作は関数オブジェクトの場合と同様ですが、新たなインスタンスの im_func 属性はもとのメソッドオブジェクトの属性ではなく、 新たなインスタンスの属性になります。

クラスやインスタンスからクラスメソッドオブジェクトを取得する 方法でユーザ定義メソッドオブジェクトを生成した場合、 im_self 属性はクラス自体 (im_class 属性と 同じ) となり、im_func 属性はクラスメソッドの根底に ある関数オブジェクトになります。

非結合ユーザ定義メソッドオブジェクトの呼び出しの際には、 根底にある関数 (im_func) が呼び出されます。このとき、 最初の引数は適切なクラス (im_class) またはサブクラスの インスタンスでなければならないという制限が課されています。

結合ユーザ定義メソッドオブジェクトの呼び出しの際には、 根底にある関数 (im_func) が呼び出されます。このとき、 クラスインスタンス (im_self) が引数の先頭に挿入され ます。例えば、関数 f() の定義が入ったクラスを C とし、x を C のインスタンスとすると、 x.f(1) の呼び出しは C.f(x, 1) と同じになります。

ユーザ定義メソッドオブジェクトがクラスオブジェクトから導出される際、 im_self に記憶されている ``クラスインスタンス'' はクラス 自体になります。これは、x.f(1) や C.f(1) の呼び出しが 根底にある関数を f としたときの呼び出し f(C,1) と 等価になるようにするためです。

関数オブジェクトから (結合または非結合の) メソッドオブジェクトへの 変換は、クラスやインスタンスから属性を取り出すたびに行われるので 注意してください。場合によっては、属性をローカルな変数に代入して おき、その変数を使って関数呼び出しを行うと効果的な最適化になります。 また、上記の変換はユーザ定義関数に対してのみ起こるので注意してください; その他の呼び出し可能オブジェクト (および呼び出し可能でない全ての オブジェクト) は、変換を受けずに取り出されます。それから、 クラスインスタンスの属性になっているユーザ定義関数は、結合メソッドに 変換できないと知っておくことも重要です; 結合メソッドへの変換が 行われるのは、関数がクラスの一属性である場合 だけ です。

ジェネレータ関数 (generator function)
yield 文 ( 6.8 節、``yield 文'' 参照) を使う関数またはメソッドは、ジェネレータ関数 (generator function) と呼ばれます。このような関数は、呼び出された 際に、常にイテレータオブジェクトを返します。このイテレータオブジェクトは 関数の本体を実行するために用いられます: イテレータの next() メソッドを呼び出すと、yield 文で値を出力する処理まで関数の 実行が行われます。関数が return 文を実行するか、関数を最後まで 実行し終えると、StopIteration 例外が送出され、イテレータが 返す値の集合はそこで終わります。

組み込み関数 (built-in function)
組み込み関数オブジェクトは C 関数へのラッパです。組み込み関数の例は len() や math.sin() (math は標準の組み込み モジュール) です。引数の数や型は C 関数で決定されています。 読み出し専用の特殊属性: __doc__ は関数のドキュメンテーション 文字列です。ドキュメンテーションがない場合は None になります; __name__ は関数の名前です; __self__ は None に設定されています (組み込みメソッドの節も参照してください); __module__ は、関数が定義されているモジュールの名前です。 モジュール名がない場合は None になります。

組み込みメソッド (built-in method)
実際には組み込み関数を別の形で隠蔽したもので、こちらの場合には C 関数に渡される何らかのオブジェクトを非明示的な外部引数として 持っています。組み込みメソッドの例は、alist をリストオブジェクト としたときの alist.append() です。 この場合には、読み出し専用の属性 __self__ は alist で表されるオブジェクトになります。

クラス型 (class type)
クラス型、あるいは ``新しいクラス型 (new-style class)'' や呼び出し可能 オブジェクトです。クラス型オブジェクトは通常、そのクラスの新たな インスタンスを生成する際のファクトリクラスとして振舞いますが、 __new__() をオーバライドして、バリエーションを持たせることも できます。呼び出しの際に使われた引数は __new__() に渡され、 さらに典型的な場合では新たなインスタンスを初期化するために __init__() に渡されます。

旧クラス型 (classic class)
(旧) クラスオブジェクトは後で詳しく説明します。クラスオブジェクトが 呼び出されると、新たにクラスインスタンス (後述) が生成され、返されます。 この操作には、クラスの __init__() メソッドの呼び出し (定義されている場合) が含まれています。呼び出しの際に使われた引数は、 すべて __init__() メソッドに渡されます。 __init__() メソッドがない場合、クラスは引数なしで呼び出さなければ なりません。

クラスインスタンス (class instance)
クラスインスタンスは後で詳しく説明します。クラスインスタンスは クラスが __call__() メソッドを持っている場合にのみ呼び出す ことができます; x(arguments) とすると、 x.__call__(arguments) 呼び出しを短く書けます。

モジュール (module)
モジュールは import 文で import します ( 6.12 節、 ``import 文'' 参照)。モジュールオブジェクトは、辞書オブジェクト (モジュール内で定義されて いる関数が func_globals 属性で参照している辞書です) で実装された 名前空間を持っています。属性への参照は、この辞書に対する検索 (lookup) に翻訳されます。例えば、m.x は m.__dict__["x"] と同じです。 モジュールオブジェクトには、モジュールを初期化するために使われる コードオブジェクトは入っていません (一度初期化が終わればもう必要 ないからです)。

属性の代入を行うと、モジュールの名前空間辞書の内容を更新します。 例えば、 "m.x = 1" は "m.__dict__["x"] = 1" と同じです。

読み出し専用の特殊属性: __dict__ はモジュールの名前空間で、 辞書オブジェクトです。

定義済みの (書き込み可能な) 属性: __name__ はモジュールの名前です; __doc__ は関数のドキュメンテーション 文字列です。ドキュメンテーションがない場合は None になります; モジュールがファイルからロードされた場合、 __file__ はロード されたモジュールファイルのパス名です。インタプリタに静的にリンクされて いる C モジュールの場合、__file__ 属性はありません; 共有ライブラリから動的にロードされた拡張モジュールの場合、この属性は 共有ライブラリファイルのパス名になります。

クラス
クラスオブジェクトはクラス定義 ( 7.6 節、 ``クラス定義'' 参照) で生成されます。クラスは辞書で実装された名前空間を持っています。 クラス属性への参照は、この辞書に対する検索 (lookup) に翻訳されます。例えば、C.x は C.__dict__["x"] と同じです。 属性がこの検索で見つからない場合、現在のクラスの基底クラスへと 検索を続けます。検索は深さ優先 (depth-first)、かつ基底クラスの 挙げられているリスト中の左から右 (left-to-right) の順番で行われ ます。

クラス (C とします) への属性参照で、要求している属性が ユーザ定義関数オブジェクトや、C やその基底クラスに関連付け られている非結合のユーザ定義メソッドオブジェクトである場合、 im_class 属性が C であるような非結合ユーザ定義 メソッドオブジェクトに変換されます。 要求している属性がクラスメソッドオブジェクトの場合、 im_class と im_self 属性がどちらも C であるようなユーザ定義メソッドオブジェクトに変換されます。 要求している属性が静的メソッドオブジェクトの場合、静的メソッド オブジェクトでラップされたオブジェクトに変換されます。 クラスから取り出した属性と実際に __dict__ に入っている ものが異なるような他の場合については、 3.3.2 節を 参照してください。

クラス属性を代入すると、そのクラスの辞書だけが更新され、基底クラスの 辞書は更新しません。

クラスオブジェクトを呼び出す (上記を参照) と、クラスインスタンスを 生成します (下記を参照)。

特殊属性: __name__ はクラス名です; __module__ はクラスが定義されているモジュールの名前です; __dict__ はクラスの名前空間が入った辞書です; __bases__ は基底クラスの入った (空、あるいは単要素を取りえる) タプルで、基底クラスリストの順番になっています; __doc__ は クラスのドキュメンテーション文字列です。ドキュメンテーション文字列が ない場合には None になります。

クラスインスタンス
クラスインスタンスはクラスオブジェクト (上記参照) を呼び出して 生成します。クラスインスタンスは辞書で実装された名前空間を持って おり、属性参照の時にはこの辞書が最初に検索されます。 辞書内に属性が見つからず、かつインスタンスのクラスに該当する 属性名がある場合、検索はクラス属性にまで広げられます。 見つかったクラス属性がユーザ定義関数オブジェクトや、 インスタンスのクラス (C とします) やその基底クラスに関連 付けられている非結合のユーザ定義メソッドオブジェクトの場合、 im_class 属性が C で im_self 属性が インスタンスになっている結合ユーザ定義メソッドオブジェクトに変換 されます。静的メソッドやクラスメソッドオブジェクトもまた、 C から取り出した場合と同様に変換されます; 上記の ``クラス'' を参照してください。 クラスから取り出した属性と実際に __dict__ に入っている ものが異なるような他の場合については、 3.3.2 節を 参照してください。 クラス属性が見つからず、かつオブジェクトのクラスが __getattr__() メソッドを持っている場合、このメソッドを 呼び出して属性名の検索を充足させます。

属性の代入や削除を行うと、インスタンスの辞書を更新しますが、クラスの 辞書を更新することはありません。クラスで __setattr__() や __delattr__() メソッドが定義されている場合、直接インスタンスの 辞書を更新する代わりにこれらのメソッドが呼び出されます。

クラスインスタンスは、ある特定の名前のメソッドを持っている 場合、数値型や配列型、あるいはマップ型のように振舞うことが できます。 3.3 節、 ``特殊メソッド名'' を参照 してください。

特殊属性: __dict__ は属性の辞書です; __class__ はインスタンスのクラスです。

ファイル (file)
ファイル オブジェクトは開かれたファイルを表します。 ファイルオブジェクトは組み込み関数 open() や、os.popen(), os.fdopen(), および socke オブジェクトの makefile()メソッド (その他の拡張モジュールで提供されている関数やメソッド) で生成 されます。codesys.stdin, sys.stdout および sys.stderr といったオブジェクトは、 インタプリタの標準入力�ﾇ現狃侘蓮△�｢茲喇現爛┘蕁悉侘ﾏ ストリームに対応するよう初期化されます。ファイルオブジェクトに 関する完全な記述については、Python ライブラリ リファレンス を参照してください。

内部型 (internal type)
インタプリタが内部的に使っているいくつかの型は、ユーザに公開されています。 これらの定義は将来のインタプリタのバージョンでは変更される可能性が ありますが、ここでは記述の完全性のために触れておきます。

コードオブジェクト
コードオブジェクトは バイトコンパイルされた (byte-compiled) 実行可能な Python コード、別名 バイトコード (bytecode) を 表現します。コードオブジェクトと関数オブジェクトの違いは、 関数オブジェクトが関数のグローバル変数 (関数を定義しているモジュールの グローバル) に対して明示的な参照を持っているのに対し、コードオブジェクト にはコンテキストがないということです; また、関数オブジェクトでは デフォルト引数値を記憶できますが、コードオブジェクトではできません (実行時に計算される値を表現するため)。関数オブジェクトと違い、 コードオブジェクトは変更不可能で、変更可能なオブジェクトへの参照を (直接、間接に関わらず) 含みません。

読み出し専用の特殊属性: co_name は関数名を表します; co_argcount は固定引数 (positional argument) の数です; co_nlocals は関数が使う (引数を含めた) ローカル変数の数です; co_varnames はローカル変数名の入ったタプルです (引数名 から始まっています); co_cellvars はネストされた関数で 参照されているローカル変数の名前が入ったタプルです; co_freevars は自由変数の名前が入ったタプルです。 co_code はバイトコード列を表現している文字列です; co_consts はバイトコードで使われているリテラルの入った タプルです; co_names はバイトコードで使われている名前 の入ったタプルです; co_filename はバイトコードのコンパイル が行われたファイル名です; co_firstlineno は関数の最初の 行番号です; co_lnotab はバイトコードオフセットから行番号 への対応付けをコード化した文字列です (詳細についてはインタプリタの ソースコードを参照してください); co_stacksize は関数で (ローカル変数の分も含めて) 必要なスタックサイズです; co_flags はインタプリタ用の様々なフラグをコード化した 整数です。

以下のフラグビットが co_flags で定義されています: 0x04 ビットは、関数が "*arguments" 構文を使って 任意の数の固定引数を受理できる場合に立てられます; 0x08 ビットは、関数が "**keywords" 構文を使って キーワード引数を受理できる場合に立てられます; 0x20 ビットは、関数がジェネレータである場合に立てられます。

将来機能 (future feature) 宣言 ("from __future__ import division") もまた、co_flags のビットを立てることで、コードオブジェクトが 特定の機能を有効にしてコンパイルされていることを示します: 0x2000 ビットは、関数が将来機能を有効にしてコンパイルされて いる場合に立てられます; 以前のバージョンの Python では、0x10 および 0x1000 ビットが使われていました。

co_flags のその他のビットは将来に内部的に利用するために 予約されています。

コードオブジェクトが関数を表現している場合、co_consts の最初の 要素は関数のドキュメンテーション文字列 になります。ドキュメンテーション文字列が定義されていない場合には None になります。

フレーム (frame) オブジェクト
フレームオブジェクトは実行フレーム (execution frame) を表します。 実行フレームはトレースバックオブジェクト内に出現します (下記参照)。

読み出し専用の特殊属性: f_back は (呼び出し側にとっての) 以前のスタックフレームです。呼び出し側がスタックフレームの最下段で ある場合には None です; f_code は現在のフレームで 実行しようとしているコードオブジェクトです; f_locals はローカル変数を検索するために使われる辞書です; f_globals はグローバル変数用です; f_builtins は組み込みの (Python 固有の) 名前です; f_restricted は、関数が制限つき実行 (restricted execution) モードで実行されているかどうかを示すフラグです; f_lasti は厳密な命令コード (コードオブジェクト中のバイトコード文字列への インデクス) です。

書き込み可能な特殊属性: f_trace が None でない場合、 各ソースコード行の先頭で呼び出される関数になります; f_exc_type, f_exc_value, f_exc_traceback は、現在のフレームでもっとも最近捕捉された例外を表します; f_lineno はフレーム中における現在の行番号です -- トレース関数 (trace function) 側でこの値に書き込みを行うと、指定した行にジャンプ します (最下段の実行フレームにいるときのみ) 。デバッガでは、 f_fileno を書き込むことで、ジャンプ命令 (Set Next Statement 命令とも 呼ばれます) を実装できます。

トレースバック (traceback) オブジェクト
トレースバックオブジェクトは例外のスタックトレースを表現します。 トレースバックオブジェクトは例外が発生した際に生成されます。 例外ハンドラを検索して実行スタックを戻っていく際、戻ったレベル 毎に、トレースバックオブジェクトが現在のトレースバックの前に 挿入されます。例外ハンドラに入ると、スタックトレースを プログラム側で利用できるようになります ( 7.4 節 ``try 文'' を参照)。 トレースバックは sys.exc_traceback として得ることができ、 sys.exc_info() が返すタプルの三番目の要素としても得られます. インタフェースとしては後者の方が推奨されていますが、これは プログラムがマルチスレッドを使っている場合に正しく動作するからです。 プログラムに適切なハンドラがない場合、スタックトレースは (うまく 書式化されて) 標準エラーストリームに書き出されます; インタプリタが 対話的に実行されている場合、sys.last_traceback として 得ることもできます。

読み出し専用の特殊属性: tb_next はスタックトレース内の (例外の発生しているフレームに向かって) 次のレベルです。 次のレベルが存在しない場合には None になります; tb_frame は現在のレベルにおける実行フレームを指します; tb_lineno は例外の発生した行番号です; tb_lasti は厳密な命令コードです。トレースバック内の行番号や最後に実行された 命令は、try 文内で例外が発生し、かつ対応する except 節や finally 節がない場合には、 フレームオブジェクト内の行番号とは異なるかもしれません。

スライス (slice) オブジェクト
スライスオブジェクトは 拡張スライス構文 (extended slice syntax) が使われた際にスライスを表現するために使われます。拡張スライス構文とは、 二つのコロンや、コンマで区切られた複数のスライスや省略符号 (ellipse) を使ったスライスで、例えば a[i:j:step] 、 a[i:j, k:l] 、 あるいは a[..., i:j] です。スライスオブジェクトは組み込み関数 slice() で生成されます。

読み出し専用の特殊属性: start は下境界 (lower bound) です; stop は上境界 (upper bound) です; step はステップ値 (step value) です; それぞれ省略されている場合には None になります。 これらの属性は任意の型の値をとることができます。

スライスオブジェクトはメソッドを一つサポートします:

indices( self, length)
このメソッドは単一の整数引数 length を取り、length 個の要素からなる配列に適用した際にスライスオブジェクトから提供 することになる、拡張スライスに関する情報を計算します。 このメソッドは三つの整数からなるタプルを返します; それぞれ start および stop のインデクスと、step または スライス間の幅に対応します。インデクス値がないか、範囲外の値 である場合、通常のスライスに対して一貫性のあるやりかたで扱われます。 バージョン2.3 以降で新規追加された 仕様です。

静的メソッド (static method) オブジェクト
静的メソッドは、上で説明したような関数オブジェクトからメソッド オブジェクトへの変換を阻止するための方法を提供します。静的メソッド オブジェクトは他の何らかのオブジェクト、通常はユーザ定義メソッド オブジェクトを包むラッパです。静的メソッドをクラスやクラスインスタンス から取得すると、実際に返されるオブジェクトはラップされたオブジェクト になり、それ以上は変換の対象にはなりません。静的メソッドオブジェクト は通常呼び出し可能なオブジェクトをラップしますが、静的オブジェクト自体は 呼び出すことができません。静的オブジェクトは組み込みコンストラクタ staticmethod() で生成されます。

クラスメソッドオブジェクト
クラスメソッドオブジェクトは、静的メソッドオブジェクトに似て、 別のオブジェクトを包むラッパであり、そのオブジェクトをクラスや クラスインスタンスから取り出す方法を代替します。 このようにして取得したクラスメソッドオブジェクトの動作については、 上の ``ユーザ定義メソッド (user-defined method)'' で説明されています。 クラスメソッドオブジェクトは組み込みのコンストラクタ classmethod() で生成されます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3.1 オブジェクト、値、および型 Up: 3. データモデル Next: 3.3 特殊メソッド名


3.3 特殊メソッド名

特殊な名前をもったメソッドを定義することで、特殊な構文 (算術演算や 添え字表記、スライス表記のような) 特定の演算をクラスで実装することが できます。これは、個々のクラスが Python 言語で提供されている演算子に対応した 独自の振る舞いをできるようにするための、演算子のオーバロード (operator overloading) に対する Python のアプローチです。 例えば、あるクラスが __getitem__() という名前のメソッドを定義 しており、x がこのクラスのインスタンスであるとすると、 x[i] は x.__getitem__(i) と等価になります。特に注釈の ない限り、適切なメソッドが定義されていない場合にこのような演算を行おうと すると例外が送出されます。

組み込み型をエミュレーションするようなクラスを実装する際には、 エミューレーションの実装をモデル化しようとしているオブジェクトで 意味のある範囲だけにとどめることが重要です。 例えば、配列によっては個々の要素の取り出し操作が意味のある操作で ある一方、スライスの抽出が意味をなさないことがあります。 (W3C ドキュメントオブジェクトモデルにおける NodeList インタフェースがその一例です。)

  • 3.3.1 基本的なカスタマイズ
  • 3.3.2 属性値アクセスをカスタマイズする
    • 3.3.2.1 新しい形式のクラスのための別の属性アクセス
    • 3.3.2.2 デスクリプタ (descriptor) の実装
    • 3.3.2.3 デスクリプタを呼び出す
    • 3.3.2.4 __slots__
  • 3.3.3 クラス生成をカスタマイズする
  • 3.3.4 呼び出し可能オブジェクトをエミュレートする
  • 3.3.5 コンテナをエミュレートする
  • 3.3.6 配列型エミュレーションで使われるその他のメソッド
  • 3.3.7 数値型をエミュレーションする
  • 3.3.8 型強制規則 (coercion rule)
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3.2 標準型の階層 Up: 3. データモデル Next: 3.3.1 基本的なカスタマイズ


3.3.1 基本的なカスタマイズ

__init__( self[, ...])
インスタンスが生成された際に呼び出されるコンストラクタ (constructor) です。引数はそのクラスのコンストラクタ式に渡した引数になります。 基底クラスが__init__() メソッドを持っている場合、 導出クラスの __init__() メソッドでは、 例えば "BaseClass.__init__(self, [args...])" の ように、必要ならば明示的に基底クラスの__init__() メソッドを 呼び出して、インスタンスの基底クラスに関わる部分が正しく初期化される ようにしなければなりません。コンストラクタには、値を返してはならない という特殊な制限があります; 値を返すようにすると、実行時に TypeError の送出を引き起こします。

__del__( self)
インスタンスが消滅させられる際に呼び出されます。このメソッドは デストラクタ (destructor) とも呼ばれます。 基底クラスが__del__() メソッドを持っている場合、 導出クラスの __del__() メソッドでは、必要ならば明示的に 基底クラスの__del__() メソッドを 呼び出して、インスタンスの基底クラスに関わる部分が正しく消滅処理 されるようにしなければなりません。 __del__() メソッドでインスタンスに対する新たな参照を 作ることで、インスタンスの消滅を遅らせることができます (とはいえ、推奨しません！)。このようにすると、新たに作成された 参照がその後削除された際にもう一度 __del__() メソッド が呼び出されます。 インタプリタが終了する際に残っているオブジェクトに対して、 __del__() メソッドが呼び出される保証はありません。

注意: "del x" は直接 x.__del__() を呼び出しません -- 前者は x への参照カウント (reference count) を 1 つ減らし、 後者は x への参照カウントがゼロになった際にのみ呼び出されます。 オブジェクトへの参照カウントがゼロになるのを妨げる可能性のある よくある状況には、以下のようなものがあります: 複数のオブジェクト間 における循環参照 (二重リンクリストや、親と子へのポインタを持つツリー データ構造); 例外を捕捉した関数におけるスタックフレーム上にある オブジェクトへの参照 (sys.exc_traceback に記憶されている トレースバックが、スタックフレームを生き延びさせます); または、対話モードでハンドルされなかった例外を送出した スタックフレーム上にあるオブジェクトへの参照 (sys.last_traceback に記憶されているトレースバックが、 スタックフレームを生き延びさせます); 最初の状況については、明示的に循環参照を壊すしか解決策は ありません; 後者の二つの状況は、None を sys.exc_traceback や sys.last_traceback に 入れることで解決できます。ごみオブジェクトと化した循環参照は、 オプションの循環参照検出機構 (cycle detector) が有効にされて いる場合 (これはデフォルトの設定です) には検出されますが、 検出された循環参照を消去するのは Python レベルで __del__() メソッドが定義されていない場合だけです。 __del__() メソッドが循環参照検出機構でどのように 扱われるか、とりわけ garbage 値の記述に関しては、 gc モジュール の ドキュメントを参照してください。

警告: __del__() メソッドの呼び出しが起きるのは不安定な状況 なので、__del__() の実行中に発生した例外は無視され、 代わりに sys.stderr に警告が出力されます。また、 (例えばプログラムの実行終了による) モジュールの削除に伴って __del__() が呼び出される際には、__del__() メソッドが参照している他のグローバル変数はすでに削除されている かもしれません。この理由から、 __del__() メソッドでは 外部の不変関係を維持する上で絶対最低限必要なことだけをすべき です。バージョン 1.5 からは、単一のアンダースコアで始まるような グローバル変数は、他のグローバル変数が削除される前にモジュール から削除されるように Python 側で保証しています; これらの アンダースコア付きグローバル変数は、__del__() が呼び 出された際に、import されたモジュールがまだ残っているか確認 する上で役に立ちます。

__repr__( self)
組み込み関数repr() や、文字列への 変換 (逆クオート表記: reverse quote) の際に呼び出され、 オブジェクトを表す ``公式の (official)'' 文字列を計算します。 可能な場合には、この値は同じ値を持ったオブジェクトを (適切な環境で) 再生成するために使えるような有効な Python 式に 似せるべきです。それが不可能なら、"<...some useful description...>" 形式の文字列を返してください。 戻り値は文字列オブジェクトでなければなりません。 クラスが __repr__() を定義しているが __str__() を定義していない場合、そのクラスのインスタンスに対する ``非公式の (informal)'' 文字列表現が必要なときにも __repr__() が使われます。

この関数はデバッグの際によく用いられるので、たくさんの情報を 含み、あいまいでないような表記にすることが重要です。

__str__( self)
組み込み関数 str() および print 文によって呼び出され、 オブジェクトを表す ``非公式の (informa)'' 文字列を計算します。 このメソッドは、有効な Python 式を返さなくても良いという点で、 __repr__() と異なります: その代わり、より便利で分かりやすい 表現を返すようにしてください。戻り値は文字列オブジェクトで なければなりません。

__lt__( self, other)
__le__( self, other)
__eq__( self, other)
__ne__( self, other)
__gt__( self, other)
__ge__( self, other)
バージョン2.1 以降で新規追加された 仕様です。 これらのメソッドは ``拡張比較 (rich comparison)'' メソッドと呼ばれ、 下記の __cmp__() に優先して呼び出されます。 演算子シンボルとメソッド名の対応は以下の通りです: x<y は x.__lt__(y) を呼び出します; x<=y は x.__le__(y) を呼び出します; x==y は x.__eq__(y) を呼び出します; x!=y および x<>y は x.__ne__(y) を呼び出します; x>y は x.__gt__(y) を呼び出します; x>=y は x.__ge__(y) を呼び出します。 これらのメソッドは任意の値を返すことができますが、比較演算子が ブール値のコンテキストで使われた場合、戻り値はブール値として 解釈可能でなければなりません。そうでない場合には TypeError が送出されます。 慣習的には、 False は偽値、 True は真値として用いられ ます。

比較演算子間には、暗黙的な論理関係はありません。すなわち、 x==y が真である場合、暗黙のうちに x!=y が偽になるわけではありません。 従って、__eq__ を実装する際、演算子が期待通りに 動作するようにするために __ne__ も定義する必要があります。

これらのメソッドには、(左引数が演算をサポートしないが、右引数は
サポートする場合に用いられるような) 鏡像となる (引数を入れ替えた)
バージョンは存在しません; むしろ、__lt__() と
__gt__() は互いに鏡像であり、__le__() と
__ge__() 、および __eq__() と
__ne__() はそれぞれ互いに鏡像です。

拡張比較メソッドの引数には型強制 (coerce) が起こりません。 与えられた引数ペアの間で演算が実装されていない場合、拡張比較 メソッドは NotImplemented を返します。

__cmp__( self, other)
拡張比較 (上参照) が定義されていない場合、比較演算によって 呼び出されます。self < other である場合には負の値、 self == other ならばゼロ、self > other であれば 正の値を返さなければなりません。演算 __cmp__() 、__eq__() および __ne__() がいずれも定義されていない場合、 クラスインスタンスはオブジェクトのアイデンティティ (``アドレス'') で比較されます。自作の比較演算をサポートするオブジェクトや、 辞書のキーとして使えるオブジェクトを生成するには、 __hash__() に関する記述を参照してください。 (注意: __cmp__() が例外を伝播しないという制限は Python 1.5 から除去されました。)

__rcmp__( self, other)
バージョン2.1 以降で変更された 仕様: もはやサポートされていません

__hash__( self)
辞書演算 の際にキーとなるオブジェクトに対して 呼び出されたり、組み込み関数 hash() から呼び出されたり します。 辞書演算におけるハッシュ値として利用できる、32 ビットの 整数を返さなければなりません。 このメソッドに必要な性質は、比較結果が等価であるオブジェクトは 同じハッシュ値をもつということです; オブジェクト間で比較を 行う際には、オブジェクトの各要素に対するハッシュ値を (排他的論理和をとるなどして) 何らかの方法で混合するよう勧めます。 クラスが __cmp__() メソッドを定義していない場合、 __hash__() メソッドも定義してはなりません; クラスが __cmp__() または __eq__() を定義しているが、 __hash__() を定義していない場合、インスタンスを 辞書のキーとして使うことはできません。 クラスが変更可能なオブジェクトを定義しており、__cmp__() または __eq__() メソッドを実装している場合、__hash__() を定義してはなりません。これは、辞書の実装においてハッシュ値が変更不能 であることが要求されているからです (オブジェクトのハッシュ値が変化 すると、キーが誤ったハッシュバケツ: hash bucket に入っていることに なってしまいます)。

__nonzero__( self)
真値テストや組み込み演算 bool() を実現するために呼び出され ます; False または True か、等価な整数値 0 または 1 を返さなければなりません。 このメソッドが定義されていない場合、__len__() (下記参照) が定義されていれば呼び出されます。__len__() と __nonzero__() のどちらもクラスで定義されていない場合、 そのクラスのインスタンスはすべて真の値を持つものとみなされます。

__unicode__( self)
組み込み関数 unicode() を実現 するために呼び出されます。Unicode オブジェクトを返さなければ なりません。このメソッドが定義されていなければ、文字列への 変換が試みられ、その結果がデフォルトの文字エンコードを用いて Unicode に変換されます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3.3 特殊メソッド名 Up: 3.3 特殊メソッド名 Next: 3.3.2 属性値アクセスをカスタマイズする


3.3.2 属性値アクセスをカスタマイズする

以下のメソッドを定義して、クラスインスタンスへの属性値アクセス ( 属性値の使用、属性値への代入、x.name の削除) の意味を カスタマイズすることができます。

__getattr__( self, name)
属性値の検索を行った結果、通常の場所に属性値が見つからなかった 場合 (すなわち、self のインスタンス属性でなく、かつクラスツリー にも見つからなかった場合) に呼び出されます。 このメソッドは (計算された) 属性値を返すか、AttributeError 例外を送出しなければなりません。

通常のメカニズムを介して属性値が見つかった場合、__getattr__() は呼び出されないので注意してください。(__getattr__() と __setattr__() の間は意図的に非対称性にされています。 これは__getattr__() および __setattr__() 双方に とっての効率性という理由と、こうしなければ __setattr__() がインスタンスの他の属性値にアクセスする方法がなくなるためです。 少なくともインスタンス変数に対しては、値をインスタンスの属性値 辞書に挿入しないようにして (代わりに他のオブジェクトに挿入することで) 属性値が完全に制御されているように見せかけられることに注意してください。 新形式のクラスで実際に完全な制御を行う方法は、以下の __getattribute__() メソッドを参照してください。

__setattr__( self, name, value)
属性値への代入が試みられた際に呼び出されます。このメソッドは 通常の代入メカニズム (すなわち、インスタンス辞書への値の代入) の代わりに呼び出されます。 name は属性名で、value はその属性に代入する値です。

__setattr__() の中でインスタンス属性値への代入が必要 な場合、単に "self.name = value" としてはなりません -- このようにすると、自分自身に対する再帰呼び出しがおきてしまいます。 その代わりに、インスタンス属性の辞書に値を挿入してください。 例えば、"self.__dict__[name] = value" とします。 新しい形式のクラスでは、インスタンス辞書にアクセスするのではなく、 基底クラスのメソッドを同じ属性名で呼び出します。例えば、 "object.__setattr__(self, name, value)" とします。

__delattr__( self, name)
__setattr__() に似ていますが、代入ではなく値の削除を 行います。このメソッドを実装するのは、オブジェクトにとって "del obj.name" が意味がある場合だけにしなければなりません。

  • 3.3.2.1 新しい形式のクラスのための別の属性アクセス
  • 3.3.2.2 デスクリプタ (descriptor) の実装
  • 3.3.2.3 デスクリプタを呼び出す
  • 3.3.2.4 __slots__
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3.3.1 基本的なカスタマイズ Up: 3.3 特殊メソッド名 Next: 3.3.2.1 新しい形式のクラスのための別の属性アクセス


3.3.3 クラス生成をカスタマイズする

デフォルトでは、新形式クラスは type() を使って構築 されます。クラス定義が別の名前空間に読み込まれ、 クラス名は type(name, bases, dict) の結果に結合されます。

クラス定義が読み込まれる際、__metaclass__ が定義されていれば、 type() の代わりに __metaclass__ が指している 呼び出し可能オブジェクトが呼び出されます。 これによって、

  • クラスが生成される前にクラス辞書を変更する
  • 他のクラスのインスタンスを返す - 本質的にはファクトリ関数の役割を 果たす

といった、クラス生成のプロセスを監視したり置き換えたりする クラスや関数を書くことができます。

__metaclass__
この変数は name、bases、および dict を引数として 取るような任意の呼び出し可能オブジェクトにできます。 クラス生成の際、組み込みの type() の代わりに、指定された 呼び出しオブジェクトが呼び出されます。 バージョン2.2 以降で新規追加された 仕様です。

以下に優先順で並んだ規則によって、適切なメタクラスが決定されます:

  • dict['__metaclass__'] があればそれを使います。

  • それ以外の場合で、最低でも一つ基底クラスを持っているなら、 基底クラスのメタクラス (__class__ 属性を探し、なければ 基底クラスの型) を使います。

  • それ以外の場合で、__metaclass__ という名前のグローバル変数 があれば、それをつかいます。

  • それ以外の場合には、旧形式のメタクラス (types.ClassType) を使います。

メタクラスは限りない潜在的利用価値を持っています。これまで試されて きたアイデアには、ログ記録、インタフェースのチェック、 自動デリゲーション、自動プロパティ生成、プロキシ、フレームワーク、 そして自動リソースロック／同期といったものがあります。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3.3.2.4 __slots__ Up: 3.3 特殊メソッド名 Next: 3.3.4 呼び出し可能オブジェクトをエミュレートする


3.3.4 呼び出し可能オブジェクトをエミュレートする

__call__( self[, args...])
インスタンスが関数として ``呼ばれた'' 際に呼び出されます;
このメソッドが定義されている場合、x(arg1, arg2, ...)
は x.__call__(arg1, arg2, ...) を短く書いたものに
なります。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3.3.3 クラス生成をカスタマイズする Up: 3.3 特殊メソッド名 Next: 3.3.5 コンテナをエミュレートする


3.3.5 コンテナをエミュレートする

以下のメソッドを定義して、コンテナオブジェクトを実装することができます。 コンテナは通常、(リストやタプルのような) 配列や、(辞書のような) マップ型を指しますが、他のコンテナも同じように表現することができます。 最初の一連のメソッドは、配列をエミュレートしたり、マップ型を エミュレートするために使われます; その違いとして、配列の場合には、 キーとして許されているのが、配列の長さが N であるときの 0 <= k < N なる整数 k か、あるいは 要素の範囲を表すスライスオブジェクトでなければならないということです。 (後方互換性のため、__getslice__() (以下参照) を 定義して、拡張されていない単純なスライスを扱うようにもできます。) 変更可能な配列では、Python の標準リストオブジェクトのように、 メソッド append()、 count()、 index()、extend()、insert()、 pop()、 remove()、reverse()、およびsort() を 提供しなければなりません。 マップ型でも、Python の標準辞書オブジェクトのように、 keys()、 values()、 items()、 has_key()、 get()、 clear()、 setdefault()、iterkeys()、 itervalues()、 iteritems()、 pop()、 popitem()、 copy()、 および update() といったメソッドをマップ型 で提供するよう推奨しています。UserDict モジュールでは、 これらのメソッドを__getitem__()、 __setitem__()、 __delitem__()、および keys() といった基本セットから 作成する上で役に立つ DictMixin クラスを提供しています。 最後に、配列型では以下に述べるメソッド群 __add__()、 __radd__()、 __iadd__()、__mul__()、 __rmul__()、および __imul__() を定義して、 (配列間の結合を意味する) 加算操作と (要素の繰り返しを 意味する) 乗算操作を実装しなければなりません; __coerce__() や、その他の数値演算子を定義してはなりません。 マップでも配列でも、in 演算子が有効利用できるように __contains__() メソッドの定義を推奨します; マップ型では、 in はhas_key() と等価でなければなりません; 配列では、 配列内の値にわたって検索を行わなければなりません。さらに、 マップでも配列でも、コンテナ内にわたる反復操作ができるようにするため、 __iter__() を実装するよう勧めます; マップ型の場合、 __iter__() は iterkeys() と等価でなければなりません; 配列の場合、配列内の値にわたって反復操作を行わなければなりません。

__len__( self)
組み込み関数 len() を実現するために 呼び出されます。オブジェクトの長さを >= 0 である整数で 返さなければなりません。また、オブジェクトが __nonzero__() メソッドを定義しておらず、__len__() メソッドがゼロを 返す場合には、ブール演算コンテキストでは偽であるとみなされます。

__getitem__( self, key)
self[key] の値評価 (evaluation) を実現するために 呼び出されます。 配列の場合、キーとして整数とスライスオブジェクトを受理できなければ なりません。 (配列型をエミュレートする場合) 負のインデクスの解釈は __getitem__() メソッド次第と なります。key が不適切な型であった場合、TypeError を送出してもかまいません; (負のインデクス値に対して何らかの解釈 を行った上で) key が配列のインデクス集合外の値である場合、 IndexError を送出しなければなりません。 注意: for ループでは、配列の終端を正しく検出できるように するために、不正なインデクスに対して IndexError が送出されるものと期待しています。

__setitem__( self, key, value)
self[key] に対する代入を実現するために呼び出されます。 __getitem__() と同じ注意事項があてはまります。 このメソッドを実装できるのは、あるキーに対する値の変更をサポートしているか、 新たなキーを追加できるようなマップの場合と、ある要素を置き換えることができる 配列の場合だけです。不正な key に対しては、__getitem__() メソッドと同様の例外の送出を行わなければなりません。

__delitem__( self, key)
self[key] の削除を実現するために呼び出されます。 __getitem__() と同じ注意事項があてはまります。 このメソッドを実装できるのは、キーの削除をサポートしているマップの場合と、 要素を削除できる配列の場合だけです。 不正な key に対しては、__getitem__() メソッドと同様の例外の送出を行わなければなりません。

__iter__( self)
このメソッドは、コンテナに対してイテレータが要求された際に呼び出されます。 このメソッドは、コンテナ内の全てのオブジェクトにわたる反復処理ができる ような、新たなイテレータオブジェクトを返さなければなりません。 マップの場合、コンテナ内のキーに渡る反復処理でなければならず、 かつiterkeys() によって利用できなければなりません。

イテレータオブジェクトでもこのメソッドを実装する必要があります; イテレータの場合、自分自身を返さなければなりません。イテレータオブジェクト に関するより詳細な情報は、 Python ライブラリリファレンス の ``イテレータ型'' を参照してください。

メンバシップテスト演算子 (in および not in) は通常、 配列に渡る反復処理を使って実装されます。しかし、コンテナオブジェクト で以下の特殊メソッドを定義して、より効率的な実装を行ったり、オブジェクト が配列でなくてもよいようにできます。

__contains__( self, item)
メンバシップテスト演算を実現するために呼び出されます。 item が self 内に存在する場合には真を、そうでない場合には 偽を返さなければなりません。マップオブジェクトの場合、値やキーと値の 組ではなく、キーに対するメンバシップテストを考えなければなりません。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3.3.4 呼び出し可能オブジェクトをエミュレートする Up: 3.3 特殊メソッド名 Next: 3.3.6 配列型エミュレーションで使われるその他のメソッド


3.3.6 配列型エミュレーションで使われるその他のメソッド

以下のオプションとなるメソッドを定義して、配列オブジェクトをより高度に エミュレーションできます。変更不能な配列のメソッドでは、 __getslice__() が定義できるだけです; 変更可能な配列では 三つのメソッド全てを定義できます。

__getslice__( self, i, j)
リリース 2.0 以降で撤廃された仕様です。 スライスオブジェクトは __getitem__() メソッドの パラメタとしてサポートするようになりました。
self[i:j] の値評価を実現するために呼び出され ます。返されるオブジェクトは self と同じ型でなければなりません。 スライス表記で i や j がない場合には、それぞれゼロや sys.maxint に置き換えられるので注意してください。 スライスに負のインデクスが用いられた場合、配列の長さがインデクス値に 加算されます。インスタンスが __len__() メソッドを実装して いない場合には、AttributeError が送出されます。 この計算の結果、インデクス値が負でなくなるという保証はありません。 配列の長さよりも大きなインデクス値は修正されません。 __getslice__() が定義されていない場合、代わりに スライスオブジェクトが生成されて __getitem__() に渡されます。

__setslice__( self, i, j, sequence)
self[i:j] への代入を実現するために呼び出され ます。i および j に関しては、__getslice__() と同じ注釈があてはまります。

このメソッドは撤廃されています。 __setslice__() がないか、 self[i:j:k] 形式の拡張スライス の場合には、__setslice__() が呼ばれる代わりにスライス オブジェクトが生成され、__setitem__() に渡されます。

__delslice__( self, i, j)
self[i:j] の削除を実現するために 呼び出されます。i および j に関しては、__getslice__() と同じ注釈があてはまります。

このメソッドは撤廃されています。 __delslice__() がないか、 self[i:j:k] 形式の拡張スライス の場合には、__delslice__() が呼ばれる代わりにスライス オブジェクトが生成され、__delitem__() に渡されます。

これらのメソッドは、単一のコロンを使った単一のスライスで、かつ スライスメソッドが利用できるときにだけ呼び出されることに注意 してください。拡張スライス表記を含んでいるスライス表記や、 スライスメソッドがない場合、__getitem__()、 __setitem__() 、あるいは __delitem__() が スライスオブジェクトを引数として呼び出されます。

以下の例は、プログラムやモジュールを以前のバージョンの Python に対して互換性を持たせる方法を示したものです (__getitem__()、 __setitem__() 、および __delitem__() は引数としてスライスオブジェクトを サポートするものと仮定します):

class MyClass:
    ...
    def __getitem__(self, index):
        ...
    def __setitem__(self, index, value):
        ...
    def __delitem__(self, index):
        ...

    if sys.version_info < (2, 0):
        # They won't be defined if version is at least 2.0 final

        def __getslice__(self, i, j):
            return self[max(0, i):max(0, j):]
        def __setslice__(self, i, j, seq):
            self[max(0, i):max(0, j):] = seq
        def __delslice__(self, i, j):
            del self[max(0, i):max(0, j):]
    ...

max() を呼び出していることに注意してください; この呼び出し __*slice__() メソッド呼び出される前に、負のインデクス値を処理 しておくために必要です。 負のインデクス値が使われた場合、 __*item__() メソッドは与えら れた値をそのまま使いますが、__*slice__() メソッドは ``調理済みの (cooked)'' 形式になったインデクス値を受け取ります。 負のインデクス値が使われると、メソッドを呼び出す前に、常に配列の長さを インデクス値に加算します (加算してもまだ負の値となっていてもかまいませ ん); これは、組み込み配列型における慣習的な負のインデクス処理方法で、 __*item__() メソッドでも同様の処理を行うよう期待しています。 しかし、ここではすでに負のインデクス値の処理を行っているので、負のイン デクスを渡すべきではありません; インデクス値は、__*item__() メソッドに渡される前に、配列のインデクス集合の境界に制限されていなけれ ばなりません。max(0, i) を呼び出せば、適切な値を返すので便利です。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3.3.5 コンテナをエミュレートする Up: 3.3 特殊メソッド名 Next: 3.3.7 数値型をエミュレーションする


3.3.7 数値型をエミュレーションする

以下のメソッドを定義して、数値型オブジェクトをエミュレートすることがで きます。特定の種類の数値型ではサポートされていないような演算に対応する メソッド (非整数の数値に対するビット単位演算など) は、未定義のままにし ておかなければなりません。

__add__( self, other)
__sub__( self, other)
__mul__( self, other)
__floordiv__( self, other)
__mod__( self, other)
__divmod__( self, other)
__pow__( self, other[, modulo])
__lshift__( self, other)
__rshift__( self, other)
__and__( self, other)
__xor__( self, other)
__or__( self, other)
これらのメソッドは、二項算術演算 (
-, *, //, %,
divmod(),
pow(), **, <<,
>>, &, ^, |)
を実現するために呼び出されます。例えば、式 x+y
の場合、x が __add__() メソッドをもつクラスのインスタン
スであれば、x.__add__(y) が呼び出されます。
__divmod__() メソッドは、__floordiv__() と
__mod__() を使った場合と等価にならなければなりません;
__truediv__() (下記参照) と関連づける必要はありません。
組み込みの三項演算子バージョンの関数
pow() をサポートする場合には、
__pow__() は、オプションとなる第三の引数を受け取れなくては
なりません。

__div__( self, other)
__truediv__( self, other)
除算演算 (/) は、これらのメソッドで実現されています。 __truediv__() は、 __future__.division が有効であると きに使われます。それ以外の場合には __div__() が使われますs。 二つのメソッドのうち一方しか定義されていなければ、オブジェクトは 他方の演算コンテキストをサポートしなくなります; このとき、 TypeError が送出されます。

__radd__( self, other)
__rsub__( self, other)
__rmul__( self, other)
__rdiv__( self, other)
__rtruediv__( self, other)
__rfloordiv__( self, other)
__rmod__( self, other)
__rdivmod__( self, other)
__rpow__( self, other)
__rlshift__( self, other)
__rrshift__( self, other)
__rand__( self, other)
__rxor__( self, other)
__ror__( self, other)
これらのメソッドは二項算術演算 (+, -, *, /, %, divmod(), pow(), **, <<, >>, &, ^, |) を実現しますが、メソッド呼び出しが行われ る被演算子が逆転して (reflected, swapped: 入れ替えられて) います。 これらの関数は、左側の被演算子が対応する演算をサポートしていない場合に のみ呼び出されます。例えば、x-y において、 y が __rsub__() メソッドを持つクラスのインスタンスであ る場合、y.__rsub__(x) が呼び出されます。三項演算子 pow() が __rpow__() を呼ぶことは ないので注意してください (型強制の規則が非常に難解になるからです)。

__iadd__( self, other)
__isub__( self, other)
__imul__( self, other)
__idiv__( self, other)
__itruediv__( self, other)
__ifloordiv__( self, other)
__imod__( self, other)
__ipow__( self, other[, modulo])
__ilshift__( self, other)
__irshift__( self, other)
__iand__( self, other)
__ixor__( self, other)
__ior__( self, other)
これらのメソッドは、累算算術演算 (augmented arithmetic operations, +=, -=, *=, /=, %=, **=, <<=, >>=, &=, ^=, |=) を実現するために呼び出されます。 これらのメソッドでは、(self の値を変更することで) 演算を インプレースで行うよう試み、その結果 (インプレースで演算を行えない場合や、行ってはならない場合には self 自体) を返さなければなりません。 特定のメソッドが定義されていない場合、その累算算術演算は通常のメソッド で代用されます。例えば、x+=y を評価する際、 x が __iadd__() メソッドを持つクラスのインスタンスで あれば、x.__iadd__(y) が呼び出されます。反対に、 x が __iadd() メソッドを持たないクラスのインスタンスで あれば、x+y に基づいて x.__add__(y) および y.__radd__(x) を考慮します。

__neg__( self)
__pos__( self)
__abs__( self)
__invert__( self)
単項算術演算 (-, +, abs() および ~) を実現するために呼び出されます。

__complex__( self)
__int__( self)
__long__( self)
__float__( self)
組み込み関数
complex(),
int(), long(),
および float() を実現するために呼び出さ
れます。適切な型の値を返さなければなりません。

__oct__( self)
__hex__( self)
組み込み関数 oct() および hex()を実現するために呼び出されます。文字列型を返さなければなりません。

__coerce__( self, other)
``型混合モード (mixed-mode)'' での数値間の算術演算を実現するために 呼び出されます。 self と other を共通の数値型に変換して、 2 要素のタプルにして返すか、不可能な場合には None を返さなけれ ばなりません。共通の型が other の型になる場合、 None を 返すだけで十分です。この場合、インタプリタはもう一方のオブジェクトを調 べて型強制を行おうとするからです (とはいえ、もう一方の値の型が実装上変 更できない場合には、ここで self を other の型に変換してお いた方が便利です)。戻り値に NotImplemented を使うのは、 None を返すのと同じです。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3.3.6 配列型エミュレーションで使われるその他のメソッド Up: 3.3 特殊メソッド名 Next: 3.3.8 型強制規則 (coercion rule)


3.3.8 型強制規則 (coercion rule)

本節では、型強制 (coercion) に関する規則について記述します。 プログラム言語が進化するにつれ、型強制規則について正確に 記述するのは難しくなってゆきます; 従って、あるバージョンのある 実装について記述するのは望ましくありません。その代わりに、 型強制に関する非公式的なガイドラインを示しておきます。 Python 3.0 からは、型強制がサポートされなくなる予定です。

  • % 演算子の左被演算子が文字列か Unicode オブジェクトの場合、 型強制は起きず、文字列としての書式化操作が呼び出されます。

  • 型強制演算の定義はもはや推奨されていません。 型強制を定義していない混合型 (mixed-mode) 演算は、 もとの引数をそのまま演算操作に渡すようになっています。

  • 新しい形式のクラス (object から導出されたもの) が、
二項演算子に対して __coerce__() メソッドを呼び出すことは
ありません。; __coerce__() が呼び出されるのは、組み込み
関数 coerce() が呼び出されたときだけです。

  • 事実上、 NotImplemented を返す演算子は、全く実装されていないも のとして扱われます。

  • 以下の説明では、__op__() および __rop__() は、演算子 に相当する一般的なメソッド名を表すために使われます; __iop__ はインプレース演算子を表します。例えば、演算子 `+' の場合、 __add__() および __radd__() がそれぞれ左右の被演算子 用の二項演算子として使われ、__iadd__ がインプレース演算用の演 算子として使われる、といった具合です。

  • オブジェクト x および y に対して、 まず x.__op__(y) が試されます。この演算が実装されて いないか、NotImplemented を返す場合、次に y.__rop__(x) が試されます。この演算も実装されていな いか、NotImplemented を返すなら、 TypeError 例外が送出されます。ただし、以下の例外があるので参照してください:

  • 前項に対する例外: 左被演算子が組み込み型や新形式クラスのインスタンスで あり、かつ右被演算子が左被演算子と同じクラスか適切なサブクラスのインス タンスである場合、左被演算子の __op__() メソッドを試す 前に 右被演算子の __rop__() が試されます。 これは、サブクラス側で二項演算子を完全にオーバライドできるようにするた めです。そうしなければ、常に左被演算子の __op__ メソッドが右被演算子を 受理してしまいます: あるクラスのインスタンスが被演算子になるとされてい る場合、そのサブクラスのインスタンスもまた受理可能だからです。

  • 双方の被演算子が型強制を定義している場合、型強制は被演算子の型の __op__() や __rop__() メソッドが呼び出される前に呼 び出され、それより早くなることはありません。型強制の結果、型強制を行う ことになったいずれの被演算子とも異なる型が返された場合、返されたオブジェ クトの新たな型を使って、この過程が部分的に再度行われます。

  • (`+=' のような) インプレース型の演算子を用いる際、左被演算子が
__iop__() を実装していれば、__iop__() が呼び出され、
方強制は一切行われません。演算が __op__() かつ/または
__rop__() に帰着した場合、通常の型強制規則が適用されます。

  • x+y において、 x が結合 (concatenation) 演算 を実装している配列であれば、配列の結合が実行されます。

  • x*y において、一方の演算子が繰り返し (repeat) 演算 を実装している配列であり、かつ他方が整数 (int または long) である場合、配列の繰り返しが実行されます。

  • (__eq__() などのメソッドで実装されている) 拡張比較は、決して 型強制を行いません。(__cmp__() で実装されている) 三値比較 (three-way comparison) は、他の二項演算子で行われているのと同じ条件で 型強制を受けます。

  • 現在の実装では、組み込み数値型 int, long および float は型強制を行いません; 一方、complex は型強制 を使います。こうした違いは、これらの型をサブクラス化する際に顕在化して きます。そのうち、 complex 型についても型強制を避けるよう修正 されるかもしれません。これらの型は全て、関数 coerce() から 利用するための __coerce__() メソッドを実装しています。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3.3.7 数値型をエミュレーションする Up: 3.3 特殊メソッド名 Next: 4. 実行モデル


4. 実行モデル

  • 4.1 名前づけと束縛 (naming and binding)
    • 4.1.1 動的な機能とのやりとり
  • 4.2 例外
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3.3.8 型強制規則 (coercion rule) Up: Python リファレンスマニュアル Next: 4.1 名前づけと束縛 (naming and


4.1 名前づけと束縛 (naming and binding)

名前 (name)とは、オブジェクトを参照する ものを指します。名前への束縛 (name binding) 操作を行うと、 名前を導入できます。プログラムテキスト中に名前が出現するたびに、 その名前が使われている最も内側の関数ブロック中で作成された 束縛 (binding) を使って名前の 参照が行われます。

ブロック (block)は、Python のプログラムテキスト からなる断片で、一つの実行単位となるものです。 モジュール、関数本体、そしてクラス定義はブロックです。 また、対話的に入力された個々のコマンドもブロックです。 スクリプトファイル (インタプリタに標準入力として与えたり、 コマンドラインの第一引数として指定したファイル) は、コードブロック です。スクリプトコマンド (インタプリタのコマンドライン上で `-c' オプションを使って指定したコマンド) もコードブロック です。組み込み関数 eval() や exec 文に 渡した文字列もコードブロックになります。 組み込み関数 input() から読み取られ、評価される 式もまた、コードブロックです。

コードブロックは、実行フレーム (execution frame) 上で実行されます。実行フレームには、 (デバッグに使われる) 管理情報が収められています。また、 現在のコードブロックの実行が完了した際に、どのようにプログラムの 実行を継続するかを決定しています。

スコープ (scope)は、ある名前があるブロック内で 参照できるかどうかを決めます。ローカル変数があるブロック内で定義されて いる場合、変数のスコープはそのブロックを含みます。関数ブロック内で 名前の定義を行った場合、その名前に対して別の束縛を行っている ブロックを除いた、関数内の全てのブロックを含むようにスコープが 拡張されます。 クラス内で定義された名前のスコープは、クラスのブロック内に制限 されます; スコープがメソッドのコードブロックを含むよう拡張される ことはありません。

ある名前がコードブロック内で使われると、その名前を最も近傍から囲う ようなスコープ (最内スコープ: nearest enclosing scope) を使って束縛の 解決を行います。こうしたスコープからなる、あるコードブロック内で 参照できるスコープ全ての集合は、ブロックの 環境 (environment)と呼ばれます。

ある名前がブロック内で束縛されている場合、名前はそのブロックに おけるローカル変数 (local variable) です。 ある名前がモジュールレベルで束縛されている場合、名前は グローバル変数 (global variable) です。 (モジュールコードブロックの変数は、ローカル変数でもあるし、 グローバル変数でもあります。) ある変数がコードブロック内で使われているが、そのブロックでは定義 されていない場合、変数は 自由変数 (free variable)です。

ある名前の定義がどこにもない場合、 NameError例外が送出されます。名前がまだ束縛されていないローカルな変数を参照 した場合、UnboundLocalError 例外が送出されます。UnboundLocalError は、 NameError のサブクラスです。

名前への束縛は、以下の文構成 (construct): 関数の仮引数 (formal parameter) 指定、import 文、クラスや関数の定義 (定義を行ったブロック中 で、クラスや関数名の束縛が行われます)、代入時に、代入対象が識別子 である場合、for ループのヘッダ、または第二形式の except 文ヘッダ、で行われます。 ``"from...import *"'' 形式の import 文は、 import しようとするモジュール内で定義されている名前について、 アンダースコアから始まっている名前以外の全てを束縛します。 この形式は、モジュールレベルでしか使うことができません。

del 文で指定された対象は、(del の意味付けは、 実際は名前の解放 (unbind) ですが) 文の目的上、束縛済みのもの とみなされます。外側のスコープで参照されている名前の解放は、 不正な操作になります; コンパイラは SyntaxError を 報告するでしょう。

代入文や import 文はいずれも、クラスや関数定義、モジュールレベル (トップレベルのコードブロック) 内で起こります。

ある名前束縛操作がコードブロック内のどこかにある場合、ブロック 内でその名前を使うと、全て現在のブロックで束縛されている名前を 指すものとみなされます。このため、ある名前が束縛される前に ブロック内で使われるとエラーを引き起こす可能性があります。

この規則はやや微妙です。Python には宣言文がなく、コードブロックの どこで名前束縛操作を行ってもかまいません。 あるコードブロックにおけるローカル変数は、 ブロック全体から名前束縛操作が行われている部分を走査して決定 します。

global 文で指定された名前がブロック内にある場合、その名前は 常にトップレベルの名前空間で束縛された名前を参照します。 それらの名前はグローバル名前空間、すなわちコードブロックが収め られているモジュールの名前空間とモジュール名 __builtin__ で表される組み込み名前空間、を検索することによって、トップレベルの 名前空間で解決されます。グローバル名前空間は、常に最初に検索 されます。名前がグローバル名前空間中に見つからない場合、組み込み 名前空間が検索されます。global 文は、その名前が使われている全て の文に先立って記述されていなければなりません。

あるコードブロックの実行時に関連付けられる組み込み名前空間は、 実際にはコードブロックのグローバル名前空間内に入っている名前 __builtins__ を参照する形になっています; __builtins__ は辞書かモジュール (後者の場合にはモジュールの辞書が使われます) でなければなりません。通常、__builtins__ 名前空間は、 組み込みモジュール __builtin__ (注意: `s' なし) のモジュール辞書です。そうでない場合、制限実行 (restricted execution) モードが有効になっています。

あるモジュールの名前空間は、そのモジュールが最初に import された 時に自動的に作成されます。スクリプトの主モジュール (main module)は 常に __main__と呼ばれます。

グローバル文は、同じブロックの束縛操作と同じスコープを持ちます。 ある自由変数の最内スコープに global 文がある場合、その自由変数は グローバル変数とみなされます。

クラス定義は一つの実行文で、名前の使用や定義を行います。クラス定義 への参照は、通常の名前解決規則に従います。 クラス定義の名前空間は、そのクラスの属性辞書になります。 クラスのスコープで定義された名前は、メソッドからは見えません。

  • 4.1.1 動的な機能とのやりとり
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 4. 実行モデル Up: 4. 実行モデル Next: 4.1.1 動的な機能とのやりとり


4.1.1 動的な機能とのやりとり

自由変数の入った入れ子スコープ (nested scope) を併用すると、 Python の文が不正な文になる場合がいくつかあります。

ある変数がスコープの外側から参照された場合、その名前に対する 削除操作は不正になります。この場合、コンパイル時にエラーが 報告されることになります。

ワイルドカード形式の import 文 -- "import *" -- を関数内で使った場合や、関数が自由変数を含んでいたり、自由変数 を伴う入れ子ブロックである場合、コンパイラは SyntaxError を 送出します。

exec が関数内で使われており、関数が自由変数を含んでいたり、 自由変数を伴う入れ子ブロックである場合、exec に明示的に ローカル名前空間を指定しないかぎりコンパイラは SyntaxError を 送出します。 (別の言い方をすれば、"exec obj"は不正になることがあり、"exec obj in ns" はならない、という ことです。)

eval()、 execfile()、および input() 関数、そして exec 文は、名前の解決を行う際に、現在の環境 に対して完全にアクセスできるわけではありません。名前が呼び出し側の ローカル名前空間やグローバル名前空間から解決されることはあります。 自由変数は最内名前空間ではなく、グローバル名前空間から解決されます。 4.1

exec 文と、関数 eval() および execfile() にはオプションの引数があり、グローバルおよび ローカル名前空間をオーバライドできます。名前空間を一つしか指定 しなければ、両方の名前空間として使われます。

... 自由変数は最内名前空間ではなく、グローバル名前空間から解決されます。4.1
この制限は、上記の操作によって実行されるコードが、モジュールをコンパイルしたときには利用できないために起こります。
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 4.1 名前づけと束縛 (naming and Up: 4.1 名前づけと束縛 (naming and Next: 4.2 例外


4.2 例外

例外とは、コードブロックの通常の制御フローを中断して、 エラーやその他の例外的な状況を処理できるようにするための 手段です。 例外はエラーが検出された時点で 送出 (raise)されます; 例外は、エラーが発生部の周辺のコードブロックか、エラーが発生した コードブロック直接または間接的に呼び出しているコードブロック で 処理 (handle)することが できます。

Python インタプリタは、ランタイムエラー (ゼロによる除算など) が 検出されると例外を送出します。Python プログラムから、raise 文を使って明示的に例外を送出することもできます。 例外ハンドラ (exception handler) は、 try ... except 文で指定することができます。try ... finally 節を使うとクリーンアップコード (cleanup code) を指定できます。 このコードは例外は処理しませんが、先行するコードブロックで例外が 起きても起きなくても実行されます。

Python は、エラー処理に ``プログラムの終了 (termination)'' モデルを用いています: 例外ハンドラは、 プログラムに何が発生したかを把握することができ、ハンドラの外側の レベルに処理を継続することはできますが、(問題のあったコード部分を 最初から実行しなおすのでない限り) エラーの原因を修復したり、 実行に失敗した操作をやり直すことはできません。

例外が全く処理されない場合、インタプリタはプログラムの実行を終了させる か、対話メインループに処理を戻します。どちらの場合も、 例外が SystemExitでない限りバックトレース (backtrace) を出力します。

例外は、クラスインスタンスとして識別されます。 ある例外にどの except 節が一致するかの選択は、オブジェクトの アイデンティティに基づいて行われます。 except 節は、同じクラスの例外か、基底クラスの例外 しか参照しません。

例外が発行されると、オブジェクト (None になることもあります) が例外の 値 (value) として渡されます; このオブジェクトが 例外ハンドラの選択自体に影響することはありませんが、選択された例外 ハンドラに付帯情報として渡されます。 例外がクラスの場合、オブジェクトは送出された例外クラスのインスタンス でなければなりません。

警告: 例外に対するメッセージは、Python API 仕様には含まれていません。 メッセージの内容は、ある Python のバージョンから次のバージョンに なるときに、警告なしに変更される可能性があります。したがって、 複数バージョンのインタプリタで動作するようなコードにおいては、 例外メッセージの内容に依存した記述をすべきではありません。

try 文については、 7.4 節、 raise 文については 6.9 節も参照してください。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 4.1.1 動的な機能とのやりとり Up: 4. 実行モデル Next: 5. 式 (expression)


5. 式 (expression)

この章では、Python の式における個々の要素の意味について解説します。

表記法に関する注意: この章と以降の章での拡張BNF (extended BNF) 表記は、字句解析規則ではなく、構文規則を記述する ために用いられています。ある構文規則 (のある表現方法) が、以下の形式

name ::= othername

で記述されていて、この構文特有の意味付け (semantics) が記述されていない場合、 name の形式をとる構文の意味付けは、othername の意味付けと同じになります。

  • 5.1 算術変換 (arithmetic conversion)
  • 5.2 アトム、原子的要素 (atom)
    • 5.2.1 識別子 (identifier、または名前 (name))
    • 5.2.2 リテラル
    • 5.2.3 丸括弧形式 (parenthesized form)
    • 5.2.4 リスト表現
    • 5.2.5 辞書表現
    • 5.2.6 文字列変換
  • 5.3 一次語 (primary)
    • 5.3.1 属性参照
    • 5.3.2 添字表記 (subscription)
    • 5.3.3 スライス表記 (slicing)
    • 5.3.4 呼び出し (call)
  • 5.4 べき乗演算 (power operator)
  • 5.5 単項算術演算 (unary arithmetic operation)
  • 5.6 二項算術演算 (binary arithmetic operation)
  • 5.7 シフト演算 (shifting operation)
  • 5.8 ビット単位演算の二項演算 (binary bit-wise operation)
  • 5.9 比較 (comparison)
  • 5.10 ブール演算 (boolean operation)
  • 5.11 ラムダ (lambda)
  • 5.12 式のリスト
  • 5.13 評価順序
  • 5.14 まとめ
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 4.2 例外 Up: Python リファレンスマニュアル Next: 5.1 算術変換 (arithmetic conversion)


5.1 算術変換 (arithmetic conversion)

以下の算術演算子の記述で、「数値引数は共通の型に変換されます」と 書かれている場合、引数は 3 章の末尾に記載されている 型強制規則に基づいて型強制されます。引数がいずれも標準の数値型 である場合、以下の型強制が適用されます:

  • 片方の引数が複素数型であれば、他方は複素数型に変換されます;
  • それ以外の場合で、片方の引数が浮動小数点数であれば、他方は 浮動小数点型に変換されます;
  • それ以外の場合で、片方の引数が長整数型であれば、他方は 長整数型に変換されます;
  • それ以外の場合で、両方の引数が通常の整数型であれば、変換の 必要はありません。

特定の演算子 (文字列を左引数とする `%' 演算子など) では、さらに 別の規則が適用されます。拡張をおこなうことで、個々の演算子に対する 型強制を定義できます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5. 式 (expression) Up: 5. 式 (expression) Next: 5.2 アトム、原子的要素 (atom)


5.2 アトム、原子的要素 (atom)

アトム (原子的要素: atom) は、式を構成する基本単位です。もっとも単純な アトムは、識別子またはリテラルになります。逆クオートや丸括弧、波括弧、 または角括弧で囲われた形式 (form) もまた、文法的にはアトムに分類 されます。アトムの構文定義は以下のようになります:

atom ::= identifier | literal | enclosure
enclosure ::= parenth_form | list_display
| dict_display | string_conversion
Download entire grammar as text.

  • 5.2.1 識別子 (identifier、または名前 (name))
  • 5.2.2 リテラル
  • 5.2.3 丸括弧形式 (parenthesized form)
  • 5.2.4 リスト表現
  • 5.2.5 辞書表現
  • 5.2.6 文字列変換
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.1 算術変換 (arithmetic conversion) Up: 5. 式 (expression) Next: 5.2.1 識別子 (identifier、または名前 (name))


5.2.1 識別子 (identifier、または名前 (name))

アトムの形になっている識別子 (identifier) は名前 (name) です。 名前づけや束縛については、4.1 節を参照してください。

名前があるオブジェクトに束縛されている場合、名前アトムを評価すると そのオブジェクトになります。名前が束縛されていない場合、アトムを 評価しようとするとNameError 例外を送出します。

プライベートな名前の難号化 (mangling):クラス定義内にテキストの形で書かれた識別子で、二つ以上のアンダースコア から始まり、末尾が二つ以上のアンダースコアになっていないものは、 そのクラスの プライベートな名前 (private name) とみなされます。 プライベートな名前は、コードが生成される前に、より長い形式の名前に 変換されます。この変換では、クラス名の先頭にあるアンダースコアを全て はぎとり、先頭にアンダースコアを一つ挿入して、名前の前に付加します。 例えば、クラス Ham 内の識別子 __spam は、 _Ham__spam に変換されます。変換は識別子が使われている構文的 コンテキストとは独立しています。変換された名前が非常に長い (255 文字以上) の場合には、実装によっては名前の切り詰めが起きる かもしれません。クラス名がアンダースコアだけから成り立つ場合には、 変換は行われません。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.2 アトム、原子的要素 (atom) Up: 5.2 アトム、原子的要素 (atom) Next: 5.2.2 リテラル


5.2.2 リテラル

Python では、文字列リテラルと、様々な数値リテラルをサポートしています:

literal ::= stringliteral | integer | longinteger
| floatnumber | imagnumber
Download entire grammar as text.

リテラルを評価すると、指定した型 (文字列、整数、長整数、 浮動小数点数、複素数) の指定した値を持つオブジェクトになります。 浮動小数点や虚数 (複素数) リテラルの場合、値は近似値になる場合 があります。詳しくは 2.4 を参照してください。 リテラルは全て変更不能なデータ型に対応します。このため、オブジェクト のアイデンティティはオブジェクトの値ほど重要ではありません。 同じ値を持つ複数のリテラルを評価した場合、(それらのリテラルが プログラムの同じ場所由来のものであっても、そうでなくても) 同じオブジェクトを指しているか、まったく同じ値を持つ別の オブジェクトになります。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.2.1 識別子 (identifier、または名前 (name)) Up: 5.2 アトム、原子的要素 (atom) Next: 5.2.3 丸括弧形式 (parenthesized form)


5.2.3 丸括弧形式 (parenthesized form)

丸括弧形式とは、式リストの一形態で、丸括弧で囲ったものです:

parenth_form ::= "(" [expression_list] ")"
Download entire grammar as text.

丸括弧で囲われた式のリストは、個々の式が表現するものになります: リスト内に少なくとも一つのカンマが入っていた場合、タプルになります; そうでない場合、式のリストを構成している単一の式自体の値になります。

中身が空の丸括弧のペアは、空のタプルオブジェクトを表します。 タプルは変更不能なので、リテラルと同じ規則が適用されます (すなわち、 空のタプルが二箇所で使われると、それらは同じオブジェクトになることも あるし、ならないこともあります)。

タプルは丸括弧で作成されるのではなく、カンマによって作成される ことに注意してください。例外は空のタプルで、この場合には 丸括弧が必要です -- 丸括弧のつかない、 ``何も記述しない式 (nothing)'' を使えるようにしてしまうと、 文法があいまいなものになってしまい、よくあるタイプミスが検出されなく なってしまいます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.2.2 リテラル Up: 5.2 アトム、原子的要素 (atom) Next: 5.2.4 リスト表現


5.2.4 リスト表現

リスト表現は、角括弧で囲われた式の系列です。系列は空の系列であっても かまいません:

test ::= and_test ( "or" and_test )* | lambda_form
testlist ::= test ( "," test )* [ "," ]
list_display ::= "[" [listmaker] "]"
listmaker ::= expression ( list_for | ( "," expression )* [","] )
list_iter ::= list_for | list_if
list_for ::= "for" expression_list "in" testlist [list_iter]
list_if ::= "if" test [list_iter]
Download entire grammar as text.

リスト表現は、新に作成されたリストオブジェクトを表します。 新たなリストの内容は、式のリストを与えるか、リストの内包表記 (list comprehension) で指定します。 カンマで区切られた式のリストを与えた場合、リストの各要素は左から 右へと順に評価され、評価された順番にリスト内に配置されます。 リストの内包表記を与える場合、内包表記はまず単一の式、続いて 少なくとも一つの for 節、続いてゼロ個以上の for 節か、if 節になります。 この場合、新たに作成されるリストの各要素は、各々の for や if 節を左から右の順にネストしたブロックとみなして実行し、 ネストの最内ブロックに到達する度に式を評価した値となります。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.2.3 丸括弧形式 (parenthesized form) Up: 5.2 アトム、原子的要素 (atom) Next: 5.2.5 辞書表現


5.2.5 辞書表現

辞書表現は、波括弧で囲われた、キーと値のペアからなる系列です。 系列は空の系列であってもかまいません:

dict_display ::= "{" [key_datum_list] "}"
key_datum_list ::= key_datum ("," key_datum)* [","]
key_datum ::= expression ":" expression
Download entire grammar as text.

辞書表現は、新たな辞書オブジェクトを表します。

キー/データのペアは、左から右へと評価され、その結果が辞書の各 エントリを決定します: 各キーオブジェクトは、対応するデータを 辞書に記憶するためのキーとして用いられます。

キーの値として使える型に関する制限は、3.2 節ですでに 列挙しています。(一言でいうと、キーは変更可能なオブジェクトを 全て排除したハッシュ可能な型でなければなりません。) 重複するキー間で衝突が起きても、衝突が検出されることはありません; あるキーに対して、最後に渡されたデータ (プログラムテキスト上では、 辞書表記の最も右側値となるもの) が使われます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.2.4 リスト表現 Up: 5.2 アトム、原子的要素 (atom) Next: 5.2.6 文字列変換


5.2.6 文字列変換

文字列変換は、逆クオート (reverse quite, 別名バッククオート: backward quote) で囲われた式のリストです:

string_conversion ::= "`" expression_list "`"
Download entire grammar as text.

文字列変換は、逆クオート内の式リストを評価して、評価結果の オブジェクトを各オブジェクトの型特有の規則に従って文字列に 変換します。

オブジェクトが文字列、数値、None か、それらの型のオブジェクト のみを含むタプル、リストまたは辞書の場合、評価結果の文字列は 有効な Python 式となり、組み込み関数 eval() に渡した 場合に同じ値となります (浮動小数点が含まれている場合には近似値の 場合もあります)。

(特に、文字列を変換すると、値を安全に出力するために文字列の両側に クオートが付けられ、``変 (funny) な'' 文字はエスケープシーケンスに 変換されます。)

再帰的な構造をもつオブジェクト (例えば自分自身を直接または間接的に 含むリストや辞書) では、"..." を使って再帰的参照であることが 示され、オブジェクトの評価結果は eval() に渡しても 等価な値を得ることができません (SyntaxError が 送出されます)。

組み込み関数 repr() は、括弧内の引数に対して、 逆クオート表記で囲われた中身と全く同じ変換を実行します。 組み込み関数 str() は似たような動作をしますが、 もっとユーザフレンドリな変換になります。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.2.5 辞書表現 Up: 5.2 アトム、原子的要素 (atom) Next: 5.3 一次語 (primary)


5.3 一次語 (primary)

一次語は、言語において最も結合の強い操作を表します。 文法は以下のようになります:

primary ::= atom | attributeref | subscription | slicing | call
Download entire grammar as text.

  • 5.3.1 属性参照
  • 5.3.2 添字表記 (subscription)
  • 5.3.3 スライス表記 (slicing)
  • 5.3.4 呼び出し (call)
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.2.6 文字列変換 Up: 5. 式 (expression) Next: 5.3.1 属性参照


5.3.1 属性参照

属性参照は、一次語の後ろにピリオドと名前を連ねたものです:

attributeref ::= primary "." identifier
Download entire grammar as text.

一次語の値評価結果は、例えばモジュール、リスト、インスタンスと いった、属性参照をサポートする型でなければなりません。 オブジェクトは次に、指定した名前が識別子名と なっているような属性を生成するよう問い合わせされます。 問い合わせた属性が得られない場合、例外 AttributeError が送出 されます。それ以外の場合、オブジェクトは属性オブジェクトの型と 値を決定し、生成して返します。同じ属性参照を複数回評価したとき、 互いに異なる属性オブジェクトになることがあります。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.3 一次語 (primary) Up: 5.3 一次語 (primary) Next: 5.3.2 添字表記 (subscription)


5.3.2 添字表記 (subscription)

添字表記は、配列 (文字列、タプルまたはリスト) やマップ (辞書) オブジェクトから、要素を一つ選択します:

subscription ::= primary "[" expression_list "]"
Download entire grammar as text.

一次語の値評価結果は、配列型かマップ型のオブジェクトでなければなりません。

一次語がマップであれば、式リストの値評価結果はマップ内のいずれかの キー値に相当するオブジェクトにならなければなりません。添字表記は、 そのキーに対応するマップ内の値 (value) を選択します。 (式リストの要素が単独である場合を除き、式リストはタプルでなければ なりません。)

一次語が配列の場合、式 (リスト) の値評価結果は (通常の) 整数でなければ なりません。値が負の場合、配列の長さが加算されます (x[-1] がx の最後の要素を指すことになります)。 加算結果は配列内の要素数よりも小さな非負の整数とならなければなりません。 添字表記は、添字と同じ配列中の (ゼロから数えた) インデクスを持つ要素を 選択します。

文字列型の要素は文字 (character) です。文字は個別の型ではなく、 1 文字だけからなる文字列です。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.3.1 属性参照 Up: 5.3 一次語 (primary) Next: 5.3.3 スライス表記 (slicing)


5.3.3 スライス表記 (slicing)

スライス表記は配列オブジェクト (文字列、タプルまたはリスト) におけるある 範囲の要素を選択します。スライス表記は式として用いたり、代入や del 文の 対象として用いたりできます。スライス表記の構文は以下のようになります:

slicing ::= simple_slicing | extended_slicing
simple_slicing ::= primary "[" short_slice "]"
extended_slicing ::= primary "[" slice_list "]"
slice_list ::= slice_item ("," slice_item)* [","]
slice_item ::= expression | proper_slice | ellipsis
proper_slice ::= short_slice | long_slice
short_slice ::= [lower_bound] ":" [upper_bound]
long_slice ::= short_slice ":" [stride]
lower_bound ::= expression
upper_bound ::= expression
stride ::= expression
ellipsis ::= "..."
Download entire grammar as text.

上記の形式的な構文法にはあいまいさがあります: 式リストに見えるものは、 スライスリストにも見えるため、添字表記はスライス表記としても解釈されうる ということです。 この場合には、(スライスリストの評価結果が、適切なスライスや省略表記 (ellipsis) にならない場合)、スライス表記としての解釈よりも添字表記 としての解釈の方が高い優先順位を持つように定義することで、構文法をより 難解にすることなくあいまいさを取り除いています。同様に、 スライスリストが厳密に一つだけの短いスライスで、末尾にカンマが 続いていない場合、拡張スライスとしての解釈より、単純なスライスとして の解釈が優先されます。

単純なスライスに対する意味付けは以下のようになります。 一次語の値評価結果は、配列型のオブジェクトでなければなりません。 下境界および上境界を表す式がある場合、それらの値評価結果は整数で なくてはなりません; デフォルトの値は、それぞれゼロと sys.maxint です。どちらかの境界値が負である場合、 配列の長さが加算されます。こうして、スライスは i および j をそれぞれ指定した下境界、上境界として、 インデクス k が i <= k < j となる全ての 要素を選択します。 選択の結果、空の配列になることもあります。i や j が 有効なインデクス範囲の外側にある場合でも、エラーにはなりません (範囲外の要素は存在しないので、選択されないだけです)。

拡張スライスに対する意味付けは、以下のようになります。 一次語の値評価結果は、辞書型のオブジェクトでなければなりません。 また、辞書は以下に述べるようにしてスライスリストから生成された キーによってインデクス指定できなければなりません。 スライスリストに少なくとも一つのカンマが含まれている場合、 キーは各スライス要素を値変換したものからなるタプルになります; それ以外の場合、単一のスライス要素自体を値変換したものがキーになります。 一個の式でできたスライス要素の変換は、その式になります。 省略表記スライス要素の変換は、組み込みの Ellipsis オブジェクト になります。適切なスライスの変換は、スライスオブジェクト (3.2 参照) で、start, stop および step 属性は、それぞれ指定した下境界、上境界、および とび幅 (stride) になります。式がない場合には、None に置き換え られます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.3.2 添字表記 (subscription) Up: 5.3 一次語 (primary) Next: 5.3.4 呼び出し (call)


5.3.4 呼び出し (call)

呼び出し (call) は、呼び出し可能オブジェクト (callable object, 例えば 関数など) を、引数列とともに呼び出します。引数列は空の配列でも かまいません:

call ::= primary "(" [argument_list [","]] ")"
argument_list ::= positional_arguments ["," keyword_arguments]
                     ["," "*" expression]
                     ["," "**" expression]
| keyword_arguments ["," "*" expression]
                    ["," "**" expression]
| "*" expression ["," "**" expression]
| "**" expression
positional_arguments ::= expression ("," expression)*
keyword_arguments ::= keyword_item ("," keyword_item)*
keyword_item ::= identifier "=" expression
Download entire grammar as text.

引数リストの末尾にカンマがあってもよく、構文の意味付けに影響を 及ぼすことはありません。

一次語の値評価結果は、呼び出し可能オブジェクトでなければなりません (ユーザ定義関数、組み込み関数、組み込みオブジェクトのメソッド、 クラスオブジェクト、クラスインスタンスのメソッド、そして特定の クラスインスタンス自体が呼び出し可能です; 拡張によって、 その他の呼び出し可能オブジェクト型を定義することができます)。 引数式は全て、呼び出しを試みる前に値評価されます。 仮引数 (formal parameter) リストの構文については、7.5 を参照してください。

キーワード引数が存在する場合、以下のようにして最初に固定引数 (positional argument) に変換されます。まず、値の入っていない スロットが仮引数に対して生成されます。N 個の固定引数が ある場合、固定引数は先頭の N スロットに配置されます。 次に、各キーワード引数について、識別子を使って対応するスロット を決定します (識別子が最初の仮引数パラメタ名と同じなら、最初の スロットを使う、といった具合です)。スロットがすでにすべて埋まって いたなら、TypeError 例外が送出されます。 それ以外の場合、引数値をスロットに埋めていきます。 (式が None であっても、その式でスロットを埋めます)。 全ての引数が処理されたら、まだ埋められていないスロットをそれぞれに 対応する関数定義時のデフォルト値で埋めます。(デフォルト値は、 関数が定義されたときに一度だけ計算されます; 従って、リストや 辞書のような変更可能なオブジェクトがデフォルト値として使われると、 対応するスロットに引数を指定しない限り、このオブジェクトが全ての 呼び出しから共有されます; このような状況は通常避けるべきです。) デフォルト値が指定されていない、値の埋められていないスロットが 残っている場合、TypeError 例外が送出されます。 そうでない場合、値の埋められたスロットからなるリストが呼び出しの 引数として使われます。

仮引数スロットの数よりも多くの固定引数がある場合、構文 "*identifier" を使って指定された仮引数がないかぎり、 TypeError 例外が送出されます; 仮引数 "*identifier" がある場合、 この仮引数は余分な固定引数が入ったタプル (もしくは、余分な 固定引数がない場合には空のタプル) を受け取ります。

キーワード引数のいずれかが仮引数名に対応しない場合、構文 "**identifier" を使って指定された仮引数がない限り、 TypeError 例外が送出されます; 仮引数 "**identifier" がある場合、 この仮引数は余分なキーワード引数が入った (キーワードをキーとし、 引数値をキーに対応する値とした) 辞書を受け取ります。 余分なキーワード引数がない場合には、空の (新たな) 辞書を 受け取ります。

関数呼び出しの際に "*expression" 構文が使われる場合、 "expression" の値評価結果は配列でなくてはなりません。 この配列の要素は、追加の固定引数のように扱われます; すなわち、固定引数 x1,...,xN と、 y1,...,yM になる配列 "expression" を使った 場合、M+N 個の固定引数 x1,...,xN,y1,...,yM を使った呼び出しと同じになります。

上記の仕様による結果として、"*expression" 構文は たとえキーワード引数 以降に あっても、キーワード引数 以前に ("**expression" 引数があればさらにその後に - 下記参照) 処理されます。従って:

>>> def f(a, b):
...  print a, b
...
>>> f(b=1, *(2,))
2 1
>>> f(a=1, *(2,))
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: f() got multiple values for keyword argument 'a'
>>> f(1, *(2,))
1 2

となります。

キーワード引数と "*expression" 構文を同じ呼び出しに使うことは あまりないので、実質的には上記のような混乱が生じることはありません。

関数呼び出しで "**expression" 構文が使われた場合、 "expression" の値評価結果は辞書 (またはそのサブクラス) で なければなりません。辞書の内容は追加のキーワード引数として扱われ ます。明示的なキーワード引数が "expression" 内のキーワード と重複した場合には、TypeError 例外が送出されます。

"*identifier" や "**identifier" 構文を使った仮引数は、 固定引数スロットやキーワード引数名にすることができません。 "(sublist)" 構文を使った仮引数は、キーワード引数名には 使えません; sublist は、リスト全体が一つの無名の引数スロット に対応しており、sublist 中の引数は、他の全てのパラメタに対する 処理が終わった後に、通常のタプル形式の代入規則を使ってスロットに 入れられます。

呼び出しを行うと、例外を送出しない限り、常に何らかの値を返します。 None を返す場合もあります。戻り値がどのように算出されるかは、 呼び出し可能オブジェクトの形態によって異なります。

呼び出し可能オブジェクトが。。。

ユーザ定義関数のとき:
関数のコードブロックに引数リストが 渡され、実行されます。コードブロックは、まず仮引数を実引数に 結合 (bind) します; この動作については 7.5 で記述しています。 コードブロックで return 文が実行される際に、関数呼び出しの 戻り値 (return value) が決定されます。

組み込み関数や組み込みメソッドのとき:
結果はインタプリタに 依存します; 組み込み関数や組み込みメソッドの詳細は、Python ライブラリリファレンス を参照してください。

クラスオブジェクトのとき:
そのクラスの新しいインスタンスが 返されます。

クラスインスタンスメソッドのとき:
対応するユーザ定義の関数 が呼び出されます。このとき、呼び出し時の引数リストより一つ長い 引数リストで呼び出されます: インスタンスが引数リストの先頭に追加 されます。

クラスインスタンスのとき:
クラスで __call__() メソッドが定義されていなければなりません; __call__() メソッドが呼び出された場合と同じ効果をもたらします。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.3.3 スライス表記 (slicing) Up: 5.3 一次語 (primary) Next: 5.4 べき乗演算 (power operator)


5.4 べき乗演算 (power operator)

べき乗演算は、左側にある単項演算子よりも強い結合優先順位 があります; 一方、右側にある単項演算子よりは低い結合優先順位に なっています。構文は以下のようになります:

power ::= primary ["**" u_expr]
Download entire grammar as text.

従って、べき乗演算子と単項演算子からなる演算列が丸括弧で囲われて いない場合、演算子は右から左へと評価されます (この演算規則は、 被演算子の評価順序を縛る規則ではありません)。

べき乗演算子は、二つの引数で呼び出される組み込み関数 pow() と同じ意味付けを持っています。引数はまず共通の型に変換されます。 結果の型は、型強制後の引数の型になります。

引数型を混合すると、二項算術演算における型強制規則が適用されます。 整数や長整数の被演算子の場合、第二引数が負でない限り、結果は (型強制後の) 被演算子と同じになります; 第二引数が負の場合、 全ての引数は浮動小数点型に変換され、浮動小数点型が返されます。 例えば、10**2 は 100 を返しますが、10**-2 は 0.01 を返します。 (上述の仕様のうち、最後のものは Python 2.2 で追加されました。 Python 2.1 以前では、双方の引数が 整数型で、第二引数が負の場合、例外が送出されていました。)

0.0 を負の数でべき乗すると、ZeroDivisionError を送出します。負の数を小数でべき乗すると ValueError になります。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.3.4 呼び出し (call) Up: 5. 式 (expression) Next: 5.5 単項算術演算 (unary arithmetic


5.5 単項算術演算 (unary arithmetic operation)

全ての単項算術演算 (およびビット単位演算子) は、同じ優先順位を 持っています:

u_expr ::= power | "-" u_expr | "+" u_expr | "~" u_expr
Download entire grammar as text.

単項演算子 - (マイナス) は、引数となる数値の符号を反転 (invert) します。

単項演算子 + (プラス) は、数値引数を変更しません。

単項演算子 ~ (逆転) は、整数または長整数の引数を ビット単位反転 (bit-wise invert) します。 x の ビット単位反転は、 -(x+1) として定義されています。 この演算子は整数にのみ適用されます。

上記の三つはいずれも、引数が正しい型でない場合には TypeError 例外が送出されます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.4 べき乗演算 (power operator) Up: 5. 式 (expression) Next: 5.6 二項算術演算 (binary arithmetic


5.6 二項算術演算 (binary arithmetic operation)

二項算術演算は、慣習的な優先順位を踏襲しています。 演算子のいずれかは、特定の非数値型にも適用されるので注意して ください。べき乗 (power) 演算子を除き、演算子には二つのレベル、 すなわち乗算的 (multiplicatie) 演算子と加算的 (additie) 演算子 しかありません:

m_expr ::= u_expr | m_expr "*" u_expr | m_expr "//" u_expr | m_expr "/" u_expr
| m_expr "%" u_expr
a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr
Download entire grammar as text.

* (乗算: multiplication) 演算は、引数間の積になります。 引数の組は、双方ともに数値型であるか、片方が整数 (通常の整数または 長整数) 型で他方が配列型かのどちらかでなければなりません。 前者の場合、数値は共通の型に変換された後乗算されます。 後者の場合、配列の繰り返し操作が行われます。繰り返し数を負に すると、空の配列になります。

/ (除算: division) および // (切り捨て除算: floor division) は、引数間の商になります。数値引数はまず共通の型に変換されます。 整数または長整数の除算結果は、同じ型の整数になります; この場合、 結果は数学的な除算に関数 `floor' を適用したものになります。 ゼロによる除算を行うと ZeroDivisionError 例外を送出 します。

% (モジュロ: modulo) 演算は、第一引数を第二引数で除算 したときの剰余になります。数値引数はまず共通の型に変換されます。 右引数値がゼロの場合には、ZeroDivisionError 例外が 送出されます。引数値は浮動小数点でもよく。例えば 3.14%0.7 は 0.34 になります (3.14 は 4*0.7 + 0.34 だからです)。モジュロ演算子は常に第二引数と同じ符号 (またはゼロ) の結果になります; モジュロ演算の結果の絶対値は、常に第二引数 の絶対値よりも小さくなります。5.1

整数による除算演算やモジュロ演算は、恒等式: x == (x/y)*y + (x%y) と関係しています。整数除算や モジュロはまた、組み込み関数 divmod(): divmod(x, y) == (x/y, x%y) と関係しています。 これらの恒等関係は浮動小数点の場合には維持されません; x/y が floor(x/y) や floor(x/y) - 1 に 置き換えられた場合、これらの恒等式は近似性を維持します。 5.2

リリース 2.3 以降で撤廃された仕様です。 切り捨て除算演算子、モジュロ演算子、および divmod() 関数は、複素数に対してはもはや定義されて いません。目的に合うならば、代わりに abs() を使って 浮動小数点に変換してください。

+ (加算) 演算は、引数を加算した値を返します。 引数は双方とも数値型か、双方とも同じ型の配列でなければなりません。 前者の場合、数値は共通の型に変換され、加算されます。 後者の場合、配列は結合 (concatenate) されます。

- (減算) 演算は、引数間で減算を行った値を返します。 数値引数はまず共通の型に変換されます。

... の絶対値よりも小さくなります。5.1
abs(x%y) < abs(y) は数学的には真となりますが、浮動小数点 に対する演算の場合には、値丸め (roundoff) のために数値計算的に 真にならない場合があります。例えば、Python の浮動小数点型が IEEE754 倍精度数型になっているプラットフォームを仮定すると、 -1e-100 % 1e100 は 1e100 と同じ符号になるはず なのに、計算結果は -1e-100 + 1e100 となります。これは 数値計算的には厳密に 1e100 と等価です。math モジュールの関数 fmod() は、最初の引数と符号が一致する ような値を返すので、上記の場合には -1e-100 を返します。 どちらのアプローチが適切かは、アプリケーションに依存します。
... 置き換えられた場合、これらの恒等式は近似性を維持します。5.2
x が y の整数倍に非常に近い場合、丸め誤差によって floor(x/y) は (x-x%y)/y よりも大きな値になる可能性があります。 そのような場合、 Python はdivmod(x,y)[0] * y + x % y が x に非常に近くなるという関係を保つために、後者の値を 返します。
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.5 単項算術演算 (unary arithmetic Up: 5. 式 (expression) Next: 5.7 シフト演算 (shifting operation)


5.7 シフト演算 (shifting operation)

シフト演算は、算術演算よりも低い優先順位を持っています:

shift_expr ::= a_expr | shift_expr ( "«" | "»" ) a_expr
Download entire grammar as text.

シフトの演算子は整数または長整数を引数にとります。 引数は共通の型に変換されます。シフト演算では、最初の引数を 二つ目の引数に応じたビット数だけ、左または右にビットシフト します。

n ビットの右シフトは、pow(2,n) による除算 として定義されています。 n ビットの左シフトは、 pow(2,n) による乗算として定義されています; 整数の場合、桁あふれ (overflow) のチェックはされないので、 演算によって末端のビットは捨てられます。また、結果の絶対値が pow(2, 31) よりも小さくない場合には、符号の反転が起こります。 負のビット数でシフトを行うと、 ValueError 例外を 送出します。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.6 二項算術演算 (binary arithmetic Up: 5. 式 (expression) Next: 5.8 ビット単位演算の二項演算 (binary bit-wise


5.8 ビット単位演算の二項演算 (binary bit-wise operation)

以下の三つのビット単位演算には、それぞれ異なる優先順位レベルがあります:

and_expr ::= shift_expr | and_expr "&" shift_expr
xor_expr ::= and_expr | xor_expr "^" and_expr
or_expr ::= xor_expr | or_expr "|" xor_expr
Download entire grammar as text.

& 演算子は、引数間でビット単位の AND をとった値になります。 引数は整数または長整数でなければなりません。引数は共通の型に変換 されます。

^ 演算子は、引数間でビット単位の XOR (排他的 OR) をとった値に なります。 引数は整数または長整数でなければなりません。引数は共通の型に変換 されます。

| 演算子は、引数間でビット単位の OR (非排他的 OR) をとった値に なります。 引数は整数または長整数でなければなりません。引数は共通の型に変換 されます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.7 シフト演算 (shifting operation) Up: 5. 式 (expression) Next: 5.9 比較 (comparison)


5.9 比較 (comparison)

C 言語と違って、Python における比較演算子は同じ優先順位をもっており、 全ての算術演算子、シフト演算子、ビット単位演算子よりも低くなっています。 また、a < b < c が数学で伝統的に用いられているのと同じ解釈に なる点も C 言語と違います:

comparison ::= or_expr ( comp_operator or_expr )*
comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "<>" | "!="
| "is" ["not"] | ["not"] "in"
Download entire grammar as text.

比較演算の結果はブール値: True または False になります。

比較はいくらでも連鎖することができます。例えば x < y <= z は x < y and y <= z と等価になります。ただしこの場合、前者では y はただ一度だけ評価される点が異なります (どちらの場合でも、 x < y が偽になると z の値はまったく評価されません)。

形式的には、 a, b, c, ..., y, z が式で、opa, opb, ..., opy が比較演算子で ある場合、a opa b opb c ...y opy z は a opa b and b opb c and ... y opy z と等価になります。ただし、前者では各式は多くても一度 しか評価されません。

a opa b opb c と書いた場合、 a から c までの範囲 にあるかどうかのテストを指すのではないことに注意してください。 例えば、x < y > z は (きれいな書き方ではありませんが) 完全に正しい文法です。

<> と != の二つの形式は等価です; C との整合性を 持たせるためには、!= を推奨します; 以下で != について 触れている部分では、<> を使うこともできます。 <> のような書き方は、現在では古い書き方とみなされています。

演算子 <, >, ==, >=, <=, および != は、二つのオブジェクト間の値を比較します。オブジェクトは 同じ型である必要はありません。双方のオブジェクトが数値であれば、 共通型への変換が行われます。それ以外の場合、異なる型のオブジェクトは 常に 不等であるとみなされ、一貫してはいるが規定されていない 方法で並べられます。

(このような比較演算の変則的な定義は、ソートのような操作や、 in およびnot in といった演算子の定義を 単純化するためのものです。将来、異なる型のオブジェクト間における 比較規則は変更されるかもしれません。)

同じ型のオブジェクト間における比較は、型によって異なります:

  • 数値間の比較では、算術的な比較が行われます。

  • 文字列間の比較では、各文字に対する等価な数値型 (組み込み関数 ord() の結果) を使って辞書的な (lexicographically) 比較が行われます。Unicode および 8 ビット文字列は、この動作に関しては 完全に互換です。

  • タプルやリスト間の比較では、対応する各要素の比較結果を使って辞書的な 比較が行われます。このため、二つの配列を等価にするためには、各要素が 完全に等価でなくてはならず、配列は同じ型で同じ長さをもっていなければ なりません。

    二つの配列が等価でない場合、異なる値を持つ最初の要素間での比較に 従った順序関係になります。例えば、cmp([1,2,x], [1,2,y]) は cmp(x,y) と等しい結果を返します。片方の要素に対応する要素が 他方にない場合、より短い配列が前に並びます (例えば、 [1,2] < [1,2,3] となります)。

  • マップ (辞書) 間の比較では、(key, value) からなるリストをソート したものが等しい場合に等価になります。5.3等価性評価以外の結果は一貫したやりかたで解決されるか、定義されないか のいずれかです。5.4

  • その他のほとんどの型の比較では、同じオブジェクトでないかぎり 等価にはなりません。あるオブジェクトの他のオブジェクトに対する 大小関係は任意に決定され、一つのプログラムの実行中は一貫した ものとなります。

演算子 in および not in は、集合内の要素であるか どうか (メンバシップ、membership) を調べます。 x in s は、x が集合 s のメンバである 場合には真となり、それ以外の場合には偽となります。 x not in s は x in s の否定 (negation) を返します。集合メンバシップテストは、伝統的には 配列型に限定されてきました; すなわち、あるオブジェクトがある集合 のメンバとなるのは、集合が配列型であり、配列がオブジェクトと等価な 要素を含む場合でした。しかしながら、現在ではオブジェクトが配列で なくてもメンバシップテストをサポートしています。特に、 辞書型では、key in dict と書くことで、 うまい具合にメンバシップテストをサポートしています; 他のマップ型も これに倣っているかもしれません。

リストやタプル型については、x in y は x == y[i] となるようなインデクス i が存在するとき、かつそのときに限り真になります。

Unicode 文字列または文字列型については、x in y は x が y の部分文字列であるとき、かつそのときに限り 真になります。この演算と等価なテストは y.find(x) != -1 です。 x および y は同じ型である必要はないので注意してください。 すなわち、u'ab' in 'abc' は True を返すことになります。 空文字列は、他のどんな文字列に対しても常に部分文字列とみなされます。 従って、"" in "abc" は True を返すことになります。 バージョン2.3 以降で変更された 仕様: 以前は、x は長さ 1 の文字列型でなければ なりませんでした

__contains__() メソッドの定義されたユーザ定義クラスでは、 x in y が真となるのは y.__contains__(x) が真となるとき、かつそのときに限ります。

__contains__() は定義していないが __getitem__() は定義しているようなユーザ定義クラスでは、 x in y は x == y[i] となるような非負の整数インデクス i が存在するとき、かつそのときにかぎり真となります。 インデクス i が負である場合に IndexError 例外が 送出されることはありません。 (別の何らかの例外が送出された場合、 例外は in から送出されたかのようになります)。

演算子 not in は、in の真値に対する逆転として定義されて います。

演算子 is および is not は、オブジェクトの アイデンティティに対するテストを行います: x is y は、 x と y が同じオブジェクト を指すとき、かつそのときに限り真になります。 x is not y は、is の真値を逆転したもの になります。

... したものが等しい場合に等価になります。5.3
実装では、この 演算をリストを構築したりソートしたりすることなく効率的に 行います。
... のいずれかです。5.4
Python の初期のバージョンでは、ソートされた (key, value) のリストに対して辞書的な比較を行っていましたが、 これは等価性の計算のようなよくある操作を実現するには非常に コストの高い操作でした。もっと以前のバージョンの Python では、辞書は アイデンティティだけで比較されていました。しかしこの仕様は、 {} との比較によって辞書が空であるか確かめられると期待して いた人々を混乱させていました。
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.8 ビット単位演算の二項演算 (binary bit-wise Up: 5. 式 (expression) Next: 5.10 ブール演算 (boolean operation)


5.10 ブール演算 (boolean operation)

ブール演算は、全ての Python 演算子の中で、最も低い優先順位になっています:

expression ::= or_test | lambda_form
or_test ::= and_test | or_test "or" and_test
and_test ::= not_test | and_test "and" not_test
not_test ::= comparison | "not" not_test
lambda_form ::= "lambda" [parameter_list]: expression
Download entire grammar as text.

ブール演算のコンテキストや、式が制御フロー文中で使われる最には、 以下の値: None 、すべての数値型におけるゼロ、空の配列 (文字列、 タプル、およびリスト) 、空のマップ型 (辞書) 、は偽 (false) であると 解釈されます。それ以外の値は真 (true) であると解釈されます。

演算子 not は、引数が偽である場合には 1 を、それ以外の 場合には 0 になります。

式 x and y は、まず x を評価します; x が偽なら、x の値を返します; それ以外の場合には、 y の値を評価し、その結果を返します。

式 x or y は、まず x を評価します; x が真なら、x の値を返します; それ以外の場合には、 y の値を評価し、その結果を返します。

(and も not も、返す値を 0 や 1 に 制限するのではなく、最後に評価した引数の値を返すので注意してください。 この仕様は、例えば s を文字列として、s が空文字列の 場合にデフォルトの値に置き換えるような場合に、s or 'foo' と書くと期待通りの値になるために便利なことがあります。 not は、式の値でなく独自に値を作成して返すので、 引数と同じ型の値を返すような処理に煩わされることはありません。 例えば、 not 'foo' は、 '' ではなく 0 になります)

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.9 比較 (comparison) Up: 5. 式 (expression) Next: 5.11 ラムダ (lambda)


5.11 ラムダ (lambda)

ラムダ形式 (lambda form, ラムダ式 (lambda expression)) は、 構文法的には式と同じ位置付けになります。ラムダは、無名関数を作成 できる省略記法です; 式 lambda arguments: expression は、関数オブジェクトになります。ラムダが表す無名オブジェクトは、 以下のコード

def name(arguments):
    return expression

で定義された関数と同様に動作します。

引数リストの構文法については、7.5 節を参照してください。 ラムダ形式で作成された関数は、実行文 (statement) を含むことができない ので注意してください。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.10 ブール演算 (boolean operation) Up: 5. 式 (expression) Next: 5.12 式のリスト


5.12 式のリスト

expression_list ::= expression ( "," expression )* [","]
Download entire grammar as text.

少なくとも一つのカンマを含む式のリストは、タプルになります。 タプルの長さは、リスト中の式の数に等しくなります。 リスト中の式は左から右へと順に評価されます。

単一要素のタプル (別名単集合 (singleton)) を作りたければ、 末尾にカンマが必要です。単一の式だけで、末尾にカンマをつけない場合 には、タプルではなくその式の値になります (空のタプルを作りたいなら、 中身が空の丸括弧ペア: () を使います。)

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.11 ラムダ (lambda) Up: 5. 式 (expression) Next: 5.13 評価順序


5.13 評価順序

Python は、式を左から右へと順に評価してゆきます。 ただし、代入式を評価する最には、代入演算子の右側項が左側項よりも 先に評価されるので注意してください。

以下に示す実行文の各行での評価順序は、添え字の数字順序と同じ になります:

expr1, expr2, expr3, expr4
(expr1, expr2, expr3, expr4)
{expr1: expr2, expr3: expr4}
expr1 + expr2 * (expr3 - expr4)
func(expr1, expr2, *expr3, **expr4)
expr3, expr4 = expr1, expr2

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.12 式のリスト Up: 5. 式 (expression) Next: 5.14 まとめ


5.14 まとめ

以下の表は、Python における演算子を、優先順位 の最も低い (結合度が最も低い) ものから最も高い (結合度が最も高い) ものの順に並べたものです。 同じボックス内に示された演算子は同じ優先順位を持ちます。演算子の 文法が示されていないかぎり、演算子は全て二項演算子です。 同じボックス内の演算子は、左から右へとグループ化されます (値のテストを含む比較演算子を除きます。比較演算子は、左から右に連鎖 します -- 5.9 を参照してください。また、べき乗演算子も 除きます。べき乗演算子は右から左にグループ化されます)。

演算子 | 説明
lambda | ラムダ式
or | ブール演算 OR
and | ブール演算 AND
not x | ブール演算 NOT
in, not in | メンバシップテスト
is, is not | アイデンティティテスト
<, <=, >, >=, <>, !=, == | 比較
| | ビット単位 OR
^ | ビット単位 XOR
& | ビット単位 AND
<<, >> | シフト演算
+, - | 加算および減算
*, /, % | 乗算、除算、剰余
+x, -x | 正符号、負符号
~x | ビット単位 NOT
** | べき乗
x.attribute | 属性参照
x[index] | 添字指定
x[index:index] | スライス操作
f(arguments...) | 関数呼び出し
(expressions...) | 式結合またはタプル表現
[expressions...] | リスト表現
{key:datum...} | 辞書表現
`expressions...` | 文字列への型変換

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.13 評価順序 Up: 5. 式 (expression) Next: 6. 単純文 (simple statement)


6. 単純文 (simple statement)

単純文とは、単一の論理行内に収められる文です。 単一の行内には、複数の単純文をセミコロンで区切って入れることが できます。単純文の構文は以下の通りです:

simple_stmt ::= expression_stmt
| assert_stmt
| assignment_stmt
| augmented_assignment_stmt
| pass_stmt
| del_stmt
| print_stmt
| return_stmt
| yield_stmt
| raise_stmt
| break_stmt
| continue_stmt
| import_stmt
| global_stmt
| exec_stmt
Download entire grammar as text.

  • 6.1 式文 (expression statement)
  • 6.2 Assert 文 (assert statement)
  • 6.3 代入文 (assignment statement)
    • 6.3.1 累算代入文 (augmented assignment statement)
  • 6.4 pass 文
  • 6.5 del 文
  • 6.6 print 文
  • 6.7 return 文
  • 6.8 yield 文
  • 6.9 raise 文
  • 6.10 break 文
  • 6.11 continue 文
  • 6.12 import 文
    • 6.12.1 future 文 (future statement)
  • 6.13 global 文
  • 6.14 exec 文
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 5.14 まとめ Up: Python リファレンスマニュアル Next: 6.1 式文 (expression statement)


6.1 式文 (expression statement)

式文は、 (主に対話的な使い方では) 値を計算して出力するために 使ったり、(通常は) プロシジャ (procedure: 有意な結果を返さない 関数のことです; Python では、プロシジャは値 None を返します) を呼び出すために使います。その他の使い方でも式文を使うことができ ますし、有用なこともあります。式文の構文は以下の通りです:

expression_stmt ::= expression_list
Download entire grammar as text.

式文は式のリスト (単一の式のこともあります) を値評価します。

対話モードでは、値が None でない場合、値を組み込み関数 repr() で文字列に変換して、 その結果のみからなる一行を標準出力に書き出します ( 6.6 節参照)。 (None になる式文の値は書き出されないので、プロシジャ呼び出しを 行っても出力は得られません。)

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6. 単純文 (simple statement) Up: 6. 単純文 (simple statement) Next: 6.2 Assert 文 (assert


6.2 Assert 文 (assert statement)

Assert 文 は、プログラム内にデバッグ用アサーション (debugging assertion) を仕掛けるための便利な方法です:

assert_stmt ::= "assert" expression ["," expression]
Download entire grammar as text.

単純な形式 "assert expression" は、

if __debug__:
   if not expression: raise AssertionError

と等価です。拡張形式 "assert expression1, expression2" は、

if __debug__:
   if not expression1: raise AssertionError, expression2

と等価です。

上記の等価関係は、 __debug__と AssertionError が、同名の組み込み 変数を参照しているという前提の上に成り立っています。 現在の実装では、組み込み変数 __debug__ は通常は 1 であり、 インタプリタに (コマンドラインオプション -O で) 最適化を要求すると 0 になります。現状のコード生成器は、コンパイル時に最適化が要求されて いると assert 文に対するコードを全く出力しません。 実行に失敗した式のソースコードをエラーメッセージ内に入れる必要は ありません; メッセージはスタックトレース内で表示されます。

__debug__ への代入は不正な操作です。組み込み変数の値は、 インタプリタが開始するときに決定されます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.1 式文 (expression statement) Up: 6. 単純文 (simple statement) Next: 6.3 代入文 (assignment statement)


6.3 代入文 (assignment statement)

代入文 は、名前を値に (再) 束縛したり、 変更可能なオブジェクトの属性や要素を変更したりするために使われます:

assignment_stmt ::= (target_list "=")+ expression_list
target_list ::= target ("," target)* [","]
target ::= identifier
| "(" target_list ")"
| "[" target_list "]"
| attributeref
| subscription
| slicing
Download entire grammar as text.

(末尾の三つのシンボルの構文については 5.3 節を 参照してください。)

代入文は式のリスト (これは単一の式でも、 カンマで区切られた式リストでもよく、後者はタプルになることを 思い出してください) を評価し、得られた単一の結果オブジェクトを ターゲット (target) のリストに対して左から右へと代入してゆきます。

代入はターゲット (リスト) の形式に従って再帰的に行われます。 ターゲットが変更可能なオブジェクト (属性参照、添字表記、またはスライス) の一部である場合、この変更可能なオブジェクトは最終的に代入を 実行して、その代入が有効な操作であるか判断しなければなりません。 代入が不可能な場合には例外を発行することもできます。型ごとに みられる規則や、送出される例外は、そのオブジェクト型定義 で与えられています ( 3.2 節を参照してください).

ターゲットリストへのオブジェクトの代入は、以下のようにして再帰的に 定義されています。

  • ターゲットリストが単一のターゲットからなる場合: オブジェクトはその ターゲットに代入されます。

  • ターゲットリストが、カンマで区切られた複数のターゲットからなる リストの場合: オブジェクトはターゲットリスト中のターゲット数と 同じ数の要素からなる配列でなければならず、その各要素は左から 右へと対応するターゲットに代入されます。(これは Python 1.5 で緩和された規則です; 以前のバージョンでは、代入するオブジェクトは タプルでなければなりませんでした。文字列も配列なので、今では "a, b = "xy"" のような代入は文字列が正しい長さを持つ限り 正規の操作になります。)

単一のターゲットへの単一のオブジェクトの代入は、以下のようにして 再帰的に定義されています。

  • ターゲットが識別子 (名前) の場合:

    • 名前が現在のコードブロック内の global 文に書かれて いない場合: 名前は現在のローカル名前空間内のオブジェクトに 束縛されます。

    • それ以外の場合: 名前は現在のグローバル名前空間内のオブジェクトに 束縛されます。

    名前がすでに束縛済みの場合、再束縛 (rebind) がおこなわれます。 再束縛によって、以前その名前に束縛されていたオブジェクトの 参照カウント (reference count) がゼロになった場合、オブジェクトは 解放 (deallocate) され、デストラクタ (destructor) が (存在すれば) 呼び出されます。

  • ターゲットが丸括弧や角括弧で囲われたターゲットリストの場合: オブジェクトはターゲットリスト中のターゲット数と 同じ数の要素からなる配列でなければならず、その各要素は左から 右へと対応するターゲットに代入されます。

  • ターゲットが属性参照の場合: 参照されている一次語の式 が値評価されます。値は代入可能な属性を伴うオブジェクトでなければ なりません; そうでなければ、 TypeError が送出されます。 次に、このオブジェクトに対して、被代入オブジェクトを指定した属性 に代入してよいか問い合わせます; 代入を実行できない場合、 例外 (通常は AttributeError ですが、必然ではありません) を送出します。

  • ターゲットが添字表記の場合: 参照されている一次語の式 が値評価されます。まず、値は変更可能な配列オブジェクト (例えばリスト) か、マップオブジェクト (例えば辞書) でなければなりません。 次に、添字表記の表す式が値評価されます。

    一次語が変更可能な配列オブジェクト (例えばリスト) の場合、 まず添字は整数でなければなりません。添字が負数の場合、配列の 長さが加算されます。添字は最終的に、配列の長さよりも小さな 非負の整数でなくてはなりません。次に、添字をインデクスに 持つ要素に非代入オブジェクトを代入してよいか、配列に問い合わせ ます。範囲を超えたインデクスに対してはIndexError が送出されます (添字指定された配列に代入を行っても、 リスト要素の新たな追加はできません)。

    一次語がマップオブジェクト (例えば辞書) の場合、まず添字は マップのキー型と互換性のある型でなくてはなりません。 次に、添字を被代入オブジェクトに関連付けるようなキー/データ の対を生成するようマップオブジェクトに問い合わせます。 この操作では、既存のキー/値の対を同じキーと別の値で置き換えても よく、(同じ値を持つキーが存在しない場合) 新たなキー/値の対を挿入しても かまいません。

  • ターゲットがスライスの場合: 参照されている一次語の式 が値評価されます。まず、値は変更可能な配列オブジェクト (例えばリスト) でなければなりません。被代入オブジェクトは同じ型を持った配列オブジェクト でなければなりません。次に、スライスの下境界と上境界を示す式があれば 評価されます; デフォルト値はそれぞれゼロと配列の長さです。 上下境界は整数にならなければなりません。いずれかの境界が負数に なった場合、配列の長さが加算されます。最終的に、境界は ゼロから配列の長さまでの内包になるようにクリップされます。 最後に、スライスを被代入オブジェクトで置き換えてよいか配列オブジェクトに 問い合わせます。オブジェクトで許されている限り、スライスの長さは 被代入配列の長さと異なっていてよく、この場合にはターゲット配列の 長さが変更されます。

(現在の実装では、ターゲットの構文は式の構文と同じであるとみなされて おり、無効な構文はコード生成フェーズ中に詳細なエラーメッセージを 伴って拒否されます。)

警告: 代入の定義では、左辺値と右辺値がオーバラップするような代入 (例えば、"a, b = b, a" を行うと、二つの変数を入れ替えます) を 定義しても `安全 (safe)' に代入できますが、代入対象となる 変数群 の間で オーバラップがある場合は安全ではありません！ 例えば、以下のプログラムは "[0, 2]" を出力してしまいます:

x = [0, 1]
i = 0
i, x[i] = 1, 2
print x

  • 6.3.1 累算代入文 (augmented assignment statement)
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.2 Assert 文 (assert Up: 6. 単純文 (simple statement) Next: 6.3.1 累算代入文 (augmented assignment


6.3.1 累算代入文 (augmented assignment statement)

累算代入文は、二項演算と代入文を組み合わせて一つの文にしたものです:

augmented_assignment_stmt ::= target augop expression_list
augop ::= "+=" | "-=" | "*=" | "/=" | "%=" | "**="
| "»=" | "«=" | "&=" | "^=" | "|="
Download entire grammar as text.

累算代入文は、ターゲット (通常の代入文と違って、アンパックは 起こりません) と式リストを評価し、それら二つの被演算子間で特定の累算 代入型の二項演算を行い、結果をもとのターゲットに代入します。 ターゲットは一度しか評価されません。

x += 1 のような累算代入式は、x = x + 1 のように書き換えて ほぼ同様の動作にできますが、厳密に等価にはなりません。累算代入の 方では、x は一度しか評価されません。また、実際の処理として、 可能ならば インプレース (in-place) 演算が実行されます。 これは、代入時に新たなオブジェクトを生成してターゲットに代入するの ではなく、以前のオブジェクトの内容を変更するということです。

累算代入文で行われる代入は、タプルへの代入や、一文中に複数の ターゲットが存在する場合を除き、通常の代入と同じように扱われます。 同様に、累算代入で行われる二項演算は、場合によって インプレース演算 が行われることを除き、通常の二項演算 と同じです。

属性参照のターゲットの場合、代入前の初期値は getattr() で 取り出され、演算結果は setattr() で代入されます。 二つのメソッドが同じ変数を参照するという必然性はないので注意してください。 例えば:

class A:
    x = 3    # class variable
a = A()
a.x += 1     # writes a.x as 4 leaving A.x as 3

のように、getattr() がクラス変数を参照していても、 setattr() はインスタンス変数への書き込みを行ってしまいます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.3 代入文 (assignment statement) Up: 6.3 代入文 (assignment statement) Next: 6.4 pass 文


6.4 pass 文

pass_stmt ::= "pass"
Download entire grammar as text.

pass はヌル操作 (null operation) です -- pass が実行されても、何も起きません。pass は、例えば:

def f(arg): pass    # a function that does nothing (yet)

class C: pass       # a class with no methods (yet)

のように、構文法的には文が必要だが、コードとしては何も実行したく ない場合のプレースホルダとして有用です。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.3.1 累算代入文 (augmented assignment Up: 6. 単純文 (simple statement) Next: 6.5 del 文


6.5 del 文

del_stmt ::= "del" target_list
Download entire grammar as text.

オブジェクトの削除 (deletion) は、代入の定義と非常に似た方法で 再帰的に定義されています。ここでは完全な詳細を記述するよりも いくつかのヒントを述べるにとどめます。

ターゲットリストに対する削除は、各々のターゲットを左から右へと 順に再帰的に削除します。

名前に対して削除を行うと、ローカルまたはグローバル名前空間での その名前の束縛を解除します。どちらの名前空間かは、名前が同じコード ブロック内の global 文で宣言されているかどうかによります。 名前が未束縛 (unbound) であるばあい、NameError 例外 が送出されます。

ネストしたブロック中で自由変数 になっている ローカル名前空間上の名前に対する削除は不正な操作になります

属性参照、添字表記、およびスライスの削除操作は、対象となる一次語 オブジェクトに渡されます; スライスの削除は一般的には適切な 型の空のスライスを代入するのと等価です (が、この仕様自体も スライスされるオブジェクトで決定されています)。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.4 pass 文 Up: 6. 単純文 (simple statement) Next: 6.6 print 文


6.6 print 文

print_stmt ::= "print" ( [expression ("," expression)* [","]]
| ">>" expression [("," expression)+ [","]] )
Download entire grammar as text.

print は、式を逐次的に評価し、得られたオブジェクトを 標準出力に書き出します。オブジェクトが文字列でなければ、まず文字列 変換規則を使って文字列に変換され、次いで (得られた文字列か、オリジナル の文字列が) 書き出されます。出力系の現在の書き出し位置が行頭にある と考えられる場合を除き、各オブジェクトの出力前にスペースが一つ出力 されます。行頭にある場合とは、(1) 標準出力にまだ何も書き出されて いない場合、(2) 標準出力に最後に書き出された文字が "\n" である、または (3) 標準出力に対する最後の書き出し操作が print 文によるものではない場合、です。(こうした理由から、 場合によっては空文字を標準出力に書き出すと便利なことがあります。) 注意: 組み込みのファイルオブジェクトでない、ファイルオブジェクト に似た動作をするオブジェクトでは、組み込みのファイルオブジェクト が持つ上記の性質を適切にエミュレートしていないことがあるため、 当てにしないほうがよいでしょう。

print 文がカンマで終了していない限り、末尾には文字 "\n" が書き出されます。この仕様は、文に予約語 print がある場合のみの動作です。

標準出力は、組み込みモジュール sys 内で stdout という名前のファイルオブジェクトとして定義されています。 該当するオブジェクトが存在しないか、オブジェクトに write() メソッドがない場合、RuntimeError 例外が送出されます。.

print には、上で説明した構文の第二形式で定義されている 拡張形式があります。 この形式は、``山形 print 表記 (print chevron)'' と呼ばれます。この形式では、>> の直後にくる最初の 式の値評価結果は ``ファイル類似 (file-like)'' なオブジェクト、とりわけ 上で述べたように write() メソッドを持つオブジェクトで なければなりません。この拡張形式では、ファイルオブジェクトを指定する 式よりも後ろの式が、指定されたファイルオブジェクトに出力されます。 最初の式の値評価結果が None になった場合、 sys.stdout が出力ファイルとして使われます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.5 del 文 Up: 6. 単純文 (simple statement) Next: 6.7 return 文


6.7 return 文

return_stmt ::= "return" [expression_list]
Download entire grammar as text.

return は、関数定義内で構文法的にネストして現れますが、 ネストしたクラス定義内には現れません。

式リストがある場合、リストが値評価されます。それ以外の場合は None で置き換えられます。

return を使うと、式リスト (または None) を戻り値として、現在の関数呼び出しから抜け出します。

return によって、finally 節をともなう try 文の外に処理が引き渡されると、実際に関数から抜ける前に finally 節が実行されます。

ジェネレータ関数の場合には、return 文の中に expression_list を入れることはできません。 ジェネレータ関数の処理コンテキストでは、単体の return はジェネレータ処理を終了し StopIteration を送出させる ことを示します。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.6 print 文 Up: 6. 単純文 (simple statement) Next: 6.8 yield 文


6.8 yield 文

yield_stmt ::= "yield" expression_list
Download entire grammar as text.

yield 文は、ジェネレータ関数 (generator function) を 定義するときだけ使われ、かつジェネレータ関数の本体の中でだけ 用いられます。 関数定義中で yield 文を使うだけで、関数定義は通常の関数 でなくジェネレータ関数になります。

ジェネレータ関数が呼び出されると、ジェネレータイテレータ (generator iterator)、一般的にはジェネレータ (generator) を 返します。ジェネレータ関数の本体は、ジェネレータの next() が例外を発行するまで繰り返し呼び出して実行します。

yield 文が実行されると、現在のジェネレータの状態は 凍結 (freeze) され、expression_list の値が next() の呼び出し側に返されます。ここでの ``凍結'' は、ローカルな変数への 束縛、命令ポインタ (instruction pointer)、および内部実行スタック (internal evaluation stack) を含む、全てのローカルな状態が保存される ことを意味します: すなわち、必要な情報を保存しておき、次に next() が呼び出された際に、関数が yield 文をあたかも もう一つの外部呼出しであるかのように処理できるようにします。

yield 文は、try ... finally 構造の try 節中で使うことはできません。ジェネレータが常に 実行再開されるとは限らないので、finally ブロックが常に 実行される保証がないという問題があるためです。

注意: Python 2.2 では、generators 機能が有効になっている場合にのみ yield 文を使えます。Python 2.3 では、常に有効になっています。 __future__ import 文を使うと、この機能を有効にできます:

from __future__ import generators

参考資料:

PEP 0255, 単純なジェネレータ
Python へのジェネレータと yield 文の導入提案

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.7 return 文 Up: 6. 単純文 (simple statement) Next: 6.9 raise 文


6.9 raise 文

raise_stmt ::= "raise" [expression ["," expression ["," expression]]]
Download entire grammar as text.

式を伴わない場合、raise は現在のスコープで最終的に有効に なっている式を再送出します。そのような式が現在のスコープに全く ない場合、エラーを示す例外が送出されます。

それ以外の場合、raise は式を値評価して、三つのオブジェクトを 取得します。このとき、None を省略された式の値として使います。 最初の二つのオブジェクトは、例外の 型 (type) と 例外の 値 (value) を決定するために用いられます。

最初のオブジェクトがインスタンスである場合、例外の型はインスタンス のクラスになり、インスタンス自体が例外の値になります。このとき 第二のオブジェクトは None でなければなりません。

最初のオブジェクトがクラスの場合、例外の型になります。 第二のオブジェクトは、例外の値を決めるために使われます: 第二のオブジェクトがインスタンスならば、そのインスタンスが 例外の値になります。第二のオブジェクトがタプルの場合、 クラスのコンストラクタに対する引数リストとして使われます; None なら、空の引数リストとして扱われ、それ以外の型 ならコンストラクタに対する単一の引数として扱われます。 このようにしてコンストラクタを呼び出して生成したインスタンス が例外の値になります。

第三のオブジェクトが存在し、かつ None でなければ、 オブジェクトはトレースバック オブジェクト でなければなりません ( 3.2 節参照)。また、 例外が発生した場所は現在の処理位置に置き換えられます。 第三のオブジェクトが存在し、オブジェクトがトレースバック オブジェクトでも None でもなければ、TypeError 例外が送出されます。raise の三連式型は、except 節から透過的に例外を再送出するのに便利ですが、再送出すべき 例外が現在のスコープで発生した最も新しいアクティブな例外で ある場合には、式なしの raise を使うよう推奨します。

例外に関する追加情報は 4.2 節にあります。また、 例外処理に関する情報は 7.4 節にあります。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.8 yield 文 Up: 6. 単純文 (simple statement) Next: 6.10 break 文


6.10 break 文

break_stmt ::= "break"
Download entire grammar as text.

break 文は for ループや while ループ内の ネストで構文法的にのみ現れますが、ループ内の関数定義やクラス定義 には現れません。

break 文は、文を囲う最も内側のループを終了させ、 ループにオプションの else 節がある場合には else 節に飛びます。

for ループを break によって終了すると、 ループ制御ターゲットはその時の値を保持します。

break が finally 節を伴う try 文の 外側に処理を渡す際には、ループを実際に抜ける前にそのfinally 節が実行されます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.9 raise 文 Up: 6. 単純文 (simple statement) Next: 6.11 continue 文


6.11 continue 文

continue_stmt ::= "continue"
Download entire grammar as text.

continue 文は for ループや while ループ内の ネストで構文法的にのみ現れますが、ループ内の関数定義やクラス定義、 try 文の中には現れません。6.1

continue 文は、文を囲う最も内側のループの次の周期に 処理を継続します。

... 文の中には現れません。6.1
except 節や else 節中に置くことはできます。try 文に置けない という制限は、実装側の不精によるもので、そのうち改善されることでしょう。
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.10 break 文 Up: 6. 単純文 (simple statement) Next: 6.12 import 文


6.12 import 文

import_stmt ::= "import" module ["as" name] ( "," module ["as" name] )*
| "from" module "import" identifier ["as" name]
  ( "," identifier ["as" name] )*
| "from" module "import" "*"
module ::= (identifier ".")* identifier
Download entire grammar as text.

import 文は、(1) モジュールを探し、必要なら初期化 (initialize) する; (import 文のあるスコープにおける) ローカルな名前空間で 名前を定義する、の二つの段階を踏んで初期化されます。 第一形式 (from のない形式) は、上記の段階をリスト中にある 各識別子に対して繰り返し実行していきます。 from のある形式では、(1) を一度だけ行い、次いで (2) を 繰り返し実行します。

組み込みモジュールや拡張モジュールの ``初期化'' は、ここでは 初期化関数の呼び出しを意味します。モジュールは初期化を行うために かならず初期化関数を提供しなければなりません (リファレンス実装では、関数名はモジュール名の前に ``init'' を つけたものになっています); Python で書かれたモジュールの ``初期化'' は、モジュール本体の 実行を意味します。

Python 処理系は、すでに初期化済みのモジュールや、初期化中のモジュール をモジュール名でインデクス化したテーブルを維持しています。 このテーブルは sys.modules からアクセスできます。 モジュール名がこのテーブル内にあるなら、段階 (1) は完了しています。 そうでなければ、処理系はモジュール定義の検索を開始します。モジュール が見つかった場合、モジュールを読み込み (load) ます。モジュール検索や 読み込みプロセスの詳細は、実装やプラットフォームに依存します。 一般的には、ある名前のモジュールを検索する際、まず同名の ``組み込み (built-in)'' モジュールを探し、次に sys.path で列挙されている場所を探します。

組み込みモジュールが見つかった場合 、 組み込みの初期化コードが実行され、段階 (1) を完結します。 合致するファイルが見つからなかった場合、 ImportError が送出されます。 ファイルが見つかった場合、ファイルを構文解析して実行可能な コードブロックにします。構文エラーが起きた場合、 SyntaxError が送出されます。 それ以外の場合、まず指定された名前をもつ空のモジュールを作成し、 モジュールテーブルに挿入します。次に、このモジュールの実行コンテキスト 下でコードブロックを実行します。実行中に例外が発生すると、段階 (1) を終了 (terminate) します。

段階 (1) が例外を送出することなく完了したなら、段階 (2) を開始 します。

import 文の第一形式は、ローカルな名前空間に置かれた モジュール名をモジュールオブジェクトに束縛し、import すべき 次の識別子があればその処理に移ります。モジュール名の後ろに as がある場合、as の後ろの名前はモジュールの ローカルな名前として使われます。

from 形式は、モジュール名の束縛を行いません: from 形式では、段階 (1) で見つかったモジュール内から、 識別子リストの各名前を順に検索し、見つかったオブジェクトを識別子の 名前でローカルな名前空間において束縛します。 import の第一形式と同じように、"as localname" で別名を与えることができます。指定された名前が見つからない場合、 ImportError が送出されます。識別子のリストを星印 ("*") で置き換えると、モジュールで公開されている名前 (public name) 全てを import 文のある場所のローカルな 名前空間に束縛します。。。

モジュールで 公開されている名前 (public names) は、 モジュールの名前空間内にある __all__ という名前の変数 を調べて決定します; __all__ が定義されている場合、 __all__ はモジュールで定義されていたり、import されている ような名前の文字列からなる配列でなければなりません。 __all__ 内にある名前は、全て公開された名前であり、 実在するものとみなされます。 __all__ が定義されていない場合、モジュールの名前空間に 見つかった名前で、アンダースコア文字 ("_") で始まっていない 全ての名前が公開された名前になります。 __all__ には、公開されている API 全てを入れなければなりません。 __all__ には、(モジュール内で import されて使われている ライブラリモジュールのように) API を構成しない要素を意に反して 公開してしまうのを避けるという意図があります。

"*" を使った from 形式は、モジュールのスコープ内 だけに作用します。関数内でワイルドカードの import 文 -- "import *" -- を使い、関数が自由変数を伴うネストされたブロック であったり、ブロックを含んでいる場合、コンパイラは SyntaxError を送出します。

階層的なモジュール名:モジュール名に一つまたはそれ以上のドットが入っている場合、 モジュール検索パスは違った扱われ方をします。最後のドットまでの 各識別子からなる配列は、``パッケージ (package)'' を見つけるために使われます; 次に、パッケージ内から各識別子が 検索されます。パッケージとは、一般には sys.path 上のディレクトリ のサブディレクトリで、__init__.py.ファイルを持つものです。 [XXX この説明については、ここでは今のところこれ以上詳しく書けません; 詳細や、パッケージ内モジュールの検索がどのように行われるかは、 http://www.python.org/doc/essays/packages.html を参照 してください]

どのモジュールがロードされるべきかを動的に決めたいアプリケーションの ために、組み込み関数 __import__() が提供されています; 詳細は、Python ライブラリリファレンス の 組み込み関数 を参照してください。

  • 6.12.1 future 文 (future statement)
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.11 continue 文 Up: 6. 単純文 (simple statement) Next: 6.12.1 future 文 (future


6.12.1 future 文 (future statement)

future 文 は、 将来の特定の Python のリリースで利用可能になるような構文や意味付け を使って、特定のモジュールをコンパイルさせるための、コンパイラに 対する指示句 (directive) です。 future 文は、言語仕様に非互換性がもたらされるような、将来の Python のバージョンに容易に移行できるよう意図されています。 future 文によって、新たな機能が標準化されたリリースが 出される前に、その機能をモジュール単位で使えるようにします。

future_statement ::= "from" "__future__" "import" feature ["as" name]
("," feature ["as" name])*
feature ::= identifier
name ::= identifier

future 文は、モジュールの先頭周辺に書かなければなりません。 future 文の前に書いてよい内容は:

  • the module docstring (if any),
  • comments,
  • blank lines, and
  • other future statements.

です。

Python 2.3 が feature 文で新たに認識するようになった機能は、 "generators"、"division"、および "nested_scopes"です。 "generators" および "nested_scopes" は Python 2.3 では常に有効になっているので、冗長な機能名といえます。

future 文は、コンパイル時に特別なやり方で認識され、扱われます: 言語の中核をなす構文構成 (construct) に対する意味付けが変更されて いる場合、変更部分はしばしば異なるコードを生成することで実現 されています。新たな機能によって、(新たな予約語のような) 互換性のない新たな構文が取り入れられることさえあります。 この場合、コンパイラはモジュールを別のやりかたで解析する必要が あるかもしれません。こうしたコード生成に関する決定は、 実行時まで先延ばしすることはできません。

これまでの全てのリリースにおいて、コンパイラはどの機能が定義済み かを知っており、future 文に未知の機能が含まれている場合には コンパイル時エラーを送出します。

future 文の実行時における直接的な意味付けは、import 文と同じです。 標準モジュール __future__ があり、これについては後で述べます。 __future__ は、future 文が実行される際に通常の方法で import されます。

future 文の実行時における特別な意味付けは、future 文で有効化される 特定の機能によって変わります。

以下の文:

import __future__ [as name]

には、何ら特殊な意味はないので注意してください。

これは future 文ではありません; この文は通常の import 文であり、 その他の特殊な意味付けや構文的な制限はありません。

future 文の入ったモジュール M 内で使われている exec 文、組み込み関数 compile() や execfile() によってコンパイルされるコードは、デフォルトの設定では、 future 文に関係する新たな構文や意味付けを使うようになっています。 Python 2.2 からは、この仕様を compile() のオプション引数 で制御できるようになりました -- 詳細はライブラリリファレンスの compile() に関するドキュメントを参照してください。

対話的インタプリタのプロンプトでタイプ入力した future 文は、 その後のインタプリタセッション中で有効になります。インタプリタ を -i オプションで起動して実行すべきスクリプト名を 渡し、スクリプト中に future 文を入れておくと、新たな機能は スクリプトが実行された後に開始する対話セッションで有効になります。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.12 import 文 Up: 6.12 import 文 Next: 6.13 global 文


6.13 global 文

global_stmt ::= "global" identifier ("," identifier)*
Download entire grammar as text.

global 文は、現在のコードブロック全体で維持される宣言文 です。global 文は、列挙した識別子をグローバル変数として 解釈するよう指定することを意味します。 global を使わずにグローバル変数に代入を行うことは 不可能ですが、自由変数を使えばその変数をグローバルであると宣言せずに グローバル変数を参照することができます。

global 文で列挙する名前は、同じコードブロック中で、 プログラムテキスト上 global 文より前に使っては なりません。

global 文で列挙する名前は、for ループの ループ制御ターゲットや、class 定義、関数定義、 import 文内で仮引数として使ってはなりません。

(現在の実装では、後ろ二つの制限については強制していませんが、 プログラムでこの緩和された仕様を乱用すべきではありません。 将来の実装では、この制限を強制したり、暗黙のうちにプログラム の意味付けを変更したりする可能性があります。)

プログラマのための注意点: global はパーザに対する指示句 (directive) です。 この指示句は、global 文と同時に読み込まれたコード に対してのみ適用されます。特に、exec 文内に入っている global 文は、exec 文を 含んでいる コードブロック内に効果を及ぼすことはなく、exec 文内に 含まれているコードは、exec 文を含むコード内での global 文に影響を受けません。同様のことが、関数 eval()、 execfile() 、および compile() にも当てはまります。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.12.1 future 文 (future Up: 6. 単純文 (simple statement) Next: 6.14 exec 文


6.14 exec 文

exec_stmt ::= "exec" expression ["in" expression ["," expression]]
Download entire grammar as text.

この文は、Python コードの動的な実行をサポートします。 最初の式の値評価結果は文字列か、開かれたファイルオブジェクトか、 コードオブジェクトでなければなりません。文字列の場合、 一連の Python 実行文として解析し、(構文エラーが生じない限り) 実行します。開かれたファイルであれば、ファイルを EOF まで読んで解析し、実行します。コードオブジェクトなら、単に オブジェクトを実行します。

いずれの場合でも、オプションの部分が省略されると、コードは 現在のスコープ内で実行されます。in の後ろに一つだけ 式を指定する場合、その式は辞書でなくてはならず、 グローバル変数とローカル変数の両方に使われます。 二つの式が与えられた場合、双方ともに辞書でなくてはならず、 それぞれグローバル変数とローカル変数として使われます。

exec の副作用として実行されるコードで設定された変数名に 対応する名前の他に、追加のキーを辞書に追加することがあります。 例えば、現在の実装では、組み込みモジュール __builtin__ の辞書に対する参照を、__builtins__ (!) というキーで追加 することがあります。

プログラマのためのヒント: 式の動的な評価は、組み込み関数 eval() でサポートされています 組み込み関数 globals() および locals() は、 それぞれ現在のグローバル辞書とローカル辞書を返すので、 exec に渡して使うと便利です。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.13 global 文 Up: 6. 単純文 (simple statement) Next: 7. 複合文 (compound statement)


7. 複合文 (compound statement)

複合文には、他の文 (のグループ) が入ります; 複合文は、中に入っている 他の文の実行の制御に何らかのやり方で影響を及ぼします。 一般的には、複合文は複数行にまたがって書かれますが、 全部の文を一行に連ねた単純な書き方もあります。

if、while 、および for 文は、 伝統的な制御フロー構成を実現します。try は例外処理 かつ/または一連の文に対するクリーンアップコードを指定します。 関数とクラス定義もまた、構文法的には複合文です。

複合文は、一つまたはそれ以上の `節 (clause)' からなります。 一つの節は、ヘッダと `スイート (suite)' からなります。 特定の複合文を構成する節のヘッダ部分は、全て同じインデント レベルになります。各々の節ヘッダ行は一意に識別されるキーワード から始まり、コロンで終わります。スイートは、ヘッダのコロンの後ろに セミコロンで区切られた一つまたはそれ以上の単純文を並べるか、 ヘッダ行後のインデントされた文の集まりです。 後者の形式のスイートに限り、ネストされた複合文を入れることが できます; 以下の文は、else 節がどの if 節 に属するかがはっきりしないという理由から不正になります:

if test1: if test2: print x

また、このコンテキスト中では、セミコロンはコロンよりも強い結合を 表すことにも注意してください。従って、以下の例では、print は全て実行されるか、されないかのどちらかです:

if x < y < z: print x; print y; print z

まとめると、以下のようになります:

compound_stmt ::= if_stmt
| while_stmt
| for_stmt
| try_stmt
| funcdef
| classdef
suite ::= stmt_list NEWLINE | NEWLINE INDENT statement+ DEDENT
statement ::= stmt_list NEWLINE | compound_stmt
stmt_list ::= simple_stmt (";" simple_stmt)* [";"]
Download entire grammar as text.

文は常に NEWLINEか、その後に DEDENT が続いたもので終了することに注意してください。 また、オプションの継続節は常にあるキーワード から始まり、このキーワードから複合文を開始することはできないため、 曖昧さは存在しないことにも注意してください (Python では、 `ぶら下がり(dangling) else' 問題を、ネストされた if 文はインデントさせること解決しています)。

以下の節における文法規則の記述方式は、明確さのために、 各節を別々の行に書くようにしています。

  • 7.1 if 文
  • 7.2 while 文
  • 7.3 for 文
  • 7.4 try 文
  • 7.5 関数定義
  • 7.6 クラス定義
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 6.14 exec 文 Up: Python リファレンスマニュアル Next: 7.1 if 文


7.1 if 文

if 文は、条件分岐を実行するために使われます:

if_stmt ::= "if" expression ":" suite
( "elif" expression ":" suite )*
["else" ":" suite]
Download entire grammar as text.

if 文は、式を一つ一つ評価してゆき、真になるまで続けて、 真になった節のスイートだけを選択します (真: true と偽: false の定義 については、 5.10 節を参照してください); 次に、選択した スイートを実行します (または、 if 文の他の部分を実行 したり、評価したりします) 全ての式が偽になった場合、 else 節があれば、そのスイート が実行されます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 7. 複合文 (compound statement) Up: 7. 複合文 (compound statement) Next: 7.2 while 文


7.2 while 文

while 文は、式の値が真である間、実行を繰り返すために使われます:

while_stmt ::= "while" expression ":" suite
["else" ":" suite]
Download entire grammar as text.

while 文は式を繰り返し真偽評価し、真であれば最初の スイートを実行します。式が偽であれば (最初から偽になっていることも ありえます)、else 節がある場合にはそれを実行し、 ループを終了します。

最初のスイート内で break 文が実行されると、else 節の スイートを実行することなくループを終了します。 continue 文が最初のスイート内で実行されると、 スイート内にある残りの文の実行をスキップして、式の真偽評価に戻ります。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 7.1 if 文 Up: 7. 複合文 (compound statement) Next: 7.3 for 文


7.3 for 文

for 文は、配列 (文字列、タプルまたはリスト) や、その他の 反復可能なオブジェクト (iterable object) 内の要素に渡って反復処理を 行うために使われます:

for_stmt ::= "for" target_list "in" expression_list ":" suite
["else" ":" suite]
Download entire grammar as text.

式リストは一度だけ値評価されます; 結果は配列にならなければなりません。 次に、配列の各要素についてインデクスの小さい順に一度だけスイートを 実行します。このとき配列内の要素が通常の代入規則を使ってターゲットリスト に代入され、その後スイートが実行されます。全ての要素を使い切ると (配列が空の場合にはすぐに)、 else 節があればそれが 実行され、ループを終了します。

最初のスイート内で break 文が実行されると、else 節の スイートを実行することなくループを終了します。 continue 文が最初のスイート内で実行されると、 スイート内にある残りの文の実行をスキップして、式の真偽評価に戻ります。

スイートの中では、ターゲットリスト内の変数に代入を行えます; この代入によって、次に代入される要素に影響を及ぼすことはありません。

ループが終了してもターゲットリストは削除されませんが、配列が 空の場合には、ループでの代入は全く行われません。 ヒント: 組み込み関数 range() は、 Pascal 言語における for i := a to b do の効果を エミュレートするのに適した数列を返します; すなわち、 range(3) はリスト [0, 1, 2] を返します。

警告: ループ中の配列の変更には微妙な問題があります (これは 変更可能な配列、すなわちリストで起こります)。 どの要素が次に使われるかを追跡するために、内部的なカウンタが 使われており、このカウンタは反復処理を行うごとに加算されます。 このカウンタが配列の長さに達すると、ループは終了します。 このことは、スイート中で配列から現在の (または以前の) 要素を 除去すると、(次の要素のインデクスは、すでに取り扱った要素の インデクスになるために) 次の要素が飛ばされることを意味します。 同様に、スイート中で配列中の現在の要素以前に要素を挿入すると、 ループ中で現在の要素が再度扱われることになります。 こうした仕様は、厄介なバグになります。配列全体に相当するスライスを 使って一時的なコピーを作ると、これを避けることができます。

for x in a[:]:
    if x < 0: a.remove(x)

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 7.2 while 文 Up: 7. 複合文 (compound statement) Next: 7.4 try 文


7.4 try 文

try 文は、ひとまとめの文に対して、例外処理かつ/または クリーンアップコードを指定します:

try_stmt ::= try_exc_stmt | try_fin_stmt
try_exc_stmt ::= "try" ":" suite
("except" [expression ["," target]] ":" suite)+
["else" ":" suite]
try_fin_stmt ::= "try" ":" suite "finally" ":" suite
Download entire grammar as text.

try 文には二つの形式: try...except および try...finally があります。 これら二つの形式を混合することはできません (互いにネストすることは できます)。

try...except 形式では、一つまたはそれ以上の 例外ハンドラ (except 節) を指定します。 try 節内で全く例外が起きなければ、どの例外ハンドラも 実行されません。try スイート内で例外が発生すると、 例外ハンドラの検索が開始されます。この検索では、except 節を逐次調べて、発生した例外に合致するまで続けます。 式を伴わない except 節を使う場合、最後に書かなければ なりません; この except 節は全ての例外に合致します。 式を伴う except 節に対しては、式が値評価され、 返されたオブジェクトが例外と ``互換である (compatible)'' 場合にその節が合致します。ある例外に対してオブジェクトが互換で あるのは、オブジェクトがその例外のアイデンティティを持つオブジェクト であるか、(クラスの例外の場合) 例外の基底クラスであるか、 例外と互換性のある要素が入ったタプルである場合です。 同じ値を持つオブジェクトであるだけでなく、アイデンティティが 合致しなければならないので注意してください。

例外がどの except 節にも合致しなかった場合、現在の コードを囲うさらに外側、そして呼び出しスタックへと検索を続けます。

except 節のヘッダにある式を値評価するときに例外が発生 すると、元々のハンドラ検索はキャンセルされ、新たな例外に対する 例外ハンドラの検索を現在の except 節の外側のコードや 呼び出しスタックに対して行います (try 文全体が 例外を発行したかのように扱われます)。

合致する except 節が見つかると、その except 節に ターゲットが指定されている場合、ターゲットに例外のパラメタが代入 され、その後except 節のスイートが実行されます。 except 節は全て実行可能なブロックを持っていなければ なりません。ブロックの末尾に到達すると、通常は try 文 全体の直後に実行を継続します。(このことは、同じ例外に対してネスト した二つの例外ハンドラが存在し、内側のハンドラ内の try 節 で例外が発生した場合、外側のハンドラが例外を処理できないことを意味 します。)

except 節のスイートが実行されｍる前に、例外に関する 詳細が sysモジュール内の三つの 変数に代入されます: sys.exc_type は、例外を示すオブジェクト を受け取ります; sys.exc_value は例外のパラメタを受け取ります; sys.exc_traceback は、プログラム上の例外が発生した位置を 識別するトレースバックオブジェクト( 3.2 節参照) を受け取ります。 これらの詳細はまた、関数 sys.exc_info() を介して 入手することもできます。この関数は タプル (exc_type, exc_value, exc_traceback) を返します。ただしこの関数に対応する変数の使用は、スレッドを使った プログラムで安全に使えないため撤廃されています。 Python 1.5 からは、例外を処理した関数から戻るときに、以前の値 (関数呼び出し前の値) に戻されます。

オプションの else 節は、実行の制御が try 節 の末尾に到達した場合に実行されます。7.1 else 節内で起きた例外は、else 節に先行する except 節で処理されることはありません。

try...finally 形式では、`クリーンアップ' ハンドラを 指定します。まず try 節が実行されます。例外が全く発生 しなければ、finally 節が実行されます。例外がtry 節内で発生した場合、例外は一時的に保存され、 finally が実行された後、保存されていた例外が再送出されます。 finally 節で別の例外が送出されたり、return や break 節が実行された場合、保存されていた例外は失われます。 finally 節での continue 文の使用は不正となります (理由は現在の実装上の問題にあります -- この制限は将来解消される かもしれません)。finally 節の実行中は、例外情報を取得 することはできません。

try...finally 文の try スイート内で return、 break、または continue 文が 実行された場合、finally 節も `抜け出る途中に (on the way out)' 実行されます。

例外に関するその他の情報は 4.2 節にあります。また、 raise 文の使用による例外の生成に関する情報は、 6.9 節にあります。

... の末尾に到達した場合に実行されます。7.1
現在、制御が ``末尾に到達する'' のは、例外が発生したり、 return、continue、または break 文 が実行される場合を除きます。
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 7.3 for 文 Up: 7. 複合文 (compound statement) Next: 7.5 関数定義


7.5 関数定義

関数定義は、ユーザ定義関数オブジェクトを定義します ( 3.2 節参照):

funcdef ::= "def" funcname "(" [parameter_list] ")" ":" suite
parameter_list ::= (defparameter ",")*
("*" identifier [, "**" identifier]
| "**" identifier | defparameter [","])
defparameter ::= parameter ["=" expression]
sublist ::= parameter ("," parameter)* [","]
parameter ::= identifier | "(" sublist ")"
funcname ::= identifier
Download entire grammar as text.

関数定義は実行可能な文です。関数定義を実行すると、現在のローカルな 名前空間内で関数名を関数オブジェクト (関数の実行可能コードを くるむラッパ) に束縛します。この関数オブジェクトには、関数が呼び出された 際に使われるグローバルな名前空間として、現在のグローバルな名前空間 への参照が入っています。

関数定義は関数本体を実行しません; 関数本体は関数が呼び出された 時にのみ実行されます。

一つ以上のトップレベルのパラメタに parameter = expression の形式がある場合、関数は ``デフォルトのパラメタ値 (default parameter values)'' を持つと いいます。デフォルト値を伴うパラメタに対しては、関数呼び出しの 際に対応するパラメタが省略されると、パラメタの値はデフォルト値で 置き換えられます。 あるパラメタがデフォルト値を持つ場合、それ以後の パラメタは全てデフォルト値を持たなければなりません -- これは 文法的には表現されていない構文上の制限です。

デフォルトパラメタ値は関数定義を実行する際に値評価されます。 これは、デフォルトパラメタの式は関数を定義するときにただ一度だけ評価され、 同じ ``計算済みの'' 値が全ての呼び出しで使われることを意味します。 デフォルトパラメタ値がリストや辞書のような変更可能なオブジェクトである 場合、この使用を理解しておくことは特に重要です: 関数でこのオブジェクト を (例えばリストに要素を追加して) 変更する と、実際のデフォルト 値が変更されてしまいます。一般には、これは意図しない動作です。 このような動作を避けるには、デフォルト値に None を使い、 この値を関数本体の中で明示的にテストします。例えば以下のようにします:

def whats_on_the_telly(penguin=None):
    if penguin is None:
        penguin = []
    penguin.append("property of the zoo")
    return penguin

関数呼び出しの意味付けに関する詳細は、 5.3.4 節で述べられて います。 関数呼び出しを行うと、パラメタリストに記述された全てのパラメタ に対して、固定引数、キーワード引数、デフォルト引数のいずれか から値を代入します。``*identifier'' 形式が存在する場合、 余った固定引数を受け取るタプルに初期化されます。この変数の デフォルト値は空のタプルです。``**identifier'' 形式が 存在する場合、余ったキーワード引数を受け取るタプルに初期化されます。 デフォルト値は空の辞書です。

式で直接使うために、無名関数 (名前に束縛されていない関数) を作成する ことも可能です。無名関数の作成には、 5.11 節で記述されている ラムダ形式 (lambda form) を使います。ラムダ形式は、単純化された 関数定義を行うための略記法にすぎません; ``def'' 文で定義 された関数は、ラムダ形式で定義された関数と全く同様に引渡したり、 他の名前に代入したりできます。実際には、``def'' 形式は複数の 式を実行できるという点でより強力です。

プログラマのための注釈: 関数は一級の (first-class) オブジェクト です。関数定義内で``def'' 形式を実行すると、戻り値として返したり 引き渡したりできるローカルな関数を定義します。 ネストされた関数内で自由変数を使うと、def 文の入っている 関数のローカル変数にアクセスすることができます。詳細は 4.1 節を参照してください。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 7.4 try 文 Up: 7. 複合文 (compound statement) Next: 7.6 クラス定義


7.6 クラス定義

クラス定義は、クラスオブジェクトを定義します ( 3.2 節参照):

classdef ::= "class" classname [inheritance] ":" suite
inheritance ::= "(" [expression_list] ")"
classname ::= identifier
Download entire grammar as text.

クラス定義は実行可能な文です。クラス定義では、まず継承リストがあれば それを評価します。継承リストの各要素の値評価結果はクラスオブジェクトで なければなりません。次にクラスのスイートが新たな実行フレーム内で、 新たなローカル名前空間と元々のグローバル名前空間を使って実行されます ( 4.1 節を参照してください)。 (通常、スイートには関数定義のみが含まれます) クラスのスイートを 実行し終えると、実行フレームは無視されますが、ローカルな 名前空間は保存されます。次に、基底クラスの継承リストを使って クラスオブジェクトが生成され、ローカルな名前空間を属性値辞書 として保存します。最後に、もとのローカルな名前空間において、クラス名が このクラスオブジェクトに束縛されます。

プログラマのための注釈: クラス定義内で定義された変数は クラス変数です; クラス変数は全てのインスタンス間で共有されます。 インスタンス変数を定義するには、__init__() メソッドや 他のメソッド中で変数に値を与えます。クラス変数もインスタンス変数も ``self.name'' 表記でアクセスすることができます。この表記で アクセスする場合、インスタンス変数は同名のクラス変数を隠蔽します。 変更不能な値をもつクラス変数は、インスタンス変数のデフォルト値と して使えます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 7.5 関数定義 Up: 7. 複合文 (compound statement) Next: 8. トップレベル要素


8. トップレベル要素

Python インタプリタは、標準入力や、プログラムの引数として与えられた スクリプト、対話的にタイプ入力された命令、モジュールのソースファイルな ど、様々な入力源から入力を得ることができます。この章では、それぞれの場 合に用いられる構文法について説明しています。

  • 8.1 完全な Python プログラム
  • 8.2 ファイル入力
  • 8.3 対話的入力
  • 8.4 式入力
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 7.6 クラス定義 Up: Python リファレンスマニュアル Next: 8.1 完全な Python プログラム


8.1 完全な Python プログラム

言語仕様の中では、その言語を処理するインタプリタがどのように起動される かまで規定する必要はないのですが、完全な Python プログラムについての概 念を持っておくと役に立ちます。完全な Python プログラムは、最小限に初期 化された環境: 全ての組み込み変数と標準モジュールが利用可能で、かつ sys (様々なシステムサービス)、__builtin__ (組み込み 関数、例外、および None)、__main__ の 3 つを除く全ての モジュールが初期化されていない状態で動作します。__main__ は、 完全なプログラムを実行する際に、ローカルおよびグローバルな名前空間を提 供するために用いられます。

完全な Python プログラムの構文は、下の節で述べるファイル入力の ためのものです。

インタプリタは、対話的モード (interactive mode) で起動されることもあり ます; この場合、インタプリタは完全なプログラムを読んで実行するのではな く、一度に単一の実行文 (複合文のときもあります) を読み込んで実行します。 初期状態の環境は、完全なプログラムを実行するときの環境と同じです; 各実 行文は、__main__ の名前空間内で実行されます。

Unix の環境下では、完全なプログラムをインタプリタに渡すには三通りの 方法があります: 第一は、 -c string コマンドラインオ プションを使う方法、第二はファイルを第一コマンドライン引数として指定す る方法、そして最後は標準入力から入力する方法です。ファイルや標準入力が tty (端末) デバイスの場合、インタプリタは対話モードに入ります; そうで ない場合、ファイルを完全なプログラムとして実行します。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 8. トップレベル要素 Up: 8. トップレベル要素 Next: 8.2 ファイル入力


8.2 ファイル入力

非対話的なファイルから読み出された入力は、全て同じ形式:

file_input ::= (NEWLINE | statement)*
Download entire grammar as text.

をとります。この構文法は、以下の状況で用いられます:

  • (ファイルや文字列内の) 完全な Python プログラムを構文解析するとき;

  • モジュールを構文解析するとき;

  • exec で渡された文字列を構文解析するとき;

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 8.1 完全な Python プログラム Up: 8. トップレベル要素 Next: 8.3 対話的入力


8.3 対話的入力

対話モードでの入力は、以下の文法の下に構文解析されます:

interactive_input ::= [stmt_list] NEWLINE | compound_stmt NEWLINE
Download entire grammar as text.

対話モードでは、(トップレベルの) 複合文の最後に空白行を入れなくてはな らないことに注意してください; これは、複合文の終端をパーザが検出するた めの手がかりとして必要です。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 8.2 ファイル入力 Up: 8. トップレベル要素 Next: 8.4 式入力


8.4 式入力

式入力には二つの形式があります。双方とも、先頭の空白を無視します。 eval() に対する文字列引数は、以下の形式をとらなければ なりません:

eval_input ::= expression_list NEWLINE*
Download entire grammar as text.

input() で読み込まれる入力行は、以下の形式をとらなければ なりません:

input_input ::= expression_list NEWLINE
Download entire grammar as text.

注意: 文としての解釈を行わない `生の (raw)' 入力行を読み出すためには、 組み込み関数 raw_input() や、ファイルオブジェクトの readline() メソッドを使うことができます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 8.3 対話的入力 Up: 8. トップレベル要素 Next: A. 歴史とライセンス


A. 歴史とライセンス

  • A.1 History of the software
  • A.2 Terms and conditions for accessing or otherwise using Python
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 8.4 式入力 Up: Python リファレンスマニュアル Next: A.1 History of the


A.1 History of the software

Python was created in the early 1990s by Guido van Rossum at Stichting Mathematisch Centrum (CWI, see http://www.cwi.nl/) in the Netherlands as a successor of a language called ABC. Guido remains Python's principal author, although it includes many contributions from others.

In 1995, Guido continued his work on Python at the Corporation for National Research Initiatives (CNRI, see http://www.cnri.reston.va.us/) in Reston, Virginia where he released several versions of the software.

In May 2000, Guido and the Python core development team moved to BeOpen.com to form the BeOpen PythonLabs team. In October of the same year, the PythonLabs team moved to Digital Creations (now Zope Corporation; see http://www.zope.com/). In 2001, the Python Software Foundation (PSF, see http://www.python.org/psf/) was formed, a non-profit organization created specifically to own Python-related Intellectual Property. Zope Corporation is a sponsoring member of the PSF.

All Python releases are Open Source (see http://www.opensource.org/ for the Open Source Definition). Historically, most, but not all, Python releases have also been GPL-compatible; the table below summarizes the various releases.

Release | Derived from | Year | Owner | GPL compatible?
0.9.0 thru 1.2 | n/a | 1991-1995 | CWI | yes
1.3 thru 1.5.2 | 1.2 | 1995-1999 | CNRI | yes
1.6 | 1.5.2 | 2000 | CNRI | no
2.0 | 1.6 | 2000 | BeOpen.com | no
1.6.1 | 1.6 | 2001 | CNRI | no
2.1 | 2.0+1.6.1 | 2001 | PSF | no
2.0.1 | 2.0+1.6.1 | 2001 | PSF | yes
2.1.1 | 2.1+2.0.1 | 2001 | PSF | yes
2.2 | 2.1.1 | 2001 | PSF | yes
2.1.2 | 2.1.1 | 2002 | PSF | yes
2.1.3 | 2.1.2 | 2002 | PSF | yes
2.2.1 | 2.2 | 2002 | PSF | yes
2.2.2 | 2.2.1 | 2002 | PSF | yes
2.2.3 | 2.2.2 | 2002-2003 | PSF | yes
2.3 | 2.2.2 | 2002-2003 | PSF | yes
2.3.1 | 2.3 | 2002-2003 | PSF | yes
2.3.2 | 2.3.1 | 2003 | PSF | yes

注意: GPL-compatible doesn't mean that we're distributing Python under the GPL. All Python licenses, unlike the GPL, let you distribute a modified version without making your changes open source. The GPL-compatible licenses make it possible to combine Python with other software that is released under the GPL; the others don't.

Thanks to the many outside volunteers who have worked under Guido's direction to make these releases possible.

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: A. 歴史とライセンス Up: A. 歴史とライセンス Next: A.2 Terms and conditions


A.2 Terms and conditions for accessing or otherwise using Python

PSF LICENSE AGREEMENT FOR PYTHON 2.3.3

  1. This LICENSE AGREEMENT is between the Python Software Foundation (``PSF''), and the Individual or Organization (``Licensee'') accessing and otherwise using Python 2.3.3 software in source or binary form and its associated documentation.

  2. Subject to the terms and conditions of this License Agreement, PSF hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python 2.3.3 alone or in any derivative version, provided, however, that PSF's License Agreement and PSF's notice of copyright, i.e., ``Copyright © 2001-2003 Python Software Foundation; All Rights Reserved'' are retained in Python 2.3.3 alone or in any derivative version prepared by Licensee.

  3. In the event Licensee prepares a derivative work that is based on or incorporates Python 2.3.3 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python 2.3.3.

  4. PSF is making Python 2.3.3 available to Licensee on an ``AS IS'' basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.3.3 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 2.3.3 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 2.3.3, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between PSF and Licensee. This License Agreement does not grant permission to use PSF trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party.

  8. By copying, installing or otherwise using Python 2.3.3, Licensee agrees to be bound by the terms and conditions of this License Agreement.

BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0

BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1

  1. This LICENSE AGREEMENT is between BeOpen.com (``BeOpen''), having an office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization (``Licensee'') accessing and otherwise using this software in source or binary form and its associated documentation (``the Software'').

  2. Subject to the terms and conditions of this BeOpen Python License Agreement, BeOpen hereby grants Licensee a non-exclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use the Software alone or in any derivative version, provided, however, that the BeOpen Python License is retained in the Software, alone or in any derivative version prepared by Licensee.

  3. BeOpen is making the Software available to Licensee on an ``AS IS'' basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  5. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  6. This License Agreement shall be governed by and interpreted in all respects by the law of the State of California, excluding conflict of law provisions. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between BeOpen and Licensee. This License Agreement does not grant permission to use BeOpen trademarks or trade names in a trademark sense to endorse or promote products or services of Licensee, or any third party. As an exception, the ``BeOpen Python'' logos available at http://www.pythonlabs.com/logos.html may be used according to the permissions granted on that web page.

  7. By copying, installing or otherwise using the software, Licensee agrees to be bound by the terms and conditions of this License Agreement.

CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1

  1. This LICENSE AGREEMENT is between the Corporation for National Research Initiatives, having an office at 1895 Preston White Drive, Reston, VA 20191 (``CNRI''), and the Individual or Organization (``Licensee'') accessing and otherwise using Python 1.6.1 software in source or binary form and its associated documentation.

  2. Subject to the terms and conditions of this License Agreement, CNRI hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python 1.6.1 alone or in any derivative version, provided, however, that CNRI's License Agreement and CNRI's notice of copyright, i.e., ``Copyright © 1995-2001 Corporation for National Research Initiatives; All Rights Reserved'' are retained in Python 1.6.1 alone or in any derivative version prepared by Licensee. Alternately, in lieu of CNRI's License Agreement, Licensee may substitute the following text (omitting the quotes): ``Python 1.6.1 is made available subject to the terms and conditions in CNRI's License Agreement. This Agreement together with Python 1.6.1 may be located on the Internet using the following unique, persistent identifier (known as a handle): 1895.22/1013. This Agreement may also be obtained from a proxy server on the Internet using the following URL: http://hdl.handle.net/1895.22/1013.''

  3. In the event Licensee prepares a derivative work that is based on or incorporates Python 1.6.1 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python 1.6.1.

  4. CNRI is making Python 1.6.1 available to Licensee on an ``AS IS'' basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  7. This License Agreement shall be governed by the federal intellectual property law of the United States, including without limitation the federal copyright law, and, to the extent such U.S. federal law does not apply, by the law of the Commonwealth of Virginia, excluding Virginia's conflict of law provisions. Notwithstanding the foregoing, with regard to derivative works based on Python 1.6.1 that incorporate non-separable material that was previously distributed under the GNU General Public License (GPL), the law of the Commonwealth of Virginia shall govern this License Agreement only as to issues arising under or with respect to Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between CNRI and Licensee. This License Agreement does not grant permission to use CNRI trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party.

  8. By clicking on the ``ACCEPT'' button where indicated, or by copying, installing or otherwise using Python 1.6.1, Licensee agrees to be bound by the terms and conditions of this License Agreement.

ACCEPT

CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2

Copyright © 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, The Netherlands. All rights reserved.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Stichting Mathematisch Centrum or CWI not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: A.1 History of the Up: A. 歴史とライセンス Next: B. 日本語訳について


B. 日本語訳について

  • B.1 このドキュメントについて
  • B.2 翻訳者一覧 (敬称略)
Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: A.2 Terms and conditions Up: Python リファレンスマニュアル Next: B.1 このドキュメントについて


B.1 このドキュメントについて

この文書は、Pythonドキュメント翻訳プロジェクトによる Python Language Reference の日本語訳版です。日本語訳に対する質問や提案などが ありましたら、Pythonドキュメント翻訳プロジェクトのメーリングリスト

http://www.python.jp/mailman/listinfo/python-doc-jp

または、プロジェクトのバグ管理ページ

http://sourceforge.jp/tracker/?atid=116&group_id=11&func=browse

までご報告ください。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: B. 日本語訳について Up: B. 日本語訳について Next: B.2 翻訳者一覧 (敬称略)


B.2 翻訳者一覧 (敬称略)

2.3.2 和訳 Yasushi Masuda <y.masuda at acm.org> (Feb 3, 2004)
2.3.3 差分 Yasushi Masuda (May 31, 2004)

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: B.1 このドキュメントについて Up: B. 日本語訳について Next: 索引


索引

_ | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | t | u | v | w | x | y | z

_ (アンダースコア)

__abs__() (numeric object のメソッド)
__add__() (numeric object のメソッド)
__add__() (sequence object method)
__all__ (optional module attribute)
__and__() (numeric object のメソッド)
__bases__ (class attribute)
__builtin__ (組み込み モジュール), [リンク]
__builtins__
__call__() (object method)
__call__() (object のメソッド)
__class__ (instance attribute)
__cmp__() (object method)
__cmp__() (object のメソッド)
__coerce__() (numeric object method)
__coerce__() (numeric object のメソッド)
__complex__() (numeric object のメソッド)
__contains__() (container object のメソッド)
__contains__() (mapping object method)
__contains__() (sequence object method)
__debug__
__del__() (object のメソッド)
__delattr__() (object のメソッド)
__delete__() (object のメソッド)
__delitem__() (container object のメソッド)
__delslice__() (sequence object のメソッド)
__dict__ (class attribute)
__dict__ (function attribute)
__dict__ (instance attribute), [リンク]
__dict__ (module attribute)
__div__() (numeric object のメソッド)
__divmod__() (numeric object のメソッド)
__doc__ (class attribute)
__doc__ (function attribute)
__doc__ (method attribute)
__doc__ (module attribute)
__eq__() (object のメソッド)
__file__ (module attribute)
__float__() (numeric object のメソッド)
__floordiv__() (numeric object のメソッド)
__ge__() (object のメソッド)
__get__() (object のメソッド)
__getattr__() (object のメソッド)
__getattribute__() (object のメソッド)
__getitem__() (container object のメソッド)
__getitem__() (mapping object method)
__getslice__() (sequence object のメソッド)
__gt__() (object のメソッド)
__hash__() (object のメソッド)
__hex__() (numeric object のメソッド)
__iadd__() (numeric object のメソッド)
__iadd__() (sequence object method)
__iand__() (numeric object のメソッド)
__idiv__() (numeric object のメソッド)
__ifloordiv__() (numeric object のメソッド)
__ilshift__() (numeric object のメソッド)
__imod__() (numeric object のメソッド)
__import__() (組み込み関数)
__imul__() (numeric object のメソッド)
__imul__() (sequence object method)
__init__() (object method)
__init__() (object のメソッド)
__init__.py
__int__() (numeric object のメソッド)
__invert__() (numeric object のメソッド)
__ior__() (numeric object のメソッド)
__ipow__() (numeric object のメソッド)
__irshift__() (numeric object のメソッド)
__isub__() (numeric object のメソッド)
__iter__() (container object のメソッド)
__iter__() (sequence object method)
__itruediv__() (numeric object のメソッド)
__ixor__() (numeric object のメソッド)
__le__() (object のメソッド)
__len__() (container object のメソッド)
__len__() (mapping object method)
__long__() (numeric object のメソッド)
__lshift__() (numeric object のメソッド)
__lt__() (object のメソッド)
__main__ (組み込み モジュール), [リンク], [リンク]
__metaclass__
__mod__() (numeric object のメソッド)
__module__ (class attribute)
__module__ (function attribute)
__module__ (method attribute)
__mul__() (numeric object のメソッド)
__mul__() (sequence object method)
__name__ (class attribute)
__name__ (function attribute)
__name__ (method attribute)
__name__ (module attribute)
__ne__() (object のメソッド)
__neg__() (numeric object のメソッド)
__nonzero__() (object method)
__nonzero__() (object のメソッド)
__oct__() (numeric object のメソッド)
__or__() (numeric object のメソッド)
__pos__() (numeric object のメソッド)
__pow__() (numeric object のメソッド)
__radd__() (numeric object のメソッド)
__radd__() (sequence object method)
__rand__() (numeric object のメソッド)
__rcmp__() (object のメソッド)
__rdiv__() (numeric object のメソッド)
__rdivmod__() (numeric object のメソッド)
__repr__() (object のメソッド)
__rfloordiv__() (numeric object のメソッド)
__rlshift__() (numeric object のメソッド)
__rmod__() (numeric object のメソッド)
__rmul__() (numeric object のメソッド)
__rmul__() (sequence object method)
__ror__() (numeric object のメソッド)
__rpow__() (numeric object のメソッド)
__rrshift__() (numeric object のメソッド)
__rshift__() (numeric object のメソッド)
__rsub__() (numeric object のメソッド)
__rtruediv__() (numeric object のメソッド)
__rxor__() (numeric object のメソッド)
__set__() (object のメソッド)
__setattr__() (object method)
__setattr__() (object のメソッド)
__setitem__() (container object のメソッド)
__setslice__() (sequence object のメソッド)
__slots__
__str__() (object のメソッド)
__sub__() (numeric object のメソッド)
__truediv__() (numeric object のメソッド)
__unicode__() (object のメソッド)
__xor__() (numeric object のメソッド)

A

abs() (組み込み関数)
addition
and
bit-wise
and 演算子
anonymous
function
append() (sequence object method)
argument
function
arithmetic
conversion
operation, binary
operation, unary
array (標準 モジュール)
ASCII, [リンク], [リンク], [リンク], [リンク], [リンク]
assert 実行文
AssertionError 例外
assignment
attribute, [リンク]
augmented
class attribute
class instance attribute
assignment (続き)
slicing
statement, [リンク]
subscription
target list
atom
attribute
assignment, [リンク]
assignment, class
assignment, class instance
class
class instance
deletion
generic special
reference
special
AttributeError 例外
augmented
assignment

B

back-quotes, [リンク]
backslash character
backward
quotes, [リンク]
binary
arithmetic operation
bit-wise operation
binding
global name
name, [リンク], [リンク], [リンク], [リンク], [リンク]
bit-wise
and
operation, binary
operation, unary
or
xor
blank line
block
block (続き)
code
BNF
Boolean
operation
Boolean オブジェクト
break 実行文, [リンク], [リンク], [リンク], [リンク]
bsddb (標準 モジュール)
built-in
method
module
built-in function
call
built-in function オブジェクト, [リンク]
built-in method
call
built-in method オブジェクト, [リンク]
byte
bytecode

C

C
language, [リンク], [リンク], [リンク]
call
built-in function
built-in method
class instance
class object, [リンク], [リンク], [リンク]
function, [リンク], [リンク]
instance, [リンク]
method
procedure
user-defined function
callable オブジェクト, [リンク]
chaining
comparisons
character, [リンク], [リンク]
character set
chr() (組み込み関数), [リンク]
class
attribute
attribute assignment
constructor
definition, [リンク]
instance
name
class instance
attribute
attribute assignment
call
class instance オブジェクト, [リンク], [リンク], [リンク]
class 実行文
class object
call, [リンク], [リンク], [リンク]
class オブジェクト, [リンク], [リンク], [リンク]
clause
clear() (mapping object method)
cmp() (組み込み関数)
co_argcount (code object attribute)
co_cellvars (code object attribute)
co_code (code object attribute)
co_consts (code object attribute)
co_filename (code object attribute)
co_firstlineno (code object attribute)
co_flags (code object attribute)
co_freevars (code object attribute)
co_lnotab (code object attribute)
co_name (code object attribute)
co_names (code object attribute)
co_nlocals (code object attribute)
co_stacksize (code object attribute)
co_varnames (code object attribute)
code
block
code block
code オブジェクト
comma
trailing, [リンク]
command line
comment
comparison
string
comparisons
chaining
compile() (組み込み関数)
complex
literal
number
complex() (組み込み関数)
complex オブジェクト
compound
statement
comprehensions
list, [リンク]
constant
constructor
class
container, [リンク]
continue 実行文, [リンク], [リンク], [リンク], [リンク]
conversion
arithmetic
string, [リンク], [リンク]
copy() (mapping object method)
count() (sequence object method)

D

dangling
else
data
type
type, immutable
datum
dbm (標準 モジュール)
decimal literal
DEDENT token, [リンク]
def 実行文
default
parameter value
definition
class, [リンク]
function, [リンク]
del 実行文, [リンク], [リンク]
delete
deletion
attribute
target
target list
delimiters
destructor, [リンク]
dictionary
display
dictionary オブジェクト, [リンク], [リンク], [リンク], [リンク], [リンク]
display
dictionary
list
tuple
division
divmod() (組み込み関数), [リンク]
documentation string

E

EBCDIC
elif
予約語
Ellipsis オブジェクト
else
dangling
予約語, [リンク], [リンク], [リンク], [リンク]
empty
list
tuple, [リンク]
environment
演算子
and
in
is
is not
not
not in
or
error handling
errors
escape sequence
eval() (組み込み関数), [リンク], [リンク]
evaluation
order
exc_info (in module sys)
exc_traceback (in module sys), [リンク]
exc_type (in module sys)
exc_value (in module sys)
except
予約語
exception, [リンク]
handler
raising
exception handler
exclusive
or
exec 実行文, [リンク]
execfile() (組み込み関数)
execution
frame, [リンク]
restricted
stack
execution model
expression
lambda
list, [リンク], [リンク]
statement
extend() (sequence object method)
extended
slicing
extended print statement
extended slicing
extension
filename
module

F

f_back (frame attribute)
f_builtins (frame attribute)
f_code (frame attribute)
f_exc_traceback (frame attribute)
f_exc_type (frame attribute)
f_exc_value (frame attribute)
f_globals (frame attribute)
f_lasti (frame attribute)
f_lineno (frame attribute)
f_locals (frame attribute)
f_restricted (frame attribute)
f_trace (frame attribute)
False
file オブジェクト, [リンク]
filename
extension
finally
予約語, [リンク], [リンク], [リンク]
float() (組み込み関数)
floating point
number
floating point literal
floating point オブジェクト
for 実行文, [リンク], [リンク]
form
lambda, [リンク]
frame
execution, [リンク]
frame オブジェクト
free
variable, [リンク]
from
予約語, [リンク]
from 実行文, [リンク]
func_closure (function attribute)
func_code (function attribute)
func_defaults (function attribute)
func_dict (function attribute)
func_doc (function attribute)
func_globals (function attribute)
function
anonymous
argument
call, [リンク], [リンク]
call, user-defined
definition, [リンク]
generator
name
user-defined
function オブジェクト, [リンク], [リンク], [リンク], [リンク]
future
statement

G

garbage collection
gdbm (標準 モジュール)
generator
function, [リンク]
iterator, [リンク]
generator オブジェクト
generic
special attribute
get() (mapping object method)
global
name binding
namespace
global 実行文, [リンク], [リンク]
globals() (組み込み関数)
grammar
grouping

H

handle an exception
handler
exception
has_key() (mapping object method)
hash character
hex() (組み込み関数)
hexadecimal literal
hierarchical
module names
hierarchy
type

I

id() (組み込み関数)
identifier, [リンク]
identity
test
identity of an object
if 実行文
im_class (method attribute), [リンク]
im_func (method attribute), [リンク], [リンク], [リンク]
im_self (method attribute), [リンク], [リンク]
imaginary literal
immutable
data type
object, [リンク]
immutable object
immutable オブジェクト
immutable sequence オブジェクト
import 実行文, [リンク]
ImportError 例外, [リンク]
in
予約語
in 演算子
inclusive
or
INDENT token
indentation
index() (sequence object method)
index operation
indices() (slice のメソッド)
inheritance
initialization
module
input
raw
input() (組み込み関数)
insert() (sequence object method)
instance
call, [リンク]
class
instance オブジェクト, [リンク], [リンク], [リンク]
int() (組み込み関数)
integer
representation
integer literal
integer オブジェクト
interactive mode
internal type
interpreter
inversion
invocation
is 演算子
is not 演算子
item
sequence
string
item selection
items() (mapping object method)
iteritems() (mapping object method)
iterkeys() (mapping object method)
itervalues() (mapping object method)

J

Java
language
実行文
assert
break, [リンク], [リンク], [リンク], [リンク]
class
continue, [リンク], [リンク], [リンク], [リンク]
def
del, [リンク], [リンク]
exec, [リンク]
for, [リンク], [リンク]
from, [リンク]
実行文 (続き)
global, [リンク], [リンク]
if
import, [リンク]
pass
print, [リンク]
raise
return, [リンク], [リンク]
try, [リンク]
while, [リンク], [リンク]
yield

K

key
key/datum pair
keys() (mapping object method)
keyword

L

lambda
expression
form, [リンク]
language
C, [リンク], [リンク], [リンク]
Java
Pascal
last_traceback (in module sys)
leading whitespace
len() (組み込み関数), [リンク], [リンク]
lexical analysis
lexical definitions
line continuation
line joining, [リンク]
line structure
list
assignment, target
comprehensions, [リンク]
list (続き)
deletion target
display
empty
expression, [リンク], [リンク]
target, [リンク]
list オブジェクト, [リンク], [リンク], [リンク], [リンク], [リンク]
literal, [リンク]
locals() (組み込み関数)
logical line
long() (組み込み関数)
long integer literal
long integer オブジェクト
loop
over mutable sequence
statement, [リンク], [リンク], [リンク]
loop control
target

M

makefile() (socket method)
mangling
name
mapping オブジェクト, [リンク], [リンク], [リンク]
membership
test
method
built-in
call
user-defined
method オブジェクト, [リンク], [リンク]
minus
module
built-in
extension
importing
initialization
module (続き)
name
names, hierarchical
namespace
search path
user-defined
module オブジェクト, [リンク]
modules (in module sys)
modulo
multiplication
mutable object
mutable オブジェクト, [リンク], [リンク]
mutable sequence
loop over
mutable sequence オブジェクト

N

name, [リンク], [リンク]
binding, [リンク], [リンク], [リンク], [リンク], [リンク]
binding, global
class
function
mangling
module
rebinding
unbinding
NameError (built-in exception)
NameError 例外
names
hierarchical module
private
namespace
global
module
negation
newline
suppression
NEWLINE token, [リンク]
\textttNone オブジェクト
None, [リンク]
not 演算子
not in 演算子
notation
\textttNotImplemented オブジェクト
NotImplemented
null
operation
number
complex
floating point
numeric literal
numeric オブジェクト, [リンク]

O

object
immutable, [リンク]
オブジェクト
Boolean
built-in function, [リンク]
built-in method, [リンク]
callable, [リンク]
class, [リンク], [リンク], [リンク]
class instance, [リンク], [リンク], [リンク]
code
complex
dictionary, [リンク], [リンク], [リンク], [リンク], [リンク]
Ellipsis
file, [リンク]
floating point
frame
function, [リンク], [リンク], [リンク], [リンク]
generator
immutable
immutable sequence
instance, [リンク], [リンク], [リンク]
integer
list, [リンク], [リンク], [リンク], [リンク], [リンク]
long integer
mapping, [リンク], [リンク], [リンク]
method, [リンク], [リンク]
module, [リンク]
mutable, [リンク], [リンク]
mutable sequence
\textttNone
\textttNotImplemented
numeric, [リンク]
plain integer
オブジェクト (続き)
recursive
sequence, [リンク], [リンク], [リンク], [リンク], [リンク], [リンク]
slice
string, [リンク], [リンク]
traceback, [リンク], [リンク]
tuple, [リンク], [リンク], [リンク]
unicode
user-defined function, [リンク], [リンク]
user-defined method
oct() (組み込み関数)
octal literal
open() (組み込み関数)
operation
binary arithmetic
binary bit-wise
Boolean
null
shifting
unary arithmetic
unary bit-wise
operator
overloading
precedence
operators
or
bit-wise
exclusive
inclusive
or 演算子
ord() (組み込み関数), [リンク], [リンク]
order
evaluation
output, [リンク]
standard, [リンク]
OverflowError (built-in exception)
overloading
operator

P

packages
parameter
value, default
parenthesized form
parser
Pascal
language
pass 実行文
path
module search
physical line, [リンク], [リンク]
plain integer literal
plain integer オブジェクト
plus
pop() (mapping object method)
pop() (sequence object method)
popen() (in module os)
popitem() (mapping object method)
pow() (組み込み関数), [リンク], [リンク], [リンク]
precedence
operator
primary
print 実行文, [リンク]
private
names
procedure
call
program

Q

quotes
backward, [リンク]
quotes (続き)
reverse, [リンク]

R

raise an exception
raise 実行文
raising
exception
range() (組み込み関数)
raw input
raw_input() (組み込み関数)
readline() (file method)
rebinding
name
recursive オブジェクト
reference
attribute
reference counting
例外
AssertionError
AttributeError
ImportError, [リンク]
NameError
例外 (続き)
RuntimeError
StopIteration
SyntaxError
TypeError
ValueError
ZeroDivisionError
remove() (sequence object method)
repr() (組み込み関数), [リンク], [リンク]
representation
integer
reserved word
restricted
execution
return 実行文, [リンク], [リンク]
reverse
quotes, [リンク]
reverse() (sequence object method)
RuntimeError 例外

S

scope, [リンク]
search
path, module
sequence
item
sequence オブジェクト, [リンク], [リンク], [リンク], [リンク], [リンク], [リンク]
setdefault() (mapping object method)
shifting
operation
simple
statement
singleton
tuple
slice
slice() (組み込み関数)
slice オブジェクト
slicing, [リンク], [リンク]
assignment
extended
sort() (sequence object method)
space
special
attribute
attribute, generic
stack
execution
trace
standard
output, [リンク]
Standard C
standard input
start (slice object attribute), [リンク]
statement
assignment, [リンク]
assignment, augmented
compound
expression
future
loop, [リンク], [リンク], [リンク]
simple
statement grouping
stderr (in module sys)
stdin (in module sys)
stdio
stdout (in module sys), [リンク]
step (slice object attribute), [リンク]
stop (slice object attribute), [リンク]
StopIteration 例外
str() (組み込み関数), [リンク]
string
comparison
conversion, [リンク], [リンク]
item
Unicode
string literal
string オブジェクト, [リンク], [リンク]
subscription, [リンク], [リンク], [リンク]
assignment
subtraction
suite
suppression
newline
syntax, [リンク]
SyntaxError 例外
sys (組み込み モジュール), [リンク], [リンク], [リンク]
sys.exc_info
sys.exc_traceback
sys.last_traceback
sys.modules
sys.stderr
sys.stdin
sys.stdout
SystemExit (built-in exception)

T

tab
target
deletion
list, [リンク]
list assignment
list, deletion
loop control
tb_frame (traceback attribute)
tb_lasti (traceback attribute)
tb_lineno (traceback attribute)
tb_next (traceback attribute)
termination model
test
identity
membership
token
trace
stack
traceback オブジェクト, [リンク], [リンク]
trailing
comma, [リンク]
triple-quoted string
True
try 実行文, [リンク]
tuple
display
empty, [リンク]
singleton
tuple オブジェクト, [リンク], [リンク], [リンク]
type
data
hierarchy
immutable data
type() (組み込み関数)
type of an object
TypeError 例外
types, internal

U

unary
arithmetic operation
bit-wise operation
unbinding
name
UnboundLocalError
unichr() (組み込み関数)
Unicode
unicode() (組み込み関数), [リンク]
Unicode Consortium
unicode オブジェクト
UNIX
unreachable object
unrecognized escape sequence
update() (mapping object method)
user-defined
function
function call
method
module
user-defined function オブジェクト, [リンク], [リンク]
user-defined method オブジェクト

V

value
default parameter
value of an object
ValueError 例外
values
writing, [リンク]
values() (mapping object method)
variable
free, [リンク]

W

while 実行文, [リンク], [リンク]
whitespace
writing
values, [リンク]

X

xor
bit-wise

Y

yield 実行文
予約語
elif
else, [リンク], [リンク], [リンク], [リンク]
except
予約語 (続き)
finally, [リンク], [リンク], [リンク]
from, [リンク]
in

Z

ZeroDivisionError 例外

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents
Previous: B.2 翻訳者一覧 (敬称略) Up: Python リファレンスマニュアル Next: この文書について...


Macintoshモジュールリファレンス

Guido van Rossum

PythonLabs
Email: docs@python.org

Fred L. Drake, Jr., editor

リリース 2.3.3
平成16年6月28日

日本語訳: Python ドキュメント翻訳プロジェクト

  • 序
  • 目次
  • 1. Mac OS 9でPythonを利用する
    • 1.1 MacPython-OSXの取得とインストール
      • 1.1.1 Pythonスクリプト実行方法
      • 1.1.2 GUIを利用したスクリプトの実行
      • 1.1.3 設定
    • 1.2 MacPython-OS9の取得とインストール
      • 1.2.1 対話型インタプリタを使う
      • 1.2.2 Pythonスクリプトの走らせ方
      • 1.2.3 コマンドライン引数をシミュレートする
      • 1.2.4 Pythonスクリプトを作成する
      • 1.2.5 設定を行なう
    • 1.3 統合開発環境
      • 1.3.1 ``Python Interactive''ウィンドウを使う
      • 1.3.2 Pythonスクリプトを書く
      • 1.3.3 統合開発環境の中からスクリプトを実行する
      • 1.3.4 ``Save as''対``Save as Applet''
  • 2. MacPython モジュール
    • 2.1 mac -- os モジュールの実装
    • 2.2 macpath -- MacOS のパス操作関数
    • 2.3 macfs -- 各種のファイルシステムのサービス
      • 2.3.1 FSSpecオブジェクト
      • 2.3.2 エイリアスオブジェクト
      • 2.3.3 FInfoオブジェクト
    • 2.4 ic -- インターネット設定へのアクセス
      • 2.4.1 ICオブジェクト
    • 2.5 MacOS -- Mac OS インタプリタ機能へのアクセス
    • 2.6 macostools -- ファイル操作に便利なルーチン
    • 2.7 findertools -- finderのApple Eventsインターフェース
    • 2.8 EasyDialogs -- 基本的なMacintoshダイアログ
      • 2.8.1 プログレスバーオブジェクト
    • 2.9 FrameWork -- 対話型アプリケーション・フレームワーク
      • 2.9.1 アプリケーションオブジェクト
      • 2.9.2 ウィンドウオブジェクト
      • 2.9.3 コントロールウィンドウオブジェクト
      • 2.9.4 スクロールウィンドウオブジェクト
      • 2.9.5 ダイアログウィンドウオブジェクト
    • 2.10 autoGIL -- イベントループ中のグローバルインタープリタの取り扱い
  • 3. MacPython OSA モジュール
    • 3.1 gensuitemodule -- OSA スタプ作成パッケージ
    • 3.2 aetools -- OSA クライアントのサポート
    • 3.3 aepack -- Python変数とAppleEventデータコンテナ間の変換
    • 3.4 aetypes -- AppleEvent オブジェクト
    • 3.5 MiniAEFrame -- オープンスクリプティングアーキテクチャサーバのサポート
      • 3.5.1 AEServer オブジェクト
  • 4. MacOS ツールボックスモジュール
    • 4.1 Carbon.AE -- Apple Events
    • 4.2 Carbon.AH -- Apple ヘルプ
    • 4.3 Carbon.App -- アピアランスマネージャ
    • 4.4 Carbon.CF -- Core Foundation
    • 4.5 Carbon.CG -- Core Graphics
    • 4.6 Carbon.CarbonEvt -- Carbon Event Manager
    • 4.7 Carbon.Cm -- Component Manager
    • 4.8 Carbon.Ctl -- Control Manager
    • 4.9 Carbon.Dlg -- Dialog Manager
    • 4.10 Carbon.Evt -- Event Manager
    • 4.11 Carbon.Fm -- Font Manager
    • 4.12 Carbon.Folder -- Folder Manager
    • 4.13 Carbon.Help -- Help Manager
    • 4.14 Carbon.List -- List Manager
    • 4.15 Carbon.Menu -- Menu Manager
    • 4.16 Carbon.Mlte -- MultiLingual Text Editor
    • 4.17 Carbon.Qd -- QuickDraw
    • 4.18 Carbon.Qdoffs -- QuickDraw Offscreen
    • 4.19 Carbon.Qt -- QuickTime
    • 4.20 Carbon.Res -- Resource Manager and Handles
    • 4.21 Carbon.Scrap -- Scrap Manager
    • 4.22 Carbon.Snd -- Sound Manager
    • 4.23 Carbon.TE -- TextEdit
    • 4.24 Carbon.Win -- Window Manager
    • 4.25 ColorPicker -- 色選択ダイアログ
  • 5. 文書化されていないモジュール
    • 5.1 applesingle -- AppleSingle デコーダー
    • 5.2 buildtools -- BuildAppletとその仲間のヘルパーモジュール
    • 5.3 py_resource -- Python コードからのリソース生成
    • 5.4 cfmfile -- コードフラグメントリソースを扱うモジュール
    • 5.5 icopen -- open()と Internet Config の置き換え
    • 5.6 macerrors -- MacOSのエラー
    • 5.7 macresource -- スクリプトのリソースを見つける
    • 5.8 Nav -- NavServices の呼出し
    • 5.9 mkcwproject -- CodeWarrior プロジェクトの作成
    • 5.10 nsremote -- Netscape OSAモジュールのラッパー
    • 5.11 PixMapWrapper -- PixMapオブジェクトのラッパー
    • 5.12 preferences -- アプリケーション初期設定管理プログラム
    • 5.13 pythonprefs -- Python の初期設定管理プログラム
    • 5.14 quietconsole -- 不可視の標準出力
    • 5.15 videoreader -- QuickTime ムービーの読み込み
    • 5.16 W -- FrameWork 上に作られたウイジェット
    • 5.17 waste -- Apple製ではない TextEdit の置き換え
  • A. 歴史とライセンス
    • A.1 History of the software
    • A.2 Terms and conditions for accessing or otherwise using Python
  • B. 日本語訳について
    • B.1 このドキュメントについて
    • B.2 翻訳者一覧 (敬称略)
  • Module Index
  • 索引
  • この文書について...
Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Up: Python ドキュメントインデクス Next: 序


1. Mac OS 9でPythonを利用する

Macintosh 上での Python の使い方は、特にMac OS 9上においては Unixラ イクなシステムや Windows システム上で使うのと全く異なっています (MacPython-OSXは完全な Unix Python を含んでいるため Unixライクな システムとほぼ同じ知識が利用できます) 。ほとんどの Python 文書や、 ``公式''文書、出版された本のたぐいも、Unixライクなシステムや Windows システム上でどう Python を使うかについて述べているにすぎず、 Python を利用するのは MacPython-OS9 が初めてという人が混乱する原因になってい ます。この章では、簡単な入門編として Macintosh 上で Python を具体的に どう使うのかを解説していきます。

IDEについての章(1.3章参照)はMacPython-OSXでも利用できます。

  • 1.1 MacPython-OSXの取得とインストール
    • 1.1.1 Pythonスクリプト実行方法
    • 1.1.2 GUIを利用したスクリプトの実行
    • 1.1.3 設定
  • 1.2 MacPython-OS9の取得とインストール
    • 1.2.1 対話型インタプリタを使う
    • 1.2.2 Pythonスクリプトの走らせ方
      • 1.2.2.1 ドラッグ＆ドロップする
      • 1.2.2.2 クリエータをセットしてダブルクリックする
    • 1.2.3 コマンドライン引数をシミュレートする
    • 1.2.4 Pythonスクリプトを作成する
      • 1.2.4.1 エディタでスクリプトを作成
      • 1.2.4.2 Pythonモード付きのエディタ
      • 1.2.4.3 BBedit
    • 1.2.5 設定を行なう
      • 1.2.5.1 EditPythonPrefs
      • 1.2.5.2 モジュール検索パスにモジュールを追加する
      • 1.2.5.3 デフォルトの起動オプション
  • 1.3 統合開発環境
    • 1.3.1 ``Python Interactive''ウィンドウを使う
    • 1.3.2 Pythonスクリプトを書く
    • 1.3.3 統合開発環境の中からスクリプトを実行する
    • 1.3.4 ``Save as''対``Save as Applet''
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 目次 Up: Macintoshモジュールリファレンス Next: 1.1 MacPython-OSXの取得とインストール


1.1 MacPython-OSXの取得とインストール

Python 2.3a2 の時点で、自分のマシンにMacPython-OSXをインストールする唯 一確実な方法はソース配布物を取得し、"framework Python"と呼ばれるものを 自分で構築する事です。構築方法の詳細は Mac/OSX/README に記述さ れています。

バイナリインストーラーが利用可能になりしだい、詳細が http://www.cwi.nl/&#126;jack/macpython.html に掲示され るでしょう。

多くのものがインストールされます。

  • Applications フォルダ中に MacPython-2.3フォルダが作 成されます。このフォルダ中に、PythonIDE 統合開発環境、ファインダ からのダブルクリックで Python スクリプトを起動するための PythonLauncher、そして Package Manager が含まれています。

  • 標準 Unix コマンドライン Python インタプリタが /usr/local/bin/python にインストールされます。しかし、 /usr/local/lib/python は除きます。

  • 全ての機能の実体として /Library/Frameworks/Python.framework にフレームワークがインストールされます。しかし、普通はこの事を知っ ている必要はありません。

MacPython をアンインストールするには、単にこの3つを削除するだけです。

PythonIDEは、そのヘルプメニューからアクセスすることができる "MacPython Help" と呼ばれる Apple ヘルプビューア書類を含んでいます。Python にまっ たく不慣れなら、そのドキュメント中の IDE 入門を読み始めるのが良いでしょ う。

他の Unix プラットフォーム上の Python に精通しているなら、Unix シェルからの Python スクリプトの実行についてのセクションを読むのが良い でしょう。

  • 1.1.1 Pythonスクリプト実行方法
  • 1.1.2 GUIを利用したスクリプトの実行
  • 1.1.3 設定
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1. Mac OS 9でPythonを利用する Up: 1. Mac OS 9でPythonを利用する Next: 1.1.1 Pythonスクリプト実行方法


1.1.1 Pythonスクリプト実行方法

Mac OS X 上で Python を始めるには PythonIDE 統合開発環境に触れてみるの が最良の方法です。章 1.3 を見るか、IDE が起動しているならヘルプ メニューから呼び出せる Apple ヘルプビューア書類の IDE 入門を読みながら IDE に触れてみてください。

ターミナルウィンドウのコマンドライン、あるいはファインダから Python スクリプトを実行したければ、スクリプトを作成するために最初にエディタ が必要になるでしょう。Mac OS X には、vi および emacs など多くの標準 Unix コマンドラインエディタが付属し ます。もし Mac らしいエディタを利用したいなら Bare Bones Software (http://www.barebones.com/products/bbedit/index.shtml) の BBEdit か TextWrangler が良いでしょう。フリーウェ アの BBEdit Lite の公式サポートは中止されましたが、まだ利用 可能です。AppleWorks や他のワードプロセッサで ASCII としてファ イルを保存できる物なら利用可能ですが、TextEdit はデフォルト では.rtf フォーマットで保存してしまうので、そのままでは利用しない 方がいいでしょう。

ターミナルウィンドウから自作のスクリプトを起動するにはシェルの検索パス に /usr/local/bin を /usr/bin よりも前に設定する必要があ ります。これを設定しないと Apple 提供の Python が起動されてしまいます。 (Mac OS X 10.2.4時点では Python 2.2です)

ファインダから自作スクリプトを実行するには、2種類方法があります。

  • PythonLauncher にドラックする
  • ファインダの情報ウィンドウで自作スクリプト(もしくはいずれかの .py スクリプト)の「このアプリケーションで開く」の設定のデフォルトを PythonLauncher にして、スクリプトをダブルクリックする。

PythonLauncherは、あなたのスクリプトをどのように起動するかコントロール するための様々な設定ができます。オプションを押しながらドラッグするとそ の実行においてのみ設定の変更がされます。また変更をずっと反映させるため には PythonLauncher の設定メニューから変更してください。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.1 MacPython-OSXの取得とインストール Up: 1.1 MacPython-OSXの取得とインストール Next: 1.1.2 GUIを利用したスクリプトの実行


1.1.2 GUIを利用したスクリプトの実行

Mac OS X では Aqua ウィンドウマネージャに依存するプログラム(言いかえれ ば GUI を持っているものすべて) は特別な方法で起動する必要がある事を知っ ておく必要があります。GUIを持ったスクリプトを実行するには python のかわりに pythonw を利用してください。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.1.1 Pythonスクリプト実行方法 Up: 1.1 MacPython-OSXの取得とインストール Next: 1.1.3 設定


1.1.3 設定

MacPython は、PYTHONPATH のような標準 Unix 環境変数をすべ て利用しますが、ファインダは自作の .profile や .cshrc を 読まないので、ファインダから起動するプログラムのためにこれらの変数を設 定することは非標準です。ファインダのためには ~ /.MacOSX/environment.plist ファイルを作成する必要があります。詳細に 関しては Apple Technical Document QA1067を見てください。

追加の Python パッケージのインストールは、パッケージマネージャによっ てかなり簡単にできます。詳細は MacPython ヘルプを見てください。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.1.2 GUIを利用したスクリプトの実行 Up: 1.1 MacPython-OSXの取得とインストール Next: 1.2 MacPython-OS9の取得とインストール


1.2 MacPython-OS9の取得とインストール

最新リリースは、今後現われる実験的な新版と同様に、Jack Jansenにより運 営されている MacPythonページ： http://homepages.cwi.nl/~jack/macpython.html で見 つかります。

使い方に関する最新情報は、配布物に含まれる README を参照してく ださい。

MacPython-OS9 は Mac OS X 上で正常に起動しますし、クラシック環境の中で はなくネイティブモードで起動します。それでも、CFM に基づいたPython を 必要とする特別な理由がない限り、Mac OS X 上でMacPython-OSX を利用しな い理由にはなりません。

  • 1.2.1 対話型インタプリタを使う
  • 1.2.2 Pythonスクリプトの走らせ方
    • 1.2.2.1 ドラッグ＆ドロップする
    • 1.2.2.2 クリエータをセットしてダブルクリックする
  • 1.2.3 コマンドライン引数をシミュレートする
  • 1.2.4 Pythonスクリプトを作成する
    • 1.2.4.1 エディタでスクリプトを作成
    • 1.2.4.2 Pythonモード付きのエディタ
    • 1.2.4.3 BBedit
  • 1.2.5 設定を行なう
    • 1.2.5.1 EditPythonPrefs
    • 1.2.5.2 モジュール検索パスにモジュールを追加する
    • 1.2.5.3 デフォルトの起動オプション
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.1.3 設定 Up: 1. Mac OS 9でPythonを利用する Next: 1.2.1 対話型インタプリタを使う


1.2.1 対話型インタプリタを使う

Python ドキュメントで使われている対話型インタプリタは、 PythonInterpreter アイコンをダブルクリックすると起動します。 アイコンは16トンの重りが落ちてきたように見えるものになっています。 1.1バージョン情報と ">>> " プロンプトが表示されるはずです。これは 標準ドキュメントに書かれているそのままに使えます。

... アイコンは16トンの重りが落ちてきたように見えるものになっています。1.1
訳注：なぜアイコンが16トンの重りなのかを疑問に思うかもしれません。 これは Monty Python's Flying Circus に由来します。Monty Python's Flying Circus を見てみるとよいでしょう。
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.2 MacPython-OS9の取得とインストール Up: 1.2 MacPython-OS9の取得とインストール Next: 1.2.2 Pythonスクリプトの走らせ方


1.2.2 Pythonスクリプトの走らせ方

既に手元にある Python スクリプトを走らせるにはいくつかの方法があります。 普通は、``ドラッグ＆ドロップする''か``ダブルクリックする''か、この２つ の方法のいずれかを使います。他にも、IDE(節 1.3 を参照)の中から走 らせるとか、AppleScript 経由で起動する方法があります。

  • 1.2.2.1 ドラッグ＆ドロップする
  • 1.2.2.2 クリエータをセットしてダブルクリックする
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.2.1 対話型インタプリタを使う Up: 1.2 MacPython-OS9の取得とインストール Next: 1.2.2.1 ドラッグ＆ドロップする


1.2.3 コマンドライン引数をシミュレートする

MacPython-OS9 でコマンドライン引数をシミュレートするには２つの方法があります。

  1. インタプリタオプション経由
    • スクリプトを起動する時、オプションキーを押す。こうするとPython インタプリタオプションのダイアログボックスが現われます。
    • ``Set Unix-style command line..''ボタンをクリックする。
    • ``Argument''フィールドに引数をタイプする。
    • ``OK''をクリックする。
    • ``Run''をクリックする。

  2. ドロップ＆ドロップ経由。スクリプトをアプレットとして保存した場合には (節 1.3.4 を参照)、 ``ドラッグ＆ドロップ''経由でコマンド引数 もシミュレートできます。この場合、アプレットにドロップされたファイルの 名前は sys.argv に追加され、スクリプトからはコマンドラインでタ イプされたように見えます。Unix システムでのように、sys.srgv の第一項目は、アプレットへのパスになり、残りの項目はアプレットにドロッ プされたファイルです。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.2.2.2 クリエータをセットしてダブルクリックする Up: 1.2 MacPython-OS9の取得とインストール Next: 1.2.4 Pythonスクリプトを作成する


1.2.4 Pythonスクリプトを作成する

Python スクリプトは単純なテキストファイルなので、テキストファイルが作 れるならどのような方法でも作成可能です。しかし、他にも特徴を供えた専用 ツールもあります。

  • 1.2.4.1 エディタでスクリプトを作成
  • 1.2.4.2 Pythonモード付きのエディタ
  • 1.2.4.3 BBedit
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.2.3 コマンドライン引数をシミュレートする Up: 1.2 MacPython-OS9の取得とインストール Next: 1.2.4.1 エディタでスクリプトを作成


1.2.5 設定を行なう

MacPython 配布物には、作業を円滑に行なうために MacPython 環境をカスタ マイズするのを助けるアプレット EditPythonPrefs が付属します。

  • 1.2.5.1 EditPythonPrefs
  • 1.2.5.2 モジュール検索パスにモジュールを追加する
  • 1.2.5.3 デフォルトの起動オプション
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.2.4.3 BBedit Up: 1.2 MacPython-OS9の取得とインストール Next: 1.2.5.1 EditPythonPrefs


1.3 統合開発環境

Python IDE(統合開発環境)は独立したアプリケーションで、Python コードのテキストエディタや、クラスブラウザ、グラフィカルデバッガなどとし て動作します。

  • 1.3.1 ``Python Interactive''ウィンドウを使う
  • 1.3.2 Pythonスクリプトを書く
  • 1.3.3 統合開発環境の中からスクリプトを実行する
  • 1.3.4 ``Save as''対``Save as Applet''
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.2.5.3 デフォルトの起動オプション Up: 1. Mac OS 9でPythonを利用する Next: 1.3.1 ``Python Interactive''ウィンドウを使う


1.3.1 ``Python Interactive''ウィンドウを使う

``ドラッグ＆ドロップ''の手法を使えない以外は、このウィンドウは PythonInterpreter と同様に使えます。通常のドラッグ＆ドロップ の代わりに、スクリプトをPython IDE アイコンの上にドロップす ると、別々なスクリプトウィンドウでファイルが開かれます(こうすると手動 で実行させることができます - 節 1.3.3を参照)。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.3 統合開発環境 Up: 1.3 統合開発環境 Next: 1.3.2 Pythonスクリプトを書く


1.3.2 Pythonスクリプトを書く

Python IDE は、対話的に使うだけでなく、Python プログラムを書 き上げ、順次保存したり、全体や一部分を実行したりすることもできます。

新たにスクリプトを作成したり、前に保存したスクリプトを開いたり、 ``File''メニューの適当なメニューアイテムを選択することで、現在開いてい るスクリプトを保存することもできます。 Python スクリプトを Python IDE の上にドロップすると、ファイルが開いて編集可能に なります。

スクリプトを Python IDE で開きたいが ``Open''ダイアログボッ クスから場所を特定できない時や、``Can't open file of type ...''のよう なエラーメッセージが出る時は、節 1.2.2 を参照してください。

Python IDE がスクリプトを保存する時に使われるクリエータコー ドの設定は、ドキュメントウィンドウの一番右上の小さな黒い三角形をクリッ クすると見つかり、``save options''を選択することで設定できます。デフォ ルトではファイルのクリエータコードは Python IDE になります。 つまり保存されたファイルのアイコンダブルクリックするとそのまま IDE で 編集できます。PythonInterpreter で開いて実行するように、こ の動作を変えたい時もあるでしょう。そうするには単に``save options''から ``Python Interpreter''を選べば良いだけです。こうしたオプションは ファイル単位の設定であり、アプリケーション単位の設定でないこと に注意してください。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.3.1 ``Python Interactive''ウィンドウを使う Up: 1.3 統合開発環境 Next: 1.3.3 統合開発環境の中からスクリプトを実行する


1.3.3 統合開発環境の中からスクリプトを実行する

Python IDEの最前面のウィンドウで全部実行(run all)ボタンを押 すと、そのウィンドウのスクリプトを実行できます。しかし、もし Python の 習慣通りに "if __name__ == "__main__":" と書いても、スクリプトは デフォルトでは``__main__''に ならない ことを知っておいてくださ い。そういう風に動作させるには、ドキュメントウィンドウの一番右上の小さ な黒い三角形から、``Run as __main__''オプションを選ばなくてはいけませ ん。こうしたオプションは ファイル単位 の設定であって、アプリケー ション単位でないことに注意してください。ただし、このオプションは、保存した後で も そのまま でありつづけます。これをオフにするには、単にもう一 度選択すればよいだけです。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.3.2 Pythonスクリプトを書く Up: 1.3 統合開発環境 Next: 1.3.4 ``Save as''対``Save as


1.3.4 ``Save as''対``Save as Applet''

Python スクリプトを書き終わったら、``applet''として保存することもでき ます(``File''メニューの``Save as applet''を選択する)。こうする重要なメ リットは、できあがったアプレットの上にファイルやフォルダをドロップする と、スクリプトに対してコマンドライン風に引数として渡すことができる点に あります。ただし、アプレットを別ファイルとして保存するように気をつけて、 くれぐれもせっかく作ったスクリプトを上書きしないようにしてください。そ うしてしまうと、再度編集できなくなってしまいます。

``ドラッグ＆ドロップ''経由でアプレットに渡された項目にアクセスするため には、標準的な sys.argv の動作を使えばよいです。詳しい説明は Pythonの標準ドキュメントを見てください。

スクリプトをアプレットとして保存しても、 Python がインストールされてい ないシステムでは実行できないことに注意してください。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.3.3 統合開発環境の中からスクリプトを実行する Up: 1.3 統合開発環境 Next: 2. MacPython モジュール


2. MacPython モジュール

このドキュメントで記述されている次のモジュールは、いずれもMacintoshで のみ利用可能です。

mac | os モジュールの実装
macpath | MacOS のパス操作関数
macfs | FSSpec、エイリアスマネージャ、finderエイリアス、標準ファイル パッケージのサポート。
ic | インターネット設定へのアクセス。
MacOS | Mac OS 固有のインタープリタ機能へのアクセス。
macostools | ファイル操作に便利なルーチン。
findertools | finderのApple Eventsインターフェースのラッパー。
EasyDialogs | 基本的なMacintoshダイアログ。
FrameWork | 対話型アプリケーション・フレームワーク
autoGIL | イベントループ中のグローバルインタープリタの取り扱い

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.3.4 ``Save as''対``Save as Up: Macintoshモジュールリファレンス Next: 2.1 mac


2.1 mac -- os モジュールの実装

利用可能な条件: Macintosh.

このモジュールは、標準モジュール osでサポー トされるのと同様の機能を、Mac OS 9 オペレーティングシステムに依存した 機能として実装しています。このモジュールを利用する一番良い使い方は posix モジュール経由で使うことです。このモジュールは MacPython-OS9 にのみ存在し、MacPython-OSX 上では posix を利 用します。

このモジュールでは次の関数が使えます。
chdir()、
close()、
dup()、
fdopen()、
getcwd()、
lseek()、
listdir()、
mkdir()、
open()、
read()、
rename()、
rmdir()、
stat()、
sync()、
unlink()、
write()、
そして例外 error も定義されています。stat() に
より返される時間は浮動小数点数で、 MacPython-OS9 で使われる他の時間の
値と同様です。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2. MacPython モジュール Up: 2. MacPython モジュール Next: 2.2 macpath


2.2 macpath -- MacOS のパス操作関数

このモジュールは os.path モジュールの Macintosh 実装です。こ のモジュールで、os.pathへの最も汎用性 のあるアクセスができます。os.path のドキュメントに関しては、 Python Library Referenceを参照してくだ さい。

次の関数がこのモジュールで利用できます。
normcase()、
normpath()、
isabs()、
join()、
split()、
isdir()、
isfile()、
walk()、
exists()。
os.path で利用できる他の関数については、ダミーの関数として相
当する物が利用できます。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.1 mac Up: 2. MacPython モジュール Next: 2.3 macfs


2.3 macfs -- 各種のファイルシステムのサービス

利用可能な条件: Macintosh.

リリース 2.3 以降で撤廃された仕様です。 macfsモジュールは旧式のものです。FSSpec、FSRef、 Aliasの代わりにCarbon.FileあるいはCarbon.Folderを使用し てください。ファイルダイアログにはEasyDialogsを使用してください。

このモジュールはMacintosh FSSpecの操作、エイリアスマネージャ、finder エイリアス、標準ファイルパッケージへのアクセスを提供します。

関数やメソッドがfile引数をとる所では、引数は次の3つのうちのどれか1 つです。つまり、 (1) Macintoshのフルパス名あるいは部分パス名、(2) FSSpecオブジェクト、(3) Inside Macintosh: Filesに記述され た3要素のタプル(wdRefNum, parID, name)。 それを含むフォルダが存在する限り、FSSpecは存在しないファイルを示 すこともできます。 MacPythonではパス名も同じように使用できますが、パス名とFSRefsの働きの違 いのため、unix-Pythonでは異なります。詳しくはAppleの文書を参照してくださ い。

エイリアスと標準ファイルパッケージの詳細についてもその文書に書かれていま す。

FSSpec( file)
指定したファイルに対するFSSpecオブジェクトを作成します。

RawFSSpec( data)
文字列としてFSSpecのC構造体の生データを与えるとFSSpec オブジェクトを作成します。主にFSSpec構造体をネットワーク経由で得 る場合に便利です。

RawAlias( data)
文字列としてエイリアスのC構造体を生データとして与えるとAlias オブジェクトを作成します。主にFSSpec構造体をネットワーク経由で得 る場合に便利です。

FInfo( )
ゼロで埋めたFInfoオブジェクトを作成します。

ResolveAliasFile( file)
エイリアスファイルを解決します(オリジナルのファイルとの対応を取りま す)。3要素のタプル(fsspec, isfolder, aliased)を返します。ここでfsspecは解決後の FSSpecオブジェクト、もしf sspecがフォルダを指していた らisfolderはtrue、もしエイリアスだったらaliasedはtrue(そ うでなければファイルそのもののFSSpecオブジェクトが返されます)で す。

StandardGetFile( [type, ...])
ユーザに標準的な``入力ファイルを開く''ダイアログを提示します。オプション として、4つまでの4文字のファイルタイプを渡すことができて、ユーザーが選ぶ ファイルを制限することができます。この関数はFSSpecオブジェクト と、ユーザがキャンセルしないでダイアログを完了したかを示すフラグを返しま す。

PromptGetFile( prompt[, type, ...])
StandardGetFile()とほぼ同じですが、ダイアログの一番上に表示さ れるプロンプトを指定できます。

StandardPutFile( prompt[, default])
ユーザに標準的な``出力ファイルを開く''ダイアログを提示します。 promptはプロンプト文字列で、省略可能なdefault引数で出力 ファイル名の初期値を指定します。この関数はFSSpecオブジェクト と、ユーザがキャンセルしないでダイアログを完了したかを示すフラグを返 します。

GetDirectory( [prompt])
ユーザに非標準的な``ディレクトリを選ぶ''ダイアログを提示します。 ``select current directory''ボタンをクリックするときには、選んだディ レクトリを開いていなくてはなりません。promptはプロンプト文字列 で、ダイアログの一番上に表示されます。FSSpecオブジェクトと、 ユーザがキャンセルしないでダイアログを完了したかを示すフラグを返しま す。

SetFolder( [fsspec])
ファイル選択ダイアログを提示する時に、最初に表示されるフォルダをセッ トします。fsspecで指定するのはそのフォルダにあるファイルであっ て、フォルダそのものではありません(指定されたファイルは存在していな くても構いません)。もし引数を渡さない場合は、フォルダはカレントディ レクトリ、つまり os.getcwd()で返されるディレクトリにセッ トされます。

システム7.5から``一般設定''コントロールパネルで、ユーザが標準ファイ ルパッケージの振る舞いを変えられることに注意してください。その設定し だいでこの関数の呼びだしは効果がなくなります。

FindFolder( where, which, create)
MacOSが管理する``特別な''フォルダ、例えばゴミ箱や初期設定フォルダな どの位置を探しだします。whereは検索するディスク、whichは 探し出すフォルダを指定する4文字の文字列です。createをセットす ると、そのフォルダが存在しなければ新たに生成します。 (vrefnum, dirid)のタプルを返します。

whereとwhichに与える定数は、標準モジュール Carbon.Foldersにあります。

NewAliasMinimalFromFullPath( pathname)
与えられたファイルを指す最短のaliasオブジェクトを返します。 ファイルはフルパス名で与えなければなりません。これは存在しないファイ ルを指すAliasを作成する唯一の方法です。

FindApplication( creator)
4文字のクリエータコードcreatorを持ったアプリケーションの位置を 探し出します。この関数はアプリケーションを指すFSSpecオブジェ クトを返します。

  • 2.3.1 FSSpecオブジェクト
  • 2.3.2 エイリアスオブジェクト
  • 2.3.3 FInfoオブジェクト
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.2 macpath Up: 2. MacPython モジュール Next: 2.3.1 FSSpecオブジェクト


2.3.1 FSSpecオブジェクト

data
FSSpecオブジェクトの生データで、例えば他のアプリケーションに渡す場合に適 しています。

as_pathname( )
FSSpecで記述されたファイルのフルパス名を返します。

as_tuple( )
FSSpecオブジェクトで記述されたファイルの (wdRefNum, parID, name)のタプルを返します。

NewAlias( [file])
このFSSpecで記述されたファイルのエイリアスオブジェクトを作成します。 省略可能なfileパラメータを渡すと、エイリアスはそのファイルに対 する相対指定で作成され、その他の場合は絶対指定となります。

NewAliasMinimal( )
このファイルを指す最短エイリアスを作成します。

GetCreatorType( )
このファイルの4文字のクリエータとタイプを返します。

SetCreatorType( creator, type)
このファイルに4文字のクリエータとタイプを設定します。

GetFInfo( )
ファイルのファインダ情報を示すFInfoオブジェクトを返します。

SetFInfo( finfo)
ファイルのファインダ情報をfinfo(FInfoオブジェクト)で与えた 値に設定します。

GetDates( )
作成日、修正日、バックアップ日を意味する3つの浮動小数点数からなるタプル を返します。

SetDates( crdate, moddate, backupdate)
ファイルの作成日、修正日、バックアップ日を設定します。各々の値はPythonシ ステム全体で標準的な浮動小数点数フォーマットです。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.3 macfs Up: 2.3 macfs Next: 2.3.2 エイリアスオブジェクト


2.3.2 エイリアスオブジェクト

data
Aliasレコードの生データで、リソースに書き込む時や他のプログラムに転送す る時に適しています。

Resolve( [file])
エイリアスを解決します。もしエイリアスが相対エイリアスとして作成され ていた場合は、相対指定の起点となるファイルを渡す必要があります。指定 先のファイルのFSSpecと、Aliasオブジェクト自体が検索途中で修 正されたかどうかのフラグを返します。もしファイルが存在しなくてそのファ イルまでのパスが存在すれば、正しいFSSpecが返されます。

GetInfo( num)
CのルーチンGetAliasInfo()へのインターフェース。

Update( file[, file2])
与えられたfileを指すエイリアスを更新します。もしfile2引 数があれば、相対エイリアスが作成されます。

今のところ、リソースをAliasオブジェクトとして直接操作すること は出来ません。そのため、Update()を呼んだ後か、 Resolve()でエイリアスに変更があったと分かった後は、Pythonプロ グラムが責任もって Aliasオブジェクトからdataの値を取 りだして、リソースを修正する必要があります。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.3.1 FSSpecオブジェクト Up: 2.3 macfs Next: 2.3.3 FInfoオブジェクト


2.3.3 FInfoオブジェクト

各々のフィールドが何を意味するかはInside Macintosh: Filesに 完全に記述されているので、そちらを参照してください。

Creator
ファイルの4文字のクリエータコード。

Type
ファイルの4文字のタイプコード。

Flags
ファイルのファインダフラグを16ビットの整数で表現したもの。 Flagsのビット値は、標準モジュールMACFSで定義されてい ます。

Location
ファイルのアイコンがフォルダの中で配置される位置。

Fldr
ファイルがあるフォルダ(整数表現)。
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.3.2 エイリアスオブジェクト Up: 2.3 macfs Next: 2.4 ic


2.4 ic -- インターネット設定へのアクセス

利用可能な条件: Macintosh.

このモジュールはMacintoshのインターネット設定パッ ケージへのアクセスを提供します。このパッケージにはインターネットプログラ ムの設定、例えばメールアドレス、デフォルトのホームページなどが保存されてい ます。 それ以外にもインターネット設定はMacintoshのクリエータ／タイプとファイル 名の拡張子との対応付けや、ファイルの転送方法(バイナリ、アスキーなど)に関す る情報を含んでいます。 MacOS 9以降では、このモジュールは``インターネット''という名前のコント ロールパネルになりました。

icglueという低レベルの関連モジュールが あって、このモジュールはインターネット設定の基本的なアクセス機能を提供し ています。 この低レベルモジュールは文書化されていませんが、ルーチンのdocstringでパ ラメータが説明されていますし、ルーチン名はインターネット設定にあるPascal やCのAPIと同じなので、このモジュールを使う場合はICプログラマーのため の標準的な文書が利用できます。

icモジュールは例外errorと、インターネット設定から生 じる全てのエラーコードに対するシンボル名を定義しています。詳細はソースを 参照してください。

exception error
icモジュール内部のエラーで発生した例外。

icモジュールは以下のクラスと関数を定義しています：

class IC( [signature[, ic]])
インターネット設定オブジェクトを作成します。signatureは、現在のア プリケーションの4文字のクリエータ(デフォルトは'Pyth')で、他のICの 設定に影響する可能性があります。オプションの引数icはあらかじめ作成さ れた低レベルのicglue.icinstanceで、別の設定ファイルなどから設定を得 る場合に便利です。

launchurl( url[, hint])
parseurl( data[, start[, end[, hint]]])
mapfile( file)
maptypecreator( type, creator[, filename])
settypecreator( file)
これらの関数は、後述する同名のメソッドへの``ショートカット''です。

  • 2.4.1 ICオブジェクト
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.3.3 FInfoオブジェクト Up: 2. MacPython モジュール Next: 2.4.1 ICオブジェクト


2.4.1 ICオブジェクト

ICオブジェクトは対応付けのインターフェースを持っているので、メー ルアドレスは単にic['MailAddress']で得ることができます。値の 代入も機能しますし、設定ファイルのオプションを変えることができます。

このモジュールは各種のデータ型を知っているので、IC内部の表現を``論理的'' なPythonデータ構造に変換します。icモジュールをスタンドアロン で実行するとテストプログラムが実行され、ICデータベースにある全てのキーと 値のペアをリスト表示するので、文書代わりになります。

もしこのモジュールがデータをどう表わすか分からない場合は、data 属性に生のデータを入れたICOpaqueDataタイプのインスタンスを返しま す。このタイプのオブジェクトは値のアクセスだけでなく代入も可能です。

ディクショナリのインターフェースだけでなく、ICには以下のメソッド があります。

launchurl( url[, hint])
与えられたURLを解析し、正しいアプリケーションを起動してURLを渡します。省 略可能なhintは、'mailto:'などのスキーム名で、不完全なURLはこ のスキームにあわせて完全化されます。もしhintが与えられていない場合 は、不完全なURLは無効になります。

parseurl( data[, start[, end[, hint]]])
dataの中からURLを検索して、URLの開始位置、終了位置、URLそのものを 返します。省略可能なstartとendで検索範囲を制限することができ ます。例えば、ユーザーが長いテキストフィールドをクリックしたとしても、テ キストフィールド全体とクリック位置startを渡すことができて、この ルーチンによってユーザーがクリックしたテキストからURL全体が返されます。 既に述べたように、hintはオプションのスキームで、不完全なURLを完全 化するために使われます。

mapfile( file)
与えられたfileに対するマッピングエントリーを返します。fileと してファイル名かmacfs.FSSpec()の結果を渡すことができて、存在 しないファイルであってもかまいません。

マッピングエントリーはタプル(version, type, creator, postcreator, flags, extension, appname, postappname, mimetype, entryname) として返されます。ここでversionはエントリーのバージョン番号、 typeは4文字のファイルタイプ、creatorは4文字のクリエータタ イプ、postcreatorは省略可能な後処理用アプリケーションを示す4文字 のクリエータで、このアプリケーションはファイルをダウンロードした後にファ イルを後処理します。flagsは各種のビットであり、転送をバイナリで 行うかアスキーで行うかなどを表わします。extensionはこのファイルタ イプに対するファイル名の拡張子、appnameはファイルが属するアプリ ケーションの出力可能な名前、postappnameは後処理用アプリケーショ ン、mimetypeはこのファイルのMIMEタイプ、最後のentrynameは このエントリーの名前です。

maptypecreator( type, creator[, filename])
与えられた4文字のtypeとcreatorを持つファイルに対するマッピン グエントリーを返します。正しいエントリーが見つかりやすいように、オプショ ンのfilenameを指定することもできます(例えばクリエータ'????' の場合など)。

マッピングエントリーはmapfileと同じフォーマットで返されます。

settypecreator( file)
存在するfileをファイル名かmacfs.FSSpec()の結果として与 えると、拡張子から判断してクリエータとタイプを適切にセットします。ファイ ンダにこの変更が伝えられるので、ファインダのアイコンは即座に更新されま す。
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.4 ic Up: 2.4 ic Next: 2.5 MacOS


2.5 MacOS -- Mac OS インタプリタ機能へのアクセス

利用可能な条件: Macintosh.

このモジュールは、Python インタプリタ内の MacOS 固有の機能に対するアク セスを提供します。例えば、インタプリタのイベントループ関数などです。十 分注意して利用してください。

モジュール名が大文字で始まることに注意してください。これは昔からの約束 です。

runtimemodel
'carbon' か 'macho' のいずれかです。現在利用している Python が Mac OS X および Mac OS 9互換性をもつ CarbonLib 形式、あるい は Mac OS X のみの Mach-O 形式をのどちらであるか判断できます。Python の初期のバージョンでは、値がさらに古い Mac OS 8 ランタイムモデル用の 'ppc' である事があります。

linkmodel
インタープリタがどのような方法でリンクされているかを返します。拡張モ ジュールがリンクモデル間で非互換性かもしれない場合、パッケージはより多 くの適切なエラーメッセージを伝えるためにこの情報を使用することができま す。値は静的リンクした Python は 'static'、Mac OS X framework で構築した Python は 'framework'、標準の unix 共有ライブラリ (shared library)で構築された Python は 'shared'、Mac OS 9 互換 Python では 'cfm' となります。

exception Error
MacOS でエラーがあると、このモジュールの関数か、Mac 固有なツールボック スインターフェースモジュールから、この例外が生成されます。引数は、整数 エラーコード(OSErr 値)とテキストで記述されたエラーコードです。 分かっている全てのエラーコードのシンボル名は、標準モジュール macerrorsで定義されています。

SetEventHandler( handler)
内部のインタプリタループでは、ScheduleParams() で止めないか ぎり、Python は時々イベントをチェックします。イベントがある場合は、こ の関数を使うと、Pythonイベントハンドラ関数を渡せます。イベントはパラメー タとして渡され、イベントが完全に処理された場合は、ハンドラ関数は非ゼロ を返さなくてはなりません。それ以外はイベント処理は継続されます(例えば、 イベントをコンソールウィンドウパッケージ渡すなど)。

イベントハンドラをクリアするには、パラメータなしで SetEventHandler() を呼び出します。既にイベントハンドラがセッ トされているのに、さらにセットしようとするとエラーになります。

有効性：MacPython-OS9

SchedParams( [doint[, evtmask[, besocial[, interval[, bgyield]]]]])

これはインタプリタの内部ループイベントハンドラに影響を与えます。 Interval は、インタプリタがどれだけの頻度(浮動小数点数の秒で表わさ れる)でイベント処理コードに入るかを指定します。真なら doint は割 り込み(コマンドドット)チェックが行われます。evtmask はインタプリ タに、イベントをマスクして (再描画、他のアプリケーションに切り替わるマ ウスクリックなど)イベント処理するよう指示します。besocial フラグは、 他のプロセスが動作するチャンスを与えます。Python が最前面で動いている 時は、最小限の実行時間が割り当てられ、Python が背景にある場合は、 interval 当りに bgyield 秒が与えられます。

全てのパラメータはオプションで、現在の値がデフォルト値となります。この 関数で返される値は、これらのオプションの既存の値からなるタプルです。デ フォルトの初期値は、全ての処理がオンで、チェックは 1/4 秒毎、バックグ ラウンドで動作している場合はプロセッサも 1/4 秒毎に割り当てられます。

最も一般的な使用ケースは完全にインタープリタメインループ中の処理をで きなくするために SchedParams(0, 0) を呼ぶことです。

有効性：MacPython-OS9

HandleEvent( ev)

イベントレコード ev を Python のイベントループに渡す、というより は、sys.stdout ウィンドウ(Pythonをビルドしたコンパイラにもとづ いて) のハンドラに渡されることになります。こうすると、Python プログラ ムが独自のイベント処理を行え、コマンドピリオドやウィンドウの切り替えが 行えます。

SetEventHandler() でセットしたイベントハンドラからこの関数 を呼びだそうとすると、例外が生じます。

有効性：MacPython-OS9

GetErrorString( errno)

MacOSのエラーコード errno のテキスト表現を返します。

splash( resid)

この関数は、resid で与えた DLOG リソースの内容で、スプラッシュウィ ンドウを画面に表示します。引数なしで呼びだすと、スプラッシュ画面を取り 除きます。拡張モジュールをたくさんロードさせる前に、初期化のタイミング でアプレットにスプラッシュ画面を表示させたいときに、この関数が便利でしょ う。

有効性：MacPython-OS9

DebugStr( message [, object])

Mac OS 9上では、メッセージ message を出してローレベルデバッガに 入ります。オプションの object 引数は使われませんが、デバッガから 内容を容易に検査することができます。Mac OS X 上では 文字列が単に stderr に印字されます。

この関数を使うときは十分気を付けてください。MacsBug などのローレベルデ バッガがインストールされていない場合は、システムがクラッシュしてしまい ます。この関数は主に Python 拡張モジュールの開発者のために用意されてい ます。

SysBeep( )

ベルを鳴らします。

GetTicks( )

システム起動時からのチック数(clock ticks、1/60秒)を得ます。

GetCreatorAndType( file)

2つの4文字の文字列としてファイルクリエータおよびファイルタイプを返しま す。file 引数はパスもしくは、FSSpec、FSRef オブジェ クトを与える事ができます。

SetCreatorAndType( file, creator, type)

ファイルクリエータおよびファイルタイプを設定します。file 引数は パスもしくは、FSSpec、FSRef オブジェクトを与える事ができ ます。creator と type は4文字の文字列が必要です。

openrf( name [, mode])

ファイルのリソースフォークを開きます。引数は組み込み関数 open() と同じです。返されたオブジェクトはファイルのように 見えるかもしれませんが、これは Python のファイルオブジェクトではあり ませんので扱いに微妙な違いがあります。

WMAvailable( )

現在のプロセスが動作しているウィンドウマネージャにアクセスします。例え ば、Mac OS X サーバー上、あるいは SSH でログインしている、もしくは現在 のインタープリタがフルブローンアプリケーションバンドル(fullblown application bundle)から起動されていない場合などのような、ウィンドウマネー ジャが存在しない場合は False を返します。

Mac OS 9 上ではこの関数はつねに True を返します。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.4.1 ICオブジェクト Up: 2. MacPython モジュール Next: 2.6 macostools


2.6 macostools -- ファイル操作に便利なルーチン

利用可能な条件: Macintosh.

このモジュールには、Macintosh上のファイル操作のための便利なルーチンがい くつか含まれています。ファイルのパラメータは全てパス名、あるいは FSRefかFSSpecオブジェクトで指定します。

macostoolsモジュールには以下の関数が定義されています。

copy( src, dst[, createpath[, copytimes]])
ファイルsrcをdstへコピーします。 createpathが非ゼロなら、必要に応じてdstに至るまでのフォルダ を作成します。 このメソッドはデータとリソースフォークとファインダ情報をいくつか(クリ エータ、タイプ、フラグ)をコピーします。オプションで作成日、修正日、バッ クアップ日の情報もコピーします(デフォルトでこれらもコピーします)。カスタ ムアイコン、コメント、アイコン位置はコピーされません。

copytree( src, dst)
必要に応じてフォルダを作成しながら、srcからdstへ再帰的にファ イルのツリーをコピーします。srcとdstはパス名で指定しなければ なりません。

mkalias( src, dst)
srcを示すファインダエイリアスdstを作成します。

touched( dst)
ファイルdstのクリエータやタイプなどのファインダ情報が変わったこと をファインダに知らせます。 ファイルはパス名かFSSpecで指定できます。この呼び出しによってアイ コンを再描画するようファインダに指示します。

BUFSIZ
copyに用いるバッファサイズで、デフォルトは1メガバイトです。

ファインダエイリアスの作成プロセスは、Appleの文書で明らかにされていませ ん。そのため、mkalias()で作成されたエイリアスは互換性のない振 る舞いをすることもあることに注意してください。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.5 MacOS Up: 2. MacPython モジュール Next: 2.7 findertools


2.7 findertools -- finderのApple Eventsインターフェース

利用可能な条件: Macintosh.

このモジュールのルーチンを使うと、Pythonプログラムからファインダが持つい くつかの機能へアクセスできます。 これらの機能はファインダへのAppleEventインターフェー スのラッパーとして実装されています。 全てのファイルとフォルダのパラメータは、フルパス名、あるいは FSRefかFSSpecオブジェクトで指定できます。

findertoolsモジュールは以下の関数を定義しています。

launch( file)
ファインダにfileを起動するように命令します。 起動が意味するものはfileに依存します。アプリケーションなら起動しま すし、フォルダなら開かれ、文書なら適切なアプリケーションで開かれます。

Print( file)
ファインダにファイルを印刷するよう命令します。 実際の動作はファイルを選択し、ファインダのファイルメニューから印刷コマン ドを使うのと同じです。

copy( file, destdir)
ファインダにファイルかフォルダであるfileをフォルダdestdirに コピーするよう命令します。 この関数は新しいファイルを示すAliasオブジェクトを返します。

move( file, destdir)
ファインダにファイルかフォルダであるfileをフォルダdestdirに 移動するように命令します。 この関数は新しいファイルを示すAliasオブジェクトを返します。

sleep( )
マシンがサポートしていれば、ファインダにMacintoshをスリープさせるよう命 令します。

restart( )
ファインダに、マシンが適切にリスタートするよう命令します。

shutdown( )
ファインダに、マシンが適切にシャットダウンするよう命令します。
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.6 macostools Up: 2. MacPython モジュール Next: 2.8 EasyDialogs


2.8 EasyDialogs -- 基本的なMacintoshダイアログ

利用可能な条件: Macintosh.

EasyDialogsモジュールはMacintoshの単純なダイアログを含んでいま す。 全てのルーチンは省略可能なリソースIDのパラメータidをとり、対応する ダイアログアイテム（タイプとアイテム番号）があれば、このidによっ てダイアログ用のDLOGリソースを上書きできます。詳細については ソースを参照してください。

EasyDialogsモジュールには以下の関数が定義されています。

Message( str[, id[, ok=None]])
メッセージテキストstr付きのモーダルダイアログを表示します。テキス トの長さは最大255文字です。 ボタンのテキストはデフォルトでは``OK''ですが、文字列の引数okが与え られると、その文字列に設定できます。 ユーザが``OK''ボタンをクリックすると、ユーザにコントロールが渡されます。

AskString( prompt[, default[, id[, ok[, cancel]]]])
ユーザに文字列値を入力するよう要求するモーダルダイアログ表示します。 promptはプロンプトメッセージで、省略可能なdefault引数は入力 文字列の初期値です（指定されないなら""が使われます）。 ``OK''と``Cancel''ボタンの文字列はokとcancelの引数で変える ことができます。 文字列の長さは全て最大255文字です。 AskString()は入力された文字列を返し、ユーザがキャンセルした 場合はNoneを返します。

AskPassword( prompt[, default[, id[, ok[, cancel]]]])
ユーザに文字列を入力するように要求するモーダルダイアログを表示します。 AskString()に似ていますが、テキストは点で表示されます。 引数はAskString()のものと同じ意味です。

AskYesNoCancel( question[, default[, yes[, no[, cancel[, id]]]]])
プロンプトquestionと``Yes''、``No''、``Cancel''というラベルの3つ ボタンが付いたダイアログを表示します。 ``Yes''を押したら1、``No''なら0、``Cancel''なら-1 を返します。 RETURNキーを押した場合はdefaultの値（defaultが設定さ れていないなら0）を返します。 ボタンのテキストはyes、no、cancelの引数で変更できます 。ボタンを表示させないためにはその引数に""を与えます。

ProgressBar( [title[, maxval[, label[, id]]]])
プログレスバー付きのモードレスダイアログを表示します。 これは後述のProgressBarクラスのためのコンストラクタです。 titleは表示されるテキスト文字列（デフォルトは``Working...''）で、 maxvalは進行が完了するときの値（デフォルトは0で、不定量の 作業が残っていることを示します）、labelはプログレスバーの上に表示 されるテキストです。

GetArgv( [optionlist[ commandlist[, addoldfile[, addnewfile[, addfolder[, id]]]]]])
コマンドライン引数のリストを作るのを補助するダイアログを表示します。 引数をgetopt.getopt()に渡すのに適したsys.argvのフォー マットのリストを返します。 addoldfile、addnewfile、addfolderの引数はブーリアン型 の引数です。 これらが非ゼロなら、存在するファイル、まだ（おそらく）存在しないファイ ル、フォルダをコマンドラインのパスとしてそれぞれ設定できます。 （注意：getopt.getopt()で認識されるために、オブションの引数は コマンドラインの中でファイルとフォルダの引数の前に示されなければなりませ ん。） 空白を含む引数は、空白をシングルクォートあるいはダブルクォートで囲んで 指定できます。

ユーザが``Cancel''ボタンを押したらSystemExit例外が発生しま す。

optionlistはポップアップメニューを示すリストで、ユーザはその中から 選択できます。 ポップアップメニューのアイテムは次の2つの形のうちの1つです。optstr あるいは(optstr, descr)。 descrは短い説明の文字列で、これがあるとポップアップメニューから選 択されている間、ダイアログに表示されます。 optstrとコマンドライン引数の対応は以下の通りです。

optstr format | Command-line format
x | -x （短いオプション）
x:あるいはx= | -x （値を持つ短いオプション）
xyz | --xyz （長いオプション）
xyz:あるいはxyz= | --xyz （値を持つ長いオプション）

commandlistはcmdstrあるいは(cmdstr, descr)の形のアイテムからなるリストで、descrは前述のよ うに働きます。cmdstrはポップアップメニューに表示されます。選択さ れるとcmdstrがコマンドラインに追加されますが、それに続く ":"あるいは"="は（もし存在するなら）取り除かれます。

バージョン2.0 以降で新規追加された 仕様です。

AskFileForOpen( [message][, typeList][, defaultLocation][, defaultOptionFlags][, location][, clientName][, windowTitle][, actionButtonLabel][, cancelButtonLabel][, preferenceKey][, popupExtension][, eventProc][, previewProc][, filterProc][, wanted])
開くファイルをユーザに尋ねるダイアログを表示して、選択されたファイ ルあるいはユーザがキャンセルしたらNoneを返します。 messageは表示するテキストメッセージで、typeListは選択 可能にする4文字のファイルタイプのリスト、defaultLocationは最 初に表示すルフォルダのパスネームでFSSpecあるいはFSRefで指定します。 locationはダイアログを表示するスクリーン上の位置の(x, y)で、 actionButtonLabelはOKボタンの位置に``Open''の代わり に表示する文字列、cancelButtonLabelは``Cancel''ボタンの位置 に``Cancel''の代わりに表示する文字列、wantedは返したい値のタ イプでstring、unicode、AFSSpec、 FSRefとそれらのサブタイプを指定できます。

その他の引数の説明についてはApple Navigation Servicesのドキュメントと EasyDialogsのソースコードを参照してください。

AskFileForSave( [message][, savedFileName][, defaultLocation][, defaultOptionFlags][, location][, clientName][, windowTitle][, actionButtonLabel][, cancelButtonLabel][, preferenceKey][, popupExtension][, fileType][, fileCreator][, eventProc][, wanted])
保存するファイルをユーザに尋ねるダイアログを表示して、選択されたファイ ルあるいはユーザがキャンセルしたらNoneを返します。 savedFileNameは保存するファイルのデフォルトの名前（であり、返され る値）です。 その他の引数の説明についてはAskFileForOpenを参照してください。

AskFolder( [message][, defaultLocation][, defaultOptionFlags][, location][, clientName][, windowTitle][, actionButtonLabel][, cancelButtonLabel][, preferenceKey][, popupExtension][, eventProc][, filterProc][, wanted])
選択するフォルダをユーザに尋ねるダイアログを表示して、選択されたフォルダ あるいはユーザがキャンセルしたらNoneを返します。 引数についての説明はAskFileForOpenを参照してください。

  • 2.8.1 プログレスバーオブジェクト
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.7 findertools Up: 2. MacPython モジュール Next: 2.8.1 プログレスバーオブジェクト


2.8.1 プログレスバーオブジェクト

ProgressBarオブジェクトはモードレスプログレスバーの土台を提供し ます。 定量プログレスインジケータ（温度計スタイル）と不定量プログレスインジケ ータ（床屋さんのぐるぐる看板のスタイル）が使用できます。 プログレスバーは最大値がゼロより大きければ定量インジケータに、そうでな いなら不定量インジケータになります。 バージョン2.2 以降で変更された 仕様: 不定量プログレスインジケータが追加されました

ダイアログは作られるとすぐに表示されます。 ダイアログの``Cancel''ボタンが押されるか、Cmd-. (コマンドキーを押しながらピリオド.を押す)かESCがタイ プされるとダイアログウィンドウは隠され、KeyboardInterruptが 発生します（しかし、この反応はプログレスバーが次にアップデートされるまで 、つまりinc()かset()の呼び出しによって次にアップデー トされるまで発生しません）。 それ以外は、プログレスバーはProgressBarオブジェクトが捨てられる まで表示されたままになります。

ProgressBarオブジェクトには以下の属性とメソッドがあります。

curval
プログレスバーの現在の値（整数型あるいはロング整数型）。 プログレスバーの通常のアクセスのメソッドによってcurvalを 0とmaxvalの間にします。 この属性は直接変更すべきではありません。

maxval
プログレスバーの最大の値（整数型あるいはロング整数型。curval がmaxvalに等しい時にはプログレスバー（温度計スタイル）は最大値 を示します。 もしmaxvalが0なら、プログレスバーは不定量インジケータ（ 床屋さんのぐるぐる看板）です。 この属性は直接変更すべきではありません。

title( [newstr])
プログレスバーのダイアログのタイトルバーのテキストをnewstrに設定 します。

label( [newstr])
プログレスバーのダイアログのプログレスボックスのテキストをnewstr に設定します。

set( value[, max])
プログレスバーの現在値curvalをvalueに設定し、もし maxが指定されたらmaxvalをmaxにします。 valueは初めに0とmaxvalの間に強制的に設定されます。 温度計スタイルのバーは変化を反映して更新され、また不定量インジケータも 定量インジケータへ、あるいはその逆も起こります。

inc( [n])
プログレスバーのcurvalをnだけ増やし、nが指定されな いなら1だけ増やします。 （nは負でもかまいません。その場合は減少します。） プログレスバーは変化を反映してアップデートされます。 もしプログレスバーが不定量インジケータなら、床屋さんのぐるぐる看板が1回 ``スピン''します。 もし増加された結果が0とmaxvalの範囲外になったら、 curvalは0とmaxvalの間に強制的に設定されます。
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.8 EasyDialogs Up: 2.8 EasyDialogs Next: 2.9 FrameWork


2.9 FrameWork -- 対話型アプリケーション・フレームワーク

利用可能な条件: Macintosh.

FrameWork モジュールは、対話型 Macintosh アプリケーションのク ラスで、同時にフレームワークを提供します。プログラマは、サブクラスを作っ て基底クラスの様々なメソッドをオーバーライドし、必要な機能を実装するこ とでアプリケーションを組み立てられます。機能のオーバーライドは、時によっ て様々な異なるレベルで行われます。つまり、ある一つのダイアログウィンド ウでクリックの処理を普段と違う方法で行うには、完全なイベント処理をオー バーライドする必要はありません。

FrameWork はまだ作成中のところがずいぶん残っています。このド キュメントでは最も重要な機能だけしか記述していませんし、それさえも論理 的な形で書かれてもいません。ソースか例題を詳しく見てください。次にあげ るのは、MacPython ニュースグループにポストされたコメントで、 FrameWork の強力さと限界について述べています。

FrameWork の最大の強みは、制御の流れをたくさんの異なる部分に 分割できることです。例えば W を使って、いろいろな方法でメ ニューをオン/オフしたり、残りをいじらずにうまくプラグインさせることが できます。FrameWork の弱点は、コマンドインタフェースが抽象化 されていないこと(といっても難しいわけではないですが)、ダイアログサポー トが最低限しかないこと、それからコントロール/ツールバーサポートが全く ないことです。

FrameWork モジュールは次の関数を定義しています。

Application( )

アプリケーション全体を表現しているオブジェクト。メソッドについての詳細 は以下の記述を参照してください。デフォルト __init__() ルーチ ンは、空のウィンドウ辞書とアップルメニューつきのメニューバーをを作成し ます。

MenuBar( )
メニューバーを表現するオブジェクト。このオブジェクトは普通はユーザは 作成しません。

Menu( bar, title[, after])

メニューを表現するオブジェクト。生成時には、メニューが現われる MenuBar と、title 文字列、メニューが表示されるべき(1から 始まる)位置 after (デフォルトは末尾)を渡します。

MenuItem( menu, title[, shortcut, callback])

メニューアイテムオブジェクトを作成します。引数は作成するメニューと、ア イテムのタイトル文字列、オプションのキーボードショートカット、コールバッ クルーチンです。コールバックは、メニューID、メニュー内のアイテム番号(1 から数える)、現在のフロントウィンドウ、イベントレコードを引数に呼ばれ ます。

呼び出し可能なオブジェクトのかわりに、コールバックは文字列でも良いです。 この場合、メニューの選択は、最前面のウィンドウとアプリケーションの中で メソッド探索を引き起こします。メソッド名は、コールバック文字列の前に 'domenu_' を付けたものです。

MenuBar の fixmenudimstate()メソッドを呼びだすと、現在 のフロントウィンドウにもとづいて、適切なディム化を全てのメニューアイテ ムに対してほどこします。

Separator( menu)

メニューの最後にセパレータを追加します。

SubMenu( menu, label)

label の名前のサブメニューを、メニュー menu の下に作成しま す。メニューオブジェクトが返されます。

Window( parent)

(モードレス)ウィンドウを作成します。Parent は、ウィンドウが属す るアプリケーションオブジェクトです。作成されたウィンドウはまだ表示され ません。

DialogWindow( parent)

モードレスダイアログウィンドウを作成します。

windowbounds( width, height)

与えた幅と高さのウィンドウを作成するのに必要な、(left, top, right, bottom) からなるタプルを返します。ウィ ンドウは以前のウィンドウに対して位置をずらして作成され、全体のウィンド ウが画面からなるべく外れないようにします。しかし、ウィンドウはいつでも 全く同じサイズで、そのため一部は画面から隠れる場合もあります。

setwatchcursor( )

マウスカーソルを時計型に設定します。

setarrowcursor( )

マウスカーソルを矢印型に設定します。

  • 2.9.1 アプリケーションオブジェクト
  • 2.9.2 ウィンドウオブジェクト
  • 2.9.3 コントロールウィンドウオブジェクト
  • 2.9.4 スクロールウィンドウオブジェクト
  • 2.9.5 ダイアログウィンドウオブジェクト
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.8.1 プログレスバーオブジェクト Up: 2. MacPython モジュール Next: 2.9.1 アプリケーションオブジェクト


2.9.1 アプリケーションオブジェクト

アプリケーションオブジェクトのメソッドは各種ありますが、次のメソッドを あげておきます。

makeusermenus( )

アプリケーションでメニューを使う必要がある場合、このメソッドをオーバー ライドします。属性 menubar にメニューを追加します。

getabouttext( )

このメソッドをオーバーライドすることで、アプリケーションの説明を記述す るテキスト文字列を返します。代わりに、do_about() メソッドをオー バーライドすれば、もっと凝った``アバウト''メッセージを出す事ができます。

mainloop( [mask[, wait]])

このルーチンがメインイベントループで、作成したアプリケーションが動き出 すためにはこれを呼ぶことになります。Mask は操作したいイベントを 選択するマスクです。 wait は並行に動作しているアプリケーションに 割り当てたいチック数(1/60秒)です(デフォルトで 0 ですが、あまり良い値で はありません)。self フラグを立ててメインループを抜ける方法はまだ サポートされていますが、これはお勧めできません。代わりに self._quit()を呼んでください。

イベントループは小さなパーツに分割されていて、各々をオーバーライドでき るようになっています。これらのメソッドは、デフォルトでウィンドウとダイ アログや、ドラッグとリサイズの操作、 AppleEvent、非FrameWorkのウィンド ウに関するウィンドウの操作などに関するイベントを分岐することなどまで面 倒をみてくれます。

原則として、全てのイベントハンドラは、イベントが完全に取り扱われた場合 は 1 を返さなくてはいけませんし、それ以外では 0 を返さな くてはいけません(例えば、前面のウィンドウは FrameWork ウィンドウではな い場合を考えてください)。こうしなくてはいけない理由は、アップデートイ ベントなどが Sioux コンソールウィンドウなどの他のウィンドウにきちんと渡さ れるようにするためです。our_dispatch やその呼び出し元の内部から MacOS.HandleEvent() を呼んではいけません。そうしたコードが Python の内部ループのイベントハンドラを経由して呼ばれると、無限ループ になりかねないからです。

asyncevents( onoff)

非同期でイベント操作をしたい場合は、非ゼロの引数でこのメソッドを呼んで ください。こうすることで、イベントが生じた時に、内部のインタプリタのルー プで、アプリケーションイベントハンドラ async_dispatch が呼ばれる ことになります。すると、長時間の計算を行っている場合でも、FrameWorkウィ ンドウがアップデートされ、ユーザーインターフェースが動き続けるようにな ります。ただし、インタプリタの動作が減速し、非リエントラントのコード (例えばFrameWork自身など)に奇妙な動作が見られるかもしれません。デフォル トでは async_dispatch はすぐに our_dispatch を呼びますが、 このメソッドをオーバーライドすると、特定のイベントを非同期で操作しても 良くなります。処理しないイベントは Sioux などに渡されることになります。

onあるいはoff値が返されます。

_quit( )

実行中の mainloop() 呼び出しを、次の適当なタイミングで終了さ せます。

do_char( c, event)

ユーザーが文字 c をタイプした時に呼ばれます。イベントの全詳細は event構造体の中にあります。このメソッドはウィンドウオブジェクト内で使 うためにも提供されています。このオブジェクトのウィンドウが最前面にある 場合は、アプリケーション全般について本ハンドラをオーバーライドします。

do_dialogevent( event)

イベントループ内部で最初に呼ばれて、モードレスダイアログイベントを処理 します。デフォルトではメソッドは単にイベントを適切なダイアログに分岐す るだけです(関連したダイアログウィンドウオブジェクトを経由してではあり ません)。特別にダイアログイベント(キーボードショートカットなど)を処理す る必要がある場合にオーバーライドしてください。

idle( event)

イベントが無い場合にメインイベントループから呼ばれます。 null イベン トも渡されます(つまりマウス位置などを監視することができます)。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.9 FrameWork Up: 2.9 FrameWork Next: 2.9.2 ウィンドウオブジェクト


2.9.2 ウィンドウオブジェクト

ウィンドウオブジェクトは特に次のメソッドを持ちます。

open( )

ウィンドウを開く時はこのメソッドをオーバーライドします。MacOS ウィンド ウ ID を self.wid に入れて do_postopen() メソッドを 呼ぶと、親アプリケーションにウィンドウを登録します。

close( )

ウィンドウを閉じるときに特別な処理をする場合はこのメソッドをオーバーラ イドします。親アプリケーションからウィンドウの登録を削除するには、 do_postclose() を呼びます。

do_postresize( width, height, macoswindowid)

ウィンドウがリサイズされた後に呼ばれます。InvalRect を呼び出す 以外にもすることがある場合はこれをオーバーライドします。

do_contentclick( local, modifiers, event)

ウィンドウのコンテント部分をユーザーがクリックすると呼ばれます。引数は 位置座標(ウィンドウを基準)、キーモディファイア、生のイベントです。

do_update( macoswindowid, event)

ウィンドウのアップデートイベントが受信された時に呼ばれます。ウィンドウ を再描画します。

do_activate( activate, event)

ウィンドウがアクティブ化(activate == 1)、非アクティブ化 (activate == 0)する際に呼ばれます。フォーカスのハイライト などを処理します。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.9.1 アプリケーションオブジェクト Up: 2.9 FrameWork Next: 2.9.3 コントロールウィンドウオブジェクト


2.9.3 コントロールウィンドウオブジェクト

コントロールウィンドウオブジェクトには Window オブジェクトのメ ソッドの他に次のメソッドがあります。

do_controlhit( window, control, pcode, event)

コントロール control のパートコード pcode がユーザーにヒットされた 場合に呼ばれます。トラッキングなどは任せておいてかまいません。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.9.2 ウィンドウオブジェクト Up: 2.9 FrameWork Next: 2.9.4 スクロールウィンドウオブジェクト


2.9.4 スクロールウィンドウオブジェクト

スクロールウィンドウオブジェクトは、次のメソッドを追加したコントロール ウィンドウオブジェクトです。

scrollbars( [wantx[, wanty]])

水平スクロールバーと垂直スクロールバーを作成します(あるいは破棄します)。 引数はどちらが欲しいか指定します(デフォルトは両方)。スクロールバーは常 に最小値 0 、最大値 32767 です。

getscrollbarvalues( )

このメソッドは必ず作っておかなくてはいけません。現在のスクロールバーの 位置を与えるタプル (x, y) を(0 の 32767 間で)返してください。バーの方向について全文書が可視状態で あること知らせるため None を返す事もできます。

updatescrollbars( )

文書に変更があった場合はこのメソッドを呼びます。このメソッドは getscrollbarvalues() を呼んでスクロールバーを更新します。

scrollbar_callback( which, what, value)

あらかじめ与えておくメソッドで、ユーザーとの対話により呼ばれます。 which は 'x' か 'y' 、whatは '-', '-', 'set','++', '+'のどれかです。 'set' の場合は、valueに新しいスクロールバー位置を入れてお きます。

scalebarvalues( absmin, absmax, curmin, curmax)

getscrollbarvalues() の結果から値を計算するのを助ける補助的な メソッドです。文書の最小値と最大値、可視部分に関する最先頭値(最左値)と 最底値(最右値)を渡すと、正しい数か None を返します。

do_activate( onoff, event)

ウィンドウが最前面になった時、スクロールバーのディム(dimming)/ハイライ トの面倒をみます。このメソッドをオーバーライドするなら、オーバーライド したメソッドの最後でオリジナルのメソッドを呼んでください。

do_postresize( width, height, window)

スクロールバーを正しい位置に移動させます。オーバーライドする時は、オー バーライドしたメソッドの一番最初でオリジナルのメソッドを呼んでください。

do_controlhit( window, control, pcode, event)

スクロールバーのインタラクションを処理します。これをオーバーライドする 時は、オリジナルのメソッドを最初に呼び出してください。非ゼロの返り値は スクロールバー内がヒットされたことを意味し、実際に処理が進むことになり ます。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.9.3 コントロールウィンドウオブジェクト Up: 2.9 FrameWork Next: 2.9.5 ダイアログウィンドウオブジェクト


2.9.5 ダイアログウィンドウオブジェクト

ダイアログウィンドウオブジェクトには、Window オブジェクトのメソッ ドの他に次のメソッドがあります。

open( resid)

ID resid の DLOG リソースからダイアログウィンドウを作成します。 ダイアログオブジェクトは self.wid に保存されます。

do_itemhit( item, event)

アイテム番号 item がヒットされた時に呼ばれます。トグルボタンなど の再描画は自分で処理してください。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.9.4 スクロールウィンドウオブジェクト Up: 2.9 FrameWork Next: 2.10 autoGIL


2.10 autoGIL -- イベントループ中のグローバルインタープリタの取り扱い

利用可能な条件: Macintosh.

autoGILモジュールは、自動的にイベントループを実行する場合 、 Python のグローバルインタープリタをロックしたり、ロックの解除をした りするための関数 installAutoGIL を提供します。

exception AutoGILError

例えば現在のスレッドがループしていないなど、オブザーバにコールバックが できない場合に発生します。

installAutoGIL( )

現在のスレッドのイベントループ(CFRunLoop)中のオブザーバにコールバッ クを行ない、適切な時にグローバルインタープリタロック(GIL)を、イ ベントループが使用されていない間、他の Python スレッドの起動がで きるようにロックしたり、ロックの解除をしたりします。

有効性：OSX 10.1以降

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.9.5 ダイアログウィンドウオブジェクト Up: 2. MacPython モジュール Next: 3. MacPython OSA モジュール


3. MacPython OSA モジュール

Python は オープンスクリプティングアーキテクチャ(Open Scripting Architecure、OSA、一般的には AppleScript と呼ばれる)のかなり完全な実装 を行っていて、Python プログラムからスクリプト可能なアプリケーションを 操作したり、Python へのインターフェースを備えたものにすることができます。

AppleScript と OSA の様々なコンポーネントの記述のために、また、アーキ テクチャおよび用語についての理解を得るために、アップルの文書を読む必 要があります。"Applescript Language Guide" は概念のモデルおよび用語、Standard Suiteについ て説明した文書です。"Open Scripting Architecture" 文書は、ア プリケーションプログラマの視点から OSA を使用する方法について説明 しています。これらの文書はAppleヘルプビューワのDeveloper Documentation 中のCore Technologiesセクションにあります。

アプリケーションをスクリプトで操作する例として、次の AppleScript は、 一番前の Finder ウィンドウの名前を取得し、それを印字します。

tell application "Finder"
    get name of window 1
end tell

Pythonでは以下のコードで同じ事ができます。

import Finder

f = Finder.Finder()
print f.get(f.window(1).name)

配布されている Python ライブラリは、Standard Suite を実装したパッケー ジに加えて、いくつかの一般的なアプリケーションへのインターフェースを実 装したパッケージが含まれています。

アプリケーションに AppleEvent を送るためには、アプリケーションの用語 (Script Editorが「辞書」と呼ぶもの)に接続する Python パッケー ジを最初に作成しなければなりません。これは、PythonIDE の内部 から、あるいは、コマンドラインからのスタンドアロンのプログラムとして gensuitemodule.py モジュールを実行することにより行うことができ ます。

gensuitemodule.py モジュールで生成される出力は多くのモジュール を備えたパッケージのため、全ての Suite をプログラムの中で 1 つにまとめ て利用できるようにするために __init__ モジュールが追加されて います。Python 継承グラフは AppleScript 継承グラフを理解するので、 Standard Suite をサポートしていて、余分な引数を備えた1つあるいは2つの 変数を拡張する事ができるようにプログラム辞書が書かれていた場合、出力さ れた Suite は、StdSuites.Standard_Suite からすべてをインポー トして再エクスポートし、さらに拡張機能をもったメソッドをオーバーライド するモジュール Standard_Suite を含みます。 gensuitemodule の出力は人間に判読可能で、Python docstrings中 にはオリジナルの AppleScript 辞書にあった文書を含んでいます。したがっ て、それを読むことは有用な情報源となります。

出力されたパッケージは、メソッドとして AppleScript 変数をすべて含み、 第1の引数としての直接オブジェクトを含み、キーワード引数としてのすべて のオプションの引数を含む、パッケージと同じ名前を備えた主要なクラスを実 装しています。また AppleScript クラスは Python クラス、そして類事物そ の他のもろもろの物として実装されています。

変数を実装する主要な Python クラスは、さらに AppleScriptクラス "application" で宣言されたプロパティおよび要素へのアクセスを許可します。 現在のリリースでオブジェクト指向的にやろうとするならば、例えば、より Python 的な f.window(1).name.get() の代りに f.get(f.window(1).name) を利用する必要があります。

AppleScript 識別子が Python 識別子と同じでない場合、名前は少数の規則に よって判別します。

  • スペースは下線に置換されます。
  • _xx_ が16進法の文字値である場合、他の英数字でない文字は xx と置換されます。
  • あらゆるPython 予約語には下線を追加します。

Python は、さらに Python でスクリプト対応アプリケーションを作成する事 をサポートしています。次のモジュールはMacPythonのAppleScriptサポートに 適切です。

gensuitemodule | OSA辞書からスタブパッケージを作成します。
aetools | Apple Eventを送るための基本的なサポート
aepack | Python変数とAppleEventデータコンテナ間の変換
aetypes | Apple Event オブジェクトモデルの Python 表現
MiniAEFrame | オープンスクリプティングアーキテクチャ(OSA)サーバ(``Apple Events'')のサポート。

さらに、Finder, Terminal, Explorer, Netscape, CodeWarrior, SystemEvents そして StdSuites のサポートモジュールは、あらかじめ生成されています。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 2.10 autoGIL Up: Macintoshモジュールリファレンス Next: 3.1 gensuitemodule


3.1 gensuitemodule -- OSA スタプ作成パッケージ

利用可能な条件: Macintosh.

gensuitemodule モジュールは AppleScript 辞書によって特定のア プリケーションに実装されている AppleScript 群のためのスタブコードを実 装した Python パッケージを作成します。

このモジュールは、通常は PythonIDE からユーザによって起動さ れますが、コマンドラインからスクリプトとして実行する(オプションとして ヘルプに --help を与えてみてください)こともできますし、Python コードでインポートして利用する事もできます。使用例として、どのようにし て標準ライブラリに含まれているスタブパッケージを生成するか、 Mac/scripts/genallsuites.py にあるソースを見てください。

このモジュールは次の関数を定義しています。

is_scriptable( application)

application としてパス名を与えたアプリケーションがスクリプト可 能でありそうな場合、真を返します。返り値はやや不確実な場合があります。 Internet Explorer はスクリプト不可能なように見えてしまいます が、実際はスクリプト可能です。

processfile( application[, output, basepkgname, edit_modnames, creatorsignature, dump, verbose])

パス名として渡された application のためのスタブパッケージを作成 します。.app として一つのパッケージにまとめてあるプログラム群の ために内部の実行プログラムそのものではなくパッケージへのパス名を渡すだ けでよくなっています。パッケージ化されていないCFM アプリケーションでは アプリケーションバイナリのファイル名を渡す事もできます。

この関数は、アプリケーションの OSA 用語リソースを捜し、これらのリソー スを読み取り、その結果データをクライアントスタブを実装したPython コー ドパッケージを作成するために使用します。

output は作成結果のパッケージを保存するパス名で、指定しない場合 は標準の「別名で保存(save file as)」ダイアログが表示されます。 basepkgname はこのパッケージの基盤となるパッケージを指定します。 デフォルトは StdSuites になります。StdSuites 自体を 生成する場合だけ、このオプションを指定する必要があります。 edit_modnames は自動生成によって作成されてあまり綺麗ではないモ ジュール名を変更するために使用することができる辞書です。 creator_signature はパッケージ中の PkgInfo ファイル、あ るいは CFM ファイルクリエータ署名から通常得られる4文字クリエータコード を無視するために使用することができます。dump にはファイルオブジェ クトを与えます、これを指定するとリソースを読取った後に停止して processfile がコード化した用語リソースの Python 表現をダンプし ます。verbose にもまたファイルオブジェクトを与え、これを指定する と processfile の行なっている処理の詳細を出力します。

processfile_fromresource( application[, output, basepkgname, edit_modnames, creatorsignature, dump, verbose])

この関数は、用語リソースを得るのに異なる方法を使用する以外は、 processfile と同じです。この関数では、リソースファイルとして application を開き、このファイルから "aete" および "aeut" リソースをすべて読み込む事で、AppleScript 用語リソース読み 込みを行ないます。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 3. MacPython OSA モジュール Up: 3. MacPython OSA モジュール Next: 3.2 aetools


3.2 aetools -- OSA クライアントのサポート

利用可能な条件: Macintosh.

aetools モジュールは Python で AppleScript クライアントとして の機能をサポートするアプリケーションを構築するための基本的な機能を含ん でいます。さらに、このモジュールは、 aetypes および aepack モジュールの中核機能をインポートし再 エクスポートします。 gensuitemodule によって生成されたスタブパッケージは aetools のかなり適切な部分をインポートするので、通常はそれを 明示的にインポートする必要はありません。生成されたパッケージ群を使用す ることができない場合と、スクリプト対応のためにより低いレベルのアクセス を必要としている場合、例外が発生します。

aetools モジュールはそれ自身、Carbon.AE モジュールに よって提供される AppleEvent サポートを利用します。このモジュールにはウィ ンドウマネージャへのアクセスを必要とするという1つの欠点があります。詳 細は第 1.1.2 章を見てください。この制限は将来のリリー スで撤廃されるかもしれません。

aetools モジュールは下記の関数を定義しています。

packevent( ae, parameters, attributes)

あらかじめ作成された Carbon.AE.AEDesc オブジェクト中のパラメー ターおよび属性を保存します。parameters と attributes は Python オブジェクトの4文字の OSA パラメータのキーを写像した辞書です。 このオブジェクトをパックするには aepack.pack() を使います。

unpackevent( ae[, formodulename])

再帰的に、Carbon.AE.AEDesc イベントをPython オブジェクトへアン パックします。関数は引数の辞書および属性の辞書を返します。 formodulename 引数は AppleScript クラスをどこに捜しに行くか制御 するために、生成されたスタブパッケージにより使用されます。

keysubst( arguments, keydict)

Python キーワード引数辞書 arguments を、写像による4文字の OSA キーとして keydict の中で指定されたPython 識別子であるキーの交 換により packevent によって要求されるフォーマットへ変換します。 生成されたパッケージ群によって使用されます。

enumsubst( arguments, key, edict)

arguments 辞書が key へのエントリーを含んでいる場合、辞 書 edict のエントリーに見合う値に変換します。これは人間に判読可 能なように Python 列挙名を OSA 4文字のコードに変換します。生成されたパッ ケージ群によって使用されます。

aetools モジュールは次のクラスを定義しています。

class TalkTo( [signature=None, start=0, timeout=0])

アプリケーションとの対話に利用する代理の基底クラスです。 signature はクラス属性 _signature (サブクラスによって通 常設定される)を上書きした、対話するアプリケーションを定義する4文字クリ エートコードです。start にはクラスインスタンス上でアプリケーショ ンを実行することを可能にするために、真を設定する事ができます。 timeout を明示的に設定する事で、 AppleEvent の返答を待つデフォ ルトのタイムアウト時間を変更する事ができます。

_start( )

アプリケーションが起動していてるか確認し、起動していなければ起動しよう とします。

send( code, subcode[, parameters, attributes])

OSA指示子 code, subcode (いずれも通常4文字の文字列です)を持った 変数のために、parameters をパックし、attributesに戻し、 目標アプリケーションにそれを送って、返答を待ち、unpackevent を 含んだ返答をアンパックし、AppleEvent の返答を返し、辞書としてアンパッ クした値と属性を返して、AppleEvent Carbon.AE.AEDesc を作成しま す。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 3.1 gensuitemodule Up: 3. MacPython OSA モジュール Next: 3.3 aepack


3.3 aepack -- Python変数とAppleEventデータコンテナ間の変換

利用可能な条件: Macintosh.

aepack モジュールは、Python 変数から AppleEvent ディスクリプ タへの変換(パック)と、その逆に変換(アンパック)する関数を定義しています。 Python 内では AppleEvent ディスクリプタは、組み込み型である AEDesc の Python オブジェクトとして扱われます。AEDesc は Carbon.AE モジュールで定義されています。

aepack モジュールは次の関数を定義しています。

pack( x[, forcetype])

Python 値 x を変換した値を保持する AEDesc オブジェクトを返しま す。forcetype が与えることで、結果のディスクリプタ型を指定できま す。それ以外では、Python 型から Apple Eventディスクリプタ型へのデフォ ルトのマッピングが使われます。マッピングは次の通りとなります。

Python type | descriptor type
FSSpec | typeFSS
FSRef | typeFSRef
Alias | typeAlias
integer | typeLong (32 bit integer)
float | typeFloat (64 bit floating point)
string | typeText
unicode | typeUnicodeText
list | typeAEList
dictionary | typeAERecord
instance | see below

x がPythonインスタンスなら、この関数は __aepack__() メ ソッドを呼びだそうとします。このメソッドは AEDesc オブジェ クトを返します。

x の変換が上で定義されていない場合は、この関数は、テキストディス クリプタとしてエンコードされた、値の(repr()関数による)Python文字列表現 が返されます。

unpack( x[, formodulename])

x は AEDesc タイプのオブジェクトでなければいけません。 この関数は、Apple Eventディスクリプタ x のデータのPythonオブジェ クト表現を返します。単純なAppleEventデータ型(整数、テキスト、浮動少 数点数)の、対応するPython型が返されます。Apple EventリストはPythonリ ストとして返され、リストの要素は再帰的にアンパックされます。 formodulename の指定がない場合、オブジェクト参照 (例：line 3 of document 1)が、aetypes.ObjectSpecifier のインスタ ンスとして返されます。ディスクリプタ型がtypeFSSであるAppleEventディ スクリプタが、FSSpec オブジェクトとして返されます。 AppleEventレコードディスクリプタが、再帰的にアンパックされた、型の4 文字キーと要素を持つPython辞書として返されます。

オプションの formodulename 引数は gensuitemodule よ り作成されるスタブパッケージにより利用され、オブジェクト指定子のため の OSA クラスをモジュールの中で見つけられることを保証します。これは、 例えば、ファインダがウィンドウに対してオブジェクト指定子を返す場合、 Finder.Window のインスタンスが得られ、aetypes.Window が得られないことを保証します。前者は、ファインダ上のウィンドウが持っ ている、すべての特性および要素のことを知っています。一方、後者のもの はそれらのことを知りません。

参考資料:

Carbon.AEモジュール:
Apple Eventマネージャルーチンへの組み込みアクセス.
aetypesモジュール:
Apple Eventディスクリプタ型としてコードされたPython定義.
Inside Macintosh: Interapplication Communication
Macintosh上でのプロセス間通信に関する情報
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 3.2 aetools Up: 3. MacPython OSA モジュール Next: 3.4 aetypes


3.4 aetypes -- AppleEvent オブジェクト

利用可能な条件: Macintosh.

aetypes は Apple Event データディスクリプタおよび Apple Event オブジェクト指定子を表わすために使用されるクラスを定義します。

Apple Event データはディスクリプタに含まれていて、これらのディスクリプ タは型です。多くのディスクリプタについては、そのPython 表現は単に対応 するPython の型になります。例えば、OSA 中の typeText は Python 文字列型で、typeFloat は 浮動小数点型、などのようになります。直 接 Python で相当する型がない OSA の型については、このモジュールがクラ スを宣言します。これらのクラスのインスタンスのパック、アンパックは aepack によって自動的に処理されます。

オブジェクト指定子は本質的に Apple Event サーバーの中で実行しているオ ブジェクトのアドレスです。Apple Event 指定子は、Apple Event のための直 接オブジェクト、あるいはオプションパラメータの引数として使用されます。 aetypes モジュールは OSA クラス、およびプロパティのための基底 クラスを含んでいて、それらは、与えられたクラス群やプロパティ群のクラス およびプロパティに含めるために、 gensuitemodule によって生成 されたパッケージによって使用されます。

下位互換性のためと、スクリプトにスタブパッケージを生成していないアプリ ケーションを必要とする場合のために、このモジュールはさらに Document 、Window、Character、などのような多くの共 通 OSA クラス用のオブジェクト指定子を含んでいます。

AEObjects モジュールは Apple Event ディスクリプタデータを表わ すために次のクラスを定義しています。

class Unknown( type, data)

これ以外のクラスによって表わされず、単純な Python の値と等価でないよう な、aepack および aetypes モジュールでサポートしてい ない OSA ディスクリプタデータの表現。

class Enum( enum)

与えられた4文字のストリング値を持った列挙値。

class InsertionLoc( of, pos)

オブジェクト of の中の pos の位置。

class Boolean( bool)

真偽値。

class StyledText( style, text)

スタイル情報(フォント、フェイスなど)を持っているテキスト。

class AEText( script, style, text)

スクリプトシステムおよびスタイル情報を持っているテキスト。

class IntlText( script, language, text)

スクリプトシステムおよび言語情報を持っているテキスト。

class IntlWritingCode( script, language)

スクリプトシステムと言語情報。

class QDPoint( v, h)

QuickDrawの点。

class QDRectangle( v0, h0, v1, h1)

QuickDrawの矩形。

class RGBColor( r, g, b)

色。

class Type( type)

4文字の名前を持つ OSA 型の値。

class Keyword( name)

4文字の名前をを持つ OSA のキーワード。

class Range( start, stop)

範囲。

class Ordinal( abso)

"firs" で最初とか、"midd" で中央、のような数値表現でな い絶対位置。

class Logical( logc, term)

term にオペレーター logc を適用する論理表現。

class Comparison( obj1, relo, obj2)

obj1 と obj2 の relo による比較。

Python の中で AppleScript クラスおよプロバティを表わすために、次のクラ スは生成するスタブパッケージの基底クラスとして使用されます。

class ComponentItem( which[, fr])

OSA クラス用の抽象基底クラスです。サブクラスには4文字のOSAクラスコード のクラス属性 want を設定する必要があります。このクラスのサブク ラスのインスタンスは AppleScript オブジェクト指定子と等価になります。 インスタンス化する時、which の値としてセレクターを渡す事は必須 で、fr 中の親オブジェクトを渡すかは任意です。

class NProperty( fr)

OSA プロパティ用の抽象基底クラスです。サブクラスはクラス属性として want と which を設定する必要がありあます。このクラスのサ ブクラスのインスタンスはオブジェクト指定子と等価です。

class ObjectSpecifier( want, form, seld[, fr])

ComponentItem と NProperty の基底クラスで、一般的な OSA オブジェクト指定子です。引数の内容はApple オープンスクリプティングアー キテクチャの文書を御覧ください。このクラスは抽象クラスではない事に注 意してください。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 3.3 aepack Up: 3. MacPython OSA モジュール Next: 3.5 MiniAEFrame


3.5 MiniAEFrame -- オープンスクリプティングアーキテクチャサーバのサポート

利用可能な条件: Macintosh.

MiniAEFrameモジュールは、アプリケーションにオープンスクリプ ティングアーキテクチャ(OSA)サーバ機 能を持たせるためのフレームワークを提供します。つまり、 AppleEventsの受信と処理を行わせます。 FrameWorkと連携させても良いし、単独 でも使えます。 実例として、このモジュールはPythonCGISlaveの中で使われていま す。

MiniAEFrameには以下のクラスが定義されています。

class AEServer( )
AppleEventの分岐を処理するクラス。作成するアプリケーションはこのクラス と、MiniApplicationあるいはFrameWork.Applicationのサブク ラスでなければなりません。サブクラス化したクラスでは__init__() メソッドで、継承した両方のクラスの__init__()メソッドを呼びださ なければなりません。

class MiniApplication( )
FrameWork.Applicationとある程度互換なクラスですが、機能は少ない です。このクラスのイベントループはアップルメニュー、Cmd-.(コマンドキーを押しながらピリオド.を押す)、 AppleEventをサポートします。他のイベントはPythonインタープリタかSioux（CodeWarriorの コンソールシステム）に渡されます。作成するアプリケーションで AEServerを使いたいが、独自のウィンドウなどを持たない場合に便利で す。

  • 3.5.1 AEServer オブジェクト
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 3.4 aetypes Up: 3. MacPython OSA モジュール Next: 3.5.1 AEServer オブジェクト


3.5.1 AEServer オブジェクト

installaehandler( classe, type, callback)
AppleEventハンドラをインストールします。classeとtypeは4文字 のOSAクラスとタイプの指定子で、ワイルドカード'****'も使えます。対 応するAppleEventを受けるとパラメータがデコードされ、与えたコールバックが 呼び出されます。

callback( _object, **kwargs)
与えたコールバックは、OSAダイレクトオブジェクトを1番目のパラメータとして 呼び出されます。他のパラメータは4文字の指定子を名前にしたキーワード引数 として渡されます。他に3つのキーワード・パラメータが渡されます。つまり、 _classと_typeはクラスとタイプ指定子で、_attributes はAppleEvent属性を持つ辞書です。

与えたメソッドの返り値はaetools.packevent()でパックされ、リプ ライとして送られます。

現在のクラス設計にはいくつか重大な問題があることに注意してください。引数 に名前ではない4文字の指定子を持つAppleEventはまだ実装されていないし、イ ベントの送信側にエラーを返すこともできません。この問題は将来のリリースま で先送りにされています。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 3.5 MiniAEFrame Up: 3.5 MiniAEFrame Next: 4. MacOS ツールボックスモジュール


4. MacOS ツールボックスモジュール

各種のMacOSツールボックスへのインターフェースを与えるモジュール群があ ります。対応するモジュールがあるなら、そのモジュールではツールボックス で宣言された各種の構造体のPythonオブジェクトが定義され、操作は定義され たオブジェクトのメソッドとして実装されています。その他の操作はモジュー ルの関数として実装されています。 Cで可能な操作がすべてPythonで可能なわ けではありませんし(コールバックはよく問題になります)、パラメータが Pythonだと違ってしまうことはよくあります(特に入力バッファや出力バッファ)。 全てのメソッドと関数は __doc__ 文字列があるので、引数と返り値 の説明を得る事ができます。他の情報源としては、 Inside Macintoshなどを参照してください。

これらのモジュールは全て Carbon パッケージに含まれています。 この名前にもかかわらずそれら全てが Carbon フレームワークの一部なわけで はありません。CF は、CoreFoundationフレームワークの中に実際はあります し、QtはQuickTimeフレームワークにあります。ツールボックスモジュールは普通以下 のようにして利用します。

from Carbon import AE

注意！これらのモジュールはまだ文書化されていません。これらの モジュールのどれでもよいですが文書化に協力したいという方は、 docs@python.org まで連絡をください。

Carbon.AE | Apple Eventツールボックスへのインタフェース
Carbon.AH | Apple ヘルプマネージャへのインタフェース
Carbon.App | アピアランスマネージャへのインタフェース
Carbon.CF | Core Foundationへのインタフェース
Carbon.CG | Component Managerへのインタフェース
Carbon.CaronEvt | Carbon Event Managerへのインタフェース
Carbon.Cm | Component Managerへのインタフェース
Carbon.Ctl | Control Managerへのインタフェース
Carbon.Dlg | Dialog Managerへのインタフェース
Carbon.Evt | Event Managerへのインタフェース
Carbon.Fm | Font Managerへのインタフェース
Carbon.Folder | Folder Managerへのインタフェース
Carbon.Help | Carbon Help Managerへのインタフェース
Carbon.List | List Managerへのインタフェース
Carbon.Menu | Menu Managerへのインタフェース
Carbon.Mlte | MultiLingual Text Editorへのインタフェース
Carbon.Qd | QuickDrawツールボックスへのインタフェース
Carbon.Qdoffs | QuickDrawオフスクリーン APIへのインタフェース
Carbon.Qt | QuickTime ツールボックスへのインタフェース
Carbon.Res | Resource Managerとハンドルへのインタフェース
Carbon.Scrap | Carbon Scrap Managerへのインタフェース
Carbon.Snd | Sound Managerへのインタフェース
Carbon.TE | TextEditへのインタフェース
Carbon.Win | Window Managerへのインタフェース
ColorPicker | 標準色選択ダイアログへのインターフェース

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 3.5.1 AEServer オブジェクト Up: Macintoshモジュールリファレンス Next: 4.1 Carbon.AE


4.1 Carbon.AE -- Apple Events

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4. MacOS ツールボックスモジュール Up: 4. MacOS ツールボックスモジュール Next: 4.2 Carbon.AH


4.2 Carbon.AH -- Apple ヘルプ

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.1 Carbon.AE Up: 4. MacOS ツールボックスモジュール Next: 4.3 Carbon.App


4.3 Carbon.App -- アピアランスマネージャ

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.2 Carbon.AH Up: 4. MacOS ツールボックスモジュール Next: 4.4 Carbon.CF


4.4 Carbon.CF -- Core Foundation

利用可能な条件: Macintosh.

CFBase, CFArray, CFData, CFDictionary, CFString と CFURL オブジェクトがいくらか部分的にサポート されています。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.3 Carbon.App Up: 4. MacOS ツールボックスモジュール Next: 4.5 Carbon.CG


4.5 Carbon.CG -- Core Graphics

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.4 Carbon.CF Up: 4. MacOS ツールボックスモジュール Next: 4.6 Carbon.CarbonEvt


4.6 Carbon.CarbonEvt -- Carbon Event Manager

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.5 Carbon.CG Up: 4. MacOS ツールボックスモジュール Next: 4.7 Carbon.Cm


4.7 Carbon.Cm -- Component Manager

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.6 Carbon.CarbonEvt Up: 4. MacOS ツールボックスモジュール Next: 4.8 Carbon.Ctl


4.8 Carbon.Ctl -- Control Manager

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.7 Carbon.Cm Up: 4. MacOS ツールボックスモジュール Next: 4.9 Carbon.Dlg


4.9 Carbon.Dlg -- Dialog Manager

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.8 Carbon.Ctl Up: 4. MacOS ツールボックスモジュール Next: 4.10 Carbon.Evt


4.10 Carbon.Evt -- Event Manager

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.9 Carbon.Dlg Up: 4. MacOS ツールボックスモジュール Next: 4.11 Carbon.Fm


4.11 Carbon.Fm -- Font Manager

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.10 Carbon.Evt Up: 4. MacOS ツールボックスモジュール Next: 4.12 Carbon.Folder


4.12 Carbon.Folder -- Folder Manager

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.11 Carbon.Fm Up: 4. MacOS ツールボックスモジュール Next: 4.13 Carbon.Help


4.13 Carbon.Help -- Help Manager

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.12 Carbon.Folder Up: 4. MacOS ツールボックスモジュール Next: 4.14 Carbon.List


4.14 Carbon.List -- List Manager

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.13 Carbon.Help Up: 4. MacOS ツールボックスモジュール Next: 4.15 Carbon.Menu


4.15 Carbon.Menu -- Menu Manager

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.14 Carbon.List Up: 4. MacOS ツールボックスモジュール Next: 4.16 Carbon.Mlte


4.16 Carbon.Mlte -- MultiLingual Text Editor

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.15 Carbon.Menu Up: 4. MacOS ツールボックスモジュール Next: 4.17 Carbon.Qd


4.17 Carbon.Qd -- QuickDraw

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.16 Carbon.Mlte Up: 4. MacOS ツールボックスモジュール Next: 4.18 Carbon.Qdoffs


4.18 Carbon.Qdoffs -- QuickDraw Offscreen

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.17 Carbon.Qd Up: 4. MacOS ツールボックスモジュール Next: 4.19 Carbon.Qt


4.19 Carbon.Qt -- QuickTime

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.18 Carbon.Qdoffs Up: 4. MacOS ツールボックスモジュール Next: 4.20 Carbon.Res


4.20 Carbon.Res -- Resource Manager and Handles

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.19 Carbon.Qt Up: 4. MacOS ツールボックスモジュール Next: 4.21 Carbon.Scrap


4.21 Carbon.Scrap -- Scrap Manager

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.20 Carbon.Res Up: 4. MacOS ツールボックスモジュール Next: 4.22 Carbon.Snd


4.22 Carbon.Snd -- Sound Manager

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.21 Carbon.Scrap Up: 4. MacOS ツールボックスモジュール Next: 4.23 Carbon.TE


4.23 Carbon.TE -- TextEdit

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.22 Carbon.Snd Up: 4. MacOS ツールボックスモジュール Next: 4.24 Carbon.Win


4.24 Carbon.Win -- Window Manager

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.23 Carbon.TE Up: 4. MacOS ツールボックスモジュール Next: 4.25 ColorPicker


4.25 ColorPicker -- 色選択ダイアログ

利用可能な条件: Macintosh.

ColorPicker モジュールは標準色選択ダイアログへのアクセスを提 供します。

GetColor( prompt, rgb)

標準色選択ダイアログを表示し、ユーザが色を選択することを可能にします。 prompt の文字列によりユーザに指示を与えられ、デフォルトの選択 色を rgb で設定する事ができます。rgb は赤、緑、青の色要 素のタプルで与えてください。GetColor() はユーザが選択した 色のタプルと色が選択されたか、取り消されたかを示すフラグを返します。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.24 Carbon.Win Up: 4. MacOS ツールボックスモジュール Next: 5. 文書化されていないモジュール


5. 文書化されていないモジュール

この章のモジュールは、(ここに記述があったとしても)文書化がほとんどされ ていません。これらのモジュールのどれでもよいが文書化に協力したいという 方は、 docs@python.org まで連絡をください。

applesingle | AppleSingle フォーマットファイル用の基本的なデコーダ
buildtools | BuildAppletとその仲間のヘルパーモジュール
py_resource | コンパイル済みアプリケーションに 'PYC~' リソースを 作成にするヘルパーモジュール
cfmfile | コードフラグメントリソースを扱うモジュール
icopen | open()と Internet Config の置き換え
macerrors | 多くの MacOS エラーコード定数定義
macresource | スクリプトのリソースを見つける
Nac | Navigation Services へのインターフェース
mkcwproject | CodeWarrior プロジェクトの作成
nsremote | Netscape OSAモジュールのラッパー
PixMapWrapper | PixMapオブジェクトのラッパー
preferences | デフォルト設定へのサポートを持つアプリケーション初期設定管理プログラム
pythonprefs | Python インタープリタに特化した初期設定管理プログラム
quietconsole | バッファを用いての不可視の標準出力
videoreader | フレームの継続処理のためのQuickTime ムービーのフレーム読み込み
W | FrameWork 上に作られた Mac 用ウイジェット
waste | ``WorldScript-Aware Styled Text Engine''へのインターフェー ス

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 4.25 ColorPicker Up: Macintoshモジュールリファレンス Next: 5.1 applesingle


5.1 applesingle -- AppleSingle デコーダー

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5. 文書化されていないモジュール Up: 5. 文書化されていないモジュール Next: 5.2 buildtools


5.2 buildtools -- BuildAppletとその仲間のヘルパーモジュール

利用可能な条件: Macintosh.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.1 applesingle Up: 5. 文書化されていないモジュール Next: 5.3 py_resource


5.3 py_resource -- Python コードからのリソース生成

利用可能な条件: Macintosh.

このモジュールは BuildApplet と BuildApplication のヘルパーモジュールとして主に利用されています。コンパイル済みの Python コードに 'PYC ' リソースを付加する事ができます。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.2 buildtools Up: 5. 文書化されていないモジュール Next: 5.4 cfmfile


5.4 cfmfile -- コードフラグメントリソースを扱うモジュール

利用可能な条件: Macintosh.

cfmfile は、コードフラグメントと関連する``cfrg''リソースを処 理するモジュールです。このモジュールでコードフラグメントを分解やマージ できて、全てのプラグインモジュールをまとめて、一つの実行可能ファイルに するため、BuildApplicationによって利用されます。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.3 py_resource Up: 5. 文書化されていないモジュール Next: 5.5 icopen


5.5 icopen -- open()と Internet Config の置き換え

利用可能な条件: Macintosh.

icopen をインポートすると、組込み open() を新しいファ イル用にファイルタイプおよびクリエーターを設定するために Internet Configを使用するバージョンに置き換えます。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.4 cfmfile Up: 5. 文書化されていないモジュール Next: 5.6 macerrors


5.6 macerrors -- MacOSのエラー

利用可能な条件: Macintosh.

macerrors は、MacOS エラーコードを意味する定数定義を含みます。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.5 icopen Up: 5. 文書化されていないモジュール Next: 5.7 macresource


5.7 macresource -- スクリプトのリソースを見つける

利用可能な条件: Macintosh.

macresource はスクリプトが MacPython 上や MacPython アプレッ トおよび OSX Python 上で起動されている時、特別な処理をせずにダイアログ やメニューなどのようなリソースを見つけるためのヘルパースクリプトです。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.6 macerrors Up: 5. 文書化されていないモジュール Next: 5.8 Nav


5.8 Nav -- NavServices の呼出し

利用可能な条件: Macintosh.

Navigation Servicesの低レベルインターフェース。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.7 macresource Up: 5. 文書化されていないモジュール Next: 5.9 mkcwproject


5.9 mkcwproject -- CodeWarrior プロジェクトの作成

利用可能な条件: Macintosh.

mkcwproject は Metrowerks CodeWarrior 開発環境用のプロジェク トファイルを作成します。これは distutilsのためのヘルパーモジュー ルですが、より多くの制御のために独立して利用できます。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.8 Nav Up: 5. 文書化されていないモジュール Next: 5.10 nsremote


5.10 nsremote -- Netscape OSAモジュールのラッパー

利用可能な条件: Macintosh.

nsremote は Netscape の OSA モジュールのラッパーであり、好き なブラウザに対して URL を簡単に送ることができます。 Python Library Referenceに記述のある webbrowserモジュールと緊密な関係があります。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.9 mkcwproject Up: 5. 文書化されていないモジュール Next: 5.11 PixMapWrapper


5.11 PixMapWrapper -- PixMapオブジェクトのラッパー

利用可能な条件: Macintosh.

PixMapWrapper はPixMap オブジェクトを Python オブジェクトでラッ プしたもので、各フィールドに対し名前でアクセスできるようになります。 PIL 画像との相互の変換をするメソッドも用意されています。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.10 nsremote Up: 5. 文書化されていないモジュール Next: 5.12 preferences


5.12 preferences -- アプリケーション初期設定管理プログラム

利用可能な条件: Macintosh.

preferences はシステム全体に渡る初期設定フォルダ中のユーザ毎 の初期設定を記憶し、特定の状況に対する好みにより、デフォルトの設定を適 用もしくは無視する事ができます。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.11 PixMapWrapper Up: 5. 文書化されていないモジュール Next: 5.13 pythonprefs


5.13 pythonprefs -- Python の初期設定管理プログラム

利用可能な条件: Macintosh.

このモジュールは preferences モジュールをを特化させて Python インター プリタの初期設定を読み込んだり、書き込みしたりできるようにした物です。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.12 preferences Up: 5. 文書化されていないモジュール Next: 5.14 quietconsole


5.14 quietconsole -- 不可視の標準出力

利用可能な条件: Macintosh.

quietconsole を使うと、バッファの stdio 出力を表示せずに (あ るいは、EditPythonPrefsで設定されていれば、stdout ウィンドウ を全く表示しないで) 保存することができます。保存されるのは、 stdin か ら読み込みを始めるか、バッファリングを止めるかするまでの間で、その時点 で全ての出力は今度はウィンドウに送られるることになります。 グラフィカ ルユーザインターフェース(GUI)プログラムで、クラッシュ時の出力を表示し たい場合に便利です。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.13 pythonprefs Up: 5. 文書化されていないモジュール Next: 5.15 videoreader


5.15 videoreader -- QuickTime ムービーの読み込み

利用可能な条件: Macintosh.

videoreader は QuickTime ムービーを読み込み、デコードし、プロ グラムへ渡す事ができます。このモジュールはさらにオーディオトラックをサ ポートしています。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.14 quietconsole Up: 5. 文書化されていないモジュール Next: 5.16 W


5.16 W -- FrameWork 上に作られたウイジェット

利用可能な条件: Macintosh.

W ウィジェットは、IDE で頻繁に使われています。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.15 videoreader Up: 5. 文書化されていないモジュール Next: 5.17 waste


5.17 waste -- Apple製ではない TextEdit の置き換え

利用可能な条件: Macintosh.

参考資料:

About WASTE
WASTEウィジェッ トとライブラリに関する情報サイト。ドキュメントとダウンロードもここ から行なえます。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.16 W Up: 5. 文書化されていないモジュール Next: A. 歴史とライセンス


A. 歴史とライセンス

  • A.1 History of the software
  • A.2 Terms and conditions for accessing or otherwise using Python
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 5.17 waste Up: Macintoshモジュールリファレンス Next: A.1 History of the


A.1 History of the software

Python was created in the early 1990s by Guido van Rossum at Stichting Mathematisch Centrum (CWI, see http://www.cwi.nl/) in the Netherlands as a successor of a language called ABC. Guido remains Python's principal author, although it includes many contributions from others.

In 1995, Guido continued his work on Python at the Corporation for National Research Initiatives (CNRI, see http://www.cnri.reston.va.us/) in Reston, Virginia where he released several versions of the software.

In May 2000, Guido and the Python core development team moved to BeOpen.com to form the BeOpen PythonLabs team. In October of the same year, the PythonLabs team moved to Digital Creations (now Zope Corporation; see http://www.zope.com/). In 2001, the Python Software Foundation (PSF, see http://www.python.org/psf/) was formed, a non-profit organization created specifically to own Python-related Intellectual Property. Zope Corporation is a sponsoring member of the PSF.

All Python releases are Open Source (see http://www.opensource.org/ for the Open Source Definition). Historically, most, but not all, Python releases have also been GPL-compatible; the table below summarizes the various releases.

Release | Derived from | Year | Owner | GPL compatible?
0.9.0 thru 1.2 | n/a | 1991-1995 | CWI | yes
1.3 thru 1.5.2 | 1.2 | 1995-1999 | CNRI | yes
1.6 | 1.5.2 | 2000 | CNRI | no
2.0 | 1.6 | 2000 | BeOpen.com | no
1.6.1 | 1.6 | 2001 | CNRI | no
2.1 | 2.0+1.6.1 | 2001 | PSF | no
2.0.1 | 2.0+1.6.1 | 2001 | PSF | yes
2.1.1 | 2.1+2.0.1 | 2001 | PSF | yes
2.2 | 2.1.1 | 2001 | PSF | yes
2.1.2 | 2.1.1 | 2002 | PSF | yes
2.1.3 | 2.1.2 | 2002 | PSF | yes
2.2.1 | 2.2 | 2002 | PSF | yes
2.2.2 | 2.2.1 | 2002 | PSF | yes
2.2.3 | 2.2.2 | 2002-2003 | PSF | yes
2.3 | 2.2.2 | 2002-2003 | PSF | yes
2.3.1 | 2.3 | 2002-2003 | PSF | yes
2.3.2 | 2.3.1 | 2003 | PSF | yes

注意: GPL-compatible doesn't mean that we're distributing Python under the GPL. All Python licenses, unlike the GPL, let you distribute a modified version without making your changes open source. The GPL-compatible licenses make it possible to combine Python with other software that is released under the GPL; the others don't.

Thanks to the many outside volunteers who have worked under Guido's direction to make these releases possible.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: A. 歴史とライセンス Up: A. 歴史とライセンス Next: A.2 Terms and conditions


A.2 Terms and conditions for accessing or otherwise using Python

PSF LICENSE AGREEMENT FOR PYTHON 2.3.3

  1. This LICENSE AGREEMENT is between the Python Software Foundation (``PSF''), and the Individual or Organization (``Licensee'') accessing and otherwise using Python 2.3.3 software in source or binary form and its associated documentation.

  2. Subject to the terms and conditions of this License Agreement, PSF hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python 2.3.3 alone or in any derivative version, provided, however, that PSF's License Agreement and PSF's notice of copyright, i.e., ``Copyright © 2001-2003 Python Software Foundation; All Rights Reserved'' are retained in Python 2.3.3 alone or in any derivative version prepared by Licensee.

  3. In the event Licensee prepares a derivative work that is based on or incorporates Python 2.3.3 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python 2.3.3.

  4. PSF is making Python 2.3.3 available to Licensee on an ``AS IS'' basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.3.3 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 2.3.3 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 2.3.3, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between PSF and Licensee. This License Agreement does not grant permission to use PSF trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party.

  8. By copying, installing or otherwise using Python 2.3.3, Licensee agrees to be bound by the terms and conditions of this License Agreement.

BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0

BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1

  1. This LICENSE AGREEMENT is between BeOpen.com (``BeOpen''), having an office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization (``Licensee'') accessing and otherwise using this software in source or binary form and its associated documentation (``the Software'').

  2. Subject to the terms and conditions of this BeOpen Python License Agreement, BeOpen hereby grants Licensee a non-exclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use the Software alone or in any derivative version, provided, however, that the BeOpen Python License is retained in the Software, alone or in any derivative version prepared by Licensee.

  3. BeOpen is making the Software available to Licensee on an ``AS IS'' basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  5. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  6. This License Agreement shall be governed by and interpreted in all respects by the law of the State of California, excluding conflict of law provisions. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between BeOpen and Licensee. This License Agreement does not grant permission to use BeOpen trademarks or trade names in a trademark sense to endorse or promote products or services of Licensee, or any third party. As an exception, the ``BeOpen Python'' logos available at http://www.pythonlabs.com/logos.html may be used according to the permissions granted on that web page.

  7. By copying, installing or otherwise using the software, Licensee agrees to be bound by the terms and conditions of this License Agreement.

CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1

  1. This LICENSE AGREEMENT is between the Corporation for National Research Initiatives, having an office at 1895 Preston White Drive, Reston, VA 20191 (``CNRI''), and the Individual or Organization (``Licensee'') accessing and otherwise using Python 1.6.1 software in source or binary form and its associated documentation.

  2. Subject to the terms and conditions of this License Agreement, CNRI hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python 1.6.1 alone or in any derivative version, provided, however, that CNRI's License Agreement and CNRI's notice of copyright, i.e., ``Copyright © 1995-2001 Corporation for National Research Initiatives; All Rights Reserved'' are retained in Python 1.6.1 alone or in any derivative version prepared by Licensee. Alternately, in lieu of CNRI's License Agreement, Licensee may substitute the following text (omitting the quotes): ``Python 1.6.1 is made available subject to the terms and conditions in CNRI's License Agreement. This Agreement together with Python 1.6.1 may be located on the Internet using the following unique, persistent identifier (known as a handle): 1895.22/1013. This Agreement may also be obtained from a proxy server on the Internet using the following URL: http://hdl.handle.net/1895.22/1013.''

  3. In the event Licensee prepares a derivative work that is based on or incorporates Python 1.6.1 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python 1.6.1.

  4. CNRI is making Python 1.6.1 available to Licensee on an ``AS IS'' basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  7. This License Agreement shall be governed by the federal intellectual property law of the United States, including without limitation the federal copyright law, and, to the extent such U.S. federal law does not apply, by the law of the Commonwealth of Virginia, excluding Virginia's conflict of law provisions. Notwithstanding the foregoing, with regard to derivative works based on Python 1.6.1 that incorporate non-separable material that was previously distributed under the GNU General Public License (GPL), the law of the Commonwealth of Virginia shall govern this License Agreement only as to issues arising under or with respect to Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between CNRI and Licensee. This License Agreement does not grant permission to use CNRI trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party.

  8. By clicking on the ``ACCEPT'' button where indicated, or by copying, installing or otherwise using Python 1.6.1, Licensee agrees to be bound by the terms and conditions of this License Agreement.

ACCEPT

CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2

Copyright © 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, The Netherlands. All rights reserved.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Stichting Mathematisch Centrum or CWI not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: A.1 History of the Up: A. 歴史とライセンス Next: B. 日本語訳について


B. 日本語訳について

  • B.1 このドキュメントについて
  • B.2 翻訳者一覧 (敬称略)
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: A.2 Terms and conditions Up: Macintoshモジュールリファレンス Next: B.1 このドキュメントについて


B.1 このドキュメントについて

この文書は、Pythonドキュメント翻訳プロジェクトによる Macintosh Library Modules Release の日本語訳版です。日本語訳に対する質問や提案などが ありましたら、Pythonドキュメント翻訳プロジェクトのメーリングリスト

http://www.python.jp/mailman/listinfo/python-doc-jp

または、プロジェクトのバグ管理ページ

http://sourceforge.jp/tracker/?atid=116&group_id=11&func=browse

までご報告ください。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: B. 日本語訳について Up: B. 日本語訳について Next: B.2 翻訳者一覧 (敬称略)


B.2 翻訳者一覧 (敬称略)

2.0 和訳: osawa <osawa at sm.rim.or.jp> (January, 2001)
2.3 差分和訳：sakito <sakito at s2.xrea.com>, Hiroyuki Yoshimura <DQB00103 at nifty.ne.jp> (October 10, 2003) 2.3.3 差分: Yasushi Masuda <y.masuda at acm.org>

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: B.1 このドキュメントについて Up: B. 日本語訳について Next: Module Index


Module Index

This index only lists modules documented in this manual. The Global Module Index lists all modules that are documented in this set of manuals.

Some module names are followed by an annotation indicating what platform they are available on.

aepack (Mac)
aetools (Mac)
aetypes (Mac)
applesingle (Mac)
autoGIL (Mac)
buildtools (Mac)
Carbon.AE (Mac)
Carbon.AH (Mac)
Carbon.App (Mac)
Carbon.CaronEvt (Mac)
Carbon.CF (Mac)
Carbon.CG (Mac)
Carbon.Cm (Mac)
Carbon.Ctl (Mac)
Carbon.Dlg (Mac)
Carbon.Evt (Mac)
Carbon.Fm (Mac)
Carbon.Folder (Mac)
Carbon.Help (Mac)
Carbon.List (Mac)
Carbon.Menu (Mac)
Carbon.Mlte (Mac)
Carbon.Qd (Mac)
Carbon.Qdoffs (Mac)
Carbon.Qt (Mac)
Carbon.Res (Mac)
Carbon.Scrap (Mac)
Carbon.Snd (Mac)
Carbon.TE (Mac)
Carbon.Win (Mac)
cfmfile (Mac)
ColorPicker (Mac)
EasyDialogs (Mac)
findertools (Mac)
FrameWork (Mac)
gensuitemodule (Mac)
ic (Mac)
icopen (Mac)
mac (Mac)
macerrors (Mac)
macfs (Mac)
MacOS (Mac)
macostools (Mac)
macpath
macresource (Mac)
MiniAEFrame (Mac)
mkcwproject (Mac)
Nac (Mac)
nsremote (Mac)
PixMapWrapper (Mac)
preferences (Mac)
py_resource (Mac)
pythonprefs (Mac)
quietconsole (Mac)
videoreader (Mac)
W (Mac)
waste (Mac)

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: B.2 翻訳者一覧 (敬称略) Up: Macintoshモジュールリファレンス Next: 索引


索引

_ | a | b | c | d | e | f | g | h | i | k | l | m | n | o | p | q | r | s | t | u | v | w

_ (アンダースコア)

_quit() (Application のメソッド)
_start() (TalkTo のメソッド)

A

aepack (標準 モジュール)
AEServer (MiniAEFrame 内の クラス)
AEText (aetypes 内の クラス)
aetools (標準 モジュール)
aetypes (標準 モジュール)
Alias Manager, Macintosh
AppleEvents, [リンク]
applesingle (標準 モジュール)
Application() (モジュール FrameWork)
as_pathname() (FSSpec のメソッド)
as_tuple() (FSSpec のメソッド)
AskFileForOpen() (モジュール EasyDialogs)
AskFileForSave() (モジュール EasyDialogs)
AskFolder() (モジュール EasyDialogs)
AskPassword() (モジュール EasyDialogs)
AskString() (モジュール EasyDialogs)
AskYesNoCancel() (モジュール EasyDialogs)
asyncevents() (Application のメソッド)
autoGIL (拡張 モジュール)
AutoGILError

B

Boolean (aetypes 内の クラス)
BUFSIZ (モジュール macostools)
buildtools (標準 モジュール)

C

callback() (AEServer のメソッド)
Carbon.AE (標準 モジュール)
Carbon.AH (標準 モジュール)
Carbon.App (標準 モジュール)
Carbon.CaronEvt (標準 モジュール)
Carbon.CF (標準 モジュール)
Carbon.CG (標準 モジュール)
Carbon.Cm (標準 モジュール)
Carbon.Ctl (標準 モジュール)
Carbon.Dlg (標準 モジュール)
Carbon.Evt (標準 モジュール)
Carbon.Fm (標準 モジュール)
Carbon.Folder (標準 モジュール)
Carbon.Help (標準 モジュール)
Carbon.List (標準 モジュール)
Carbon.Menu (標準 モジュール)
Carbon.Mlte (標準 モジュール)
Carbon.Qd (組み込み モジュール)
Carbon.Qdoffs (組み込み モジュール)
Carbon.Qt (標準 モジュール)
Carbon.Res (標準 モジュール)
Carbon.Scrap (標準 モジュール)
Carbon.Snd (標準 モジュール)
Carbon.TE (標準 モジュール)
Carbon.Win (標準 モジュール)
cfmfile (標準 モジュール)
close() (Window のメソッド)
ColorPicker (拡張 モジュール)
Comparison (aetypes 内の クラス)
ComponentItem (aetypes 内の クラス)
copy() (モジュール findertools)
copy() (モジュール macostools)
copytree() (モジュール macostools)
Creator (FInfo の属性)
curval (ProgressBar の属性)

D

data (Alias の属性)
data (FSSpec の属性)
DebugStr() (モジュール MacOS)
DialogWindow() (モジュール FrameWork)
distutils (組み込み モジュール)
do_activate() (IC のメソッド)
do_activate() (ScrolledWindow のメソッド)
do_char() (Application のメソッド)
do_contentclick() (Window のメソッド)
do_controlhit() (ControlsWindow のメソッド)
do_controlhit() (ScrolledWindow のメソッド)
do_dialogevent() (Application のメソッド)
do_itemhit() (DialogWindow のメソッド)
do_postresize() (ScrolledWindow のメソッド)
do_postresize() (Window のメソッド)
do_update() (Window のメソッド)

E

EasyDialogs (標準 モジュール)
Enum (aetypes 内の クラス)
enumsubst() (モジュール aetools)
Error
error

F

FindApplication() (モジュール macfs)
findertools (標準 モジュール)
FindFolder() (モジュール macfs)
FInfo() (モジュール macfs)
Flags (FInfo の属性)
Fldr (FInfo の属性)
FrameWork (標準 モジュール), [リンク]
FSSpec() (モジュール macfs)

G

gensuitemodule (標準 モジュール)
getabouttext() (Application のメソッド)
GetArgv() (モジュール EasyDialogs)
GetColor() (モジュール ColorPicker)
GetCreatorAndType() (モジュール MacOS)
GetCreatorType() (FSSpec のメソッド)
GetDates() (FSSpec のメソッド)
GetDirectory() (モジュール macfs)
GetErrorString() (モジュール MacOS)
GetFInfo() (FSSpec のメソッド)
GetInfo() (Alias のメソッド)
getscrollbarvalues() (ScrolledWindow のメソッド)
GetTicks() (モジュール MacOS)

H

HandleEvent() (モジュール MacOS)

I

IC (ic 内の クラス)
ic (組み込み モジュール)
icglue (組み込み モジュール)
icopen (標準 モジュール)
idle() (Application のメソッド)
inc() (ProgressBar のメソッド)
InsertionLoc (aetypes 内の クラス)
installaehandler() (AEServer のメソッド)
installAutoGIL() (モジュール autoGIL)
Internet Config
IntlText (aetypes 内の クラス)
IntlWritingCode (aetypes 内の クラス)
is_scriptable() (モジュール gensuitemodule)

K

環境変数
PYTHONPATH
keysubst() (モジュール aetools)
Keyword (aetypes 内の クラス)

L

label() (ProgressBar のメソッド)
launch() (モジュール findertools)
launchurl() (IC のメソッド)
launchurl() (モジュール ic)
linkmodel (モジュール MacOS)
Location (FInfo の属性)
Logical (aetypes 内の クラス)

M

mac (組み込み モジュール)
macerrors (標準 モジュール), [リンク]
macfs (標準 モジュール)
Macintosh Alias Manager
MacOS (組み込み モジュール)
macostools (標準 モジュール)
macpath (標準 モジュール)
macresource (標準 モジュール)
mainloop() (Application のメソッド)
makeusermenus() (Application のメソッド)
mapfile() (IC のメソッド)
mapfile() (モジュール ic)
maptypecreator() (IC のメソッド)
maptypecreator() (モジュール ic)
maxval (ProgressBar の属性)
Menu() (モジュール FrameWork)
MenuBar() (モジュール FrameWork)
MenuItem() (モジュール FrameWork)
Message() (モジュール EasyDialogs)
MiniAEFrame (標準 モジュール)
MiniApplication (MiniAEFrame 内の クラス)
mkalias() (モジュール macostools)
mkcwproject (標準 モジュール)
move() (モジュール findertools)

N

Nac (標準 モジュール)
NewAlias() (FSSpec のメソッド)
NewAliasMinimal() (FSSpec のメソッド)
NewAliasMinimalFromFullPath() (モジュール macfs)
NProperty (aetypes 内の クラス)
nsremote (標準 モジュール)

O

ObjectSpecifier (aetypes 内の クラス)
open() (DialogWindow のメソッド)
open() (Window のメソッド)
Open Scripting Architecture
openrf() (モジュール MacOS)
Ordinal (aetypes 内の クラス)
os (標準 モジュール)
os.path (標準 モジュール)

P

pack() (モジュール aepack)
packevent() (モジュール aetools)
parseurl() (IC のメソッド)
parseurl() (モジュール ic)
PixMapWrapper (標準 モジュール)
preferences (標準 モジュール)
Print() (モジュール findertools)
processfile() (モジュール gensuitemodule)
processfile_fromresource() (モジュール gensuitemodule)
ProgressBar() (モジュール EasyDialogs)
PromptGetFile() (モジュール macfs)
py_resource (標準 モジュール)
PYTHONPATH (environment variable)
PYTHONPATH (環境変数)
pythonprefs (標準 モジュール)

Q

QDPoint (aetypes 内の クラス)
QDRectangle (aetypes 内の クラス)
quietconsole (標準 モジュール)

R

Range (aetypes 内の クラス)
RawAlias() (モジュール macfs)
RawFSSpec() (モジュール macfs)
Resolve() (Alias のメソッド)
ResolveAliasFile() (モジュール macfs)
restart() (モジュール findertools)
RGBColor (aetypes 内の クラス)
runtimemodel (モジュール MacOS)

S

scalebarvalues() (ScrolledWindow のメソッド)
SchedParams() (モジュール MacOS)
scrollbar_callback() (ScrolledWindow のメソッド)
scrollbars() (ScrolledWindow のメソッド)
send() (TalkTo のメソッド)
Separator() (モジュール FrameWork)
set() (ProgressBar のメソッド)
setarrowcursor() (モジュール FrameWork)
SetCreatorAndType() (モジュール MacOS)
SetCreatorType() (FSSpec のメソッド)
SetDates() (FSSpec のメソッド)
SetEventHandler() (モジュール MacOS)
SetFInfo() (FSSpec のメソッド)
SetFolder() (モジュール macfs)
settypecreator() (IC のメソッド)
settypecreator() (モジュール ic)
setwatchcursor() (モジュール FrameWork)
shutdown() (モジュール findertools)
sleep() (モジュール findertools)
splash() (モジュール MacOS)
Standard File
StandardGetFile() (モジュール macfs)
StandardPutFile() (モジュール macfs)
StyledText (aetypes 内の クラス)
SubMenu() (モジュール FrameWork)
SysBeep() (モジュール MacOS)

T

TalkTo (aetools 内の クラス)
title() (ProgressBar のメソッド)
touched() (モジュール macostools)
Type (aetypes 内の クラス)
Type (FInfo の属性)

U

Unknown (aetypes 内の クラス)
unpack() (モジュール aepack)
unpackevent() (モジュール aetools)
Update() (Alias のメソッド)
updatescrollbars() (ScrolledWindow のメソッド)

V

videoreader (標準 モジュール)

W

W (標準 モジュール)
waste (標準 モジュール)
Window() (モジュール FrameWork)
windowbounds() (モジュール FrameWork)
WMAvailable() (モジュール MacOS)

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index
Previous: Module Index Up: Macintoshモジュールリファレンス Next: この文書について...


Python インタプリタの拡張と埋め込み

Guido van Rossum

PythonLabs
Email: docs@python.org

Fred L. Drake, Jr., editor

リリース 2.3.3
平成16年6月28日

日本語訳: Python ドキュメント翻訳プロジェクト

  • 序
  • 目次
  • 1. C や C++ による Python の拡張
    • 1.1 簡単な例
    • 1.2 幕間小話: エラーと例外
    • 1.3 例に戻る
    • 1.4 モジュールのメソッドテーブルと初期化関数
    • 1.5 コンパイルとリンク
    • 1.6 C から Python 関数を呼び出す
    • 1.7 拡張モジュール関数でのパラメタ展開
    • 1.8 拡張モジュール関数のキーワードパラメタ
    • 1.9 任意の値を構築する
    • 1.10 参照カウント法
      • 1.10.1 Python における参照カウント法
      • 1.10.2 所有権にまつわる規則
      • 1.10.3 薄氷
      • 1.10.4 NULL ポインタ
    • 1.11 C++での拡張モジュール作成
    • 1.12 拡張モジュールに C API を提供する
  • 2. 新しい型を定義する
    • 2.1 基本的なこと
      • 2.1.1 基本のサンプルにデータとメソッドを追加する
      • 2.1.2 データ属性をこまかく制御する
      • 2.1.3 循環ガベージコレクションをサポートする
    • 2.2 タイプメソッド
      • 2.2.1 最終化 (finalization) と解放
      • 2.2.2 Object Presentation
      • 2.2.3 属性を管理する
      • 2.2.4 オブジェクトの比較
      • 2.2.5 抽象的なプロトコルのサポート
      • 2.2.6 その他いろいろ
  • 3. distutils による C および C++ 拡張モジュールのビルド
    • 3.1 拡張モジュールの配布
  • 4. Windows 上での C および C++ 拡張モジュールのビルド
    • 4.1 型どおりのアプローチ
    • 4.2 Unix と Windows の相違点
    • 4.3 DLL 使用の実際
  • 5. 他のアプリケーションへの Python の埋め込み
    • 5.1 高水準の埋め込み
    • 5.2 超高水準の埋め込みから踏み出す: 概要
    • 5.3 純粋な埋め込み
    • 5.4 埋め込まれた Python の拡張
    • 5.5 C++による Python の埋め込み
    • 5.6 リンクに関する要件
  • A. バグ報告
  • B. 歴史とライセンス
    • B.1 History of the software
    • B.2 Terms and conditions for accessing or otherwise using Python
  • C. 日本語訳について
    • C.1 このドキュメントについて
    • C.2 翻訳者一覧 (敬称略)
  • この文書について...
Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Up: Python ドキュメントインデクス Next: 序


1. C や C++ による Python の拡張

C プログラムの書き方を知っているなら、Python に新たな組み込み モジュールを追加するのはきわめて簡単です。 この新たなモジュール、拡張モジュール (extention module) を使うと、Python が直接行えない二つのこと: 新しい組み込み オブジェクトの実装、そして全ての C ライブラリ関数と システムコールに対する呼び出し、ができるようになります。

拡張モジュールをサポートするため、Python API (Application Programmer's Interface) では一連の関数、マクロ および変数を提供していて、Python ランタイムシステムの ほとんどの側面へのアクセス手段を提供しています。 Python API は、ヘッダ "Python.h" をインクルードして C ソースに取り込みます。

拡張モジュールのコンパイル方法は、モジュールの用途やシステムの 設定方法に依存します; 詳細は後の章で説明します。

  • 1.1 簡単な例
  • 1.2 幕間小話: エラーと例外
  • 1.3 例に戻る
  • 1.4 モジュールのメソッドテーブルと初期化関数
  • 1.5 コンパイルとリンク
  • 1.6 C から Python 関数を呼び出す
  • 1.7 拡張モジュール関数でのパラメタ展開
  • 1.8 拡張モジュール関数のキーワードパラメタ
  • 1.9 任意の値を構築する
  • 1.10 参照カウント法
    • 1.10.1 Python における参照カウント法
    • 1.10.2 所有権にまつわる規則
    • 1.10.3 薄氷
    • 1.10.4 NULL ポインタ
  • 1.11 C++での拡張モジュール作成
  • 1.12 拡張モジュールに C API を提供する
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 目次 Up: Python インタプリタの拡張と埋め込み Next: 1.1 簡単な例


1.1 簡単な例

"spam" (Monty Python ファンの好物ですね) という名の拡張モジュールを 作成することにして、C ライブラリ関数 system() に対する Python インタフェースを作成したいとします。 1.1この関数は null で終端されたキャラクタ文字列を引数にとり、 整数を返します。この関数を以下のようにして Python から呼び出せるように したいとします:

>>> import spam
>>> status = spam.system("ls -l")

まずは spammodule.c を作成するところから始めます。 (伝統として、"spam" という名前のモジュールを作成する場合、 モジュールの実装が入った C ファイルを spammodule.c と 呼ぶことになっています; "spammify" のように長すぎる モジュール名の場合には、単にspammify.c にもできます。)

このファイルの最初の行は以下のようにします:

#include <Python.h>

これで、Python API を取り込みます (必要なら、モジュールの用途に 関する説明や、著作権表示を追加します)。 Python は、システムによっては標準ヘッダの定義に影響するような プリプロセッサ定義を行っているので、 Python.h は いずれの標準ヘッダよりも前にインクルードせねばなりません。

Python.h で定義されているユーザから可視のシンボルは、 全て接頭辞"Py" または "PY" が付いています。ただし、 標準ヘッダファイル内の定義は除きます。 簡単のためと、Python 内で広範に使うことになるという理由から、 "Python.h" はいくつかの標準ヘッダファイル: <stdio.h>、 <string.h>、 <errno.h>、および <stdlib.h> をインクルードしています。 後者のヘッダファイルがシステム上になければ、"Python.h" が 関数 malloc()、free() および realloc() を直接定義します。

次にファイルに追加する内容は、Python 式 "spam.system(string)"を評価する際に呼び出されることになる C 関数です (この関数を最終的にどのように呼び出すかは、後ですぐわかります):

static PyObject *
spam_system(PyObject *self, PyObject *args)
{
    char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = system(command);
    return Py_BuildValue("i", sts);
}

ここでは、Python の引数リスト (例えば、単一の式 "ls -l") から C 関数に渡す引数にそのまま変換しています。 C 関数は常に二つの引数を持ち、便宜的に self および args と呼ばれます。

self 引数は C 関数が Python の関数ではなく組み込みメソッド を実装している場合にのみ使われます。この例ではメソッドではなく 関数を定義しているので、 self は常に NULL ポインタになります。 (これは、インタプリタが二つの異なる形式の C 関数を理解しなくてもよく するためです。)

args 引数は、引数の入った Python タプルオブジェクトへの ポインタになります。タプル内の各要素は、呼び出しの際の引数リストに おける各引数に対応します。引数は Python オブジェクトです -- C 関数で引数を使って何かを行うには、オブジェクトから C の値に 変換せねばなりません。Python API の関数 PyArg_ParseTuple() は引数の型をチェックし、C の値に変換します。 PyArg_ParseTuple() はテンプレート文字列を使って、 引数オブジェクトの型と、変換された値を入れる C 変数の型を判別します。 これについては後で詳しく説明します。

PyArg_ParseTuple() は、全ての引数が正しい型を持っていて、 アドレス渡しされた各変数に各引数要素を保存したときに真 (非ゼロ) を 返します。この関数は不正な引数リストを渡すと偽 (ゼロ) を返します。 後者の場合、関数は適切な例外を送出するので、呼び出し側は (例にもあるように) すぐにNULL を返すようにしてください。

... インタフェースを作成したいとします。1.1
この関数へのインタフェースはすでに標準モジュール os にあります -- この関数を選んだのは、単純で直接的な例を示したいからです。
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1. C や C++ Up: 1. C や C++ Next: 1.2 幕間小話: エラーと例外


1.2 幕間小話: エラーと例外

Python インタプリタ全体を通して、一つの重要な取り決めがあります: それは、関数が処理に失敗した場合、例外状態をセットして、 エラーを示す値 (通常は NULL ポインタ) を返さねばならない、 ということです。 例外はインタプリタ内の静的なグローバル変数に保存されます; この値が NULL の場合、例外は何も起きていないことになります。 第二のグローバル変数には、例外の ``付属値 (associated value)'' (raise 文の第二引数) が入ります。 第三の値には、エラーの発生源が Python コード内だった場合に スタックトレースバック (stack traceback) が入ります。 これらの三つの変数は、それぞれ Python の変数 sys.exc_type、 sys.exc_value および sys.exc_traceback と等価な C の変数です (Python ライブラリリファレンス のsys モジュールに関する節を参照してください。) エラーがどのように受け渡されるかを理解するには、これらの変数に ついてよく知っておくことが重要です。

Python API では、様々な型の例外をセットするための関数をいくつか 定義しています。

もっともよく用いられるのはPyErr_SetString() です。 引数は例外オブジェクトと C 文字列です。例外オブジェクトは 通常、PyExc_ZeroDivisionError のような定義済みのオブジェクト です。 C 文字列はエラーの原因を示し、Python 文字列オブジェクトに変換されて 例外の ``付属値'' に保存されます。

もう一つ有用な関数としてPyErr_SetFromErrno() があります。 この関数は引数に例外だけをとり、付属値はグローバル変数 errno から構築します。もっとも汎用的な関数はPyErr_SetObject() で、 二つのオブジェクト、例外と付属値を引数にとります。これら関数に 渡すオブジェクトにはPy_INCREF() を使う必要はありません。

例外がセットされているかどうかは、PyErr_Occurred() を使って非破壊的に調べられます。この関数は現在の例外オブジェクトを 返します。例外が発生していない場合には NULL を返します。 通常は、関数の戻り値からエラーが発生したかを判別できるはずなので、 PyErr_Occurred() を呼び出す必要はありません。

関数g を呼び出すf が、前者の関数の呼び出しに失敗したことを 検出すると、f 自体はエラー値 (大抵は NULL や -1) を返さねばなりません。しかし、PyErr_*() 関数群の いずれかを呼び出す必要は ありません -- なぜなら、g がすでに呼び出しているからです。次いでf を呼び出したコードも エラーを示す値を自らを呼び出したコード に返すことになりますが、 同様にPyErr_*() は呼び出しません。 以下同様に 続きます -- エラーの最も詳しい原因は、最初にエラーを検出した 関数がすでに報告しているからです。エラーが Python インタプリタの メインループに到達すると、現在実行中の Python コードは一時停止 し、 Python プログラマが指定した例外ハンドラを探し出そうとします。

(モジュールがPyErr_*() 関数をもう一度呼び出して、より詳細な エラーメッセージを提供するような状況があります。このような状況では そうすべきです。とはいえ、一般的な規則としては、PyErr_*() を何度も呼び出す必要はなく、ともすればエラーの原因に関する情報を 失う結果になりがちです: これにより、ほとんどの操作が様々な理由から 失敗するかもしれません)

ある関数呼び出しでの処理の失敗によってセットされた例外を無視するには、 PyErr_Clear() を呼び出して例外状態を明示的に消去 しなくてはなりません。 エラーをインタプリタには渡したくなく、自前で (何か他の作業を行ったり、 何も起こらなかったかのように見せかけるような) エラー処理を完全に 行う場合にのみ、PyErr_Clear() を呼び出すようにすべきです。

malloc() の呼び出し失敗は、常に例外にしなくては
なりません -- malloc() (または realloc())
を直接呼び出しているコードは、PyErr_NoMemory() を
呼び出して、失敗を示す値を返さねばなりません。オブジェクトを
生成する全ての関数 (例えば PyInt_FromLong()) は
PyErr_NoMemory() の呼び出しを済ませてしまうので、
この規則が関係するのは直接 malloc() を呼び出す
コードだけです。

また、PyArg_ParseTuple() という重要な例外を除いて、 整数の状態コードを返す関数はたいてい、Unix のシステムコール と同じく、処理が成功した際にはゼロまたは正の値を返し、 失敗した場合には -1 を返します。

最後に、エラー標示値を返す際に、(エラーが発生するまでに既に 生成してしまったオブジェクトに対してPy_XDECREF() や Py_DECREF() を呼び出して) ごみ処理を注意深く 行ってください!

どの例外を返すかの選択は、ユーザに完全にゆだねられます。 PyExc_ZeroDivisionError のように、全ての組み込みの Python 例外には対応する宣言済みの C オブジェクトがあり、直接利用できます。 もちろん、例外の選択は賢く行わねばなりません -- ファイルが開けなかったことを表すのにPyExc_TypeError を使ったりはしないでください (この場合はおそらくPyExc_IOError の方にすべきでしょう)。 引数リストに問題がある場合には、PyArg_ParseTuple() はたいてい PyExc_TypeError を送出します。 引数の値が特定の範囲を超えていたり、その他の満たすべき条件を満たさ なかった場合には、PyExc_ValueError が適切です。

モジュール固有の新たな例外も定義できます。定義するには、通常は ファイルの先頭部分に静的なオブジェクト変数の宣言を行います:

static PyObject *SpamError;

そして、モジュールの初期化関数 (initspam()) の中で、例外オブジェクトを使って初期化します (ここでは エラーチェックを省略しています):

PyMODINIT_FUNC
initspam(void)
{
    PyObject *m;

    m = Py_InitModule("spam", SpamMethods);

    SpamError = PyErr_NewException("spam.error", NULL, NULL);
    Py_INCREF(SpamError);
    PyModule_AddObject(m, "error", SpamError);
}

Python レベルでの例外オブジェクトの名前は spam.error になることに注意してください。 PyErr_NewException() 関数は、Python ライブラリリファレンス の ``組み込み例外'' の節に述べられているException クラスを基底クラスに持つ例外クラスも作成できます (NULLの代わりに他のクラスを渡した場合は別です)。

SpamError 変数は、新たに生成された例外クラスへの参照を 維持することにも注意してください; これは意図的な仕様です! 外部のコードが例外オブジェクトをモジュールから除去できるため、 モジュールから新たに作成した例外クラスが見えなくなり、 SpamError がぶら下がりポインタ (dangling pointer) になってしまわないようにするために、クラスに対する参照を所有して おかねばなりません。 もしSpamError がぶら下がりポインタになってしまうと、 C コードが例外を送出しようとしたときにコアダンプや意図しない副作用を 引き起こすことがあります。

この例にある PyMODINIT_FUNC の使い方については後で議論します。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.1 簡単な例 Up: 1. C や C++ Next: 1.3 例に戻る


1.3 例に戻る

先ほどの関数の例に戻ると、今度は以下の実行文を理解できるはずです:

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;

この実行文は、PyArg_ParseTuple() がセットする例外 によって、引数リストに何らかのエラーが生じたときにNULL (オブジェクトへのポインタを返すタイプの関数におけるエラー標示値) を返します。エラーでなければ、引数として与えた文字列値はローカル な変数 command にコピーされています。 この操作はポインタ代入であり、ポインタが指している文字列に対して 変更が行われるとは想定されていません (従って、標準 C では、 変数 command は "const char* command" として 適切に定義せねばなりません)。

次の文では、PyArg_ParseTuple() で得た文字列を 渡して Unix 関数 system() を呼び出しています:

    sts = system(command);

spam.system() は sts を Python オブジェクト として返さねばなりません。これには、PyArg_ParseTuple() の逆ともいうべき関数Py_BuildValue() を使います: Py_BuildValue() は書式化文字列と任意の数の C の値を 引数にとり、新たな Python オブジェクトを返します。 Py_BuildValue() に関する詳しい情報は後で示します。

    return Py_BuildValue("i", sts);

上の場合では、Py_BuildValue() は整数オブジェクトを 返します。(そう、整数ですら、 Python においてはヒープ上の オブジェクトなのです! )

何ら有用な値を返さない関数 (void を返す関数) に 対応する Python の関数はNone を返さねばなりません。 関数に None を返させるには、以下のような慣用句を使います:

    Py_INCREF(Py_None);
    return Py_None;

Py_None は特殊な Pyhton オブジェクトである None に 対応する C での名前です。これまで見てきたようにほとんどのコンテキスト で ``エラー'' を意味する NULL ポインタとは違い、None は純粋な Python のオブジェクトです。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.2 幕間小話: エラーと例外 Up: 1. C や C++ Next: 1.4 モジュールのメソッドテーブルと初期化関数


1.4 モジュールのメソッドテーブルと初期化関数

さて、前に約束したように、spam_system() Python プログラム からどうやって呼び出すかをこれから示します。まずは、関数名とアドレスを ``メソッドテーブル (method table)'' に列挙する必要があります:

static PyMethodDef SpamMethods[] = {
    ...
    {"system",  spam_system, METH_VARARGS,
     "Execute a shell command."},
    ...
    {NULL, NULL, 0, NULL}        /* Sentinel */
};

リスト要素の三つ目のエントリ ("METH_VARARGS") に注意してください。 このエントリは、C 関数が使う呼び出し規約をインタプリタに教えるための フラグです。通常この値は"METH_VARARGS" か "METH_VARARGS | METH_KEYWORDS" のはずです; 0 は旧式のPyArg_ParseTuple() の変化形が使われることを 意味します。

"METH_VARARGS" だけを使う場合、C 関数は、Python レベルでの引数が PyArg_ParseTuple() が受理できるタプルの形式で渡されるもの と想定しなければなりません; この関数についての詳細は下で説明します。

関数にキーワード引数が渡されることになっているのなら、 第三フィールドにMETH_KEYWORDS ビットをセットできます。 この場合、C 関数は第三引数に "PyObject *" を受理するように せねばなりません。このオブジェクトは、キーワード引数の辞書に なります。こうした関数で引数を解釈するには、 PyArg_ParseTupleAndKeywords() を使ってください。

メソッドテーブルは、モジュールの初期化関数内でインタプリタに 渡さねばなりません。初期化関数はモジュールの名前を name としたときに initname() という名前でなければ ならず、モジュールファイル内で定義されているもののうち、唯一の 非static 要素でなければなりません:

PyMODINIT_FUNC
initspam(void)
{
    (void) Py_InitModule("spam", SpamMethods);
}

PyMODINIT_FUNC は関数の戻り値を void になるように宣言し、 プラットフォーム毎に必要とされる、特有のリンク宣言 (linkage declaration) を定義すること、さらに C++ の場合には関数を extern "C" に 宣言することに注意してください。

Python プログラムがモジュール spam を初めて import するとき、initspam() が呼び出されます。 (Python の埋め込みに関するコメントは下記を参照してください。) initspam() は Py_InitModule() を呼び出して ``モジュールオブジェクト'' を生成し (オブジェクトは"spam" を キーとして辞書 sys.modules に挿入されます)、第二引数として 与えたメソッドテーブル (PyMethodDef 構造体の配列) の情報に 基づいて、組み込み関数オブジェクトを新たなモジュールに挿入していきます。 Py_InitModule() は、自らが生成した (この段階ではまだ未使用の) モジュールオブジェクトへのポインタを返します。 Py_InitModule() は、モジュールを満足に初期化できなかった場合、 致命的エラーで中断するため、この関数の呼び出し側がエラーをチェックする 必要はありません。

Python を埋め込む場合には、_PyImport_Inittab テーブルの エントリ内に initspam() がない限り、initspam() は自動的には呼び出されません。この問題を解決する最も簡単な方法は、 Py_Initialize() や PyMac_Initialize() を 呼び出した後に initspam() を直接呼び出し、 静的にリンクしておいたモジュールを静的に初期化してしまうというものです:

int
main(int argc, char *argv[])
{
    /* Python インタプリタに argv[0] を渡す */
    Py_SetProgramName(argv[0]);

    /* Python インタプリタを初期化する。必ず必要。 */
    Py_Initialize();

    /* 静的モジュールを追加する */
    initspam();

Python ソース配布物中の Demo/embed/demo.c ファイル内 に例があります。

注意: 単一のプロセス内 (または fork() 後の exec() が介入していない状態) における複数のインタプリタにおいて、 sys.module から エントリを除去したり新たなコンパイル済みモジュールを import したりすると、拡張モジュールによっては問題を生じることがあります。 拡張モジュールの作者は、内部データ構造を初期化する際にはよくよく 用心すべきです。また、reload() 関数を拡張モジュールに 対して利用でき、この場合はモジュール初期化関数 (initspam()) は呼び出されますが、モジュールが動的にロード可能なオブジェクトファイル (Unixでは .so、Windows では .dll) から読み出された 場合にはモジュールファイルを再読み込みしないので注意してください。

より実質的なモジュール例は、Python ソース配布物に Modules/xxmodule.c という名前で入っています。 このファイルはテンプレートとしても利用できますし、単に例としても 読めます。ソース配布物や Windows にインストールされた Python に入っている modulator.py では、拡張モジュールで実装しなければならない 関数やオブジェクトを宣言し、実装部分を埋めて作成するためのテンプレート を生成できるような、簡単なグラフィカルユーザインタフェースを 提供しています。 このスクリプトはTools/modulator/ ディレクトリにあります; 詳しくはディレクトリ内の README ファイルを参照してください。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.3 例に戻る Up: 1. C や C++ Next: 1.5 コンパイルとリンク


1.5 コンパイルとリンク

新しい拡張モジュールを使えるようになるまで、まだ二つの作業: コンパイルと、Python システムへのリンク、が残っています。 動的読み込み (dynamic loading) を使っているのなら、作業の詳細は 自分のシステムが使っている動的読み込みの形式によって変わるかも しれません; 詳しくは、拡張モジュールのビルドに関する章 (3 章) や、Windows におけるビルドに関係する追加情報の章 (4 章) を参照してください。

動的読み込みを使えなかったり、モジュールを常時 Python インタプリタの 一部にしておきたい場合には、インタプリタのビルド設定を変更して再ビルド しなければならなくなるでしょう。Unixでは、幸運なことにこの作業は とても単純です: 単に自作のモジュールファイル (例えば spammodule.c ) を展開したソース配布物の Modules/ ディレクトリに置き、 Modules/Setup.local に自分のファイルを 説明する以下の一行:

spam spammodule.o

を追加して、トップレベルのディレクトリで make を実行して、 インタプリタを再ビルドするだけです。 Modules/ サブディレクトリでも make を実行できますが、 前もって `make Makefile' を実行して Makefile ｗ再ビルドしておかなければならりません。(この作業は Setup ファイルを変更するたびに必要です。)

モジュールが別のライブラリとリンクされている必要がある場合、 ライブラリも設定ファイルに列挙できます。例えば以下のようにします:

spam spammodule.o -lX11

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.4 モジュールのメソッドテーブルと初期化関数 Up: 1. C や C++ Next: 1.6 C から Python


1.6 C から Python 関数を呼び出す

これまでは、Python からの C 関数の呼び出しに重点を置いて 述べてきました。ところでこの逆: C からの Python 関数の呼び出し もまた有用です。 とりわけ、いわゆる ``コールバック'' 関数をサポートするような ライブラリを作成する際にはこの機能が便利です。 ある C インタフェースがコールバックを利用している場合、 同等の機能を提供する Python コードでは、しばしば Python プログラマに コールバック機構を提供する必要があります; このとき実装では、 C で書かれたコールバック関数から Python で書かれたコールパック関数 を呼び出すようにする必要があるでしょう。 もちろん、他の用途も考えられます。

幸運なことに、Python インタプリタは簡単に再帰呼び出しでき、 Python 関数を呼び出すための標準インタフェースもあります。 (Python パーザを特定の入力文字を使って呼び出す方法について 詳説するつもりはありません -- この方法に興味があるなら、 Python ソースコードの Python/pythonmain.c にある、 コマンドラインオプション-c の実装を見てください)

Python 関数の呼び出しは簡単です。まず、C のコードに対して コールバックを登録しようとする Python プログラムは、何らかの方法で Python の関数オブジェクトを渡さねばなりません。このために、 コールバック登録関数 (またはその他のインタフェース) を提供 せねばなりません。このコールバック登録関数が呼び出された際に、 引き渡された Python 関数オブジェクトへのポインタをグローバル変数に -- あるいは、どこか適切な場所に -- 保存します (関数オブジェクトをPy_INCREF() するようよく注意して ください!)。例えば、以下のような関数がモジュールの一部になって いることでしょう:

static PyObject *my_callback = NULL;

static PyObject *
my_set_callback(PyObject *dummy, PyObject *args)
{
    PyObject *result = NULL;
    PyObject *temp;

    if (PyArg_ParseTuple(args, "O:set_callback", &temp)) {
        if (!PyCallable_Check(temp)) {
            PyErr_SetString(PyExc_TypeError, "parameter must be callable");
            return NULL;
        }
        Py_XINCREF(temp);         /* 新たなコールバックへの参照を追加 */
        Py_XDECREF(my_callback);  /* 以前のコールバックを捨てる */
        my_callback = temp;       /* 新たなコールバックを記憶 */
        /* "None" を返す際の定型句 */
        Py_INCREF(Py_None);
        result = Py_None;
    }
    return result;
}

この関数はMETH_VARARGS フラグを使ってインタプリタに 登録せねばなりません; METH_VARARGS フラグについては、 1.4 節、 ``モジュールのメソッドテーブルと初期化関数'' で説明しています。 PyArg_ParseTuple() 関数とその引数については、 1.7 節、 ``拡張モジュール関数でのパラメタ展開'' に記述しています。

Py_XINCREF() およびPy_XDECREF() は、 オブジェクトに対する参照カウントをインクリメント/デクリメントする ためのマクロで、NULL ポインタが渡されても安全に操作できる 形式です (とはいえ、上の流れではtemp がNULL になることは ありません)。 これらのマクロと参照カウントについては、1.10 節、 ``参照カウント'' で説明しています。

その後、コールバック関数を呼び出す時が来たら、C 関数 PyEval_CallObject() を呼び出します。 この関数には二つの引数: Python 関数と Python 関数の引数リストがあり、 いずれも任意の Python オブジェクトを表すポインタ型です。 引数リストは常にタプルオブジェクトでなければならず、その長さは 引数の数になります。Python 関数を引数なしで呼び出すのなら 空のタプルを渡します; 単一の引数で関数を呼び出すのなら、 単要素 (singleton) のタプルを渡します。 Py_BuildValue() の書式化文字列中に、ゼロ個または 一個以上の書式化コードが入った丸括弧がある場合、この関数は タプルを返します。以下に例を示します:

    int arg;
    PyObject *arglist;
    PyObject *result;
    ...
    arg = 123;
    ...
    /* ここでコールバックを呼ぶ */
    arglist = Py_BuildValue("(i)", arg);
    result = PyEval_CallObject(my_callback, arglist);
    Py_DECREF(arglist);

PyEval_CallObject() は Python オブジェクトへのポインタを 返します; これは Python 関数からの戻り値になります。 PyEval_CallObject() は、引数に対して ``参照カウント中立 (reference-count-neutral)'' です。 上の例ではタプルを生成して引数リストとして提供しており、この タプルは呼び出し直後に Py_DECREF() しています。

PyEval_CallObject() は ``新しい'' 戻り値を返します: 戻り値が表すオブジェクトは新たなオブジェクトか、既存のオブジェクトの 参照カウントをインクリメントしたものです。従って、このオブジェクトを グローバル変数に保存したいのでないかぎり、 たとえこの戻り値に興味がなくても (むしろ、そうであればなおさら!) 何がしかの方法で戻り値オブジェクトを Py_DECREF() しなければなりません。

とはいえ、戻り値をPy_DECREF() する前には、値が NULL でないかチェックしておくことが重要です。もし NULLなら、呼び出した Python 関数は例外を送出して終了させられています。 PyEval_CallObject() を呼び出しているコード自体もまた Python から呼び出されているのであれば、今度は C コードが自分を 呼び出している Python コードにエラー標示値を返さねばなりません。 それにより、インタプリタはスタックトレースを出力したり、例外を 処理するための Python コードを呼び出したりできます。 例外の送出が不可能だったり、したくないのなら、 PyErr_Clear() を呼んで例外を消去しておかねばなりません。 例えば以下のようにします:

    if (result == NULL)
        return NULL; /* エラーを返す */
    ...use result...
    Py_DECREF(result);

Python コールバック関数をどんなインタフェースにしたいかによっては、 引数リストをPyEval_CallObject() に与えなければ ならない場合もあります。 あるケースでは、コールバック関数を指定したのと同じインタフェース を介して、引数リストも渡されているかもしれません。 また別のケースでは、新しいタプルを構築して引数リストを渡さねば ならないかもしれません。この場合最も簡単なのは Py_BuildValue() を呼ぶやり方です。 例えば、整数のイベントコードを渡したければ、以下のようなコードを 使うことになるでしょう:

    PyObject *arglist;
    ...
    arglist = Py_BuildValue("(l)", eventcode);
    result = PyEval_CallObject(my_callback, arglist);
    Py_DECREF(arglist);
    if (result == NULL)
        return NULL; /* エラーを返す */
    /* 場合によってはここで結果を使うかもね */
    Py_DECREF(result);

"Py_DECREF(arglist)" が呼び出しの直後、エラーチェックよりも前に 置かれていることに注意してください! また、厳密に言えば、このコードは 完全ではありません: Py_BuildValue() はメモリ不足に おちいるかもしれず、チェックしておくべきです。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.5 コンパイルとリンク Up: 1. C や C++ Next: 1.7 拡張モジュール関数でのパラメタ展開


1.7 拡張モジュール関数でのパラメタ展開

PyArg_ParseTuple() は、以下のように宣言されています:

int PyArg_ParseTuple(PyObject *arg, char *format, ...);

引数arg は C 関数から Python に渡される引数リストが入った タプルオブジェクトでなければなりません。 format 引数は書式化文字列で、 Python/C API リファレンスマニュアル の ``引数の解釈と値の構築'' で解説されている書法に従わねばなりません。 残りの引数は、それぞれの変数のアドレスで、書式化文字列から 決まる型になっていなければなりません。

PyArg_ParseTuple() は Python 側から与えられた引数が 必要な型になっているか調べるのに対し、PyArg_ParseTuple() は呼び出しの際に渡された C 変数のアドレスが有効な値を持つか調べ られないことに注意してください: ここで間違いを犯すと、コードが クラッシュするかもしれませんし、少なくともでたらめなビットを メモリに上書きしてしまいます。慎重に!

呼び出し側に提供されるオブジェクトへの参照はすべて 借用 参照 (borrowed reference) になります; これらのオブジェクトの参照 カウントをデクリメントしてはなりません!

以下にいくつかの呼び出し例を示します:

    int ok;
    int i, j;
    long k, l;
    char *s;
    int size;

    ok = PyArg_ParseTuple(args, ""); /* 引数なし */
        /* Python での呼び出し: f() */

    ok = PyArg_ParseTuple(args, "s", &s); /* 文字列 */
        /* Python での呼び出し例: f('whoops!') */

    ok = PyArg_ParseTuple(args, "lls", &k, &l, &s);
        /* 二つの long と文字列 */
        /* Python での呼び出し例: f(1, 2, 'three') */

    ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);
        /* 二つの int と文字列、文字列のサイズも返す */
        /* Python での呼び出し例: f((1, 2), 'three') */

    {
        char *file;
        char *mode = "r";
        int bufsize = 0;
        ok = PyArg_ParseTuple(args, "s|si", &file, &mode, &bufsize);
        /* 文字列、オプションとして文字列がもう一つと整数が一つ */
        /* Python での呼び出し例:
           f('spam')
           f('spam', 'w')
           f('spam', 'wb', 100000) */
    }

    {
        int left, top, right, bottom, h, v;
        ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
                 &left, &top, &right, &bottom, &h, &v);
        /* 矩形と点を表現するデータ */
        /* Python での呼び出し例:
           f(((0, 0), (400, 300)), (10, 10)) */
    }

    {
        Py_complex c;
        ok = PyArg_ParseTuple(args, "D:myfunction", &c);
        /* 複素数。エラー発生時用に関数名も指定 */
        /* Python での呼び出し例: myfunction(1+2j) */
    }

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.6 C から Python Up: 1. C や C++ Next: 1.8 拡張モジュール関数のキーワードパラメタ


1.8 拡張モジュール関数のキーワードパラメタ

PyArg_ParseTupleAndKeywords() は、以下のように宣言されています:

int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
                                char *format, char *kwlist[], ...);

arg と format パラメタはPyArg_ParseTuple() のものと同じです。kwdict パラメタはキーワード引数の入った 辞書で、 Python ランタイムシステムから第三パラメタとして受け取ります。 kwlist パラメタは各パラメタを識別するための文字列からなる、 NULL終端されたリストです; 各パラメタ名は format 中の 型情報に対して左から右の順に照合されます。

成功するとPyArg_ParseTupleAndKeywords() は真を返し、 それ以外の場合には適切な例外を送出して偽を返します。

注意: キーワード引数を使っている場合、タプルは入れ子にして使えません! kwlist 内に存在しないキーワードパラメタが渡された場合、 TypeError の送出を引き起こします。

以下にキーワードを使ったモジュール例を示します。これは Geoff Philbrick (philbrick@hks.com) によるプログラム例を もとにしています:

#include "Python.h"

static PyObject *
keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
{
    int voltage;
    char *state = "a stiff";
    char *action = "voom";
    char *type = "Norwegian Blue";

    static char *kwlist[] = {"voltage", "state", "action", "type", NULL};

    if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist,
                                     &voltage, &state, &action, &type))
        return NULL;

    printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",
           action, voltage);
    printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);

    Py_INCREF(Py_None);

    return Py_None;
}

static PyMethodDef keywdarg_methods[] = {
    /* PyCFunction の値は PyObject* パラメタを二つだけしか引数に
     * 取らないが、 keywordarg_parrot() は三つとるので、キャストが
     * 必要。
     */
    {"parrot", (PyCFunction)keywdarg_parrot, METH_VARARGS | METH_KEYWORDS,
     "Print a lovely skit to standard output."},
    {NULL, NULL, 0, NULL}   /* センティネル値 */
};

void
initkeywdarg(void)
{
  /* モジュールを作成して関数を追加する */
  Py_InitModule("keywdarg", keywdarg_methods);
}

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.7 拡張モジュール関数でのパラメタ展開 Up: 1. C や C++ Next: 1.9 任意の値を構築する


1.9 任意の値を構築する

Py_BuildValue() はPyArg_ParseTuple() の 対極に位置するものです。この関数は以下のように定義されています:

PyObject *Py_BuildValue(char *format, ...);

Py_BuildValue() は、PyArg_ParseTuple() の認識する一連の書式化単位に似た書式化単位を認識します。ただし (関数への出力ではなく、入力に使われる) 引数はポインタではなく、 ただの値でなければなりません。 Python から呼び出された C 関数が返す値として適切な、新たな Python オブジェクトを返します。

PyArg_ParseTuple() とは一つ違う点があります: PyArg_ParseTuple() は第一引数をタプルにする必要があります (Python の引数リストは内部的には常にタプルとして表現されるからです) が、Py_BuildValue() はタプルを生成するとは限りません。 Py_BuildValue() は書式化文字列中に書式化単位が 二つかそれ以上入っている場合にのみタプルを構築します。 書式化文字列が空なら、None を返します。きっかり一つの 書式化単位なら、その書式化単位が記述している何らかのオブジェクト になります。サイズが 0 や 1 のタプル返させたいのなら、書式化 文字列を丸括弧で囲います。

以下に例を示します (左に呼び出し例を、右に構築される Python 値を示します):

    Py_BuildValue("")                        None
    Py_BuildValue("i", 123)                  123
    Py_BuildValue("iii", 123, 456, 789)      (123, 456, 789)
    Py_BuildValue("s", "hello")              'hello'
    Py_BuildValue("ss", "hello", "world")    ('hello', 'world')
    Py_BuildValue("s#", "hello", 4)          'hell'
    Py_BuildValue("()")                      ()
    Py_BuildValue("(i)", 123)                (123,)
    Py_BuildValue("(ii)", 123, 456)          (123, 456)
    Py_BuildValue("(i,i)", 123, 456)         (123, 456)
    Py_BuildValue("[i,i]", 123, 456)         [123, 456]
    Py_BuildValue("{s:i,s:i}",
                  "abc", 123, "def", 456)    {'abc': 123, 'def': 456}
    Py_BuildValue("((ii)(ii)) (ii)",
                  1, 2, 3, 4, 5, 6)          (((1, 2), (3, 4)), (5, 6))

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.8 拡張モジュール関数のキーワードパラメタ Up: 1. C や C++ Next: 1.10 参照カウント法


1.10 参照カウント法

C や C++のような言語では、プログラマはヒープ上のメモリを 動的に確保したり解放したりする責任があります。 こうした作業は C では関数malloc() やfree() で 行います。C++では本質的に同じ意味で演算子new や delete が使われます。そこで、以下の議論は C の場合に限定 して行います。

malloc() が確保する全てのメモリブロックは、最終的には free() を厳密に一度だけ呼び出して利用可能メモリのプールに 戻さねばなりません。そこで、適切な時にfree() を呼び出す ことが重要になります。 あるメモリブロックに対して、free() を呼ばなかったにも かかわらずそのアドレスを忘却してしまうと、ブロックが占有しているメモリ はプログラムが終了するまで再利用できなくなります。 これはメモリリーク(memory leak) と呼ばれています。 逆に、プログラムがあるメモリブロックに対してfree() を 呼んでおきながら、そのブロックを使い続けようとすると、 別の malloc() 呼び出しによって行われるブロックの再利用 と衝突を起こします。これは解放済みメモリの使用 (using freed memory) と呼ばれます。これは初期化されていないデータに対する参照と同様の よくない結果 -- コアダンプ、誤った参照、不可解なクラッシュ -- を引き起こします。

よくあるメモリリークの原因はコード中の普通でない処理経路です。 例えば、ある関数があるメモリブロックを確保し、何らかの計算を行って、 再度ブロックを解放するとします。さて、関数の要求仕様を変更して、 計算に対するテストを追加すると、エラー条件を検出し、関数の途中で 処理を戻すようになるかもしれません。 この途中での終了が起きるとき、確保されたメモリブロックは解放し忘れ やすいのです。コードが後で追加された場合には特にそうです。 このようなメモリリークが一旦紛れ込んでしまうと、長い間検出 されないままになることがよくあります: エラーによる関数の終了は、 全ての関数呼び出しのに対してほんのわずかな割合しか起きず、その一方で ほとんどの近代的な計算機は相当量の仮想記憶を持っているため、 メモリリークが明らかになるのは、長い間動作していたプロセスが リークを起こす関数を何度も使った場合に限られるからです。 従って、この種のエラーを最小限にとどめるようなコーディング規約や戦略を 設けて、不慮のメモリリークを避けることが重要なのです。

Python はmalloc() やfree() を非常によく利用 するため、メモリリークの防止に加え、解放されたメモリの使用を 防止する戦略が必要です。このために選ばれたのが 参照カウント法 (reference counting) と呼ばれる手法です。 参照カウント法の原理は簡単です: 全てのオブジェクトには カウンタがあり、オブジェクトに対する参照がどこかに保存されたら カウンタをインクリメントし、オブジェクトに対する参照が削除されたら デクリメントします。カウンタがゼロになったら、オブジェクトへの 最後の参照が削除されたことになり、オブジェクトは解放されます。

もう一つの戦略は自動ガベージコレクション (automatic garbage collection) と呼ばれています。 (参照カウント法はガベージコレクション戦略の一つとして挙げられることも あるので、二つを区別するために筆者は ``自動 (automatic)'' を使っています。) 自動ガベージコレクションの大きな利点は、ユーザがfree() を明示的によばなくてよいことにあります。 (速度やメモリの有効利用性も利点として主張されています -- が、 これは確たる事実ではありません。) C における自動ガベージコレクションの欠点は、真に可搬性のある ガベージコレクタが存在しないということです。それに対し、 参照カウント法は可搬性のある実装ができます (malloc() やfree() を利用できるのが前提です -- C 標準は これを保証しています)。 いつの日か、十分可搬性のあるガベージコレクタが C で使えるように なるかもしれませんが、それまでは参照カウント法でやっていく以外には ないのです。

Python では、伝統的な参照カウント法の実装を行っている一方で、 参照の循環を検出するために働く循環参照検出機構 (cycle detector) も提供しています。循環参照検出機構のおかげで、直接、間接に かかわらず循環参照の生成を気にせずにアプリケーションを構築できます; というのも、参照カウント法だけを使ったガベージコレクション実装に とって循環参照は弱点だからです。 循環参照は、(間接参照の場合も含めて) 相互への参照が入ったオブジェクト から形成されるため、循環内のオブジェクトは各々非ゼロの参照カウント を持ちます。典型的な参照カウント法の実装では、たとえ循環参照を形成する オブジェクトに対して他に全く参照がないとしても、 循環参照内のどのオブジェクトに属するメモリも再利用できません。

循環参照検出機構は、ごみとなった循環参照を検出し、Python で実装 された後始末関数 (finalizer、__del__() メソッド) が定義 されていないかぎり、それらのメモリを再利用できます。 後始末関数がある場合、検出機構は検出した循環参照を gc モジュール に (具体的にはこのモジュールの garbage 変数内) に公開します。gc モジュールではまた、 検出機構 (collect() 関数) を実行する方法や設定用の インタフェース、実行時に検出機構を無効化する機能も公開しています。 循環参照検出機構はオプションの機構とみなされています; デフォルトで入ってはいますが、Unix プラットフォーム (Mac OS X も含みます) ではビルド時にconfigure スクリプトの --without-cycle-gc オプションを使って、 他のプラットフォームではpyconfig.h ヘッダのWITH_CYCLE_GC 定義をはずして無効にできます。 こうして循環参照検出機構を無効化すると、gc モジュールは 利用できなくなります。

  • 1.10.1 Python における参照カウント法
  • 1.10.2 所有権にまつわる規則
  • 1.10.3 薄氷
  • 1.10.4 NULL ポインタ
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.9 任意の値を構築する Up: 1. C や C++ Next: 1.10.1 Python における参照カウント法


1.10.1 Python における参照カウント法

Python には、参照カウントのインクリメントやデクリメントを処理する二つの マクロ、Py_INCREF(x) と Py_DECREF(x) があります。 Py_DECREF() は、参照カウントがゼロに到達した際に、 オブジェクトのメモリ解放も行います。 柔軟性を持たせるために、free() を直接呼び出しません -- その代わりにオブジェクトの型オブジェクト (type object) を介します。このために (他の目的もありますが)、全てのオブジェクトには 自身の型オブジェクトに対するポインタが入っています。

さて、まだ重大な疑問が残っています: いつ Py_INCREF(x) や Py_DECREF(x) を使えばよいのでしょうか? まず、いくつかの用語説明から始めさせてください。 まず、オブジェクトは ``占有 (own)'' されることはありません; しかし、あるオブジェクトに対する参照の所有 own a reference はできます。オブジェクトの参照カウントは、そのオブジェクトが 参照を所有を受けている回数と定義されています。 参照の所有者は、参照が必要なくなった際にPy_DECREF() を呼び出す役割を担います。参照の所有権は委譲 (transfer) できます。 所有参照 (owned reference) の放棄には、渡す、保存する、 Py_DECREF() を呼び出す、という三つの方法があります。 所有参照を処理し忘れると、メモリリークを引き起こします。

オブジェクトに対する参照は、借用 (borrow) も可能です。 1.2参照の借用者は、Py_DECREF() を呼んではなりません。 借用者は、参照の所有者から借用した期間を超えて参照を保持し続けては なりません。所有者が参照を放棄した後で借用参照を使うと、 解放済みメモリを使用してしまう危険があるので、絶対に避けねばなりません。 1.3

参照の借用が参照の所有よりも優れている点は、コードがとりうる あらゆる処理経路で参照を廃棄しておくよう注意しなくて済むことです -- 別の言い方をすれば、借用参照の場合には、処理の途中で関数を 終了してもメモリリークの危険を冒すことがない、ということです。 逆に、メモリリークの危険を冒すよりも不利な点は、ごくまともに 見えるコードが、実際には参照の借用元で放棄されてしまった後に その参照を使うかもしれないような微妙な状況があるということです。

Py_INCREF() を呼び出すと、借用参照を所有参照 に変更できます。この操作は参照の借用元の状態には影響しません -- Py_INCREF() は新たな所有参照を生成し、参照の所有者が 担うべき全ての責任を課します (つまり、新たな参照の所有者は、以前の 所有者と同様、参照の放棄を適切に行わねばなりません)。

... も可能です。1.2
参照を ``借用する'' というメタファは厳密には正しくありません: なぜなら、参照の所有者は依然として参照のコピーを持っている からです。
... 解放済みメモリを使用してしまう危険があるので、絶対に避けねばなりません。1.3
参照カウントが 1 以上かどうか調べる方法は うまくいきません -- 参照カウント自体も解放されたメモリ上に あるため、その領域が他のオブジェクトに使われている可能性があります!
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.10 参照カウント法 Up: 1.10 参照カウント法 Next: 1.10.2 所有権にまつわる規則


1.10.2 所有権にまつわる規則

オブジェクトへの参照を関数の内外に渡す場合には、オブジェクトの 所有権が参照と共に渡されるか否かが常に関数インタフェース仕様の一部と なります。

オブジェクトへの参照を返すほとんどの関数は、参照とともに所有権も 渡します。特に、PyInt_FromLong() や Py_BuildValue() のように、新しいオブジェクトを生成する 関数は全て所有権を相手に渡します。オブジェクトが実際には新たな オブジェクトでなくても、そのオブジェクトに対する新たな参照の 所有権を得ます。例えば、PyInt_FromLong() はよく使う値をキャッシュしており、キャッシュされた値への参照を 返すことがあります。

PyObject_GetAttrString() のように、あるオブジェクトから 別のオブジェクトを抽出するような関数もまた、参照とともに所有権を 委譲します。こちらの方はやや理解しにくいかもしれません。というのは よく使われるルーチンのいくつかが例外となっているからです: PyTuple_GetItem()、 PyList_GetItem()、 PyDict_GetItem()、および PyDict_GetItemString() は全て、タプル、リスト、または辞書から借用参照を返します。

PyImport_AddModule() は、実際にはオブジェクトを生成して 返すことがあるにもかかわらず、借用参照を返します: これが可能なのは、 生成されたオブジェクトに対する所有参照はsys.modules に 保持されるからです。

オブジェクトへの参照を別の関数に渡す場合、一般的には、関数側は 呼び出し手から参照を借用します -- 参照を保存する必要があるなら、 関数側はPy_INCREF() を呼び出して独立した所有者に なります。とはいえ、この規則には二つの重要な例外: PyTuple_SetItem() とPyList_SetItem() があります。これらの関数は、渡された引数要素に対して所有権を 乗っ取り (take over) ます -- たとえ失敗してもです! (PyDict_SetItem() とその仲間は所有権を乗っ取りません -- これらはいわば ``普通の'' 関数です。)

Python から C 関数が呼び出される際には、C 関数は呼び出し側から 引数への参照を借用します。C 関数の呼び出し側はオブジェクトへの参照を 所有しているので、借用参照の生存期間が保証されるのは関数が処理を 返すまでです。このようにして借用参照を保存したり他に渡したりしたい 場合にのみ、Py_INCREF() を使って所有参照にする必要が あります。

Python から呼び出された C 関数が返す参照は所有参照でなければ なりません -- 所有権は関数から呼び出し側へと委譲されます。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.10.1 Python における参照カウント法 Up: 1.10 参照カウント法 Next: 1.10.3 薄氷


1.10.3 薄氷

数少ない状況において、一見無害に見える借用参照の利用が問題をひきおこす ことがあります。この問題はすべて、インタプリタが非明示的に呼び出され、 インタプリタが参照の所有者に参照を放棄させてしまう状況と関係しています。

知っておくべきケースのうち最初の、そして最も重要なものは、 リスト要素に対する参照を借りている際に起きる、 関係ないオブジェクトに対するPy_DECREF() の使用です。 例えば:

void
bug(PyObject *list)
{
    PyObject *item = PyList_GetItem(list, 0);

    PyList_SetItem(list, 1, PyInt_FromLong(0L));
    PyObject_Print(item, stdout, 0); /* BUG! */
}

上の関数はまず、list[0] への参照を借用し、次にlist[1] を値 0 で置き換え、最後にさきほど借用した参照を出力 しています。何も問題ないように見えますね? でもそうではないのです!

PyList_SetItem() の処理の流れを追跡してみましょう。 リストは全ての要素に対して参照を所有しているので、要素 1 を 置き換えると、以前の要素 1 を放棄します。ここで、以前の要素 1 がユーザ定義クラスのインスタンスであり、さらにこのクラスが __del__() メソッドを定義していると仮定しましょう。 このクラスインスタンスの参照カウントが 1 だった場合、 リストが参照を放棄すると、インスタンスの __del__() メソッドが呼び出されます。

クラスは Python で書かれているので、__del__()
は任意の Python コードを実行できます。この __del__()
が bug() における item に何か不正なことをして
いるのでしょうか? その通り! buf() に渡したリストが
__del__() メソッドから操作できるとすると、"del list[0]"の効果を持つような文を実行できてしまいます。もしこの操作で
list[0] に対する最後の参照が放棄されてしまうと、
list[0] に関連付けられていたメモリは解放され、
結果的に item は無効な値になってしまいます。

問題の原因が分かれば、解決は簡単です。 一時的に参照回数を増やせばよいのです。 正しく動作するバージョンは以下のようになります:

void
no_bug(PyObject *list)
{
    PyObject *item = PyList_GetItem(list, 0);

    Py_INCREF(item);
    PyList_SetItem(list, 1, PyInt_FromLong(0L));
    PyObject_Print(item, stdout, 0);
    Py_DECREF(item);
}

これは実際にあった話です。以前のバージョンの Python には、 このバグの一種が潜んでいて、__del__() メソッドが どうしてうまく動かないのかを調べるために C デバッガで相当 時間を費やした人がいました...

二つ目は、借用参照がスレッドに関係しているケースです。 通常は、 Python インタプリタにおける複数のスレッドは、 グローバルインタプリタロックがオブジェクト空間全体を保護している ため、互いに邪魔し合うことはありません。とはいえ、ロックは Py_BEGIN_ALLOW_THREADS マクロで一時的に解除したり、 Py_END_ALLOW_THREADS で再獲得したりできます。 これらのマクロはブロックの起こる I/O 呼び出しの周囲によく置かれ、 I/O が完了するまでの間に他のスレッドがプロセッサを利用できるように します。明らかに、以下の関数は上の例と似た問題をはらんでいます:

void
bug(PyObject *list)
{
    PyObject *item = PyList_GetItem(list, 0);
    Py_BEGIN_ALLOW_THREADS
    ...ブロックが起こる何らかの I/O 呼び出し...
    Py_END_ALLOW_THREADS
    PyObject_Print(item, stdout, 0); /* BUG! */
}

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.10.2 所有権にまつわる規則 Up: 1.10 参照カウント法 Next: 1.10.4 NULL ポインタ


1.10.4 NULL ポインタ

一般論として、オブジェクトへの参照を引数にとる関数はユーザが NULL ポインタを渡すとは予想しておらず、渡そうとすると コアダンプになる (か、あとでコアダンプを引き起こす) ことでしょう。 一方、オブジェクトへの参照を返すような関数は一般に、例外の発生を 示す場合にのみ NULL を返します。引数に対して NULL テストを 行わない理由は、こうした関数群はしばしば受け取った関数を他の関数へと 引き渡すからです -- 各々の関数が NULLテストを行えば、 冗長なテストが大量に行われ、コードはより低速に動くことになります。

従って、NULL のテストはオブジェクトの ``発生源''、すなわち 値が NULL になるかもしれないポインタを受け取ったときだけに しましょう。malloc() や、例外を送出する可能性の ある関数がその例です。

マクロPy_INCREF() および Py_DECREF() は NULL ポインタのチェックを行いません -- しかし、これらの マクロの変化形である Py_XINCREF() および Py_XDECREF() は チェックを行います。

特定のオブジェクト型について調べるマクロ (Pytype_Check()) は NULL ポインタのチェックを行いません -- 繰り返しますが、 様々な異なる型を想定してオブジェクトの型を調べる際には、こうした マクロを続けて呼び出す必要があるので、個別に NULL ポインタの チェックをすると冗長なテストになってしまうのです。 型を調べるマクロには、NULL チェックを行う変化形はありません。

Python から C 関数を呼び出す機構は、 C 関数に渡される引数リスト (例でいうところの args) が決して NULL にならないよう 保証しています -- 実際には、常にタプル型になるよう保証しています。 1.4

NULL ポインタを Python ユーザレベルに ``逃がし'' てしまうと、 深刻なエラーを引き起こします。

... 実際には、常にタプル型になるよう保証しています。1.4
``旧式の'' 呼び出し規約を使っている場合には、この保証は 適用されません -- 既存のコードにはいまだに旧式の呼び出し規約が 多々あります
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.10.3 薄氷 Up: 1.10 参照カウント法 Next: 1.11 C++での拡張モジュール作成


1.11 C++での拡張モジュール作成

C++でも拡張モジュールは作成できます。ただしいくつか制限があります。 メインプログラム (Python インタプリタ) は C コンパイラでコンパイルされ リンクされているので、グローバル変数や静的オブジェクトをコンストラクタ で作成できません。メインプログラムが C++ コンパイラでリンクされて いるならこれは問題ではありません。 Python インタプリタから呼び出される関数 (特にモジュール初期化関数) は、extern "C" を使って宣言しなければなりません。 また、Python ヘッダファイルをextern "C" {...} に入れる必要 はありません-- シンボル"__cplusplus" (最近の C++ コンパイラは 全てこのシンボルを定義しています) が定義されているときに extern "C" {...} が行われるように、ヘッダファイル内に すでに書かれているからです。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.10.4 NULL ポインタ Up: 1. C や C++ Next: 1.12 拡張モジュールに C API


1.12 拡張モジュールに C API を提供する

多くの拡張モジュールは単に Python から使える新たな関数や型を 提供するだけですが、時に拡張モジュール内のコードが他の拡張 モジュールでも便利なことがあります。例えば、あるモジュールでは 順序概念のないリストのように動作する ``コレクション (collection)'' クラスを実装しているかもしれません。 ちょうどリストを生成したり操作したりできる C API を備えた標準の Python リスト型のように、この新たなコレクション型も他の 拡張モジュールから直接操作できるようにするには一連の C 関数を 持っていなければなりません。

一見するとこれは簡単なこと: 単に関数を (もちろんstatic などとは宣言せずに) 書いて、適切なヘッダファイルを提供し、C API を書けばよいだけ、に思えます。そして実際のところ、全ての 拡張モジュールが Python インタプリタに常に静的にリンクされている 場合にはうまく動作します。 ところがモジュールが共有ライブラリの場合には、一つのモジュールで 定義されているシンボルが他のモジュールから不可視なことがあります。 可視性の詳細はオペレーティングシステムによります; あるシステムは Python インタプリタと全ての拡張モジュール用に単一のグローバルな 名前空間を用意しています (例えば Windows)。別のシステムはモジュールの リンク時に取り込まれるシンボルを明示的に指定する必要があります (AIX がその一例です)、また別のシステム (ほとんどの Unix) では、 違った戦略を選択肢として提供しています。 そして、たとえシンボルがグローバル変数として可視であっても、 呼び出したい関数の入ったモジュールがまだロードされていないこと だってあります!

従って、可搬性の点からシンボルの可視性には何ら仮定をしてはならない ことになります。つまり拡張モジュール中の全てのシンボルは static と宣言せねばなりません。例外はモジュールの初期化関数 で、これは (1.4 で述べたように) 他の拡張モジュールとの間で 名前が衝突するのを避けるためです。 また、他の拡張モジュールからアクセスを受けるべきではない シンボルは別のやり方で公開せねばなりません。

Python はある拡張モジュールの C レベルの情報 (ポインタ) を別の モジュールに渡すための特殊な機構: CObject を提供しています。 CObject はポインタ (void*) を記憶する Python のデータ型です。 CObject は C API を介してのみ生成したりアクセスしたりできますが、 他の Python オブジェクトと同じように受け渡しできます。 とりわけ、CObject は拡張モジュールの名前空間内にある名前に代入 できます。他の拡張モジュールはこのモジュールを import でき、次に名前を 取得し、最後にCObject へのポインタを取得します。

拡張モジュールの C API を公開するために、様々な方法で CObject が 使われます。エクスポートされているそれぞれの名前を使うと、CObject 自体や、CObject が公表しているアドレスで示される配列内に収められた 全ての C API ポインタを得られます。 そして、ポインタに対する保存や取得といった様々な作業は、コードを 提供しているモジュールとクライアントモジュールとの間では異なる 方法で分散できます。

以下の例では、名前を公開するモジュールの作者にほとんどの負荷が 掛かりますが、よく使われるライブラリを作る際に適切なアプローチを 実演します。 このアプローチでは、全ての C API ポインタ (例中では一つだけですが!) を、 CObject の値となるvoid ポインタの配列に保存します。 拡張モジュールに対応するヘッダファイルは、モジュールの import と C API ポインタを取得するよう手配するマクロを提供します; クライアントモジュールは、C API にアクセスする前にこの マクロを呼ぶだけです。

名前を公開する側のモジュールは、1.1 節のspam モジュールを修正したものです。関数spam.system() は C ライブラリ関数system() を直接呼び出さず、 PySpam_System() を呼び出します。この関数はもちろん、 実際には (全てのコマンドに ``spam'' を付けるといったような) より込み入った処理を行います。 この関数 PySpam_System() はまた、他の拡張モジュール にも公開されます。

関数PySpam_System() は、他の全ての関数と同様に static で宣言された通常の C 関数です。

static int
PySpam_System(char *command)
{
    return system(command);
}

spam_system() には取るに足らない変更が施されています:

static PyObject *
spam_system(PyObject *self, PyObject *args)
{
    char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = PySpam_System(command);
    return Py_BuildValue("i", sts);
}

モジュールの先頭にある以下の行

#include "Python.h"

の直後に、以下の二行:

#define SPAM_MODULE
#include "spammodule.h"

を必ず追加してください。

#define は、ファイルspammodule.h をインクルードして いるのが名前を公開する側のモジュールであって、クライアントモジュール ではないことをヘッダファイルに教えるために使われます。 最後に、モジュールの初期化関数は C API のポインタ配列を初期化するよう 手配しなければなりません:

PyMODINIT_FUNC
initspam(void)
{
    PyObject *m;
    static void *PySpam_API[PySpam_API_pointers];
    PyObject *c_api_object;

    m = Py_InitModule("spam", SpamMethods);

    /* C API ポインタ配列を初期化する */
    PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;

    /* API ポインタ配列のアドレスが入った CObject を生成する */
    c_api_object = PyCObject_FromVoidPtr((void *)PySpam_API, NULL);

    if (c_api_object != NULL)
        PyModule_AddObject(m, "_C_API", c_api_object);
}

PySpam_API がstatic と宣言されていることに注意して ください; そうしなければ、initspam() が終了したときに ポインタアレイは消滅してしまいます!

からくりの大部分はヘッダファイル spammodule.h 内にあり、 以下のようになっています:

#ifndef Py_SPAMMODULE_H
#define Py_SPAMMODULE_H
#ifdef __cplusplus
extern "C" {
#endif

/* spammodule のヘッダファイル */

/* C API 関数 */
#define PySpam_System_NUM 0
#define PySpam_System_RETURN int
#define PySpam_System_PROTO (char *command)

/* C API ポインタの総数 */
#define PySpam_API_pointers 1

#ifdef SPAM_MODULE
/* この部分は spammodule.c をコンパイルする際に使われる */

static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;

#else
/* この部分は spammodule の API を使うモジュール側で使われる */

static void **PySpam_API;

#define PySpam_System \
 (*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])

/* エラーによる例外の場合には -1 を、成功すると 0 を返す */
static int
import_spam(void)
{
    PyObject *module = PyImport_ImportModule("spam");

    if (module != NULL) {
        PyObject *c_api_object = PyObject_GetAttrString(module, "_C_API");
        if (c_api_object == NULL)
            return -1;
        if (PyCObject_Check(c_api_object))
            PySpam_API = (void **)PyCObject_AsVoidPtr(c_api_object);
        Py_DECREF(c_api_object);
    }
    return 0;
}

#endif

#ifdef __cplusplus
}
#endif

#endif /* !defined(Py_SPAMMODULE_H) */

PySpam_System() へのアクセス手段を得るために クライアントモジュール側がしなければならないことは、初期化関数内 でのimport_spam() 関数 (またはマクロ) の呼び出しです:

PyMODINIT_FUNC
initclient(void)
{
    PyObject *m;

    Py_InitModule("client", ClientMethods);
    if (import_spam() < 0)
        return;
    /* さらなる初期化処理はここに置ける */
}

このアプローチの主要な欠点は、spammodule.h がやや難解に なるということです。とはいえ、各関数の基本的な構成は公開される ものと同じなので、書き方を一度だけ学べばすみます。

最後に、CObject は、自身に保存されているポインタをメモリ確保したり 解放したりする際に特に便利な、もう一つの機能を提供しているという ことに触れておかねばなりません。詳細は Python/C API リファレンスマニュアル の ``CObjects '' の節、および CObjects の実装部分 (Python ソースコード配布物中のファイル Include/cobject.h およびObjects/cobject.c に述べられています。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.11 C++での拡張モジュール作成 Up: 1. C や C++ Next: 2. 新しい型を定義する


2. 新しい型を定義する

前の章でふれたように、Python では拡張モジュールを書くプログラマが Python のコードから操作できる、新しい型を定義できるようになっています。 ちょうど Python の中核にある文字列やリストをつくれるようなものです。

これはそんなにむずかしくはありません。拡張型のためのコードにはすべて、 一定のパターンが存在しています。しかし始める前に、いくつか細かいことを 理解しておく必要があるでしょう。

注意: Python 2.2 から、新しい型を定義する方法がかなり変わって (よくなって) います。この文書は Python 2.2 およびそれ以降で 新しい型をどうやって定義するかについて述べています。古いバージョンの Python をサポートする必要がある場合は、この文書の古い版を参照してください。

  • 2.1 基本的なこと
    • 2.1.1 基本のサンプルにデータとメソッドを追加する
    • 2.1.2 データ属性をこまかく制御する
    • 2.1.3 循環ガベージコレクションをサポートする
  • 2.2 タイプメソッド
    • 2.2.1 最終化 (finalization) と解放
    • 2.2.2 Object Presentation
    • 2.2.3 属性を管理する
      • 2.2.3.1 総称的な属性を管理する
      • 2.2.3.2 特定の型に特化した属性の管理
    • 2.2.4 オブジェクトの比較
    • 2.2.5 抽象的なプロトコルのサポート
    • 2.2.6 その他いろいろ
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 1.12 拡張モジュールに C API Up: Python インタプリタの拡張と埋め込み Next: 2.1 基本的なこと


2.1 基本的なこと

Python ランタイムでは、すべての Python オブジェクトは PyObject* 型の変数として扱います。PyObject は さほど大仰なオブジェクトではなく、単にオブジェクトに対する参照回数と、 そのオブジェクトの「タイプオブジェクト (type object)」へのポインタを 格納しているだけです。 重要な役割を果たしているのはこのタイプオブジェクトです。 つまりタイプオブジェクトは、例えばあるオブジェクトのある属性が参照される とか、あるいは別のオブジェクトとの間で乗算を行うといったときに、 どの (C の) 関数を呼び出すかを決定しているのです。 これらの C 関数は「タイプメソッド (type method)」と呼ばれ、 [].append のようなもの (いわゆる「オブジェクトメソッド (object method)」) とは区別しています。

なので、新しいオブジェクトの型を定義したいときは、 新しいタイプオブジェクトを作成すればよいわけです。

この手のことは例を見たほうが早いでしょうから、 ここに最小限の、しかし完全な、新しい型を定義するモジュールをあげておきます:

#include <Python.h>

typedef struct {
    PyObject_HEAD
    /* Type-specific fields go here. */
} noddy_NoddyObject;

static PyTypeObject noddy_NoddyType = {
    PyObject_HEAD_INIT(NULL)
    0,                         /*ob_size*/
    "noddy.Noddy",             /*tp_name*/
    sizeof(noddy_NoddyObject), /*tp_basicsize*/
    0,                         /*tp_itemsize*/
    0,                         /*tp_dealloc*/
    0,                         /*tp_print*/
    0,                         /*tp_getattr*/
    0,                         /*tp_setattr*/
    0,                         /*tp_compare*/
    0,                         /*tp_repr*/
    0,                         /*tp_as_number*/
    0,                         /*tp_as_sequence*/
    0,                         /*tp_as_mapping*/
    0,                         /*tp_hash */
    0,                         /*tp_call*/
    0,                         /*tp_str*/
    0,                         /*tp_getattro*/
    0,                         /*tp_setattro*/
    0,                         /*tp_as_buffer*/
    Py_TPFLAGS_DEFAULT,        /*tp_flags*/
    "Noddy objects",           /* tp_doc */
};

static PyMethodDef noddy_methods[] = {
    {NULL}  /* Sentinel */
};

#ifndef PyMODINIT_FUNC	/* declarations for DLL import/export */
#define PyMODINIT_FUNC void
#endif
PyMODINIT_FUNC
initnoddy(void)
{
    PyObject* m;

    noddy_NoddyType.tp_new = PyType_GenericNew;
    if (PyType_Ready(&noddy_NoddyType) < 0)
        return;

    m = Py_InitModule3("noddy", noddy_methods,
                       "Example module that creates an extension type.");

    Py_INCREF(&noddy_NoddyType);
    PyModule_AddObject(m, "Noddy", (PyObject *)&noddy_NoddyType);
}
Download as text (original file name: noddy.c).

さしあたって覚えておくことは以上ですが、これで前の章からすこしは 説明がわかりやすくなっていることと思います。

最初に習うのは、つぎのようなものです:

typedef struct {
    PyObject_HEAD
} noddy_NoddyObject;

これが Noddy オブジェクトの内容です -- このケースでは、 ほかの Python オブジェクトが持っているものと何ら変わりはありません。 つまり参照カウントと型オブジェクトへのポインタですね。これらは PyObject_HEAD マクロによって 展開されるメンバです。マクロを使う理由は、レイアウトを標準化するためと、 デバッグ用ビルド時に特別なデバッグ用のメンバを定義できるようにするためです。 この PyObject_HEAD マクロの後にはセミコロンがないことに 注意してください。 セミコロンはすでにマクロ内に含まれています。うっかり後にセミコロンを つけてしまわないように気をつけて。 これはお使いの機種では何の問題も起こらないかもしれませんが、 機種によっては、おそらく問題になるのです! (Windows 上では、MS Visual C がこの手のエラーを出し、 コンパイルできないことが知られています)

比較のため、以下に標準的な Python の整数型の定義を見てみましょう:

typedef struct {
    PyObject_HEAD
    long ob_ival;
} PyIntObject;

では次にいってみます。かなめの部分、タイプオブジェクトです。

static PyTypeObject noddy_NoddyType = {
    PyObject_HEAD_INIT(NULL)
    0,                         /*ob_size*/
    "noddy.Noddy",             /*tp_name*/
    sizeof(noddy_NoddyObject), /*tp_basicsize*/
    0,                         /*tp_itemsize*/
    0,                         /*tp_dealloc*/
    0,                         /*tp_print*/
    0,                         /*tp_getattr*/
    0,                         /*tp_setattr*/
    0,                         /*tp_compare*/
    0,                         /*tp_repr*/
    0,                         /*tp_as_number*/
    0,                         /*tp_as_sequence*/
    0,                         /*tp_as_mapping*/
    0,                         /*tp_hash */
    0,                         /*tp_call*/
    0,                         /*tp_str*/
    0,                         /*tp_getattro*/
    0,                         /*tp_setattro*/
    0,                         /*tp_as_buffer*/
    Py_TPFLAGS_DEFAULT,        /*tp_flags*/
    "Noddy objects",           /* tp_doc */
};

object.h の中にある PyTypeObject の定義を見ると、 実際にはここに挙げた以上の数のメンバがあるとわかるでしょう。 これ以外のメンバは C コンパイラによってゼロに初期化されるので、 必要な時を除いてふつうはそれらの値を明示的には指定せずにおきます。

次のものは非常に重要なので、とくに最初の最初に見ておきましょう:

    PyObject_HEAD_INIT(NULL)

これはちょっとぶっきらぼうですね。実際に書きたかったのはこうです:

    PyObject_HEAD_INIT(&PyType_Type)

この場合、タイプオブジェクトの型は「type」という名前になりますが、 これは厳密には C の基準に従っておらず、コンパイラによっては文句を 言われます。 幸いにも、このメンバは PyType_Ready() が埋めてくれます。

    0,                          /* ob_size */

ヘッダ中の ob_size メンバは使われていません。 これは歴史的な遺物であり、構造体中にこれが存在しているのは 古いバージョンの Python 用にコンパイルされた拡張モジュールとの バイナリ上の互換性を保つためです。ここにはつねにゼロを指定してください。

    "noddy.Noddy",              /* tp_name */

これは型の名前です。この名前はオブジェクトのデフォルトの表現形式と、 いくつかのエラーメッセージ中で使われます。たとえば:

>>> "" + noddy.new_noddy()
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: cannot add type "noddy.Noddy" to string

注意: この名前はドットで区切られた名前で、モジュール名と、そのモジュール内での 型名を両方ふくんでいます。この場合のモジュールは noddy で、型の名前は Noddy ですから、ここでの型名としては noddy.Noddy を 指定するわけです。

    sizeof(noddy_NoddyObject),  /* tp_basicsize */

これによって Python は PyObject_New() が呼ばれたときに どれくらいの量のメモリを割り当てればよいのか知ることができます。

    0,                          /* tp_itemsize */

これはリストや文字列などの可変長オブジェクトのためのものです。 今のところ無視しましょう。

このあとのいくつかのメソッドは使わないのでとばして、 クラスのフラグ (flags) には Py_TPFLAGS_DEFAULT を入れます。

    Py_TPFLAGS_DEFAULT,        /*tp_flags*/

すべての型はフラグにこの定数を含めておく必要があります。 これは現在のバージョンの Python で定義されているすべての メンバを許可します。

この型の docstring は tp_doc に入れます。

    "Noddy objects",           /* tp_doc */

ここからタイプメソッドに入るわけですが。 ここがあなたのオブジェクトが他と違うところです。 でも今回のバージョンでは、これらはどれも実装しないでおき、 あとでこの例をより面白いものに改造することにしましょう。

とりあえずやりたいのは、この Noddy オブジェクトを新しく 作れるようにすることです。オブジェクトの作成を許可するには、 tp_new の実装を提供する必要があります。今回は、 API 関数によって提供されるデフォルトの実装 PyType_GenericNew() を 使うだけにしましょう。これを単に tp_new スロットに代入すれば よいのですが、 これは互換上の理由からできません。プラットフォームやコンパイラによっては、 構造体メンバの初期化に別の場所で定義されている C の関数を代入することは できないのです。 なので、この tp_new の値はモジュール初期化用の関数で代入します。 PyType_Ready() を呼ぶ直前です:

    noddy_NoddyType.tp_new = PyType_GenericNew;
    if (PyType_Ready(&noddy_NoddyType) < 0)
        return;

これ以外のタイプメソッドはすべて NULLです。 これらについては後ほどふれます。

このファイル中にある他のものは、どれもおなじみでしょう。 initnoddy() のこれを除いて:

    if (PyType_Ready(&noddy_NoddyType) < 0)
        return;

この関数は、上で NULLに指定していた ob_type などの いくつものメンバを埋めて、Noddy 型を初期化します。

    PyModule_AddObject(m, "Noddy", (PyObject *)&noddy_NoddyType);

これはこの型をモジュール中の辞書に埋め込みます。これで、 Noddy クラスを呼べば Noddy インスタンスを作れるように なりました:

import noddy
mynoddy = noddy.Noddy()

これだけです! 残るはこれをどうやってビルドするかということです。 上のコードを noddy.c というファイルに入れて、 以下のものを setup.py というファイルに入れましょう。

from distutils.core import setup, Extension
setup(name="noddy", version="1.0",
      ext_modules=[Extension("noddy", ["noddy.c"])])

そして、シェルから以下のように入力します。

$ python setup.py build

これでサブディレクトリの下にファイル noddy.so が作成されます。 このディレクトリに移動して Python を起動しましょう。 import noddy して Noddy オブジェクトで遊べるようになっているはずです。

そんなにむずかしくありません、よね?

もちろん、現在の Noddy 型はまだおもしろみに欠けています。 何もデータを持ってないし、何もしてはくれません。 継承してサブクラスを作ることさえできないのです。

  • 2.1.1 基本のサンプルにデータとメソッドを追加する
  • 2.1.2 データ属性をこまかく制御する
  • 2.1.3 循環ガベージコレクションをサポートする
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 2. 新しい型を定義する Up: 2. 新しい型を定義する Next: 2.1.1 基本のサンプルにデータとメソッドを追加する


2.1.1 基本のサンプルにデータとメソッドを追加する

この基本のサンプルにデータとメソッドを追加してみましょう。 ついでに、この型を基底クラスとしても利用できるようにします。 ここでは新しいモジュール noddy2 をつくり、以下の機能を追加します:

#include <Python.h>
#include "structmember.h"

typedef struct {
    PyObject_HEAD
    PyObject *first;
    PyObject *last;
    int number;
} Noddy;

static void
Noddy_dealloc(Noddy* self)
{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    self->ob_type->tp_free((PyObject*)self);
}

static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    Noddy *self;

    self = (Noddy *)type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyString_FromString("");
        if (self->first == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->last = PyString_FromString("");
        if (self->last == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->number = 0;
    }

    return (PyObject *)self;
}

static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
    PyObject *first=NULL, *last=NULL;

    static char *kwlist[] = {"first", "last", "number", NULL};

    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                      &first, &last,
                                      &self->number))
        return -1;

    if (first) {
        Py_XDECREF(self->first);
        Py_INCREF(first);
        self->first = first;
    }

    if (last) {
        Py_XDECREF(self->last);
        Py_INCREF(last);
        self->last = last;
    }

    return 0;
}

static PyMemberDef Noddy_members[] = {
    {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
     "first name"},
    {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
     "last name"},
    {"number", T_INT, offsetof(Noddy, number), 0,
     "noddy number"},
    {NULL}  /* Sentinel */
};

static PyObject *
Noddy_name(Noddy* self)
{
    static PyObject *format = NULL;
    PyObject *args, *result;

    if (format == NULL) {
        format = PyString_FromString("%s %s");
        if (format == NULL)
            return NULL;
    }

    if (self->first == NULL) {
        PyErr_SetString(PyExc_AttributeError, "first");
        return NULL;
    }

    if (self->last == NULL) {
        PyErr_SetString(PyExc_AttributeError, "last");
        return NULL;
    }

    args = Py_BuildValue("OO", self->first, self->last);
    if (args == NULL)
        return NULL;

    result = PyString_Format(format, args);
    Py_DECREF(args);

    return result;
}

static PyMethodDef Noddy_methods[] = {
    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

static PyTypeObject NoddyType = {
    PyObject_HEAD_INIT(NULL)
    0,                         /*ob_size*/
    "noddy.Noddy",             /*tp_name*/
    sizeof(Noddy),             /*tp_basicsize*/
    0,                         /*tp_itemsize*/
    (destructor)Noddy_dealloc, /*tp_dealloc*/
    0,                         /*tp_print*/
    0,                         /*tp_getattr*/
    0,                         /*tp_setattr*/
    0,                         /*tp_compare*/
    0,                         /*tp_repr*/
    0,                         /*tp_as_number*/
    0,                         /*tp_as_sequence*/
    0,                         /*tp_as_mapping*/
    0,                         /*tp_hash */
    0,                         /*tp_call*/
    0,                         /*tp_str*/
    0,                         /*tp_getattro*/
    0,                         /*tp_setattro*/
    0,                         /*tp_as_buffer*/
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
    "Noddy objects",           /* tp_doc */
    0,		               /* tp_traverse */
    0,		               /* tp_clear */
    0,		               /* tp_richcompare */
    0,		               /* tp_weaklistoffset */
    0,		               /* tp_iter */
    0,		               /* tp_iternext */
    Noddy_methods,             /* tp_methods */
    Noddy_members,             /* tp_members */
    0,                         /* tp_getset */
    0,                         /* tp_base */
    0,                         /* tp_dict */
    0,                         /* tp_descr_get */
    0,                         /* tp_descr_set */
    0,                         /* tp_dictoffset */
    (initproc)Noddy_init,      /* tp_init */
    0,                         /* tp_alloc */
    Noddy_new,                 /* tp_new */
};

static PyMethodDef module_methods[] = {
    {NULL}  /* Sentinel */
};

#ifndef PyMODINIT_FUNC	/* declarations for DLL import/export */
#define PyMODINIT_FUNC void
#endif
PyMODINIT_FUNC
initnoddy2(void)
{
    PyObject* m;

    if (PyType_Ready(&NoddyType) < 0)
        return;

    m = Py_InitModule3("noddy2", module_methods,
                       "Example module that creates an extension type.");

    if (m == NULL)
      return;

    Py_INCREF(&NoddyType);
    PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
}
Download as text (original file name: noddy2.c).

このバージョンでは、いくつもの変更をおこないます。

以下の include を追加します:

#include "structmember.h"

すこしあとでふれますが、この include には属性を扱うための宣言が 入っています。

Noddy オブジェクトの構造体の名前は Noddy に縮めることにします。 タイプオブジェクト名は NoddyType に縮めます。

これから Noddy 型は 3つのデータ属性をもつようになります。 first、last、および number です。first と last 属性は ファーストネームとラストネームを格納した Python 文字列で、 number 属性は整数の値です。

これにしたがうと、オブジェクトの構造体は次のようになります:

typedef struct {
    PyObject_HEAD
    PyObject *first;
    PyObject *last;
    int number;
} Noddy;

いまや管理すべきデータができたので、オブジェクトの割り当てと解放に際しては より慎重になる必要があります。最低限、オブジェクトの解放メソッドが必要です:

static void
Noddy_dealloc(Noddy* self)
{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    self->ob_type->tp_free((PyObject*)self);
}

この関数は tp_dealloc メンバに代入されます。

    (destructor)Noddy_dealloc, /*tp_dealloc*/

このメソッドでやっているのは、ふたつの Python 属性の参照カウントを 減らすことです。first メンバと last メンバが NULLかもしれないため、ここでは Py_XDECREF() を使いました。 このあとそのオブジェクトのタイプメソッドである tp_free メンバを 呼び出しています。 ここではオブジェクトの型が NoddyType とは限らないことに 注意してください。 なぜなら、このオブジェクトはサブクラス化したインスタンスかもしれないからです。

ファーストネームとラストネームを空文字列に初期化しておきたいので、 新しいメソッドを追加することにしましょう:

static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    Noddy *self;

    self = (Noddy *)type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyString_FromString("");
        if (self->first == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->last = PyString_FromString("");
        if (self->last == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->number = 0;
    }

    return (PyObject *)self;
}

そしてこれを tp_new メンバとしてインストールします:

    Noddy_new,                 /* tp_new */

この新しいメンバはその型のオブジェクトを (初期化するのではなく) 作成する 責任を負っています。Python ではこのメンバは __new__() メソッドと して見えています。__new__() メソッドについての詳しい議論は ``Unifying types and classes in Python'' という題名の論文を見てください。 new メソッドを実装する理由のひとつは、インスタンス変数の初期値を保証するためです。 この例でやりたいのは new メソッドが first メンバと last メンバの値を NULLでないようにするということです。 もしこれらの初期値が NULLでもよいのであれば、 先の例でやったように、new メソッドとして PyType_GenericNew() を 使うこともできたでしょう。PyType_GenericNew() はすべての インスタンス変数のメンバをNULL にします。

この new メソッドは静的なメソッドで、インスタンスを生成するときに その型と、型が呼び出されたときの引数が渡され、新しいオブジェクトを作成して 返します。new メソッドはつねに、あらかじめ固定引数 (positional argument) と キーワード引数を取りますが、これらのメソッドはしばしばそれらの 引数は無視して初期化メソッドにそのまま渡します。new メソッドは メモリ割り当てのために tp_alloc メンバを呼び出します。tp_alloc をこちらで 初期化する必要はありません。これは PyType_Ready() が 基底クラス (デフォルトでは object) をもとに埋めるものです。 ほとんどの型ではデフォルトのメモリ割り当てを使っています。

つぎに初期化用の関数を見てみましょう:

static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
    PyObject *first=NULL, *last=NULL;

    static char *kwlist[] = {"first", "last", "number", NULL};

    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                      &first, &last,
                                      &self->number))
        return -1;

    if (first) {
        Py_XDECREF(self->first);
        Py_INCREF(first);
        self->first = first;
    }

    if (last) {
        Py_XDECREF(self->last);
        Py_INCREF(last);
        self->last = last;
    }

    return 0;
}

これは tp_init メンバに代入されます。

    (initproc)Noddy_init,         /* tp_init */

Python では、tp_init メンバは __init__() メソッド として見えています。 このメソッドは、オブジェクトが作成されたあとに、それを初期化する目的で 使われます。 new メソッドとはちがって、初期化用のメソッドは必ず呼ばれるとは限りません。 初期化用のメソッドは、インスタンスの初期値を提供するのに必要な引数を 受けとります。 このメソッドはつねに固定引数とキーワード引数を受けとります。

ここではインスタンス変数を属性として見えるようにしたいのですが、 これにはいくつもの方法があります。もっとも簡単な方法は、メンバの定義を 与えることです:

static PyMemberDef Noddy_members[] = {
    {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
     "first name"},
    {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
     "last name"},
    {"number", T_INT, offsetof(Noddy, number), 0,
     "noddy number"},
    {NULL}  /* Sentinel */
};

そして、この定義を tp_members に入れましょう:

    Noddy_members,             /* tp_members */

各メンバの定義はそれぞれ、メンバの名前、型、オフセット、アクセスフラグ および docstring です。詳しくは後の ``総称的な属性を管理する'' の節を ご覧ください。

この方法の欠点は、Python 属性に代入できるオブジェクトの型を制限する方法が ないことです。 ここではファーストネーム first とラストネーム last に、ともに文字列が 入るよう期待していますが、今のやり方ではどんな Python オブジェクトも 代入できてしまいます。 加えてこの属性は削除 (del) できてしまい、その場合、 C のポインタには NULLが設定されます。たとえもしメンバが NULL以外の値に初期化されるように してあったとしても、属性が削除されればメンバは NULLになってしまいます。

ここでは name と呼ばれるメソッドを定義しましょう。 これはファーストネーム first とラストネーム last を連結した文字列を そのオブジェクトの名前として返します。

static PyObject *
Noddy_name(Noddy* self)
{
    static PyObject *format = NULL;
    PyObject *args, *result;

    if (format == NULL) {
        format = PyString_FromString("%s %s");
        if (format == NULL)
            return NULL;
    }

    if (self->first == NULL) {
        PyErr_SetString(PyExc_AttributeError, "first");
        return NULL;
    }

    if (self->last == NULL) {
        PyErr_SetString(PyExc_AttributeError, "last");
        return NULL;
    }

    args = Py_BuildValue("OO", self->first, self->last);
    if (args == NULL)
        return NULL;

    result = PyString_Format(format, args);
    Py_DECREF(args);

    return result;
}

このメソッドは C 関数として実装され、Noddy (あるいは Noddy のサブクラス) のインスタンスを第一引数として受けとります。メソッドはつねにその インスタンスを最初の引数として受けとらなければなりません。 しばしば固定引数とキーワード引数も受けとりますが、 今回はなにも必要ないので、固定引数のタプルもキーワード引数の辞書も 取らないことにします。 このメソッドは Python の以下のメソッドと等価です:

    def name(self):
       return "%s %s" % (self.first, self.last)

first メンバと last メンバがそれぞれ NULLかどうか チェックしなければならないことに注意してください。 これらは削除される可能性があり、その場合値は NULLにセットされます。 この属性の削除を禁止して、そこに入れられる値を文字列に限定できれば なおいいでしょう。次の節ではこれについて扱います。

さて、メソッドを定義したので、ここでメソッド定義用の配列を作成する 必要があります:

static PyMethodDef Noddy_methods[] = {
    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

これを tp_methods スロットに入れましょう:

    Noddy_methods,             /* tp_methods */

ここでの METH_NOARGS フラグは、そのメソッドが引数を取らないことを 宣言するのに使われています。

最後に、この型を基底クラスとして利用可能にしましょう。 上のメソッドは注意ぶかく書かれているので、これはそのオブジェクトの型が 作成されたり利用される場合についてどんな仮定も置いていません。 なので、ここですべきことは Py_TPFLAGS_BASETYPE を クラス定義のフラグに加えるだけです:

    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/

initnoddy() の名前を initnoddy2() に変更し、 Py_InitModule3() に渡されるモジュール名を更新します。

さいごに setup.py ファイルを更新して新しいモジュールをビルドします。

from distutils.core import setup, Extension
setup(name="noddy", version="1.0",
      ext_modules=[
         Extension("noddy", ["noddy.c"]),
         Extension("noddy2", ["noddy2.c"]),
         ])

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 2.1 基本的なこと Up: 2.1 基本的なこと Next: 2.1.2 データ属性をこまかく制御する


2.1.2 データ属性をこまかく制御する

この節では、Noddy クラスの例にあった first と last の各属性にたいして、より精密な制御を提供します。 以前のバージョンのモジュールでは、 インスタンス変数の first と last には文字列以外のものも 代入できてしまい、あまつさえ削除さえ可能でした。 ここではこれらの属性が必ず文字列を保持しているようにしましょう。

#include <Python.h>
#include "structmember.h"

typedef struct {
    PyObject_HEAD
    PyObject *first;
    PyObject *last;
    int number;
} Noddy;

static void
Noddy_dealloc(Noddy* self)
{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    self->ob_type->tp_free((PyObject*)self);
}

static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    Noddy *self;

    self = (Noddy *)type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyString_FromString("");
        if (self->first == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->last = PyString_FromString("");
        if (self->last == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->number = 0;
    }

    return (PyObject *)self;
}

static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
    PyObject *first=NULL, *last=NULL;

    static char *kwlist[] = {"first", "last", "number", NULL};

    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                      &first, &last,
                                      &self->number))
        return -1;

    if (first) {
        Py_DECREF(self->first);
        Py_INCREF(first);
        self->first = first;
    }

    if (last) {
        Py_DECREF(self->last);
        Py_INCREF(last);
        self->last = last;
    }

    return 0;
}

static PyMemberDef Noddy_members[] = {
    {"number", T_INT, offsetof(Noddy, number), 0,
     "noddy number"},
    {NULL}  /* Sentinel */
};

static PyObject *
Noddy_getfirst(Noddy *self, void *closure)
{
    Py_INCREF(self->first);
    return self->first;
}

static int
Noddy_setfirst(Noddy *self, PyObject *value, void *closure)
{
  if (value == NULL) {
    PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
    return -1;
  }

  if (! PyString_Check(value)) {
    PyErr_SetString(PyExc_TypeError,
                    "The first attribute value must be a string");
    return -1;
  }

  Py_DECREF(self->first);
  Py_INCREF(value);
  self->first = value;

  return 0;
}

static PyObject *
Noddy_getlast(Noddy *self, void *closure)
{
    Py_INCREF(self->last);
    return self->last;
}

static int
Noddy_setlast(Noddy *self, PyObject *value, void *closure)
{
  if (value == NULL) {
    PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");
    return -1;
  }

  if (! PyString_Check(value)) {
    PyErr_SetString(PyExc_TypeError,
                    "The last attribute value must be a string");
    return -1;
  }

  Py_DECREF(self->last);
  Py_INCREF(value);
  self->last = value;

  return 0;
}

static PyGetSetDef Noddy_getseters[] = {
    {"first",
     (getter)Noddy_getfirst, (setter)Noddy_setfirst,
     "first name",
     NULL},
    {"last",
     (getter)Noddy_getlast, (setter)Noddy_setlast,
     "last name",
     NULL},
    {NULL}  /* Sentinel */
};

static PyObject *
Noddy_name(Noddy* self)
{
    static PyObject *format = NULL;
    PyObject *args, *result;

    if (format == NULL) {
        format = PyString_FromString("%s %s");
        if (format == NULL)
            return NULL;
    }

    args = Py_BuildValue("OO", self->first, self->last);
    if (args == NULL)
        return NULL;

    result = PyString_Format(format, args);
    Py_DECREF(args);

    return result;
}

static PyMethodDef Noddy_methods[] = {
    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

static PyTypeObject NoddyType = {
    PyObject_HEAD_INIT(NULL)
    0,                         /*ob_size*/
    "noddy.Noddy",             /*tp_name*/
    sizeof(Noddy),             /*tp_basicsize*/
    0,                         /*tp_itemsize*/
    (destructor)Noddy_dealloc, /*tp_dealloc*/
    0,                         /*tp_print*/
    0,                         /*tp_getattr*/
    0,                         /*tp_setattr*/
    0,                         /*tp_compare*/
    0,                         /*tp_repr*/
    0,                         /*tp_as_number*/
    0,                         /*tp_as_sequence*/
    0,                         /*tp_as_mapping*/
    0,                         /*tp_hash */
    0,                         /*tp_call*/
    0,                         /*tp_str*/
    0,                         /*tp_getattro*/
    0,                         /*tp_setattro*/
    0,                         /*tp_as_buffer*/
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
    "Noddy objects",           /* tp_doc */
    0,		               /* tp_traverse */
    0,		               /* tp_clear */
    0,		               /* tp_richcompare */
    0,		               /* tp_weaklistoffset */
    0,		               /* tp_iter */
    0,		               /* tp_iternext */
    Noddy_methods,             /* tp_methods */
    Noddy_members,             /* tp_members */
    Noddy_getseters,           /* tp_getset */
    0,                         /* tp_base */
    0,                         /* tp_dict */
    0,                         /* tp_descr_get */
    0,                         /* tp_descr_set */
    0,                         /* tp_dictoffset */
    (initproc)Noddy_init,      /* tp_init */
    0,                         /* tp_alloc */
    Noddy_new,                 /* tp_new */
};

static PyMethodDef module_methods[] = {
    {NULL}  /* Sentinel */
};

#ifndef PyMODINIT_FUNC	/* declarations for DLL import/export */
#define PyMODINIT_FUNC void
#endif
PyMODINIT_FUNC
initnoddy3(void)
{
    PyObject* m;

    if (PyType_Ready(&NoddyType) < 0)
        return;

    m = Py_InitModule3("noddy3", module_methods,
                       "Example module that creates an extension type.");

    if (m == NULL)
      return;

    Py_INCREF(&NoddyType);
    PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
}
Download as text (original file name: noddy3.c).

first 属性と last 属性をよりこまかく制御するためには、 カスタムメイドの getter 関数と setter 関数を使います。以下は first 属性から値を取得する関数 (getter) と、 この属性に値を格納する関数 (setter) です:

Noddy_getfirst(Noddy *self, void *closure)
{
    Py_INCREF(self->first);
    return self->first;
}

static int
Noddy_setfirst(Noddy *self, PyObject *value, void *closure)
{
  if (value == NULL) {
    PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
    return -1;
  }

  if (! PyString_Check(value)) {
    PyErr_SetString(PyExc_TypeError,
                    "The first attribute value must be a string");
    return -1;
  }

  Py_DECREF(self->first);
  Py_INCREF(value);
  self->first = value;

  return 0;
}

getter 関数には Noddy オブジェクトと「閉包 (closure)」 (これは void型のポインタです) が渡されます。今回のケースでは閉包は無視します。 (閉包とは定義データが渡される setter や getter の高度な利用をサポートするためのもので、 これを使うとたとえば getter と setter をひとまとめにした関数に、 閉包のデータにもとづいて属性を get するか set するか決めさせる、 といったことができます。)

setter 関数には Noddy オブジェクトと新しい値、そして閉包が渡されます。 新しい値は NULLかもしれず、その場合はこの属性が削除されます。ここでは 属性が削除されたり、その値が文字列でないときにはエラーを発生させるように します。

ここでは PyGetSetDef 構造体の配列をつくります:

static PyGetSetDef Noddy_getseters[] = {
    {"first",
     (getter)Noddy_getfirst, (setter)Noddy_setfirst,
     "first name",
     NULL},
    {"last",
     (getter)Noddy_getlast, (setter)Noddy_setlast,
     "last name",
     NULL},
    {NULL}  /* Sentinel */
};

そしてこれを tp_getset スロットに登録します:

    Noddy_getseters,           /* tp_getset */

これで属性の getter と setter が登録できました。

PyGetSetDef 構造体の最後の要素が上で説明した閉包です。 今回は閉包は使わないので、たんに NULLを渡しています。

また、メンバ定義からはこれらの属性を除いておきましょう:

static PyMemberDef Noddy_members[] = {
    {"number", T_INT, offsetof(Noddy, number), 0,
     "noddy number"},
    {NULL}  /* Sentinel */
};

これらの変更によって、 first メンバと last メンバが 決して NULL にならないと保証できました。これでほとんどすべてのケースから NULL値のチェックを除けます。これは Py_XDECREF() 呼び出しを Py_DECREF() 呼び出しに変えられることを意味します。 唯一これを変えられないのはオブジェクト解放メソッド (deallocator) で、 なぜならここではコンストラクタによるメンバ初期化が失敗している 可能性があるからです。

さて、先ほどもしたように、このモジュール初期化関数と 初期化関数内にあるモジュール名を変更しましょう。 そして setup.py ファイルに追加の定義をくわえます。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 2.1.1 基本のサンプルにデータとメソッドを追加する Up: 2.1 基本的なこと Next: 2.1.3 循環ガベージコレクションをサポートする


2.1.3 循環ガベージコレクションをサポートする

Python は循環ガベージコレクション機能をもっており、これは不要なオブジェクトを、 たとえ参照カウントがゼロでなくても、発見することができます。 これはオブジェクトの参照が循環しているときに起こりえます。 たとえば以下の例を考えてください:

>>> l = []
>>> l.append(l)
>>> del l

この例では、自分自身をふくむリストをつくりました。たとえこのリストを del しても、それは自分自身への参照をまだ持ちつづけますから、参照カウントは ゼロにはなりません。嬉しいことに Python には循環ガベージコレクション機能が ありますから、最終的にはこのリストが不要であることを検出し、解放できます。

Noddy クラスの 2番目の例では、first 属性と last 属性にどんなオブジェクトでも格納できるようになっていました。つまり、 Noddy オブジェクトの参照は循環しうるのです:

>>> import noddy2
>>> n = noddy2.Noddy()
>>> l = [n]
>>> n.first = l

これは実にばかげた例ですが、すくなくとも Noddy クラスに 循環ガベージコレクション機能のサポートを加える口実を与えてくれます。 循環ガベージコレクションをサポートするには 2つのタイプスロットを埋め、 これらのスロットを許可するようにクラス定義のフラグを設定する必要があります:

#include <Python.h>
#include "structmember.h"

typedef struct {
    PyObject_HEAD
    PyObject *first;
    PyObject *last;
    int number;
} Noddy;

static int
Noddy_traverse(Noddy *self, visitproc visit, void *arg)
{
    if (self->first && visit(self->first, arg) < 0)
        return -1;
    if (self->last && visit(self->last, arg) < 0)
        return -1;

    return 0;
}

static int
Noddy_clear(Noddy *self)
{
    Py_XDECREF(self->first);
    self->first = NULL;
    Py_XDECREF(self->last);
    self->last = NULL;

    return 0;
}

static void
Noddy_dealloc(Noddy* self)
{
    Noddy_clear(self);
    self->ob_type->tp_free((PyObject*)self);
}

static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    Noddy *self;

    self = (Noddy *)type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyString_FromString("");
        if (self->first == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->last = PyString_FromString("");
        if (self->last == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->number = 0;
    }

    return (PyObject *)self;
}

static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
    PyObject *first=NULL, *last=NULL;

    static char *kwlist[] = {"first", "last", "number", NULL};

    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                      &first, &last,
                                      &self->number))
        return -1;

    if (first) {
        Py_XDECREF(self->first);
        Py_INCREF(first);
        self->first = first;
    }

    if (last) {
        Py_XDECREF(self->last);
        Py_INCREF(last);
        self->last = last;
    }

    return 0;
}

static PyMemberDef Noddy_members[] = {
    {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
     "first name"},
    {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
     "last name"},
    {"number", T_INT, offsetof(Noddy, number), 0,
     "noddy number"},
    {NULL}  /* Sentinel */
};

static PyObject *
Noddy_name(Noddy* self)
{
    static PyObject *format = NULL;
    PyObject *args, *result;

    if (format == NULL) {
        format = PyString_FromString("%s %s");
        if (format == NULL)
            return NULL;
    }

    if (self->first == NULL) {
        PyErr_SetString(PyExc_AttributeError, "first");
        return NULL;
    }

    if (self->last == NULL) {
        PyErr_SetString(PyExc_AttributeError, "last");
        return NULL;
    }

    args = Py_BuildValue("OO", self->first, self->last);
    if (args == NULL)
        return NULL;

    result = PyString_Format(format, args);
    Py_DECREF(args);

    return result;
}

static PyMethodDef Noddy_methods[] = {
    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

static PyTypeObject NoddyType = {
    PyObject_HEAD_INIT(NULL)
    0,                         /*ob_size*/
    "noddy.Noddy",             /*tp_name*/
    sizeof(Noddy),             /*tp_basicsize*/
    0,                         /*tp_itemsize*/
    (destructor)Noddy_dealloc, /*tp_dealloc*/
    0,                         /*tp_print*/
    0,                         /*tp_getattr*/
    0,                         /*tp_setattr*/
    0,                         /*tp_compare*/
    0,                         /*tp_repr*/
    0,                         /*tp_as_number*/
    0,                         /*tp_as_sequence*/
    0,                         /*tp_as_mapping*/
    0,                         /*tp_hash */
    0,                         /*tp_call*/
    0,                         /*tp_str*/
    0,                         /*tp_getattro*/
    0,                         /*tp_setattro*/
    0,                         /*tp_as_buffer*/
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /*tp_flags*/
    "Noddy objects",           /* tp_doc */
    (traverseproc)Noddy_traverse,   /* tp_traverse */
    (inquiry)Noddy_clear,           /* tp_clear */
    0,		               /* tp_richcompare */
    0,		               /* tp_weaklistoffset */
    0,		               /* tp_iter */
    0,		               /* tp_iternext */
    Noddy_methods,             /* tp_methods */
    Noddy_members,             /* tp_members */
    0,                         /* tp_getset */
    0,                         /* tp_base */
    0,                         /* tp_dict */
    0,                         /* tp_descr_get */
    0,                         /* tp_descr_set */
    0,                         /* tp_dictoffset */
    (initproc)Noddy_init,      /* tp_init */
    0,                         /* tp_alloc */
    Noddy_new,                 /* tp_new */
};

static PyMethodDef module_methods[] = {
    {NULL}  /* Sentinel */
};

#ifndef PyMODINIT_FUNC	/* declarations for DLL import/export */
#define PyMODINIT_FUNC void
#endif
PyMODINIT_FUNC
initnoddy4(void)
{
    PyObject* m;

    if (PyType_Ready(&NoddyType) < 0)
        return;

    m = Py_InitModule3("noddy4", module_methods,
                       "Example module that creates an extension type.");

    if (m == NULL)
      return;

    Py_INCREF(&NoddyType);
    PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
}
Download as text (original file name: noddy4.c).

traversal メソッドは循環した参照に含まれる可能性のある 内部オブジェクトへのアクセスを提供します:

static int
Noddy_traverse(Noddy *self, visitproc visit, void *arg)
{
    if (self->first && visit(self->first, arg) < 0)
        return -1;
    if (self->last && visit(self->last, arg) < 0)
        return -1;

    return 0;
}

循環した参照に含まれるかもしれない各内部オブジェクトに対して、 traversal メソッドに渡された visit() 関数を呼びます。 visit() 関数は内部オブジェクトと、traversal メソッドに渡された 追加の引数 arg を引数としてとります。

また、循環した参照に含まれた内部オブジェクトを消去するためのメソッドも 提供する必要があります。オブジェクト解放用のメソッドを再実装して、 このメッソドに使いましょう:

static int
Noddy_clear(Noddy *self)
{
    Py_XDECREF(self->first);
    self->first = NULL;
    Py_XDECREF(self->last);
    self->last = NULL;

    return 0;
}

static void
Noddy_dealloc(Noddy* self)
{
    Noddy_clear(self);
    self->ob_type->tp_free((PyObject*)self);
}

さいごに、Py_TPFLAGS_HAVE_GC フラグを クラス定義のフラグに加えます:

    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /*tp_flags*/

これで完了です。tp_alloc スロットまたは tp_free スロットが 書かれていれば、それらを循環ガベージコレクションに使えるよう修正すれば よいのです。 ほとんどの拡張機能は自動的に提供されるバージョンを使うでしょう。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 2.1.2 データ属性をこまかく制御する Up: 2.1 基本的なこと Next: 2.2 タイプメソッド


2.2 タイプメソッド

この節ではさまざまな実装可能なタイプメソッドと、 それらが何をするものであるかについて、ざっと説明します。

以下は PyTypeObject の定義です。デバッグビルドでしか使われない いくつかのメンバは省いてあります:

typedef struct _typeobject {
    PyObject_VAR_HEAD
    char *tp_name; /* For printing, in format "<module>.<name>" */
    int tp_basicsize, tp_itemsize; /* For allocation */

    /* Methods to implement standard operations */

    destructor tp_dealloc;
    printfunc tp_print;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    cmpfunc tp_compare;
    reprfunc tp_repr;

    /* Method suites for standard classes */

    PyNumberMethods *tp_as_number;
    PySequenceMethods *tp_as_sequence;
    PyMappingMethods *tp_as_mapping;

    /* More standard operations (here for binary compatibility) */

    hashfunc tp_hash;
    ternaryfunc tp_call;
    reprfunc tp_str;
    getattrofunc tp_getattro;
    setattrofunc tp_setattro;

    /* Functions to access object as input/output buffer */
    PyBufferProcs *tp_as_buffer;

    /* Flags to define presence of optional/expanded features */
    long tp_flags;

    char *tp_doc; /* Documentation string */

    /* Assigned meaning in release 2.0 */
    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* Assigned meaning in release 2.1 */
    /* rich comparisons */
    richcmpfunc tp_richcompare;

    /* weak reference enabler */
    long tp_weaklistoffset;

    /* Added in release 2.2 */
    /* Iterators */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

    /* Attribute descriptor and subclassing stuff */
    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
    struct _typeobject *tp_base;
    PyObject *tp_dict;
    descrgetfunc tp_descr_get;
    descrsetfunc tp_descr_set;
    long tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Low-level free-memory routine */
    inquiry tp_is_gc; /* For PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* method resolution order */
    PyObject *tp_cache;
    PyObject *tp_subclasses;
    PyObject *tp_weaklist;

} PyTypeObject;
Download as text (original file name: typestruct.h).

たくさんのメソッドがありますね。でもそんなに心配する必要はありません。 定義したい型があるなら、実装するのはこのうちのごくわずかですむことが ほとんどです。

すでに予想されているでしょうが、これらの多様なハンドラについて、 これからより詳しい情報を提供します。しかしこれらのメンバが構造体中で 定義されている順番は無視します。というのは、これらのメンバの現れる 順序は歴史的な遺産によるものだからです。型を初期化するさいに、これらの メンバを正しい順序で並べるよう、くれぐれも注意してください。 ふつういちばん簡単なのは、必要なメンバがすべて含まれている (たとえそれらが 0 に初期化されていても) 例をとってきて、 自分の型に合わせるよう変更をくわえることです。

    char *tp_name; /* 表示用 */

これは型の名前です。前節で説明したように、これはいろいろな場面で 現れ、ほとんどは診断用の目的で使われるものです。 なので、そのような場面で役に立つであろう名前を選んでください。

    int tp_basicsize, tp_itemsize; /* 割り当て用 */

これらのメンバは、この型のオブジェクトが作成されるときにどれだけのメモリを 割り当てればよいのかをランタイムに指示します。Python には可変長の構造体 (文字列やリストなどを想像してください) に対する組み込みのサポートが ある程度あり、ここで tp_itemsize メンバが使われます。 これらについてはあとでふれます。

    char *tp_doc;

ここには Python スクリプトリファレンス obj.__doc__ が docstring を 返すときの文字列 (あるいはそのアドレス) を入れます。

では次に、ほとんどの拡張型が実装するであろう基本的な タイプメソッドに入っていきます。

  • 2.2.1 最終化 (finalization) と解放
  • 2.2.2 Object Presentation
  • 2.2.3 属性を管理する
    • 2.2.3.1 総称的な属性を管理する
    • 2.2.3.2 特定の型に特化した属性の管理
  • 2.2.4 オブジェクトの比較
  • 2.2.5 抽象的なプロトコルのサポート
  • 2.2.6 その他いろいろ
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 2.1.3 循環ガベージコレクションをサポートする Up: 2. 新しい型を定義する Next: 2.2.1 最終化 (finalization) と解放


2.2.1 最終化 (finalization) と解放

    destructor tp_dealloc;

型のインスタンスの参照カウントがゼロになり、 Python インタプリタがそれを潰して再利用したくなると、 この関数が呼ばれます。解放すべきメモリをその型が保持していたり、 それ以外にも実行すべき後処理がある場合は、それらをここに入れます。 オブジェクトそれ自体もここで解放される必要があります。 この関数の例は、以下のようなものです:

static void
newdatatype_dealloc(newdatatypeobject * obj)
{
    free(obj->obj_UnderlyingDatatypePtr);
    obj->ob_type->tp_free(obj);
}

解放用関数でひとつ重要なのは、処理待ちの例外にいっさい手をつけないことです。 なぜなら、解放用の関数は Python インタプリタがスタックを元の状態に戻すときに 呼ばれることが多いからです。そして (通常の関数からの復帰でなく) 例外のために スタックが巻き戻されるときは、すでに発生している例外から解放用関数を 守るものはありません。解放用の関数がおこなう動作が追加の Python のコードを 実行してしまうと、それらは例外が発生していることを検知するかもしれません。 これはインタプリタが誤解させるエラーを発生させることにつながります。 これを防ぐ正しい方法は、安全でない操作を実行する前に処理待ちの例外を 保存しておき、終わったらそれを元に戻すことです。これは PyErr_Fetch()および PyErr_Restore()関数を使うことによって 可能になります:

static void
my_dealloc(PyObject *obj)
{
    MyObject *self = (MyObject *) obj;
    PyObject *cbresult;

    if (self->my_callback != NULL) {
        PyObject *err_type, *err_value, *err_traceback;
        int have_error = PyErr_Occurred() ? 1 : 0;

        if (have_error)
            PyErr_Fetch(&err_type, &err_value, &err_traceback);

        cbresult = PyObject_CallObject(self->my_callback, NULL);
        if (cbresult == NULL)
            PyErr_WriteUnraisable();
        else
            Py_DECREF(cbresult);

        if (have_error)
            PyErr_Restore(err_type, err_value, err_traceback);

        Py_DECREF(self->my_callback);
    }
    obj->ob_type->tp_free((PyObject*)self);
}

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 2.2 タイプメソッド Up: 2.2 タイプメソッド Next: 2.2.2 Object Presentation


2.2.2 Object Presentation

Python では、オブジェクトの文字列表現を生成するのに 3つのやり方があります: repr() 関数 (あるいはそれと等価な バッククォートを用いた表現) を使う方法、str() 関数を使う方法、そして print 文を使う方法です。 ほとんどのオブジェクトで print 文は str() 関数と 同じですが、 必要な場合には特殊なケースとして FILE* にも表示できます。 FILE* への表示は、効率が問題となっている場合で、一時的な 文字列オブジェクトを作成してファイルに書き込むのでは効率が悪すぎることが プロファイリングからも明らかな場合にのみ使うべきです。

これらのハンドラはどれも必須ではありません。 ほとんどの型ではせいぜい tp_str ハンドラと tp_repr ハンドラを実装するだけですみます。

    reprfunc tp_repr;
    reprfunc tp_str;
    printfunc tp_print;

tp_repr ハンドラは呼び出されたインスタンスの文字列表現を 格納した文字列オブジェクトを返す必要があります。簡単な例は以下のようなものです:

static PyObject *
newdatatype_repr(newdatatypeobject * obj)
{
    return PyString_FromFormat("Repr-ified_newdatatype{{size:\%d}}",
                               obj->obj_UnderlyingDatatypePtr->size);
}

tp_repr ハンドラが指定されていなければ、インタプリタは その型の tp_name とそのオブジェクトの一意な識別値をもちいて 文字列表現を作成します。

tp_str ハンドラと str() の関係は、上の tp_repr ハンドラと repr() の関係に相当します。 つまり、これは Python のコードがオブジェクトのインスタンスに対して str() を呼び出したときに呼ばれます。この関数の実装は tp_repr ハンドラのそれと非常に似ていますが、得られる文字列表現は 人間が読むことを意図されています。tp_str が指定されていない場合、 かわりに tp_repr ハンドラが使われます。

以下は簡単な例です:

static PyObject *
newdatatype_str(newdatatypeobject * obj)
{
    return PyString_FromFormat("Stringified_newdatatype{{size:\%d}}",
                               obj->obj_UnderlyingDatatypePtr->size);
}

print ハンドラは Python がその型のインスタンスを「print する」必要の あるときに毎回呼ばれます。たとえば 'node' が TreeNode 型のインスタンスだと すると、print ハンドラは Python が以下を実行したときに呼ばれます:

print node

flags 引数には Py_PRINT_RAW というフラグがあり、 これはその文字列をクォートやおそらくはエスケープシーケンスの解釈もなしで 表示することを指示します。

この print 関数は FILE* オブジェクトを引数としてとります。 たぶん、ここに出力することになるでしょう。

print 関数の例は以下のようになります:

static int
newdatatype_print(newdatatypeobject *obj, FILE *fp, int flags)
{
    if (flags & Py_PRINT_RAW) {
        fprintf(fp, "<{newdatatype object--size: %d}>",
                obj->obj_UnderlyingDatatypePtr->size);
    }
    else {
        fprintf(fp, "\"<{newdatatype object--size: %d}>\"",
                obj->obj_UnderlyingDatatypePtr->size);
    }
    return 0;
}

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 2.2.1 最終化 (finalization) と解放 Up: 2.2 タイプメソッド Next: 2.2.3 属性を管理する


2.2.3 属性を管理する

属性をもつどのオブジェクトに対しても、その型は、 それらオブジェクトの属性をどのように解決するか制御する関数を提供する 必要があります。必要な関数としては、属性を (それが定義されていれば) 取り出すものと、もうひとつは属性に (それが許可されていれば) 値を 設定するものです。属性を削除するのは特殊なケースで、この場合は 新しい値としてハンドラに NULLが渡されます。

Python は 2つの属性ハンドラの組をサポートしています。 属性をもつ型はどちらか一組を実装するだけでよく、それらの違いは 一方の組が属性の名前を char* として受け取るのに対して もう一方の組は属性の名前を PyObject* として受け取る、というものです。 それぞれの型はその実装にとって都合がよい方を使えます。

    getattrfunc  tp_getattr;        /* char * バージョン */
    setattrfunc  tp_setattr;
    /* ... */
    getattrofunc tp_getattrofunc;   /* PyObject * バージョン */
    setattrofunc tp_setattrofunc;

オブジェクトの属性へのアクセスがつねに (すぐあとで説明する) 単純な操作だけならば、PyObject* を使って属性を管理する 関数として、総称的 (generic) な実装を使えます。 特定の型に特化した属性ハンドラの必要性は Python 2.2 からほとんど完全に なくなりました。しかし、多くの例はまだ、この新しく使えるようになった 総称的なメカニズムを使うよう更新されてはいません。

  • 2.2.3.1 総称的な属性を管理する
  • 2.2.3.2 特定の型に特化した属性の管理
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 2.2.2 Object Presentation Up: 2.2 タイプメソッド Next: 2.2.3.1 総称的な属性を管理する


2.2.4 オブジェクトの比較

    cmpfunc tp_compare;

tp_compare ハンドラは、オブジェクトどうしの比較が必要で、 そのオブジェクトに要求された比較をおこなうのに適した特定の拡張比較メソッドが 実装されていないときに呼び出されます。(これが定義されているとき、 PyObject_Compare() または PyObject_Cmp() が使われると これはつねに呼び出されます、また Python で cmp() が使われたときにも 呼び出されます。) これは __cmp__() メソッドに似ています。 この関数はもし obj1 が obj2 より「小さい」場合は -1 を返し、 それらが等しければ 0、そしてもし obj1 が obj2 より 「大きい」場合は1 を返す必要があります。 (以前は大小比較の結果として、任意の大きさの負または正の整数を返せましたが、 Python 2.2 以降ではこれはもう許されていません。将来的には、上にあげた 以外の返り値は別の意味をもつ可能性があります。)

tp_compare ハンドラは例外を発生させられます。 この場合、この関数は負の値を返す必要があります。呼び出した側は PyErr_Occurred() を使って例外を検査しなければなりません。

以下はサンプル実装です:

static int
newdatatype_compare(newdatatypeobject * obj1, newdatatypeobject * obj2)
{
    long result;

    if (obj1->obj_UnderlyingDatatypePtr->size <
        obj2->obj_UnderlyingDatatypePtr->size) {
        result = -1;
    }
    else if (obj1->obj_UnderlyingDatatypePtr->size >
             obj2->obj_UnderlyingDatatypePtr->size) {
        result = 1;
    }
    else {
        result = 0;
    }
    return result;
}

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 2.2.3.2 特定の型に特化した属性の管理 Up: 2.2 タイプメソッド Next: 2.2.5 抽象的なプロトコルのサポート


2.2.5 抽象的なプロトコルのサポート

Python はいくつもの 抽象的な “プロトコル” をサポートしています。 これらを使用する特定のインターフェイスについては Python/C API Reference Manual の 「Abstract Objects Layer」の章で解説されて います。

これら多数の抽象的なインターフェイスは、Python の実装が開発される 初期の段階で定義されていました。とりわけ数値や辞書、そしてシーケンスなどの プロトコルは最初から Python の一部だったのです。それ以外のプロトコルは その後追加されました。 型の実装にあるいくつかのハンドラルーチンに依存するようなプロトコル のために、古いプロトコルはハンドラの入ったオプションのブロックとして 定義し、型オブジェクトから参照するようになりました。 タイプオブジェクトの主部に追加のスロットをもつ新しいプロトコルについては、 フラグ用のビットを立てることでそれらのスロットが存在しており、 インタプリタがチェックすべきであることを指示できます。 (このフラグ用のビットは、そのスロットの値が 非 NULLであることを 示しているわけではありません。フラグはスロットの存在を示すのに使えますが、 そのスロットはまだ埋まっていないかもしれないのです。)

    PyNumberMethods   tp_as_number;
    PySequenceMethods tp_as_sequence;
    PyMappingMethods  tp_as_mapping;

お使いのオブジェクトを数値やシーケンス、あるいは辞書のようにふるまうように したいならば、それぞれに C の PyNumberMethods 構造体、 PySequenceMethods 構造体、または PyMappingMethods 構造体のアドレスを 入れます。これらに適切な値を入れても入れなくてもかまいません。 これらを使った例は Python の配布ソースにある Objects で みつけることができるでしょう。

    hashfunc tp_hash;

この関数は、もし使うのならば、これはお使いの型のインスタンスの ハッシュ番号を返すようにします。以下はやや的はずれな例ですが :

static long
newdatatype_hash(newdatatypeobject *obj)
{
    long result;
    result = obj->obj_UnderlyingDatatypePtr->size;
    result = result * 3;
    return result;
}

    ternaryfunc tp_call;

この関数は、その型のインスタンスが「関数として呼び出される」ときに呼ばれます。 たとえばもし obj1 にそのインスタンスが入っていて、Python スクリプトで obj1('hello') を実行したとすると、 tp_call ハンドラが 呼ばれます。

この関数は 3つの引数をとります:

  1. arg1 にはその呼び出しの対象となる、 そのデータ型のインスタンスが入ります。たとえば呼び出しが obj1('hello') の場合、arg1 は obj1 になります。

  2. arg2 は呼び出しの引数を格納しているタプルです。 ここから引数を取り出すには PyArg_ParseTuple() を使います。

  3. arg3 はキーワード引数のための辞書です。これが NULL 以外で キーワード引数をサポートしているなら、 PyArg_ParseTupleAndKeywords() をつかって引数を取り出せます。キーワード引数をサポートしていないのに これが NULL 以外の場合は、キーワード引数はサポートしていない旨の メッセージとともに TypeError を発生させてください。

以下はこの call 関数をてきとうに使った例です。

/* call 関数の実装。
 *    obj1 : 呼び出しを受けるインスタンス。
 *    obj2 : 呼び出しのさいの引数を格納するタプル、この場合は 3つの文字列。
 */
static PyObject *
newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *other)
{
    PyObject *result;
    char *arg1;
    char *arg2;
    char *arg3;

    if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {
        return NULL;
    }
    result = PyString_FromFormat(
        "Returning -- value: [\%d] arg1: [\%s] arg2: [\%s] arg3: [\%s]\n",
        obj->obj_UnderlyingDatatypePtr->size,
        arg1, arg2, arg3);
    printf("\%s", PyString_AS_STRING(result));
    return result;
}

    /* バージョン 2.2 以降で追加 */
    /* Iterators */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

これらの関数はイテレータ用プロトコルをサポートします。 オブジェクトが、その (ループ中に順に生成されていくかもしれない) 内容を 巡回 (訳注: イテレータでひとつずつ要素をたどっていくこと) する イテレータをサポートしたい場合は、tp_iter ハンドラを 実装する必要があります。 tp_iter ハンドラによって返される オブジェクトは tp_iter と tp_iternext の両方を実装する必要が あります。 どちらのハンドラも、それが呼ばれたインスタンスをひとつだけ引数としてとり、 新しい参照を返します。エラーが起きた場合には例外を設定してから NULLを返す必要があります。

巡回可能な要素を表現するオブジェクトに対しては、tp_iter ハンドラが イテレータオブジェクトを返す必要があります。イテレータオブジェクトは 巡回中の状態を保持する責任をもっています。お互いに干渉しない複数の イテレータの存在を許すようなオブジェクト (リストやタプルがそうです) の場合は、 新しいイテレータを作成して返す必要があります。 (巡回の結果生じる副作用のために) 一回だけしか巡回できないオブジェクトの場合は、それ自身への参照を返すような ハンドラと、 tp_iternext ハンドラも実装する必要があります。 ファイルオブジェクトはそのようなイテレータの例です。

イテレータオブジェクトは両方のハンドラを実装する必要があります。 tp_iter ハンドラはそのイテレータへの新しい参照を返します (これは破壊的にしか巡回できないオブジェクトに対する tp_iter ハンドラと同じです)。 tp_iternext ハンドラはその次のオブジェクトがある場合、それへの 新しい参照を返します。巡回が終端に達したときは例外を出さずに NULL を 返してもいいですし、 StopIteration を放出してもかまいません。 例外を使わないほうがやや速度が上がるかもしれません。 実際のエラーが起こったときには、例外を放出して NULLを返す必要があります。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 2.2.4 オブジェクトの比較 Up: 2.2 タイプメソッド Next: 2.2.6 その他いろいろ


2.2.6 その他いろいろ

上にあげたほとんどの関数は、その値として 0 を与えれば 省略できることを忘れないでください。それぞれの関数で提供しなければならない 型の定義があり、これらは Python の include 用ディレクトリの object.h というファイルにおさめられています。これは Python の 配布ソースに含まれています。

新しいデータ型に何らかのメソッドを実装するやりかたを学ぶには、 以下の方法がおすすめです: Python の配布されているソースをダウンロードして 展開する。Objects ディレクトリへ行き、C のソースファイルから 「tp_欲しい名前」の文字列で検索する (たとえば tp_print とか tp_compare のように)。こうすれば実装したい例がみつかるでしょう。

あるオブジェクトが、いま実装している型のインスタンスであるかどうかを 確かめたい場合には、 PyObject_TypeCheck 関数を使ってください。 使用例は以下のようなかんじです:

    if (! PyObject_TypeCheck(some_object, &MyType)) {
        PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");
        return NULL;
    }
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 2.2.5 抽象的なプロトコルのサポート Up: 2.2 タイプメソッド Next: 3. distutils による C


3. distutils による C および C++ 拡張モジュールのビルド

Python 1.4 になってから、動的にリンクされるような拡張モジュール をビルドするためのメイクファイルを作成するような、特殊なメイクファイル をUnix 向けに提供するようになりました。Python 2.0 からは この機構 (いわゆる Makefile.pre.in および Setup ファイルの関係ファイル) はサポートされなくなりました。インタプリタ自体のカスタマイズは ほとんど使われず、 distutils で拡張モジュールをビルドできる ようになったからです。

distutils を使った拡張モジュールのビルドには、ビルドを行う計算機上に distutils をインストールしていることが必要です。 Python 2.x には distutils が入っており、 Python 1.5 用には個別の パッケージがあります。distutils はバイナリパッケージの作成も サポートしているので、ユーザが拡張モジュールをインストールする 際に、必ずしもコンパイラが必要というわけではありません。

distutils ベースのパッケージには、駆動スクリプト (driver script) となる setup.py が入っています。 setup.py は普通の Python プログラムファイルで、ほとんどの場合 以下のような見かけになっています:

from distutils.core import setup, Extension

module1 = Extension('demo',
                    sources = ['demo.c'])

setup (name = 'PackageName',
       version = '1.0',
       description = 'This is a demo package',
       ext_modules = [module1])

この setup.py とファイル demo.c があるとき、以下の コマンド

python setup.py build

を実行すると、demo.c をコンパイルして、"demo" という名前の 拡張モジュールをbuild ディレクトリ内に生成します。 システムによってはモジュールファイルは build/lib.system サブディレクトリに生成され、demo.so や demo.pyd といった名前になることがあります。

setup.py 内では、コマンドの実行はすべて "setup" 関数を 呼び出して行います。この関数は可変個のキーワード引数をとります。 例ではその一部を使っているにすぎません。 もっと具体的にいうと、例の中ではパッケージをビルドするための メタ情報と、パッケージの内容を指定しています。 通常、パッケージには Python ソースモジュールやドキュメント、 サブパッケージ等といった別のファイルも入ります。 distutils の機能に関する詳細は、 Python モジュールの配布 に書かれている distutils のドキュメントを参照してください; この節では、拡張モジュールのビルドについてのみ説明します。

駆動スクリプトをよりよく構成するために、決め打ちの引数を setup に入れておくことがよくあります。 上の例では、setup の "ext_modules" は 拡張モジュールのリストで、リストの各々の要素は Extension クラスのインスタンスになっています。 上の例では、"demo" という名の拡張モジュールを定義していて、単一の ソースファイルdemo.c をコンパイルしてビルドするよう定義しています。

多くの場合、拡張モジュールのビルドはもっと複雑になります。 というのは、プリプロセッサ定義やライブラリの追加指定が必要に なることがあるからです。例えば以下のファイルがその実例です。

from distutils.core import setup, Extension

module1 = Extension('demo',
                    define_macros = [('MAJOR_VERSION', '1'),
                                     ('MINOR_VERSION', '0')],
                    include_dirs = ['/usr/local/include'],
                    libraries = ['tcl83'],
                    library_dirs = ['/usr/local/lib'],
                    sources = ['demo.c'])

setup (name = 'PackageName',
       version = '1.0',
       description = 'This is a demo package',
       author = 'Martin v. Loewis',
       author_email = 'martin@v.loewis.de',
       url = 'http://www.python.org/doc/current/ext/building.html',
       long_description = '''
This is really just a demo package.
''',
       ext_modules = [module1])

この例では、setup は追加のメタ情報と共に呼び出されます。 配布パッケージを構築する際には、メタ情報の追加が推奨されています。 拡張モジュール自体については、プリプロセッサ定義、インクルードファイルの ディレクトリ、ライブラリのディレクトリ、ライブラリといった指定が あります。 distutils はこの情報をコンパイラに応じて異なるやり方で引渡します。 例えば、Unix では、上の設定は以下のようなコンパイルコマンドに なるかもしれません:

gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o

gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so

これらのコマンドラインは実演目的で書かれたものです; distutils の ユーザは distutils が正しくコマンドを実行すると信用してください。

  • 3.1 拡張モジュールの配布
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 2.2.6 その他いろいろ Up: Python インタプリタの拡張と埋め込み Next: 3.1 拡張モジュールの配布


3.1 拡張モジュールの配布

拡張モジュールをうまくビルドできたら、三通りの使い方があります。

エンドユーザは普通モジュールをインストールしようと考えます; これには

python setup.py install
を実行します。

モジュールメンテナはソースパッケージを作成します; これには

python setup.py sdist
を実行します。

場合によっては、ソース配布物に追加のファイルを含める必要が あります; これにはMANIFEST.in ファイルを使います; 詳しくは distutils のドキュメントを参照してください。

ソースコード配布物をうまく構築できたら、メンテナはバイナリ配布物も 作成できます。プラットフォームに応じて、以下のコマンドのいずれかを 使います。

python setup.py bdist_wininst
python setup.py bdist_rpm
python setup.py bdist_dumb
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 3. distutils による C Up: 3. distutils による C Next: 4. Windows 上での C


4. Windows 上での C および C++ 拡張モジュールのビルド

この章では Windows 向けの Python 拡張モジュールを Microsoft Visual C++ を使って作成する方法について簡単に述べ、その後に拡張モジュールの ビルドがどのように動作するのかについて詳しい背景を述べます。 この説明は、Python 拡張モジュールを作成する Windows プログラマと、 Unix と Windows の双方でうまくビルドできるようなソフトウェアの 作成に興味がある Unix プログラマの双方にとって有用です。

モジュールの作者には、この節で説明している方法よりも、 distutils によるアプローチで拡張モジュールをビルドするよう勧めます。 また、Python をビルドした際に使われた C コンパイラが必要です; 通常は Microsoft Visual C++です。

注意: この章では、Python のバージョン番号が符号化されて入っている たくさんのファイル名について触れます。これらのファイル名は "XY" で表されるバージョン名付きで表現されます; "X" は使っている Python リリースのメジャーバージョン番号、 "Y" はマイナーバージョン番号です。 例えば、 Python 2.2.1 を使っているなら、"XY" は実際には "22" になります。

  • 4.1 型どおりのアプローチ
  • 4.2 Unix と Windows の相違点
  • 4.3 DLL 使用の実際
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 3.1 拡張モジュールの配布 Up: Python インタプリタの拡張と埋め込み Next: 4.1 型どおりのアプローチ


4.1 型どおりのアプローチ

Windows での拡張モジュールのビルドには、Unixと同じように、 distutils パッケージを使ったビルド作業の制御と 手動の二通りのアプローチがあります。 distutils によるアプローチはほとんどの拡張モジュールで うまくいきます; distutils を使った拡張モジュールの ビルドとパッケージ化については、 Python モジュールの配布 に あります。この節では、C や C++で書かれた Python 拡張モジュール を手動でビルドするアプローチについて述べます。

以下の説明に従って拡張モジュールをビルドするには、インストールされている Python と同じバージョンの Python のソースコードを持っていなければ なりません。また、 Microsoft Visual C++ ``Developer Studio'' が必要になります; プロジェクトファイルは VC++ バージョン 6 向けのものが提供されていますが、以前のバージョンの VC++も 使えます。ここで述べる例題のファイルは、Python ソースコードと 共に配布されており、PC\example_nt\ ディレクトリにあります。

  1. 例題ファイルをコピーする
    example_nt ディレクトリは PC ディレクトリのサブディレクトリ になっています。これは PC 関連の全てのファイルをソースコード配布物内の 同じディレクトリに置くための措置です。とはいえ実際には、 example_nt ディレクトリはPC の下では利用できません。 そこで、まずこのディレクトリを一階層上にコピーして、 example_nt が PC および Include と同じ 階層のディレクトリになるようにします。 以降の作業は、移動先の新しいディレクトリ内で行ってください。

  2. プロジェクトを開く
    VC++から、 ファイル > ワークスペースを開く ダイアログメニューを選択します (ファイル > 開く ではありません!)。ディレクトリ階層を辿って、example_nt をコピーしたディレクトリ 内のexample.dsw を選択 し、「開く」をクリックします。

  3. 例題の DLL をビルドする
    設定が全て正しく行われているか調べるために、ビルドしてみます:

    1. ビルド構成を選びます。このステップは省略できます。 ビルド > アクティブな構成の選択 を選び、 ``example - Win32 リリース'' または ``example - Win32 デバッグ'' を選びます。このステップを飛ばすと、VC++ はデフォルトで デバッグ構成を使います。

    2. DLL をビルドします。デバッグモードなら、 ビルド > example_d.dll のビルド を、 リリースモードなら ビルド > example.dll を選びます。 この操作で。全ての中間ファイルおよび最終ファイルが、上のビルド構成 で選んだ構成に従ってDebug または Release という名前の ディレクトリに生成されます。

  4. デバッグモードの DLL をテストする
    デバッグビルドが成功したら、コマンドプロンプトを起動し、 example_nt\Debug ディレクトリに移動して ください。以下のセッション通りにコマンドを実行できるはずです (C> は DOS コマンドのプロンプト、>>> は Python のプロンプトです; ビルド情報や様々なデバッグ出力は、 ここに示したスクリーン出力と一致しないこともあるので注意して下さい):

    C>..\..\PCbuild\python_d
Adding parser accelerators ...
Done.
Python 2.2 (#28, Dec 19 2001, 23:26:37) [MSC 32 bit (Intel)] on win32
Type "copyright", "credits" or "license" for more information.
>>> import example
[4897 refs]
>>> example.foo()
Hello, world
[4903 refs]
>>>

    おめでとうございます! とうとう初めての Python 拡張モジュールのビルド に成功しましたね。

  5. 自分用にプロジェクトを作成する
    プロジェクト用のディレクトリを適当な名前で作成してください。 自作の C ソースコードをディレクトリ内にコピーします。 モジュールのソースコードファイル名は必ずしもモジュール名と 一致している必要はありませんが、初期化関数の名前はモジュール名と 一致していなければなりません -- 初期化関数の名前が initspam() なら、モジュールはspam という 名前でしか import できません。initspam() は 第一引数を "spam" にして、Py_InitModule() を 呼び出します (このディレクトリにある、最小限の内容が書かれている example.c を手がかりにするとよいでしょう)。 ならわしとして、ファイルはspam.c または spammodule.c という名前にしておきます。 出力ファイル名はリリースモードでは smap.dll や spam.pyd、 デバッグモードではsmap_d.dll や spam_d.pyd、になるはず です (後者は、システムライブラリ spam.dll と、Python インタフェースとなる自作のモジュールとの混同を避けるために 推奨されています) 。

    さて、やり方は二通りあります:

    1. example.dsw と example.dsp をコピーし、 spam.* に名前を変えて、手作業で編集する
    2. 新しくプロジェクトを作成する; 説明は下にあります。

    どちらの場合も、example_nt\example.def を spam\spam.def にコピーして、新たにできた spam.def を編集し、二行目に `initspam' が入るように します。 自分で新たなプロジェクトを作成したのなら、ここで spam.def を プロジェクトに追加しておいてください (このファイルはたった二行しか ない目障りなファイルです。.def ファイルを全く無視するという 方法もあり、それには /exprt:initspam を 「プロジェクトのオプション」ダイアログにあるリンク設定のどこかに 手動で追加します)。

  6. 新しくプロジェクトを作成する
    ファイル > 新規作成 > プロジェクト ダイアログ を使って、新たなプロジェクト用ワークスペースを作成します。 ``Win32 ダイナミックリンクライブラリ'' を選択し、名前("spam") を入れ、「場所」が先ほど作成した spam ディレクトリ下に (Python ビルドツリーの直下のサブディレクトリで、Include および PC と同じディレクトリになるはずです) あることを 確かめます。「作成」をクリックします。

    プロジェクト > 設定 ダイアログを開きます。 ほんのいくつかですが、設定の変更が必要です。 「構成」ドロップダウンリストに「すべての構成」が設定されているか 確かめてください。C/C++ タブを選び、ポップアップメニュー から「プリプロセッサ」カテゴリを選びます。 以下のテキスト:

    ..\Include,..\PC
    を、「追加のインクルードディレクトリ」とラベルされた エントリボックスに入力します

    次に、「リンカ」タブの「入力」カテゴリを選び、

    ..\PCbuild

    を ``追加のライブラリディレクトリ'' と書かれたテキストボックスに 入力します。

    さて、構成ごとに特有の設定をいくつか行う必要があります:

    「構成」 ドロップダウンリストから、``Win32 リリース'' を 選んでください。「リンク」タブをクリックし、「入力」カテゴリを 選んで、「追加の依存ファイル」ボックス内のリストにpythonXY.lib を追加します。

    「構成」 ドロップダウンリストから、``Win32 デバッグ'' に切り替え、 「追加の依存ファイル」ボックス内のリストにpythonXY_d.lib を追加します。 次に C/C++ タブをクリックして、 ``コード生成'' をカテゴリから 選び、 ``ラインタイムライブラリ'' に対して ``マルチスレッド デバッグ DLL'' を選びます。

    「構成」ドロップダウンリストから ``Win32 リリース'' に切り替えなおし ます。 ``ラインタイムライブラリ'' に対して ``マルチスレッド DLL'' を選びます。

    前の節で述べたspam.def をここで作成しておかねばなりません。 その後、追加 > ファイルをプロジェクトに追加 ダイアログを選びます。「ファイルの種類」を *.* にして、 spam.c と spam.def を選び、 OK をクリックします (一つ一つファイルを追加してもかまいません)。

作っているモジュールが新たな型を作成するのなら、 以下の行:

    PyObject_HEAD_INIT(&PyType_Type)

がうまくいかないはずです。そこで:

    PyObject_HEAD_INIT(NULL)

に変更してください。また、以下の行をモジュール初期化関数に加えます:

    MyObject_Type.ob_type = &PyType_Type;

この操作を行う詳しい理由は、 Python FAQ の 第 3 節を参照してください。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 4. Windows 上での C Up: 4. Windows 上での C Next: 4.2 Unix と Windows


4.2 Unix と Windows の相違点

Unix と Windows では、コードの実行時読み込みに全く異なる パラダイムを用いています。動的ロードされるようなモジュールをビルド しようとする前に、自分のシステムがどのように動作するか 知っておいてください。

Unixでは、共有オブジェクト (.so) ファイルにプログラムが 使うコード、そしてプログラム内で使う関数名やデータが入っています。 ファイルがプログラムに結合されると、これらの関数やデータに 対するファイルのコード内の全ての参照は、メモリ内で関数やデータが 配置されている、プログラム中の実際の場所を指すように変更されます。 これは基本的にはリンク操作にあたります。

Windows では、動的リンクライブラリ (.dll) ファイルには ぶら下がり参照 (dangling reference) はありません。 その代わり、関数やデータへのアクセスはルックアップテーブルを 介します。従って DLL コードの場合、実行時にポインタがプログラム メモリ上の正しい場所を指すように修正する必要はありません; その代わり、コードは常に DLL のルックアップテーブルを使い、 ルックアップテーブル自体は実行時に実際の関数やデータを指すように 修正されます。

Unixには、唯一のライブラリファイル形式 (.a) しかありません。 .a ファイルには複数のオブジェクトファイル (.o) 由来の コードが入っています。共有オブジェクトファイル (.so) を作成 するリンク処理の段階中に、リンカは定義場所の不明な識別子に遭遇する ことがあります。このときリンカはライブラリ内のオブジェクトファイルを 検索します; もし識別子が見つかると、リンカはそのオブジェクトファイルから 全てのコードを取り込みます。

Windows では、二つの形式のライブラリ、静的ライブラリとインポート ライブラリがあります (どちらも.lib と呼ばれています)。 静的ライブラリは Unix における .a ファイルに似ています; このファイルには、必要に応じて取り込まれるようなコードが入っています。 インポートライブラリは、基本的には特定の識別子が不正ではなく、 DLL がロードされた時点で存在することを保証するためにだけ使われます。 リンカはインポートライブラリからの情報を使ってルックアップテーブル を作成し、DLL に入っていない識別子を使えるようにします。 アプリケーションや DLL がリンクされるさい、インポートライブラリ が生成されることがあります。このライブラリは、アプリケーションや DLL 内のシンボルに依存するような、将来作成される全ての DLL で 使うために必要になります。

二つの動的ロードモジュール、B と C を作成し、別のコードブロック A を 共有するとします。Unixでは、 A.a を B.so やC.so をビルドするときのリンカに渡したりはしません; そんなことをすれば、 コードは二度取り込まれ、B と C のそれぞれが自分用のコピーを持って しまいます。 Windows では、A.dll をビルドするとA.lib もビルドされます。 B や C のリンクにはA.lib を渡します。 A.lib にはコードは 入っていません; 単に A のコードにアクセスするするために実行時に 用いられる情報が入っているだけです。

Windows ではインポートライブラリの使用は "import spam"とするようなものです; この操作によって spam の名前にアクセスできますが、 コードのコピーを個別に作成したりはしません。Unixでは、ライブラリとの リンクはむしろ "from spam import *" に似ています; この操作では個別にコードのコピーを生成します。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 4.1 型どおりのアプローチ Up: 4. Windows 上での C Next: 4.3 DLL 使用の実際


4.3 DLL 使用の実際

Windows 版の Python は Microsoft Visual C++でビルドされています; 他のコンパイラを使うと、うまく動作したり、しなかったりします (Borland も一見うまく動作しません)。この節の残りの部分は MSVC++ 向けの説明です。

Windows で DLL を作成する際は、pythonXY.lib をリンカに 渡さねばなりません。 例えば二つの DLL 、spam と ni (spam の中には C 関数が入っているとします) をビルドするには、以下のコマンドを 実行します:

cl /LD /I/python/include spam.c ../libs/pythonXY.lib
cl /LD /I/python/include ni.c spam.lib ../libs/pythonXY.lib

最初のコマンドで、三つのファイル: spam.obj、spam.dll および spam.lib ができます。 Spam.dll には (PyArg_ParseTuple() のような) Python 関数は全く入って いませんが、pythonXY.lib のおかげで Python コードを 見つけることはできます。

二つ目のコマンドでは、ni.dll (および .obj と .lib) ができ、このライブラリは spam と Python 実行形式中の 必要な関数をどうやって見つければよいか知っています。

全ての識別子がルックアップテーブル上に公開されるわけではありません。 他のモジュール (Python 自体を含みます) から、自作の識別子が 見えるようにするには、 "void _declspec(dllexport) initspam(void)" や "PyObject _declspec(dllexport) *NiGetSpamData(void)"のように、"_declspec(dllexport)" で宣言せねばなりません。

Developer Studio は必要もなく大量のインポートライブラリを DLL に 突っ込んで、実行形式のサイズを 100K も大きくしてしまいます。 不用なライブラリを追い出したければ、「プロジェクトのプロパティ」 ダイアログを選び、「リンカ」タブに移動して、 インポートライブラリの無視 を指定します。その後、 適切なmsvcrtxx.lib をライブラリのリストに追加してください。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 4.2 Unix と Windows Up: 4. Windows 上での C Next: 5. 他のアプリケーションへの Python の埋め込み


5. 他のアプリケーションへの Python の埋め込み

前章では、 Python を拡張する方法、すなわち C 関数のライブラリを Python に結びつけて機能を拡張する方法について述べました。 同じようなことを別の方法でも実行できます: それは、自分の C/C++ アプリケーションに Python を埋め込んで機能を強化する、というものです。 埋め込みを行うことで、アプリケーションの何らかの機能を C や C++ の代わりに Python で実装できるようになります。 埋め込みは多くの用途で利用できます; ユーザが Python でスクリプトを書き、 アプリケーションを自分好みに仕立てられるようにする、というのが その一例です。プログラマが、特定の機能を Python でより楽に書ける場合に 自分自身のために埋め込みを行うこともできます。

Python の埋め込みは Python の拡張と似ていますが、全く同じという わけではありません。その違いは、Python を拡張した場合には アプリケーションのメインプログラムは依然として Python インタプリタ である一方、 Python を組み込みんだ場合には、メインプログラムには Python が関係しない -- その代わりに、アプリケーションのある一部分 が時折 Python インタプリタを呼び出して何らかの Python コードを 実行させる -- かもしれない、ということです。

従って、 Python の埋め込みを行う場合、自作のメインプログラムを 提供しなければなりません。メインプログラムがやらなければならないこと の一つに、 Python インタプリタの初期化があります。とにかく少なくとも 関数 Py_Initialize() (Mac OS ならPyMac_Initialize()) を呼び出さねばなりません。 オプションとして、Python 側にコマンドライン引数を渡すために関数呼び出し を行います。その後、アプリケーションのどこでもインタプリタを 呼び出せるようになります。

インタプリタを呼び出すには、異なるいくつかの方法があります: Python 文が入った文字列をPyRun_SimpleString() に渡す、 stdio ファイルポインタとファイル名 (これはエラーメッセージ内で コードを識別するためだけのものです) を PyRun_SimpleFile() に渡す、といった具合です。 これまでの各章で説明した低水準の操作を呼び出して、Python オブジェクトを 構築したり使用したりもできます。

Python の埋め込みを行っている簡単なデモは、ソース配布物の Demo/embed/ ディレクトリにあります。

参考資料:

Python/C API リファレンスマニュアル
Python C インタフェースの詳細はこのマニュアルに書かれています。 必要な情報の大部分はここにあるはずです。

  • 5.1 高水準の埋め込み
  • 5.2 超高水準の埋め込みから踏み出す: 概要
  • 5.3 純粋な埋め込み
  • 5.4 埋め込まれた Python の拡張
  • 5.5 C++による Python の埋め込み
  • 5.6 リンクに関する要件
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 4.3 DLL 使用の実際 Up: Python インタプリタの拡張と埋め込み Next: 5.1 高水準の埋め込み


5.1 高水準の埋め込み

Python の埋め込みの最も簡単な形式は、超高水準インタフェースの 利用です。 このインタフェースは、アプリケーションとやり取りする必要がない Python スクリプトを実行するためのものです。 例えばこれは、一つのファイル上で何らかの操作を実現するのに利用 できます。

#include <Python.h>

int
main(int argc, char *argv[])
{
  Py_Initialize();
  PyRun_SimpleString("from time import time,ctime\n"
                     "print 'Today is',ctime(time())\n");
  Py_Finalize();
  return 0;
}

上のコードでは、まず Python インタプリタを Py_Initialize() で起動し、続いてハードコードされた Python スクリプトで日付と時間の出力を実行します。 その後、Py_Finalize() の呼び出しでインタプリタを 終了し, プログラムの終了に続きます。 実際のプログラムでは、Python スクリプトを他のソース、おそらく テキストエディタルーチンやファイル、データベースから取り出したいと 考えるかもしれません。Python コードをファイルから取り出すには、 PyRun_SimpleFile() 関数を使うのがよいでしょう。 この関数はメモリを確保して、ファイルの内容をロードする手間を 省いてくれます。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 5. 他のアプリケーションへの Python の埋め込み Up: 5. 他のアプリケーションへの Python の埋め込み Next: 5.2 超高水準の埋め込みから踏み出す: 概要


5.2 超高水準の埋め込みから踏み出す: 概要

高水準インタフェースは、断片的な Python コードをアプリケーションから 実行できるようにしてくれますが、アプリケーションと Python コードの 間でのデータのやり取りは、控えめに言っても煩わしいものです。 データのやり取りをしたいなら、より低水準のインタフェース呼び出しを 利用しなくてはなりません。より多く C コードを書かねばならない 代わりに、ほぼ何でもできるようになります。

Python の拡張と埋め込みは、趣旨こそ違え、同じ作業であるということ に注意せねばなりません。これまでの章で議論してきたトピックの ほとんどが埋め込みでもあてはまります。これを示すために、 Python から C への拡張を行うコードが実際には何をするか考えて みましょう:

  1. データ値を Python から C に変換する。
  2. 変換された値を使って C ルーチンの関数呼び出しを行い、
  3. 呼び出しで得られたデータ値 C から Python に変換する。

Python を埋め込む場合には、インタフェースコードが行う作業は以下の ようになります:

  1. データ値を C から Python に変換する。
  2. 変換された値を使って Python インタフェースルーチンの 関数呼び出しを行い、
  3. 呼び出しで得られたデータ値 Python から C に変換する。

一見して分かるように、データ変換のステップは、言語間でデータを 転送する方向が変わったのに合わせて単に入れ替えただけです。 唯一の相違点は、データ変換の間にあるルーチンです。 拡張を行う際には C ルーチンを呼び出しますが、埋め込みの 際には Python ルーチンを呼び出します。

この章では、Python から C へ、そしてその逆へとデータを変換する 方法については議論しません。また、正しい参照の使い方やエラーの 扱い方についてすでに理解しているものと仮定します。 これらの側面についてはインタプリタの拡張と何ら変わるところが ないので、必要な情報については以前の章を参照できます。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 5.1 高水準の埋め込み Up: 5. 他のアプリケーションへの Python の埋め込み Next: 5.3 純粋な埋め込み


5.3 純粋な埋め込み

最初に例示するプログラムは、Python スクリプト内の関数を実行する ためのものです。超高水準インタフェースに関する節で挙げた 例と同様に、Python インタプリタはアプリケーションと直接 やりとりはしません (が、次の節でやりとりするよう変更します)。

Python スクリプト内で定義されている関数を実行するための コードは以下のようになります:

#include <Python.h>

int
main(int argc, char *argv[])
{
    PyObject *pName, *pModule, *pDict, *pFunc;
    PyObject *pArgs, *pValue;
    int i;

    if (argc < 3) {
        fprintf(stderr,"Usage: call pythonfile funcname [args]\n");
        return 1;
    }

    Py_Initialize();
    pName = PyString_FromString(argv[1]);
    /* Error checking of pName left out */

    pModule = PyImport_Import(pName);
    Py_DECREF(pName);

    if (pModule != NULL) {
        pDict = PyModule_GetDict(pModule);
        /* pDict is a borrowed reference */

        pFunc = PyDict_GetItemString(pDict, argv[2]);
        /* pFun: Borrowed reference */

        if (pFunc && PyCallable_Check(pFunc)) {
            pArgs = PyTuple_New(argc - 3);
            for (i = 0; i < argc - 3; ++i) {
                pValue = PyInt_FromLong(atoi(argv[i + 3]));
                if (!pValue) {
                    Py_DECREF(pArgs);
                    Py_DECREF(pModule);
                    fprintf(stderr, "Cannot convert argument\n");
                    return 1;
                }
                /* pValue reference stolen here: */
                PyTuple_SetItem(pArgs, i, pValue);
            }
            pValue = PyObject_CallObject(pFunc, pArgs);
            Py_DECREF(pArgs);
            if (pValue != NULL) {
                printf("Result of call: %ld\n", PyInt_AsLong(pValue));
                Py_DECREF(pValue);
            }
            else {
                Py_DECREF(pModule);
                PyErr_Print();
                fprintf(stderr,"Call failed\n");
                return 1;
            }
            /* pDict and pFunc are borrowed and must not be Py_DECREF-ed */
        }
        else {
            if (PyErr_Occurred())
                PyErr_Print();
            fprintf(stderr, "Cannot find function \"%s\"\n", argv[2]);
        }
        Py_DECREF(pModule);
    }
    else {
        PyErr_Print();
        fprintf(stderr, "Failed to load \"%s\"\n", argv[1]);
        return 1;
    }
    Py_Finalize();
    return 0;
}
Download as text (original file name: run-func.c).

このコードはargv[1] を使って Python スクリプトをロードし、 argv[2] 内に指定された名前の関数を呼び出します。 関数の整数引数は argv 配列中の他の値になります。 このプログラムをコンパイルしてリンクし (できた実行可能形式を call と呼びましょう)、以下のような Python スクリプトを実行することにします:

def multiply(a,b):
    print "Will compute", a, "times", b
    c = 0
    for i in range(0, a):
        c = c + b
    return c

実行結果は以下のようになるはずです:

$ call multiply multiply 3 2
Will compute 3 times 2
Result of call: 6

この程度の機能を実現するにはプログラムがいささか大きすぎますが、 ほとんどは Python から C へのデータ変換やエラー報告のための コードです。Python の埋め込みという観点から最も興味深い部分は 以下のコード、

    Py_Initialize();
    pName = PyString_FromString(argv[1]);
    /* pName のエラーチェックは省略している */
    pModule = PyImport_Import(pName);

から始まる部分です。

インタプリタの初期化後、スクリプトは PyImport_Import() を使って読み込まれます。 このルーチンは Python 文字列を引数に取る必要があり、 データ変換ルーチンPyString_FromString() で 構築します。

    pFunc = PyObject_GetAttrString(pModule, argv[2]);
    /* pFunc は新たな参照 */

    if (pFunc && PyCallable_Check(pFunc)) {
        ...
    }
    Py_XDECREF(pFunc);

ひとたびスクリプトが読み込まれると、 PyObject_GetAttrString() を使って必要な名前を取得 できます。名前がスクリプト中に存在し、取得したオブジェクトが 呼び出し可能オブジェクトであれば、このオブジェクトが関数であると 考えて差し支えないでしょう。そこでプログラムは定石どおりに引数の タプル構築に進みます。その後、Python 関数を以下のコードで 呼び出します:

    pValue = PyObject_CallObject(pFunc, pArgs);

関数が処理を戻す際、pValue は NULL になるか、 関数の戻り値への参照が入っています。 値を調べた後には忘れずに参照を解放してください。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 5.2 超高水準の埋め込みから踏み出す: 概要 Up: 5. 他のアプリケーションへの Python の埋め込み Next: 5.4 埋め込まれた Python の拡張


5.4 埋め込まれた Python の拡張

ここまでは、埋め込み Python インタプリタはアプリケーション本体の 機能にアクセスする手段がありませんでした。 Python API を使うと、埋め込みインタプリタを拡張することで アプリケーション本体へのアクセスを可能にします。 つまり、アプリケーションで提供されているルーチンを使って、 埋め込みインタプリタを拡張するのです。 複雑なことのように思えますが、それほどひどいわけではありません。 さしあたって、アプリケーションが Python インタプリタを起動したと いうことをちょっと忘れてみてください。その代わり、アプリケーションが サブルーチンの集まりで、あたかも普通の Python 拡張モジュールを 書くかのように、Python から各ルーチンにアクセスできるようにする グルー(glue, 糊) コードを書くと考えてください。例えば以下のようにです:

static int numargs=0;

/* アプリケーションのコマンドライン引数の個数を返す */
static PyObject*
emb_numargs(PyObject *self, PyObject *args)
{
    if(!PyArg_ParseTuple(args, ":numargs"))
        return NULL;
    return Py_BuildValue("i", numargs);
}

static PyMethodDef EmbMethods[] = {
    {"numargs", emb_numargs, METH_VARARGS,
     "Return the number of arguments received by the process."},
    {NULL, NULL, 0, NULL}
};

上のコードを main() 関数のすぐ上に挿入します。 また、以下の二つの文をPy_Initialize() の直後 に挿入します:

    numargs = argc;
    Py_InitModule("emb", EmbMethods);

これら二つの行はnumargs 変数を初期化し、 埋め込み Python インタプリタからemb.numargs() 関数に アクセスできるようにします。これらの拡張モジュール関数を使うと、 Python スクリプトは

import emb
print "Number of arguments", emb.numargs()

のようなことができます。

実際のアプリケーションでは、こうしたメソッドでアプリケーション内の API を Python に公開することになります。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 5.3 純粋な埋め込み Up: 5. 他のアプリケーションへの Python の埋め込み Next: 5.5 C++による Python の埋め込み


5.5 C++による Python の埋め込み

C++ プログラム中にも Python を埋め込めます; 厳密に言うと、 どうやって埋め込むかは使っているC++ 処理系の詳細に依存します; 一般的には、メインプログラムをC++で書き、C++ コンパイラ を使ってプログラムをコンパイル・リンクする必要があるでしょう。 Python 自体を C++でコンパイルしなおす必要はありません。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 5.4 埋め込まれた Python の拡張 Up: 5. 他のアプリケーションへの Python の埋め込み Next: 5.6 リンクに関する要件


5.6 リンクに関する要件

Python ソースと一緒についてくるconfigure スクリプトは 動的にリンクされる拡張モジュールが必要とするシンボルを公開するよう ただしく Python をビルドしますが、この機能は Python ライブラリを静的に埋め込むようなアプリケーションには 継承されません。少なくとも Unixではそうです。 これは、アプリケーションが静的な実行時ライブラリ (libpython.a) にリンクされていて、かつ (.so ファイルとして実装されている) 動的ロードされるような拡張モジュールをロードする必要がある場合に 起きる問題です。

問題になるのは、拡張モジュールが使うあるエントリポイントが Python ランタイムだけで定義されているという状況です。 埋め込みを行うアプリケーション側がこうしたエントリポイントを 全く使わない場合、リンカによってはエントリポイントを最終的に 生成される実行可能形式のシンボルテーブル内に含めません。 こうした場合、リンカに追加のオプションを与えて、これらのシンボルを 除去しないよう教える必要があります。

プラットフォームごとに正しいオプションを決めるのはかなり困難です、 とはいえ、幸運なことに、オプションは Python のビルド設定内にすでに あります。インストール済みの Python インタプリタからオプションを 取り出すには、対話インタプリタを起動して、以下のような短い セッションを実行します:

>>> import distutils.sysconfig
>>> distutils.sysconfig.get_config_var('LINKFORSHARED')
'-Xlinker -export-dynamic'

表示された文字列の内容が、ビルド時に使うべきオプションです。 文字列が空であれば、特に追加すべきオプションはありません。 LINKFORSHARED の定義内容は、 Python のトップレベル Makefile 内の同名の変数に対応しています。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 5.5 C++による Python の埋め込み Up: 5. 他のアプリケーションへの Python の埋め込み Next: A. バグ報告


A. バグ報告

Python is a mature programming language which has established a reputation for stability. In order to maintain this reputation, the developers would like to know of any deficiencies you find in Python or its documentation.

Before submitting a report, you will be required to log into SourceForge; this will make it possible for the developers to contact you for additional information if needed. It is not possible to submit a bug report anonymously.

All bug reports should be submitted via the Python Bug Tracker on SourceForge (http://sourceforge.net/bugs/?group_id=5470). The bug tracker offers a Web form which allows pertinent information to be entered and submitted to the developers.

The first step in filing a report is to determine whether the problem has already been reported. The advantage in doing so, aside from saving the developers time, is that you learn what has been done to fix it; it may be that the problem has already been fixed for the next release, or additional information is needed (in which case you are welcome to provide it if you can!). To do this, search the bug database using the search box near the bottom of the page.

If the problem you're reporting is not already in the bug tracker, go back to the Python Bug Tracker (http://sourceforge.net/bugs/?group_id=5470). Select the ``Submit a Bug'' link at the top of the page to open the bug reporting form.

The submission form has a number of fields. The only fields that are required are the ``Summary'' and ``Details'' fields. For the summary, enter a very short description of the problem; less than ten words is good. In the Details field, describe the problem in detail, including what you expected to happen and what did happen. Be sure to include the version of Python you used, whether any extension modules were involved, and what hardware and software platform you were using (including version information as appropriate).

The only other field that you may want to set is the ``Category'' field, which allows you to place the bug report into a broad category (such as ``Documentation'' or ``Library'').

Each bug report will be assigned to a developer who will determine what needs to be done to correct the problem. You will receive an update each time action is taken on the bug.

参考資料:

How to Report Bugs Effectively
Article which goes into some detail about how to create a useful bug report. This describes what kind of information is useful and why it is useful.

Bug Writing Guidelines
Information about writing a good bug report. Some of this is specific to the Mozilla project, but describes general good practices.

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 5.6 リンクに関する要件 Up: Python インタプリタの拡張と埋め込み Next: B. 歴史とライセンス


B. 歴史とライセンス

  • B.1 History of the software
  • B.2 Terms and conditions for accessing or otherwise using Python
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: A. バグ報告 Up: Python インタプリタの拡張と埋め込み Next: B.1 History of the


B.1 History of the software

Python was created in the early 1990s by Guido van Rossum at Stichting Mathematisch Centrum (CWI, see http://www.cwi.nl/) in the Netherlands as a successor of a language called ABC. Guido remains Python's principal author, although it includes many contributions from others.

In 1995, Guido continued his work on Python at the Corporation for National Research Initiatives (CNRI, see http://www.cnri.reston.va.us/) in Reston, Virginia where he released several versions of the software.

In May 2000, Guido and the Python core development team moved to BeOpen.com to form the BeOpen PythonLabs team. In October of the same year, the PythonLabs team moved to Digital Creations (now Zope Corporation; see http://www.zope.com/). In 2001, the Python Software Foundation (PSF, see http://www.python.org/psf/) was formed, a non-profit organization created specifically to own Python-related Intellectual Property. Zope Corporation is a sponsoring member of the PSF.

All Python releases are Open Source (see http://www.opensource.org/ for the Open Source Definition). Historically, most, but not all, Python releases have also been GPL-compatible; the table below summarizes the various releases.

Release | Derived from | Year | Owner | GPL compatible?
0.9.0 thru 1.2 | n/a | 1991-1995 | CWI | yes
1.3 thru 1.5.2 | 1.2 | 1995-1999 | CNRI | yes
1.6 | 1.5.2 | 2000 | CNRI | no
2.0 | 1.6 | 2000 | BeOpen.com | no
1.6.1 | 1.6 | 2001 | CNRI | no
2.1 | 2.0+1.6.1 | 2001 | PSF | no
2.0.1 | 2.0+1.6.1 | 2001 | PSF | yes
2.1.1 | 2.1+2.0.1 | 2001 | PSF | yes
2.2 | 2.1.1 | 2001 | PSF | yes
2.1.2 | 2.1.1 | 2002 | PSF | yes
2.1.3 | 2.1.2 | 2002 | PSF | yes
2.2.1 | 2.2 | 2002 | PSF | yes
2.2.2 | 2.2.1 | 2002 | PSF | yes
2.2.3 | 2.2.2 | 2002-2003 | PSF | yes
2.3 | 2.2.2 | 2002-2003 | PSF | yes
2.3.1 | 2.3 | 2002-2003 | PSF | yes
2.3.2 | 2.3.1 | 2003 | PSF | yes

注意: GPL-compatible doesn't mean that we're distributing Python under the GPL. All Python licenses, unlike the GPL, let you distribute a modified version without making your changes open source. The GPL-compatible licenses make it possible to combine Python with other software that is released under the GPL; the others don't.

Thanks to the many outside volunteers who have worked under Guido's direction to make these releases possible.

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: B. 歴史とライセンス Up: B. 歴史とライセンス Next: B.2 Terms and conditions


B.2 Terms and conditions for accessing or otherwise using Python

PSF LICENSE AGREEMENT FOR PYTHON 2.3.3

  1. This LICENSE AGREEMENT is between the Python Software Foundation (``PSF''), and the Individual or Organization (``Licensee'') accessing and otherwise using Python 2.3.3 software in source or binary form and its associated documentation.

  2. Subject to the terms and conditions of this License Agreement, PSF hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python 2.3.3 alone or in any derivative version, provided, however, that PSF's License Agreement and PSF's notice of copyright, i.e., ``Copyright © 2001-2003 Python Software Foundation; All Rights Reserved'' are retained in Python 2.3.3 alone or in any derivative version prepared by Licensee.

  3. In the event Licensee prepares a derivative work that is based on or incorporates Python 2.3.3 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python 2.3.3.

  4. PSF is making Python 2.3.3 available to Licensee on an ``AS IS'' basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.3.3 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 2.3.3 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 2.3.3, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between PSF and Licensee. This License Agreement does not grant permission to use PSF trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party.

  8. By copying, installing or otherwise using Python 2.3.3, Licensee agrees to be bound by the terms and conditions of this License Agreement.

BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0

BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1

  1. This LICENSE AGREEMENT is between BeOpen.com (``BeOpen''), having an office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization (``Licensee'') accessing and otherwise using this software in source or binary form and its associated documentation (``the Software'').

  2. Subject to the terms and conditions of this BeOpen Python License Agreement, BeOpen hereby grants Licensee a non-exclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use the Software alone or in any derivative version, provided, however, that the BeOpen Python License is retained in the Software, alone or in any derivative version prepared by Licensee.

  3. BeOpen is making the Software available to Licensee on an ``AS IS'' basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  5. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  6. This License Agreement shall be governed by and interpreted in all respects by the law of the State of California, excluding conflict of law provisions. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between BeOpen and Licensee. This License Agreement does not grant permission to use BeOpen trademarks or trade names in a trademark sense to endorse or promote products or services of Licensee, or any third party. As an exception, the ``BeOpen Python'' logos available at http://www.pythonlabs.com/logos.html may be used according to the permissions granted on that web page.

  7. By copying, installing or otherwise using the software, Licensee agrees to be bound by the terms and conditions of this License Agreement.

CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1

  1. This LICENSE AGREEMENT is between the Corporation for National Research Initiatives, having an office at 1895 Preston White Drive, Reston, VA 20191 (``CNRI''), and the Individual or Organization (``Licensee'') accessing and otherwise using Python 1.6.1 software in source or binary form and its associated documentation.

  2. Subject to the terms and conditions of this License Agreement, CNRI hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python 1.6.1 alone or in any derivative version, provided, however, that CNRI's License Agreement and CNRI's notice of copyright, i.e., ``Copyright © 1995-2001 Corporation for National Research Initiatives; All Rights Reserved'' are retained in Python 1.6.1 alone or in any derivative version prepared by Licensee. Alternately, in lieu of CNRI's License Agreement, Licensee may substitute the following text (omitting the quotes): ``Python 1.6.1 is made available subject to the terms and conditions in CNRI's License Agreement. This Agreement together with Python 1.6.1 may be located on the Internet using the following unique, persistent identifier (known as a handle): 1895.22/1013. This Agreement may also be obtained from a proxy server on the Internet using the following URL: http://hdl.handle.net/1895.22/1013.''

  3. In the event Licensee prepares a derivative work that is based on or incorporates Python 1.6.1 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python 1.6.1.

  4. CNRI is making Python 1.6.1 available to Licensee on an ``AS IS'' basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  7. This License Agreement shall be governed by the federal intellectual property law of the United States, including without limitation the federal copyright law, and, to the extent such U.S. federal law does not apply, by the law of the Commonwealth of Virginia, excluding Virginia's conflict of law provisions. Notwithstanding the foregoing, with regard to derivative works based on Python 1.6.1 that incorporate non-separable material that was previously distributed under the GNU General Public License (GPL), the law of the Commonwealth of Virginia shall govern this License Agreement only as to issues arising under or with respect to Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between CNRI and Licensee. This License Agreement does not grant permission to use CNRI trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party.

  8. By clicking on the ``ACCEPT'' button where indicated, or by copying, installing or otherwise using Python 1.6.1, Licensee agrees to be bound by the terms and conditions of this License Agreement.

ACCEPT

CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2

Copyright © 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, The Netherlands. All rights reserved.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Stichting Mathematisch Centrum or CWI not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: B.1 History of the Up: B. 歴史とライセンス Next: C. 日本語訳について


C. 日本語訳について

  • C.1 このドキュメントについて
  • C.2 翻訳者一覧 (敬称略)
Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: B.2 Terms and conditions Up: Python インタプリタの拡張と埋め込み Next: C.1 このドキュメントについて


C.1 このドキュメントについて

この文書は、Pythonドキュメント翻訳プロジェクトによる Extending and Embedding the Python Interpreter 2.3の日本語訳版です。 日本語訳に対する質問や提案などが ありましたら、Pythonドキュメント翻訳プロジェクトのメーリングリスト

http://www.python.jp/mailman/listinfo/python-doc-jp

または、プロジェクトのバグ管理ページ

http://sourceforge.jp/tracker/?atid=116&group_id=11&func=browse

までご報告ください。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: C. 日本語訳について Up: C. 日本語訳について Next: C.2 翻訳者一覧 (敬称略)


C.2 翻訳者一覧 (敬称略)

Yasushi Masuda, Yusuke Shinyama

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: C.1 このドキュメントについて Up: C. 日本語訳について Next: この文書について...


Python/C API リファレンスマニュアル

Guido van Rossum

PythonLabs
Email: docs@python.org

Fred L. Drake, Jr., editor

リリース 2.3.3
December 19, 2003

  • 序
  • 目次
  • 1. はじめに
    • 1.1 インクルードファイル
    • 1.2 オブジェクト、型および参照カウント
      • 1.2.1 参照カウント
      • 1.2.2 型
    • 1.3 例外
    • 1.4 Python の埋め込み
  • 2. 超高レベルレイヤ
  • 3. 参照カウント
  • 4. 例外処理
    • 4.1 標準例外
    • 4.2 文字列例外の廃止
  • 5. ユーティリティ関数
    • 5.1 オペレーティングシステム関連のユーティリティ
    • 5.2 プロセス制御
    • 5.3 モジュールの import
    • 5.4 データ整列化 (data marshalling) のサポート
    • 5.5 引数の解釈と値の構築
  • 6. 抽象オブジェクトレイヤ (abstract objects layer)
    • 6.1 オブジェクトプロトコル (object protocol)
    • 6.2 数値型プロトコル (number protocol)
    • 6.3 配列プロトコル (sequence protocol)
    • 6.4 マップ型プロトコル (mapping protocol)
    • 6.5 イテレータプロトコル (iterator protocol)
    • 6.6 バッファプロトコル (buffer protocol)
  • 7. 具象オブジェクト (concrete object) レイヤ
    • 7.1 基本オブジェクト (fundamental object)
      • 7.1.1 型オブジェクト (type object)
      • 7.1.2 None オブジェクト
    • 7.2 数値型オブジェクト (numeric object)
      • 7.2.1 (通常)整数型オブジェクト (plain integer object)
      • 7.2.2 長整数型オブジェクト (long integer object)
      • 7.2.3 浮動小数点型オブジェクト (floating point object)
      • 7.2.4 浮動小数点オブジェクト (complex number object)
    • 7.3 配列オブジェクト (sequence object)
      • 7.3.1 文字列オブジェクト (string object)
      • 7.3.2 Unicode オブジェクト (Unicode object)
      • 7.3.3 Buffer Objects
      • 7.3.4 タプルオブジェクト (tuple object)
      • 7.3.5 List Objects
    • 7.4 マップ型オブジェクト (mapping object)
      • 7.4.1 辞書オブジェクト (dictionary object)
    • 7.5 その他のオブジェクト
      • 7.5.1 ファイルオブジェクト (file object)
      • 7.5.2 インスタンスオブジェクト (instance object)
      • 7.5.3 メソッドオブジェクト (method object)
      • 7.5.4 モジュールオブジェクト (module object)
      • 7.5.5 イテレータオブジェクト (iterator object)
      • 7.5.6 デスクリプタオブジェクト (descriptor object)
      • 7.5.7 スライスオブジェクト (slice object)
      • 7.5.8 弱参照オブジェクト (weak reference object)
      • 7.5.9 Cオブジェクト (CObject)
      • 7.5.10 セルオブジェクト (cell object)
  • 8. 初期化 (initialization)、終了処理 (finalization)、スレッド
    • 8.1 スレッド状態 (thread state) とグローバルインタプリタロック (global interpreter lock)
    • 8.2 プロファイルとトレース (profiling and tracing)
    • 8.3 高度なデバッガサポート (advanced debugger support)
  • 9. メモリ管理
    • 9.1 概要
    • 9.2 メモリインタフェース
    • 9.3 例
  • 10. オブジェクト実装サポート (object implementation support)
    • 10.1 オブジェクトをヒープ上にメモリ確保する
    • 10.2 共通のオブジェクト構造体 (common object structure)
    • 10.3 型オブジェクト
    • 10.4 マップ型オブジェクト構造体 (mapping object structure)
    • 10.5 数値オブジェクト構造体 (number object structure)
    • 10.6 配列オブジェクト構造体 (sequence object structure)
    • 10.7 バッファオブジェクト構造体 (buffer object structure)
    • 10.8 イテレータプロトコルをサポートする
    • 10.9 循環参照ガベージコレクションをサポートする
  • A. バグ報告
  • B. 歴史とライセンス
    • B.1 History of the software
    • B.2 Terms and conditions for accessing or otherwise using Python
  • C. 日本語訳について
    • C.1 このドキュメントについて
    • C.2 翻訳者一覧 (敬称略)
  • 索引
  • この文書について...
Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Up: Python ドキュメントインデクス Next: 序
Release 2.3.3, documentation updated on December 19, 2003.


1. はじめに

Python のアプリケーションプログラマ用インタフェース (Application Programmer's Interface, API) は、 Python インタプリタに対する様々なレベルでのアクセス手段を C や C++ のプログラマに提供しています。この API は通常 C++ からも全く同じように利用できるのですが、簡潔な呼び名に するために Python/C API と名づけられています。 根本的に異なる二つの目的から、 Python/C API が用いられます。 第一は、特定用途の 拡張モジュール (extention module)、 すなわち Python インタプリタを拡張する C で書かれたモジュール を記述する、という目的です。第二は、より大規模なアプリケーション 内で Python を構成要素 (component) として利用するという目的です; このテクニックは、一般的にはアプリケーションへの Python の 埋め込み (embedding) と呼びます。 拡張モジュールの作成は比較的わかりやすいプロセスで、 ``手引書 (cookbook)'' 的なアプローチでうまく実現できます。 作業をある程度まで自動化してくれるツールもいくつかあります。 一方、他のアプリケーションへの Python の埋め込みは、Python ができてから早い 時期から行われてきましたが、拡張モジュールの作成に比べるとやや難解です。

多くの API 関数は、Python の埋め込みであるか拡張であるかに関わらず 役立ちます; とはいえ、 Python を埋め込んでいるほとんどのアプリケーション は、同時に自作の拡張モジュールも提供する必要が生じることになる でしょうから、Python を実際にアプリケーションに埋め込んでみる前に 拡張モジュールの書き方に詳しくなっておくのはよい考えだと思います。

  • 1.1 インクルードファイル
  • 1.2 オブジェクト、型および参照カウント
    • 1.2.1 参照カウント
      • 1.2.1.1 参照カウントの詳細
    • 1.2.2 型
  • 1.3 例外
  • 1.4 Python の埋め込み
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 目次 Up: Python/C API リファレンスマニュアル Next: 1.1 インクルードファイル
Release 2.3.3, documentation updated on December 19, 2003.


1.1 インクルードファイル

Python/C API を使うために必要な、関数、型およびマクロの全ての定義 をインクルードするには、以下の行:

#include "Python.h"

をソースコードに記述します。 この行を記述すると、標準ヘッダ: <stdio.h>, <string.h>, <errno.h>, <limits.h>, and <stdlib.h> を (あれば) インクルードします。 システムによっては、Python の定義しているプリプロセッサ定義が 標準ヘッダに影響をおよぼす可能性があるので、Python.h は他の標準ヘッダファイルよりも前にインクルードしてください。

Python.h で定義されている、ユーザから見える名前全て (Python.h がインクルードしている標準ヘッダの名前は除きます) には、接頭文字列 "Py" または "_Py" が付きます。 "_Py" で始まる名前は Python 実装で内部使用するための名前で、拡張モジュールの作者は 使ってはなりません。構造体のメンバには予約済みの接頭文字列はありません。

重要: API のユーザは、"Py" や "_Py" で始まる名前を 定義するようなコードを絶対に書いてはなりません。 後からコードを読む人を混乱させたり、将来の Python のバージョンで同じ 名前が定義されて、ユーザの書いたコードの可搬性を危うくする可能性が あります。

ヘッダファイル群は通常 Python と共にインストールされます。 Unixでは prefix/include/pythonversion/ および exec_prefix/include/pythonversion/ に 置かれます。prefix と exec_prefix は Python を ビルドする際の configure スクリプトに与えたパラメタに 対応し、version は sys.version[:3] に対応します。 Windows では、ヘッダは prefix/include に置かれます。 prefix はインストーラに指定したインストールディレクトリです。

ヘッダをインクルードするには、 各ヘッダの入ったディレクトリ (別々の ディレクトリの場合は両方) を、コンパイラがインクルードファイルを 検索するためのパスに入れます。 親ディレクトリをサーチパスに入れて、 "#include <python2.3/Python.h>" のようにしては なりません; prefix 内のプラットフォームに依存しない ヘッダは、exec_prefix からプラットフォーム依存のヘッダを インクルードしているので、このような操作を行うと複数のプラットフォーム でのビルドができなくなります。

API はすべて C 言語を使って定義していますが、ヘッダファイルは エントリポイントを extern "C" で適切に宣言しているので、 C++ ユーザは、なんの問題もなく C++から API を利用できる ことに気づくはずです。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 1. はじめに Up: 1. はじめに Next: 1.2 オブジェクト、型および参照カウント
Release 2.3.3, documentation updated on December 19, 2003.


1.2 オブジェクト、型および参照カウント

Python/C API 関数は、 PyObject* 型の一つ以上の引数と 戻り値を持ちます。この型は、任意の Python オブジェクトを表現する 不透明 (opaque) なデータ型へのポインタです。 Python 言語は、全ての Python オブジェクト型をほとんどの状況 (例えば代入、スコープ規則 (scope rule)、引数渡し) で同様に 扱います。ほとんど全ての Python オブジェクトはヒープ (heap) 上に 置かれます: このため、PyObject 型のオブジェクトは、 自動記憶 (automatic) としても静的記憶 (static) としても 宣言できません。PyObject* 型のポインタ変数のみ 宣言できます。唯一の例外は、型オブジェクト です; 型オブジェクトはメモリ解放 (deallocate) してはならないので、 通常は静的記憶の PyTypeObject オブジェクトにします。

全ての Python オブジェクトには (Python 整数型ですら) 型 (type) と参照カウント (reference count) があります。 あるオブジェクトの型は、そのオブジェクトがどの種類のオブジェクト か (例えば整数、リスト、ユーザ定義関数、など; その他多数については、 Python リファレンスマニュアル で説明して います) を決定します。よく知られている型については、各々マクロが 存在して、あるオブジェクトがその型かどうか調べられます; 例えば、 "PyList_Check(a)" は、a で示されたオブジェクトが Python リスト型のとき (かつそのときに限り) 真値を返します。

  • 1.2.1 参照カウント
    • 1.2.1.1 参照カウントの詳細
  • 1.2.2 型
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 1.1 インクルードファイル Up: 1. はじめに Next: 1.2.1 参照カウント
Release 2.3.3, documentation updated on December 19, 2003.


1.2.1 参照カウント

今日の計算機は有限の (しばしば非常に限られた) メモリサイズしか 持たないので、参照カウントは重要な概念です; 参照カウントは、 あるオブジェクトに対して参照を行っている場所が何箇所あるか を数える値です。参照を行っている場所とは、別のオブジェクトで あったり、グローバルな (あるいは静的な) C 変数であったり、 何らかの C 関数内にあるローカルな変数だったりします。 あるオブジェクトの参照カウントがゼロになると、そのオブジェクトは 解放されます。そのオブジェクトに他のオブジェクトへの 参照が入っていれば、他のオブジェクトの参照カウントはデクリメント されます。デクリメントの結果、他のオブジェクトの参照カウント がゼロになると、今度はそのオブジェクトが解放される、といった具合に 以後続きます。(言うまでもなく、互いを参照しあうオブジェクトに ついて問題があります; 現状では、解決策は ``何もしない'' です。)

参照カウントは、常に明示的なやり方で操作されます。 通常の方法では、Py_INCREF() でオブジェクトの参照を 1 インクリメントし、 Py_DECREF()で 1 デクリメント します。Py_DECREF() マクロは、incref よりもかなり 複雑です。というのは、Py_DECREF() マクロは参照カウント がゼロになったかどうかを調べて、なった場合にはオブジェクトの デアロケータ (deallocator) を呼び出さなければならないからです。 デアロケータとは、オブジェクトの型を定義している構造体内にある 関数へのポインタです。 型固有のデアロケータは、その型が複合オブジェクト (compound object) 型である場合には、オブジェクト内の他のオブジェクトに対する参照 カウントをデクリメントするよう気を配るとともに、その他の必要な ファイナライズ (finalize) 処理を実行します。 参照カウントがオーバフローすることはありません; というのも、 仮想メモリ空間には、(sizeof(long) >= sizeof(char*) と 仮定した場合) 少なくとも参照カウントの記憶に使われるビット数と 同じだけのメモリ上の位置があるからです。従って、参照カウントの インクリメントは単純な操作になります。

オブジェクトへのポインタが入っているローカルな変数全てについて、 オブジェクトの参照カウントを必ずインクリメントしなければならない わけではありません。理論上は、オブジェクトの参照カウントは、 オブジェクトを指し示す変数が生成されたときに 1 増やされ、 その変数がスコープから出て行った際に 1 減らされます。しかしこの 場合、二つの操作は互いに相殺するので、結果的に参照カウントは 変化しません。参照カウントを使う真の意義とは、手持ちの何らかの 変数がオブジェクトを指している間はオブジェクトがデアロケート されないようにすることにあります。オブジェクトに対して、 一つでも別の参照が行われていて、その参照が手持ちの変数 と同じ間維持されるのなら、参照カウントを一時的に増やす必要は ありません。参照カウント操作の必要性が浮き彫りになる重要な局面 とは、Python から呼び出された拡張モジュール内の C 関数に オブジェクトを引数として渡すときです; 呼び出しメカニズムは、 呼び出しの間全ての引数に対する参照を保証します。

しかしながら、よく陥る過ちとして、あるオブジェクトをリストから 得たときに、参照カウントをインクリメントせずにしばらく放っておく というのがあります。他の操作がオブジェクトをリストから除去してしまい、 参照カウントがデクリメントされてデアロケートされてしまうことが 考えられます。 本当に危険なのは、まったく無害そうにみえる操作が、上記の動作を 引き起こす何らかの Python コードを呼び出しかねないということです; Py_DECREF() からユーザへ制御を戻せるような コードパスが存在するため、ほとんど全ての操作が潜在的に危険を はらむことになります。

安全に参照カウントを操作するアプローチは、汎用の操作 (関数名が "PyObject_", "PyNumber_", "PySequence_", および "PyMapping_" で始まる関数) の利用です。これらの操作は 常に戻り値となるオブジェクトの参照カウントをインクリメントします。 ユーザには戻り値が不要になったら Py_DECREF() を呼ぶ 責任が残されています; とはいえ、すぐにその習慣は身に付くでしょう。

  • 1.2.1.1 参照カウントの詳細
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 1.2 オブジェクト、型および参照カウント Up: 1.2 オブジェクト、型および参照カウント Next: 1.2.1.1 参照カウントの詳細
Release 2.3.3, documentation updated on December 19, 2003.


1.2.2 型

Python/C API において重要な役割を持つデータ型は、PyObject 型の他にもいくつかあります; ほとんどは int, long, double, および char* といった、単なる C のデータ型です。 また、モジュールで公開している関数を列挙する際に用いられる静的な テーブルや、新しいオブジェクト型におけるデータ属性を記述したり、 複素数の値を記述したりするために構造体をいくつか使っています。 これらの型については、その型を使う関数とともに説明してゆきます。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 1.2.1.1 参照カウントの詳細 Up: 1.2 オブジェクト、型および参照カウント Next: 1.3 例外
Release 2.3.3, documentation updated on December 19, 2003.


1.3 例外

Python プログラマは、特定のエラー処理が必要なときだけしか例外を扱う 必要はありません; 処理しなかった例外は、処理の呼び出し側、そのまた 呼び出し側、といった具合に、トップレベルのインタプリタ層まで自動的に 伝播します。インタプリタ層は、スタックトレースバックと合わせて 例外をユーザに報告します。

ところが、 C プログラマの場合、エラーチェックは常に明示的に行わねば なりません。Python/C API の全ての関数は、関数のドキュメントで明確に 説明がない限り例外を発行する可能性があります。 一般的な話として、ある関数が何らかのエラーに遭遇すると、関数は 例外を送出して、関数内における参照の所有権を全て放棄し、 エラー指標 (error indicator) -- 通常は NULL または -1 を返します。いくつかの関数ではブール型で真/偽を返し、偽はエラーを 示します。きわめて少数の関数では明確なエラー指標を返さなかったり、 あいまいな戻り値を返したりするので、 PyErr_Occurred()で 明示的にエラーテストを行う必要があります。

例外時の状態情報 (exception state)は、スレッド単位に用意された 記憶領域 (per-thread storage) 内で管理されます (この記憶領域は、 スレッドを使わないアプリケーションではグローバルな記憶領域と 同じです)。 一つのスレッドは二つの状態のどちらか: 例外が発生したか、まだ発生 していないか、をとります。 関数 PyErr_Occurred() を使うと、この状態を調べられます: この関数は例外が発生した際にはその例外型オブジェクトに対する 借用参照 (borrowed reference) を返し、そうでないときには NULL を返します。例外状態を設定する関数は数多くあります: PyErr_SetString()はもっとも よく知られている (が、もっとも汎用性のない) 例外を設定するための 関数で、PyErr_Clear()は 例外状態情報を消し去る関数です。

完全な例外状態情報は、3 つのオブジェクト: 例外の型、例外の値、 そしてトレースバック、からなります (どのオブジェクトも NULLを取り得ます)。これらの情報は、 Python オブジェクトの sys.exc_type, sys.exc_value, および sys.exc_traceback と同じ意味を持ちます; とはいえ、 C と Python の例外状態情報は全く同じではありません: Python における 例外オブジェクトは、Python の try ... except 文で最近処理したオブジェクトを表す一方、 C レベルの例外状態情報が存続するのは、 渡された例外情報を sys.exc_typeその他に転送するよう取り計らう Python のバイトコードインタプリタのメインループに到達するまで、 例外が関数の間で受け渡しされている間だけです。

Python 1.5 からは、Python で書かれたコードから例外状態情報にアクセス する方法として、推奨されていてスレッドセーフな方法は sys.exc_info() になっているので注意してください。 この関数は Python コードの実行されているスレッドにおける 例外状態情報を返します。 また、これらの例外状態情報に対するアクセス手段は、両方とも 意味づけ (semantics) が変更され、ある関数が例外を捕捉すると、 その関数を実行しているスレッドの例外状態情報を保存して、呼び出し側の 呼び出し側の例外状態情報を維持するようになりました。 この変更によって、無害そうに見える関数が現在扱っている例外を上書き することで引き起こされる、例外処理コードでよくおきていたバグを 抑止しています; また、トレースバック内のスタックフレームで 参照されているオブジェクトがしばしば不必要に寿命を永らえて いたのをなくしています。

一般的な原理として、ある関数が別の関数を呼び出して何らかの作業を させるとき、呼び出し先の関数が例外を送出していないか調べなくては ならず、もし送出していれば、その例外状態情報は呼び出し側に 渡されなければなりません。 呼び出し元の関数はオブジェクト参照の所有権をすべて放棄し、 エラー指標を返さなくてはなりませんが、余計に例外を設定 する必要は ありません -- そんなことをすれば、たった今 送出されたばかりの例外を上書きしてしまい、エラーの原因そのもの に関する重要な情報を失うことになります。

例外を検出して渡す例は、上の sum_sequence()で示しています。 偶然にも、この例ではエラーを検出した際に何ら参照を放棄する必要が ありません。以下の関数の例では、エラーに対する後始末について示して います。まず、どうして Python で書くのが好きか思い出してもらうために、 等価な Python コードを示します:

def incr_item(dict, key):
    try:
        item = dict[key]
    except KeyError:
        item = 0
    dict[key] = item + 1

以下は対応するコードを C で完璧に書いたものです:

int
incr_item(PyObject *dict, PyObject *key)
{
    /* Py_XDECREF 用に全てのオブジェクトを NULL で初期化 */
    PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
    int rv = -1; /* 戻り値の初期値を -1 (失敗) に設定しておく */

    item = PyObject_GetItem(dict, key);
    if (item == NULL) {
        /* KeyError だけを処理: */
        if (!PyErr_ExceptionMatches(PyExc_KeyError))
            goto error;

        /* エラーを無かったことに (clear) してゼロを使う: */
        PyErr_Clear();
        item = PyInt_FromLong(0L);
        if (item == NULL)
            goto error;
    }
    const_one = PyInt_FromLong(1L);
    if (const_one == NULL)
        goto error;

    incremented_item = PyNumber_Add(item, const_one);
    if (incremented_item == NULL)
        goto error;

    if (PyObject_SetItem(dict, key, incremented_item) < 0)
        goto error;
    rv = 0; /* うまくいった場合 */
    /* 後始末コードに続く */

 error:
    /* 成功しても失敗しても使われる後始末コード */

    /* NULL を参照している場合は無視するために Py_XDECREF() を使う */
    Py_XDECREF(item);
    Py_XDECREF(const_one);
    Py_XDECREF(incremented_item);

    return rv; /* エラーなら -1 、 成功なら 0 */
}

なんとこの例は C で goto 文を使うお勧めの方法まで示して いますね! この例では、特定の例外を処理するために PyErr_ExceptionMatches() および PyErr_Clear()をどう使うかを 示しています。また、所有権を持っている参照で、値が NULL に なるかもしれないものを捨てるために Py_XDECREF() をどう使うかも示しています (関数名に "X" が付いていることに 注意してください; Py_DECREF() は NULL 参照に出くわすと クラッシュします)。正しく動作させるためには、所有権を持つ参照を 保持するための変数を NULL で初期化することが重要です; 同様に、 あらかじめ戻り値を定義する際には値を -1 (失敗) で初期化して おいて、最後の関数呼び出しまでうまくいった場合にのみ 0 (成功) に設定します。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 1.2.2 型 Up: 1. はじめに Next: 1.4 Python の埋め込み
Release 2.3.3, documentation updated on December 19, 2003.


1.4 Python の埋め込み

Python インタプリタの埋め込みを行う人 (いわば拡張モジュールの 書き手の対極) が気にかけなければならない重要なタスクは、 Python インタプリタの初期化処理 (initialization)、そしておそらくは 終了処理 (finalization) です。インタプリタのほとんどの機能は、 インタプリタの起動後しか使えません。

基本的な初期化処理を行う関数は Py_Initialize()です。 この関数はロード済みのモジュールからなるテーブルを作成し、 土台となるモジュール __builtin__ __main__ sys および exceptionsを作成します。 また、モジュール検索パス (sys.path) の初期化も行います。

Py_Initialize() の中では、 ``スクリプトへの引数リスト'' (script argument list, sys.argv のこと) を設定しません。 この変数が後に実行される Python コード中で必要なら、 Py_Initialize() に続いて PySys_SetArgv(argc, argv)を呼び出して明示的に設定しなければなりません。

ほとんどのシステムでは (特に Unix と Windows は、詳細がわずかに 異なりはしますが)、 Py_Initialize() は 標準の Python インタプリタ実行形式の場所に対する推定結果に基づいて、 Python のライブラリが Python インタプリタ実行形式からの相対パスで 見つかるという仮定の下にモジュール検索パスを計算します。 とりわけこの検索では、シェルコマンド検索パス (環境変数 PATH) 上に見つかった python という名前の実行ファイルの置かれている ディレクトリの親ディレクトリからの相対で、 lib/python2.3 という名前のディレクトリを探します。

例えば、 Python 実行形式が /usr/local/bin/python で見つかった とすると、Py_Initialize() はライブラリが /usr/local/lib/python2.3 にあるものと仮定します。 (実際には、このパスは ``フォールバック (fallback)'' のライブラリ 位置でもあり、python が PATH 上にない場合に使われます。) ユーザは PYTHONHOME を設定することでこの動作をオーバライド したり、PYTHONPATH を設定して追加のディレクトリを 標準モジュール検索パスの前に挿入したりできます。

埋め込みを行うアプリケーションでは、 Py_Initialize() を呼び出す 前に Py_SetProgramName(file) を呼び出すことで、上記の検索を操作できます。 この埋め込みアプリケーションでの設定は依然として PYTHONHOME でオーバライドでき、標準のモジュール検索パスの前には以前として PYTHONPATH が挿入されるので注意してください。 アプリケーションでモジュール検索パスを完全に制御したいのなら、 独自に Py_GetPath() Py_GetPrefix() Py_GetExecPrefix() および Py_GetProgramFullPath() の実装を提供しなければなりません (これらは全て Modules/getpath.c で定義されています)。

たまに、 Python を ``初期化しない'' ようにしたいことがあります。 例えば、あるアプリケーションでは実行を最初からやりなおし (start over) させる (Py_Initialize() をもう一度呼び出させる) ように したいかもしれません。あるいは、アプリケーションが Python を一旦 使い終えて、Python が確保した全てのメモリを解放できるようにしたいかも しれません。Py_Finalize() を使うと、こうした処理を 実現できます。また、関数 Py_IsInitialized() は、Python が現在初期化済みの状態にある場合に真を返します。 これらの関数についてのさらなる情報は、後の章で説明します。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 1.3 例外 Up: 1. はじめに Next: 2. 超高レベルレイヤ
Release 2.3.3, documentation updated on December 19, 2003.


2. 超高レベルレイヤ

この章の関数を使うとファイルまたはバッファにあるPythonソースコードを 実行できますが、より詳細なやり取りをインタプリタとすることはできないでしょう。

これらの関数のいくつかは引数として文法の開始記号を受け取ります。 使用できる開始記号はPy_eval_inputとPy_file_input、 Py_single_inputです。開始期号の説明はこれらを引数として取る 関数の後にあります。

これらの関数のいくつかがFILE*引数をとることにも注意してください。 注意深く扱う必要がある特別な問題には、異なるCライブラリのFILE構造体は 異なっていて互換性がない可能性があるということが関係しています。 実際に(少なくとも)Windowsでは、動的リンクされる拡張が異なるライブラリを 使うことが可能であり、したがって、FILE*引数がPythonランタイムが 使っているライブラリと同じライブラリによって作成されたことが確かならば、 単にこれらの関数へ渡すだけということに注意すべきです。

int Py_Main( int argc, char **argv)
標準インタプリタのためのメインプログラム。Pythonを組み込む プログラムのためにこれを利用できるようにしています。 argcとargv引数をCプログラムのmain()関数へ 渡されるものとまったく同じに作成すべきです。 引数リストが変更される可能性があるという点に注意することは重要です。 (しかし、引数リストが指している文字列の内容は変更されません)。 戻り値はsys.exit()関数へ渡される整数でしょう。 例外が原因でインタプリタが終了した場合は1、あるいは、 引数リストが有効なPythonコマンドラインになっていない場合は2です。

int PyRun_AnyFile( FILE *fp, char *filename)
fpが対話的デバイス(コンソールや端末入力あるいはUnix仮想端末)と 関連づけられたファイルを参照しているならば、 PyRun_InteractiveLoop()の値を返します。それ以外の場合は、 PyRun_SimpleFile()の結果を返します。filenameが NULLならば、この関数はファイル名として"???"を使います。

int PyRun_SimpleString( char *command)
__main__モジュールの中でcommandに含まれるPythonソースコードを 実行します。__main__がまだ存在しない場合は作成されます。 正常終了の場合は0を返し、また例外が発生した場合は-1を 返します。エラーがあっても、例外情報を得る方法はありません。

int PyRun_SimpleFile( FILE *fp, char *filename)
PyRun_SimpleString()と似ていますが、Pythonソースコードを メモリ内の文字列ではなくfpから読み込みます。 filenameはそのファイルの名前でなければなりません。

int PyRun_InteractiveOne( FILE *fp, char *filename)
対話的デバイスに関連付けられたファイルから文を一つ読み込み実行します。 filenameがNULLならば、"???"が代わりに使われます。 sys.ps1とsys.ps2を使って、ユーザにプロンプトを提示します。 入力が正常に実行されたときは0を返します。例外が発生した場合は -1を返すか、もしくはパースエラーの場合はPythonの一部として配布されている errcode.hインクルードファイルにあるエラーコードを返します。 (Python.hはerrcode.hをインクルードしません。したがって、 必要ならば特別にインクルードしなければならないことに注意してください。)

int PyRun_InteractiveLoop( FILE *fp, char *filename)
対話的デバイスに関連付けられたファイルからEOF に達するまで複数の文を 読み込み実行します。filenameがNULLならば、"???"が代わりに 使われます。sys.ps1とsys.ps2を使って、ユーザにプロンプトを 提示します。EOFに達すると0を返します。

struct _node* PyParser_SimpleParseString( char *str, int start)
開始トークンstartを使ってstrに含まれるPythonソースコードをパースします。 効率的に評価可能なコードオブジェクトを作成するためにその結果を使うことができます。 コード断片を何度も評価しなければならない場合に役に立ちます。

struct _node* PyParser_SimpleParseFile( FILE *fp, char *filename, int start)
PyParser_SimpleParseString()に似ていますが、 Pythonソースコードをメモリ内の文字列ではなくfpから読み込みます。 filenameはそのファイルの名前でなけれななりません。

PyObject* PyRun_String( char *str, int start, PyObject *globals, PyObject *locals)
戻り値: 新たな参照.
辞書globalsとlocalsで指定されるコンテキストにおいて、 strに含まれるPythonソースコードを実行します。 パラメータstartはソースコードをパースするために使われるべき 開始トークンを指定します。

コードを実行した結果をPythonオブジェクトとして返します。または、 例外が発生したならばNULL を返します。

PyObject* PyRun_File( FILE *fp, char *filename, int start, PyObject *globals, PyObject *locals)
戻り値: 新たな参照.
PyRun_String()と似ていますが、Pythonソースコードを メモリ内の文字列ではなくfpから読み込みます。 filenameはそのファイルの名前でなければなりません。

PyObject* Py_CompileString( char *str, char *filename, int start)
戻り値: 新たな参照.
str内のPythonソースコードをパースしてコンパイルし、 作られたコードオブジェクトを返します。開始トークンは startによって与えられます。これはコンパイル可能なコードを 制限するために使うことができ、Py_eval_input、 Py_file_inputもしくはPy_single_inputであるべきです。 filenameで指定されるファイル名はコードオブジェクトを構築するために使われ、 トレースバックあるいはSyntaxError例外メッセージに出てくる可能性があります。 コードがパースできなかったりコンパイルできなかったりした場合に、 これはNULL を返します。

int Py_eval_input
単独の式に対するPython文法の開始記号で、 Py_CompileString()醗貊錣忙箸い泙后｣

int Py_file_input
ファイルあるいは他のソースから読み込まれた文の並びに対するPython文法の 開始記号で、Py_CompileString()ﾈ 一緒に使います。これは任意の長さのPythonソースコードをコンパイルするときに 使う記号です。

int Py_single_input
単一の文に対するPython文法の開始記号で、 Py_CompileString()醗貊錣忙箸い泙后｣ これは対話式のインタプリタループのための記号です。
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 1.4 Python の埋め込み Up: Python/C API リファレンスマニュアル Next: 3. 参照カウント
Release 2.3.3, documentation updated on December 19, 2003.


3. 参照カウント

この節のマクロはPythonオブジェクトの参照カウントを管理するために使われます。

void Py_INCREF( PyObject *o)
オブジェクトoに対する参照カウントを一つ増やします。オブジェクトが NULLであってはいけません。それがNULLではないと確信が持てないならば、 Py_XINCREF()を使ってください。

void Py_XINCREF( PyObject *o)
オブジェクトoに対する参照カウントを一つ増やします。オブジェクトが NULLであってもよく、その場合マクロは何の影響も与えません。

void Py_DECREF( PyObject *o)
オブジェクトoに対する参照カウントを一つ減らします。オブジェクトが NULLであってはいけません。それがNULLではないと確信が持てないならば、 Py_XDECREF()を使ってください。参照カウントがゼロになったら、 オブジェクトの型のメモリ解放関数(NULLであってはならない)が呼ばれます。

警告: (例えば__del__()メソッドをもつクラスインスタンスが メモリ解放されたときに)メモリ解放関数は任意のPythonコードを呼び出すことが できます。このようなコードでは例外は伝播しませんが、実行されたコードは すべてのPythonグローバル変数に自由にアクセスできます。 これが意味するのは、Py_DECREF()が呼び出されるより前では、 グローバル変数から到達可能などんなオブジェクトも一貫した状態に あるべきであるということです。 例えば、リストからオブジェクトを削除するコードは削除するオブジェクト への参照を一時変数にコピーし、リストデータ構造を更新し、それから 一時変数に対してPy_DECREF()を呼び出すべきです。

void Py_XDECREF( PyObject *o)
オブジェクトoへの参照カウントを一つ減らします。オブジェクトは NULLであってもよいが、その場合マクロは何の影響も与えません。それ以外の 場合、結果はPy_DECREF()と同じです。また、注意すべきことも 同じです。

以下の関数やマクロはインタプリタのコアの内部においてのみ使用するための ものです: _Py_Dealloc(), _Py_ForgetReference(), _Py_NewReference()。また、グローバル変数_Py_RefTotal も同様です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 2. 超高レベルレイヤ Up: Python/C API リファレンスマニュアル Next: 4. 例外処理
Release 2.3.3, documentation updated on December 19, 2003.


4. 例外処理

この章で説明する関数を使うと、Pythonの例外の処理や送出ができるように なります。Pythonの例外処理の基本をいくらか理解することが大切です。 例外はUnix errno変数にやや似た機能を果たします: 発生した 中で最も新しいエラーの(スレッド毎の)グローバルなインジケータがあります。 実行に成功した場合にはほとんどの関数がこれをクリアしませんが、失敗したときには エラーの原因を示すために設定します。ほとんどの関数はエラーインジケータも 返し、通常は関数がポインタを返すことになっている場合はNULLであり、 関数が整数を返す場合は-1です。(例外: PyArg_*()関数は 実行に成功したときに1を返し、失敗したときに0を返します).

ある関数が呼び出した関数がいくつか失敗したために、その関数が失敗しなければ ならないとき、一般的にエラーインジケータを設定しません。呼び出した関数が すでに設定しています。エラーを処理して例外をクリアするか、あるいは (オブジェクト参照またはメモリ割り当てのような)それが持つどんなリソースも 取り除いた後に戻るかのどちらか一方を行う責任があります。エラーを処理する 準備をしていなければ、普通に続けるべきではありません。エラーのために 戻る場合は、エラーが設定されていると呼び出し元に知らせることが大切です。 エラーが処理されていない場合または丁寧に伝えられている場合には、 Python/C APIのさらなる呼び出しは意図した通りには動かない可能性があり、 不可解な形で失敗するかもしれません。

エラーインジケータはPython変数sys.exc_type, sys.exc_value および sys.exc_tracebackに対応する三つのPythonオブジェクトからからなります。 いろいろな方法でエラーインジケータとやりとりするためにAPI関数が存在します。 各スレッドに別々のエラーインジケータがあります。

void PyErr_Print( )
sys.stderrへ標準トレースバックをプリントし、エラーインジケータを クリアします。エラーインジケータが設定されているときにだけ、この関数を 呼び出してください。(それ以外の場合、致命的なエラーを引き起こすでしょう!)

PyObject* PyErr_Occurred( )
戻り値: 借りた参照.
エラーインジケータが設定されているかテストします。設定されている場合は、 例外の型(PyErr_Set*()関数の一つあるいは PyErr_Restore()への最も新しい呼び出しに対する第一引数)を返します。 設定されていない場合はNULLを返します。あなたは戻り値への参照を持っていませんので、 それにPy_DECREF()する必要はありません。注意: 戻り値を特定の例外と 比較しないでください。その代わり、下に示すPyErr_ExceptionMatches()を 使ってください。(比較は簡単に失敗するでしょう。なぜなら、例外はクラスではなく インスタンスかもしれないし、あるいは、クラス例外の場合は期待される例外の サブクラスかもしれないからです。)

int PyErr_ExceptionMatches( PyObject *exc)
"PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)"と同じ。 例外が実際に設定されたときにだけ、これを呼び出だすべきです。例外が発生 していないならば、メモリアクセス違反が起きるでしょう。

int PyErr_GivenExceptionMatches( PyObject *given, PyObject *exc)
given例外がexcの例外と一致するなら真を返します。これはexcが クラスオブジェクトである場合も真を返します。これはgivenがサブクラスの インスタンスであるときも真を返します。excがタプルならば、タプル内 (と再帰的にサブタプル内)のすべての例外が一致するか調べられます。 givenがNULLならば、メモリアクセス違反が起きるでしょう。

void PyErr_NormalizeException( PyObject**exc, PyObject**val, PyObject**tb)
ある状況では、以下のPyErr_Fetch()が返す値は ``正規化されていない''可能性があります。つまり、*excは クラスオブジェクトだが*valは同じクラスのインスタンスでは ないという意味です。この関数はそのような場合にそのクラスをインスタンス化 するために使われます。その値がすでに正規化されている場合は何も起きません。 遅延正規化はパフォーマンスを改善するために実装されています。

void PyErr_Clear( )
エラーインジケータをクリアします。エラーインジケータが設定されていないならば、 効果はありません。

void PyErr_Fetch( PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
エラーインジケータをアドレスを渡す三つの変数の中へ取り出します。 エラーインジケータが設定されていない場合は、三つすべての変数をNULLに 設定します。エラーインジケータが設定されている場合はクリアされ、 あなたは取り出されたそれぞれのオブジェクトへの参照を持つことになります。 型オブジェクトがNULLでないときでさえ、その値とトレースバックオブジェクトは NULLかもしれません。注意: 通常、この関数は例外を扱う必要のあるコード あるいはエラーインジケータを一時的に保存して元に戻す必要のあるコードに よってのみ使用されます。

void PyErr_Restore( PyObject *type, PyObject *value, PyObject *traceback)
三つのオブジェクトからエラーインジケータを設定します。エラーインジケータが すでに設定されている場合は、最初にクリアされます。オブジェクトがNULLならば、 エラーインジケータがクリアされます。NULLのtypeと非NULLのvalueあるいは tracebackを渡してはいけません。例外の型(type)はクラスであるべきです。 無効な例外の型(type)あるいは値(value)を渡してはいけません。 (これらの規則を破ると後で気付きにくい問題の原因となるでしょう。) この呼び出しはそれぞれのオブジェクトへの参照を取り除きます: あなたは 呼び出しの前にそれぞれのオブジェクトへの参照を持たなければならないのであり、 また呼び出しの後にはもはやこれらの参照を持っていません。 (これを理解していない場合は、この関数を使ってはいけません。注意しておきます。) 注意: 通常この関数はエラーインジケータを一時的に保存し元に戻す必要のある コードによってのみに使われます。現在の例外状態を保存するためには PyErr_Fetch()を使ってください。

void PyErr_SetString( PyObject *type, char *message)
これはエラーインジケータを設定するための最も一般的な方法です。第一引数は 例外の型を指定します。通常は標準例外の一つ、例えばPyExc_RuntimeErrorです。 その参照カウントを増加させる必要はありません。第二引数はエラーメッセージで、 文字列オブジェクトへ変換されます。

void PyErr_SetObject( PyObject *type, PyObject *value)
この関数はPyErr_SetString()に似ていますが、 例外の``値(value)''として任意のPythonオブジェクトを指定することができます。

PyObject* PyErr_Format( PyObject *exception, const char *format, ...)
戻り値: 常に NULL.
この関数はエラーインジケータを設定しNULLを返します。 exceptionはPython例外(インスタンスではなくクラス)であるべきです。 formatは文字列であるべきであり、printf()に似た 書式化コードを含んでいます。書式化コードの前の幅.精度(width.precision)は 解析されますが、幅の部分は無視されます。

文字 | 意味
c | 文字、int引数として
d | 10進数、int引数として
x | 16進数、int引数として
s | 文字列、char *引数として
p | 16進法のポインタ、void *引数として

認識できない書式化文字があると書式化文字列の残りすべてがそのまま 結果の文字列へコピーされ、余分の引数はどれも捨てられます。

void PyErr_SetNone( PyObject *type)
これは"PyErr_SetObject(type, Py_None)"を省略したものです。

int PyErr_BadArgument( )
これは"PyErr_SetString(PyExc_TypeError, message)"を省略したもので、 ここでmessageは組み込み操作が不正な引数で呼び出されたということを表しています。 主に内部で使用するためのものです。

PyObject* PyErr_NoMemory( )
戻り値: 常に NULL.
これは"PyErr_SetNone(PyExc_MemoryError)"を省略したもので、 NULLを返します。したがって、メモリ不足になったとき、 オブジェクト割り当て関数は"return PyErr_NoMemory();"と 書くことができます。

PyObject* PyErr_SetFromErrno( PyObject *type)
戻り値: 常に NULL.
Cライブラリ関数がエラーを返してC変数errnoを設定したときに、 これは例外を発生させるために便利な関数です。第一要素が 整数errno値で、第二要素が (strerror()�C蘰世蕕譴�)対応する エラーメッセージであるタプルオブジェクトを構成します。それから、 "PyErr_SetObject(type, object)"を呼び出します。 Unixでは、errno値がEINTRであるとき、すなわち 割り込まれたシステムコールを表しているとき、これは PyErr_CheckSignals()を呼び出し、それがエラーインジケータを 設定した場合は設定されたままにしておきます。関数は常にNULLを返します。 したがって、システムコールがエラーを返したとき、システムコールの ラッパー関数は"return PyErr_SetFromErrno(type);"と 書くことができます。

PyObject* PyErr_SetFromErrnoWithFilename( PyObject *type, char *filename)
戻り値: 常に NULL.
PyErr_SetFromErrno()に似ていて、filenameがNULLでない場合に、 それがtypeのコンストラクタに第三引数として渡されるというふるまいが追加 されています。IOErrorとOSErrorのような例外の場合では、 これが例外インスタンスのfilename属性を定義するために使われます。

PyObject* PyErr_SetFromWindowsErr( int ierr)
戻り値: 常に NULL.
これはWindowsErrorを発生させるために便利な関数です。 0のierrとともに呼び出された場合、GetLastError()が 返すエラーコードが代りに使われます。ierrあるいは GetLastError()によって与えられるエラーコードのWindows用の説明を 取り出すために、Win32関数FormatMessage()を呼び出します。それから、 第一要素がierr値で第二要素が(FormatMessage()から得られる) 対応するエラーメッセージであるタプルオブジェクトを構成します。そして、 "PyErr_SetObject(PyExc_WindowsError, object)"を呼び出します。 この関数は常にNULLを返します。 利用可能範囲: Windows。

PyObject* PyErr_SetExcFromWindowsErr( PyObject *type, int ierr)
PyErr_SetFromWindowsErr()に似ていて、送出する例外の型を 指定する引数が追加されています。 利用可能範囲: Windows。 バージョン2.3 以降で新規追加された 仕様です。

PyObject* PyErr_SetFromWindowsErrWithFilename( int ierr, char *filename)
戻り値: 常に NULL.
PyErr_SetFromWindowsErr()に似ていて、filenameがNULLでない場合には WindowsErrorのコンストラクタへ第三引数として渡されるという振る舞いが 追加されています。 利用可能範囲: Windows。

PyObject* PyErr_SetExcFromWindowsErrWithFilename( PyObject *type, int ierr, char *filename)
PyErr_SetFromWindowsErrWithFilename()に似ていて、 発生させる例外の型を指定する引数が追加されています。 利用可能範囲: Windows。 バージョン2.3 以降で新規追加された 仕様です。

void PyErr_BadInternalCall( )
"PyErr_SetString(PyExc_TypeError, message)"を省略したものです。 ここでmessageは内部操作(例えば、Python/C API関数)が不正な引数と ともに呼び出されたということを示しています。主に内部で使用するためのもの です。

int PyErr_Warn( PyObject *category, char *message)
警告メッセージを出します。category引数は警告カテゴリ(以下を参照) かまたはNULLで、message引数はメッセージ文字列です。

この関数は通常警告メッセージをsys.stderrへプリントします。 けれども、ユーザが警告をエラーへ変更するように指定することも可能です。 そのような場合には、これは例外を発生させます。警告機構がもつ問題のために その関数が例外を発生させるということも可能です。(実装ではその厄介な仕事を 行うためにwarningsモジュールをインポートします)。 例外が発生させられなければ、戻り値は0です。あるいは、例外が発生させ られると-1です。(警告メッセージが実際にプリントされるかどうかを決定 することはできず、また何がその例外の原因なのかを決定することもできない。 これは意図的なものです。)例外が発生した場合、呼び出し元は通常の例外処理を 行います(例えば、Py_DECREF()は参照を持っており、エラー値を 返します)。

警告カテゴリはWarningのサブクラスでなければならない。 デフォルト警告カテゴリはRuntimeWarningです。 標準Python警告カテゴリは"PyExc_"にPython例外名が続く名前の グローバル変数を用いて変更できます。これらは型PyObject*を 持ち、すべてクラスオブジェクトです。それらの名前は PyExc_Warning, PyExc_UserWarning, PyExc_DeprecationWarning, PyExc_SyntaxWarning, PyExc_RuntimeWarningおよびPyExc_FutureWarningです。 PyExc_WarningはPyExc_Exceptionのサブクラスです。 その他の警告カテゴリはPyExc_Warningのサブクラスです。

警告をコントロールするための情報については、warningsモジュールの ドキュメンテーションとコマンドライン・ドキュメンテーションの -Wオプションを参照してください。 警告コントロールのためのC APIはありません。

int PyErr_WarnExplicit( PyObject *category, char *message, char *filename, int lineno, char *module, PyObject *registry)
すべての警告の属性を明示的に制御した警告メッセージを出します。 これはPython関数warnings.warn_explicit()の直接的なラッパで、 さらに情報を得るにはそちらを参照してください。そこに説明されているデフォルトの 効果を得るために、moduleとregistry引数はNULLに設定することができます。

int PyErr_CheckSignals( )
この関数はPythonのシグナル処理とやりとりすることができます。 シグナルがそのプロセスへ送られたかどうかチェックし、そうならば対応する シグナルハンドラを呼び出します。 signal皀献紂璽襪�｣汽檗璽箸気譴討い訃豺腓蓮｢ これはPythonで書かれたシグナルハンドラを呼び出せます。すべての場合で、 SIGINT離妊侫�D襯箸慮擎未ﾏ KeyboardInterrupt例外を発生させることです。例外が発生した場合、 エラーインジケータが設定され、関数は1を返します。 そうでなければ、関数は0を返します。エラーインジケータが以前に 設定されている場合は、それがクリアされるかどうかわからない。

void PyErr_SetInterrupt( )
この関数は廃止されています。SIGINT轡哀淵襪ｬ 到達した影響をシミュレートします -- 次に PyErr_CheckSignals()が呼ばれるとき、 KeyboardInterruptは送出されるでしょう。インタプリタロックを 保持することなく呼び出すことができます。

PyObject* PyErr_NewException( char *name, PyObject *base, PyObject *dict)
戻り値: 新たな参照.
このユーティリティ関数は新しい例外オブジェクトを作成して返します。 name引数は新しい例外の名前、module.class形式の C文字列でなければならない。 baseとdict引数は通常NULLです。これはすべての例外のためのルート、 組み込み名Exception(CではPyExc_Exceptionとしてアクセス可能) から導出されたクラスオブジェクトを作成します。 新しいクラスの__module__属性はname引数の前半部分(最後のドットまで)に 設定され、クラス名は後半部分(最後のドットの後)に設定されます。 base引数は代わりのベースクラスを指定するために使えます。 dict引数はクラス変数とメソッドの辞書を指定するために使えます。

void PyErr_WriteUnraisable( PyObject *obj)
例外が設定されているがインタプリタが実際に例外を発生させることができないときに、 このユーティリティ関数は警告メッセージをsys.stderrへプリントします。 例えば、例外が__del__()メソッドで発生したときに使われます。

発生させられない例外が生じたコンテキストを特定するための一つの引数objとともに 関数が呼び出されます。objのreprが警告メッセージにプリントされるでしょう。

  • 4.1 標準例外
  • 4.2 文字列例外の廃止
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 3. 参照カウント Up: Python/C API リファレンスマニュアル Next: 4.1 標準例外
Release 2.3.3, documentation updated on December 19, 2003.


4.1 標準例外

"PyExc_"の後ろにPythonの例外名が続く名前をもつグローバル変数として、 すべての標準Python例外が利用可能です。これらは型PyObject*を 持ち、すべてクラスオブジェクトです。完璧を期するために、すべての変数を 以下に列挙します:

C名 | Python名 | 注記
PyExc_Exception | Exception | (1)
PyExc_StandardError | StandardError | (1)
PyExc_ArithmeticError | ArithmeticError | (1)
PyExc_LookupError | LookupError | (1)
PyExc_AssertionError | AssertionError |
PyExc_AttributeError | AttributeError |
PyExc_EOFError | EOFError |
PyExc_EnvironmentError | EnvironmentError | (1)
PyExc_FloatingPointError | FloatingPointError |
PyExc_IOError | IOError |
PyExc_ImportError | ImportError |
PyExc_IndexError | IndexError |
PyExc_KeyError | KeyError |
PyExc_KeyboardInterrupt | KeyboardInterrupt |
PyExc_MemoryError | MemoryError |
PyExc_NameError | NameError |
PyExc_NotImplementedError | NotImplementedError |
PyExc_OSError | OSError |
PyExc_OverflowError | OverflowError |
PyExc_ReferenceError | ReferenceError | (2)
PyExc_RuntimeError | RuntimeError |
PyExc_SyntaxError | SyntaxError |
PyExc_SystemError | SystemError |
PyExc_SystemExit | SystemExit |
PyExc_TypeError | TypeError |
PyExc_ValueError | ValueError |
PyExc_WindowsError | WindowsError | (3)
PyExc_ZeroDivisionError | ZeroDivisionError |

注記:

(1)
これは別の標準例外のためのベースクラスです。

(2)
これはweakref.ReferenceErrorと同じです。

(3)
Windowsでのみ定義されています。 プリプロセッサマクロMS_WINDOWSが定義されているかテストすることで、 これを使うコードを保護してください。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 4. 例外処理 Up: 4. 例外処理 Next: 4.2 文字列例外の廃止
Release 2.3.3, documentation updated on December 19, 2003.


4.2 文字列例外の廃止

Pythonへ組み込まれるすべての例外あるいは標準ライブラリに提供されている例外は、 Exceptionから導出されています。

インタプリタで既存のコードが変更なしで動作するように、文字列例外は今でも サポートされています。しかし、これも将来のリリースで変更されるでしょう。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 4.1 標準例外 Up: 4. 例外処理 Next: 5. ユーティリティ関数
Release 2.3.3, documentation updated on December 19, 2003.


5. ユーティリティ関数

この章の関数は、 C で書かれたコードをプラットフォーム間で可搬性の あるものにする上で役立つものから、C から Python モジュールを使う もの、そして関数の引数を解釈したり、 C の値から Python の値を 構築するものまで、様々なユーティリティ的タスクを行います。

  • 5.1 オペレーティングシステム関連のユーティリティ
  • 5.2 プロセス制御
  • 5.3 モジュールの import
  • 5.4 データ整列化 (data marshalling) のサポート
  • 5.5 引数の解釈と値の構築
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 4.2 文字列例外の廃止 Up: Python/C API リファレンスマニュアル Next: 5.1 オペレーティングシステム関連のユーティリティ
Release 2.3.3, documentation updated on December 19, 2003.


5.1 オペレーティングシステム関連のユーティリティ

int Py_FdIsInteractive( FILE *fp, char *filename)
filename という名前の標準 I/O ファイル fp が対話的 (interactive) であると考えられる場合に真 (非ゼロ) を返します。 これは"isatty(fileno(fp))" が真になるファイルの場合です。 グローバルなフラグ Py_InteractiveFlag が真の場合には、 filename ポインタが NULL か、名前が '<stdin>' または '???' のいずれかに等しい場合にも真を返します。

long PyOS_GetLastModificationTime( char *filename)
ファイル filename の最終更新時刻を返します。 結果は標準 C ライブラリ関数 time() が返すタイムスタンプと 同じ様式で符号化されています。

void PyOS_AfterFork( )
プロセスが fork した後の内部状態を更新するための関数です; fork 後 Python インタプリタを使い続ける場合、新たなプロセス内で この関数を呼び出さねばなりません。新たなプロセスに新たな実行 可能物をロードする場合、この関数を呼び出す必要はありません。

int PyOS_CheckStack( )
インタプリタがスタック空間を使い尽くしたときに真を返します。 このチェック関数には信頼性がありますが、USE_STACKCHECK が定義されている場合 (現状では Microsoft Visual C++ コンパイラ でビルドした Windows 版と Macintosh 版) にしか利用できません . USE_CHECKSTACK は自動的に定義されます; 自前のコードで この定義を変更してはなりません。

PyOS_sighandler_t PyOS_getsig( int i)
シグナル i に対する現在のシグナルハンドラを返します。 この関数は sigaction() または signal() のいずれかに対する薄いラッパです。 sigaction() や signal() を直接呼び出しては なりません! PyOS_sighandler_t は void (*)(int) の typedef による別名です。

PyOS_sighandler_t PyOS_setsig( int i, PyOS_sighandler_t h)
シグナル i に対する現在のシグナルハンドラを h に設定 します; 以前のシグナルハンドラを返します。 この関数は sigaction() または signal() のいずれかに対する薄いラッパです。 sigaction() や signal() を直接呼び出しては なりません! PyOS_sighandler_t は void (*)(int) の typedef による別名です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 5. ユーティリティ関数 Up: 5. ユーティリティ関数 Next: 5.2 プロセス制御
Release 2.3.3, documentation updated on December 19, 2003.


5.2 プロセス制御

void Py_FatalError( const char *message)
致命的エラーメッセージ (fatal error message) を出力してプロセスを 強制終了 (kill) します。後始末処理は行われません。この関数は、Python インタプリタを使い続けるのが危険であるような状況が検出されたとき; 例えば、オブジェクト管理が崩壊していると思われるときにのみ、呼び出され るようにしなければなりません。Unixでは、標準 C ライブラリ関数 abort()を呼び出して core を生成しようと試みます。

void Py_Exit( int status)
現在のプロセスを終了 (exit) します。この関数は Py_Finalize()を呼び出し、 次いで標準 C ライブラリ関数 exit(status)を呼び出します。

int Py_AtExit( void (*func) ())
Py_Finalize()から呼び出される 後始末処理を行う関数 (cleanup function) を登録します。 後始末関数は引数無しで呼び出され、値を返しません。 最大で 32 の後始末処理関数を登録できます。 登録に成功すると、Py_AtExit() は 0 を返します; 失敗すると -1 を返します。最後に登録した後始末処理関数から 先に呼び出されます。各関数は高々一度しか呼び出されません。 Python の内部的な終了処理は後始末処理関数より以前に完了している ので、func からはいかなる Python API も呼び出してはなりません。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 5.1 オペレーティングシステム関連のユーティリティ Up: 5. ユーティリティ関数 Next: 5.3 モジュールの import
Release 2.3.3, documentation updated on December 19, 2003.


5.3 モジュールの import

PyObject* PyImport_ImportModule( char *name)
戻り値: 新たな参照.
この関数は下で述べる PyImport_ImportModuleEx() を単純化したインタフェースで、 globals および locals 引数を NULLのままにしたものです。 name 引数にドットが含まれる場合 (あるパッケージの サブモジュールを指定している場合)、fromlist 引数が リスト ['*'] に追加され、戻り値がモジュールを含む トップレベルパッケージではなく名前つきモジュール (named module) に なるようにします。 (残念ながらこのやり方には、name が実際にはサブモジュールでなく サブパッケージを指定している場合、パッケージの __all__ 変数に指定されている サブモジュールがロードされてしまうという副作用があります。) import されたモジュールへの新たな参照を返します。失敗した 場合には例外をセットし、NULL を返します (その場合でも、 モジュールは生成されている場合があります -- sys.modules を使って調べてください)。

PyObject* PyImport_ImportModuleEx( char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
戻り値: 新たな参照.
モジュールを import します。モジュールの import については 組み込みの Python 関数__import__()を読むとよく分かります。というのも、標準の __import__() はこの関数を直接呼び出しているからです。

戻り値は import されたモジュールかトップレベルパッケージへの新たな参照 になります。失敗した場合には例外をセットし、NULL を返します (その場合でも、モジュールは生成されている場合があります) __import__() と同じく、パッケージに対してサブモジュール を要求した場合の戻り値は通常、空でない fromlist を指定しない 限りトップレベルパッケージになります。

PyObject* PyImport_Import( PyObject *name)
戻り値: 新たな参照.
現在の ``import フック関数'' を呼び出すための高水準のインタフェース です。この関数は現在のグローバル変数辞書内の __builtins__ から __import__() 関数を呼び出します。 すなわち、現在の環境にインストールされている import フック、 例えば rexecや ihooksを使って import を行います。

PyObject* PyImport_ReloadModule( PyObject *m)
戻り値: 新たな参照.
モジュールを再ロード (reload) します。モジュールの再ロードについては 組み込みの Python 関数reload()を読むとよく分かります。というのも、標準の reload はこの関数を直接呼び出しているからです。 戻り値は再ロードしたモジュールかトップレベルパッケージへの新たな参照 になります。失敗した場合には例外をセットし、NULL を返します (その場合でも、モジュールは生成されている場合があります)

PyObject* PyImport_AddModule( char *name)
戻り値: 借りた参照.
モジュール名に対応するモジュールオブジェクトを返します。 name 引数は package.module の形式でもかまいません。 まずモジュール辞書に該当するモジュールがあるかどうか調べ、 なければ新たなモジュールを生成してモジュール辞書に挿入します。 失敗した場合には例外をセットして NULL を返します。 注意: この関数はモジュールの import やロードを行いません; モジュールがまだロードされていなければ、空のモジュール オブジェクトを得ることになります。 PyImport_ImportModule() やその別形式を使って モジュールを import してください。ドット名表記で 指定したname が存在しない場合、パッケージ構造は 作成されません。

PyObject* PyImport_ExecCodeModule( char *name, PyObject *co)
戻り値: 新たな参照.
モジュール名 (package.module 形式でもかまいません) および Python のバイトコードファイルや組み込み関数 compile() で得られたコードオブジェクトを元にモジュールを ロードします。 モジュールオブジェクトへの新たな参照を返します。失敗した 場合には例外をセットし、NULL を返します (その場合でも、 モジュールは生成されている場合があります)。 この関数は、すでに import されているモジュールの場合には再ロードを 行います。name がpackage.module 形式のドット名表記で あった場合、まだ作成されていないパッケージ構造はその作成されない ままになります。

long PyImport_GetMagicNumber( )
Python バイトコードファイル (いわゆる .pyc および .pyo ファイル) のマジックナンバを返します。マジックナンバは バイトコードファイルの先頭 4 バイトにリトルエンディアン整列で 配置されています。

PyObject* PyImport_GetModuleDict( )
戻り値: 借りた参照.
モジュール管理のための辞書 (いわゆる sys.modules )を返します。 この辞書はインタプリタごとに一つだけある変数なので注意してください。

void _PyImport_Init( )
import 機構を初期化します。 内部使用だけのための関数です。

void PyImport_Cleanup( )
モジュールテーブルを空にします。 内部使用だけのための関数です。

void _PyImport_Fini( )
import 機構を終了処理します。 内部使用だけのための関数です。

PyObject* _PyImport_FindExtension( char *, char *)
戻り値: 借りた参照.
内部使用だけのための関数です。

PyObject* _PyImport_FixupExtension( char *, char *)
内部使用だけのための関数です。

int PyImport_ImportFrozenModule( char *name)
name という名前のフリーズ (freeze) されたモジュールをロード します。成功すると 1 を、モジュールが見つからなかった場合には 0 を、初期化が失敗した場合には例外をセットして-1 を 返します。ロードに成功したモジュールにアクセスするには PyImport_ImportModule() を使ってください。 (Note この関数名はいささか誤称めいています -- この関数は すでに import 済みのモジュールをリロードしてしまいます。)

struct _frozen
freezeユーティリティが生成するような フリーズ化モジュールデスクリプタの構造体型定義です。 (Python ソース配布物の Tools/freeze/ を参照してください) この構造体の定義は Include/import.h にあり、以下のように なっています:

struct _frozen {
    char *name;
    unsigned char *code;
    int size;
};

struct _frozen* PyImport_FrozenModules
このポインタは struct _frozen のレコードからなり、 終端の要素のメンバが NULL かゼロになっているような配列 を指すよう初期化されます。フリーズされたモジュールを import する とき、このテーブルを検索します。サードパーティ製のコードから このポインタに仕掛けを講じて、動的に生成されたフリーズ化モジュールの 集合を提供するようにできます。

int PyImport_AppendInittab( char *name, void (*initfunc)(void))
既存の組み込みモジュールテーブルに単一のモジュールを追加します。 この関数は利便性を目的とした PyImport_ExtendInittab() のラッパ関数で、テーブルが拡張できないときには -1 を返します。 新たなモジュールは name で import でき、最初に import を 試みた際に呼び出される関数として initfunc を使います。 Py_Initialize() よりも前に呼び出さねばなりません。

struct _inittab
組み込みモジュールリスト内の一つのエントリを記述している構造体です。 リスト内の各構造体には、インタプリタ内に組み込まれているモジュールの 名前と初期化関数が指定されています。 Python を埋め込むようなプログラムは、この構造体の配列と PyImport_ExtendInittab() を組み合わせて、追加の 組み込みモジュールを提供できます。構造体はInclude/import.h で以下のように定義されています:

struct _inittab {
    char *name;
    void (*initfunc)(void);
};

int PyImport_ExtendInittab( struct _inittab *newtab)
組み込みモジュールのテーブルに一群のモジュールを追加します。 配列 newtab は name フィールドが NULL になっている センチネル (sentinel) エントリで終端されていなければなりません; センチネル値を与えられなかった場合にはメモリ違反になるかもしれません。 成功すると 0 を、内部テーブルを拡張するのに十分なメモリを 確保できなかった場合には -1 を返します。操作が失敗した場合、 モジュールは一切内部テーブルに追加されません。 Py_Initialize() よりも前に呼び出さねばなりません。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 5.2 プロセス制御 Up: 5. ユーティリティ関数 Next: 5.4 データ整列化 (data marshalling)
Release 2.3.3, documentation updated on December 19, 2003.


5.4 データ整列化 (data marshalling) のサポート

以下のルーチン群は、marshal モジュールと同じ形式を使った 整列化オブジェクトを C コードから使えるようにします。 整列化形式でデータを書き出す関数に加えて、データを読み戻す関数 もあります。整列化されたデータを記録するファイルはバイナリモードで 開かれていなければなりません。

数値は最小桁が先にくるように記録されます。

void PyMarshal_WriteLongToFile( long value, FILE *file)
long 型の整数値 value を file へ整列化します。 この関数は value の下桁 32 ビットを書き込むだけです; ネイティブの long 型サイズには関知しません。

void PyMarshal_WriteObjectToFile( PyObject *value, FILE *file)
Python オブジェクトvalue を file へ整列化します。

PyObject* PyMarshal_WriteObjectToString( PyObject *value)
戻り値: 新たな参照.
value の整列化表現が入った文字列オブジェクトを返します。

以下の関数を使うと、整列化された値を読み戻せます。

long PyMarshal_ReadLongFromFile( FILE *file)
読み出し用に開かれた FILE* 内のデータストリームから、 C の long 型データを読み出して返します。 この関数は、ネイティブの long のサイズに関係なく、 32 ビットの値だけを読み出せます。

int PyMarshal_ReadShortFromFile( FILE *file)
読み出し用に開かれた FILE* 内のデータストリームから、 C の short 型データを読み出して返します。 この関数は、ネイティブの short のサイズに関係なく、 16 ビットの値だけを読み出せます。

PyObject* PyMarshal_ReadObjectFromFile( FILE *file)
戻り値: 新たな参照.
読み出し用に開かれた FILE* 内のデータストリームから、 Python オブジェクトを読み出して返します。 エラーが生じた場合、適切な例外 (EOFError または TypeError) を送出して NULLを返します。

PyObject* PyMarshal_ReadLastObjectFromFile( FILE *file)
戻り値: 新たな参照.
読み出し用に開かれた FILE* 内のデータストリームから、 Python オブジェクトを読み出して返します。 PyMarshal_ReadObjectFromFile() と違い、この関数は ファイル中に後続のオブジェクトが存在しないと仮定し、ファイルから メモリ上にファイルデータを一気にメモリにロードして、逆整列化機構が ファイルから一バイトづつ読み出す代わりにメモリ上のデータを操作 できるようにします。対象のファイルから他に何も読み出さないと 分かっている場合にのみ、この関数を使ってください。 エラーが生じた場合、適切な例外 (EOFError または TypeError) を送出して NULLを返します。

PyObject* PyMarshal_ReadObjectFromString( char *string, int len)
戻り値: 新たな参照.
string が指しているlen バイトの文字列バッファに納められた データストリームから Python オブジェクトを読み出して返します。 エラーが生じた場合、適切な例外 (EOFError または TypeError) を送出して NULLを返します。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 5.3 モジュールの import Up: 5. ユーティリティ関数 Next: 5.5 引数の解釈と値の構築
Release 2.3.3, documentation updated on December 19, 2003.


5.5 引数の解釈と値の構築

これらの関数は独自の拡張モジュール用の関数やメソッドを作成する際に 便利です。詳しい情報や用例は Python インタプリタの拡張と埋め込み に あります。

最初に説明する 3 つの関数、 PyArg_ParseTuple()、 PyArg_ParseTupleAndKeywords()、および PyArg_Parse() はいずれも 書式化文字列 (format string) を使います。 書式化文字列は、関数が受け取るはずの引数に関する情報を伝えるのに 用いられます。いずれの関数における書式化文字列も、同じ書式を 使っています。

書式化文字列は、ゼロ個またはそれ以上の ``書式化単位 (format unit)'' から成り立ちます。一つの書式化単位は一つの Python オブジェクトを 表します; 通常は単一の文字か、書式化単位からなる文字列を括弧で 囲ったものになります。例外として、括弧で囲われていない 書式化単位文字列が単一のアドレス引数に対応する場合がいくつかあります。 以下の説明では、引用符のついた形式は書式化単位です; (丸)括弧で囲った部分は書式化単位に対応する Python のオブジェクト型 です; [角] 括弧は値をアドレス渡しする際に使う C の変数型です。

"s" (文字列型または Unicode オブジェクト型) [char *]
Python の文字列または Unicode オブジェクトを、キャラクタ文字列を 指す C のポインタに変換します。 変換先の文字列自体の記憶領域を提供する必要はありません; キャラクタ型ポインタ変数のアドレスを渡すと、すでに存在している 文字列へのポインタをその変数に記録します。C 文字列は NUL で 終端されています。Python の文字列型は、NUL バイトが途中に埋め込まれて いてはなりません; もし埋め込まれていればTypeError 例外を 送出します。Unicode オブジェクトはデフォルトエンコーディングを使って C 文字列に変換されます。変換に失敗すると UnicodeError を 送出します。

"s#" (文字列型、Unicode オブジェクト型または任意の読み出しバッファ互換型) [char *, int]
これは "s" の変化形で、値を二つの変数に記録します。一つ目の変数は キャラクタ文字列へのポインタで、二つ目はその長さです。 この書式化単位の場合には、Python 文字列に null バイトが埋め込まれて いてもかまいません。 Unicode オブジェクトの場合、デフォルト エンコーディングでの変換が可能ならば、変換したオブジェクトから文字列 へのポインタを返します。その他の読み出しバッファ互換オブジェクトは 生の内部データ表現への参照を返します。

"z" (文字列型または None) [char *]
"s" に似ていますが、Python オブジェクトは None でも よく、その場合には C のポインタは NULLにセットされます。

"z#" (文字列型、None、または任意の読み出しバッファ互換型) [char *, int]
"s#" の "s" を "z" にしたような意味です。

"u" (Unicode オブジェクト型) [Py_UNICODE *]
Python の Unicode オブジェクトを、NUL で終端された 16 ビットの Unicode (UTF-16) データに変換します。"s" と同様に、 Unicode データバッファ用に記憶領域を提供する必要はありません; Py_UNICODE 型ポインタ変数のアドレスを渡すと、すでに存在している Unicode データへのポインタをその変数に記録します。

"u#" (Unicode オブジェクト型) [Py_UNICODE *, int]
これは "u" の変化形で、値を二つの変数に記録します。一つ目の変数は Unicode データバッファへのポインタで、二つ目はその長さです。 非 Unicode のオブジェクトの場合、読み出しバッファのポインタを Py_UNICODE 型配列へのポインタと解釈して扱います。

"es" (文字列型、Unicode オブジェクト型または任意の読み出しバッファ互換型)[const char *encoding, char **buffer]
これは "s" の変化形で、Unicode オブジェクトや Unicode に 変換可能なオブジェクトをキャラクタ型バッファにエンコードするために 用いられます。NUL バイトが埋め込まれていない文字列でのみ動作します。

この書式化単位には二つの引数が必要です。一つ目は入力にのみ用いられ、 NUL で終端されたエンコード名文字列を指す char* 型で なければなりません。指定したエンコード名を Python が理解できない 場合には例外を送出します。第二の引数は char** でなければ なりません; この引数が参照しているポインタの値は、引数に指定した テキストの内容が入ったバッファへのポインタになります。 テキストは最初の引数に指定したエンコード方式でエンコードされます。

PyArg_ParseTuple() を使うと、必要なサイズのバッファを 確保し、そのバッファにエンコード後のデータをコピーして、 *buffer がこの新たに確保された記憶領域を指すように変更します。 呼び出し側には、確保されたバッファを使い終わった後に PyMem_Free() で解放する責任があります。

"et" (文字列型、Unicode オブジェクト型または文字列バッファ互換型) [const char *encoding, char **buffer]
"es" と同じです。ただし、8 ビット幅の文字列オブジェクトを エンコードし直さずに渡します。その代わり、実装では文字列オブジェクトが パラメタに渡したエンコードを使っているものと仮定します。

"es#" (文字列型、Unicode オブジェクト型または文字列バッファ互換型) [const char *encoding, char **buffer, int *buffer_length]
"s#" の変化形で、Unicode オブジェクトや Unicode に 変換可能なオブジェクトをキャラクタ型バッファにエンコードするために 用いられます。"es" 書式化単位と違って、この変化形はバイトが埋め込まれて いてもかまいません。

この書式化単位には三つの引数が必要です。一つ目は入力にのみ用いられ、 NUL で終端されたエンコード名文字列を指す char* 型か NULLでなければなりません。NULLの場合にはデフォルトエンコーディング を使います。指定したエンコード名を Python が理解できない 場合には例外を送出します。第二の引数は char** でなければ なりません; この引数が参照しているポインタの値は、引数に指定した テキストの内容が入ったバッファへのポインタになります。 テキストは最初の引数に指定したエンコード方式でエンコードされます。 第三の引数は整数へのポインタでなければなりません; ポインタが参照 している整数の値は出力バッファ内のバイト数にセットされます。

この書式化単位の処理には二つのモードがあります:

*buffer がNULL ポインタを指している場合、関数は 必要なサイズのバッファを確保し、そのバッファにエンコード後の データをコピーして、*buffer がこの新たに確保された 記憶領域を指すように変更します。 呼び出し側には、確保されたバッファを使い終わった後に PyMem_Free() で解放する責任があります。

*buffer が非 NULL のポインタ (すでにメモリ確保済みの バッファ) を指している場合、PyArg_ParseTuple() はこのメモリ位置をバッファとして用い、*buffer_length の初期値をバッファサイズとして用います。PyArg_ParseTuple() は次にエンコード済みのデータをバッファにコピーして、NUL で終端 します。バッファの大きさが足りなければ ValueError がセットされます。

どちらの場合も、 *buffer_length は終端の NUL バイトを 含まないエンコード済みデータの長さにセットされます。

"et#" (文字列型、Unicode オブジェクト型または文字列バッファ互換型) [const char *encoding, char **buffer]
"es#" と同じです。ただし、文字列オブジェクトを エンコードし直さずに渡します。その代わり、実装では文字列オブジェクトが パラメタに渡したエンコードを使っているものと仮定します。

"b" (整数型) [char]
Python の整数型を、 C の char 型の小さな整数に変換します。

"B" (整数型) [unsigned char]
Python の整数型を、オーバフローチェックを行わずに、 C の unsigned char 型の小さな整数に変換します。 バージョン2.3 以降で新規追加された 仕様です。

"h" (整数型) [short int]
Python の整数型を、 C の short int 型に変換します。

"H" (整数型) [unsigned short int]
Python の整数型を、オーバフローチェックを行わずに、 C の unsigned short int 型に変換します。 バージョン2.3 以降で新規追加された 仕様です。

"i" (整数型) [int]
Python の整数型を、 C の int 型に変換します。

"I" (整数型) [unsigned int]
Python の整数型を、オーバフローチェックを行わずに、 C の unsigned int 型に変換します。 バージョン2.3 以降で新規追加された 仕様です。

"l" (整数型) [long int]
Python の整数型を、 C の long int 型に変換します。

"k" (整数型) [unsigned long]
Python の整数型を、オーバフローチェックを行わずに、 C の unsigned long int 型に変換します。 バージョン2.3 以降で新規追加された 仕様です。

"L" (整数型) [PY_LONG_LONG]
Python の整数型を、 C の long long 型に変換します。 この書式化単位は、long long 型 (または Windows の _int64 型) がサポートされているプラットフォームでのみ 利用できます。 Convert a Python integer to a C long long. This format is only available on platforms that support long long (or _int64 on Windows).

"K" (整数型) [unsigned PY_LONG_LONG]
Python の整数型を、オーバフローチェックを行わずに、 C の unsigned long long 型に変換します。 この書式化単位は、unsigned long long 型 (または Windows の unsigned _int64 型) がサポートされているプラットフォームでのみ 利用できます。 バージョン2.3 以降で新規追加された 仕様です。

"c" (長さ 1 の文字列型) [char]
長さ 1 の文字列として表現されている Python キャラクタを C の char 型に変換します。

"f" (浮動小数点型) [float]
Python の浮動小数点型を、 C の float 型に変換します。

"d" (浮動小数点型) [double]
Python の浮動小数点型を、 C の double 型に変換します。

"D" (複素数型) [Py_complex]
Python の複素数型を、 C の Py_complex 構造体に変換します。

"O" (オブジェクト) [PyObject *]
Python オブジェクトを (一切変換を行わずに) C の Python オブジェクト型 ポインタに保存します。これにより、C プログラムは実際のオブジェクトを 受け渡しされます。オブジェクトの参照カウントは増加しません。 保存されるポインタが NULLになることはありません。

"O!" (オブジェクト) [typeobject, PyObject *]
Python オブジェクトを C の Python オブジェクト型ポインタに保存します。 "O" に似ていますが、二つの C の引数をとります: 一つ目の引数は Python の型オブジェクトへのアドレスで、二つ目の引数は オブジェクトへのポインタが保存されている (PyObject* の) C の 変数へのアドレスです。Python オブジェクトが指定した型ではない場合、 TypeError を送出します。

"O&" (オブジェクト) [converter, anything]
Python オブジェクトを converter 関数を介して C の変数に変換します。 二つの引数をとります: 一つ目は関数で、二つ目は (任意の型の) C 変数 へのアドレスをvoid * 型に変換したものです。 converter は以下のようにして呼び出されます:

status = converter(object, address);

ここで object は変換対象の Python オブジェクトで、 address は PyArg_Parse*() に渡した void* 型の引数です。戻り値 status は変換に成功した際に 1、 失敗した場合には 0 になります。変換に失敗した場合、 converter 関数は例外を送出しなくてはなりません。

"S" (文字列型) [PyStringObject *]
"O" に似ていますが、Python オブジェクトは文字列オブジェクトで なければなりません。 オブジェクトが文字列オブジェクトでない場合にはTypeError を送出します。 C 変数は PyObject* で宣言しておいてもかまいません。

"U" (Unicode 文字列型) [PyUnicodeObject *]
"O" に似ていますが、Python オブジェクトは Unicode オブジェクトで なければなりません。 オブジェクトが Unicode オブジェクトでない場合にはTypeError を送出します。 C 変数は PyObject* で宣言しておいてもかまいません。

"t#" (読み出し専用キャラクタバッファ) [char *, int]
"s#" に似ていますが、読み出し専用バッファインタフェースを 実装している任意のオブジェクトを受理します。 char* 変数はバッファの最初のバイトを指すようにセットされ、 int はバッファの長さにセットされます。 単一セグメントからなるバッファオブジェクトだけを受理します; それ以外の場合には TypeError を送出します。

"w" (読み書き可能なキャラクタバッファ) [char *]
"s" と同様ですが、読み書き可能なバッファインタフェースを 実装している任意のオブジェクトを受理します。 呼び出し側は何らかの別の手段でバッファの長さを決定するか、 あるいは"w#" を使わねばなりません。 単一セグメントからなるバッファオブジェクトだけを受理します; それ以外の場合には TypeError を送出します。

"w#" (読み書き可能なキャラクタバッファ) [char *, int]
"s#" に似ていますが、読み書き可能なバッファインタフェースを 実装している任意のオブジェクトを受理します。 char* 変数はバッファの最初のバイトを指すようにセットされ、 int はバッファの長さにセットされます。 単一セグメントからなるバッファオブジェクトだけを受理します; それ以外の場合には TypeError を送出します。

"(items)" (タプル) [matching-items]
オブジェクトはitems に入っている書式化単位の数だけの長さを持つ Python の配列型でなくてはなりません。各 C 引数は items 内の 個々の書式化単位に対応づけできねばなりません。 配列の書式化単位は入れ子構造にできます。

注意: Python のバージョン 1.5.2 より以前は、この書式化指定文字列は パラメタ列ではなく、個別のパラメタが入ったタプルでなければなりません でした。このため、以前は TypeError を引き起こしていたよう なコードが現在は例外を出さずに処理されるかもしれません。 とはいえ、既存のコードにとってこれは問題ないと思われます。

Python 整数型を要求している場所に Python 長整数型を渡すのは 可能です; しかしながら、適切な値域チェックはまったく行われません -- 値を受け取るためのフィールドが、値全てを受け取るには小さすぎる 場合、上桁のビット群は暗黙のうちに切り詰められます (実際のところ、 このセマンティクスは C のダウンキャスト (downcast) から継承して います -- その恩恵は人それぞれかもしれませんが)。

その他、書式化文字列において意味を持つ文字がいくつかあります。 それらの文字は括弧による入れ子内には使えません。以下に文字を 示します:

"|"
Python 引数リスト中で、この文字以降の引数がオプションであることを 示します。 オプションの引数に対応する C の変数はデフォルトの値で初期化して おかねばなりません -- オプションの引数が省略された場合、 PyArg_ParseTuple() は対応する C 変数の内容に 手を加えません。

":"
この文字があると、書式化単位の記述はそこで終わります; コロン以降の文字列は、エラーメッセージにおける関数名 (PyArg_ParseTuple() が送出する例外の ``付属値 (associated value)'') として使われます。

";"
この文字があると、書式化単位の記述はそこで終わります; セミコロン以降の文字列は、デフォルトエラーメッセージを 置き換える エラーメッセージとして使われます。 言うまでもなく、":" と ";" は相互に排他の文字です。

呼び出し側に提供される Python オブジェクトの参照は全て 借りた (borrowed) ものです; オブジェクトの参照カウントを デクリメントしてはなりません!

以下の関数に渡す補助引数 (additional argument) は、書式化文字列から 決定される型へのアドレスでなければなりません; 補助引数に指定した アドレスは、タプルから入力された値を保存するために使います。 上の書式化単位のリストで説明したように、補助引数を入力値として 使う場合がいくつかあります; その場合、対応する書式化単位 の指定する形式に従うようにせねばなりません。

変換を正しく行うためには、arg オブジェクトは 書式化文字に一致しなければならず、かつ書式化文字列内の 書式化単位に全て値が入るようにせねばなりません。 成功すると、PyArg_Parse*() 関数は真を返します。 それ以外の場合には偽を返し、適切な例外を送出します。

int PyArg_ParseTuple( PyObject *args, char *format, ...)
固定引数のみを引数にとる関数のパラメタを解釈して、ローカルな 変数に変換します。 成功すると真を返します;失敗すると偽を返し、適切な例外を送出します。

int PyArg_ParseTupleAndKeywords( PyObject *args, PyObject *kw, char *format, char *keywords[], ...)
固定引数およびキーワード引数をとる関数のパラメタを解釈して、ローカルな 変数に変換します。 成功すると真を返します;失敗すると偽を返し、適切な例外を送出します。

int PyArg_Parse( PyObject *args, char *format, ...)
``旧形式'' の関数における引数リストを分析するために使われる 関数です -- 旧形式の関数は、引数解釈手法に METH_OLDARGS を使います。 新たに書かれるコードでのパラメタ解釈にはこの関数の使用は奨められず、 標準のインタプリタにおけるほとんどのコードがもはや引数解釈の ためにこの関数を使わないように変更済みです。 この関数を残しているのは、この関数が依然として引数以外のタプルを 分析する上で便利だからですが、この目的においては将来も使われ つづけるかもしれません。

int PyArg_UnpackTuple( PyObject *args, char *name, int min, int max, ...)
パラメータ取得を簡単にした形式で、引数の型を指定する書式化文字列を 使いません。 パラメタの取得にこの手法を使う関数は、関数宣言テーブル、またはメソッド 宣言テーブル内でMETH_VARARGS として宣言しなくては なりません。 実引数の入ったタプルは args に渡します; このタプルは本当のタプルでなくてはなりません。 タプルの長さは少なくとも min で、max を超えてはなりません; min と max が等しくてもかまいません。 補助引数を関数に渡さなくてはならず、各補助引数はPyObject* 変数へのポインタでなくてはなりません; これらの補助引数には、 args の値が入ります; 値の参照は借りた参照です。 オプションのパラメタに対応する変数のうち、args に指定していない ものには値が入りません; 呼び出し側はそれらの値を初期化しておかねば なりません。 この関数は成功すると真を返し、args がタプルでない場合や 間違った数の要素が入っている場合に偽を返します; 何らかの失敗が 起きた場合には例外をセットします。

この関数の使用例を以下に示します。この例は、弱参照のための _weakref 補助モジュールのソースコードからとったものです:

static PyObject *
weakref_ref(PyObject *self, PyObject *args)
{
    PyObject *object;
    PyObject *callback = NULL;
    PyObject *result = NULL;

    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
        result = PyWeakref_NewRef(object, callback);
    }
    return result;
}

この例におけるPyArg_UnpackTuple() 呼び出しは、 PyArg_ParseTuple() を使った以下の呼び出し:

PyArg_ParseTuple(args, "O|O:ref", &object, &callback)

と全く等価です。

バージョン2.2 以降で新規追加された 仕様です。

PyObject* Py_BuildValue( char *format, ...)
戻り値: 新たな参照.
PyArg_Parse*() ファミリの関数が受け取るのと似た 形式の書式化文字列および値列に基づいて、新たな値を生成します。 生成した値を返します。エラーの場合にはNULL を返します; NULL を返す場合、例外を送出するでしょう。

Py_BuildValue() は常にタプルを生成するとは限りません。 この関数がタプルを生成するのは、書式化文字列に二つ以上の書式化単位 が入っているときだけです。書式化文字列が空の場合、None を返します; 書式化単位が厳密に一つだけ入っている場合、 書式化単位で指定されている何らかのオブジェクト単体を返します。 サイズがゼロや 1 のタプルを返すように強制するには、 丸括弧で囲われた書式化文字列を使います。

書式化単位 "s" や "s#" の場合のように、オブジェクトを 構築する際にデータを供給するためにメモリバッファをパラメタとして渡す 場合には、指定したデータはコピーされます。Py_BuildValue() が生成したオブジェクトは、呼び出し側が提供したバッファを決して参照 しません。 別の言い方をすれば、malloc() を呼び出してメモリを確保し、 それを Py_BuildValue() に渡した場合、コード内で Py_BuildValue() が返った後でfree() を 呼び出す責任があるということです。

以下の説明では、引用符のついた形式は書式化単位です; (丸)括弧で囲った部分は書式化単位が返す Python のオブジェクト型 です; [角] 括弧は関数に渡す値の C 変数型です。

書式化文字列内では、("s#" のような書式化単位を除いて) スペース、 タブ、コロンおよびコンマは無視されます。 これらの文字を使うと、長い書式化文字列をちょっとだけ読みやすく できます。

"s" (文字列型) [char *]
null 終端された C 文字列から Python オブジェクトに変換します。 C 文字列ポインタが NULLの場合、 None になります。

"s#" (文字列型) [char *, int]
C 文字列とその長さから Python オブジェクトに変換します。 C 文字列ポインタが NULLの場合、長さは無視され None になります。

"z" (string or None) [char *]
"s" と同じです。

"z#" (string or None) [char *, int]
"s#" と同じです。

"u" (Unicode string) [Py_UNICODE *]
null 終端された Unicode (UCS-2) データのバッファから Python オブジェクトに変換します。 Unicode バッファポインタが NULLの場合、 None になります。

"u#" (Unicode string) [Py_UNICODE *, int]
null 終端された Unicode (UCS-2) データのバッファとその長さから Python オブジェクトに変換します。 Unicode バッファポインタが NULLの場合、長さは無視され None になります。

"i" (整数型) [int]
通常の C の int を Python の整数オブジェクトに変換します。

"b" (整数型) [char]
"i" と同じです。

"h" (整数型) [short int]
"i" と同じです。

"l" (整数型) [long int]
C の long int を Python の整数オブジェクトに変換します。

"c" (string of length 1) [char]
文字を表す通常の C の int を、長さ 1 の Python の文字列 オブジェクトに変換します。

"d" (浮動小数点型) [double]
C の double を Python の浮動小数点数に変換します。

"f" (浮動小数点型) [float]
"d" と同じです。

"D" (複素数型) [Py_complex *]
C の Py_complex 構造体を Python の複素数に変換します。

"O" (オブジェクト) [PyObject *]
Python オブジェクトを手を加えずに渡します (ただし、参照カウントは 1 インクリメントします)。渡したオブジェクトが NULL ポインタ の場合、この引数を生成するのに使った何らかの呼び出しがエラーに なったのが原因であると仮定して、例外をセットします。 従ってこのとき Py_BuildValue() は NULL を返しますが Py_BuildValue() 自体は例外を送出しません。 例外をまだ送出していなければSystemError をセットします。

"S" (オブジェクト) [PyObject *]
"O" と同じです。

"U" (オブジェクト) [PyObject *]
"O" と同じです。

"N" (オブジェクト) [PyObject *]
"O" と同じです。ただし、オブジェクトの参照カウントを インクリメントしません。オブジェクトが引数リスト内のオブジェクト コンストラクタ呼び出しによって生成されている場合に便利です。

"O&" (オブジェクト) [converter, anything]
anything を converter 関数を介して Python オブジェクトに 変換します。この関数は anything (void * と互換の型で なければなりません) を引数にして呼び出され、``新たな'' オブジェクト を返すか、失敗した場合には NULL を返すようにしなければなりません。

"(items)" (タプル型) [matching-items]
C の値からなる配列を、同じ要素数を持つ Python のタプルに変換します。

"[items]" (リスト型) [matching-items]
C の値からなる配列を、同じ要素数を持つ Python のリストに変換します。

"{items}" (辞書型) [matching-items]
C の値からなる配列を Python の辞書に変換します。一連のペアからなる C の値が、それぞれキーおよび値となって辞書に追加されます。

書式化文字列に関するエラーが生じると、SystemError 例外を セットして NULL を返します。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 5.4 データ整列化 (data marshalling) Up: 5. ユーティリティ関数 Next: 6. 抽象オブジェクトレイヤ (abstract objects
Release 2.3.3, documentation updated on December 19, 2003.


6. 抽象オブジェクトレイヤ (abstract objects layer)

この章で説明する関数は、Python オブジェクトとのやりとりを型や (数値型全て、配列型全てといった) 大まかなオブジェクト型の種類に 関係なく行います。関数を適用対象でないオブジェクトに対して 使った場合、 Python の例外が送出されることになります。

  • 6.1 オブジェクトプロトコル (object protocol)
  • 6.2 数値型プロトコル (number protocol)
  • 6.3 配列プロトコル (sequence protocol)
  • 6.4 マップ型プロトコル (mapping protocol)
  • 6.5 イテレータプロトコル (iterator protocol)
  • 6.6 バッファプロトコル (buffer protocol)
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 5.5 引数の解釈と値の構築 Up: Python/C API リファレンスマニュアル Next: 6.1 オブジェクトプロトコル (object protocol)
Release 2.3.3, documentation updated on December 19, 2003.


6.1 オブジェクトプロトコル (object protocol)

int PyObject_Print( PyObject *o, FILE *fp, int flags)
オブジェクト o をファイル fp に出力します。 失敗すると-1 を返します。 flags 引数は何らかの出力オプションを有効にする際に使います。 現在サポートされている唯一のオプションはPy_PRINT_RAW です; このオプションを指定すると、repr() の代わりに str() を使ってオブジェクトを書き込みます。

int PyObject_HasAttrString( PyObject *o, char *attr_name)
o が属性 attr_name を持つときに 1 を、それ以外の ときに 0 を返します。この関数は Python の式 "hasattr(o, attr_name)" と同じです。 この関数は常に成功します。

PyObject* PyObject_GetAttrString( PyObject *o, char *attr_name)
戻り値: 新たな参照.
オブジェクト o から、名前 attr_name の属性を取得します。 成功すると属性値を返し失敗すると NULL を返します。 この関数は Python の式 "o.attr_name"と同じです。

int PyObject_HasAttr( PyObject *o, PyObject *attr_name)
o が属性 attr_name を持つときに 1 を、それ以外の ときに 0 を返します。この関数は Python の式 "hasattr(o, attr_name)" と同じです。 この関数は常に成功します。

PyObject* PyObject_GetAttr( PyObject *o, PyObject *attr_name)
戻り値: 新たな参照.
オブジェクト o から、名前 attr_name の属性を取得します。 成功すると属性値を返し失敗すると NULL を返します。 この関数は Python の式 "o.attr_name"と同じです。

int PyObject_SetAttrString( PyObject *o, char *attr_name, PyObject *v)
オブジェクト o のattr_name という名の属性に、値 v を設定します。失敗すると -1 を返します。 この関数は Python の式 "o.attr_name = v"と同じです。

int PyObject_SetAttr( PyObject *o, PyObject *attr_name, PyObject *v)
オブジェクト o のattr_name という名の属性に、値 v を設定します。失敗すると -1 を返します。 この関数は Python の式 "o.attr_name = v"と同じです。

int PyObject_DelAttrString( PyObject *o, char *attr_name)
オブジェクト o のattr_name という名の属性を削除します。 失敗すると -1 を返します。 この関数は Python の文 "del o.attr_name"と同じです。

int PyObject_DelAttr( PyObject *o, PyObject *attr_name)
オブジェクト o のattr_name という名の属性を削除します。 失敗すると -1 を返します。 この関数は Python の文 "del o.attr_name"と同じです。

PyObject* PyObject_RichCompare( PyObject *o1, PyObject *o2, int opid)
戻り値: 新たな参照.
o1 と o2 を opid に指定した演算によって比較します。 opid は Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT, または Py_GE, のいずれかでなければならず、それぞれ <, <=, ==, !=, >, および >= に対応します。 この関数は Python の式 "o1 op o2" と同じで、 op が opid に対応する演算子です。 成功すると比較結果の値を返し失敗すると NULL を返します。

int PyObject_RichCompareBool( PyObject *o1, PyObject *o2, int opid)
o1 と o2 を opid に指定した演算によって比較します。 opid は Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT, または Py_GE, のいずれかでなければならず、それぞれ <, <=, ==, !=, >, および >= に対応します。 比較結果が真ならば 1 を、偽ならば 0 を、 エラーが発生すると -1 を返します。 この関数は Python の式 "o1 op o2" と同じで、 op が opid に対応する演算子です。

int PyObject_Cmp( PyObject *o1, PyObject *o2, int *result)
o1 と o2 の値を比較します。このときo1 が比較ルーチンを 持っていればそれを使い、なければ o2 のルーチンを使います。 比較結果は result に返されます。失敗すると -1 を返します。 Python 文 "result = cmp(o1, o2)"と同じです。

int PyObject_Compare( PyObject *o1, PyObject *o2)
o1 と o2 の値を比較します。このときo1 が比較ルーチンを 持っていればそれを使い、なければ o2 のルーチンを使います。 比較結果は result に返されます。失敗すると -1 を返します。 Python 文 "result = cmp(o1, o2)"と同じです。成功すると比較結果を返します。エラーが生じた場合の 戻り値は未定義です; PyErr_Occurred() を使ってエラー検出を 行って下さい。Python 式 "cmp(o1, o2)"と同じです。

PyObject* PyObject_Repr( PyObject *o)
戻り値: 新たな参照.
o の文字列表現を計算します。成功すると文字列表現を返し、 失敗すると NULL を返します。Python 式"repr(o)"と同じです。この関数は組み込み関数 repr() や逆クオート表記の処理で 呼び出されます。

PyObject* PyObject_Str( PyObject *o)
戻り値: 新たな参照.
o の文字列表現を計算します。成功すると文字列表現を返し、 失敗すると NULL を返します。Python 式"str(o)"と同じです。この関数は組み込み関数 str() やprint 文の処理で 呼び出されます。

PyObject* PyObject_Unicode( PyObject *o)
戻り値: 新たな参照.
o の Unicode 文字列表現を計算します。成功すると Unicode 文字列表現を返し失敗すると NULL を返します。 Python 式"unicode(o)" と同じです。この関数は組み込み関数 unicode() の処理で呼び出されます。

int PyObject_IsInstance( PyObject *inst, PyObject *cls)
inst が cls のインスタンスか、 cls のサブクラスの インスタンスの場合に -1 を返し、そうでなければ 0 を 返します。エラーの時には -1 を返し、例外をセットします。 cls がクラスオブジェクトではなく型オブジェクトの場合、 PyObject_IsInstance() は inst がcls で あるときに 1 を返します。cls をタプルで指定した場合、 cls に指定した全てのエントリについてチェックを行います。 少なくとも一つのエントリに対するチェックが 1 を返せば結果は 1 になり、そうでなければ 0 になります。 inst がクラスインスタンスでなく、かつ cls が 型オブジェクトでもクラスオブジェクトでもタプルでもない場合、 inst には __class__ 属性がなくてはなりません -- この場合、__class__ 属性の値と、cls の値の間の クラス関係を、関数の戻り値を決定するのに使います。 バージョン2.1 以降で新規追加された 仕様です。 バージョン2.2 以降で変更された 仕様: 二つ目の引数にタプルのサポートを追加しました。

サブクラスの決定はかなり正攻法で行いますが、クラスシステムの拡張を 実装する人たちに知っておいて欲しいちょっとした問題点があります。 A と B がクラスオブジェクトの場合、 B が A のサブクラスとなるのは、B が A を 直接的あるいは間接的に継承 (inherit) している場合です。 両方がクラスオブジェクトでない場合、二つのオブジェクト間の クラス関係を決めるには、より汎用の機構を使います。 B が A のサブクラスであるか調べたとき、A が B と等しければ、PyObject_IsSubclass() は真を返します。 A および B が異なるオブジェクトなら、B の __bases__ 属性から深さ優先探索 (depth-first search)で A を探索します -- オブジェクトに__bases__ があるだけで、 この決定法を適用する条件を満たしているとみなされます。

int PyObject_IsSubclass( PyObject *derived, PyObject *cls)
クラス derived が cls と同じクラスか、cls の導出 クラスの場合に 1 を返し、それ以外の場合には 0 を 返します。エラーが生じると -1 を返します。 cls をタプルで指定した場合、cls に指定した全てのエントリに ついてチェックを行います。 少なくとも一つのエントリに対するチェックが 1 を返せば結果は 1 になり、そうでなければ 0 になります。 derived または cls のいずれかが実際のクラスオブジェクト (あるいはタプル) でない場合、上で述べた汎用アルゴリズムを使います。 バージョン2.1 以降で新規追加された 仕様です。 バージョン2.3 以降で変更された 仕様: 以前の Python のバージョンは、二つ目の引数に タプルをサポートしていませんでした

int PyCallable_Check( PyObject *o)
オブジェクト o が呼び出し可能オブジェクトかどうか調べます。 オブジェクトが呼び出し可能であるときに 1 を返し、 そうでないときには 0 を返します。 この関数呼び出しは常に成功します。

PyObject* PyObject_Call( PyObject *callable_object, PyObject *args, PyObject *kw)
呼び出し可能な Python オブジェクト callable_object を タプルで指定された引数 args および辞書で指定された名前つき 引数 (named argument) kw とともに呼び出します。名前つき引数を 必要としない場合、 kw を NULL にしてもかまいません。 args は NULL であってはなりません。引数が全く必要ない場合には 空のタプルを使ってください。 成功すると呼び出し結果として得られたオブジェクトを返し、 失敗すると NULL を返します。 Python の式 "apply(callable_object, args, kw)"あるいは "callable_object(*args, **kw)" と同じです。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyObject_CallObject( PyObject *callable_object, PyObject *args)
戻り値: 新たな参照.
呼び出し可能な Python オブジェクト callable_object を タプルで指定された引数 args とともに呼び出します。 引数を 必要としない場合、 args を NULL にしてもかまいません。 成功すると呼び出し結果として得られたオブジェクトを返し、 失敗すると NULL を返します。 Python の式 "apply(callable_object, args)" あるいは "callable_object(*args)" と同じです。

PyObject* PyObject_CallFunction( PyObject *callable, char *format, ...)
戻り値: 新たな参照.
呼び出し可能な Python オブジェクト callable_object を 可変数個の C 引数とともに呼び出します。C 引数は Py_BuildValue() 形式のフォーマット文字列を使って記述します。 format はNULLにしてもよく、与える引数がないことを表します。 成功すると呼び出し結果として得られたオブジェクトを返し、 失敗すると NULL を返します。 Python の式 "apply(callable, args)" あるいは "callable(*args)" と同じです。

PyObject* PyObject_CallMethod( PyObject *o, char *method, char *format, ...)
戻り値: 新たな参照.
オブジェクト o の method という名前のメソッドを、 可変数個の C 引数とともに呼び出します。C 引数は Py_BuildValue() 形式のフォーマット文字列を使って記述します。 format はNULLにしてもよく、与える引数がないことを表します。 成功すると呼び出し結果として得られたオブジェクトを返し、 失敗すると NULL を返します。 Python の式 "o.method(args)" と同じです。

PyObject* PyObject_CallFunctionObjArgs( PyObject *callable, ..., NULL)
戻り値: 新たな参照.

呼び出し可能な Python オブジェクト callable_object を 可変数個の PyObject* 引数とともに呼び出します。 引数列は末尾に NULLがついた可変数個のパラメタとして与えます。 成功すると呼び出し結果として得られたオブジェクトを返し 失敗すると NULL を返します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyObject_CallMethodObjArgs( PyObject *o, PyObject *name, ..., NULL)
戻り値: 新たな参照.
オブジェクト o のメソッドを呼び出します、メソッド名は Python 文字列オブジェクトname で与えます。可変数個の PyObject* 引数と共に呼び出されます. 引数列は末尾に NULLがついた可変数個のパラメタとして与えます。 成功すると呼び出し結果として得られたオブジェクトを返し 失敗すると NULL を返します。 バージョン2.2 以降で新規追加された 仕様です。

int PyObject_Hash( PyObject *o)
オブジェクト o のハッシュ値を計算して返します。 失敗すると -1 を返します。 Python の式 "hash(o)" と同じです。

int PyObject_IsTrue( PyObject *o)
o が真を表すとみなせる場合には 1 を、 そうでないときには 0 を返します。 Python の式 "not not o" と同じです。 失敗すると -1 を返します。

int PyObject_Not( PyObject *o)
o が真を表すとみなせる場合には 0 を、 そうでないときには 1 を返します。 Python の式 "not o" と同じです。 失敗すると -1 を返します。

PyObject* PyObject_Type( PyObject *o)
戻り値: 新たな参照.
o が NULLでない場合、オブジェクトo のオブジェクト型に 相当する型オブジェクトを返します。失敗すると SystemError を送出して NULLを返します。 Python の式 type(o)と同じです。 この関数は戻り値の参照カウントをインクリメントします。 参照カウントのインクリメントが必要でない限り、広く使われていて PyTypeObject* 型のポインタを返す表記法 o->ob_type の代わりに使う理由は全くありません。

int PyObject_TypeCheck( PyObject *o, PyTypeObject *type)
オブジェクト o が、 type か type のサブタイプで あるときに真を返します。どちらのパラメタも NULLであってはなりません。 バージョン2.2 以降で新規追加された 仕様です。

int PyObject_Length( PyObject *o)
int PyObject_Size( PyObject *o)
o の長さを返します。オブジェクトo が配列プロトコルと マップ型プロトコルの両方を提供している場合、配列としての長さを 返します。エラーが生じると -1 を返します。 Python の式 "len(o)"と同じです。

PyObject* PyObject_GetItem( PyObject *o, PyObject *key)
戻り値: 新たな参照.
成功するとオブジェクト key に対応する o の要素を返し、 失敗すると NULL を返します。 Python の式 "o[key]" と同じです。

int PyObject_SetItem( PyObject *o, PyObject *key, PyObject *v)
オブジェクト key を値 v に対応付けます。 失敗すると -1 を返します。 Python の文 "o[key] = v" と同じです。

int PyObject_DelItem( PyObject *o, PyObject *key)
オブジェクト o から key に対する対応付けを削除します。 失敗すると -1 を返します。 Python の文 "del o[key]" と同じです。

int PyObject_AsFileDescriptor( PyObject *o)
Python オブジェクトからファイル記述子を取り出します。 オブジェクトが整数か長整数なら、その値を返します。 (長)整数でない場合、オブジェクトに fileno() メソッドがあれば 呼び出します; この場合、 fileno() メソッドは 整数または長整数をファイル記述子の値として返さなければなりません。 失敗すると -1 を返します。

PyObject* PyObject_Dir( PyObject *o)
戻り値: 新たな参照.
この関数は Python の式 "dir(o)" と同じで、 オブジェクトの変数名に割り当てている文字列からなるリスト (空の場合もあります) を返します。エラーの場合には NULL を返します。引数を NULLにすると、Python における"dir()" と同様に、現在のローカルな名前を返します; この場合、 アクティブな実行フレームがなければ NULL を返しますが、 PyErr_Occurred() は偽を返します。

PyObject* PyObject_GetIter( PyObject *o)
戻り値: 新たな参照.
Python の式 "iter(o)" と同じです。 引数にとったオブジェクトに対する新たなイテレータか、 オブジェクトがすでにイテレータの場合にはオブジェクト自身を 返します。オブジェクトが反復処理不可能であった場合には TypeError を送出して NULL を返します。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 6. 抽象オブジェクトレイヤ (abstract objects Up: 6. 抽象オブジェクトレイヤ (abstract objects Next: 6.2 数値型プロトコル (number protocol)
Release 2.3.3, documentation updated on December 19, 2003.


6.2 数値型プロトコル (number protocol)

int PyNumber_Check( PyObject *o)
オブジェクト o が数値型プロトコルを提供している場合に 1 を返し、そうでないときには偽を返します。 この関数呼び出しは常に成功します。

PyObject* PyNumber_Add( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功するとo1 と o2 を加算した結果を返し、 失敗すると NULL を返します。 Python の式 "o1 + o2" と同じです。

PyObject* PyNumber_Subtract( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功するとo1 から o2 を減算した結果を返し、 失敗すると NULL を返します。 Python の式 "o1 - o2" と同じです。

PyObject* PyNumber_Multiply( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功するとo1 と o2 を乗算した結果を返し、失敗すると NULL を返します。 Python の式 "o1 * o2" と同じです。

PyObject* PyNumber_Divide( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると o1 を o2 で除算した結果を返し, 失敗すると NULL を返します。 Python の式 "o1 / o2" と同じです。

PyObject* PyNumber_FloorDivide( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功するとo1 を o2 で除算した切捨て値を返し、 失敗すると NULL を返します。 ``旧仕様の'' 整数間での除算と同じです。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyNumber_TrueDivide( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると、数学的な o1 の o2 による除算値に対する 妥当な近似 (reasonable approximation) を返し、 失敗すると NULL を返します。 全ての実数を 2 を基数として表現するのは不可能なため、二進の浮動小数点数は ``近似値'' しか表現できません。このため、戻り値も近似になります。 この関数に二つの整数を渡した際、浮動小数点の値を返すことがあります。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyNumber_Remainder( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると o1 を o2 で除算した剰余を返し、 失敗すると NULL を返します。 Python の式 "o1 % o2" と同じです。

PyObject* PyNumber_Divmod( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
組み込み関数 divmod() を参照してください。 失敗すると NULL を返します。 Python の式 "divmod(o1, o2)" と同じです。

PyObject* PyNumber_Power( PyObject *o1, PyObject *o2, PyObject *o3)
戻り値: 新たな参照.
組み込み関数pow() を参照してください。 失敗すると NULL を返します。 Python の式 "pow(o1, o2, o3)"と同じです。 o3 はオプションです。 o3 を無視させたいなら、 Py_None を入れてください (o3 にNULL を渡すと、不正なメモリアクセスを引き起こすことが あります)。

PyObject* PyNumber_Negative( PyObject *o)
戻り値: 新たな参照.
成功するとo の符号反転を返し、失敗すると NULL を返します。 Python の式 "-o" と同じです。

PyObject* PyNumber_Positive( PyObject *o)
戻り値: 新たな参照.
成功すると o を返し、失敗すると NULL を返します。 Python の式 "+o" と同じです。

PyObject* PyNumber_Absolute( PyObject *o)
戻り値: 新たな参照.
成功すると o の絶対値を返し、失敗すると NULL を返します。 Python の式 "abs(o)" と同じです。

PyObject* PyNumber_Invert( PyObject *o)
戻り値: 新たな参照.
成功すると o のビット単位反転 (bitwise negation) を返し、 失敗すると NULL を返します。Python の式 "~o" と同じです。

PyObject* PyNumber_Lshift( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると o1 を o2 だけ左シフトした結果を返し、 失敗すると NULL を返します。 Python の式 "o1 << o2" と同じです。

PyObject* PyNumber_Rshift( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると o1 を o2 だけ右シフトした結果を返し、 失敗すると NULL を返します。 Python の式 "o1 >> o2" と同じです。

PyObject* PyNumber_And( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると o1 と o2 の ``ビット単位論理積 (bitwise and)'' を返し、 失敗すると NULL を返します。 Python の式 "o1 & o2" と同じです。

PyObject* PyNumber_Xor( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると o1 と o2 の ``ビット単位排他的論理和 (bitwise exclusive or)'' を返し、 失敗すると NULL を返します。 Python の式 "o1 ^ o2" と同じです。

PyObject* PyNumber_Or( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると o1 と o2 の ``ビット単位論理和 (bitwise or)'' を返し 失敗すると NULL を返します。 Python の式 "o1 | o2" と同じです。

PyObject* PyNumber_InPlaceAdd( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功するとo1 と o2 を加算した結果を返し、 失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 Python の文 "o1 += o2" と同じです。

PyObject* PyNumber_InPlaceSubtract( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功するとo1 から o2 を減算した結果を返し、 失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 Python の文 "o1 -= o2" と同じです。

PyObject* PyNumber_InPlaceMultiply( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功するとo1 と o2 を乗算した結果を返し、 失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 Python の文 "o1 *= o2" と同じです。

PyObject* PyNumber_InPlaceDivide( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると o1 を o2 で除算した結果を返し, 失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 Python の文 "o1 /= o2" と同じです。

PyObject* PyNumber_InPlaceFloorDivide( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功するとo1 を o2 で除算した切捨て値を返し、 失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 Python の文 "o1 //= o2" と同じです。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyNumber_InPlaceTrueDivide( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると、数学的な o1 の o2 による除算値に対する 妥当な近似 (reasonable approximation) を返し、 失敗すると NULL を返します。 全ての実数を 2 を基数として表現するのは不可能なため、二進の浮動小数点数は ``近似値'' しか表現できません。このため、戻り値も近似になります。 この関数に二つの整数を渡した際、浮動小数点の値を返すことがあります。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyNumber_InPlaceRemainder( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると o1 を o2 で除算した剰余を返し、 , 失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 Python の文 "o1 %= o2" と同じです。

PyObject* PyNumber_InPlacePower( PyObject *o1, PyObject *o2, PyObject *o3)
戻り値: 新たな参照.
組み込み関数pow() を参照してください。 失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 この関数は o3 が Py_None の場合は Python 文 "o1 **= o2" と同じで、それ以外の場合は "pow(o1, o2, o3)" の in-place 版です。 o3 を無視させたいなら、 Py_None を入れてください (o3 にNULL を渡すと、不正なメモリアクセスを引き起こすことが あります)。

PyObject* PyNumber_InPlaceLshift( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると o1 を o2 だけ左シフトした結果を返し、 失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 Python の文 "o1 <<= o2" と同じです。

PyObject* PyNumber_InPlaceRshift( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると o1 を o2 だけ右シフトした結果を返し、 失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 Python の文 "o1 >>= o2" と同じです。

PyObject* PyNumber_InPlaceAnd( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると o1 と o2 の ``ビット単位論理積 (bitwise and)'' を返し、 失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。 Python の文 "o1 &= o2" と同じです。

PyObject* PyNumber_InPlaceXor( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると o1 と o2 の ``ビット単位排他的論理和 (bitwise exclusive or)'' を返し、失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 Python の文 "o1 ^= o2" と同じです。

PyObject* PyNumber_InPlaceOr( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功すると o1 と o2 の ``ビット単位論理和 (bitwise or)'' を返し 失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 Python の文 "o1 |= o2" と同じです。

int PyNumber_Coerce( PyObject **p1, PyObject **p2)
この関数はPyObject* 型の二つの変数のアドレスを引数にとります。 *p1 と*p2 が指すオブジェクトが同じ型の場合、 それぞれの参照カウントをインクリメントして 0 (成功) を返します。 オブジェクトを変換して共通の数値型にできる場合、 *p1 と *p2 を変換後の値に置き換えて (参照カウントを '新しく' して) 、0 を返します。 変換が不可能な場合や、その他何らかのエラーが生じた場合、-1 (失敗) を返し、参照カウントをインクリメントしません。 PyNumber_Coerce(&o1, &o2) の呼び出しは Python 文 "o1, o2 = coerce(o1, o2)" と同じです。

PyObject* PyNumber_Int( PyObject *o)
戻り値: 新たな参照.
成功するとo を整数に変換したものを返し、 失敗すると NULL を返します。 引数の値が整数の範囲外の場合、長整数を代わりに返します。 Python の式 "int(o)" と同じです。

PyObject* PyNumber_Long( PyObject *o)
戻り値: 新たな参照.
成功するとo を長整数に変換したものを返し、 失敗すると NULL を返します。 Python の式 "long(o)" と同じです。

PyObject* PyNumber_Float( PyObject *o)
戻り値: 新たな参照.
成功するとo を浮動小数点数に変換したものを返し、 失敗すると NULL を返します。 Python の式 "float(o)" と同じです。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 6.1 オブジェクトプロトコル (object protocol) Up: 6. 抽象オブジェクトレイヤ (abstract objects Next: 6.3 配列プロトコル (sequence protocol)
Release 2.3.3, documentation updated on December 19, 2003.


6.3 配列プロトコル (sequence protocol)

int PySequence_Check( PyObject *o)
オブジェクトが配列プロトコルを提供している場合に 1 を返し、 そうでないときには 0 を返します。 この関数呼び出しは常に成功します。

int PySequence_Size( PyObject *o)
成功すると配列 o 中のオブジェクトの数を返し、 失敗すると -1 を返します。 配列プロトコルをサポートしないオブジェクトに対しては、 Python の式 "len(o)" と同じ になります。

int PySequence_Length( PyObject *o)
PySequence_Size() の別名です。

PyObject* PySequence_Concat( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功するとo1 と o2 の連結 (concatenation) を返し、 失敗すると NULL を返します。 Python の式 "o1 + o2" と同じです。

PyObject* PySequence_Repeat( PyObject *o, int count)
戻り値: 新たな参照.
成功するとオブジェクトo の count 回繰り返しを返し、 失敗すると NULL を返します。 Python の式 "o * count" と同じです。

PyObject* PySequence_InPlaceConcat( PyObject *o1, PyObject *o2)
戻り値: 新たな参照.
成功するとo1 と o2 の連結 (concatenation) を返し、 失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 Python の式 "o1 += o2" と同じです。

PyObject* PySequence_InPlaceRepeat( PyObject *o, int count)
戻り値: 新たな参照.
成功するとオブジェクトo の count 回繰り返しを返し、 失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 Python の式 "o *= count" と同じです。

PyObject* PySequence_GetItem( PyObject *o, int i)
戻り値: 新たな参照.
成功すると o の i 番目の要素を返し、 失敗すると NULL を返します。 Python の式 "o[i]" と同じです。

PyObject* PySequence_GetSlice( PyObject *o, int i1, int i2)
戻り値: 新たな参照.
成功するとo の i1 から i2 までの間のスライスを返し、 失敗すると NULL を返します。 Python の式 "o[i1:i2]" と同じです。

int PySequence_SetItem( PyObject *o, int i, PyObject *v)
o の i 番目の要素に v を代入します。 失敗すると -1 を返します。 Python の文 "o[i] = v" と同じです。 この関数は v への参照を盗み取りません。

int PySequence_DelItem( PyObject *o, int i)
o の i 番目の要素を削除します。 失敗すると -1 を返します。 Python の文 "del o[i]" と同じです。

int PySequence_SetSlice( PyObject *o, int i1, int i2, PyObject *v)
o の i1 から i2 までの間のスライスに v を代入します。 Python の文 "o[i1:i2] = v" と同じです。

int PySequence_DelSlice( PyObject *o, int i1, int i2)
配列オブジェクト o の i1 から i2 までの間の スライスを削除します。失敗すると -1 を返します。 Python の文 "del o[i1:i2]" と同じです。

PyObject* PySequence_Tuple( PyObject *o)
戻り値: 新たな参照.
成功するとo をタプルで返します。 失敗すると NULL を返します。 Python の式 "tuple(o)" と同じです。

int PySequence_Count( PyObject *o, PyObject *value)
o における value の出現回数、すなわち o[key] == value となる key の個数を 返します。失敗すると -1 を返します。 Python の式 "o.count(value)" と同じです。

int PySequence_Contains( PyObject *o, PyObject *value)
o にvalue が入っているか判定します。 o のある要素が value と等価 (equal) ならば1 を 返し、それ以外の場合には 0 を返します。 エラーが発生すると -1 を返します。 Python の式 "value in o" と同じです。

int PySequence_Index( PyObject *o, PyObject *value)
o[i] == value となる最初に見つかったインデクス i を返します。 エラーが発生すると -1 を返します。 Python の式 "o.index(value)" と同じです。

PyObject* PySequence_List( PyObject *o)
戻り値: 新たな参照.
任意の配列 o と同じ内容を持つリストオブジェクトを返します。 返されるリストは必ず新しいリストオブジェクトになります。

PyObject* PySequence_Tuple( PyObject *o)
戻り値: 新たな参照.
任意の配列 o と同じ内容を持つタプルオブジェクトを返します。 o がタプルの場合、新たな参照を返します。それ以外の場合、 適切な内容が入ったタプルを構築して返します。

PyObject* PySequence_Fast( PyObject *o, const char *m)
戻り値: 新たな参照.
配列 o がすでにタプルやリストであれば o を返し、 そうでなければ o をタプルで返します。 返されるタプルのメンバにアクセスするには PySequence_Fast_GET_ITEM() を使ってください。 失敗すると NULL を返します。 オブジェクトが配列でなければ、m がメッセージテキストに なっているTypeError を送出します。

PyObject* PySequence_Fast_GET_ITEM( PyObject *o, int i)
戻り値: 借りた参照.
o がNULLでなく、PySequence_Fast() が返した オブジェクトであり、かつi がインデクスの範囲内にあると 仮定して、o の i 番目の要素を返します。

PyObject* PySequence_ITEM( PyObject *o, int i)
戻り値: 新たな参照.
成功すると the ith element of o を返し、 失敗すると NULL を返します。 PySequence_GetItem() ですが、 PySequence_Check(o) が真になるかチェックせず、 負のインデクスに対する調整を行いません。 バージョン2.3 以降で新規追加された 仕様です。

int PySequence_Fast_GET_SIZE( PyObject *o)
o がNULLでなく、PySequence_Fast() が返した オブジェクトであると仮定して、o の長さを返します。 o のサイズはPySequence_Size() を呼び出しても 得られますが、PySequence_Fast_GET_SIZE() の方が o をリストかタプルであると仮定して処理するため、より高速です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 6.2 数値型プロトコル (number protocol) Up: 6. 抽象オブジェクトレイヤ (abstract objects Next: 6.4 マップ型プロトコル (mapping protocol)
Release 2.3.3, documentation updated on December 19, 2003.


6.4 マップ型プロトコル (mapping protocol)

int PyMapping_Check( PyObject *o)
オブジェクトがマップ型プロトコルを提供している場合に 1 を返し、 そうでないときには 0 を返します。 この関数呼び出しは常に成功します。

int PyMapping_Length( PyObject *o)
成功するとオブジェクト o 中のキーの数を返し、 失敗すると -1 を返します。 マップ型プロトコルを提供していないオブジェクトに対しては、 Python の式 "len(o)" と同じ になります。

int PyMapping_DelItemString( PyObject *o, char *key)
オブジェクト o から key に関する対応付けを削除します。 失敗すると -1 を返します。 Python の文 "del o[key]" と同じです。

int PyMapping_DelItem( PyObject *o, PyObject *key)
オブジェクト o から key に対する対応付けを削除します。 失敗すると -1 を返します。 Python の文 "del o[key]" と同じです。

int PyMapping_HasKeyString( PyObject *o, char *key)
成功すると、マップ型オブジェクトがキー key を持つ場合に 1 を返し、そうでないときには 0 を返します。 Python の式 "o.has_key(key)" と同じです。 この関数呼び出しは常に成功します。

int PyMapping_HasKey( PyObject *o, PyObject *key)
マップ型オブジェクトがキー key を持つ場合に 1 を返し、 そうでないときには 0 を返します。 Python の式 "o.has_key(key)" と同じです。 この関数呼び出しは常に成功します。

PyObject* PyMapping_Keys( PyObject *o)
戻り値: 新たな参照.
成功するとオブジェクト o のキーからなるリストを返します。 失敗すると NULLを返します。 Python の式 "o.keys()" と同じです。

PyObject* PyMapping_Values( PyObject *o)
戻り値: 新たな参照.
成功するとオブジェクト o のキーに対応する値からなるリストを返します。 失敗すると NULLを返します。 Python の式 "o.values()" と同じです。

PyObject* PyMapping_Items( PyObject *o)
戻り値: 新たな参照.
成功するとオブジェクト o の要素対、すなわちキーと値のペアが 入ったタプルからなるリストを返します。 失敗すると NULLを返します。 Python の式 "o.items()" と同じです。

PyObject* PyMapping_GetItemString( PyObject *o, char *key)
戻り値: 新たな参照.
オブジェクト key に対応するo の要素を返します。 失敗すると NULLを返します。 Python の式 "o[key]" と同じです。

int PyMapping_SetItemString( PyObject *o, char *key, PyObject *v)
オブジェクトo で key を値 v に対応付けます。 失敗すると -1 を返します。 Python の文 "o[key] = v" と同じです。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 6.3 配列プロトコル (sequence protocol) Up: 6. 抽象オブジェクトレイヤ (abstract objects Next: 6.5 イテレータプロトコル (iterator protocol)
Release 2.3.3, documentation updated on December 19, 2003.


6.5 イテレータプロトコル (iterator protocol)

バージョン2.2 以降で新規追加された 仕様です。

イテレータを扱うための固有の関数は二つしかありません。

int PyIter_Check( PyObject *o)
o がイテレータプロトコルをサポートする場合に真を返します。

PyObject* PyIter_Next( PyObject *o)
戻り値: 新たな参照.
反復処理 o における次の値を返します。オブジェクトが イテレータの場合、この関数は反復処理における次の値を取り出します。 要素が何も残っていない場合には例外がセットされていない状態で NULL を 返します。オブジェクトがイテレータでない場合には TypeError を送出します。要素を取り出す際にエラーが生じると NULL を返し、 発生した例外を送出します。

イテレータの返す要素にわたって反復処理を行うループを書くと、 C のコードは以下のようになるはずです:

PyObject *iterator = PyObject_GetIter(obj);
PyObject *item;

if (iterator == NULL) {
    /* エラーの伝播処理をここに書く */
}

while (item = PyIter_Next(iterator)) {
    /* 取り出した要素で何らかの処理を行う */
    ...
    /* 終わったら参照を放棄する */
    Py_DECREF(item);
}

Py_DECREF(iterator);

if (PyErr_Occurred()) {
    /* エラーの伝播処理をここに書く */
}
else {
    /* 別の処理を続ける */
}

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 6.4 マップ型プロトコル (mapping protocol) Up: 6. 抽象オブジェクトレイヤ (abstract objects Next: 6.6 バッファプロトコル (buffer protocol)
Release 2.3.3, documentation updated on December 19, 2003.


6.6 バッファプロトコル (buffer protocol)

int PyObject_AsCharBuffer( PyObject *obj, const char **buffer, int *buffer_len)
文字ベースの入力として使える読み出し専用メモリ上の位置へのポインタを 返します。obj 引数は単一セグメントからなる 文字バッファインタフェースをサポートしていなければなりません。 成功すると 0を返し、buffer をメモリの位置に、 buffer_len をバッファの長さに設定します。エラーの際には -1 を返し、TypeError をセットします。 バージョン1.6 以降で新規追加された 仕様です。

int PyObject_AsReadBuffer( PyObject *obj, const char **buffer, int *buffer_len)
任意のデータを収めた読み出し専用のメモリ上の位置へのポインタを 返します。obj 引数は単一セグメントからなる読み出し可能 バッファインタフェースをサポートしていなければなりません。 成功すると 0を返し、buffer をメモリの位置に、 buffer_len をバッファの長さに設定します。エラーの際には -1 を返し、TypeError をセットします。 バージョン1.6 以降で新規追加された 仕様です。

int PyObject_CheckReadBuffer( PyObject *o)
o が単一セグメントからなる読み出し可能バッファインタフェース をサポートしている場合に 1 を返します。それ以外の場合には 0 を返します。 バージョン2.2 以降で新規追加された 仕様です。

int PyObject_AsWriteBuffer( PyObject *obj, char **buffer, int *buffer_len)
書き込み可能なメモリ上の位置へのポインタを返します。obj 引数は単一セグメントからなる文字バッファインタフェース をサポートしていなければなりません。成功すると 0を返し、 buffer をメモリの位置に、 buffer_len をバッファの 長さに設定します。エラーの際には -1 を返し、 TypeError をセットします。 バージョン1.6 以降で新規追加された 仕様です。
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 6.5 イテレータプロトコル (iterator protocol) Up: 6. 抽象オブジェクトレイヤ (abstract objects Next: 7. 具象オブジェクト (concrete object)
Release 2.3.3, documentation updated on December 19, 2003.


7. 具象オブジェクト (concrete object) レイヤ

この章ではは、特定の Python オブジェクト型固有の関数について述べて います。これらの関数に間違った方のオブジェクトを渡すのは良い考え であありません; Python プログラムから何らかのオブジェクトを受け取った とき、そのオブジェクトが正しい型になっているか確信をもてないの なら、まず型チェックを行わなければなりません; 例えば、あるオブジェクト が辞書型か調べるには、PyDict_Check() を使います。 この章は Python のオブジェクト型における ``家計図'' に従って構成 されています。

警告: この章で述べている関数は、渡されたオブジェクトの型を注意深く チェックしはするものの、多くの関数は渡されたオブジェクトが有効な NULL なのか有効なオブジェクトなのかをチェックしません。 これらの関数に NULL を渡させてしまうと、関数はメモリアクセス 違反を起こして、インタプリタを即座に終了させてしまうはずです。

  • 7.1 基本オブジェクト (fundamental object)
    • 7.1.1 型オブジェクト (type object)
    • 7.1.2 None オブジェクト
  • 7.2 数値型オブジェクト (numeric object)
    • 7.2.1 (通常)整数型オブジェクト (plain integer object)
    • 7.2.2 長整数型オブジェクト (long integer object)
    • 7.2.3 浮動小数点型オブジェクト (floating point object)
    • 7.2.4 浮動小数点オブジェクト (complex number object)
      • 7.2.4.1 C 構造体としての複素数
      • 7.2.4.2 Python オブジェクトとしての複素数型
  • 7.3 配列オブジェクト (sequence object)
    • 7.3.1 文字列オブジェクト (string object)
    • 7.3.2 Unicode オブジェクト (Unicode object)
      • 7.3.2.1 組み込み codec (built-in codec)
      • 7.3.2.2 メソッドおよびスロット関数 (slot function)
    • 7.3.3 Buffer Objects
    • 7.3.4 タプルオブジェクト (tuple object)
    • 7.3.5 List Objects
  • 7.4 マップ型オブジェクト (mapping object)
    • 7.4.1 辞書オブジェクト (dictionary object)
  • 7.5 その他のオブジェクト
    • 7.5.1 ファイルオブジェクト (file object)
    • 7.5.2 インスタンスオブジェクト (instance object)
    • 7.5.3 メソッドオブジェクト (method object)
    • 7.5.4 モジュールオブジェクト (module object)
    • 7.5.5 イテレータオブジェクト (iterator object)
    • 7.5.6 デスクリプタオブジェクト (descriptor object)
    • 7.5.7 スライスオブジェクト (slice object)
    • 7.5.8 弱参照オブジェクト (weak reference object)
    • 7.5.9 Cオブジェクト (CObject)
    • 7.5.10 セルオブジェクト (cell object)
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 6.6 バッファプロトコル (buffer protocol) Up: Python/C API リファレンスマニュアル Next: 7.1 基本オブジェクト (fundamental object)
Release 2.3.3, documentation updated on December 19, 2003.


7.1 基本オブジェクト (fundamental object)

この節では、Python の型オブジェクトと単量子 (singleton) オブジェクト None について述べます。

  • 7.1.1 型オブジェクト (type object)
  • 7.1.2 None オブジェクト
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7. 具象オブジェクト (concrete object) Up: 7. 具象オブジェクト (concrete object) Next: 7.1.1 型オブジェクト (type object)
Release 2.3.3, documentation updated on December 19, 2003.


7.1.1 型オブジェクト (type object)

PyTypeObject
組み込み型を記述する際に用いられる、オブジェクトを表す C 構造体です。

PyObject* PyType_Type
型オブジェクト自身の型オブジェクトです; Python レイヤにおける types.TypeType と同じオブジェクトです。

int PyType_Check( PyObject *o)
オブジェクト o が型オブジェクトの場合に真を返します。 標準型オブジェクトから導出されたサブタイプ (subtype) のインスタンスも 含みます。その他の場合には偽を返します。

int PyType_CheckExact( PyObject *o)
オブジェクト o が型オブジェクトの場合に真を返します。 標準型のサブタイプの場合は含みません。その他の場合には偽を返します。 バージョン2.2 以降で新規追加された 仕様です。

int PyType_HasFeature( PyObject *o, int feature)
型オブジェクト o に、型機能 feature が設定されている 場合に真を返します。型機能は各々単一ビットのフラグで表されます。

int PyType_IS_GC( PyObject *o)
型オブジェクトが o が循環参照検出をサポートしている場合に 真を返します; この関数は型機能フラグ Py_TPFLAGS_HAVE_GC の設定状態をチェックします。 バージョン2.0 以降で新規追加された 仕様です。

int PyType_IsSubtype( PyTypeObject *a, PyTypeObject *b)
a が b のサブタイプの場合に真を返します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyType_GenericAlloc( PyTypeObject *type, int nitems)
戻り値: 新たな参照.
バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyType_GenericNew( PyTypeObject *type, PyObject *args, PyObject *kwds)
戻り値: 新たな参照.
バージョン2.2 以降で新規追加された 仕様です。

int PyType_Ready( PyTypeObject *type)
型オブジェクトの後始末処理 (finalize) を行います。この関数は 全てのオブジェクトで初期化を完了するために呼び出されなくては なりません。 この関数は、基底クラス型から継承したスロットを型オブジェクトに追加する 役割があります。 成功した場合には 0 を返し、エラーの場合には -1 を 返して例外情報を設定します。 バージョン2.2 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.1 基本オブジェクト (fundamental object) Up: 7.1 基本オブジェクト (fundamental object) Next: 7.1.2 None オブジェクト
Release 2.3.3, documentation updated on December 19, 2003.


7.1.2 None オブジェクト

None に対する PyTypeObject は、 Python/C API では 直接公開されていないので注意してください。 None は単量子 (singleton) なので、オブジェクトのアイデンティティテスト (C では "==") を使うだけで十分だからです。 同じ理由から、PyNone_Check() 関数はありません。

PyObject* Py_None
Python における None オブジェクトで、値がないことを表します。 このオブジェクトにはメソッドがありません。リファレンスカウントに ついては、このオブジェクトも他のオブジェクトと同様に扱う必要が あります。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.1.1 型オブジェクト (type object) Up: 7.1 基本オブジェクト (fundamental object) Next: 7.2 数値型オブジェクト (numeric object)
Release 2.3.3, documentation updated on December 19, 2003.


7.2 数値型オブジェクト (numeric object)

  • 7.2.1 (通常)整数型オブジェクト (plain integer object)
  • 7.2.2 長整数型オブジェクト (long integer object)
  • 7.2.3 浮動小数点型オブジェクト (floating point object)
  • 7.2.4 浮動小数点オブジェクト (complex number object)
    • 7.2.4.1 C 構造体としての複素数
    • 7.2.4.2 Python オブジェクトとしての複素数型
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.1.2 None オブジェクト Up: 7. 具象オブジェクト (concrete object) Next: 7.2.1 (通常)整数型オブジェクト (plain integer
Release 2.3.3, documentation updated on December 19, 2003.


7.2.1 (通常)整数型オブジェクト (plain integer object)

PyIntObject
この PyObject のサブタイプは Python の整数型オブジェクトを表現します。

PyTypeObject PyInt_Type
この PyTypeObject のインスタンスは Python の (長整数でない) 整数型を表現します。これは types.IntType と同じオブジェクトです。

int PyInt_Check( PyObject* o)
o が PyInt_Type 型か PyInt_Type 型のサブタイプであるときに真を返します。 バージョン2.2 以降で変更された 仕様: サブタイプを引数にとれるようになりました

int PyInt_CheckExact( PyObject* o)
o が PyInt_Type 型で、かつ PyInt_Type 型のサブタイプでないときに真を返します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyInt_FromString( char *str, char **pend, int base)
str の文字列値に基づいて、新たな PyIntObject または PyLongObject を返します。このとき base を基数として文字列を解釈します。 pend が NULLでなければ、 *pend は str 中で 数が表現されている部分以後の先頭の文字のアドレスを指しています。 base が 0 ならば、str の先頭の文字列に基づいて 基数を決定します: もし str が '0x' または '0X' で始まっていれば、基数に 16 を使います; str が '0' で始まっていれば、基数に 8 を使います; その他の場合には基数に 10 を 使います。base が 0 でなければ、base は 2 以上 36 以下の数でなければなりません。先頭に空白がある場合は 無視されます。数字が全くない場合、ValueError が送出 されます。使用しているマシンの long int 型で表現し切れないくらい 大きな数が文字列に入っており、オーバフロー警告が抑制されていれば、 PyLongObject を返します。オーバフロー警告が抑制されていなければ、 NULL を返します。

PyObject* PyInt_FromLong( long ival)
戻り値: 新たな参照.
ival の値を使って新たな整数オブジェクトを生成します。

現在の実装では、-1 から 100 までの全ての整数 に対する整数オブジェクトの配列を保持するようにしており、 この範囲の数を生成すると、実際には既存のオブジェクトに 対する参照が返るようになっています。従って、 1 の 値を変えることすら可能です。変えてしまった場合の Python の 挙動は未定義です :-)

long PyInt_AsLong( PyObject *io)
オブジェクトがまだ PyIntObject でなければまず型キャストを 試み、次にその値を返します。

long PyInt_AS_LONG( PyObject *io)
オブジェクト io の値を返します。エラーチェックを行いません。

unsigned long PyInt_AsUnsignedLongMask( PyObject *io)
オブジェクトがまだ PyIntObject または PyLongObject で なければまず型キャストを試み、次にその値をunsigned long 型で 返します。この関数はオーバフローをチェックしません。 バージョン2.3 以降で新規追加された 仕様です。

unsigned long PyInt_AsUnsignedLongLongMask( PyObject *io)
オブジェクトがまだ PyIntObject または PyLongObject で なければまず型キャストを試み、次にその値をunsigned long long 型で 返します。オーバフローをチェックしません。 バージョン2.3 以降で新規追加された 仕様です。

long PyInt_GetMax( )
システムの知識に基づく、扱える最大の整数値 (システムのヘッダファイル に定義されている LONG_MAX を返します。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.2 数値型オブジェクト (numeric object) Up: 7.2 数値型オブジェクト (numeric object) Next: 7.2.2 長整数型オブジェクト (long integer
Release 2.3.3, documentation updated on December 19, 2003.


7.2.2 長整数型オブジェクト (long integer object)

PyLongObject
この PyObject のサブタイプは長整数型を表現します。

PyTypeObject PyLong_Type
この PyTypeObject のインスタンスは Python 長整数型を表現します。これは types.LongType と同じオブジェクトです。

int PyLong_Check( PyObject *p)
引数が PyLongObject か PyLongObject のサブタイプのときに真を返します。 バージョン2.2 以降で変更された 仕様: サブタイプを引数にとれるようになりました

int PyLong_CheckExact( PyObject *p)
引数が PyLongObject 型で、かつ PyLongObject 型のサブタイプでないときに真を返します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyLong_FromLong( long v)
戻り値: 新たな参照.
v から新たな PyLongObject オブジェクトを生成して返します。 失敗のときには NULL を返します。

PyObject* PyLong_FromUnsignedLong( unsigned long v)
戻り値: 新たな参照.
C の unsigned long 型から新たな PyLongObject オブジェクト を生成して返します。 失敗のときには NULL を返します。

PyObject* PyLong_FromLongLong( long long v)
戻り値: 新たな参照.
C の long long 型から新たな PyLongObject オブジェクトを 生成して返します。失敗のときには NULL を返します。

PyObject* PyLong_FromUnsignedLongLong( unsigned long long v)
戻り値: 新たな参照.
C の unsigned long long 型から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。

PyObject* PyLong_FromDouble( double v)
戻り値: 新たな参照.
v の整数部から新たな PyLongObject オブジェクトを生成して 返します。失敗のときには NULL を返します。

PyObject* PyLong_FromString( char *str, char **pend, int base)
戻り値: 新たな参照.
str の文字列値に基づいて、新たな PyLongObject を返します。 このとき base を基数として文字列を解釈します。 pend が NULLでなければ、 *pend は str 中で 数が表現されている部分以後の先頭の文字のアドレスを指しています。 base が 0 ならば、str の先頭の文字列に基づいて 基数を決定します: もし str が '0x' または '0X' で始まっていれば、基数に 16 を使います; str が '0' で始まっていれば、基数に 8 を使います; その他の場合には基数に 10 を 使います。base が 0 でなければ、base は 2 以上 36 以下の数でなければなりません。先頭に空白がある場合は 無視されます。数字が全くない場合、ValueError が送出 されます。

PyObject* PyLong_FromUnicode( Py_UNICODE *u, int length, int base)
戻り値: 新たな参照.
Unicode の数字配列を Python の長整数型に変換します。最初のパラメタ u は、 Unicode 文字列の最初の文字を指し、length には 文字数を指定し、base には変換時の基数を指定します。 基数は範囲 [2, 36] になければなりません; 範囲外の基数を指定すると、 ValueError を送出します。 バージョン1.6 以降で新規追加された 仕様です。

PyObject* PyLong_FromVoidPtr( void *p)
戻り値: 新たな参照.

Python 整数型または長整数型をポインタ p から生成します。 ポインタに入れる値は PyLong_AsVoidPtr() を使って 得られるような値です。 バージョン1.5.2 以降で新規追加された 仕様です。

long PyLong_AsLong( PyObject *pylong)
pylong の指す長整数値を、 C の long 型表現で返します。 pylong が LONG_MAXよりも 大きい場合、 OverflowError を送出します。

unsigned long PyLong_AsUnsignedLong( PyObject *pylong)
pylong の指す長整数値を、 C の unsigned long 型表現で返します。 pylong が ULONG_MAXよりも 大きい場合、 OverflowError を送出します。

long long PyLong_AsLongLong( PyObject *pylong)
pylong の指す長整数値を、 C の long long 型表現で返します。 pylong が long long で表せない場合、 OverflowError を送出します。 バージョン2.2 以降で新規追加された 仕様です。

unsigned long long PyLong_AsUnsignedLongLong( PyObject *pylong)
pylong の指す値を、 C の unsigned long long 型表現で 返します。 pylong が unsigned long long で表せない場合、 正の値なら OverflowError を、負の値なら TypeError を送出します。 バージョン2.2 以降で新規追加された 仕様です。

unsigned long PyLong_AsUnsignedLongMask( PyObject *io)
Python 長整数値を、 オーバフローチェックを行わずに C の unsigned long 型表現で返します。 バージョン2.3 以降で新規追加された 仕様です。

unsigned long PyLong_AsUnsignedLongLongMask( PyObject *io)
Python 長整数値を、 オーバフローチェックを行わずに C の unsigned long long 型表現で返します。 バージョン2.3 以降で新規追加された 仕様です。

double PyLong_AsDouble( PyObject *pylong)
pylong の指す値を、 C の double 型表現で返します。 pylong が double を使って近似表現できない場合、 OverflowError 例外を送出して -1.0 を返します。

void* PyLong_AsVoidPtr( PyObject *pylong)
Python の整数型か長整数型を指す pylong を、 C の void ポインタに変換します。pylong を変換できなければ、 OverflowError を送出します。この関数は PyLong_FromVoidPtr() で値を生成するときに使うような void ポインタ型を生成できるだけです。 バージョン1.5.2 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.2.1 (通常)整数型オブジェクト (plain integer Up: 7.2 数値型オブジェクト (numeric object) Next: 7.2.3 浮動小数点型オブジェクト (floating point
Release 2.3.3, documentation updated on December 19, 2003.


7.2.3 浮動小数点型オブジェクト (floating point object)

PyFloatObject
この PyObject のサブタイプは Python 浮動小数点型オブジェクト を表現します。

PyTypeObject PyFloat_Type
この PyTypeObject のインスタンスは Python 浮動小数点型を 表現します。これは types.FloatType と同じオブジェクトです。

int PyFloat_Check( PyObject *p)
引数が PyFloatObject か PyFloatObject のサブタイプのときに真を返します。 バージョン2.2 以降で変更された 仕様: サブタイプを引数にとれるようになりました

int PyFloat_CheckExact( PyObject *p)
引数が PyFloatObject 型で、かつ PyFloatObject 型のサブタイプでないときに真を返します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyFloat_FromString( PyObject *str, char **pend)
str の文字列値をもとに PyFloatObject オブジェクトを生成 します。失敗すると NULL を返します。引数 pend は無視されます。 この引数は後方互換性のためだけに残されています。

PyObject* PyFloat_FromDouble( double v)
戻り値: 新たな参照.
v から PyFloatObject オブジェクトを生成して返します。 失敗すると NULL を返します。

double PyFloat_AsDouble( PyObject *pyfloat)
pyfloat の指す値を、 C の double 型表現で返します。

double PyFloat_AS_DOUBLE( PyObject *pyfloat)
pyfloat の指す値を、 C の double 型表現で返しますが、 エラーチェックを行いません。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.2.2 長整数型オブジェクト (long integer Up: 7.2 数値型オブジェクト (numeric object) Next: 7.2.4 浮動小数点オブジェクト (complex number
Release 2.3.3, documentation updated on December 19, 2003.


7.2.4 浮動小数点オブジェクト (complex number object)

Python の複素数オブジェクトは、 C API 側から見ると二つの別個の 型として実装されています: 一方は Python プログラムに対して公開 されている Python のオブジェクトで、他方は実際の複素数値を 表現する C の構造体です。 API では、これら双方を扱う関数を提供して います。

  • 7.2.4.1 C 構造体としての複素数
  • 7.2.4.2 Python オブジェクトとしての複素数型
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.2.3 浮動小数点型オブジェクト (floating point Up: 7.2 数値型オブジェクト (numeric object) Next: 7.2.4.1 C 構造体としての複素数
Release 2.3.3, documentation updated on December 19, 2003.


7.3 配列オブジェクト (sequence object)

配列オブジェクトに対する一般的な操作については前の章ですでに 述べました; この節では、Python 言語にもともと備わっている 特定の配列オブジェクトについて扱います。

  • 7.3.1 文字列オブジェクト (string object)
  • 7.3.2 Unicode オブジェクト (Unicode object)
    • 7.3.2.1 組み込み codec (built-in codec)
    • 7.3.2.2 メソッドおよびスロット関数 (slot function)
  • 7.3.3 Buffer Objects
  • 7.3.4 タプルオブジェクト (tuple object)
  • 7.3.5 List Objects
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.2.4.2 Python オブジェクトとしての複素数型 Up: 7. 具象オブジェクト (concrete object) Next: 7.3.1 文字列オブジェクト (string object)
Release 2.3.3, documentation updated on December 19, 2003.


7.3.1 文字列オブジェクト (string object)

以下の関数では、文字列が渡されるはずのパラメタに非文字列が渡された 場合に TypeError を送出します。

PyStringObject
この PyObject のサブタイプは Python の文字列オブジェクトを 表現します。

PyTypeObject PyString_Type
この PyTypeObject のインスタンスは Python の文字列型を 表現します; このオブジェクトは Python レイヤにおける types.TypeType と同じです。 .

int PyString_Check( PyObject *o)
o が文字列型か文字列型のサブタイプであるときに真を返します。 バージョン2.2 以降で変更された 仕様: サブタイプを引数にとれるようになりました

int PyString_CheckExact( PyObject *o)
o が文字列型で、かつ文字列型のサブタイプでないときに真を返します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyString_FromString( const char *v)
戻り値: 新たな参照.
v を値に持つ文字列オブジェクトを返します。失敗すると NULL を返します。パラメタ v は NULLであってはなりません; NULLかどうかはチェックしません。

PyObject* PyString_FromStringAndSize( const char *v, int len)
戻り値: 新たな参照.
値が v で長さが len の新たな文字列オブジェクト を返します。失敗すると NULL を返します。v が NULLの場合、文字列の中身は未初期化の状態になります。

PyObject* PyString_FromFormat( const char *format, ...)
戻り値: 新たな参照.
C 関数 printf() 形式の format 文字列と可変個の 引数をとり、書式化済みの文字列長を計算した上で、書式化を行った結果を 値とする Python 文字列にして返します。可変個の引数部は C の データ型でなくてはならず、かつ format 文字列内の書式指定文字 (format character) に一致する型でなくてはなりません。利用できる 書式化文字は以下の通りです:

書式指定文字 | 型 | コメント
%% n/a 文字 % のリテラル。
%c | int | C の整数型で表現される単一の文字。
%d | int | C のprintf("%d") と全く同じ。
%ld | long | C のprintf("%ld") と全く同じ。
%i | int | C のprintf("%i") と全く同じ。
%x | int | C のprintf("%x") と全く同じ。
%s | char* | null で終端された C の文字配列。
%p | void* | C ポインタの 16 進表記。printf("%p") とほとんど同じだが、プラットフォームにおける printf の定義に 関わりなく先頭にリテラル 0x が付きます。

PyObject* PyString_FromFormatV( const char *format, va_list vargs)
戻り値: 新たな参照.
PyString_FromFormat() と同じです。ただし、こちらの関数は 二つしか引数をとりません。

int PyString_Size( PyObject *string)
文字列オブジェクト string 内の文字列値の長さを返します。

int PyString_GET_SIZE( PyObject *string)
PyString_Size() をマクロで実装したもので、 エラーチェックを行いません。

char* PyString_AsString( PyObject *string)
string の中身を NUL 文字終端された表現で返します。 ポインタはstring オブジェクトの内部バッファを指し、 バッファのコピーを指すわけではありません。 PyString_FromStringAndSize(NULL, size) を使って 生成した文字列でない限り、バッファ内のデータはいかなる変更も してはなりません。この文字列をデアロケートしてはなりません。 string が Unicode オブジェクトの場合、この関数は string のデフォルトエンコーディング版を計算し、 デフォルトエンコーディング版に対して操作を行います。 string が文字列オブジェクトですらない場合、 PyString_AsString() は NULL を返して TypeError を送出します。

char* PyString_AS_STRING( PyObject *string)
PyString_AsString() をマクロで実装したもので、 エラーチェックを行いません。文字列オブジェクトだけをサポート します; Unicode オブジェクトを渡してはなりません。

int PyString_AsStringAndSize( PyObject *obj, char **buffer, int *length)
obj の中身を NUL 文字終端された表現にして、出力用の変数 buffer と length を使って返します。

この関数は文字列オブジェクトと Unicode オブジェクトのどちらも 入力として受理します。 Unicode オブジェクトの場合、オブジェクトを デフォルトエンコーディングでエンコードしたバージョン (default encoded version) を返します。length が NULLの 場合、値を返させるバッファには NUL 文字を入れてはなりません; NUL 文字が入っている場合、関数は -1 を返し、 TypeError を送出します。

buffer は obj の内部文字列バッファを参照し、 バッファのコピーを参照するわけではありません。 PyString_FromStringAndSize(NULL, size) を使って 生成した文字列でない限り、バッファ内のデータはいかなる変更も してはなりません。この文字列をデアロケートしてはなりません。

string が Unicode オブジェクトの場合、この関数は string のデフォルトエンコーディング版を計算し、 デフォルトエンコーディング版に対して操作を行います。 string が文字列オブジェクトですらない場合、 PyString_AsStringAnsSize() は NULL を返して TypeError を送出します。

void PyString_Concat( PyObject **string, PyObject *newpart)
新しい文字列オブジェクトを *string に作成し、 newpart の内容を string に追加します; 呼び出し側は新たな参照を所有 することになります。string の以前の値に対する参照は盗み取られ ます。新たな文字列を生成できなければ、string に対する古い参照は 無視され、 *string の値は NULLに設定されます; その際、 適切な例外情報が設定されます。

void PyString_ConcatAndDel( PyObject **string, PyObject *newpart)
新しい文字列オブジェクトを *string に作成し、 newpart の内容を string に追加します。こちらのバージョンの関数は newpart への参照をデクリメントします。

int _PyString_Resize( PyObject **string, int newsize)
``変更不能'' である文字列オブジェクトをサイズ変更する手段です。 新たな文字列オブジェクトを作成するときにのみ使用してください; 文字列がすでにコードの他の部分で使われているかもしれない場合には、 この関数を使ってはなりません。入力する文字列オブジェクトの参照カウント が 1 でない場合、この関数を呼び出すとエラーになります。 左側値には、既存の文字列オブジェクトのアドレスを渡し (このアドレスには 書き込み操作が起きるかもしれません)、新たなサイズを指定します。 成功した場合、 *string はサイズ変更された文字列オブジェクトを 保持し、0 が返されます; *string の値は、入力したときの 値と異なっているかもしれません。文字列の再アロケーションに失敗した場合、 *string に入っていた元の文字列オブジェクトを解放し、 *string を NULL にセットし、メモリ例外をセットし、 -1 を返します。

PyObject* PyString_Format( PyObject *format, PyObject *args)
戻り値: 新たな参照.
新たな文字列オブジェクトを format と args から生成します。 format % args と似た働きです。引数 args はタプルでなければなりません。

void PyString_InternInPlace( PyObject **string)
引数 *string をインプレースで隔離 (intern) します。 引数は Python 文字列オブジェクトを指すポインタへのアドレスで なくてはなりません。*string と等しい、すでに隔離済みの 文字列が存在する場合、そのオブジェクトを *string に 設定します (かつ、元の文字列オブジェクトの参照カウントをデクリメントし、 すでに隔離済みの文字列オブジェクトの参照カウントをインクリメントします)。 (補足: 参照カウントについては沢山説明して来ましtが、この関数は 参照カウント中立 (reference-count-neutral) と考えてください; この関数では、関数の呼び出し後にオブジェクトに対して参照の所有権を 持てるのは、関数を呼び出す前にすでに所有権を持っていた場合に限ります。)

PyObject* PyString_InternFromString( const char *v)
戻り値: 新たな参照.
PyString_FromString() と PyString_InternInPlace() を組み合わせたもので、 隔離済みの新たな文字列オブジェクトを返すか、同じ値を持つすでに 隔離済みの文字列オブジェクトに対する新たな (``所有権を得た'') 参照 を返します。

PyObject* PyString_Decode( const char *s, int size, const char *encoding, const char *errors)
戻り値: 新たな参照.
size からなるエンコード済みのバッファ s を encoding の名前で登録されている codec に 渡してデコードし、オブジェクトを生成します。 encoding および errors は 組み込み関数 unicode() に与える同名のパラメタと 同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。

PyObject* PyString_AsDecodedObject( PyObject *str, const char *encoding, const char *errors)
戻り値: 新たな参照.
文字列オブジェクトをencoding の名前で登録されている codec に 渡してデコードし、Python オブジェクトを返します。 encoding および errors は 文字列型の encode() メソッドに与える同名のパラメタと 同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。

PyObject* PyString_Encode( const char *s, int size, const char *encoding, const char *errors)
戻り値: 新たな参照.
size で指定されたサイズの char バッファを encoding の名前で登録されている codec に渡してエンコードし、 Python オブジェクトを返します。encoding および errors は 文字列型の encode() メソッドに与える同名のパラメタと 同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。

PyObject* PyString_AsEncodedObject( PyObject *str, const char *encoding, const char *errors)
戻り値: 新たな参照.
エンコード名 encoding で登録された codec を使って 文字列オブジェクトをエンコードし、その結果を Python オブジェクト として返します。encoding および errors は 文字列型の encode() メソッドに与える同名のパラメタと 同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.3 配列オブジェクト (sequence object) Up: 7.3 配列オブジェクト (sequence object) Next: 7.3.2 Unicode オブジェクト (Unicode
Release 2.3.3, documentation updated on December 19, 2003.


7.3.2 Unicode オブジェクト (Unicode object)

以下は Python の Unicode 実装に用いられている基本 Unicode オブジェクト型です:

Py_UNICODE
この型は 16 ビットの符号なしストレージ型を表し、Unicode 序数 (Unicode ordinal) を保持するための基礎単位として Python が内部的 に使います。wchar_t が利用でき、かつ 16 ビットである場合、 Py_UNICODE は wchar_t を typedef でエイリアスされ、 ネイティブプラットフォームに対する互換性を高めます。その他の プラットフォームでは全て、Py_UNICODE は unsigned short の typedef によるエイリアスになります。

PyUnicodeObject
この PyObject のサブタイプは Unicode オブジェクトを表現します。

PyTypeObject PyUnicode_Type
この PyTypeObject のインスタンスは Python の Unicode 型を 表現します。

以下の API は実際には C マクロで、Unicode オブジェクト内部の 読み出し専用データに対するチェックやアクセスを高速に行います:

int PyUnicode_Check( PyObject *o)
o が Unicode 文字列型か Unicode 文字列型のサブタイプで あるときに真を返します。 バージョン2.2 以降で変更された 仕様: サブタイプを引数にとれるようになりました

int PyUnicode_CheckExact( PyObject *o)
o が Unicode 文字列型で、かつ Unicode 文字列型のサブタイプで ないときに真を返します。 バージョン2.2 以降で新規追加された 仕様です。

int PyUnicode_GET_SIZE( PyObject *o)
オブジェクトのサイズを返します。 o は PyUnicodeObject でなければなりません (チェックはしません)。

int PyUnicode_GET_DATA_SIZE( PyObject *o)
オブジェクトの内部バッファのサイズをバイト数で返します。 o は PyUnicodeObject でなければなりません (チェックはしません)。

Py_UNICODE* PyUnicode_AS_UNICODE( PyObject *o)
オブジェクト内部のPy_UNICODE バッファへのポインタを返します。 o は PyUnicodeObject でなければなりません (チェックは しません)。

const char* PyUnicode_AS_DATA( PyObject *o)
オブジェクト内部バッファへのポインタを返します。 o は PyUnicodeObject でなければなりません (チェックはしません)。

Unicode は数多くの異なる文字プロパティ (character property) を提供しています。よく使われる文字プロパティは、以下のマクロ で利用できます。これらのマクロは Python の設定に応じて、 各々 C の関数に対応付けられています。

int Py_UNICODE_ISSPACE( Py_UNICODE ch)
ch が空白文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISLOWER( Py_UNICODE ch)
ch が小文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISUPPER( Py_UNICODE ch)
ch が大文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISTITLE( Py_UNICODE ch)
ch がタイトルケース文字 (titlecase character) かどうかに 応じて 1 または 0 を返します。

int Py_UNICODE_ISLINEBREAK( Py_UNICODE ch)
ch が改行文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISDECIMAL( Py_UNICODE ch)
ch が 10 進の数字文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISDIGIT( Py_UNICODE ch)
ch が 2 進の数字文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISNUMERIC( Py_UNICODE ch)
ch が数字文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISALPHA( Py_UNICODE ch)
ch がアルファベット文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISALNUM( Py_UNICODE ch)
ch が英数文字かどうかに応じて 1 または 0 を返します。

以下の API は、高速に直接文字変換を行うために使われます:

Py_UNICODE Py_UNICODE_TOLOWER( Py_UNICODE ch)
ch を小文字に変換したものを返します。

Py_UNICODE Py_UNICODE_TOUPPER( Py_UNICODE ch)
ch を大文字に変換したものを返します。

Py_UNICODE Py_UNICODE_TOTITLE( Py_UNICODE ch)
ch をタイトルケース文字に変換したものを返します。

int Py_UNICODE_TODECIMAL( Py_UNICODE ch)
ch を 10 進の正の整数に変換したものを返します。 不可能ならば -1 を返します。例外を送出しません。

int Py_UNICODE_TODIGIT( Py_UNICODE ch)
ch を一桁の 2 進整数に変換したものを返します。 不可能ならば -1 を返します。例外を送出しません。

double Py_UNICODE_TONUMERIC( Py_UNICODE ch)
ch を (正の) double に変換したものを返します。 不可能ならば -1.0 を返します。例外を送出しません。

Unicode オブジェクトを生成したり、Unicode の配列としての基本的な プロパティにアクセスしたりするには、以下の API を使ってください:

PyObject* PyUnicode_FromUnicode( const Py_UNICODE *u, int size)
戻り値: 新たな参照.
size で指定された長さを持つ Py_UNICODE 型バッファ u から Unicode オブジェクトを生成します。u を NULL にしても よく、その場合オブジェクトの内容は未定義です。バッファに必要な情報を 埋めるのはユーザの責任です。バッファの内容は新たなオブジェクトに コピーされます。バッファが NULLでない場合、戻り値は共有された オブジェクトになることがあります。従って、この関数が返す Unicode オブジェクトを変更してよいのは u が NULLのときだけです。

Py_UNICODE* PyUnicode_AsUnicode( PyObject *unicode)
Unicode オブジェクトの内部バッファ Py_UNICODE に対する読み出し 専用のポインタを返します。unicode が Unicode オブジェクトで なければ NULL を返します。

int PyUnicode_GetSize( PyObject *unicode)
Unicode オブジェクトの長さを返します。

PyObject* PyUnicode_FromEncodedObject( PyObject *obj, const char *encoding, const char *errors)
戻り値: 新たな参照.
あるエンコード方式でエンコードされたオブジェクト obj を Unicode オブジェクトに型強制して、参照カウントをインクリメントして 返します。

型強制は以下のようにして行われます:

  1. obj が Unicode オブジェクトの場合、オブジェクトそのままを、 参照カウントをインクリメントして返します。注意: Unicode オブジェクトは デコードできません; encoding に NULL でない値を渡すと、 TypeError になります。

  2. 文字列やその他の char バッファ互換オブジェクトの場合、オブジェクト は encoding に従ってデコードされます。このとき error で 定義されたエラー処理を用います。これら二つの引数は NULL にでき、 その場合デフォルト値が使われます (詳細は次の節を参照してください)

  3. その他のオブジェクトは例外を引き起こします。

この API は、エラーが生じたときには NULL を返します。 呼び出し側は返されたオブジェクトを decref する責任があります。

PyObject* PyUnicode_FromObject( PyObject *obj)
戻り値: 新たな参照.
PyUnicode_FromEncodedObject(obj, NULL, "strict") を行うショートカットで、インタプリタは Unicode への型強制が必要な 際に常にこの関数を使います。

プラットフォームで wchar_t がサポートされていて、かつ wchar.h が提供されている場合、Python は以下の関数を使って wchar_t に対するインタフェースを確立することがあります。 このサポートは、Python 自体の Py_UNICODE 型がシステムの wchar_t と同一の場合に最適化をもたらします。

PyObject* PyUnicode_FromWideChar( const wchar_t *w, int size)
戻り値: 新たな参照.
size の wchar_t バッファ w から Unicode オブジェクト を生成します。失敗すると NULL を返します。

int PyUnicode_AsWideChar( PyUnicodeObject *unicode, wchar_t *w, int size)
Unicode オブジェクトの内容を wchar_t バッファ w にコピーします。最大で size 個の wchar_t 文字を コピーします。コピーされたwchar_t 文字の個数を返します。 エラーの時には -1 を返します。

  • 7.3.2.1 組み込み codec (built-in codec)
  • 7.3.2.2 メソッドおよびスロット関数 (slot function)
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.3.1 文字列オブジェクト (string object) Up: 7.3 配列オブジェクト (sequence object) Next: 7.3.2.1 組み込み codec (built-in
Release 2.3.3, documentation updated on December 19, 2003.


7.3.3 Buffer Objects

C で実装された Python オブジェクトは、``バッファインタフェース (bufferinterface)'' と呼ばれる一連の 関数を公開していることがあります。これらの関数は、あるオブジェクトの データを生 (raw) のバイト列形式で公開するために使います。 このオブジェクトの使い手は、バッファインタフェースを使うことで、 オブジェクトをあらかじめコピーしておく必要なしに、オブジェクトの データに直接アクセスできます。

バッファインタフェースをサポートするオブジェクトの例として、 文字列型とアレイ (array) 型の二つがあります。文字列オブジェクトは、 その内容をバッファインタフェースのバイト単位形式で公開して います。アレイもその内容を公開していますが、注意する必要が あるのはアレイの要素は複数バイトの値になりうる、ということです。

バッファインタフェースの使い手の一例として、ファイルオブジェクトの write() メソッドがあります。バッファインタフェースを 介してバイト列を公開しているオブジェクトは全て、ファイルへの書き出し ができます。オブジェクトのバッファインタフェースを操作し、 対象となるオブジェクトからデータを返させる PyArg_ParseTuple() には数多くのデータ書式化コードが あります。

バッファインタフェースに関するより詳しい情報は、 ``バッファオブジェクト構造体'' 節 ( 10.7 節) の、 PyBufferProcsの説明のところに あります。

``バッファオブジェクト'' はヘッダファイル bufferobject.h の中で定義されています (このファイルは Python.h がインクルード しています)。 バッファオブジェクトは、 Python プログラミングの レベルからは文字列オブジェクトと非常によく似ているように見えます: スライス、インデクス指定、結合、その他標準の文字列操作をサポート しています。しかし、バッファオブジェクトのデータは二つのデータソース: 何らかのメモリブロックか、バッファインタフェースを公開している 別のオブジェクト、のいずれかに由来しています。

バッファオブジェクトは、他のオブジェクトのバッファインタフェースから Python プログラマにデータを公開する方法として便利です。 バッファオブジェクトはゼロコピーなスライス機構 (zero-copy slicing mechanism) としても使われます。ブロックメモリを参照するという バッファオブジェクトの機能を使うことで、任意のデータをきわめて簡単に Python プログラマに公開できます。メモリブロックは巨大でも かまいませんし、C 拡張モジュール内の定数配列でもかまいません。 また、オペレーティングシステムライブラリ側に渡す前の、 操作用の生のブロックメモリでもかまいませんし、 構造化されたデータをネイティブのメモリ配置形式でやりとりするため にも使えます。

PyBufferObject
この PyObject のサブタイプはバッファオブジェクトを表現します。

PyTypeObject PyBuffer_Type
Python バッファ型 (buffer type) を表現するPyTypeObject です; Python レイヤにおける types.BufferType と同じオブジェクト です 。

int Py_END_OF_BUFFER
この定数は、PyBuffer_FromObject() または の PyBuffer_FromReadWriteObject() size パラメタに 渡します。 このパラメタを渡すと、PyBufferObject は指定された offset からバッファの終わりまでを base オブジェクトとして参照します。 このパラメタを使うことで、関数の呼び出し側が base オブジェクト のサイズを調べる必要がなくなります。

int PyBuffer_Check( PyObject *p)
引数がPyBuffer_Type 型のときに真を返します。

PyObject* PyBuffer_FromObject( PyObject *base, int offset, int size)
戻り値: 新たな参照.
新たな読み出し専用バッファオブジェクトを返します。base が 読み出し専用バッファに必要なバッファプロトコルをサポートしていない 場合や、厳密に一つのバッファセグメントを提供していない場合には TypeError を送出し、offset がゼロ以下の場合には ValueError を送出します。 バッファオブジェクトはは base オブジェクトに対する参照を保持し、 バッファオブジェクトのの内容は base オブジェクトの offset から size バイトのバッファインタフェースへの参照になります。 size が Py_END_OF_BUFFER の場合、新たに作成する バッファオブジェクトの内容は base から公開されているバッファの 末尾までにわたります。

PyObject* PyBuffer_FromReadWriteObject( PyObject *base, int offset, int size)
戻り値: 新たな参照.
新たな書き込み可能バッファオブジェクトを返します。パラメタおよび例外 は PyBuffer_FromObject と同じです。base オブジェクト が書き込み可能バッファに必要なバッファプロトコルを公開していない 場合、TypeError を送出します。

PyObject* PyBuffer_FromMemory( void *ptr, int size)
戻り値: 新たな参照.
メモリ上の指定された場所から指定されたサイズのデータを読み出せる、 新たな読み出し専用バッファオブジェクトを返します。 この関数が返すバッファオブジェクトが存続する間、ptr で与え られたメモリバッファがデアロケートされないようにするのは呼び出し側の 責任です。size がゼロ以下の場合にはValueError を 送出します。size には Py_END_OF_BUFFER を指定しては なりません; 指定すると、ValueError を送出します。

PyObject* PyBuffer_FromReadWriteMemory( void *ptr, int size)
戻り値: 新たな参照.
PyBuffer_FromMemory() に似ていますが、書き込み可能な バッファを返します。

PyObject* PyBuffer_New( int size)
戻り値: 新たな参照.
size バイトのメモリバッファを独自に維持する新たな書き込み可能 バッファオブジェクトを返します。 size がゼロまたは正の値でない場合、ValueError を 送出します。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.3.2.2 メソッドおよびスロット関数 (slot function) Up: 7.3 配列オブジェクト (sequence object) Next: 7.3.4 タプルオブジェクト (tuple object)
Release 2.3.3, documentation updated on December 19, 2003.


7.3.4 タプルオブジェクト (tuple object)

PyTupleObject
この PyObject のサブタイプは Python のタプルオブジェクトを 表現します。

PyTypeObject PyTuple_Type
この PyTypeObject のインスタンスは Python のタプル型を 表現します; Python レイヤにおける types.TupleType と同じオブジェクトです。

int PyTuple_Check( PyObject *p)
p がタプルオブジェクトか、タプル型のサブタイプのインスタンス である場合に真を返します。 バージョン2.2 以降で変更された 仕様: サブタイプを引数にとれるようになりました

int PyTuple_CheckExact( PyObject *p)
p がタプルオブジェクトで、かつタプル型のサブタイプのインスタンス でない場合に真を返します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyTuple_New( int len)
戻り値: 新たな参照.
サイズが len 新たなタプルオブジェクトを返します。 失敗すると NULL を返します。

int PyTuple_Size( PyObject *p)
タプルオブジェクトへのポインタを引数にとり、そのタプルのサイズを 返します。

int PyTuple_GET_SIZE( PyObject *p)
タプル p のサイズを返しますが、p は非 NULL でなくては ならず、タプルオブジェクトを指していなければなりません; エラーチェックを行いません。

PyObject* PyTuple_GetItem( PyObject *p, int pos)
戻り値: 借りた参照.
p の指すタプルオブジェクト内の、位置 pos にあるオブジェクト を返します。 pos が範囲を超えている場合、 NULL を返して IndexError 例外をセットします。

PyObject* PyTuple_GET_ITEM( PyObject *p, int pos)
戻り値: 借りた参照.
PyTuple_GetItem() に似ていますが、引数に対する エラーチェックを行いません。

PyObject* PyTuple_GetSlice( PyObject *p, int low, int high)
戻り値: 新たな参照.
p の指すタプルオブジェクト内の、位置 low から high までのスライスを取り出して、タプルオブジェクトとして 返します。

int PyTuple_SetItem( PyObject *p, int pos, PyObject *o)
p の指すタプルオブジェクト内の位置 pos に、 オブジェクト o への参照を挿入します。成功した場合には 0 を返します。 注意: この関数は o への参照を ``盗み取り'' ます。

void PyTuple_SET_ITEM( PyObject *p, int pos, PyObject *o)
PyTuple_SetItem() に似ていますが、エラーチェックを 行わず、新たなタプルに値を入れるとき 以外には使ってはなりません。 注意: この関数は o への参照を ``盗み取り'' ます。

int _PyTuple_Resize( PyObject **p, int newsize)
タプルをリサイズする際に使えます。newsize はタプルの新たな 長さです。タプルは変更不能なオブジェクト ということになっている ので、この関数は対象のオブジェクトに対してただ一つしか参照がない時 以外には使ってはなりません。タプルがコード中の他の部分ですでに参照 されている場合には、この関数を 使ってはなりません。 タプルは常に指定サイズの末尾まで伸縮します。 成功した場合には 0 を返します。 クライアントコードは、*p の値が呼び出し前と同じに なると気体してはなりません。 *p が置き換えられた場合、オリジナルの *p は破壊されます。失敗すると -1 を返し、 *p を NULLに設定して、 MemoryError または SystemError を送出します。 バージョン2.2 以降で変更された 仕様: 使われていなかった三つ目のパラメタ、 last_is_sticky を削除しました

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.3.3 Buffer Objects Up: 7.3 配列オブジェクト (sequence object) Next: 7.3.5 List Objects
Release 2.3.3, documentation updated on December 19, 2003.


7.3.5 List Objects

PyListObject
この PyObject のサブタイプは Python のリストオブジェクトを 表現します。

PyTypeObject PyList_Type
この PyTypeObject のインスタンスは Python のタプル型を 表現します。これは Python レイヤにおけるtypes.ListType と 同じオブジェクトです。

int PyList_Check( PyObject *p)
引数が PyListObject である場合に真を返します。

PyObject* PyList_New( int len)
戻り値: 新たな参照.
サイズが len 新たなリストオブジェクトを返します。 失敗すると NULL を返します。

int PyList_Size( PyObject *list)
リストオブジェクトlist の長さを返します; リストオブジェクトにおける "len(list)" と同じです。

int PyList_GET_SIZE( PyObject *list)
マクロ形式でできた PyList_Size() で、エラーチェックを しません。

PyObject* PyList_GetItem( PyObject *list, int index)
戻り値: 借りた参照.
p の指すリストオブジェクト内の、位置 pos にあるオブジェクト を返します。 pos が範囲を超えている場合、 NULL を返して IndexError 例外をセットします。

PyObject* PyList_GET_ITEM( PyObject *list, int i)
戻り値: 借りた参照.
マクロ形式でできた PyList_GetItem() で、エラーチェックを しません。

int PyList_SetItem( PyObject *list, int index, PyObject *item)
リストオブジェクト内の位置 index に、オブジェクト item を挿入します。成功した場合には0 を返し、失敗すると -1 を返します。 注意: この関数は item への参照を ``盗み取り'' ます。また、 変更先のインデクスにすでに別の要素が入っている場合、その 要素に対する参照を放棄します。

void PyList_SET_ITEM( PyObject *list, int i, PyObject *o)
PyList_SetItem() をマクロによる実装で、エラーチェック を行いません。この関数は、新たなリストのまだ要素を入れたことのない 位置に要素を入れるときにのみ使います。 注意: この関数は item への参照を ``盗み取り'' ます。また、 PyList_SetItem() と違って、要素の置き換えが生じても 置き換えられるオブジェクトへの参照を放棄 しません; その結果、 list 中の位置 i で参照されていたオブジェクト がメモリリークを引き起こします。

int PyList_Insert( PyObject *list, int index, PyObject *item)
要素 item をインデクス index の前に挿入します。 成功すると 0 を返します。失敗すると -1 を返し、 例外を送出します。 list.insert(index, item) に類似した 機能です。

int PyList_Append( PyObject *list, PyObject *item)
オブジェクト item を list の末尾に追加します。 成功すると 0 を返します; 失敗すると -1 を返し、 例外をセットします。list.append(item) に類似した機能です。

PyObject* PyList_GetSlice( PyObject *list, int low, int high)
戻り値: 新たな参照.
list 内の、low から high の 間の オブジェクト からなるリストを返します。失敗すると NULL を返し、 例外をセットします。 list[low:high] に類似した機能です。

int PyList_SetSlice( PyObject *list, int low, int high, PyObject *itemlist)
list 内の、low から high の間のオブジェクトを、 itemlist の内容にします。 list[low:high] = itemlist と類似の機能です。itemlist は NULL でもよく、空リストの 代入 (指定スライスの削除) になります。 成功した場合には 0 を、失敗した場合には -1 を返します。

int PyList_Sort( PyObject *list)
list の内容をインプレースでソートします。成功した場合には 0 を、失敗した場合には -1 を返します。 success, -1 on failure. "list.sort()" と同じです。

int PyList_Reverse( PyObject *list)
list の要素をインプレースで反転します。成功した場合には 0 を、失敗した場合には -1 を返します。 "list.reverse()" と同じです。

PyObject* PyList_AsTuple( PyObject *list)
戻り値: 新たな参照.
list の内容が入った新たなタプルオブジェクトを返します; "tuple(list)". と同じです。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.3.4 タプルオブジェクト (tuple object) Up: 7.3 配列オブジェクト (sequence object) Next: 7.4 マップ型オブジェクト (mapping object)
Release 2.3.3, documentation updated on December 19, 2003.


7.4 マップ型オブジェクト (mapping object)

  • 7.4.1 辞書オブジェクト (dictionary object)
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.3.5 List Objects Up: 7. 具象オブジェクト (concrete object) Next: 7.4.1 辞書オブジェクト (dictionary object)
Release 2.3.3, documentation updated on December 19, 2003.


7.4.1 辞書オブジェクト (dictionary object)

PyDictObject
この PyObject のサブタイプは Python の辞書オブジェクト を表現します。

PyTypeObject PyDict_Type
この PyTypeObject のインスタンスは Python の辞書を表現します。 このオブジェクトは、Python プログラムには types.DictType および types.DictionaryType として公開されています。

int PyDict_Check( PyObject *p)
引数が PyDictObject のときに真を返します。

PyObject* PyDict_New( )
戻り値: 新たな参照.
新たな空の辞書を返します。失敗すると NULL を返します。

PyObject* PyDictProxy_New( PyObject *dict)
戻り値: 新たな参照.
あるマップ型オブジェクトに対して、読み出し専用に制限されたプロキシ オブジェクト (proxy object) を返します。通常、この関数は 動的でないクラス型 (non-dynamic class type) のクラス辞書を 変更させないためにプロキシを作成するために使われます。 バージョン2.2 以降で新規追加された 仕様です。

void PyDict_Clear( PyObject *p)
現在辞書に入っている全てのキーと値のペアを除去して空にします。

PyObject* PyDict_Copy( PyObject *p)
戻り値: 新たな参照.
p と同じキーと値のペアが入った新たな辞書を返します。 バージョン1.6 以降で新規追加された 仕様です。

int PyDict_SetItem( PyObject *p, PyObject *key, PyObject *val)
辞書 p に、 key をキーとして値 value を 挿入します。 key はハッシュ可能でなければなりません; ハッシュ可能でない場合、 TypeError を送出します。 成功した場合には 0 を、失敗した場合には -1 を返します。

int PyDict_SetItemString( PyObject *p, char *key, PyObject *val)
辞書 p に、 key をキーとして値 value を 挿入します。 key は char* 型でなければなりません。 キーオブジェクトはPyString_FromString(key) で生成 されます。 成功した場合には 0 を、失敗した場合には -1 を返します。

int PyDict_DelItem( PyObject *p, PyObject *key)
辞書 p から key をキーとするエントリを除去します。 key はハッシュ可能でなければなりません; ハッシュ可能でない場合、 TypeError を送出します。 成功した場合には 0 を、失敗した場合には -1 を返します。

int PyDict_DelItemString( PyObject *p, char *key)
辞書 p から文字列 key をキーとするエントリを除去します。 成功した場合には 0 を、失敗した場合には -1 を返します。

PyObject* PyDict_GetItem( PyObject *p, PyObject *key)
戻り値: 借りた参照.
辞書p 内で key をキーとするオブジェクトを返します。 キー key が存在しない場合には NULL を返しますが、例外を セット しません。

PyObject* PyDict_GetItemString( PyObject *p, char *key)
戻り値: 借りた参照.
PyDict_GetItem() と同じですが、key は PyObject* ではなく char* で指定します。

PyObject* PyDict_Items( PyObject *p)
戻り値: 新たな参照.
辞書オブジェクトのメソッド item() のように、 辞書内の全ての要素対が入った PyListObject を返します。 (items() については Python ライブラリリファレンス を 参照してください。)

PyObject* PyDict_Keys( PyObject *p)
戻り値: 新たな参照.
辞書オブジェクトのメソッド keys() のように、 辞書内の全てのキーが入った PyListObject を返します。 (keys() については Python ライブラリリファレンス を 参照してください。)

PyObject* PyDict_Values( PyObject *p)
戻り値: 新たな参照.
辞書オブジェクトのメソッド values() のように、 辞書内の全ての値が入った PyListObject を返します。 (values() については Python ライブラリリファレンス を 参照してください。)

int PyDict_Size( PyObject *p)
辞書内の要素の数を返します。辞書に対して "len(p)" を 実行するのと同じです。

int PyDict_Next( PyObject *p, int *ppos, PyObject **pkey, PyObject **pvalue)
辞書 p 内の全てのキー/値のペアにわたる反復処理を行います。 ppos が参照している int 型は、この関数で反復処理 を開始する際に、最初に関数を呼び出すよりも前に 0 に 初期化しておかなければなりません; この関数は辞書内の各ペアを 取り上げるごとに真を返し、全てのペアを取り上げたことが分かると 偽を返します。パラメタ pkey および pvalue には、 それぞれ辞書の各々のキーと値を指すポインタか、または NULL が入ります。この関数から返される参照はすべて借りた参照になります。

以下に例を示します:

PyObject *key, *value;
int pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    /* 取り出した値で何らかの処理を行う... */
    ...
}

反復処理中に辞書 p を変更してはなりません。 (Python 2.1 からは) 辞書を反復処理する際に、キーに対応する値を 変更しても大丈夫になりましたが、キーの集合を変更しないことが 前提です。以下に例を示します:

PyObject *key, *value;
int pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    int i = PyInt_AS_LONG(value) + 1;
    PyObject *o = PyInt_FromLong(i);
    if (o == NULL)
        return -1;
    if (PyDict_SetItem(self->dict, key, o) < 0) {
        Py_DECREF(o);
        return -1;
    }
    Py_DECREF(o);
}

int PyDict_Merge( PyObject *a, PyObject *b, int override)
マップ型オブジェクト b の全ての要素にわたって、反復的に キー/値のペアを辞書 a に追加します。 b は辞書か、PyMapping_Keys() または PyObject_GetItem() をサポートする何らかのオブジェクト にできます。 override が真ならば、a のキーと一致するキーが b にある際に、既存のペアを置き換えます。それ以外の場合は、b のキーに一致するキーが a にないときのみ追加を行います。 成功した場合には 0 を返し、例外が送出された場合には -1 を返します。 バージョン2.2 以降で新規追加された 仕様です。

int PyDict_Update( PyObject *a, PyObject *b)
C で表せば PyDict_Merge(a, b, 1) と同じ、 Python で表せばa.update(b) と同じです。 成功した場合には 0 を返し、例外が送出された場合には -1 を返します。 バージョン2.2 以降で新規追加された 仕様です。

int PyDict_MergeFromSeq2( PyObject *a, PyObject *seq2, int override)
seq2 内のキー/値ペアを使って、辞書a の内容を更新したり 統合したりします。seq2 は、キー/値のペアとみなせる長さ 2 の 反復可能オブジェクト(iterable object) を生成する反復可能オブジェクトで なければなりません。重複するキーが存在する場合、override が 真ならば先に出現したキーを使い、そうでない場合は後に出現したキーを 使います。 成功した場合には 0 を返し、例外が送出された場合には -1 を返します。

(戻り値以外は) 等価な Python コードを書くと、以下のようになります:

def PyDict_MergeFromSeq2(a, seq2, override):
    for key, value in seq2:
        if override or key not in a:
            a[key] = value

バージョン2.2 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.4 マップ型オブジェクト (mapping object) Up: 7.4 マップ型オブジェクト (mapping object) Next: 7.5 その他のオブジェクト
Release 2.3.3, documentation updated on December 19, 2003.


7.5 その他のオブジェクト

  • 7.5.1 ファイルオブジェクト (file object)
  • 7.5.2 インスタンスオブジェクト (instance object)
  • 7.5.3 メソッドオブジェクト (method object)
  • 7.5.4 モジュールオブジェクト (module object)
  • 7.5.5 イテレータオブジェクト (iterator object)
  • 7.5.6 デスクリプタオブジェクト (descriptor object)
  • 7.5.7 スライスオブジェクト (slice object)
  • 7.5.8 弱参照オブジェクト (weak reference object)
  • 7.5.9 Cオブジェクト (CObject)
  • 7.5.10 セルオブジェクト (cell object)
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.4.1 辞書オブジェクト (dictionary object) Up: 7. 具象オブジェクト (concrete object) Next: 7.5.1 ファイルオブジェクト (file object)
Release 2.3.3, documentation updated on December 19, 2003.


7.5.1 ファイルオブジェクト (file object)

Python の組み込みファイルオブジェクトは、全て標準 C ライブラリの FILE* サポートの上に実装されています。以下の詳細説明は 一実装に関するもので、将来の Python のリリースで変更されるかも しれません。

PyFileObject
この PyObject のサブタイプは Python のファイル型オブジェクトを 表現します。

PyTypeObject PyFile_Type
この PyTypeObject のインスタンスは Python のファイル型を 表現します。このオブジェクトは types.FileType として Python プログラムで公開されています。

int PyFile_Check( PyObject *p)
引数が PyFileObject か PyFileObject のサブタイプのときに真を返します。 バージョン2.2 以降で変更された 仕様: サブタイプを引数にとれるようになりました

int PyFile_CheckExact( PyObject *p)
引数が PyFileObject 型で、かつ PyFileObject 型のサブタイプでないときに真を返します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyFile_FromString( char *filename, char *mode)
戻り値: 新たな参照.
成功すると、filename に指定した名前のファイルを mode に 指定したファイルモードで開いて得た新たなファイルオブジェクトを返します。 mode のセマンティクスは標準 C ルーチン fopen()と同じです。失敗するとNULLを返します。

PyObject* PyFile_FromFile( FILE *fp, char *name, char *mode, int (*close)(FILE*))
戻り値: 新たな参照.
すでに開かれている標準 C ファイルポインタ fp から 新たな PyFileObject を生成します。この関数で生成した ファイルオブジェクトは、閉じる際にclose に指定した関数を 呼び出します。失敗するとNULLを返します。

FILE* PyFile_AsFile( PyFileObject *p)
p に関連付けられたファイルオブジェクトを FILE* で返します。

PyObject* PyFile_GetLine( PyObject *p, int n)
戻り値: 新たな参照.
p.readline([n]) と同じで、この関数は オブジェクト p の各行を読み出します。 p は ファイルオブジェクトか、readline() メソッドを持つ 何らかのオブジェクトでかまいません。n が 0 の場合、 行の長さに関係なく正確に 1 行だけ読み出します。n が 0 より大きければ、n バイト以上のデータは 読み出しません; 従って、行の一部だけが返される場合があります。 どちらの場合でも、読み出し後すぐにファイルの終端に到達した場合には 空文字列を返します。n が 0 より小さければ、長さに 関わらず 1 行だけを読み出しますが、すぐにファイルの終端に到達した 場合には EOFError を送出します。

PyObject* PyFile_Name( PyObject *p)
戻り値: 借りた参照.
p に指定したファイルの名前を文字列オブジェクトで 返します。

void PyFile_SetBufSize( PyFileObject *p, int n)
setvbuf()があるシステムでのみ 利用できます。この関数を呼び出してよいのはファイルオブジェクトの 生成直後のみです。

int PyFile_Encoding( PyFileObject *p, char *enc)
Unicode オブジェクトをファイルに出力するときにのエンコード方式を enc にします。成功すると 1 を、失敗すると 0 を返します。 バージョン2.3 以降で新規追加された 仕様です。

int PyFile_SoftSpace( PyObject *p, int newflag)
この関数はインタプリタの内部的な利用のために存在します。 この関数はp の softspace 属性を newflag に 設定し、以前の設定値を返します。この関数を正しく動作させるために、 p がファイルオブジェクトである必然性はありません; 任意の オブジェクトをサポートします (softspace 属性が設定 されているかどうかのみが問題だと思ってください)。 この関数は全てのエラーを解消し、属性値が存在しない場合や属性値を 取得する際にエラーが生じると、0 を以前の値として返します。 この関数からはエラーを検出できませんが、そもそもそういう必要は ありません。

int PyFile_WriteObject( PyObject *obj, PyFileObject *p, int flags)
オブジェクト obj をファイルオブジェクト p に書き込みます。 flag がサポートするフラグは Py_PRINT_RAWだけです; このフラグ を指定すると、 オブジェクトにrepr() ではなく str() を適用した結果をファイルに書き出します。 成功した場合には 0 を返し、失敗すると -1 を返して 適切な例外をセットします。

int PyFile_WriteString( const char *s, PyFileObject *p)
文字列 s をファイルオブジェクト p に書き出します。 成功した場合には 0 を返し、失敗すると -1 を返して 適切な例外をセットします。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.5 その他のオブジェクト Up: 7.5 その他のオブジェクト Next: 7.5.2 インスタンスオブジェクト (instance object)
Release 2.3.3, documentation updated on December 19, 2003.


7.5.2 インスタンスオブジェクト (instance object)

インスタンスオブジェクト固有の関数はきわめてわずかです。

PyTypeObject PyInstance_Type
クラスインスタンスの型オブジェクトです。

int PyInstance_Check( PyObject *obj)
obj がインスタンスの場合に真を返します。

PyObject* PyInstance_New( PyObject *class, PyObject *arg, PyObject *kw)
戻り値: 新たな参照.
特定クラスの新たなインスタンスを生成します。パラメタ arg および kw はそれぞれオブジェクトのコンストラクタに渡す 実引数およびキーワードパラメタとして使われます。

PyObject* PyInstance_NewRaw( PyObject *class, PyObject *dict)
戻り値: 新たな参照.
特定クラスの新たなインスタンスを生成します。class は新たに 作成するオブジェクトのクラスです。dict パラメタは オブジェクトの __dict__ に使われます; dict が NULLなら、インスタンス用に新たな辞書が作成されます。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.5.1 ファイルオブジェクト (file object) Up: 7.5 その他のオブジェクト Next: 7.5.3 メソッドオブジェクト (method object)
Release 2.3.3, documentation updated on December 19, 2003.


7.5.3 メソッドオブジェクト (method object)

メソッドオブジェクトを操作する上で便利な関数がいくつかあります。

PyTypeObject PyMethod_Type
この PyTypeObject のインスタンスは Python のメソッドオブジェクト 型を表現します。このオブジェクトは、types.MethodType として Python プログラムに公開されています。

int PyMethod_Check( PyObject *o)
o がメソッドオブジェクト (PyMethod_Type 型である) 場合に真を返します。パラメタは NULLにできません。

PyObject* PyMethod_New( PyObject *func. PyObject *self, PyObject *class)
戻り値: 新たな参照.
任意の呼び出し可能オブジェクトfunc を使った新たなメソッド オブジェクトを返します; 関数 func は、メソッドが呼び出された 時に呼び出されるオブジェクトです。このメソッドをインスタンスに 束縛 (bind) したい場合、 self をインスタンス自体にして、 class をself のクラスにしなければなりません。 それ以外の場合は self を NULL に、 class を 非束縛メソッドを提供しているクラスにしなければなりません。

PyObject* PyMethod_Class( PyObject *meth)
戻り値: 借りた参照.
メソッドオブジェクト meth を生成したクラスオブジェクトを返します; インスタンスがメソッドオブジェクトを生成した場合、戻り値は インスタンスのクラスになります。

PyObject* PyMethod_GET_CLASS( PyObject *meth)
戻り値: 借りた参照.
PyMethod_Class() をマクロで実装したバージョンで、 エラーチェックを行いません。

PyObject* PyMethod_Function( PyObject *meth)
戻り値: 借りた参照.
meth に関連付けられている関数オブジェクトを返します。

PyObject* PyMethod_GET_FUNCTION( PyObject *meth)
戻り値: 借りた参照.
PyMethod_Function() のマクロ版で、エラーチェックを 行いません。

PyObject* PyMethod_Self( PyObject *meth)
戻り値: 借りた参照.
meth が束縛メソッドの場合には、メソッドに関連付けられている インスタンスを返します。それ以外の場合には NULLを返します。

PyObject* PyMethod_GET_SELF( PyObject *meth)
戻り値: 借りた参照.
PyMethod_Self() のマクロ版で、エラーチェックを 行いません。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.5.2 インスタンスオブジェクト (instance object) Up: 7.5 その他のオブジェクト Next: 7.5.4 モジュールオブジェクト (module object)
Release 2.3.3, documentation updated on December 19, 2003.


7.5.4 モジュールオブジェクト (module object)

モジュールオブジェクト固有の関数は数個しかありません。

PyTypeObject PyModule_Type
この PyTypeObject のインスタンスは Python のモジュールオブジェクト 型を表現します。 このオブジェクトは、Python プログラムには types.ModuleType として公開されています。

int PyModule_Check( PyObject *p)
o がモジュールオブジェクトかモジュールオブジェクトのサブタイプで あるときに真を返します。 バージョン2.2 以降で変更された 仕様: サブタイプを引数にとれるようになりました

int PyModule_CheckExact( PyObject *p)
o がモジュールオブジェクトで、かつモジュールオブジェクトの サブタイプでないときに真を返します。 PyModule_Type. バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyModule_New( char *name)
戻り値: 新たな参照.
__name__ 属性が name に設定された新たなモジュール オブジェクトを返します。モジュールの __doc__ および __name__ 属性だけに値が入っています; __file__ 属性に値を入れるのは呼び出し側の責任です。

PyObject* PyModule_GetDict( PyObject *module)
戻り値: 借りた参照.
module の名前空間を実現する辞書オブジェクトを返します; このオブジェクトはモジュールオブジェクトの __dict__ と同じです。この関数が失敗することはありません。 拡張モジュールでは、この関数で得たモジュールの__dict__ を直接いじるより、他のPyModule_*() および PyObject_*() 関数を使うよう勧めます。

char* PyModule_GetName( PyObject *module)
module の __name__ の値を返します。 モジュールがこの属性を提供していない場合や文字列型でない場合、 SystemError を送出して NULL を返します。

char* PyModule_GetFilename( PyObject *module)
module をロードするために使ったファイルの名前を、module の __file__ 属性から調べて返します。__file__ が定義されていない場合や文字列型でない場合、 SystemError を送出して NULL を返します。

int PyModule_AddObject( PyObject *module, char *name, PyObject *value)
module にオブジェクトをname として追加します。 この関数はモジュールの初期化関数から利用される便宜関数です。 エラーのときには -1 を、成功したときには 0 を 返します。 バージョン2.0 以降で新規追加された 仕様です。

int PyModule_AddIntConstant( PyObject *module, char *name, int value)
module に整数定数をname として追加します。 この便宜関数はモジュールの初期化関数から利用されています。 エラーのときには -1 を、成功したときには 0 を 返します。 バージョン2.0 以降で新規追加された 仕様です。

int PyModule_AddStringConstant( PyObject *module, char *name, char *value)
module に文字列定数をname として追加します。 この便宜関数はモジュールの初期化関数から利用されています。 文字列 value は null 終端されていなければなりません。 エラーのときには -1 を、成功したときには 0 を 返します。 バージョン2.0 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.5.3 メソッドオブジェクト (method object) Up: 7.5 その他のオブジェクト Next: 7.5.5 イテレータオブジェクト (iterator object)
Release 2.3.3, documentation updated on December 19, 2003.


7.5.5 イテレータオブジェクト (iterator object)

Python では二種類のイテレータオブジェクトを提供しています。 一つ目は配列イテレータで、__getitem__() メソッドを サポートする任意の配列を取り扱います。二つ目は呼び出し可能 オブジェクトとセンチネル値 (sentinel value) を扱い、 配列内の要素ごとに呼び出し可能オブジェクトを呼び出して、 センチネル値が返されたときに反復処理を終了します。

PyTypeObject PySeqIter_Type
PySeqIter_New() や、組み込み配列型に対して 1 引数形式の組み込み関数iter() を呼び出したときに 返される、イテレータオブジェクトの型オブジェクトです。 バージョン2.2 以降で新規追加された 仕様です。

int PySeqIter_Check( op)
PySeqIter_Type の型が op のときに真を返します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PySeqIter_New( PyObject *seq)
戻り値: 新たな参照.
一般的な配列オブジェクト seq を扱うイテレータを返します。 反復処理は、配列が添字指定操作の際に IndexError を 返したときに終了します。 バージョン2.2 以降で新規追加された 仕様です。

PyTypeObject PyCallIter_Type
PyCallIter_New() や、組み込み関数 iter() の 2 引数形式が返すイテレータオブジェクトの型オブジェクトです。 iter() built-in function. バージョン2.2 以降で新規追加された 仕様です。

int PyCallIter_Check( op)
PyCallIter_Type の型が op のときに真を返します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyCallIter_New( PyObject *callable, PyObject *sentinel)
戻り値: 新たな参照.
新たなイテレータを返します。最初のパラメタ callable は 引数なしで呼び出せる Python の呼び出し可能オブジェクトなら なんでもかまいません; callableは、呼び出されるたびに 次の反復処理対象オブジェクトを返さなければなりません。 生成されたイテレータは、 callableが sentinel に等しい 値を返すと反復処理を終了します。 バージョン2.2 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.5.4 モジュールオブジェクト (module object) Up: 7.5 その他のオブジェクト Next: 7.5.6 デスクリプタオブジェクト (descriptor object)
Release 2.3.3, documentation updated on December 19, 2003.


7.5.6 デスクリプタオブジェクト (descriptor object)

``デスクリプタ (descriptor)'' は、あるオブジェクトのいくつかの属性 について記述したオブジェクトです。デスクリプタオブジェクトは 型オブジェクトの辞書内にあります。

PyTypeObject PyProperty_Type
組み込みデスクリプタ型の型オブジェクトです。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyDescr_NewGetSet( PyTypeObject *type, PyGetSetDef *getset)
戻り値: 新たな参照.
バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyDescr_NewMember( PyTypeObject *type, PyMemberDef *meth)
戻り値: 新たな参照.
バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyDescr_NewMethod( PyTypeObject *type, PyMethodDef *meth)
戻り値: 新たな参照.
バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyDescr_NewWrapper( PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
戻り値: 新たな参照.
バージョン2.2 以降で新規追加された 仕様です。

int PyDescr_IsData( PyObject *descr)
デスクリプタオブジェクト descr がデータ属性のデスクリプタの 場合には真を、メソッドデスクリプタの場合には偽を返します。 descr はデスクリプタオブジェクトでなければなりません; エラーチェックは行いません。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyWrapper_New( PyObject *, PyObject *)
戻り値: 新たな参照.
バージョン2.2 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.5.5 イテレータオブジェクト (iterator object) Up: 7.5 その他のオブジェクト Next: 7.5.7 スライスオブジェクト (slice object)
Release 2.3.3, documentation updated on December 19, 2003.


7.5.7 スライスオブジェクト (slice object)

PyTypeObject PySlice_Type
スライスオブジェクトの型オブジェクトです。 types.SliceType と同じです。

int PySlice_Check( PyObject *ob)
ob がスライスオブジェクトの場合に真を返します; ob は NULLであってはなりません。

PyObject* PySlice_New( PyObject *start, PyObject *stop, PyObject *step)
戻り値: 新たな参照.
指定した値から新たなスライスオブジェクトを返します。パラメタ start, stop, および step はスライスオブジェクトに おける同名の属性として用いられます。これらの値はいずれも NULLにでき、対応する値には None が使われます。新たな オブジェクトをアロケーションできない場合には NULL を返します。

int PySlice_GetIndices( PySliceObject *slice, int length, int *start, int *stop, int *step)
スライスオブジェクト slice における start, stop, および step のインデクス値を取得します。このとき配列の 長さを length と仮定します。length よりも大きな インデクスになるとエラーとして扱います。

成功のときには 0 を、エラーのときには例外をセットせずに -1 を返します (ただし、指定インデクスのいずれか一つが None ではなく、かつ整数に変換できなかった場合を 除きます。この場合、 -1 を返して例外をセットします)。

おそらくこの関数を使う気にはならないでしょう。バージョン 2.3 以前の Python でスライスオブジェクトを使いたいのなら、 PySlice_GetIndicesEx のソースを適切に名前変更して 自分の拡張モジュールのソースコード内に組み込むとよいでしょう。

int PySlice_GetIndicesEx( PySliceObject *slice, int length, int *start, int *stop, int *step, int *slicelength)
PySlice_GetIndices の置き換えとして使える関数です。

スライスオブジェクト slice における start, stop, および step のインデクス値を取得します。このとき配列の 長さを length と仮定します。スライスの長さを slicelength に記憶します。境界をはみだしたインデクスは、通常のスライスを扱うのと 同じ一貫したやり方でクリップされます。

成功のときには 0 を、エラーのときには例外をセットして -1 を返します。

バージョン2.3 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.5.6 デスクリプタオブジェクト (descriptor object) Up: 7.5 その他のオブジェクト Next: 7.5.8 弱参照オブジェクト (weak reference
Release 2.3.3, documentation updated on December 19, 2003.


7.5.8 弱参照オブジェクト (weak reference object)

Python は 弱参照 を第一級オブジェクト (first-class object) としてサポートします。弱参照を直接実装する二種類の固有のオブジェクト 型があります。第一は単純な参照オブジェクトで、第二はオリジナルの オブジェクトに対して可能な限りプロキシとして振舞うオブジェクトです。

int PyWeakref_Check( ob)
ob が参照オブジェクトかプロキシオブジェクトの場合に真を返します。 バージョン2.2 以降で新規追加された 仕様です。

int PyWeakref_CheckRef( ob)
ob が参照オブジェクトの場合に真を返します。 バージョン2.2 以降で新規追加された 仕様です。

int PyWeakref_CheckProxy( ob)
ob がプロキシオブジェクトの場合に真を返します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyWeakref_NewRef( PyObject *ob, PyObject *callback)
戻り値: 新たな参照.
ob に対する弱参照オブジェクトを返します。この関数は常に 新たな参照を返しますが、必ずしも新たなオブジェクトを作る保証は ありません; 既存の参照オブジェクトが返されることもあります。 第二のパラメタ callback は呼び出し可能オブジェクトで、 ob がガーベジコレクションされた際に通知を受け取ります; callback は弱参照オブジェクト自体を単一のパラメタとして 受け取ります。callback は None や NULLにしても かまいません。 ob が弱参照できないオブジェクトの場合や、 callback が呼び出し可能オブジェクト、None、NULL のいずれでもない場合は、NULL を返してTypeError を送出します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyWeakref_NewProxy( PyObject *ob, PyObject *callback)
戻り値: 新たな参照.
ob に対する弱参照プロキシオブジェクトを返します。この関数は常に 新たな参照を返しますが、必ずしも新たなオブジェクトを作る保証は ありません; 既存の参照オブジェクトが返されることもあります。 第二のパラメタ callback は呼び出し可能オブジェクトで、 ob がガーベジコレクションされた際に通知を受け取ります; callback は弱参照オブジェクト自体を単一のパラメタとして 受け取ります。callback は None や NULLにしても かまいません。 ob が弱参照できないオブジェクトの場合や、 callback が呼び出し可能オブジェクト、None、NULL のいずれでもない場合は、NULL を返してTypeError を送出します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyWeakref_GetObject( PyObject *ref)
戻り値: 借りた参照.
弱参照 ref が参照しているオブジェクトを返します。 被参照オブジェクトがすでに存続していない場合、 None を 返します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyWeakref_GET_OBJECT( PyObject *ref)
戻り値: 借りた参照.
PyWeakref_GetObject() に似ていますが、マクロで実装 されていて、エラーチェックを行いません。 バージョン2.2 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.5.7 スライスオブジェクト (slice object) Up: 7.5 その他のオブジェクト Next: 7.5.9 Cオブジェクト (CObject)
Release 2.3.3, documentation updated on December 19, 2003.


7.5.9 Cオブジェクト (CObject)

このオブジェクトの使用法に関する情報は、 Python インタプリタの拡張と埋め込み 1.12 節、 ``Providing a C API for an Extension Module,'' を参照してください。

PyCObject
この PyObject のサブタイプは不透明型値 (opaque value) を 表現します。C 拡張モジュールが Python コードから不透明型値を (void* ポインタで) 他の C コードに渡す必要があるときに 便利です。 正規の import 機構を使って動的にロードされるモジュール内で定義 されている C API にアクセスするために、あるモジュール内で定義 されている C 関数ポインタを別のモジュールでも利用できるように するためによく使われます。

int PyCObject_Check( PyObject *p)
引数が PyCObject の場合に真を返します。

PyObject* PyCObject_FromVoidPtr( void* cobj, void (*destr)(void *))
戻り値: 新たな参照.
void *cobj から PyCObject を生成します。 関数 destr が NULLでない場合、オブジェクトを再利用する際に 呼び出します。

PyObject* PyCObject_FromVoidPtrAndDesc( void* cobj, void* desc, void (*destr)(void *, void *))
戻り値: 新たな参照.
void *cobj から PyCObject を生成します。 関数 destr が NULLでない場合、オブジェクトを再利用する際に 呼び出します。 引数 desc を使って、デストラクタ関数に追加のコールバックデータ を渡せます。

void* PyCObject_AsVoidPtr( PyObject* self)
PyCObject オブジェクト self を生成するのに用いた オブジェクト void * を返します。

void* PyCObject_GetDesc( PyObject* self)
PyCObject オブジェクト self を生成するのに用いた コールバックデータ void * を返します。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.5.8 弱参照オブジェクト (weak reference Up: 7.5 その他のオブジェクト Next: 7.5.10 セルオブジェクト (cell object)
Release 2.3.3, documentation updated on December 19, 2003.


7.5.10 セルオブジェクト (cell object)

``セル (cell)'' オブジェクトは、複数のスコープから参照される 変数群を実装するために使われます。セルは各変数について作成され、 各々の値を記憶します; この値を参照する各スタックフレームにおける ローカル変数には、そのスタックフレームの外側で同じ値を参照している セルに対する参照が入ります。セルで表現された値にアクセスすると、 セルオブジェクト自体の代わりにセル内の値が使われます。この セルオブジェクトを使った間接参照 (dereference) は、インタプリタに よって生成されたバイトコード内でサポートされている必要があります; セルオブジェクトにアクセスした際に、自動的に間接参照は起こり ません。上記以外の状況では、セルオブジェクトは役に立たないはずです。

PyCellObject
セルオブジェクトに使われる C 構造体です。

PyTypeObject PyCell_Type
セルオブジェクトに対応する型オブジェクトです。

int PyCell_Check( ob)
ob がセルオブジェクトの場合に真を返します; ob は NULLであってはなりません。

PyObject* PyCell_New( PyObject *ob)
戻り値: 新たな参照.
値 ob の入った新たなセルオブジェクトを生成して返します。 引数を NULLにしてもかまいません。

PyObject* PyCell_Get( PyObject *cell)
戻り値: 新たな参照.
cell の内容を返します。

PyObject* PyCell_GET( PyObject *cell)
戻り値: 借りた参照.
cell の内容を返しますが、cell が非 NULL でかつ セルオブジェクトであるかどうかチェックしません。

int PyCell_Set( PyObject *cell, PyObject *value)
セルオブジェクト cell の内容を value に設定します。 この関数は現在のセルの全ての内容に対する参照を解放します。 value は NULLでもかまいません。cell は 非NULL でなければなりません; もしcell がセルオブジェクトでない 場合、 -1 を返します。成功すると 0 を返します。

void PyCell_SET( PyObject *cell, PyObject *value)
セルオブジェクト cell の値を value に設定します。 参照カウントに対する変更はなく、安全のためのチェックは何も 行いません; cell は非NULL でなければならず、かつ セルオブジェクトでなければなりません。
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.5.9 Cオブジェクト (CObject) Up: 7.5 その他のオブジェクト Next: 8. 初期化 (initialization)、終了処理 (finalization)、スレッド
Release 2.3.3, documentation updated on December 19, 2003.


8. 初期化 (initialization)、終了処理 (finalization)、スレッド

void Py_Initialize( )
Python インタプリタを初期化します。Python の埋め込みを行う アプリケーションでは、他のあらゆる Python/C API を使用するよりも 前にこの関数を呼び出さねばなりません; ただし、 Py_SetProgramName(), PyEval_InitThreads(), PyEval_ReleaseLock(), および PyEval_AcquireLock()は例外です。 この関数はロード済みモジュールのテーブル (sys.modules) を初期化し、基盤となるモジュール群、 __builtin__, __main__および sysを生成します。 また、モジュール検索パス (sys.path) も初期化します。 sys.argv の設定は行いません; 設定するには、 PySys_SetArgv()を使ってください。 この関数を (Py_Finalize()を 呼ばずに) 再度呼び出しても何も行いません。 戻り値はありません; 初期化が失敗すれば、それは致命的なエラーです。

int Py_IsInitialized( )
Python インタプリタがすでに初期化済みの場合に真 (非ゼロ) を返し、 そうでない場合には偽 (ゼロ) を返します。Py_Finalize() を呼び出すと、次にPy_Initialize() を呼び出すまで この関数は偽を返します。

void Py_Finalize( )
Py_Initialize() とそれ以後の Python/C API 関数で行った 全ての初期化処理を取り消し、最後の Py_Initialize() 呼び出し以後に Python インタプリタが生成した全てのサブインタプリタ (sub-interpreter, 下記の Py_NewInterpreter() を参照) を 消去します。 理想的な状況では、この関数によって Python インタプリタが確保した メモリは全て解放されます。 この関数を (Py_Initialize() を呼ばずに) 再度呼び出しても 何も行いません。 戻り値はありません; 終了処理中のエラーは無視されます。

この関数が提供されている理由はいくつかあります。Python の埋め込みを 行っているアプリケーションでは、アプリケーションを再起動することなく Python を再起動したいことがあります。また、動的ロード可能イブラリ (あるいは DLL) から Python インタプリタをロードするアプリケーション では、DLL をアンロードする前に Python が確保したメモリを解放したい と考えるかもしれません。アプリケーション内で起きているメモリリークを 追跡する際に、開発者は Python が確保したメモリをアプリケーションの 終了前に解放させたいと思う場合もあります。

バグおよび注意事項: モジュールやモジュール内のオブジェクト はランダムな順番で削除されます; このため、他のオブジェクト (関数オブジェクトも含みます) やモジュールに依存するデストラクタ (__del__() メソッド) が失敗してしまうことがあります。 動的にロードされるようになっている拡張モジュールが Python によって ロードされていた場合、アンロードされません。Python が確保した メモリがわずかながら解放されないかもしれません (メモリリークを 発見したら、どうか報告してください)。オブジェクト間の循環参照に 捕捉されているメモリは解放されないことがあります。拡張モジュール が確保したメモリは解放されないことがあります。拡張モジュールに よっては、初期化ルーチンを 2 度以上呼び出すと正しく動作 しないことがあります; こうした状況は、Py_Initialize() やPy_Finalize() を 2 度以上呼び出すと起こり得ます。

PyThreadState* Py_NewInterpreter( )
新しいサブインタプリタ (sub-interpreter) を生成します。 サブインタプリタとは、(ほぼ完全に) 個別に分割された Python コードの実行環境です。特に、新しいサブインタプリタは、 import されるモジュール全てについて個別のバージョンを持ち、 これには基盤となるモジュール __builtin__, __main__および sysも含まれます。 ロード済みのモジュールからなるテーブル (sys.modules) およびモジュール検索パス (sys.path) もサブインタプリタ 毎に別個のものになります。新たなサブインタプリタ環境には sys.argv 変数がありません。また、サブインタプリタは 新たな標準 I/O ストリーム sys.stdin, sys.stdout および sys.stderr を持ちます (とはいえ、これらのストリームは 根底にある C ライブラリの同じ FILE 構造体を参照しています)。

戻り値は、新たなサブインタプリタが生成したスレッド状態 (thread state) オブジェクトのうち、最初のものを指しています。 このスレッド状態が現在のスレッド状態 (current thread state) になります。 実際のスレッドが生成されるわけではないので注意してください; 下記のスレッド状態に関する議論を参照してください。 新たなインタプリタの生成に失敗すると、NULL を返します; 例外状態はセットされませんが、これは例外状態が現在のスレッド状態に 保存されることになっていて、現在のスレッド状態なるものが 存在しないことがあるからです。 (他の Python/C API 関数のように、 この関数を呼び出す前にはグローバルインタプリタロック (global interpreter lock) が保持されていなければならず、関数が 処理を戻した際にも保持されたままになります; しかし、 他の Python/C API 関数とは違い、関数から戻ったときの現在のスレッド状態 が関数に入るときと同じとは限らないので注意してください)。

拡張モジュールは以下のような形で (サブ) インタプリタ間で共有 されます: ある特定の拡張モジュールを最初に import すると、 モジュールを通常通りに初期化し、そのモジュールの辞書の (浅い) コピーをしまい込んでおきます。他の (サブ) インタプリタが 同じ拡張モジュールを import すると、新たなモジュールを初期化し、 先ほどのコピーの内容で辞書の値を埋めます; 拡張モジュールの init 関数は呼び出されません。この挙動は、 Py_Finalize()および Py_Initialize()を呼び出して インタプリタを完全に再初期化した後に拡張モジュールを import した 際の挙動とは異なるので注意してください; 再初期化後に import を 行うと、拡張モジュールの initmodule は再度 呼び出され ます。

バグと注意事項: サブインタプリタ (とメインインタプリタ) は同じプロセスの一部分なので、インタプリタ間の絶縁性は完璧では ありません -- 例えば、os.close() のような低レベルのファイル操作を使うと、 (偶然なり故意なりに) 互いのインタプリタ下にある開かれたファイルに 影響を及ぼせてしまいます。 拡張モジュールを (サブ) インタプリタ間で共有する方法のために、 拡張モジュールによっては正しく動作しないかもしれません; 拡張モジュールが (静的な) グローバル変数を利用している 場合や、拡張モジュールが初期化後に自身のモジュール辞書を操作 する場合には特にそうです。 一つのサブインタプリタで生成されたオブジェクトは他のサブインタプリタ の名前空間への挿入が可能です; ユーザ定義関数、メソッド、インスタンス およびクラスをサブインタプリタをサブインタプリタ間で共有しないように 十分注意してください。というのは、これらの共有オブジェクトが 実行した import 文は間違った (サブ) インタプリタのロード済み モジュール辞書に影響を及ぼす場合があるからです (XXX この問題は 修正が難しいバグで、将来のリリースで解決される予定です)

void Py_EndInterpreter( PyThreadState *tstate)
指定されたスレッド状態 tstate で表現される (サブ) インタプリタを 抹消します。tstate は現在のスレッド状態でなければなりません。 下記のスレッド状態に関する議論を参照してください。関数呼び出しが 戻ったとき、現在のスレッド状態は NULLになっています。 このインタプリタに関連付けられた全てのスレッド状態は抹消されます。 (この関数を呼び出す前にはグローバルインタプリタロックを保持して おかねばならず、ロックは関数が戻ったときも保持されています。) Py_Finalize()は、その時点で 明示的に抹消されていない全てのサブインタプリタを抹消します。

void Py_SetProgramName( char *name)
この関数を呼び出すなら、最初に Py_Initialize()を呼び出す よりも前に呼び出さねばなりません。この関数はインタプリタに プログラムのmain()関数に 指定したargv[0] 引数の値を教えます。 この引数値は、Py_GetPath()や、 以下に示すその他の関数が、インタプリタの実行可能形式から Python ランタイムライブラリへの相対パスを取得するために使われます。 デフォルトの値は'python' です。引数はゼロ終端された キャラクタ文字列で、静的な記憶領域に入っていなければならず、 その内容はプログラムの実行中に変更してはなりません。 Python インタプリタ内のコードで、この記憶領域の内容を変更するものは 一切ありません。

char* Py_GetProgramName( )
Py_SetProgramName()で 設定されたプログラム名か、デフォルトのプログラム名を返します。 関数が返す文字列ポインタは静的な記憶領域を返します; 関数の 呼び出し側はこの値を変更できません。

char* Py_GetPrefix( )
プラットフォーム非依存のファイル群がインストールされている場所である prefix を返します。この値は Py_SetProgramName() でセットされたプログラム名や いくつかの環境変数をもとに、数々の複雑な規則から導出されます; 例えば、プログラム名が'/usr/local/bin/python' の場合、prefix は '/usr/local' になります。 関数が返す文字列ポインタは静的な記憶領域を返します; 関数の 呼び出し側はこの値を変更できません。 この値はトップレベルの Makefile に指定されている変数 prefix や、ビルド値に configure スクリプト に指定した --prefix 引数に対応しています。 この値は Python コードからは sys.prefix として利用できます。 Unixでも有用です。次に説明する関数も参照してください。

char* Py_GetExecPrefix( )
プラットフォーム依存 のファイルがインストールされている場所 であるexec-prefix を返します。 この値はPy_SetProgramName() でセットされたプログラム名や いくつかの環境変数をもとに、数々の複雑な規則から導出されます; 例えば、プログラム名が'/usr/local/bin/python' の場合、exec-prefix は '/usr/local' になります。 関数が返す文字列ポインタは静的な記憶領域を返します; 関数の 呼び出し側はこの値を変更できません。 この値はトップレベルの Makefile に指定されている変数 exec_prefix や、ビルド値に configure スクリプト に指定した --exec-prefix 引数に対応しています。 この値は Python コードからは sys.exec_prefix として利用できます。 Unixのみで有用です。

背景: プラットフォーム依存のファイル (実行形式や共有ライブラリ) が、 別個のディレクトリツリー内にインストールされている場合、 exec-prefix は prefix と異なります。典型的なインストール形態では、 プラットフォーム非依存のファイルが/usr/local に収められる一方、 プラットフォーム依存のファイルは/usr/local/plat サブツリーに 収められます。

概して、プラットフォームとは、ハードウェアとソフトウェアファミリの 組み合わせを指します。例えば、 Solaris 2.x を動作させている Sparc マシンは全て同じプラットフォームであるとみなしますが、Solaris 2.x を動作させている Intel マシンは違うプラットフォームになりますし、 同じ Intel マシンでも Linux を動作させているならまた別の プラットフォームです。一般的には、同じオペレーティングシステムでも、 メジャーリビジョンの違うものは異なるプラットフォームです。 非 Unix のオペレーティングシステムの場合は話はまた別です; 非 Unix のシステムでは、インストール方法はとても異なっていて、 prefix や exec-prefix には意味がなく、空文字列が設定されている ことがあります。コンパイル済みの Python バイトコードは プラットフォームに依存しないので注意してください (ただし、 どのバージョンの Python でコンパイルされたかには依存します!)。

システム管理者は、mount や automount プログラムを 使って、各プラットフォーム用の/usr/local/plat を異なった ファイルシステムに置き、プラットフォーム間で /usr/local を 共有するための設定方法を知っているはずです。

char* Py_GetProgramFullPath( )
Python 実行可能形式の完全なプログラム名を返します; この値は デフォルトのモジュール検索パスを (前述のPy_SetProgramName() で設定された) プログラム名から導出する際に 副作用的に計算されます。 関数が返す文字列ポインタは静的な記憶領域を返します; 関数の 呼び出し側はこの値を変更できません。 この値は Python コードからは sys.executable として利用できます。 Unixのみで有用です。

char* Py_GetPath( )
デフォルトモジュール検索パスを返します; パスは (上の Py_SetProgramName() で設定された) プログラム名と、 いくつかの環境変数から計算されます。戻り値となる文字列は、 プラットフォーム依存のパスデリミタ文字で分割された一連の ディレクトリ名からなります。デリミタ文字は Unixでは":"、 Windows では";" 、Macintosh では "\n" (ASCII 改行文字) です。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。 この値は Python コードからはリスト sys.path として 利用できます。このリストは、値を修正して将来モジュールをロードする際に 使う検索パスを変更できます。

const char* Py_GetVersion( )
Python インタプリタのバージョンを返します。バージョンは、

"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"

ような形式の文字列です。

第一ワード (最初のスペース文字まで) は、現在の Python のバージョン です; 最初の三文字は、メジャーバージョンとマイナーバージョン、そして それを分割しているピリオドです。関数が返す文字列ポインタは静的な 記憶領域を返します; 関数の呼び出し側はこの値を変更できません。 この値は Python コードからはsys.versionとして利用できます。

const char* Py_GetPlatform( )
現在のプラットフォームのプラットフォーム識別文字列を返します。 Unixでは、オペレーティングシステムの ``公式の'' 名前を小文字に 変換し、後ろにメジャーリビジョン番号を付けた構成になっています; 例えば Solaris 2.x は、SunOS 5.x, としても知られていますが、 'sunos5' になります。Macintosh では 'mac' です。 Windows では'win' です。 関数が返す文字列ポインタは静的な 記憶領域を返します; 関数の呼び出し側はこの値を変更できません。 この値は Python コードからはsys.platformとして利用できます。

const char* Py_GetCopyright( )
現在の Python バージョンに対する公式の著作権表示文字列、例えば 'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam' を返します。 関数が返す文字列ポインタは静的な 記憶領域を返します; 関数の呼び出し側はこの値を変更できません。 この値は Python コードからはsys.copyrightとして利用できます。

const char* Py_GetCompiler( )
現在使っているバージョンの Python をビルドする際に用いたコンパイラ を示す文字列を、各括弧で囲った文字列を返します。例えば:

"[GCC 2.7.2.2]"

になります。

関数が返す文字列ポインタは静的な 記憶領域を返します; 関数の呼び出し側はこの値を変更できません。 この値は Python コードからはsys.version の一部として 取り出せます。

const char* Py_GetBuildInfo( )
現在使っている Python インタプリタインスタンスの、シーケンス番号と ビルド日時に関する情報を返します。例えば

"#67, Aug  1 1997, 22:34:28"

になります。

関数が返す文字列ポインタは静的な 記憶領域を返します; 関数の呼び出し側はこの値を変更できません。 この値は Python コードからはsys.version の一部として 取り出せます。

int PySys_SetArgv( int argc, char **argv)
argc および argv に基づいて sys.argv を設定 します。このパラメタはプログラムの main()に渡したパラメタに似ていますが、最初の要素が Python インタプリタ の宿主となっている実行形式の名前ではなく、実行されるスクリプト名を 参照しなければならない点が違います。実行するスクリプトがない場合、 argv の最初の要素は空文字列にしてもかまいません。 この関数が sys.argv の初期化に失敗した場合、致命的 エラー条件をPy_FatalError()でシグナルします。

  • 8.1 スレッド状態 (thread state) とグローバルインタプリタロック (global interpreter lock)
  • 8.2 プロファイルとトレース (profiling and tracing)
  • 8.3 高度なデバッガサポート (advanced debugger support)
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.5.10 セルオブジェクト (cell object) Up: Python/C API リファレンスマニュアル Next: 8.1 スレッド状態 (thread state)
Release 2.3.3, documentation updated on December 19, 2003.


8.1 スレッド状態 (thread state) とグローバルインタプリタロック (global interpreter lock)

Python インタプリタは完全にスレッド安全 (thread safe) ではありません。 マルチスレッドの Python プログラムをサポートするために、グローバルな ロックが存在していて、現在のスレッドが Python オブジェクトに安全に アクセスする前に必ずロックを獲得しなければならなくなっています。 ロック機構がなければ、単純な操作でさえ、マルチスレッドプログラムの 実行に問題を引き起こす可能性があります: たとえば、二つのスレッドが 同じオブジェクトの参照カウントを同時にインクリメントすると、 結果的に参照カウントは二回でなく一回だけしかインクリメントされない かもしれません。

このため、グローバルインタプリタロックを獲得したスレッドだけが Python オブジェクトを操作したり、 Python/C API 関数を呼び出したり できるというルールがあります。マルチスレッドの Python プログラムを サポートするため、インタプリタは定期的に -- デフォルトの設定では バイトコード 100 命令ごとに (この値は sys.setcheckinterval() で 変更できます) -- ロックを解放したり獲得したりします。 このロックはブロックが起こりうる I/O 操作の付近でも解放・獲得 され、I/O を要求するスレッドが I/O 操作の完了を待つ間、他の スレッドが動作できるようにしています。

Python インタプリタはスレッドごとに何らかの予約情報を持っておかねば なりません -- このため、Python は PyThreadStateと呼ばれるデータ構造 を用います。これは Python 1.5 からの仕様です; 以前のバージョンでは、 スレッド状態はグローバル変数内に保存されていて、スレッドを切り替えると 問題を起こすことがありました。特に、アプリケーションが sys.exc_info() を使って、現在のスレッドで送出された 最新の例外にアクセスする際の例外処理は、いまやスレッド安全になりました。 とはいえ、グローバル変数はまだ一つだけ残っています: それは現在の PyThreadState構造体を指すポインタです。 ほとんどのスレッドパッケージが ``スレッドごとのグローバルデータ'' を保存する手段を持っている一方で、Python の内部的なプラットフォーム 非依存のスレッド抽象層はこれをサポートしていません。従って、 現在のスレッド状態を明示的に操作するようにしなければなりません。

ほとんどのケースで、このような操作は十分簡単にできます。 グローバルインタプリタロックを操作数ほとんどのコードは、以下のような 単純な構造を持ちます:

スレッド状態をローカル変数に保存する。
インタプリタロックを解放する。
...ブロックが起きるような何らかの I/O 操作...
インタプリタロックを獲得する。
ローカル変数からスレッド状態を回復する。

このやりかたは非常に一般的なので、作業を単純にするために二つの マクロが用意されています:

Py_BEGIN_ALLOW_THREADS
...ブロックが起きるような何らかの I/O 操作...
Py_END_ALLOW_THREADS

Py_BEGIN_ALLOW_THREADSマクロは新たなブロック文を開始し、隠しローカル変数を宣言します; Py_END_ALLOW_THREADSはブロック文を終了します。これらの二つのマクロを使うもうひとつの 利点は、Python をスレッドサポートなしでコンパイルしたとき、 マクロの内容、すなわちスレッド状態の退避とロック操作が空になると いう点です。

スレッドサポートが有効になっている場合、上記のブロックは 以下のようなコードに展開されます:

    PyThreadState *_save;

    _save = PyEval_SaveThread();
    ...ブロックが起きるような何らかの I/O 操作...
    PyEval_RestoreThread(_save);

より低水準のプリミティブを使うと、以下のようにしてほぼ同じ効果を 得られます:

    PyThreadState *_save;

    _save = PyThreadState_Swap(NULL);
    PyEval_ReleaseLock();
    ...ブロックが起きるような何らかの I/O 操作...
    PyEval_AcquireLock();
    PyThreadState_Swap(_save);

上の二つには微妙な違いがあります; とりわけ、 PyEval_RestoreThread() はグローバル変数 errnoの値を保存しておいて 元に戻す点が異なります。というのは、ロック操作が errno に 何もしないという保証がないからです。また、スレッドサポートが無効化 されている場合、 PyEval_SaveThread()および PyEval_RestoreThread() はロックを操作しません; この場合、 PyEval_ReleaseLock()および PyEval_AcquireLock()は 利用できません。この仕様は、スレッドサポートを無効化してコンパイル されているインタプリタが、スレッドサポートが有効化された状態で コンパイルされている動的ロード拡張モジュールをロードできる ようにするためのものです。

グローバルインタプリタロックは、現在のスレッド状態を指すポインタを 保護するために使われます。ロックを解放してスレッド状態を退避する際、 ロックを解放する前に現在のスレッド状態ポインタを取得しておかなければ なりません (他のスレッドがすぐさまロックを獲得して、自らの スレッド状態をグローバル変数に保存してしまうかもしれないからです)。 逆に、ロックを獲得してスレッド状態を復帰する際には、 グローバル変数にスレッド状態ポインタを保存する前にロックを獲得して おかなければなりません。

なぜここまで詳しく説明しようとするかおわかりでしょうか? それは、 C でスレッドを生成した場合、そのスレッドにはグローバルインタプリタ ロックがなく、スレッド状態データ構造体もないからです。このような スレッドが Python/C API を利用するには、まずスレッド状態データ構造体を 生成し、次にロックを獲得し、そしてスレッド状態ポインタを保存すると いったように、自分自身をブートストラップして生成しなければ なりません。スレッドが作業を終えたら、スレッド状態ポインタを リセットして、ロックを解放し、最後にスレッド状態データ構造体を メモリ解放しなければなりません。

スレッドデータ構造体を生成する際には、インタプリタ状態データ構造体を 指定する必要があります。インタプリタ状態データ構造体は、 インタプリタ内の全てのスレッド間で共有されているグローバルなデータ、 例えばモジュール管理データ (codesys.modules) を保持しています。 必要に応じて、新たなインタプリタ状態データ構造体を作成するなり、 Python メインスレッドが使っているインタプリタ状態データ構造体 を共有するなりできます (後者のデータにアクセスするためには、 スレッド状態データ構造体を獲得して、その interp メンバ にアクセスしなければなりません; この処理は、Python が作成した スレッドから行うか、Python を初期化した後で主スレッドから行わねば なりません)。

インタプリタオブジェクトにアクセスできるという仮定の下では、C の スレッドから Python を呼び出す際の典型的な常套句は以下のようになります。

    PyThreadState *tstate;
    PyObject *result;

    /* interp is your reference to an interpreter object. */
    tstate = PyThreadState_New(interp);
    PyEval_AcquireThread(tstate);

    /* Perform Python actions here.  */
    result = CallSomeFunction();
    /* evaluate result */

    /* Release the thread. No Python API allowed beyond this point. */
    PyEval_ReleaseThread(tstate);

    /* You can either delete the thread state, or save it
       until you need it the next time. */
    PyThreadState_Delete(tstate);

PyInterpreterState
このデータ構造体は、協調動作する多数のスレッド間で共有されている 状態 (state) を表現します。同じインタプリタに属するスレッドは モジュール管理情報やその他いくつかの内部的な情報を共有しています。 この構造体には公開 (public) のメンバはありません。

異なるインタプリタに属するスレッド間では、利用可能なメモリ、 開かれているファイルデスクリプタなどといったプロセス状態を除き、 初期状態では何も共有されていません。グローバルインタプリタロック もまた、スレッドがどのインタプリタに属しているかに関わらず すべてのスレッドで共有されています。

PyThreadState
単一のスレッドの状態を表現する表現するデータ構造体です。 データメンバ PyInterpreterState *interp だけが公開されていて、スレッドのインタプリタ状態を指すポインタに なっています。

void PyEval_InitThreads( )
グローバルインタプリタロックを初期化し、獲得します。 この関数は、主スレッドが第二のスレッドを生成する以前や、 PyEval_ReleaseLock()や PyEval_ReleaseThread(tstate)といった他のスレッド操作に入るよりも前に呼び出されるようにして おかなければなりません。

二度目に呼び出すと何も行いません。この関数を Py_Initialize()の前に呼び出しても 安全です。

主スレッドしか存在しないのであれば、ロック操作は必要ありません。 これはよくある状況ですし (ほとんどの Python プログラムはスレッドを 使いません)、ロック操作はインタプリタをごくわずかに低速化します。 従って、初期状態ではロックは生成されません。ロックを使わない状況は、 すでにロックを獲得している状況と同じです: 単一のスレッドしか なければ、オブジェクトへのアクセスは全て安全です。従って、 この関数がロックを初期化すると、同時にロックを獲得するようになって います。Python の threadモジュールは、 新たなスレッドを作成する前に、ロックが存在するか、あるいはまだ 作成されていないかを調べ、PyEval_InitThreads() を 呼び出します。この関数から処理が戻った場合、ロックの作成と獲得が 保証されています。

どのスレッドが現在グローバルインタプリタロックを (存在する場合) 持っているか分からない時にこの関数を使うのは安全では ありません 。

この関数はコンパイル時にスレッドサポートを無効化すると利用できません。

void PyEval_AcquireLock( )
グローバルインタプリタロックを獲得します。 ロックは前もって作成されていなければなりません。 この関数を呼び出したスレッドがすでにロックを獲得している場合、 デッドロックに陥ります。 この関数はコンパイル時にスレッドサポートを無効化すると利用できません。

void PyEval_ReleaseLock( )
グローバルインタプリタロックを解放します。 ロックは前もって作成されていなければなりません。 この関数はコンパイル時にスレッドサポートを無効化すると利用できません。

void PyEval_AcquireThread( PyThreadState *tstate)
グローバルインタプリタロックを獲得し、現在のスレッド状態を tstate に設定します。tstate は NULLであっては なりません。ロックはあらかじめ作成されていなければなりません。 この関数を呼び出したスレッドがすでにロックを獲得している場合、 デッドロックに陥ります。 この関数はコンパイル時にスレッドサポートを無効化すると利用できません。

void PyEval_ReleaseThread( PyThreadState *tstate)
現在のスレッド状態をリセットして NULL にし、グローバルインタプリタ ロックを解放します。ロックはあらかじめ作成されていなければならず、 かつ現在のスレッドが保持していなければなりません。tstate は NULLであってはなりませんが、その値が現在のスレッド状態を 表現しているかどうかを調べるためにだけ使われます -- もしそうで なければ、致命的エラーが報告されます。 この関数はコンパイル時にスレッドサポートを無効化すると利用できません。

PyThreadState* PyEval_SaveThread( )
(インタプリタロックが生成されていて、スレッドサポートが有効の 場合) インタプリタロックを解放して、スレッド状態を NULLにし、 以前のスレッド状態 (NULLにはなりません) を返します。 ロックがすでに生成されている場合、現在のスレッドがロックを獲得 していなければなりません。

void PyEval_RestoreThread( PyThreadState *tstate)
(インタプリタロックが生成されていて、スレッドサポートが有効の 場合) インタプリタロックを獲得して、現在のスレッド状態を tstate に設定します。tstate は NULLであっては なりません。 この関数を呼び出したスレッドがすでにロックを獲得している場合、 デッドロックに陥ります。 (この関数はコンパイル時にスレッドサポートを無効化すると利用できません。)

以下のマクロは、通常末尾にセミコロンを付けずに使います; Python ソース配布物内の使用例を見てください。

Py_BEGIN_ALLOW_THREADS
このマクロを展開すると "{ PyThreadState *_save; _save = PyEval_SaveThread();"になります。 マクロに開き波括弧が入っていることに注意してください; この波括弧は 後で Py_END_ALLOW_THREADS マクロと対応させなければ なりません。 マクロについての詳しい議論は上記を参照してください。 コンパイル時にスレッドサポートが無効化されていると何も行いません。

Py_END_ALLOW_THREADS
このマクロを展開すると "PyEval_RestoreThread(_save); }"になります。 マクロに開き波括弧が入っていることに注意してください; この波括弧は 事前の Py_BEGIN_ALLOW_THREADS マクロと対応して いなければなりません。 マクロについての詳しい議論は上記を参照してください。 コンパイル時にスレッドサポートが無効化されていると何も行いません。

Py_BLOCK_THREADS
このマクロを展開すると "PyEval_RestoreThread(_save);"になります: 閉じ波括弧のないPy_END_ALLOW_THREADS と同じです。 コンパイル時にスレッドサポートが無効化されていると何も行いません。

Py_UNBLOCK_THREADS
このマクロを展開すると "_save = PyEval_SaveThread();"になります: 閉じ波括弧のないPy_BEGIN_ALLOW_THREADS と同じです。 コンパイル時にスレッドサポートが無効化されていると何も行いません。

以下の全ての関数はコンパイル時にスレッドサポートが有効になっている 時だけ利用でき、呼び出すのはインタプリタロックがすでに作成されている 場合だけにしなくてはなりません。

PyInterpreterState* PyInterpreterState_New( )
新しいインタプリタ状態オブジェクトを生成します。 インタプリタロックを保持しておく必要はありませんが、この関数を次々に 呼び出す必要がある場合には保持しておいたほうがよいでしょう。

void PyInterpreterState_Clear( PyInterpreterState *interp)
インタプリタ状態オブジェクト内の全ての情報をリセットします。 インタプリタロックを保持していなければなりません。

void PyInterpreterState_Delete( PyInterpreterState *interp)
インタプリタ状態オブジェクトを破壊します。 インタプリタロックを保持しておく必要はありません。 インタプリタ状態はPyInterpreterState_Clear() であらかじめ リセットしておかなければなりません。

PyThreadState* PyThreadState_New( PyInterpreterState *interp)
指定したインタプリタオブジェクトに属する新たなスレッド状態オブジェクトを 生成します。 インタプリタロックを保持しておく必要はありませんが、この関数を次々に 呼び出す必要がある場合には保持しておいたほうがよいでしょう。

void PyThreadState_Clear( PyThreadState *tstate)
スレッド状態オブジェクト内の全ての情報をリセットします。 インタプリタロックを保持していなければなりません。

void PyThreadState_Delete( PyThreadState *tstate)
スレッド状態オブジェクトを破壊します。 インタプリタロックを保持していなければなりません。 スレッド状態はPyThreadState_Clear() であらかじめ リセットしておかなければなりません。

PyThreadState* PyThreadState_Get( )
現在のスレッド状態を返します。 インタプリタロックを保持していなければなりません。 現在のスレッド状態が NULLなら、(呼び出し側が NULLチェックを しなくてすむように) この関数は致命的エラーを起こすようになっています。

PyThreadState* PyThreadState_Swap( PyThreadState *tstate)
現在のスレッド状態を tstate に指定したスレッド状態と入れ変えます。 tstate はNULLであってはなりません。 インタプリタロックを保持していなければなりません。

PyObject* PyThreadState_GetDict( )
戻り値: 借りた参照.
拡張モジュールがスレッド固有の状態情報を保存できるような辞書を返します。 各々の拡張モジュールが辞書に状態情報を保存するためには唯一のキーを 使わねばなりません。 現在のスレッド状態がない時にこの関数を呼び出してもかまいません。 この関数が NULLを返す場合、例外はまったく送出されず、呼び出し側は 現在のスレッド状態が利用できないと考えねばなりません。 バージョン2.3 以降で変更された 仕様: 以前は、現在のスレッドがアクティブなときのみ呼び出せる ようになっており、 NULL は例外が送出されたことを意味していました

int PyThreadState_SetAsyncExc( long id, PyObject *exc)
スレッド内で非同期的に例外を送出します。 id 引数はターゲットとなるスレッドのスレッド id です; exc は送出する例外オブジェクトです。 この関数は exc に対する参照を一切盗み取りません。 素朴な間違いを防ぐため、この関数を呼び出すには独自に C 拡張モジュール を書かねばなりません。 グローバルインタプリタロックを保持した状態で呼び出さなければなりません。 変更を受けたスレッド状態の数を返します; 1 よりも大きな数を返した場合、 何らかのトラブルに巻き込まれていることになり、exc を NULL にして再度呼び出すことで効果を打ち消さねばなりません。 この関数自体は例外を送出しません。 バージョン2.3 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 8. 初期化 (initialization)、終了処理 (finalization)、スレッド Up: 8. 初期化 (initialization)、終了処理 (finalization)、スレッド Next: 8.2 プロファイルとトレース (profiling and
Release 2.3.3, documentation updated on December 19, 2003.


8.2 プロファイルとトレース (profiling and tracing)

Python インタプリタは、プロファイル: 分析 (profile) や実行の トレース: 追跡 (trace) といった機能を組み込むために低水準の サポートを提供しています。このサポートは、プロファイルや デバッグ、適用範囲分析 (coverage analysis) ツールなどに使われます。

Python 2.2 になってから、この機能の実装は実質的に作り直され、 C から呼び出すためのインタフェースが追加されました。 この C インタフェースは、プロファイルやトレース作業時に、 Python レベルの呼び出し可能オブジェクトが呼び出されることによる オーバヘッドを避け、直接 C 関数呼び出しが行えるようにしています。 プロファイルやトレース機能の本質的な特性は変わっていません; インタフェースではとレース関数をスレッドごとにインストールでき、 トレース関数に報告される基本イベント (basic event) は以前の バージョンにおいて Python レベルのトレース関数で報告されていた ものと同じです。

int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)
PyEval_SetProfile() および PyEval_SetTrace() を使って登録できるトレース関数の形式です。最初のパラメタは オブジェクトで、登録関数に obj として渡されます。 frame はイベントが属している実行フレームオブジェクトで、 what は定数 PyTrace_CALL, PyTrace_EXCEPT, PyTrace_LINE あるいは PyTrace_RETURN のいずれかで、arg は what の値によって以下のように 異なります:

what の値 | arg の意味
PyTrace_CALL | 常に NULLです。
PyTrace_EXCEPT | sys.exc_info() の返す例外情報です。
PyTrace_LINE | 常に NULLです。
PyTrace_RETURN | 呼び出し側に返される予定の値です。

int PyTrace_CALL
関数やメソッドが新たに呼び出されたり、ジェネレータが新たなエントリの 処理に入ったことを報告する際の、Py_tracefunc のwhat の 値です。イテレータやジェネレータ関数の生成は、対応するフレーム内の Python バイトコードに制御の委譲 (control transfer) が起こらない ため報告されないので注意してください。

int PyTrace_EXCEPT
例外が送出された際のPy_tracefunc のwhat の値です。 現在実行されているフレームで例外がセットされ、何らかのバイトコードが 処理された後に、what にこの値がセットされた状態でコールバック 関数が呼び出されます。

この結果、例外の伝播によって Python が呼び出しスタックを逆戻りする 際に、各フレームから処理が戻るごとにコールバック関数が呼び出されます。 トレース関数だけがこれらのイベントを受け取ります; プロファイラは この種のイベントを必要としません。

int PyTrace_LINE
行番号イベントを報告するときに (プロファイル関数ではなく) トレース関数のwhat パラメタとして渡す値です。

int PyTrace_RETURN
関数呼び出しが例外の伝播なしに返るときに Py_tracefunc 関数what パラメタとして渡す値です。

void PyEval_SetProfile( Py_tracefunc func, PyObject *obj)
プロファイル関数を func に設定します。obj パラメタは 関数の第一パラメタとして渡され、何らかの Python オブジェクトかまたは NULLになります。プロファイル関数がスレッド状態を維持する必要が あるなら、各々のスレッドに異なる obj を使うことで、状態を 記憶しておく便利でスレッドセーフな場所を提供できます。プロファイル 関数は、モニタされているイベントのうち、行番号イベントを除く全ての イベントに対して呼び出されます。

void PyEval_SetTrace( Py_tracefunc func, PyObject *obj)
トレース関数を func にセットします。 PyEval_SetProfile() に似ていますが、トレース関数は 行番号イベントを受け取る点が違います。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 8.1 スレッド状態 (thread state) Up: 8. 初期化 (initialization)、終了処理 (finalization)、スレッド Next: 8.3 高度なデバッガサポート (advanced debugger
Release 2.3.3, documentation updated on December 19, 2003.


8.3 高度なデバッガサポート (advanced debugger support)

以下の関数は高度なデバッグツールでの使用のためだけのものです。

PyInterpreterState* PyInterpreterState_Head( )
インタプリタ状態オブジェクトからなるリストのうち、先頭にあるもの を返します。 バージョン2.2 以降で新規追加された 仕様です。

PyInterpreterState* PyInterpreterState_Next( PyInterpreterState *interp)
インタプリタ状態オブジェクトからなるリストのうち、interp の 次にあるものを返します。 バージョン2.2 以降で新規追加された 仕様です。

PyThreadState * PyInterpreterState_ThreadHead( PyInterpreterState *interp)
インタプリタ interp に関連付けられているスレッドからなるリストの うち、先頭にある PyThreadState オブジェクトを返します。 バージョン2.2 以降で新規追加された 仕様です。

PyThreadState* PyThreadState_Next( PyThreadState *tstate)
tstate と同じPyInterpreterState オブジェクトに属している スレッド状態オブジェクトのうち、tstate の次にあるものを返します。 バージョン2.2 以降で新規追加された 仕様です。
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 8.2 プロファイルとトレース (profiling and Up: 8. 初期化 (initialization)、終了処理 (finalization)、スレッド Next: 9. メモリ管理
Release 2.3.3, documentation updated on December 19, 2003.


9. メモリ管理

  • 9.1 概要
  • 9.2 メモリインタフェース
  • 9.3 例
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 8.3 高度なデバッガサポート (advanced debugger Up: Python/C API リファレンスマニュアル Next: 9.1 概要
Release 2.3.3, documentation updated on December 19, 2003.


9.1 概要

Python におけるメモリ管理には、全ての Python オブジェクトとデータ構造が 入ったプライベートヒープ (private heap) が必須です。プライベートヒープ の管理は、内部的には Python メモリマネージャ (Python memory manager) が確実に行います。Python メモリマネージャには、共有 (sharing)、 セグメント分割 (segmentation)、事前割り当て (preallocation)、 キャッシュ化 (caching) といった、様々な動的記憶管理の側面を 扱うために、個別のコンポーネントがあります。

最低水準層では、素のメモリ操作関数 (raw memory allocator) が オペレーティングシステムのメモリ管理機構とやりとりして、 プライベートヒープ内にPython 関連の全てのデータを記憶するのに 十分な空きがあるかどうか確認します。 素のメモリ操作関数の上には、いくつかのオブジェクト固有の メモリ操作関数があります。これらは同じヒープを操作し、 各オブジェクト型固有の事情に合ったメモリ管理ポリシを実装しています。 例えば、整数オブジェクトは文字列やタプル、辞書とは違ったやり方で ヒープ内で管理されます。というのも、整数には値を記憶する上で 特別な要件があり、速度/容量のトレードオフが存在するからです。 このように、 Python メモリマネジャは作業のいくつかをオブジェクト 固有のメモリ操作関数に委譲しますが、これらの関数が プライベートヒープからはみ出してメモリ管理を行わないように しています。

重要なのは、たとえユーザがいつもヒープ内のメモリブロックを指すような オブジェクトポインタを操作しているとしても、Python 用ヒープの管理は インタプリタ自体が行うもので、ユーザがそれを制御する余地はないと理解 することです。Python オブジェクトや内部使用されるバッファを入れるための ヒープ空間のメモリ確保は、必要に応じて、Python メモリマネージャがこの ドキュメント内で列挙しているPython/C API 関数群を介して行います。

メモリ管理の崩壊を避けるため、拡張モジュールの作者は決して Python オブジェクトを C ライブラリが公開している関数: malloc()、 calloc()、 realloc()および free()で操作しようとしては なりません。こうした関数を使うと、C のメモリ操作関数と Python メモリマネージャとの間で関数呼び出しが交錯します。 C のメモリ操作関数とPython メモリマネージャは異なる アルゴリズムで実装されていて、異なるヒープを操作するため、 呼び出しの交錯は致命的な結果を招きます。 とはいえ、個別の目的のためなら、 C ライブラリのメモリ操作関数を 使って安全にメモリを確保したり解放したりできます。 例えば、以下がそのような例です:

    PyObject *res;
    char *buf = (char *) malloc(BUFSIZ); /* for I/O */

    if (buf == NULL)
        return PyErr_NoMemory();
    ...Do some I/O operation involving buf...
    res = PyString_FromString(buf);
    free(buf); /* malloc'ed */
    return res;

この例では、I/O バッファに対するメモリ要求は C ライブラリのメモリ 操作関数を使っています。 Python メモリマネジャは戻り値として 返される文字列オブジェクトを確保する時にだけ必要です。

とはいえ、ほとんどの状況では、メモリの操作は Python ヒープに 固定して行うよう勧めます。なぜなら、Python ヒープは Python メモリマネジャの管理下にあるからです。 例えば、インタプリタを C で書かれた新たなオブジェクト型で拡張 する際には、ヒープでのメモリ管理が必要です。 Python ヒープを使った方がよいもう一つの理由として、拡張モジュールが 必要としているメモリについて Python メモリマネージャに 情報を提供 してほしいということがあります。 たとえ必要なメモリが内部的かつ非常に特化した用途に対して排他的に 用いられるものだとしても、全てのメモリ操作要求を Python メモリマネージャ に委譲すれば、インタプリタはより正確なメモリフットプリント (memory footprint) の全体像を把握できます。その結果、特定の状況では、 Python メモリマネージャがガベージコレクションやメモリのコンパクト化、 その他何らかの予防措置といった、適切な動作をトリガできることが あります。上の例で示したように C ライブラリのメモリ操作関数 を使うと、 I/O バッファ用に確保したメモリは Python メモリマネージャ の管理から完全に外れることに注意してください。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 9. メモリ管理 Up: 9. メモリ管理 Next: 9.2 メモリインタフェース
Release 2.3.3, documentation updated on December 19, 2003.


9.2 メモリインタフェース

Python ヒープに対してメモリを確保したり解放したりするために、 以下の関数セットが利用できます。これらの関数は ANSI C 標準に 従ってモデル化されていますが、0 バイトの領域を要求した際の 動作についても定義しています:

void* PyMem_Malloc( size_t n)
n バイトをメモリ確保し、確保されたメモリを指す void* 型のポインタを返します。確保要求に失敗した場合には NULL を 返します。 0 バイトをリクエストすると、可能ならば独立した非NULL の ポインタを返します。このポインタは PyMem_Malloc(1) を代わりに呼んだときのようなメモリ領域を指しています。 確保されたメモリ領域はいかなる初期化も行われていません。

void* PyMem_Realloc( void *p, size_t n)
p が指しているメモリブロックを n バイトにサイズ変更 します。メモリの内容のうち、新旧のサイズのうち小さい方までの 領域は変更されません。p が NULLならば、この関数は PyMem_Malloc(n) と等価になります; それ以外の場合で、n がゼロに等しければ、 メモリブロックはサイズ変更されますが、解放されず、非 NULLの ポインタを返します。p の値をNULLにしないのなら、 以前呼び出した PyMem_Malloc() や PyMem_Realloc() の返した値でなければなりません。

void PyMem_Free( void *p)
p が指すメモリブロックを解放します。p は 以前呼び出した PyMem_Malloc() や PyMem_Realloc() の返した値でなければなりません。 それ以外の場合や、すでに PyMem_Free(p) を 呼び出した後だった場合、未定義の動作になります。 p が NULLなら、何も行いません。

以下に挙げる型対象のマクロは利便性のために提供されているものです。 TYPE は任意の C の型を表します。

TYPE* PyMem_New( TYPE, size_t n)
PyMem_Malloc() と同じですが、 (n * sizeof(TYPE)) バイトのメモリを確保します。 TYPE* に型キャストされたポインタを返します。 メモリには何の初期化も行われていません。

TYPE* PyMem_Resize( void *p, TYPE, size_t n)
PyMem_Realloc() と同じですが、 (n * sizeof(TYPE)) バイトにサイズ変更されたメモリを 確保します。 TYPE* に型キャストされたポインタを返します。

void PyMem_Del( void *p)
PyMem_Free() と同じです。

上記に加えて、C API 関数を介することなく Python メモリ操作関数を 直接呼び出すための以下のマクロセットが提供されています。 ただし、これらのマクロは Python バージョン間でのバイナリ互換性を 保てず、それゆえに拡張モジュールでは撤廃されているので注意してください。

PyMem_MALLOC()、
PyMem_REALLOC()、
 PyMem_FREE()。

PyMem_NEW()、
PyMem_RESIZE()、
PyMem_DEL()。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 9.1 概要 Up: 9. メモリ管理 Next: 9.3 例
Release 2.3.3, documentation updated on December 19, 2003.


9.3 例

最初に述べた関数セットを使って、9.1 節の例を Python ヒープに I/O バッファをメモリ確保するように書き換えたものを 以下に示します:

    PyObject *res;
    char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */

    if (buf == NULL)
        return PyErr_NoMemory();
    /* ...Do some I/O operation involving buf... */
    res = PyString_FromString(buf);
    PyMem_Free(buf); /* allocated with PyMem_Malloc */
    return res;

同じコードを型対象の関数セットで書いたものを以下に示します:

    PyObject *res;
    char *buf = PyMem_New(char, BUFSIZ); /* for I/O */

    if (buf == NULL)
        return PyErr_NoMemory();
    /* ...Do some I/O operation involving buf... */
    res = PyString_FromString(buf);
    PyMem_Del(buf); /* allocated with PyMem_New */
    return res;

上の二つの例では、バッファを常に同じ関数セットに属する関数で 操作していることに注意してください。 実際、あるメモリブロックに対する操作は、異なるメモリ操作機構を 混用する危険を減らすために、同じメモリ API ファミリを使って行うことが 必要です。以下のコードには二つのエラーがあり、そのうちの一つには 異なるヒープを操作する別のメモリ操作関数を混用しているので 致命的 (Fatal) とラベルづけをしています。

char *buf1 = PyMem_New(char, BUFSIZ);
char *buf2 = (char *) malloc(BUFSIZ);
char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
...
PyMem_Del(buf3);  /* Wrong -- should be PyMem_Free() */
free(buf2);       /* Right -- allocated via malloc() */
free(buf1);       /* Fatal -- should be PyMem_Del()  */

素のメモリブロックを Python ヒープ上で操作する関数に加え、 PyObject_New()、 PyObject_NewVar()、および PyObject_Del() を使うと、 Python におけるオブジェクトを メモリ確保したり解放したりできます。またこれらの関数には マクロ PyObject_NEW()、 PyObject_NEW_VAR()、 および PyObject_DEL() が対応します。

これらの関数については、次章の C による新しいオブジェクト型の定義や 実装に関する記述の中で説明します。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 9.2 メモリインタフェース Up: 9. メモリ管理 Next: 10. オブジェクト実装サポート (object implementation
Release 2.3.3, documentation updated on December 19, 2003.


10. オブジェクト実装サポート (object implementation support)

この章では、新しいオブジェクト型 (new object type) を定義する際に 使われる関数、型、およびマクロについて説明します。

  • 10.1 オブジェクトをヒープ上にメモリ確保する
  • 10.2 共通のオブジェクト構造体 (common object structure)
  • 10.3 型オブジェクト
  • 10.4 マップ型オブジェクト構造体 (mapping object structure)
  • 10.5 数値オブジェクト構造体 (number object structure)
  • 10.6 配列オブジェクト構造体 (sequence object structure)
  • 10.7 バッファオブジェクト構造体 (buffer object structure)
  • 10.8 イテレータプロトコルをサポートする
  • 10.9 循環参照ガベージコレクションをサポートする
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 9.3 例 Up: Python/C API リファレンスマニュアル Next: 10.1 オブジェクトをヒープ上にメモリ確保する
Release 2.3.3, documentation updated on December 19, 2003.


10.1 オブジェクトをヒープ上にメモリ確保する

PyObject* _PyObject_New( PyTypeObject *type)
戻り値: 新たな参照.

PyVarObject* _PyObject_NewVar( PyTypeObject *type, int size)
戻り値: 新たな参照.

void _PyObject_Del( PyObject *op)

PyObject* PyObject_Init( PyObject *op, PyTypeObject *type)
戻り値: 借りた参照.
新たにメモリ確保されたオブジェクト op に対し、型と初期状態での 参照 (initial reference) を初期化します。 初期化されたオブジェクトを返します。type からそのオブジェクトが 循環参照ガベージ検出の機能を有する場合、検出機構が監視対象とする オブジェクトのセットに追加されます。 オブジェクトの他のフィールドには影響を及ぼしません。

PyVarObject* PyObject_InitVar( PyVarObject *op, PyTypeObject *type, int size)
PyObject_Init() の全ての処理を行い、可変サイズオブジェクト の場合には長さ情報も初期化します。

TYPE* PyObject_New( TYPE, PyTypeObject *type)
戻り値: 新たな参照.
C 構造体型 TYPE と Python 型オブジェクト type を使って 新たな Python オブジェクトをメモリ確保します。 Python オブジェクトヘッダで定義されていないフィールドは初期化されません; オブジェクトの参照カウントは 1 になります。メモリ確保のサイズは 型オブジェクトの tp_basicsize で決定します。

TYPE* PyObject_NewVar( TYPE, PyTypeObject *type, int size)
戻り値: 新たな参照.
C 構造体型 TYPE と Python 型オブジェクト type を使って 新たな Python オブジェクトをメモリ確保します。 Python オブジェクトヘッダで定義されていないフィールドは初期化されません。 確保されたメモリは、TYPE 構造体に加え、vartype の tp_itemsize フィールドで指定されているサイズ中の size フィールドを 収容できます。この関数は、例えばタプルのように生成時にサイズを決定 できるオブジェクトを実装する際に便利です。一連の複数のフィールドに 対するアロケーション操作を一つにして埋め込むと、アロケーション回数 が減り、メモリ管理の処理効率が向上します。

void PyObject_Del( PyObject *op)
PyObject_New() や PyObject_NewVar() で 確保されたメモリを解放します。この関数は、通常オブジェクトの型に 指定されている tp_dealloc ハンドラ内で呼び出します。 この関数を呼び出した後では、オブジェクトのメモリ領域はもはや有効な Python オブジェクトを表現してはいないので、オブジェクトのフィールド に対してアクセスしてはなりません。

TYPE* PyObject_NEW( TYPE, PyTypeObject *type)
戻り値: 新たな参照.
安全性と引き換えにパフォーマンスを高めるためのPyObject_New() のマクロ版です。 type が NULL かどうかチェックしません。

TYPE* PyObject_NEW_VAR( TYPE, PyTypeObject *type, int size)
戻り値: 新たな参照.
安全性と引き換えにパフォーマンスを高めるためのPyObject_NewVar() のマクロ版です。 type が NULL かどうかチェックしません。

void PyObject_DEL( PyObject *op)
PyObject_Del()のマクロ版です。

PyObject* Py_InitModule( char *name, PyMethodDef *methods)
戻り値: 借りた参照.
name と関数のテーブルに基づいて新たなモジュールオブジェクトを 生成し、生成されたモジュールオブジェクトを返します。 バージョン2.3 以降で変更された 仕様: 以前のバージョンの Python では、methods 引数の 値としてNULL をサポートしていませんでした

PyObject* Py_InitModule3( char *name, PyMethodDef *methods, char *doc)
戻り値: 借りた参照.
name と関数のテーブルに基づいて新たなモジュールオブジェクトを 生成し、生成されたモジュールオブジェクトを返します。 doc が NULLでない場合、モジュールの docstring として 使われます。 バージョン2.3 以降で変更された 仕様: 以前のバージョンの Python では、methods 引数の 値としてNULL をサポートしていませんでした

PyObject* Py_InitModule4( char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver)
戻り値: 借りた参照.
name と関数のテーブルに基づいて新たなモジュールオブジェクトを 生成し、生成されたモジュールオブジェクトを返します。 doc が NULLでない場合、モジュールの docstring として 使われます。self がNULLでない場合、モジュール内の各関数 の第一引数として渡されます (NULLの時には第一引数も NULLになります)。 (この関数は実験的な機能のために追加されたもので、現在の Python の バージョンで使われてはいないはずです。) apiver に渡してよい値は、 PYTHON_API_VERSION で定義されている定数だけです。

注意: この関数のほとんどの用途は、代わりにPy_InitModule3() を使えるはずです; 本当にこの関数を使いたいときにだけ利用してください バージョン2.3 以降で変更された 仕様: 以前のバージョンの Python では、methods 引数の 値としてNULL をサポートしていませんでした

DL_IMPORT

PyObject _Py_NoneStruct
Python からは None に見えるオブジェクトです。この値への アクセスは、このオブジェクトへのポインタを評価するPy_None マクロを使わねばなりません。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 10. オブジェクト実装サポート (object implementation Up: 10. オブジェクト実装サポート (object implementation Next: 10.2 共通のオブジェクト構造体 (common object
Release 2.3.3, documentation updated on December 19, 2003.


10.2 共通のオブジェクト構造体 (common object structure)

Python では、オブジェクト型を定義する上で数多くの構造体が使われます。 この節では三つの構造体とその利用方法について説明します。

全ての Python オブジェクトは、オブジェクトのメモリ内表現の先頭部分に ある少数のフィールドを完全に共有しています。このフィールドは PyObject および PyVarObject 型で表現されます。 PyObject 型や PyVarObject 型もまた、他の全ての Python オブジェクトを定義する上で直接的・間接的に使われているマクロを 使って定義されています。

PyObject
全てのオブジェクト型はこの型を拡張したものです。 この型には、あるオブジェクトに対するオブジェクトとしてのポインタを Python から扱う必要がある際に必要な情報が入っています。 通常に ``リリースされている'' ビルドでは、この構造体にはオブジェクトの 参照カウントと、オブジェクトに対応する型オブジェクトだけが入っています。

PyObject_HEAD マクロ展開で定義されているフィールドに対応します。

PyVarObject
PyObject を拡張して、ob_size フィールドを追加した ものです。この構造体は、長さ (length) の概念を持つオブジェクト だけに対して使います。この型が Python/C API で使われることは ほとんどありません。 PyObject_VAR_HEAD マクロ展開で定義されているフィールドに対応します。

PyObject および PyVarObject の定義には以下のマクロが 使われています:

PyObject_HEAD
PyObject 型のフィールド宣言に展開されるマクロです; 可変でない長さを持つオブジェクトを表現する新たな型を宣言する 場合に使います。展開によってどのフィールドが宣言されるかは、 Py_TRACE_REFS の定義に依存します。 デフォルトでは、Py_TRACE_REFS は定義されておらず、 PyObject_HEAD は以下のコードに展開されます:
    int ob_refcnt;
    PyTypeObject *ob_type;
Py_TRACE_REFS が定義されている場合、以下のように展開 されます:
    PyObject *_ob_next, *_ob_prev;
    int ob_refcnt;
    PyTypeObject *ob_type;

PyObject_VAR_HEAD
マクロです。PyVarObject 型のフィールド宣言に展開されるマクロです; インスタンスによって可変の長さを持つオブジェクトを表現する新たな型を 宣言する場合に使います。マクロは常に以下のように展開されます:
    PyObject_HEAD
    int ob_size;
マクロ展開結果の一部にPyObject_HEAD が含まれており、 PyObject_HEAD の展開結果はPy_TRACE_REFS の定義に依存します。

PyObject_HEAD_INIT

PyCFunction
ほとんどの Python の呼び出し可能オブジェクトを C で実装する際に 用いられている関数の型です。 この型の関数は二つの PyObject* 型パラメタをとり、 PyObject* 型の値を返します。戻り値を NULLにする場合、 例外をセットしておかなければなりません。NULLでない値を返す場合、 戻り値は Python に関数の戻り値として公開される値として解釈されます。 この型の関数は新たな参照を返さなければなりません。

PyMethodDef
拡張型のメソッドを記述する際に用いる構造体です。この構造体には 4 つのフィールドがあります:

フィールド | C データ型 | 意味
ml_name | char * | メソッド名
ml_meth | PyCFunction | C 実装へのポインタ
ml_flags | int | 呼び出しをどのように行うかを示すフラグビット
ml_doc | char * | docstring の内容を指すポインタ

ml_meth は C の関数ポインタです。関数は別の型で定義 されていてもかまいませんが、常に PyObject* を返します。 関数が PyFunction でない場合、メソッドテーブル内でキャスト を行うようコンパイラが要求することになるでしょう。 PyCFunction では最初のパラメタがPyObject* 型で あると定義していますが、固有の C 型を self オブジェクトに 使う実装はよく行われています。

ml_flags フィールドはビットフィールドで、以下のフラグが入ります。 個々のフラグは呼び出し規約 (calling convention) や束縛規約 (binding convention) を表します。 呼び出し規約フラグでは、METH_VARARGS および METH_KEYWORDS を組み合わせられます (ただし、 METH_KEYWORDS 単体の指定を行っても METH_VARARGS | METH_KEYWORDS と 同じなので注意してください)。 呼び出し規約フラグは束縛フラグと組み合わせられます。

METH_VARARGS
PyCFunction 型のメソッドで典型的に使われる呼び出し規約です。 関数はPyObject* 型の引数値を二つ要求します。最初の引数は メソッドの self オブジェクトです; モジュール関数の場合、 Py_InitModule4() に与えることになる値が入ります (NULL にするとPy_InitModule() が使われます)。 第二のパラメタ (よく args と呼ばれます) は、全ての引数を 表現するタプルオブジェクトです。パラメタは通常、 PyArg_ParseTuple() や PyArg_UnpackTuple で処理されます。

METH_KEYWORDS
このフラグを持つメソッドはPyCFunctionWithKeywords 型でなければなりません。PyCFunctionWithKeywords は 三つのパラメタ:self、 args、 およびキーワード引数 全てからなる辞書、を要求します。このフラグは通常 METH_VARARGS と組み合わされ、パラメタは PyArg_ParseTupleAndKeywords() で処理されます。

METH_NOARGS
引数のないメソッドは、METH_NOARGS フラグをつけた場合、 必要な引数が指定されているかをチェックしなくなります。 こうしたメソッドは PyCFunction 型でなくてはなりません。 オブジェクトのメソッドに使った場合、第一のパラメタは self になり、オブジェクトインスタンスへの参照を保持することになります。 いずれにせよ、第二のパラメタは NULLになります。

METH_O
単一のオブジェクト引数だけをとるメソッドは、 PyArg_ParseTuple() を引数 "O" にして呼び出す代わりに、 METH_O フラグつきで指定できます。メソッドは PyCFunction 型で、self パラメタと単一の引数を表現する PyObject* パラメタを伴います。

METH_OLDARGS
この呼び出し規約は撤廃されました。メソッドはPyCFunction 型で なければなりません。第二引数は、引数がない場合には NULL、単一の 引数の場合にはその引数オブジェクト、複数個の引数の場合には引数 オブジェクトからなるタプルです。この呼び出し規約を使うと、複数個の 引数の場合と、単一のタプルが唯一引数の場合を区別できなくなってしまいます。

以下の二つの定数は、呼び出し規約を示すものではなく、 クラスのメソッドとして使う際の束縛方式を示すものです。 モジュールに対して定義された関数で用いてはなりません。 メソッドに対しては、最大で一つしかこのフラグをセットできません。

METH_CLASS
メソッドの最初の引数には、型のインスタンスではなく型オブジェクト が渡されます。このフラグは 組み込み関数 classmethod()を使って生成するのと同じクラスメソッド (class method) を生成するために使われます。 バージョン2.3 以降で新規追加された 仕様です。

METH_STATIC
メソッドの最初の引数んは、型のインスタンスではなく NULL が 渡されます。このフラグは、 staticmethod() を使って生成するのと同じ静的メソッド (static method) を生成するために使われます。 バージョン2.3 以降で新規追加された 仕様です。

PyObject* Py_FindMethod( PyMethodDef table[], PyObject *ob, char *name)
戻り値: 新たな参照.
C で実装された拡張型の束縛メソッドオブジェクトを返します。 PyObject_GenericGetAttr() 関数を使わない tp_getattro や tp_getattr ハンドラを実装する際に 便利です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 10.1 オブジェクトをヒープ上にメモリ確保する Up: 10. オブジェクト実装サポート (object implementation Next: 10.3 型オブジェクト
Release 2.3.3, documentation updated on December 19, 2003.


10.3 型オブジェクト

新形式の型を定義する構造体: PyTypeObject 構造体は、おそらく Python オブジェクトシステムの中で最も重要な構造体の一つでしょう。 型オブジェクトはPyObject_*() 系や PyType_*() 系の関数で扱えますが、ほとんどの Python アプリケーションにとって、 さして面白みのある機能を提供しません。 とはいえ、型オブジェクトはオブジェクトがどのように振舞うかを決める 基盤ですから、インタプリタ自体や新たな型を定義する拡張モジュールでは 非常に重要な存在です。

型オブジェクトは標準の型 (standard type) に比べるとかなり大きな 構造体です。その理由は、型オブジェクトがある型の様々な機能を実現する 小さな機能単位を実装した C 関数へのポインタが大部分を占めるような 多数の値を保持しているからです。この節では、型オブジェクトの各 フィールドについて詳細を説明します。各フィールドは、構造体内で 出現する順番に説明されています。

Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc, intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor, freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc, cmpfunc, reprfunc, hashfunc

PyTypeObject の構造体定義はInclude/object.h で見つけられるはずです。参照の手間を省くために、ここでは 定義を繰り返します:

typedef struct _typeobject {
    PyObject_VAR_HEAD
    char *tp_name; /* For printing, in format "<module>.<name>" */
    int tp_basicsize, tp_itemsize; /* For allocation */

    /* Methods to implement standard operations */

    destructor tp_dealloc;
    printfunc tp_print;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    cmpfunc tp_compare;
    reprfunc tp_repr;

    /* Method suites for standard classes */

    PyNumberMethods *tp_as_number;
    PySequenceMethods *tp_as_sequence;
    PyMappingMethods *tp_as_mapping;

    /* More standard operations (here for binary compatibility) */

    hashfunc tp_hash;
    ternaryfunc tp_call;
    reprfunc tp_str;
    getattrofunc tp_getattro;
    setattrofunc tp_setattro;

    /* Functions to access object as input/output buffer */
    PyBufferProcs *tp_as_buffer;

    /* Flags to define presence of optional/expanded features */
    long tp_flags;

    char *tp_doc; /* Documentation string */

    /* Assigned meaning in release 2.0 */
    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* Assigned meaning in release 2.1 */
    /* rich comparisons */
    richcmpfunc tp_richcompare;

    /* weak reference enabler */
    long tp_weaklistoffset;

    /* Added in release 2.2 */
    /* Iterators */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

    /* Attribute descriptor and subclassing stuff */
    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
    struct _typeobject *tp_base;
    PyObject *tp_dict;
    descrgetfunc tp_descr_get;
    descrsetfunc tp_descr_set;
    long tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Low-level free-memory routine */
    inquiry tp_is_gc; /* For PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* method resolution order */
    PyObject *tp_cache;
    PyObject *tp_subclasses;
    PyObject *tp_weaklist;

} PyTypeObject;
Download as text (original file name: typestruct.h).

型オブジェクト構造体はPyVarObject 構造体を拡張したものです。 ob_size フィールドは、(通常 class 文が呼び出す type_new() で生成される) 動的な型に使います。 PyType_Type (メタタイプ) はtp_itemsize を初期化するので 注意してください。すなわち、インスタンス (つまり型オブジェクト) には ob_size フィールドがなければなりません。

PyObject* _ob_next
PyObject* _ob_prev
これらのフィールドはマクロ Py_TRACE_REFS が定義されている 場合のみ存在します。PyObject_HEAD_INIT マクロを使うと、 フィールドを NULL に初期化します。静的にメモリ確保されている オブジェクトでは、これらのフィールドは常に NULLのままです。 動的にメモリ確保されるオブジェクトの場合、これら二つのフィールドは、 ヒープ上の全ての 存続中のオブジェクトからなる二重リンクリスト でオブジェクトをリンクする際に使われます。 このことは様々なデバッグ目的に利用できます; 現状では、環境変数 PYTHONDUMPREFS が設定されているときに、プログラムの実行 終了時点で存続しているオブジェクトを出力するのが唯一の用例です。

サブタイプはこのフィールドを継承しません。

int ob_refcnt
かたオブジェクトの参照カウントで、PyObject_HEAD_INIT は この値を 1 に初期化します。静的にメモリ確保された型オブジェクト では、型のインスタンス (ob_type が該当する型を指している オブジェクト) は参照をカウントする対象にはなりません。 動的にメモリ確保される型オブジェクトの場合、インスタンスは 参照カウントの対象になります。

サブタイプはこのフィールドを継承しません。

PyTypeObject* ob_type
型自体の型、別の言い方をするとメタタイプです。 PyObject_HEAD_INIT マクロで初期化され、通常は &PyType_Type になります。しかし、(少なくとも) Windows で 利用できる動的ロード可能な拡張モジュールでは、コンパイラは 有効な初期化ではないと文句をつけます。そこで、ならわしとして、 PyObject_HEAD_INIT には NULL を渡して初期化しておき、 他の操作を行う前にモジュールの初期化関数で明示的にこのフィールドを 初期化することになっています。この操作は以下のように行います:

Foo_Type.ob_type = &PyType_Type;

上の操作は、該当する型のいかなるインスタンス生成よりも前に しておかねばなりません。PyType_Ready() は ob_type が NULLかどうか調べ、NULLの場合には 初期化します: Python 2.2 では、&PyType_Type にセット します; in Python 2.2.1 およびそれ以降では基底クラスの ob_type フィールドに初期化します。 ob_type が非ゼロの場合、PyType_Ready() は このフィールドを変更しません。

Python 2.2 では、サブタイプはこのフィールドを継承しません。 2.2.1 と 2.3 以降では、サブタイプはこのフィールドを継承します。

int ob_size
静的にメモリ確保されている型オブジェクトの場合、このフィールドは ゼロに初期化されます。動的にメモリ確保されている型オブジェクトの 場合、このフィールドは内部使用される特殊な意味を持ちます。

サブタイプはこのフィールドを継承しません。

char* tp_name
型の名前が入っている NUL 終端された文字列へのポインタです。 モジュールのグローバル変数としてアクセスできる型の場合、 この文字列は完全なモジュール名、ドット、そして型の名前と続く 文字列になります; 組み込み型の場合、ただの型の名前です。 モジュールがあるパッケージのサブモジュールの場合、完全なパッケージ名が 完全なモジュール名の一部になっています。例えば、パッケージ P 内のサブモジュール Q に入っているモジュールM 内で 定義されているT は、tp_name を "P.Q.M.T" に 初期化します。

動的にメモリ確保される型オブジェクトの場合、このフィールドは 単に型の名前になり、モジュール名は型の辞書内でキー '__module__' に対する値として明示的に保存されます。

静的にメモリ確保される型オブジェクトの場合、tp_name フィールド にはドットが入っているはずです。最後のドットよりも前にある 部分文字列全体は __module__ 属性として、また ドットよりも後ろにある部分は__name__ 属性としてアクセスできます。

ドットが入っていない場合、tp_name フィールドの内容全てが __name__ 属性になり、 __module__ 属性は (前述のように型の辞書内で明示的にセットしないかぎり) 未定義になります。 このため、こうした型オブジェクトは pickle 化できないことになります。

サブタイプはこのフィールドを継承しません。

int tp_basicsize
int tp_itemsize
これらのフィールドは、型インスタンスのバイトサイズを計算できる ようにします。

型には二つの種類があります: 固定長インスタンスの型は、 tp_itemsize フィールドがゼロで、可変長インスタンスの方は tp_itemsize フィールドが非ゼロの値になります。 固定長インスタンスの型の場合、全てのインスタンスは等しく tp_basicsize で与えられたサイズになります。

可変長インスタンスの型の場合、インスタンスにはob_size フィールドがなくてはならず、インスタンスのサイズは N をオブジェクトの ``長さ'' として、tp_basicsize と N かける tp_itemsize の加算になります。N の値は通常、インスタンスの ob_size フィールドに記憶されます。ただし例外がいくつかあります: 例えば、長整数では負の値を ob_size に使って、インスタンスの 表す値が負であることを示し、 N 自体は abs(ob_size) になります。また、ob_size フィールドがあるからといって、 必ずしもインスタンスが可変長であることを意味しません (例えば、 リスト型の構造体は固定長のインスタンスになるにもかかわらず、 インスタンスにはちゃんと意味を持った ob_size フィールドが あります)。

基本サイズには、PyObject_HEAD マクロまたは PyObject_VAR_HEAD マクロ (インスタンス構造体を 宣言するのに使ったどちらかのマクロ) で宣言されているフィールド が入っています。さらに、_ob_prev および _ob_next フィールドがある場合、これらのフィールドもサイズに加算されます。

従って、tp_basicsize の正しい初期化パラメタを得るには、 インスタンスデータのレイアウトを宣言するのに使う構造体に対して sizeof 演算子を使うしかありません。 基本サイズには、GC ヘッダサイズは入っていません (これは Python 2.2 からの新しい仕様です; 2.1 や 2.0 では、GC ヘッダサイズは tp_basicsize に入っていました)。

バイト整列 (alignment) に関する注釈: 変数の各要素を配置する際に特定の バイト整列が必要となる場合、tp_basicsize の値に 気をつけなければなりません。一例: 例えばある型がdouble の 配列を実装しているとします。tp_itemsize は sizeof(double) です。(double のバイト整列条件に従って) tp_basicsize がsizeof(double) の個数分のサイズに なるようにするのはプログラマの責任です。

destructor tp_dealloc
インスタンスのデストラクタ関数へのポインタです。この関数は (単量子None やEllipsis の場合のように、インスタンスが 決してメモリ解放されない型でない限り) 必ず定義しなければなりません。

デストラクタ関数は、Py_DECREF() や Py_XDECREF() マクロで、操作後の参照カウントがゼロになった際に呼び出されます。 呼び出された時点では、インスタンスはまだ存在しますが、インスタンスに 対する参照は全ない状態です。デストラクタ関数はインスタンスが保持している 全ての参照を解放し、インスタンスが確保している全てのメモリバッファを (バッファの確保時に使った関数に対応するメモリ解放関数を使って) 解放し、最後に (かならず最後に行う操作として) その型の tp_free 関数を呼び出します。ある型がサブタイプを作成できない (Py_TPFLAGS_BASETYPE フラグがセットされていない) 場合、 tp_free の代わりにオブジェクトのメモリ解放関数 (deallocator) を 直接呼び出してもかまいません。オブジェクトのメモリ解放関数は、 インスタンスのメモリ確保を行う際に使った関数と同じファミリでなければ なりません; インスタンスを PyObject_New() や PyOject_VarNew() でメモリ確保した場合には、通常 PyObject_Del() を使い、PyObject_GC_New() や PyObject_GC_VarNew() で確保した場合には PyObject_GC_Del() を使います。

サブタイプはこのフィールドを継承します。

printfunc tp_print
オプションのフィールドです。ポインタで、インスタンスの出力 (print) を 行う関数を指します。

出力関数は、インスタンスが 実体のある (real) ファイルに出力 される場合にのみ呼び出されます; (StringIO インスタンスのような) 擬似ファイルに出力される場合には、インスタンスの tp_repr や tp_str が指す関数が呼び出され、文字列への変換を行います。 また、tp_print が NULLの場合にもこれらの関数が呼び出され ます。 tp_repr や tp_str と異なる出力を生成するような tp_print は、決して型に実装してはなりません。

出力関数はPyObject_Print() と同じシグネチャ: int tp_print(PyObject *self, FILE *file, int flags) で呼び出されます。self 引数は出力するインスタンスを指します。 file 引数は出力先となる標準入出力 (stdio) ファイルです。 flags 引数はフラグビットを組み合わせた値です。 現在定義されているフラグビットは Py_PRINT_RAW のみです。 Py_PRINT_RAW フラグビットがセットされていれば、 インスタンスはtp_str と同じ書式で出力されます。 Py_PRINT_RAW フラグビットがクリアならば、 インスタンスはtp_repr と同じ書式で出力されます。 この関数は、操作中にエラーが生じた場合、-1 を返して例外状態を セットしなければなりません。

tp_print フィールドは撤廃されるかもしれません。いずれにせよ、 tp_print は定義せず、代わりにtp_repr や tp_str に頼って出力を行うようにしてください。

サブタイプはこのフィールドを継承します。

getattrfunc tp_getattr
オプションのフィールドです。ポインタで、 get-attribute-string を行う関数を指します。

このフィールドは撤廃されています。このフィールドを定義する場合、 tp_getattro 関数と同じように動作し、属性名は Python 文字列 オブジェクトではなく C 文字列で指定するような関数を指すように しなければなりません。シグネチャは PyObject_GetAttrString() と同じです。

このフィールドはtp_getattro と共にサブタイプに継承 されます: すなわち、サブタイプのtp_getattr および tp_getattro が共に NULLの場合、サブタイプは 基底タイプからtp_getattr と tp_getattro を一緒に 継承します。

setattrfunc tp_setattr
オプションのフィールドです。ポインタで、 set-attribute-string を行う関数を指します。

このフィールドは撤廃されています。このフィールドを定義する場合、 tp_setattro 関数と同じように動作し、属性名は Python 文字列 オブジェクトではなく C 文字列で指定するような関数を指すように しなければなりません。シグネチャは PyObject_SetAttrString() と同じです。

このフィールドはtp_setattro と共にサブタイプに継承 されます: すなわち、サブタイプのtp_setattr および tp_setattro が共に NULLの場合、サブタイプは 基底タイプからtp_setattr と tp_setattro を一緒に 継承します。

cmpfunc tp_compare
オプションのフィールドです。ポインタで、 三値比較 (three-way comparison) を行う関数を指します。

シグネチャはPyObject_Compare() と同じです。 この関数は self が other よりも大きければ 1、 self と other の値が等しければ 0、 self が other より小さければ -1 を返します。 この関数は、比較操作中にエラーが生じた場合、例外状態をセットして -1 を返さねばなりません。

このフィールドはtp_richcompare およびtp_hash と共にサブタイプに継承されます: すなわち、サブタイプの tp_compare 、tp_richcompare および tp_hash が共に NULLの場合、サブタイプは 基底タイプからtp_compare、tp_richcompare、 tp_hash の三つを一緒に継承します。

reprfunc tp_repr
オプションのフィールドです。ポインタで、 組み込み関数repr() を実装している 関数を指します。

シグネチャはPyObject_Repr() と同じです。 この関数は文字列オブジェクトか Unicode オブジェクトを返さねば なりません。理想的には、この関数が返す文字列は、適切な環境で eval() に渡した場合、同じ値を持つオブジェクトになるような 文字列でなければなりません。不可能な場合には、オブジェクトの型と 値から導出した内容の入った "<" から始まって ">" で終わる文字列を返さねば なりません。

このフィールドが設定されていない場合、"<%s object at %p>" の形式をとる文字列が返されます。 %s は型の名前に、 %p はオブジェクトのメモリアドレスに置き換えられます。

サブタイプはこのフィールドを継承します。

PyNumberMethods *tp_as_number;

XXX

PySequenceMethods *tp_as_sequence;

XXX

PyMappingMethods *tp_as_mapping;

XXX

hashfunc tp_hash
オプションのフィールドです。ポインタで、 組み込み関数hash() を実装している 関数を指します。

シグネチャはPyObject_Hash() と同じです。 この関数は C の long 型の値を返さねばなりません。 通常時には -1 を戻り値にしてはなりません; ハッシュ値の 計算中にエラーが生じた場合、関数は例外をセットして-1 を 返さねばなりません。

このフィールドが設定されていない場合、二つの可能性があります: tp_compare および tp_richcompare フィールドの 両方が NULLの場合、オブジェクトのアドレスに基づいたデフォルトの ハッシュ値が返されます; それ以外の場合、TypeError が送出されます。

このフィールドはtp_compare およびtp_richcompare と共にサブタイプに継承されます: すなわち、サブタイプの tp_compare 、tp_richcompare および tp_hash が共に NULLの場合、サブタイプは 基底タイプからtp_compare、tp_richcompare、 tp_hash の三つを一緒に継承します。

ternaryfunc tp_call
オプションのフィールドです。ポインタで、 オブジェクトの呼び出しを実装している 関数を指します。 オブジェクトが呼び出し可能でない場合には NULL にしなければ なりません。シグネチャは PyObject_Call() と同じです。

サブタイプはこのフィールドを継承します。

reprfunc tp_str
オプションのフィールドです。ポインタで、 組み込みの演算 str() を実装している 関数を指します。(str が型の一つになったため、 str() は str のコンストラクタを呼び出す ことに注意してください。このコンストラクタは実際の処理を行う 上でPyObject_Str() を呼び出し、さらに PyObject_Str() がこのハンドラを呼び出すことになります。)

シグネチャはPyObject_Str() と同じです; この関数は文字列オブジェクトか Unicode オブジェクトを返さねばなりません。 また、この関数はオブジェクトを ``分かりやすく (friendly)'' 表現 した文字列を返さねばなりません。というのは、この文字列は print 文で使われることになる表記だからです。

このフィールドが設定されていない場合、文字列表現を返すためには PyObject_Repr() が呼び出されます。

サブタイプはこのフィールドを継承します。

getattrofunc tp_getattro
オプションのフィールドです。ポインタで、 get-attribute を実装している関数を指します。

シグネチャはPyObject_GetAttr() と同じです。 対する通常の属性検索を実装しているPyObject_GenericGetAttr() をこのフィールドに設定しておくと往々にして便利です。

このフィールドはtp_getattr と共にサブタイプに継承 されます: すなわち、サブタイプのtp_getattr および tp_getattro が共に NULLの場合、サブタイプは 基底タイプからtp_getattr と tp_getattro を一緒に 継承します。

setattrofunc tp_setattro
オプションのフィールドです。ポインタで、 set-attribute を行う関数を指します。

シグネチャはPyObject_SetAttr() と同じです。 対する通常の属性設定を実装しているPyObject_GenericSetAttr() をこのフィールドに設定しておくと往々にして便利です。

このフィールドはtp_setattr と共にサブタイプに継承 されます: すなわち、サブタイプのtp_setattr および tp_setattro が共に NULLの場合、サブタイプは 基底タイプからtp_setattr と tp_setattro を一緒に 継承します。

PyBufferProcs* tp_as_buffer
バッファインタフェースを実装しているオブジェクトにのみ関連する、 一連のフィールド群が入った別の構造体を指すポインタです。 構造体内の各フィールドは ``バッファオブジェクト構造体'' (10.7 節) で説明します。

tp_as_buffer フィールド自体は継承されませんが、フィールド内に 入っているフィールドは個別に継承されます。

long tp_flags
このフィールドは様々なフラグからなるビットマスクです。 いくつかのフラグは、特定の状況において変則的なセマンティクスが適用 されることを示します; その他のフラグは、型オブジェクト (あるいはtp_as_number、tp_as_sequence、 tp_as_mapping、およびtp_as_buffer が参照している 拡張機能構造体: extention structure ) の特定のフィールドのうち、 過去から現在までずっと存在しているわけではないもの が有効に なっていることを示すために使われます; フラグビットがクリアであれば、フラグが保護しているフィールド にはアクセスしない代わりに、その値はゼロかNULL に なっているとみなさなければなりません。

このフィールドの継承は複雑です。ほとんどのフラグビットは 個別に継承されます。つまり、基底タイプであるフラグビットがセット されている場合、サブタイプはそのフラグビットを継承します。 機能拡張のための構造体に関するフラグビットは、その機能拡張構造体 が継承されるときに限定して継承されます。すなわち、基底タイプの フラグビットの値は、機能拡張構造体へのポインタと一緒にサブタイプに コピーされます。 Py_TPFLAGS_HAVE_GC フラグビットは、tp_traverse および tp_clear フィールドと合わせてコピーされます。 すなわち、サブタイプの Py_TPFLAGS_HAVE_GC フラグビットが クリアで、かつ (Py_TPFLAGS_HAVE_RICHCOMPARE フラグビットの 指定によって) tp_traverse および tp_clear フィールドがサブタイプ内に存在しており、かつ値が NULL の場合に 基底タイプから値を継承します。

以下のビットマスクは現在定義されているものです; フラグは| 演算子で論理和を取って tp_flags フィールドの値にできます。 PyType_HasFeature() マクロは型とフラグ値、 tp および f をとり、tp->tp_flags & f が非ゼロかどうか調べます。

Py_TPFLAGS_HAVE_GETCHARBUFFER
このビットがセットされていれば、tp_as_buffer が参照する PyBufferProcs 構造体には bf_getcharbuffer フィールドが あります。

Py_TPFLAGS_HAVE_SEQUENCE_IN
このビットがセットされていれば、tp_as_sequence が参照する PySequenceMethods 構造体には sq_contains フィールドが あります。

Py_TPFLAGS_GC
このビットは旧式のものです。このシンボルが指し示していたビットは もはや使われていません。シンボルの現在の定義はゼロになっています。

Py_TPFLAGS_HAVE_INPLACEOPS
このビットがセットされていれば、tp_as_sequence が参照する PySequenceMethods 構造体、およびtp_as_number が参照する PyNumberMethods 構造体には in-place 演算に関するフィールドが 入っています。具体的に言うと、 PyNumberMethods 構造体はフィールド nb_inplace_add、 nb_inplace_subtract、 nb_inplace_multiply、 nb_inplace_divide、 nb_inplace_remainder、 nb_inplace_power、 nb_inplace_lshift、 nb_inplace_rshift、 nb_inplace_and、 nb_inplace_xor、および nb_inplace_or を持つことになります; また、 PySequenceMethods 構造体はフィールド sq_inplace_concat および sq_inplace_repeat を持つことになります。

Py_TPFLAGS_CHECKTYPES
このビットがセットされていれば、tp_as_number が参照する PyNumberMethods 構造体内で定義されている二項演算子および 三項演算子は任意のオブジェクト型を非演算子にとるようになり、 必要に応じて引数の型変換を行います。このビットがクリアなら、 演算子は全ての引数が現在のオブジェクト型と同じであるよう要求し、 演算の呼び出し側は演算に先立って型変換を行うものと想定します。 対象となる演算子は nb_add、 nb_subtract、 nb_multiply、 nb_divide、 nb_remainder、 nb_divmod、 nb_power、 nb_lshift、 nb_rshift、 nb_and、 nb_xor、および nb_or です。

Py_TPFLAGS_HAVE_RICHCOMPARE
このビットがセットされていれば、型オブジェクトには tp_richcompare フィールド、そして tp_traverse および tp_clear フィールドがあります。

Py_TPFLAGS_HAVE_WEAKREFS
このビットがセットされていれば、構造体にはtp_weaklistoffset フィールドが定義されています。tp_weaklistoffset フィールドの 値がゼロより大きければ、この型のインスタンスは弱参照で参照できます。

Py_TPFLAGS_HAVE_ITER
このビットがセットされていれば、型オブジェクトにはtp_iter および tp_iternext フィールドがあります。

Py_TPFLAGS_HAVE_CLASS
このビットがセットされていれば、型オブジェクトは Python 2.2 以降で 定義されている新たなフィールド: tp_methods、 tp_members、 tp_getset、 tp_base、 tp_dict、 tp_descr_get、 tp_descr_set、 tp_dictoffset、 tp_init、 tp_alloc、 tp_new、 tp_free、 tp_is_gc、 tp_bases、 tp_mro、 tp_cache、 tp_subclasses、 および tp_weaklist が あります。

Py_TPFLAGS_HEAPTYPE
型オブジェクト自体がヒープにメモリ確保される場合にセットされるビットです。 型オブジェクト自体がヒープにメモリ確保される場合、インスタンスの ob_type フィールドは型オブジェクトへの参照とみなされます。 この場合、新たなインスタンスを 生成する度に型オブジェクトを INCREF し、インスタンスを解放するたびに DECREF します (サブタイプのインスタンスには適当されません; インスタンスが ob_type で参照している型だけが INCREF および DECREF されます)。

Py_TPFLAGS_BASETYPE
型を別の型の基底タイプとして使える場合にセットされるビットです。 このビットがクリアならば、この型のサブタイプは生成できません (Java における "final" クラスに似たクラスになります)。

Py_TPFLAGS_READY
型オブジェクトが PyType_Ready() で完全に初期化される とセットされるビットです。

Py_TPFLAGS_READYING
PyType_Ready() による型オブジェクトの初期化処理中にセット されるビットです。

Py_TPFLAGS_HAVE_GC
オブジェクトがガベージコレクション (GC) をサポートする場合にセットされる ビットです。このビットがセットされている場合、インスタンスは PyObject_GC_New() を使って生成し、 PyObject_GC_Del() を使って破壊しなければなりません。 詳しい情報は XXX 節のガベージコレクションに関する説明中にあります。 このビットはまた、GC に関連するフィールドtp_traverse および tp_clear が型オブジェクト内に存在することを示します; しかし、これらのフィールドは Py_TPFLAGS_HAVE_GC がクリア でもPy_TPFLAGS_HAVE_RICHCOMPARE がセットされている場合には 存在します。

Py_TPFLAGS_DEFAULT
型オブジェクトおよび拡張機能構造体の特定のフィールドの存在の有無に 関連する全てのビットからなるビットマスクです。 現状では、このビットマスクには以下のビット: Py_TPFLAGS_HAVE_GETCHARBUFFER、 Py_TPFLAGS_HAVE_SEQUENCE_IN、 Py_TPFLAGS_HAVE_INPLACEOPS、 Py_TPFLAGS_HAVE_RICHCOMPARE、 Py_TPFLAGS_HAVE_WEAKREFS、 Py_TPFLAGS_HAVE_ITER、および Py_TPFLAGS_HAVE_CLASS が入っています。

char* tp_doc
オプションのフィールドです。ポインタで、この型オブジェクトの docstring を与える NUL 終端された C の文字列を指します。 この値は型オブジェクトと型のインスタンスにおける __doc__ 属性として公開されます。

サブタイプはこのフィールドを継承しません。

以下の三つのフィールドは、Py_TPFLAGS_HAVE_RICHCOMPARE フラグビットがセットされている場合にのみ存在します。

traverseproc tp_traverse
オプションのフィールドです。ポインタで、 ガベージコレクタのためのトラバーサル関数 (traversal function) を指します。Py_TPFLAGS_HAVE_GC がセットされている 場合にのみ使われます。ガベージコレクションに関する詳細は 10.9 にあります。

このフィールドは tp_clear および Py_TPFLAGS_HAVE_GC フラグビットと一緒に継承されます: フラグビット、tp_traverse、 および tp_clear の値がサブタイプで全てゼロになっており、 かつ サブタイプで Py_TPFLAGS_HAVE_RICHCOMPARE フラグビットがセットされている場合に、基底タイプから値を継承します。

inquiry tp_clear
オプションのフィールドです。ポインタで、 ガベージコレクタにおける消去関数 (clear function) を指します。 Py_TPFLAGS_HAVE_GC がセットされている 場合にのみ使われます。ガベージコレクションに関する詳細は 10.9 にあります。

このフィールドは tp_traverse および Py_TPFLAGS_HAVE_GC フラグビットと一緒に継承されます: フラグビット、tp_traverse、 および tp_clear の値がサブタイプで全てゼロになっており、 かつ サブタイプで Py_TPFLAGS_HAVE_RICHCOMPARE フラグビットがセットされている場合に、基底タイプから値を継承します。

richcmpfunc tp_richcompare
オプションのフィールドです。ポインタで、 拡張比較関数 (rich comparison function) を指します。

シグネチャはPyObject_RichCompare() と同じです。 この関数は、要求された比較演算が真を返す場合に 1 を、 偽を返す場合に 0 を返さなければなりません。 比較中にエラーが発生した場合には例外状態をセットして -1 を返さねばなりません。

このフィールドはtp_compare およびtp_hash と共にサブタイプに継承されます: すなわち、サブタイプの tp_compare 、tp_richcompare および tp_hash が共に NULLの場合、サブタイプは 基底タイプからtp_compare、tp_richcompare、 tp_hash の三つを一緒に継承します。

tp_richcompare およびPyObject_RichCompare() 関数の第三引数に使うための定数としては以下が定義されています:

定数 比較
Py_LT <
Py_LE <=
Py_EQ ==
Py_NE !=
Py_GT >
Py_GE >=

次のフィールドは、Py_TPFLAGS_HAVE_WEAKREFS フラグビットがセットされている場合にのみ存在します。

long tp_weaklistoffset
型のインスタンスが弱参照可能な場合、このフィールドはゼロよりも 大きな数になり、インスタンス構造体における弱参照リストの先頭を 示すオフセットが入ります (GC ヘッダがある場合には無視します); このオフセット値は PyObject_ClearWeakRefs() および PyWeakref_*() 関数が利用します。 インスタンス構造体には、 NULLに初期化されたPyObject* 型の フィールドが入っていなければなりません。

このフィールドを tp_weaklist と混同しないようにしてください; tp_weaklist は型オブジェクト自体の弱参照リストの先頭です。

サブタイプはこのフィールドを継承しますが、以下の規則があるので 読んでください。 サブタイプはこのオフセット値をオーバライドできます; 従って、 サブタイプでは弱参照リストの先頭が基底タイプとは異なる場合が あります。リストの先頭は常にtp_weaklistoffset で 分かるはずなので、このことは問題にはならないはずです。

class 文で定義された型に __slots__ 宣言が 全くなく、かつ基底タイプが弱参照可能でない場合、 その型を弱参照可能にするには弱参照リストの先頭を表すスロットを インスタンスデータレイアウト構造体に追加し、スロットのオフセットを tp_weaklistoffset に設定します。

型の __slots__ 宣言中に __weakref__ という名前の スロットが入っている場合、スロットはその型のインスタンスにおける 弱参照リストの先頭を表すスロットになり、スロットのオフセットが 型の tp_weaklistoffset に入ります。

型の __slots__ 宣言に __weakref__ という名のスロット が入っていない場合、その型は基底タイプからtp_weaklistoffset を継承します。

次の二つのフィールドは、Py_TPFLAGS_HAVE_CLASS フラグビットがセットされている場合にのみ存在します。

getiterfunc tp_iter
An optional pointer to a function that returns an iterator for the object. Its presence normally signals that the instances of this type are iterable (although sequences may be iterable without this function, and classic instances always have this function, even if they don't define an __iter__() method).

This function has the same signature as PyObject_GetIter().

サブタイプはこのフィールドを継承します。

iternextfunc tp_iternext
オプションのフィールドです。ポインタで、 イテレータにおいて次の要素を返すか、イテレータの要素がなくなると StopIteration を送出する関数を指します。このフィールド があると、通常この型のインスタンスがイテレータであることを示します (ただし、旧形式のインスタンスでは、たとえ next() メソッドが 定義されていなくても常にこの関数を持っています)。

イテレータ型では、 tp_iter 関数も定義していなければならず、 tp_iter は (新たなイテレータインスタンスではなく) イテレータインスタンス自体を返さねばなりません。

この関数のシグネチャは PyIter_Next() と同じです。

サブタイプはこのフィールドを継承します。

次の tp_weaklist までのフィールドは、 Py_TPFLAGS_HAVE_CLASS フラグビットがセットされている場合にのみ存在します。

struct PyMethodDef* tp_methods
オプションのフィールドです。ポインタで、 この型の正規 (regular) のメソッドを宣言しているPyMethodDef 構造体からなる、NULLで終端された静的配列を指します。

配列の各要素ごとに、メソッドデスクリプタの入ったエントリが 型辞書 (下記の tp_dict 参照) に追加されます。

サブタイプはこのフィールドを継承しません (メソッドは別個の メカニズムで継承されています)。

struct PyMemberDef* tp_members
オプションのフィールドです。ポインタで、 型の正規 (regular) のデータメンバ (フィールドおよびスロット) を 宣言しているPyMemberDef 構造体からなる、 NULLで終端された静的配列を指します。

配列の各要素ごとに、メンバデスクリプタの入ったエントリが 型辞書 (下記の tp_dict 参照) に追加されます。

サブタイプはこのフィールドを継承しません (メンバは別個の メカニズムで継承されています)。

struct PyGetSetDef* tp_getset
オプションのフィールドです。ポインタで、 インスタンスの算出属性 (computed attribute) を 宣言しているPyGetSetDef 構造体からなる、 NULLで終端された静的配列を指します。

配列の各要素ごとに、getset デスクリプタの入ったエントリが 型辞書 (下記の tp_dict 参照) に追加されます。

サブタイプはこのフィールドを継承しません (算出属性は別個の メカニズムで継承されています)。

Docs for PyGetSetDef (XXX belong elsewhere):

typedef PyObject *(*getter)(PyObject *, void *);
typedef int (*setter)(PyObject *, PyObject *, void *);

typedef struct PyGetSetDef {
    char *name;    /* 属性名 */
    getter get;    /* 属性の get を行う C 関数 */
    setter set;    /* 属性の set を行う C 関数 */
    char *doc;     /* オプションの docstring  */
    void *closure; /* オプションの get/set 関数用追加データ */
} PyGetSetDef;

PyTypeObject* tp_base
オプションのフィールドです。ポインタで、型に関するプロパティを 継承する基底タイプへのポインタです。このフィールドのレベルでは、 単継承 (single inheritance) だけがサポートされています; 多重継承はメタタイプの呼び出しによる動的な型オブジェクトの生成を 必要とします。

(当たり前ですが) サブタイプはこのフィールドを継承しません。しかし、 このフィールドのデフォルト値は (Python プログラマはobject 型として知っている) &PyBaseObject_Type になります。 .

PyObject* tp_dict
型の辞書はPyType_Ready() によってこのフィールドに 収められます。

このフィールドは通常、PyType_Ready() を呼び出す前に NULL に初期化しておかねばなりません; あるいは、型の初期属性の入った 辞書で初期化しておいてもかまいません。PyType_Ready() が 型をひとたび初期化すると、型の新たな属性をこの辞書に追加できるのは、 属性が (__add__() のような) オーバロード用演算でないとき だけです。

サブタイプはこのフィールドを継承しません (が、この辞書内で 定義されている属性は異なるメカニズムで継承されます)。

descrgetfunc tp_descr_get
オプションのフィールドです。ポインタで、 "デスクリプタ get" 関数を指します。

XXX blah, blah.

サブタイプはこのフィールドを継承します。

descrsetfunc tp_descr_set
オプションのフィールドです。ポインタで、 "デスクリプタ set" 関数を指します。

XXX blah, blah.

サブタイプはこのフィールドを継承します。

long tp_dictoffset
型のインスタンスにインスタンス変数の入った辞書がある場合、 このフィールドは非ゼロの値になり、型のインスタンスデータ構造体 におけるインスタンス変数辞書へのオフセットが入ります; このオフセット値は PyObject_GenericGetAttr() が 使います。

このフィールドを tp_dict と混同しないでください; tp_dict は型オブジェクト自体の属性のための辞書です。

このフィールドの値がゼロより大きければ、値はインスタンス構造体の 先頭からのオフセットを表します。値がゼロより小さければ、 インスタンス構造体の 末尾 からのオフセットを表します。 負のオフセットを使うコストは比較的高くつくので、インスタンス構造体に 可変長の部分があるときのみ使うべきです。 例えば、str や tuple のサブタイプにインスタンス 辞書を追加する場合には、負のオフセットを使います。 この場合、たとえ辞書が基本のオブジェクトレイアウトに含まれていなくても、 tp_basicsize フィールドは追加された辞書を考慮にいれなければ ならないので注意してください。ポインタサイズが 4 バイトのシステムでは、 構造体の最後尾に辞書が宣言されていることを示す場合、 tp_dictoffset を-4 にしなければなりません。

tp_dictoffset が負の場合、インスタンスにおける実際の辞書の オフセットは以下のようにして計算されます:

dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
if dictoffset is not aligned on sizeof(void*):
    round up to sizeof(void*)

ここで、tp_basicsize、 tp_itemsize および tp_dictoffset は型オブジェクトから取り出され、 ob_size はインスタンスから取り出されます。 長整数は符号を記憶するのに ob_size の符号を使うため、 ob_size は絶対値を使います。(この計算を自分で行う必要は まったくありません; _PyObject_GetDictPtr() が やってくれます。)

サブタイプはこのフィールドを継承しますが、以下の規則があるので 読んでください。 サブタイプはこのオフセット値をオーバライドできます; 従って、 サブタイプでは辞書のオフセットが基底タイプとは異なる場合が あります。辞書へのオフセット常にtp_dictoffset で 分かるはずなので、このことは問題にはならないはずです。

class 文で定義された型に __slots__ 宣言が 全くなく、かつ基底タイプの全てにインスタンス変数辞書がない場合、 辞書のスロットをインスタンスデータレイアウト構造体に追加し、 スロットのオフセットをtp_dictoffset に設定します。

class 文で定義された型に __slots__ 宣言が ある場合、この型は基底タイプから tp_dictoffset を 継承します。

(__dict__ という名前のスロットを __slots__ 宣言に 追加しても、期待どおりの効果は得られず、単に混乱を招くだけに なります。とはいえ、これは将来__weakref__ のように 追加されるはずです。)

initproc tp_init
オプションのフィールドです。ポインタで、 インスタンス初期化関数を指します。

この関数はクラスにおける  __init__() メソッドに対応
します。__init__() と同様、__init__() を呼び出さず
にインスタンスを作成できます。また、__init__() を再度
呼び出してインスタンスの再初期化もできます。

関数のシグネチャは

int tp_init(PyObject *self, PyObject *args, PyObject *kwds)

です。

self 引数は初期化するインスタンスです; args および kwds 引数は、__init__() を呼び出す際の 固定引数およびキーワード引数です。

tp_init 関数のフィールドが NULLでない場合、型の呼び出し で普通にインスタンスを生成する際に、型のtp_new が インスタンスを返した後にtp_init が呼び出されます。 tp_new が元の型のサブタイプでない別の型を返す場合、 tp_init は全く呼び出されません; tp_new が 元の型のサブタイプのインスタンスを返す場合、サブタイプの tp_init が呼び出されます。 (VERSION NOTE: ここに書かれている 内容は、Python 2.2.1 以降での実装に関するものです。Python 2.2 では、 tp_init は NULLでない限りtp_new が返す全ての オブジェクトに対して常に呼び出されます。) not NULL.)

サブタイプはこのフィールドを継承します。

allocfunc tp_alloc
オプションのフィールドです。ポインタで、 インスタンスのメモリ確保関数を指します。

関数のシグネチャは

PyObject *tp_alloc(PyTypeObject *self, int nitems)

です。

この関数の目的は、メモリ確保をメモリ初期化から分離することにあります。 この関数は、インスタンス用の的確なサイズを持ち、適切にバイト整列 され、ゼロで初期化され、ただしob_refcnt を 1 にセットされ、 ob_type が型引数 (type argument) にセットされて いるようなメモリブロックを返さねばなりません。 型の tp_itemsize がゼロでない場合、オブジェクトの ob_size フィールドはnitems に初期化され、 確保されるメモリブロックの長さは tp_basicsize + nitems*tp_itemsize をsizeof(void*) の倍数で 丸めた値になるはずです; それ以外の場合、nitems の値は使われず、 メモリブロックの長さは tp_basicsize になるはずです。

この関数をインスタンス初期化の他のどの処理にも、追加でメモリ確保 をする場合でさえ使ってはなりません; そうした処理は tp_new で行わねばなりません。

静的なサブタイプはこのフィールドを継承しますが、動的なサブタイプ (class 文で生成するサブタイプ) の場合は継承しません; 後者の場合、このフィールドは常にPyType_GenericAlloc() にセットされ、標準のヒープ上メモリ確保戦略が強制されます。 静的に定義する型の場合でも、PyType_GenericAlloc() を推奨します。

newfunc tp_new
オプションのフィールドです。ポインタで、 インスタンス生成関数を指します。

このフィールドが NULL を指している型では、型を呼び出して新たな インスタンスを生成できません; こうした型では、おそらくファクトリ 関数のように、インスタンスを生成する他の方法があるはずです。

関数のシグネチャは

PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)

です。

引数 subtype は生成するオブジェクトの型です; args およびkwds 引数は、型を呼び出すときの 固定引数およびキーワード引数です。サブタイプは tp_new 関数 を呼び出すときに使う型と等価というわけではないので注意してください; tp_new 関数を呼び出すときに使う型 (と無関係ではない) サブタイプのこともあります。

tp_new 関数は subtype->tp_alloc(subtype, nitems) を呼び出してオブジェクトのメモリ領域を確保し、初期化で本当に必要と される処理だけを行います。省略したり繰り返したりしても問題のない 初期化処理はtp_init ハンドラ内に配置しなければなりません。 経験則からいうと、変更不能な型の場合、初期化は全て tp_new で行い、変更可能な型の場合はほとんどの初期化を tp_init に回すべきです。

サブタイプはこのフィールドを継承します。例外として、 tp_base がNULL か&PyBaseObject_Type になっている静的な型では 継承しません。後者が例外になっているのは、旧式の拡張型が Python 2.2 でリンクされたときに呼び出し可能オブジェクトにならないように するための予防措置です。

destructor tp_free
オプションのフィールドです。ポインタで、 インスタンスのメモリ解放関数を指します。

この関数のシグネチャは少し変更されています; Python 2.2 および 2.2.1 では、シグネチャはdestructor :

void tp_free(PyObject *)

でしたが、 Python 2.3 以降では、シグネチャは freefunc:

void tp_free(void *)

になっています。

両方のバージョンと互換性のある初期値は _PyObject_Del です。 _PyObject_Del の定義は Python 2.3 で適切に対応できる よう変更されました。

静的なサブタイプはこのフィールドを継承しますが、動的なサブタイプ (class 文で生成するサブタイプ) の場合は継承しません; 後者の場合、このフィールドにはPyType_GenericAlloc() とPy_TPFLAGS_HAVE_GC フラグビットの値に対応させるのに ふさわしいメモリ解放関数がセットされます。

inquiry tp_is_gc
オプションのフィールドです。ポインタで、 ガベージコレクタから呼び出される関数を指します。

ガベージコレクタは、オブジェクトがガベージとして収集可能かどうか を知る必要があります。これを知るには、通常はオブジェクトの型の tp_flags フィールドを見て、 Py_TPFLAGS_HAVE_GC フラグビットを調べるだけで十分です。しかし、静的なメモリ確保と 動的なメモリ確保が混じっているインスタンスを持つような型や、 静的にメモリ確保されたインスタンスは収集できません。こうした型では、 このフィールドに関数を定義しなければなりません; 関数は インスタンスが収集可能の場合には 1 を、 収集不能の場合には 0 を返さねばなりません。 シグネチャは

int tp_is_gc(PyObject *self)

です。

(上記のような型の例は、型オブジェクト自体です。メタタイプ PyType_Type は、型のメモリ確保が静的か動的かを 区別するためにこの関数を定義しています。)

サブタイプはこのフィールドを継承します。 (VERSION NOTE: Python 2.2 では、このフィールドは継承されませんでした。 2.2.1 以降のバージョンから継承されるようになりました。)

PyObject* tp_bases
基底型からなるタプルです。

class 文で生成されたクラスの場合このフィールドがセット されます。静的に定義されている型の場合には、このフィールドは NULL になります。

このフィールドは継承されません。

PyObject* tp_mro
基底クラス群を展開した集合が入っているタプルです。集合は 該当する型自体からはじまり、object で終わります。 メソッド解決順 (Method Resolution Order) の順に並んでいます。

このフィールドは継承されません; フィールドの値は PyType_Ready() で毎回計算されます。

PyObject* tp_cache
使用されていません。継承されません。 内部で使用するためだけのものです。

PyObject* tp_subclasses
サブクラスへの弱参照からなるリストです。継承されません。 内部で使用するためだけのものです。

PyObject* tp_weaklist
この型オブジェクトに対する弱参照からなるリストの先頭です。

残りのフィールドは、機能テスト用のマクロである COUNT_ALLOCS が定義されている場合のみ利用でき、内部で使用するためだけのものです。 これらのフィールドについて記述するのは単に完全性のためです。 サブタイプはこれらのフィールドを継承しません。

int tp_allocs
メモリ確保の回数です。

int tp_frees
メモリ解放の回数です。

int tp_maxalloc
同時にメモリ確保できる最大オブジェクト数です。

PyTypeObject* tp_next
tp_allocs フィールドが非ゼロの、(リンクリストの) 次の型 オブジェクトを指すポインタです。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 10.2 共通のオブジェクト構造体 (common object Up: 10. オブジェクト実装サポート (object implementation Next: 10.4 マップ型オブジェクト構造体 (mapping object
Release 2.3.3, documentation updated on December 19, 2003.


10.4 マップ型オブジェクト構造体 (mapping object structure)

PyMappingMethods
拡張型でマップ型プロトコルを実装するために使われる関数群へのポインタを 保持するために使われる構造体です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 10.3 型オブジェクト Up: 10. オブジェクト実装サポート (object implementation Next: 10.5 数値オブジェクト構造体 (number object
Release 2.3.3, documentation updated on December 19, 2003.


10.5 数値オブジェクト構造体 (number object structure)

PyNumberMethods
拡張型で数値型プロトコルを実装するために使われる関数群へのポインタを 保持するために使われる構造体です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 10.4 マップ型オブジェクト構造体 (mapping object Up: 10. オブジェクト実装サポート (object implementation Next: 10.6 配列オブジェクト構造体 (sequence object
Release 2.3.3, documentation updated on December 19, 2003.


10.6 配列オブジェクト構造体 (sequence object structure)

PySequenceMethods
拡張型で配列型プロトコルを実装するために使われる関数群へのポインタを 保持するために使われる構造体です。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 10.5 数値オブジェクト構造体 (number object Up: 10. オブジェクト実装サポート (object implementation Next: 10.7 バッファオブジェクト構造体 (buffer object
Release 2.3.3, documentation updated on December 19, 2003.


10.7 バッファオブジェクト構造体 (buffer object structure)

バッファインタフェースは、あるオブジェクトの内部データを一連の データチャンク (chunk) として見せるモデルを外部から利用できるようにします。 各チャンクはポインタ/データ長からなるペアで指定します。 チャンクはセグメント(segment) と呼ばれ、 メモリ内に不連続的に配置されるものと想定されています。

バッファインタフェースを利用できるようにしたくないオブジェクト では、PyTypeObject 構造体の tp_as_buffer メンバを NULLにしなくてはなりません。利用できるようにする場合、 tp_as_buffer はPyBufferProcs 構造体を 指さねばなりません。

注意: PyTypeObject 構造体の tp_flags メンバ の値を 0 でなく Py_TPFLAGS_DEFAULT に しておくことがとても重要です。この設定は、 PyBufferProcs 構造体に bf_getcharbuffer スロットが入っていることを Python ランタイムに教えます。 Python の古いバージョンには bf_getcharbuffer メンバが 存在しないので、古い拡張モジュールを使おうとしている新しいバージョンの Python インタプリタは、このメンバがあるかどうかテストしてから 使えるようにする必要があるのです。

PyBufferProcs
バッファプロトコルの実装を定義している関数群へのポインタを 保持するのに使われる構造体です。

最初のスロットはbf_getreadbuffer で、 getreadbufferproc 型です。 このスロットが NULLの場合、オブジェクトは内部データの 読み出しをサポートしません。そのような仕様には意味がないので、 実装を行う側はこのスロットに値を埋めるはずですが、呼び出し側では 非 NULL の値かどうかきちんと調べておくべきです。

次のスロットは bf_getwritebuffer で、 getwritebufferproc 型です。オブジェクトが返すバッファに 対して書き込みを許可しない場合はこのスロットをNULL にできます。

第三のスロットは bf_getsegcount で、 getsegcountproc 型です。このスロットは NULL であっては ならず、オブジェクトにいくつセグメントが入っているかを呼び出し側に 教えるために使われます。PyString_Type や PyBuffer_Type オブジェクトのような単純なオブジェクトには単一のセグメントしか入って いません。

最後のスロットは bf_getcharbuffer で、 getcharbufferproc です。オブジェクトの PyTypeObject 構造体における tp_flags フィールドに、 Py_TPFLAGS_HAVE_GETCHARBUFFER ビットフラグがセットされている 場合にのみ、このスロットが存在することになります。 このスロットの使用に先立って、呼び出し側は PyType_HasFeature()を使ってスロットが存在するか調べねばなりません。 スロットが存在する場合、値は NULLのときもあり、NULLは オブジェクトの内容を 8 ビット文字列 として利用できない ことを示します。 このスロットに入る関数も、オブジェクトの内容を 8 ビット文字列に 変換できない場合に例外を送出することがあります。例えば、 オブジェクトが浮動小数点数を保持するように設定されたアレイの場合、 呼び出し側が bf_getcharbuffer を使って 8 ビット文字列 としてデータを取り出そうとすると例外を送出するようにできます。 この、内部バッファを ``テキスト'' として取り出すという概念は、 本質的にはバイナリで、文字ベースの内容を持ったオブジェクト間の 区別に使われます。

注意: 現在のポリシでは、文字 (character) はマルチバイト文字 でもかまわないと決めているように思われます。従って、 サイズ N のバッファが N 個のキャラクタからなる とはかぎらないことになります。

Py_TPFLAGS_HAVE_GETCHARBUFFER
型構造体中のフラグビットで、bf_getcharbuffer スロットが 既知の値になっていることを示します。このフラグビットがセット されていたとしても、オブジェクトがバッファインタフェースをサポート していることや、bf_getcharbuffer スロットが NULLでない ことを示すわけではありません。

int (*getreadbufferproc) (PyObject *self, int segment, void **ptrptr)
読み出し可能なバッファセグメントへのポインタを返します。この関数は 例外を送出してもよく、送出する場合には -1 を返さねばなりません。 segment に渡す値はゼロまたは正の値で、bf_getsegcount スロット関数が返すセグメント数よりも必ず小さな値でなければなりません。 成功すると、バッファメモリのサイズを返し、 *ptrptr を バッファメモリを指すポインタ値にセットします。

int (*getwritebufferproc) (PyObject *self, int segment, void **ptrptr)
読み出し可能なバッファセグメントへのポインタを *ptrptr に 返し、セグメントの長さを関数の戻り値として返します。エラーによる例外の 場合には -1 を-1 を返さねばなりません。 オブジェクトが呼び出し専用バッファしかサポートしていない場合には TypeError を、segment が存在しないセグメントを 指している場合には SystemError を送出しなければなりません。

int (*getsegcountproc) (PyObject *self, int *lenp)
バッファを構成するメモリセグメントの数を返します。 lenp が NULLでない場合、この関数の実装は全てのセグメント のサイズ (バイト単位) の合計値を *lenp を介して 報告しなければなりません。この関数呼び出しは失敗させられません。

int (*getcharbufferproc) (PyObject *self, int segment, const char **ptrptr)
セグメント segment のメモリバッファを ptrptr に入れ、 メモリバッファのサイズを返します。*ptrptr がメモリバッファ を表す値になるようにセットされます。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 10.6 配列オブジェクト構造体 (sequence object Up: 10. オブジェクト実装サポート (object implementation Next: 10.8 イテレータプロトコルをサポートする
Release 2.3.3, documentation updated on December 19, 2003.


10.8 イテレータプロトコルをサポートする

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 10.7 バッファオブジェクト構造体 (buffer object Up: 10. オブジェクト実装サポート (object implementation Next: 10.9 循環参照ガベージコレクションをサポートする
Release 2.3.3, documentation updated on December 19, 2003.


10.9 循環参照ガベージコレクションをサポートする

Python が循環参照を含むガベージの検出とコレクションをサポートする には、他のオブジェクトに対する ``コンテナ'' (他のオブジェクトには 他のコンテナも含みます) となるオブジェクト型によるサポートが必要です。 他のオブジェクトに対する参照を記憶しないオブジェクトや、 (数値や文字列のような) アトム型 (atomic type) への参照だけを 記憶するような型では、ガベージコレクションに際して特別これといった サポートを提供する必要はありません。

ここで説明しているインタフェースの使い方を示した例は、 Python の拡張と埋め込み の ``循環参照の収集をサポートする'' にあります。 コンテナ型を作るには、型オブジェクトの tp_flags フィールド にPy_TPFLAGS_HAVE_GC フラグがなくてはならず、 tp_traverse ハンドラの実装を提供しなければなりません。 実装する型のインスタンスを変更可能なオブジェクトにするなら、 tp_clear の実装も提供しなければなりません。

Py_TPFLAGS_HAVE_GC
このフラグをセットした型のオブジェクトは、この節に述べた規則に 適合しなければなりません。簡単のため、このフラグをセットした型の オブジェクトをコンテナオブジェクトと呼びます。

コンテナ型のコンストラクタは以下の二つの規則に適合しなければなりません:

  1. オブジェクトのメモリは PyObject_GC_New() または PyObject_GC_VarNew() で確保しなければなりません。

  2. 一度他のコンテナへの参照が入るかもしれないフィールドが全て 初期化されたら、PyObject_GC_Track() を呼び出さねば なりません。

TYPE* PyObject_GC_New( TYPE, PyTypeObject *type)
PyObject_New() に似ていますが、 Py_TPFLAGS_HAVE_GC のセットされたコンテナオブジェクト 用です。

TYPE* PyObject_GC_NewVar( TYPE, PyTypeObject *type, int size)
PyObject_NewVar() に似ていますが、 Py_TPFLAGS_HAVE_GC のセットされたコンテナオブジェクト 用です。

PyVarObject * PyObject_GC_Resize( PyVarObject *op, int)
PyObject_NewVar() が確保したオブジェクトのメモリを リサイズします。リサイズされたオブジェクトを返します。 失敗すると NULL を返します。

void PyObject_GC_Track( PyObject *op)
ガベージコレクタが追跡しているコンテナオブジェクトの集合に オブジェクト op を追加します。ガベージコレクタの動作する 回数は予測不能なので、追加対象にするオブジェクトは追跡されている 間ずっと有効なオブジェクトでなければなりません。 この関数は、通常コンストラクタの最後付近で、tp_traverse ハンドラ以降の全てのフィールドが有効な値になった時点で呼び出さねば なりません。

void _PyObject_GC_TRACK( PyObject *op)
PyObject_GC_Track() のマクロ版です。拡張モジュールに 使ってはなりません。

同様に、オブジェクトのメモリ解放関数も以下の二つの規則に適合しなければ なりません:

  1. 他のコンテナを参照しているフィールドを無効化する前に、 PyObject_GC_UnTrack() を呼び出さねばなりません。
  2. オブジェクトのメモリは PyObject_GC_Del() で解放しなければなりません。

void PyObject_GC_Del( PyObject *op)
PyObject_GC_New() や PyObject_GC_NewVar() を使って確保されたメモリを解放します。

void PyObject_GC_UnTrack( PyObject *op)
ガベージコレクタが追跡しているコンテナオブジェクトの集合から オブジェクト op を除去します。PyObject_GC_Track() を呼び出して、除去したオブジェクトを再度追跡対象セットに追加 できるので注意してください。メモリ解放関数 (deallocator, tp_dealloc ハンドラ) は、tp_traverse ハンドラが 使用しているフィールドのいずれかが無効化されるよりも 以前にオブジェクトに対して呼び出されていなければなりません。

void _PyObject_GC_UNTRACK( PyObject *op)
PyObject_GC_UnTrack() のマクロ版です。拡張モジュールに 使ってはなりません。

tp_traverse ハンドラは以下の型を持つ関数を引数の一つとして とります:

int (*visitproc)(PyObject *object, void *arg)
tp_traverse ハンドラに渡すビジタ関数 (visitor function) の型です。この関数は追跡すべきオブジェクトを object に、 tp_traverse ハンドラの第三引数を arg にして呼び出され ます。

tp_traverse ハンドラは以下の型でなければなりません:

int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
コンテナオブジェクトのためのトラバーサル関数 (traversal function) です。 実装では、self に直接入っている各オブジェクトに対してvisit 関数を呼び出さねばなりません。このとき、visit へのパラメタは コンテナに入っている各オブジェクトと、このハンドラに渡された arg の値です。visit が非ゼロの値を返す場合、 エラーが発生し、戻り値をそのまま返すようににしなければなりません。

tp_clear ハンドラは inquiry 型にするか、 オブジェクトが変更不能の場合には NULL にしなければなりません。 NULL if the object is immutable.

int (*inquiry)(PyObject *self)
循環参照を形成しているとおぼしき参照群を放棄します。 変更不可能なオブジェクトは循環参照を直接形成することが決してない ので、この関数を定義する必要はありません。 このメソッドを呼び出した後でもオブジェクトは有効なままでなければ ならないので注意してください (参照に対して Py_DECREF() を呼ぶだけにしないでください)。ガベージコレクタは、オブジェクトが 循環参照を形成していることを検出した際にこのメソッドを呼び出します。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 10.8 イテレータプロトコルをサポートする Up: 10. オブジェクト実装サポート (object implementation Next: A. バグ報告
Release 2.3.3, documentation updated on December 19, 2003.


A. バグ報告

Python is a mature programming language which has established a reputation for stability. In order to maintain this reputation, the developers would like to know of any deficiencies you find in Python or its documentation.

Before submitting a report, you will be required to log into SourceForge; this will make it possible for the developers to contact you for additional information if needed. It is not possible to submit a bug report anonymously.

All bug reports should be submitted via the Python Bug Tracker on SourceForge (http://sourceforge.net/bugs/?group_id=5470). The bug tracker offers a Web form which allows pertinent information to be entered and submitted to the developers.

The first step in filing a report is to determine whether the problem has already been reported. The advantage in doing so, aside from saving the developers time, is that you learn what has been done to fix it; it may be that the problem has already been fixed for the next release, or additional information is needed (in which case you are welcome to provide it if you can!). To do this, search the bug database using the search box near the bottom of the page.

If the problem you're reporting is not already in the bug tracker, go back to the Python Bug Tracker (http://sourceforge.net/bugs/?group_id=5470). Select the ``Submit a Bug'' link at the top of the page to open the bug reporting form.

The submission form has a number of fields. The only fields that are required are the ``Summary'' and ``Details'' fields. For the summary, enter a very short description of the problem; less than ten words is good. In the Details field, describe the problem in detail, including what you expected to happen and what did happen. Be sure to include the version of Python you used, whether any extension modules were involved, and what hardware and software platform you were using (including version information as appropriate).

The only other field that you may want to set is the ``Category'' field, which allows you to place the bug report into a broad category (such as ``Documentation'' or ``Library'').

Each bug report will be assigned to a developer who will determine what needs to be done to correct the problem. You will receive an update each time action is taken on the bug.

参考資料:

How to Report Bugs Effectively
Article which goes into some detail about how to create a useful bug report. This describes what kind of information is useful and why it is useful.

Bug Writing Guidelines
Information about writing a good bug report. Some of this is specific to the Mozilla project, but describes general good practices.

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 10.9 循環参照ガベージコレクションをサポートする Up: Python/C API リファレンスマニュアル Next: B. 歴史とライセンス
Release 2.3.3, documentation updated on December 19, 2003.


B. 歴史とライセンス

  • B.1 History of the software
  • B.2 Terms and conditions for accessing or otherwise using Python
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: A. バグ報告 Up: Python/C API リファレンスマニュアル Next: B.1 History of the
Release 2.3.3, documentation updated on December 19, 2003.


B.1 History of the software

Python was created in the early 1990s by Guido van Rossum at Stichting Mathematisch Centrum (CWI, see http://www.cwi.nl/) in the Netherlands as a successor of a language called ABC. Guido remains Python's principal author, although it includes many contributions from others.

In 1995, Guido continued his work on Python at the Corporation for National Research Initiatives (CNRI, see http://www.cnri.reston.va.us/) in Reston, Virginia where he released several versions of the software.

In May 2000, Guido and the Python core development team moved to BeOpen.com to form the BeOpen PythonLabs team. In October of the same year, the PythonLabs team moved to Digital Creations (now Zope Corporation; see http://www.zope.com/). In 2001, the Python Software Foundation (PSF, see http://www.python.org/psf/) was formed, a non-profit organization created specifically to own Python-related Intellectual Property. Zope Corporation is a sponsoring member of the PSF.

All Python releases are Open Source (see http://www.opensource.org/ for the Open Source Definition). Historically, most, but not all, Python releases have also been GPL-compatible; the table below summarizes the various releases.

Release | Derived from | Year | Owner | GPL compatible?
0.9.0 thru 1.2 | n/a | 1991-1995 | CWI | yes
1.3 thru 1.5.2 | 1.2 | 1995-1999 | CNRI | yes
1.6 | 1.5.2 | 2000 | CNRI | no
2.0 | 1.6 | 2000 | BeOpen.com | no
1.6.1 | 1.6 | 2001 | CNRI | no
2.1 | 2.0+1.6.1 | 2001 | PSF | no
2.0.1 | 2.0+1.6.1 | 2001 | PSF | yes
2.1.1 | 2.1+2.0.1 | 2001 | PSF | yes
2.2 | 2.1.1 | 2001 | PSF | yes
2.1.2 | 2.1.1 | 2002 | PSF | yes
2.1.3 | 2.1.2 | 2002 | PSF | yes
2.2.1 | 2.2 | 2002 | PSF | yes
2.2.2 | 2.2.1 | 2002 | PSF | yes
2.2.3 | 2.2.2 | 2002-2003 | PSF | yes
2.3 | 2.2.2 | 2002-2003 | PSF | yes
2.3.1 | 2.3 | 2002-2003 | PSF | yes
2.3.2 | 2.3.1 | 2003 | PSF | yes

注意: GPL-compatible doesn't mean that we're distributing Python under the GPL. All Python licenses, unlike the GPL, let you distribute a modified version without making your changes open source. The GPL-compatible licenses make it possible to combine Python with other software that is released under the GPL; the others don't.

Thanks to the many outside volunteers who have worked under Guido's direction to make these releases possible.

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: B. 歴史とライセンス Up: B. 歴史とライセンス Next: B.2 Terms and conditions
Release 2.3.3, documentation updated on December 19, 2003.


B.2 Terms and conditions for accessing or otherwise using Python

PSF LICENSE AGREEMENT FOR PYTHON 2.3.3

  1. This LICENSE AGREEMENT is between the Python Software Foundation (``PSF''), and the Individual or Organization (``Licensee'') accessing and otherwise using Python 2.3.3 software in source or binary form and its associated documentation.

  2. Subject to the terms and conditions of this License Agreement, PSF hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python 2.3.3 alone or in any derivative version, provided, however, that PSF's License Agreement and PSF's notice of copyright, i.e., ``Copyright © 2001-2003 Python Software Foundation; All Rights Reserved'' are retained in Python 2.3.3 alone or in any derivative version prepared by Licensee.

  3. In the event Licensee prepares a derivative work that is based on or incorporates Python 2.3.3 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python 2.3.3.

  4. PSF is making Python 2.3.3 available to Licensee on an ``AS IS'' basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.3.3 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 2.3.3 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 2.3.3, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between PSF and Licensee. This License Agreement does not grant permission to use PSF trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party.

  8. By copying, installing or otherwise using Python 2.3.3, Licensee agrees to be bound by the terms and conditions of this License Agreement.

BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0

BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1

  1. This LICENSE AGREEMENT is between BeOpen.com (``BeOpen''), having an office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization (``Licensee'') accessing and otherwise using this software in source or binary form and its associated documentation (``the Software'').

  2. Subject to the terms and conditions of this BeOpen Python License Agreement, BeOpen hereby grants Licensee a non-exclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use the Software alone or in any derivative version, provided, however, that the BeOpen Python License is retained in the Software, alone or in any derivative version prepared by Licensee.

  3. BeOpen is making the Software available to Licensee on an ``AS IS'' basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  5. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  6. This License Agreement shall be governed by and interpreted in all respects by the law of the State of California, excluding conflict of law provisions. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between BeOpen and Licensee. This License Agreement does not grant permission to use BeOpen trademarks or trade names in a trademark sense to endorse or promote products or services of Licensee, or any third party. As an exception, the ``BeOpen Python'' logos available at http://www.pythonlabs.com/logos.html may be used according to the permissions granted on that web page.

  7. By copying, installing or otherwise using the software, Licensee agrees to be bound by the terms and conditions of this License Agreement.

CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1

  1. This LICENSE AGREEMENT is between the Corporation for National Research Initiatives, having an office at 1895 Preston White Drive, Reston, VA 20191 (``CNRI''), and the Individual or Organization (``Licensee'') accessing and otherwise using Python 1.6.1 software in source or binary form and its associated documentation.

  2. Subject to the terms and conditions of this License Agreement, CNRI hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python 1.6.1 alone or in any derivative version, provided, however, that CNRI's License Agreement and CNRI's notice of copyright, i.e., ``Copyright © 1995-2001 Corporation for National Research Initiatives; All Rights Reserved'' are retained in Python 1.6.1 alone or in any derivative version prepared by Licensee. Alternately, in lieu of CNRI's License Agreement, Licensee may substitute the following text (omitting the quotes): ``Python 1.6.1 is made available subject to the terms and conditions in CNRI's License Agreement. This Agreement together with Python 1.6.1 may be located on the Internet using the following unique, persistent identifier (known as a handle): 1895.22/1013. This Agreement may also be obtained from a proxy server on the Internet using the following URL: http://hdl.handle.net/1895.22/1013.''

  3. In the event Licensee prepares a derivative work that is based on or incorporates Python 1.6.1 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python 1.6.1.

  4. CNRI is making Python 1.6.1 available to Licensee on an ``AS IS'' basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

  5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

  6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

  7. This License Agreement shall be governed by the federal intellectual property law of the United States, including without limitation the federal copyright law, and, to the extent such U.S. federal law does not apply, by the law of the Commonwealth of Virginia, excluding Virginia's conflict of law provisions. Notwithstanding the foregoing, with regard to derivative works based on Python 1.6.1 that incorporate non-separable material that was previously distributed under the GNU General Public License (GPL), the law of the Commonwealth of Virginia shall govern this License Agreement only as to issues arising under or with respect to Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between CNRI and Licensee. This License Agreement does not grant permission to use CNRI trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party.

  8. By clicking on the ``ACCEPT'' button where indicated, or by copying, installing or otherwise using Python 1.6.1, Licensee agrees to be bound by the terms and conditions of this License Agreement.

ACCEPT

CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2

Copyright © 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, The Netherlands. All rights reserved.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Stichting Mathematisch Centrum or CWI not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: B.1 History of the Up: B. 歴史とライセンス Next: C. 日本語訳について
Release 2.3.3, documentation updated on December 19, 2003.


C. 日本語訳について

  • C.1 このドキュメントについて
  • C.2 翻訳者一覧 (敬称略)
Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: B.2 Terms and conditions Up: Python/C API リファレンスマニュアル Next: C.1 このドキュメントについて
Release 2.3.3, documentation updated on December 19, 2003.


C.1 このドキュメントについて

この文書は、Pythonドキュメント翻訳プロジェクトによる Python C/API Reference Release 2.3の日本語訳版です。日本語訳に対する質問や提案などが ありましたら、Pythonドキュメント翻訳プロジェクトのメーリングリスト

http://www.python.jp/mailman/listinfo/python-doc-jp

または、プロジェクトのバグ管理ページ

http://sourceforge.jp/tracker/?atid=116&group_id=11&func=browse

までご報告ください。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: C. 日本語訳について Up: C. 日本語訳について Next: C.2 翻訳者一覧 (敬称略)
Release 2.3.3, documentation updated on December 19, 2003.


C.2 翻訳者一覧 (敬称略)

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: C.1 このドキュメントについて Up: C. 日本語訳について Next: 索引
Release 2.3.3, documentation updated on December 19, 2003.


索引

_ | a | b | c | d | e | f | g | h | i | k | l | m | n | o | p | r | s | t | u | v

_ (アンダースコア)

__all__ (package variable)
__builtin__ (組み込み モジュール), [リンク], [リンク]
__dict__ (module attribute)
__doc__ (module attribute)
__file__ (module attribute), [リンク]
__import__() (組み込み関数)
__main__ (組み込み モジュール), [リンク], [リンク]
__name__ (module attribute), [リンク]
_frozen (C の型)
_inittab (C の型)
_ob_next (PyObject のメンバ)
_ob_prev (PyObject のメンバ)
_Py_c_diff()
_Py_c_neg()
_Py_c_pow()
_Py_c_prod()
_Py_c_quot()
_Py_c_sum()
_Py_NoneStruct
_PyImport_FindExtension()
_PyImport_Fini()
_PyImport_FixupExtension()
_PyImport_Init()
_PyObject_Del()
_PyObject_GC_TRACK()
_PyObject_GC_UNTRACK()
_PyObject_New()
_PyObject_NewVar()
_PyString_Resize()
_PyTuple_Resize()

A

abort()
abs() (組み込み関数)
apply() (組み込み関数), [リンク], [リンク]
argv (in module sys)

B

buffer interface
buffer オブジェクト
BufferType (in module types)

C

calloc()
classmethod() (組み込み関数)
cleanup functions
close() (in module os)
cmp() (組み込み関数), [リンク], [リンク]
CObject オブジェクト
coerce() (組み込み関数)
compile() (組み込み関数)
complex number オブジェクト
copyright (in module sys)

D

dictionary オブジェクト
DictionaryType (in module types)
DictType (in module types)
divmod() (組み込み関数)

E

EOFError (built-in exception)
errno
exc_info() (in module sys), [リンク]
exc_traceback (in module sys), [リンク]
exc_type (in module sys), [リンク]
exc_value (in module sys), [リンク]
Exception (built-in exception)
exceptions (組み込み モジュール)
exec_prefix (environment variable), [リンク], [リンク]
exec_prefix (環境変数), [リンク], [リンク]
executable (in module sys)
exit()

F

file オブジェクト
FileType (in module types)
float() (組み込み関数)
floating point オブジェクト
FloatType (in modules types)
fopen()
free()
freeze utility

G

getcharbufferproc (C の型)
getreadbufferproc (C の型)
getsegcountproc (C の型)
getwritebufferproc (C の型)
global interpreter lock

H

hash() (組み込み関数), [リンク]

I

ihooks (標準 モジュール)
incr_item(), [リンク]
inquiry (C の型)
instance オブジェクト
int() (組み込み関数)
integer オブジェクト
interpreter lock
IntType (in modules types)

K

環境変数
exec_prefix, [リンク], [リンク]
PATH, [リンク]
prefix, [リンク], [リンク], [リンク], [リンク]
PYTHONDUMPREFS
環境変数 (続き)
PYTHONHOME, [リンク]
PYTHONPATH, [リンク]
KeyboardInterrupt (built-in exception), [リンク]

L

len() (組み込み関数), [リンク], [リンク], [リンク], [リンク]
list オブジェクト
ListType (in module types)
lock, interpreter
long() (組み込み関数)
long integer オブジェクト
LONG_MAX, [リンク]
LongType (in modules types)

M

main(), [リンク]
malloc()
mapping オブジェクト
METH_CLASS
METH_KEYWORDS
METH_NOARGS
METH_O
METH_OLDARGS
METH_STATIC
METH_VARARGS
method オブジェクト
MethodType (in module types)
module
search path, [リンク], [リンク]
module オブジェクト
modules (in module sys), [リンク]
ModuleType (in module types)

N

\textttNone オブジェクト
numeric オブジェクト

O

ob_refcnt (PyObject のメンバ)
ob_size (PyVarObject のメンバ)
ob_type (PyObject のメンバ)
オブジェクト
buffer
CObject
complex number
dictionary
file
floating point
instance
integer
list
オブジェクト (続き)
long integer
mapping
method
module
\textttNone
numeric
sequence
string
tuple
type, [リンク]
OverflowError (built-in exception), [リンク]

P

package variable
__all__
path
module search, [リンク], [リンク]
PATH (environment variable), [リンク]
path (in module sys), [リンク], [リンク]
PATH (環境変数), [リンク]
platform (in module sys)
pow() (組み込み関数), [リンク]
prefix (environment variable), [リンク], [リンク], [リンク], [リンク]
prefix (環境変数), [リンク], [リンク], [リンク], [リンク]
Py_AtExit()
Py_BEGIN_ALLOW_THREADS, [リンク]
Py_BLOCK_THREADS
Py_BuildValue()
Py_CompileString(), [リンク], [リンク], [リンク]
Py_complex (C の型)
Py_DECREF(), [リンク]
Py_END_ALLOW_THREADS, [リンク]
Py_END_OF_BUFFER
Py_EndInterpreter()
Py_eval_input
Py_Exit()
Py_FatalError(), [リンク]
Py_FdIsInteractive()
Py_file_input
Py_Finalize(), [リンク], [リンク], [リンク], [リンク], [リンク]
Py_FindMethod()
Py_GetBuildInfo()
Py_GetCompiler()
Py_GetCopyright()
Py_GetExecPrefix(), [リンク]
Py_GetPath(), [リンク], [リンク]
Py_GetPlatform()
Py_GetPrefix(), [リンク]
Py_GetProgramFullPath(), [リンク]
Py_GetProgramName()
Py_GetVersion()
Py_INCREF(), [リンク]
Py_Initialize(), [リンク], [リンク], [リンク], [リンク]
Py_InitModule()
Py_InitModule3()
Py_InitModule4()
Py_IsInitialized(), [リンク]
Py_Main()
Py_NewInterpreter()
Py_None
Py_PRINT_RAW
Py_SetProgramName(), [リンク], [リンク], [リンク], [リンク]
Py_single_input
Py_TPFLAGS_BASETYPE
Py_TPFLAGS_CHECKTYPES
Py_TPFLAGS_DEFAULT
Py_TPFLAGS_GC
Py_TPFLAGS_HAVE_CLASS
Py_TPFLAGS_HAVE_GC, [リンク]
Py_TPFLAGS_HAVE_GETCHARBUFFER, [リンク]
Py_TPFLAGS_HAVE_INPLACEOPS
Py_TPFLAGS_HAVE_ITER
Py_TPFLAGS_HAVE_RICHCOMPARE
Py_TPFLAGS_HAVE_SEQUENCE_IN
Py_TPFLAGS_HAVE_WEAKREFS
Py_TPFLAGS_HEAPTYPE
Py_TPFLAGS_READY
Py_TPFLAGS_READYING
Py_tracefunc (C の型)
Py_UNBLOCK_THREADS
Py_UNICODE (C の型)
Py_UNICODE_ISALNUM()
Py_UNICODE_ISALPHA()
Py_UNICODE_ISDECIMAL()
Py_UNICODE_ISDIGIT()
Py_UNICODE_ISLINEBREAK()
Py_UNICODE_ISLOWER()
Py_UNICODE_ISNUMERIC()
Py_UNICODE_ISSPACE()
Py_UNICODE_ISTITLE()
Py_UNICODE_ISUPPER()
Py_UNICODE_TODECIMAL()
Py_UNICODE_TODIGIT()
Py_UNICODE_TOLOWER()
Py_UNICODE_TONUMERIC()
Py_UNICODE_TOTITLE()
Py_UNICODE_TOUPPER()
Py_XDECREF(), [リンク]
Py_XINCREF()
PyArg_Parse()
PyArg_ParseTuple()
PyArg_ParseTupleAndKeywords()
PyArg_UnpackTuple()
PyBuffer_Check()
PyBuffer_FromMemory()
PyBuffer_FromObject()
PyBuffer_FromReadWriteMemory()
PyBuffer_FromReadWriteObject()
PyBuffer_New()
PyBuffer_Type
PyBufferObject (C の型)
PyBufferProcs
PyBufferProcs (C の型)
PyCallable_Check()
PyCallIter_Check()
PyCallIter_New()
PyCallIter_Type
PyCell_Check()
PyCell_GET()
PyCell_Get()
PyCell_New()
PyCell_SET()
PyCell_Set()
PyCell_Type
PyCellObject (C の型)
PyCFunction (C の型)
PyCObject (C の型)
PyCObject_AsVoidPtr()
PyCObject_Check()
PyCObject_FromVoidPtr()
PyCObject_FromVoidPtrAndDesc()
PyCObject_GetDesc()
PyComplex_AsCComplex()
PyComplex_Check()
PyComplex_CheckExact()
PyComplex_FromCComplex()
PyComplex_FromDoubles()
PyComplex_ImagAsDouble()
PyComplex_RealAsDouble()
PyComplex_Type
PyComplexObject (C の型)
PyDescr_IsData()
PyDescr_NewGetSet()
PyDescr_NewMember()
PyDescr_NewMethod()
PyDescr_NewWrapper()
PyDict_Check()
PyDict_Clear()
PyDict_Copy()
PyDict_DelItem()
PyDict_DelItemString()
PyDict_GetItem()
PyDict_GetItemString()
PyDict_Items()
PyDict_Keys()
PyDict_Merge()
PyDict_MergeFromSeq2()
PyDict_New()
PyDict_Next()
PyDict_SetItem()
PyDict_SetItemString()
PyDict_Size()
PyDict_Type
PyDict_Update()
PyDict_Values()
PyDictObject (C の型)
PyDictProxy_New()
PyErr_BadArgument()
PyErr_BadInternalCall()
PyErr_CheckSignals()
PyErr_Clear(), [リンク], [リンク]
PyErr_ExceptionMatches(), [リンク]
PyErr_Fetch()
PyErr_Format()
PyErr_GivenExceptionMatches()
PyErr_NewException()
PyErr_NoMemory()
PyErr_NormalizeException()
PyErr_Occurred(), [リンク]
PyErr_Print()
PyErr_Restore()
PyErr_SetExcFromWindowsErr()
PyErr_SetExcFromWindowsErrWithFilename()
PyErr_SetFromErrno()
PyErr_SetFromErrnoWithFilename()
PyErr_SetFromWindowsErr()
PyErr_SetFromWindowsErrWithFilename()
PyErr_SetInterrupt()
PyErr_SetNone()
PyErr_SetObject()
PyErr_SetString(), [リンク]
PyErr_Warn()
PyErr_WarnExplicit()
PyErr_WriteUnraisable()
PyEval_AcquireLock(), [リンク], [リンク]
PyEval_AcquireThread()
PyEval_InitThreads(), [リンク]
PyEval_ReleaseLock(), [リンク], [リンク], [リンク]
PyEval_ReleaseThread(), [リンク]
PyEval_RestoreThread(), [リンク]
PyEval_SaveThread(), [リンク]
PyEval_SetProfile()
PyEval_SetTrace()
PyFile_AsFile()
PyFile_Check()
PyFile_CheckExact()
PyFile_Encoding()
PyFile_FromFile()
PyFile_FromString()
PyFile_GetLine()
PyFile_Name()
PyFile_SetBufSize()
PyFile_SoftSpace()
PyFile_Type
PyFile_WriteObject()
PyFile_WriteString()
PyFileObject (C の型)
PyFloat_AS_DOUBLE()
PyFloat_AsDouble()
PyFloat_Check()
PyFloat_CheckExact()
PyFloat_FromDouble()
PyFloat_FromString()
PyFloat_Type
PyFloatObject (C の型)
PyImport_AddModule()
PyImport_AppendInittab()
PyImport_Cleanup()
PyImport_ExecCodeModule()
PyImport_ExtendInittab()
PyImport_FrozenModules
PyImport_GetMagicNumber()
PyImport_GetModuleDict()
PyImport_Import()
PyImport_ImportFrozenModule()
PyImport_ImportModule()
PyImport_ImportModuleEx()
PyImport_ReloadModule()
PyInstance_Check()
PyInstance_New()
PyInstance_NewRaw()
PyInstance_Type
PyInt_AS_LONG()
PyInt_AsLong()
PyInt_AsUnsignedLongLongMask()
PyInt_AsUnsignedLongMask()
PyInt_Check()
PyInt_CheckExact()
PyInt_FromLong()
PyInt_FromString()
PyInt_GetMax()
PyInt_Type
PyInterpreterState (C の型)
PyInterpreterState_Clear()
PyInterpreterState_Delete()
PyInterpreterState_Head()
PyInterpreterState_New()
PyInterpreterState_Next()
PyInterpreterState_ThreadHead()
PyIntObject (C の型)
PyIter_Check()
PyIter_Next()
PyList_Append()
PyList_AsTuple()
PyList_Check()
PyList_GET_ITEM()
PyList_GET_SIZE()
PyList_GetItem(), [リンク]
PyList_GetSlice()
PyList_Insert()
PyList_New()
PyList_Reverse()
PyList_SET_ITEM()
PyList_SetItem(), [リンク]
PyList_SetSlice()
PyList_Size()
PyList_Sort()
PyList_Type
PyListObject (C の型)
PyLong_AsDouble()
PyLong_AsLong()
PyLong_AsLongLong()
PyLong_AsUnsignedLong()
PyLong_AsUnsignedLongLong()
PyLong_AsUnsignedLongLongMask()
PyLong_AsUnsignedLongMask()
PyLong_AsVoidPtr()
PyLong_Check()
PyLong_CheckExact()
PyLong_FromDouble()
PyLong_FromLong()
PyLong_FromLongLong()
PyLong_FromString()
PyLong_FromUnicode()
PyLong_FromUnsignedLong()
PyLong_FromUnsignedLongLong()
PyLong_FromVoidPtr()
PyLong_Type
PyLongObject (C の型)
PyMapping_Check()
PyMapping_DelItem()
PyMapping_DelItemString()
PyMapping_GetItemString()
PyMapping_HasKey()
PyMapping_HasKeyString()
PyMapping_Items()
PyMapping_Keys()
PyMapping_Length()
PyMapping_SetItemString()
PyMapping_Values()
PyMappingMethods (C の型)
PyMarshal_ReadLastObjectFromFile()
PyMarshal_ReadLongFromFile()
PyMarshal_ReadObjectFromFile()
PyMarshal_ReadObjectFromString()
PyMarshal_ReadShortFromFile()
PyMarshal_WriteLongToFile()
PyMarshal_WriteObjectToFile()
PyMarshal_WriteObjectToString()
PyMem_Del()
PyMem_Free()
PyMem_Malloc()
PyMem_New()
PyMem_Realloc()
PyMem_Resize()
PyMethod_Check()
PyMethod_Class()
PyMethod_Function()
PyMethod_GET_CLASS()
PyMethod_GET_FUNCTION()
PyMethod_GET_SELF()
PyMethod_New()
PyMethod_Self()
PyMethod_Type
PyMethodDef (C の型)
PyModule_AddIntConstant()
PyModule_AddObject()
PyModule_AddStringConstant()
PyModule_Check()
PyModule_CheckExact()
PyModule_GetDict()
PyModule_GetFilename()
PyModule_GetName()
PyModule_New()
PyModule_Type
PyNumber_Absolute()
PyNumber_Add()
PyNumber_And()
PyNumber_Check()
PyNumber_Coerce()
PyNumber_Divide()
PyNumber_Divmod()
PyNumber_Float()
PyNumber_FloorDivide()
PyNumber_InPlaceAdd()
PyNumber_InPlaceAnd()
PyNumber_InPlaceDivide()
PyNumber_InPlaceFloorDivide()
PyNumber_InPlaceLshift()
PyNumber_InPlaceMultiply()
PyNumber_InPlaceOr()
PyNumber_InPlacePower()
PyNumber_InPlaceRemainder()
PyNumber_InPlaceRshift()
PyNumber_InPlaceSubtract()
PyNumber_InPlaceTrueDivide()
PyNumber_InPlaceXor()
PyNumber_Int()
PyNumber_Invert()
PyNumber_Long()
PyNumber_Lshift()
PyNumber_Multiply()
PyNumber_Negative()
PyNumber_Or()
PyNumber_Positive()
PyNumber_Power()
PyNumber_Remainder()
PyNumber_Rshift()
PyNumber_Subtract()
PyNumber_TrueDivide()
PyNumber_Xor()
PyNumberMethods (C の型)
PyObject (C の型)
PyObject_AsCharBuffer()
PyObject_AsFileDescriptor()
PyObject_AsReadBuffer()
PyObject_AsWriteBuffer()
PyObject_Call()
PyObject_CallFunction()
PyObject_CallFunctionObjArgs()
PyObject_CallMethod()
PyObject_CallMethodObjArgs()
PyObject_CallObject()
PyObject_CheckReadBuffer()
PyObject_Cmp()
PyObject_Compare()
PyObject_DEL()
PyObject_Del()
PyObject_DelAttr()
PyObject_DelAttrString()
PyObject_DelItem()
PyObject_Dir()
PyObject_GC_Del()
PyObject_GC_New()
PyObject_GC_NewVar()
PyObject_GC_Resize()
PyObject_GC_Track()
PyObject_GC_UnTrack()
PyObject_GetAttr()
PyObject_GetAttrString()
PyObject_GetItem()
PyObject_GetIter()
PyObject_HasAttr()
PyObject_HasAttrString()
PyObject_Hash()
PyObject_HEAD
PyObject_HEAD_INIT
PyObject_Init()
PyObject_InitVar()
PyObject_IsInstance()
PyObject_IsSubclass()
PyObject_IsTrue()
PyObject_Length()
PyObject_NEW()
PyObject_New()
PyObject_NEW_VAR()
PyObject_NewVar()
PyObject_Not()
PyObject_Print()
PyObject_Repr()
PyObject_RichCompare()
PyObject_RichCompareBool()
PyObject_SetAttr()
PyObject_SetAttrString()
PyObject_SetItem()
PyObject_Size()
PyObject_Str()
PyObject_Type()
PyObject_TypeCheck()
PyObject_Unicode()
PyObject_VAR_HEAD
PyOS_AfterFork()
PyOS_CheckStack()
PyOS_GetLastModificationTime()
PyOS_getsig()
PyOS_setsig()
PyParser_SimpleParseFile()
PyParser_SimpleParseString()
PyProperty_Type
PyRun_AnyFile()
PyRun_File()
PyRun_InteractiveLoop()
PyRun_InteractiveOne()
PyRun_SimpleFile()
PyRun_SimpleString()
PyRun_String()
PySeqIter_Check()
PySeqIter_New()
PySeqIter_Type
PySequence_Check()
PySequence_Concat()
PySequence_Contains()
PySequence_Count()
PySequence_DelItem()
PySequence_DelSlice()
PySequence_Fast()
PySequence_Fast_GET_ITEM()
PySequence_Fast_GET_SIZE()
PySequence_GetItem(), [リンク]
PySequence_GetSlice()
PySequence_Index()
PySequence_InPlaceConcat()
PySequence_InPlaceRepeat()
PySequence_ITEM()
PySequence_Length()
PySequence_List()
PySequence_Repeat()
PySequence_SetItem()
PySequence_SetSlice()
PySequence_Size()
PySequence_Tuple(), [リンク]
PySequenceMethods (C の型)
PySlice_Check()
PySlice_GetIndices()
PySlice_GetIndicesEx()
PySlice_New()
PySlice_Type
PyString_AS_STRING()
PyString_AsDecodedObject()
PyString_AsEncodedObject()
PyString_AsString()
PyString_AsStringAndSize()
PyString_Check()
PyString_CheckExact()
PyString_Concat()
PyString_ConcatAndDel()
PyString_Decode()
PyString_Encode()
PyString_Format()
PyString_FromFormat()
PyString_FromFormatV()
PyString_FromString(), [リンク]
PyString_FromStringAndSize()
PyString_GET_SIZE()
PyString_InternFromString()
PyString_InternInPlace()
PyString_Size()
PyString_Type
PyStringObject (C の型)
PySys_SetArgv(), [リンク], [リンク]
PYTHONDUMPREFS (environment variable)
PYTHONDUMPREFS (環境変数)
PYTHONHOME (environment variable), [リンク]
PYTHONHOME (環境変数), [リンク]
PYTHONPATH (environment variable), [リンク]
PYTHONPATH (環境変数), [リンク]
PyThreadState, [リンク]
PyThreadState (C の型)
PyThreadState_Clear()
PyThreadState_Delete()
PyThreadState_Get()
PyThreadState_GetDict()
PyThreadState_New()
PyThreadState_Next()
PyThreadState_SetAsyncExc()
PyThreadState_Swap()
PyTrace_CALL
PyTrace_EXCEPT
PyTrace_LINE
PyTrace_RETURN
PyTuple_Check()
PyTuple_CheckExact()
PyTuple_GET_ITEM()
PyTuple_GET_SIZE()
PyTuple_GetItem()
PyTuple_GetSlice()
PyTuple_New()
PyTuple_SET_ITEM()
PyTuple_SetItem(), [リンク]
PyTuple_Size()
PyTuple_Type
PyTupleObject (C の型)
PyType_Check()
PyType_CheckExact()
PyType_GenericAlloc()
PyType_GenericNew()
PyType_HasFeature(), [リンク]
PyType_IS_GC()
PyType_IsSubtype()
PyType_Ready()
PyType_Type
PyTypeObject (C の型)
PyUnicode_AS_DATA()
PyUnicode_AS_UNICODE()
PyUnicode_AsASCIIString()
PyUnicode_AsCharmapString()
PyUnicode_AsEncodedString()
PyUnicode_AsLatin1String()
PyUnicode_AsMBCSString()
PyUnicode_AsRawUnicodeEscapeString()
PyUnicode_AsUnicode()
PyUnicode_AsUnicodeEscapeString()
PyUnicode_AsUTF16String()
PyUnicode_AsUTF8String()
PyUnicode_AsWideChar()
PyUnicode_Check()
PyUnicode_CheckExact()
PyUnicode_Compare()
PyUnicode_Concat()
PyUnicode_Contains()
PyUnicode_Count()
PyUnicode_Decode()
PyUnicode_DecodeASCII()
PyUnicode_DecodeCharmap()
PyUnicode_DecodeLatin1()
PyUnicode_DecodeMBCS()
PyUnicode_DecodeRawUnicodeEscape()
PyUnicode_DecodeUnicodeEscape()
PyUnicode_DecodeUTF16()
PyUnicode_DecodeUTF8()
PyUnicode_Encode()
PyUnicode_EncodeASCII()
PyUnicode_EncodeCharmap()
PyUnicode_EncodeLatin1()
PyUnicode_EncodeMBCS()
PyUnicode_EncodeRawUnicodeEscape()
PyUnicode_EncodeUnicodeEscape()
PyUnicode_EncodeUTF16()
PyUnicode_EncodeUTF8()
PyUnicode_Find()
PyUnicode_Format()
PyUnicode_FromEncodedObject()
PyUnicode_FromObject()
PyUnicode_FromUnicode()
PyUnicode_FromWideChar()
PyUnicode_GET_DATA_SIZE()
PyUnicode_GET_SIZE()
PyUnicode_GetSize()
PyUnicode_Join()
PyUnicode_Replace()
PyUnicode_Split()
PyUnicode_Splitlines()
PyUnicode_Tailmatch()
PyUnicode_Translate()
PyUnicode_TranslateCharmap()
PyUnicode_Type
PyUnicodeObject (C の型)
PyVarObject (C の型)
PyWeakref_Check()
PyWeakref_CheckProxy()
PyWeakref_CheckRef()
PyWeakref_GET_OBJECT()
PyWeakref_GetObject()
PyWeakref_NewProxy()
PyWeakref_NewRef()
PyWrapper_New()

R

realloc()
reload() (組み込み関数)
repr() (組み込み関数), [リンク]
rexec (標準 モジュール)

S

search
path, module, [リンク], [リンク]
sequence オブジェクト
set_all()
setcheckinterval() (in module sys)
setvbuf()
SIGINT, [リンク]
signal (組み込み モジュール)
SliceType (in module types)
softspace (file attribute)
staticmethod() (組み込み関数)
stderr (in module sys)
stdin (in module sys)
stdout (in module sys)
str() (組み込み関数)
strerror()
string オブジェクト
StringType (in module types)
sum_list()
sum_sequence(), [リンク]
sys (組み込み モジュール), [リンク], [リンク]
SystemError (built-in exception), [リンク]

T

thread (組み込み モジュール)
tp_alloc (PyTypeObject のメンバ)
tp_allocs (PyTypeObject のメンバ)
tp_as_buffer (PyTypeObject のメンバ)
tp_base (PyTypeObject のメンバ)
tp_bases (PyTypeObject のメンバ)
tp_basicsize (PyTypeObject のメンバ)
tp_cache (PyTypeObject のメンバ)
tp_call (PyTypeObject のメンバ)
tp_clear (PyTypeObject のメンバ)
tp_compare (PyTypeObject のメンバ)
tp_dealloc (PyTypeObject のメンバ)
tp_descr_get (PyTypeObject のメンバ)
tp_descr_set (PyTypeObject のメンバ)
tp_dict (PyTypeObject のメンバ)
tp_dictoffset (PyTypeObject のメンバ)
tp_doc (PyTypeObject のメンバ)
tp_flags (PyTypeObject のメンバ)
tp_free (PyTypeObject のメンバ)
tp_frees (PyTypeObject のメンバ)
tp_getattr (PyTypeObject のメンバ)
tp_getattro (PyTypeObject のメンバ)
tp_getset (PyTypeObject のメンバ)
tp_hash (PyTypeObject のメンバ)
tp_init (PyTypeObject のメンバ)
tp_is_gc (PyTypeObject のメンバ)
tp_itemsize (PyTypeObject のメンバ)
tp_iter (PyTypeObject のメンバ)
tp_iternext (PyTypeObject のメンバ)
tp_maxalloc (PyTypeObject のメンバ)
tp_members (PyTypeObject のメンバ)
tp_methods (PyTypeObject のメンバ)
tp_mro (PyTypeObject のメンバ)
tp_name (PyTypeObject のメンバ)
tp_new (PyTypeObject のメンバ)
tp_next (PyTypeObject のメンバ)
tp_print (PyTypeObject のメンバ)
tp_repr (PyTypeObject のメンバ)
tp_richcompare (PyTypeObject のメンバ)
tp_setattr (PyTypeObject のメンバ)
tp_setattro (PyTypeObject のメンバ)
tp_str (PyTypeObject のメンバ)
tp_subclasses (PyTypeObject のメンバ)
tp_traverse (PyTypeObject のメンバ)
tp_weaklist (PyTypeObject のメンバ)
tp_weaklistoffset (PyTypeObject のメンバ)
traverseproc (C の型)
tuple() (組み込み関数), [リンク]
tuple オブジェクト
TupleType (in module types)
type() (組み込み関数)
type オブジェクト, [リンク]
TypeType (in module types)

U

ULONG_MAX
unicode() (組み込み関数)

V

version (in module sys), [リンク], [リンク]
visitproc (C の型)

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents
Previous: C.2 翻訳者一覧 (敬称略) Up: Python/C API リファレンスマニュアル Next: この文書について...
Release 2.3.3, documentation updated on December 19, 2003.


Python ドキュメントの作成

Fred L. Drake, Jr.

PythonLabs
Email: fdrake@acm.org

日本語訳: Python ドキュメント翻訳プロジェクト

概要:

Python には様々な著者により寄稿された非常に多くのドキュメント類があり ます。Python のドキュメント作成に使われるマークアップは LATEX に 基づいていて、Python のドキュメント作成用に特別に書かれたかなりの数の マクロセットを必要とします。 このドキュメントでは、Python のドキュメント作成をサポートするために 採用されているマクロ、および広範な出力形式をサポートするために マクロをどのように使うかについて述べます。

このドキュメントでは、Python ドキュメント作成で使うドキュメントクラス と特殊なマークアップについて述べます。 ドキュメントの作者は、このガイドと Python 配布物で提供されている 雛形ファイルを組み合わせて使い、ドキュメント全体やドキュメントの 各セクションを作成したり維持したりできます。

  • 目次
  • 1 初めに
  • 2 ディレクトリ構造
  • 3 スタイルガイド
  • 4 LATEX 入門
    • 4.1 構文法
    • 4.2 階層構造
  • 5 ドキュメントクラス
  • 6 特殊マークアップ構文
    • 6.1 プリアンブル用のマークアップ
    • 6.2 メタ情報マークアップ
    • 6.3 情報単位
    • 6.4 コードの例示
    • 6.5 インラインマークアップ
    • 6.6 雑多なテキストマークアップ
    • 6.7 モジュール特有のマークアップ
    • 6.8 ライブラリレベルのマークアップ
    • 6.9 表のマークアップ
    • 6.10 参考文献リストのマークアップ
    • 6.11 索引生成のためのマークアップ
    • 6.12 文法における導出の表示
    • 6.13 グラフィカルインタフェースの構成要素
  • 7 処理ツール
    • 7.1 外部ツール
    • 7.2 内部用ツール
    • 7.3 Cygwin での作業
  • 8 将来の方向性
    • 8.1 構造化ドキュメント
    • 8.2 議論の場
  • A. 日本語訳について
    • A..1 このドキュメントについて
    • A..2 翻訳者一覧
  • この文書について...
Up One Level Next Page Python ドキュメントの作成 Contents
Up: Python ドキュメントインデクス Next: 目次


1 初めに

Python のドキュメントは、このフリーなプログラミング言語の長所であると 考えられてきました。その理由は多々ありますが、最も重要なのは、 Python の作者である Guido van Rossum が、言語やそのライブラリの ドキュメントの提供と、ドキュメントの作成と維持の手助けする上での ユーザコミュニティの継続的な参加に早期から関わっていたことです。

コミュニティの参加には、バグ報告の作成から、単にドキュメントがより 完全で利用しやすいものになりうる場合に素朴な提案を発するといったこと まで、数多くの形式があります。 作者がドキュメントの維持に参加している中で、こうしたコミュニティからの 入力の全てが有用なものであると証明されました。

このドキュメントは、Python のドキュメントの作者、あるいは潜在的な 作者向けのものです。もっと具体的にいうと、標準ドキュメントに貢献 したり、標準ドキュメントと同じツールを使って別のドキュメントを 開発する人々向けです。 このガイドは Python 以外のトピックに Python ドキュメント作成 ツールを使う作者にとってはあまり有用ではなく、ツールを全く使用しない 作者にもあまり有用ではないでしょう。

このガイドに書かれていることは、Python ドキュメント作成ツールを使う 著者の支援を目的としています。ガイドには、標準ドキュメントのソース 配布に関する情報、ドキュメントタイプに関する議論、ドキュメントクラス中で で定義されているマークアップについてのリファレンス、ドキュメントを処理する 上で必要な外部ツールのリスト、ドキュメントリソースと共に提供されている ツールに関するリファレンスが入っています。ガイドの末尾には、Python ドキュメントの将来の方向性と、詳細な情報をどこで取得できるかについて 議論した章もあります。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 目次 Up: Python ドキュメントの作成 Next: 2 ディレクトリ構造


2 ディレクトリ構造

標準 Python ドキュメントのソース配布物には、数多くのディレクトリが 入っています。サードパーティ製のドキュメントは、このディレクトリ構造下や 似たディレクトリ構造下におく必要はありませんが、Python ドキュメント作成 ツールを利用して新たなドキュメントを開発する際に、どこで例題やツールを 探せばよいか知っておけば便利でしょう。そこでこの節では、ディレクトリ 構造について述べます。

ドキュメントソースは通常、Doc/ をトップレベルディレクトリとして Python ソース配布物中に配置されていますが、Python ソース配布物 には全く依存していません。

Doc/ ディレクトリには、いくつかのファイルとサブディレクトリ が入っています。ファイルはREADME や Makefile を含め、 ほとんどが自明なものです。ディレクトリは以下の三つのカテゴリーに 分類されます:

ドキュメントソース
各ドキュメントの LATEX ソースは個別のディレクトリに配置されています。 ディレクトリには、各々のドキュメントを漠然と説明する短い名前がついて います:

ディレクトリ | タイトル
api/ | Python/C API
dist/ | Python モジュールの配布
doc/ | Python ドキュメントの作成
ext/ | Python インタプリタの拡張と埋め込み
inst/ | Python モジュールのインストール
lib/ | Python ライブラリリファレンス
mac/ | Macintosh モジュールリファレンス
ref/ | Python リファレンスマニュアル
tut/ | Python チュートリアル

出力書式ごとの出力ディレクトリ
ほとんどの出力書式に対して、個々の出力書式の生成を制御するMakefile が入っている、書式化されたドキュメントを格納するためのディレクトリが あります。 このカテゴリの例外となるのは Portable Document Format (PDF) および PostScript 版で、これらは paper-a4/ および paper-letter/ に配置されます (こうすることで、LATEX が生成する全ての一時ファイル は用紙サイズごとに同じ場所に置かれ、目立たなくできます)

ディレクトリ | 出力書式
html/ | HTML 形式
info/ | GNU info 形式
isilo/ | iSilo ドキュメント (Palm OS 機器用)
paper-a4/ | PDF とPostScript、A4 サイズ
paper-letter/ | PDF と PostScript、US-Letter サイズ

補助ファイル群

その他のディレクトリは、様々な処理で用いられる補助ファイル群を格納 するためのものです。補助ファイル群は、共有される LATEX ドキュメントクラス、LATEX2HTML のサポートファイル、様々な ドキュメント構成要素のための雛形ファイル、書式化処理の様々な処理段階を 実現するスクリプトなどです。

ディレクトリ | 内容
commontex/ | ドキュメント間で共通の文章
perl/ | LATEX2HTML 処理のサポート
templates/ | ソースドキュメントの例
texinputs/ | LATEXスタイルファイル
tools/ | 独自の処理用スクリプト

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 1 初めに Up: Python ドキュメントの作成 Next: 3 スタイルガイド


3 スタイルガイド

Python ドキュメントは、可能な限り Apple Publications Style Guide に準拠することになっています。内容の合理性と、オンラインで 容易に取得できることから、このスタイルガイドが選ばれました。

Apple のスタイルガイドがカバーしていないトピックについては、この ドキュメントで必要に応じて議論していきます。

Python ドキュメントの中では、オペレーティングシステムやプログラミング 言語、標準機関、その他の名前を含む沢山の特殊な名前が使われています。 こうした名前の多くはかなり古い時期にLATEX マクロに割り当てられ、 その便利さから長い間利用されつづけてきました。現在のマークアップでは、 こうしたエンティティのほとんどには特殊なマークアップを割り当てません。 その代わり、推奨される表記法を提供して、ドキュメント作者が Python ドキュメントにおける表現の一貫性を維持できるよう手助けしています。

その他の用語や単語についても特筆する必要があります; これらの規約に 従い、ドキュメント全体を通して一貫性を保証しなければなりません。

CPU

``central processing unit'' (中央処理装置) のことです。多くの スタイルガイドが、この語を最初に利用するときには略さずに書かねば ならないとしています (ですから、どうしてもこの語を使う必要があるなら、 かならずそうしてください!)。 Python ドキュメントでは、読者がこの略語を 最初に読むのがどこかを予測できる合理的な方法がないので、略語の 使用を避けねばなりません。代わりに ``processor (プロセッサ)'' を 使う方がよいでしょう。

POSIX

ある特定の標準仕様グループにつけられた名前です。常に大文字だけからなります。 この名前を表現するにはマクロ \POSIX を使用してください。

Python

私たちの好きなプログラミング言語の名前は常に大文字で始めます。

Unicode

文字セットと、対応する符号化方式の名前です。常に大文字で始めます。

Unix

1970年代初頭に AT&T ベル研究所で開発されたオペレーティングシステムの名前 です。この名前を使うにはマクロの \UNIX を使用してください。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 2 ディレクトリ構造 Up: Python ドキュメントの作成 Next: 4 LATEX 入門


4 LATEX 入門

この節では、LATEX の概念と構文法について簡単に紹介し、 ドキュメントの作者が ``TEXnician'' にならなくてもドキュメントを 十分生産的に書けるような情報を提供します。

おそらく、Python ドキュメントのマークアップにおいて心に留めておくべき 最も重要な概念は、TEX が非体系的なのに対して、LATEX は TEX の上のレイヤとして設計されていて、本質的には構造化マークアップを サポートしているということです。 Python 特有のマークアップは、 標準の LATEX ドキュメントクラスで提供されている構造を拡張し、 Python 特有の情報のサポートを目的としています。

LATEX ドキュメントには、二つの構成要素: プリアンブルと本体が 入っています。プリアンブルは、タイトル、著者のリスト、日付、ドキュメント が属する クラス といった、ドキュメント自体に関するメタデータ を指定するために使用されます。その他の情報で、インデクスの生成や 参考文献データベースの使用を制御するものもプリアンブル内に置けます。 ほとんどの著者にとっては、既存のドキュメントからプリアンブルをコピーし、 いくつかの情報を修正するだけで、簡単にプリアンブルを作成できます。

ドキュメントのクラス は、広範なドキュメントカテゴリに おける位置づけを行い、基本的な書式化プロパティを設定するために 使われます。 Python ドキュメントの場合、二つのクラス: manual クラスと howto クラスが使われています。 これらのクラスではまた、Python における概念やデータ構造を記述 する際に使う追加のマークアップを定義しています。これらのクラスに 関する詳しい説明は後述の 5 節、 ``ドキュメントクラス'' にあります。プリアンブルの最初に置かれているのが、ドキュメントクラスの 宣言です。

クラス宣言の後ろには数多くのマクロ があり、ドキュメントに 関する詳しい情報を与えたり、追加の必要なマークアップを設定しています。 プリアンブルからは何も出力生成されません; 自由文 (free text) は出力生成につながるため、プリアンブルに自由文をおくとエラーに なります。

ドキュメント本体はプリアンブルの後に続けます。本体には、出力すべき ドキュメントの構成要素を構造的にマークアップして入れます。 一般的なLATEX の構造には、階層化された章節、番号付けリストや 箇条書きリスト、そしてドキュメントの概要や索引といった特殊な 構造があります。

  • 4.1 構文法
  • 4.2 階層構造
Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 3 スタイルガイド Up: Python ドキュメントの作成 Next: 4.1 構文法


4.1 構文法

Python ドキュメントの作者は、LATEX の構文法についていくつか知って おかねばならないことがあります。

コメント は、``パーセント'' 文字 ("%") から始まり、行末まで、または次の行の先頭にある空白文字まで続きます。 これは著者の知っているどのプログラミング言語とも少し違っています。 そこで、順序立てて例を挙げます:

This is text.% comment
    This is more text.  % another comment
Still more text.

最初の行のコメントの後ろに続くコメントでない文字は、二行目の "T" になります; 二行目の先頭にある空白文字は、最初の行の コメントの一部として消費されてしまいます。これは、最初と二つ目の 文との間には全くスペースがなく、最初の行のピリオドと二行目の文字 "T" はタイプセット時に直接くっつけることを意味します。

二つめのコメントの直後にくる非コメント文字は "S" ですが、 二つ目のコメントの直前に空白を入れているため、意図通りに二つの 単語が分割されることにも注意してください。

グループ は一連のテキストやコマンドに対する囲いで、 書式化処理のコンテキストを囲い、グループ内のコマンドが処理コンテキスト に及ぼす変更の範囲を制限します。 グループは入れ子構造にして階層化できます。書式化処理のコンテキストは、 フォントや、追加のマクロ定義 (またはグループ外部で定義されているマクロ に対するオーバライド) を含みます。構文法的には、グループは波括弧で 囲います:

{text in a group}

グループを表すには、ブラケット [...] を使う代用構文もあります。 この代用構文はマクロや環境のコンストラクタでオプションのパラメタをとる ものが使います; ブラケットは通常、構文的な意味を持っていません。 内容が唯一の原始的要素 (atomic bit) からなるような縮重グループ (degenerate group) の場合、あいまいさを防ぐために必須である場合をのぞき、 明示的なグループにする必要はありません。とはいえ、 Python は明示的であることをよしとするので、ドキュメントのマークアップ においてもグループを明示します。

マクロや環境におけるパラメタをマークする場合を除き、Python ドキュメントでは グループを控えめに使います。

マクロ は通常は単純な構成要素で、マクロ名で識別 され、いくつかのパラメタを取ることがあります。通常の LATEX の 使用法では、パラメタのうちの一つがオプションになっていることが あります。マークアップはバックスラッシュ文字 ("\") から 始め、マクロ名はアルファベット文字 (数字、ハイフン、アンダースコア以外) で与えます。必須パラメタはグループとしてマークし、 オプションのパラメタはグループの代用構文でマークせねばなりません。

例えば、 単一のパラメタにとる ``foo'' という名のマクロは以下のように なります:

\name{parameter}
オプションのパラメタをとるマクロで、パラメタを指定するときには以下の ように入力します:

\name[optional]
オプションと必須パラメタの両方が必要な場合には、以下のようになります:

\name[optional]{required}

マクロ名の後ろには空白や改行を入れてもかまいません; この場合、マクロ名と パラメタ間の空白は取り去られてしまいます。しかし、Python ドキュメント ではこうした使い方を実践しません。空白はマクロにパラメタがない場合にも 取り去られますが、この場合には空のグループ ({}) や、空白の 明示的表現 ("\ ") をマクロ名の直後に続けると、マクロ展開が 後続の文字に及ぶのを避ける手助けになります。 パラメタを取らないが、後ろに空白を続けたくないマクロの場合には、 ドキュメントソース中で名前の後ろに名前に使わない文字 (区切り文字など) が 入っていれば、特別扱いする必要はありません。

例題中の各行は、パラメタをとらないマクロが入った文章を書くための 適切な方法を示しています。

This \UNIX{} is followed by a space.
This \UNIX\ is also followed by a space.
\UNIX, followed by a comma, needs no additional markup.

環境 はマクロよりも大きな構文要素で、 マクロの引数に入れるには内容がやや大きすぎて便利さを欠く場合に 利用できます。本文の大きな断片の前後で書式化パラメタを変更する 必要があり、かつ本文の記述に高い柔軟性を持たせたい場合に主に利用 されます。コード例は環境を使って表現します。また、関数、メソッド、 クラスの定義も環境を使ってマークします。

環境内に記述する内容は自由形式で複数の段落にできるため、実際には 二つのマクロからなるペア: \begin および \end を 使ってマークします。これらのマクロはいずれも環境の名前をパラメタにとります。 以下の例は、ドキュメントの概要をマークするために使う環境です:

\begin{abstract}
  This is the text of the abstract.  It concisely explains what
  information is found in the document.

  It can consist of multiple paragraphs.
\end{abstract}

環境は、環境自体の必須パラメタやオプションパラメタを持つこともあります。 これらのパラメタは \begin マクロのパラメタの後ろに続けます。 以下に単一の必須パラメタをとる環境の例を示します:

\begin{datadesc}{controlnames}
  A 33-element string array that contains the \ASCII{} mnemonics for
  the thirty-two \ASCII{} control characters from 0 (NUL) to 0x1f
  (US), in order, plus the mnemonic \samp{SP} for the space character.
\end{datadesc}

ASCII に含まれない文字、特殊文字とされている文字、TEX や LATEXで アクティブ (active) な文字を入力するための、 あまり使われないマークアップがあります。 これらのマークアップはよく他の文字に隣接して使われるので、適切な 文字を生成するためには、マークアップの後ろにスペースや空のグループ を置く必要があるかもしれません。あるいは、マークアップをグループ内に 囲うこともできます。Python ドキュメントで使われるようなマークアップを 以下にいくつか示します:

キャラクタ文字 | マークアップ
^ | \textasciicircum
~ | \textasciitilde
> | \textgreater
< | \textless
ç | \c c
ö | \"o
ø | \o

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 4 LATEX 入門 Up: 4 LATEX 入門 Next: 4.2 階層構造


4.2 階層構造

LATEX は、章、セクション、サブセクション、付録などといった、 伝統的な階層化された方法でドキュメントが整理されると想定しています。 これらの各階層は環境ではなくマクロでマークされますが、おそらくこれは ある章構造とレベルが同じかより高い章構造が続くと、その章がそこで 終わったと考えて差し支えないからでしょう。

Python ドキュメントが使っているクラスには 6 段階の章節分けの ``レベル'' があり、そのうち最も深い 2 レベル1 は使いません。

レベル | マクロ名 | 注釈
1 | \chapter | (1)
2 | \section |
3 | \subsection |
4 | \subsubsection |
5 | \paragraph | (2)
6 | \subparagraph |

注釈:

(1)
5 節、``ドキュメントクラス'' で述べたように、 manual ドキュメントだけで使います。

(2)
テキストの段落とは違います; このレベルは誰も使っていないようです。

... レベル1
表中では、深いレベルほど 番号が大きくなります。
Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 4.1 構文法 Up: 4 LATEX 入門 Next: 5 ドキュメントクラス


5 ドキュメントクラス

2つの LATEX ドキュメントクラスが Python ドキュメントで使うために 定義されています。manual クラスは、章単位で区分するような大きな ドキュメントのためのクラスです。howto クラスはより小さな ドキュメントのためのクラスです。

manual ドキュメントは大規模で、ほとんどの標準ドキュメント が使うクラスです。このドキュメントクラスは標準 LATEX の report クラスに基づいていて、まるで長い技術的報告書のように書式化されます。 ます。Python リファレンスマニュアル は manual ドキュメントのよい例です。また、 Python Library Reference は大規模な文書の 例です。

howto ドキュメントはより短く、manual ドキュメントのような 大きな構造を持ちません。このクラスは標準 LATEX のarticle クラスに基づいていて、Linux Documentation プロジェクトの ``HOWTO'' シリーズのように書式化されます。``HOWTO'' シリーズはもともと LinuxDoc ソフトウェアを使って書式化を行っています。このドキュメントクラスの本来の 目的は、 LDP の HOWTO シリーズと同様の役割として役立つことでしたが、 このクラスにはより広範囲な適用性があることが判明したのです。 このクラスは ``how-to'' ドキュメント (このドキュメントがその一例です) や、小規模で、かなり強い関連性で結ばれたモジュールライブラリ群の リファレンスマニュアルに用いられます。 後者のドキュメントクラスの例には Using Kerberos from Python があります。これらのドキュメントは、大きな ドキュメントにおける一個の章とだいたい同じ規模です。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 4.2 階層構造 Up: Python ドキュメントの作成 Next: 6 特殊マークアップ構文


6 特殊マークアップ構文

Python ドキュメントのクラスでは、環境やマクロを新たに数多く定義しています。 この節にはこれらの機能についてのリファレンスマニュアルがあります。

  • 6.1 プリアンブル用のマークアップ
  • 6.2 メタ情報マークアップ
  • 6.3 情報単位
  • 6.4 コードの例示
  • 6.5 インラインマークアップ
  • 6.6 雑多なテキストマークアップ
  • 6.7 モジュール特有のマークアップ
  • 6.8 ライブラリレベルのマークアップ
  • 6.9 表のマークアップ
  • 6.10 参考文献リストのマークアップ
  • 6.11 索引生成のためのマークアップ
  • 6.12 文法における導出の表示
  • 6.13 グラフィカルインタフェースの構成要素
Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 5 ドキュメントクラス Up: Python ドキュメントの作成 Next: 6.1 プリアンブル用のマークアップ


6.1 プリアンブル用のマークアップ

\release {ver}
このマークアップは、ドキュメント中で述べているソフトウェアのバージョン 番号を設定します。

\setshortversion {sver}
このマークアップは、ドキュメントが扱っているソフトウェアの ``短い形式の'' バージョン番号をsver にします。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 6 特殊マークアップ構文 Up: 6 特殊マークアップ構文 Next: 6.2 メタ情報マークアップ


6.2 メタ情報マークアップ

\sectionauthor {author}{email}

現在の節の作者を指定します。author は作者の名前で、著者紹介 に使える形式になっていなければなりません (もっとも、実際には使われ ません)。また、email は作者の電子メールアドレスです。 アドレスのドメインネーム部分は小文字にしなければなりません。

このマークアップを行っても著者紹介は生成されませんが、だれがドキュメント に貢献したかを追跡する上での補助として用いられます。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 6.1 プリアンブル用のマークアップ Up: 6 特殊マークアップ構文 Next: 6.3 情報単位


6.3 情報単位

モジュールが提供している特定の機能を説明するために使うマクロが 数多くあります。これらの各環境はパラメタをとり、 その環境で何を説明しようとしているかを表す基本的な情報を与える 必要があります。そして、説明内容は環境の中で記述します。 こうした環境のほとんどは、 (ドキュメントが総合索引を生成する場合には) 総合索引上のエントリになります; 索引エントリが必要ない場合、 各環境について索引を生成しない変化形を利用できます。 環境はfeaturedesc という形式の名前になり、索引を生成しない 変化形は featuredescni という形式の名前になります。 利用可能な変化形がある場合は以下のリスト内に明示しています。

各々の環境について、最初のパラメタ name は、アクセスする 機能を指定する名前です。

オブジェクトのメソッドやデータ属性といった、モジュール内の オブジェクトのもつ機能を記述するための環境では、オプションの type name パラメタを指定できます。 該当する機能がクラスインスタンスの属性である場合、type name を与える必要があるのは、クラスがそのモジュールの説明で最後に説明した クラスでない場合だけです; それ以外の場合、最後に説明した\classdesc の name が適用されます。 組み込み型や拡張型の機能については、type name を常に与えねば なりません。もう一つ特殊なケースとして、formatter モジュールに おける formatter や writer のような、汎用の ``プロトコル'' の メソッドやメンバがあります: これらのドキュメントは特定の実装クラスを 伴わず、常に type name パラメタを指定する必要があります。

\begin{cfuncdesc}
    {type}{name}{args}
\end{cfuncdesc}
C 関数を解説するときに使う環境です。type は typedef されている型名か、 struct tag か、基本型の名前でなければ なりません。ポインタ型の場合、後続するアスタリスクの前にスペースを 入れてはなりません。name は関数 (または関数に似た形式をとる プリプロセッサマクロ) の名前でなくてはならず、args にはパラメタの 型と名前を与えねばなりません。名前は説明文内でも使える形式で書かねば なりません。

\begin{cmemberdesc}
    {container}{type}{name}
\end{cmemberdesc}
構造体メンバを説明するときに使う環境です。container には、 typedef されている名前ならそれを使い、そうでなければ "struct tag" と指定せねばなりません。 メンバの型は type に指定し、メンバ名は name に指定します。 説明文中には変数の許容範囲、値がどのように解釈されるか、そして 値が変更可能かを記述せねばなりません。本文中で構造体メンバを参照する 場合には、 \member マクロを使います。

\begin{csimplemacrodesc}
    {name}
\end{csimplemacrodesc}
``単純'' マクロを説明するときに使う環境です。単純マクロは、 引数を取らないため関数で記述できないようなコードの展開に使われます。 この環境は単純な定数定義には用いません。 Python ドキュメント内でのこのマクロの用例としては、 PyObject_HEAD やPy_BEGIN_ALLOW_THREADS が あります。

\begin{ctypedesc}
    [tag]{name}
\end{ctypedesc}
C の型を説明するときに使う環境です。name パラメタは typedef された名前でなければなりません。 型がtypedef を伴わずに struct で定義されている 場合、 name は struct tag の形式を取らねば なりません。tag がない限りname が索引に追加されます。 tag がある場合、 tag を索引に使います。 tag は typedef された名前であってはなりません。

\begin{cvardesc}
    {type}{name}
\end{cvardesc}
グローバルな C の変数を説明するときに使う環境です。 type は typedef されている型名か、 struct tag か、基本型の名前でなければ なりません。ポインタ型の場合、後続するアスタリスクの前にスペースを 入れてはなりません。

\begin{datadesc}
    {name}
\end{datadesc}
この環境は、モジュールにおけるグローバルなデータを説明する際に 使います。グローバルなデータには、変数と ``定義済み定数 (defined constant)'' として使われる値の両方を含みます。クラスやオブジェクト属性の記述には この環境を使いません。
\begin{datadescni}
    {name}
\end{datadescni}
\datadesc に似ていますが、索引エントリを作成しません。

\begin{excclassdesc}
    {name}{constructor parameters}
\end{excclassdesc}
クラスとして定義されている例外を説明するために使います。 constructor parameters には、self やコンストラクタ呼び出し 構文で使う丸括弧を含めてはなりません。コンストラクタに与える パラメタの説明がないような例外クラスを記述するには、 \excdesc 環境を使用してください。

\begin{excdesc}
    {name}
\end{excdesc}
例外を説明するための環境です。クラス例外の場合には、コンストラクタの パラメタが記述されません: 例外クラスとコンストラクタを説明する場合には、 \excclassdesc を使ってください。

\begin{funcdesc}
    {name}{parameters}
\end{funcdesc}
モジュールレベルの関数を説明するための環境です。 parameters には、呼び出しの際に使う丸括弧を含めてはなりません。 オブジェクトメソッドはこの環境で記述しません。 束縛オブジェクトメソッドをモジュールの公開インタフェースの一部として モジュールの名前空間に配置している場合、メソッドはほとんどの用途で モジュールレベル関数と等価であるため、この環境を使って記述します。

説明には、必要なパラメタと、パラメタがどう処理されるか (とりわけ、 パラメタとして渡した変更可能なオブジェクトが変更されるか否か) 、副作用、 送出される可能性のある例外についての情報を含めねばなりません。 小規模の例題を与えてもかまいません。

\begin{funcdescni}
    {name}{parameters}
\end{funcdescni}

\funcdesc に似ていますが、索引エントリを作成しません。

\begin{classdesc}
    {name}{constructor parameters}
\end{classdesc}
クラスとそのコンストラクタを説明するための環境です。 constructor parameters には、self やコンストラクタ呼び出し 構文で使う丸括弧を含めてはなりません。

\begin{classdesc*}
    {name}
\end{classdesc*}
コンストラクタの説明を伴わないクラスを説明するための環境です。 属性をコンテナ化することがほとんどなかったり、ユーザコードから インスタンス化やサブクラス化を行わないようなクラスを記述する際に 利用できます。

\begin{memberdesc}
    [type name]{name}
\end{memberdesc}
オブジェクトのデータ属性を説明するための環境です。 説明には、想定されているデータ型や、データが直接変更可能かについての 情報がなければなりません。
\begin{memberdescni}
    [type name]{name}
\end{memberdescni}

\memberdesc に似ていますが、索引エントリを作成しません。

\begin{methoddesc}
    [type name]{name}{parameters}
\end{methoddesc}

オブジェクトメソッドを説明するための環境です。 parameters には、self パラメタや呼び出し構文で使う 丸括弧を含めてはなりません。説明には、\funcdesc 内で説明するのと 同じような情報が入っていなければなりません。

\begin{methoddescni}
    [type name]{name}{parameters}
\end{methoddescni}

\methoddesc に似ていますが、索引エントリを作成しません。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 6.2 メタ情報マークアップ Up: 6 特殊マークアップ構文 Next: 6.4 コードの例示


6.4 コードの例示

Python ソースコードや対話セッションの例は \verbatim 環境で 表現します。この環境は LATEX の標準です。TEX はタブをスペースに 変換せずに捨てるので、 コード例中でのインデントにはスペースだけを使用することが重要です。

対話セッションの表現には、プロンプトや Python コード由来の出力 を含める必要があります。対話セッションには特殊なマークアップを 行う必要はありません。最後の入力行または出力行を示した後に、 ``未使用の'' 一次プロンプトを置いてはなりません; 以下に やってはいけない 例を示します:

>>> 1 + 1
2
>>>

\verbatim 環境の中では、LATEX の特殊文字を何がしかの特殊な 方法でマークする必要はありません。例題は全体が等幅フォントで 表示されます; この環境は Python コードの表示でなくても、コードの 表示でさえなくても使えなければならないため、``整形印刷'' は一切 行おうとしません。\verbatim で表示する際には、先頭や末尾に 空行を入れてはなりません。

長い\verbatim テキストを表示する場合には、平文テキストだけの 入った例題のテキストを外部ファイルに入れて取り込めます。 ファイルは標準マクロ \verbatiminput で取り込めます; このマクロは単一の引数名として、例題テキストの入ったファイル名を とります。例えば、 example.py の入った Python ソースファイルを 取り込むには、以下のようにします:

\verbatiminput{example.py}

\verbatiminput を使うと、取り込むファイルに対して特殊な 編集モードを使いやすくできます。ファイルはドキュメントの LATEX ファイルと同じディレクトリに置かねばなりません。

Python Documentation Special Interest Group では、 コード表示や対話セッションに対して整形印刷を行うための数々の アプローチについて議論してきました; この話題に関する詳細は、 Python Web サイトの Doc-SIG エリアを参照してください。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 6.3 情報単位 Up: 6 特殊マークアップ構文 Next: 6.5 インラインマークアップ


6.5 インラインマークアップ

この節で説明するマクロは、単にドキュメントテキスト中の興味深い内容を マークするために使われます。これらのマクロは、本文だけではなく、 表題に利用してもかまいません (とはいえ、ハイパーリンクを含むものは 除かねばなりません)。

\bfcode {text}

\code に似ていますが、ボールド書体にします。

\cdata {name}

C言語における変数の名前です。

\cfunction {name}

C言語における関数の名前です。name には関数名とその後ろの丸括弧 を含めねばなりません。

\character {char}

1 バイトの文字列値ではなく、単一の文字について議論する場合の文字です。 文字は \samp と同じようにタイプセットされます。

\citetitle [url]{title}

参照している出版物のタイトルです。url を指定すると、 タイトル部分は HTML 形式に書式化した際にハイパーリンクになります。

\class {name}

クラス名です; ドット名表記を使用できます。

\code {text}

短いコード断片や定数リテラル。引用符で囲わないので、スペースを 入れてはなりません。

\constant {name}

``定義済みの'' 定数名です。C 言語における #define や、 変更されないことになっている Python の変数の場合があります。

\csimplemacro {name}

``単純'' マクロの名前です。単純マクロは、引数を取らないため 関数で記述できないようなコードの展開に使われます。 この環境は単純な定数定義には用いません。 Python ドキュメント内でのこのマクロの用例としては、 PyObject_HEAD やPy_BEGIN_ALLOW_THREADS が あります。

\ctype {name}
C の typedef や構造体の名前です。 型がtypedef を伴わずに定義されている構造体の場合は、 \ctype{struct struct_tag} を使って、struct が必須であることを明示してください。

\deprecated {version}{what to do}

記述対象がリリース version 以降で撤廃されていることを宣言します。 what to do に指定したテキストでは、撤廃されたものの代わりに 利用すべきものを推奨せねばなりません。テキストは完全な文にせねば なりません。文章全体に対して撤廃を注釈する場合、別個の段落にして 表示せねばなりません; この場合、撤廃される機能の説明の前か後ろの どちらかに置きます。

\dfn {term}
テキストにおけるterm のインスタンスの定義をマークします。 (索引エントリを生成しません。)

\e
バックスラッシュを生成します。\code や類似のマクロを記述 する場合に便利で、そうした場合でだけ使えます。 (\file マクロの中身のような) 通常の文章でバックスラッシュを 生成する場合には標準の \textbackslash マクロを 使ってください。

\email {address}
電子メールアドレスです。出力形式が何であれ、ハイパーリンクは 行われない ので注意してください。アドレスのドメインネーム部分は 小文字でなければなりません。

\emph {text}
強調テキストです。イタリックフォントで表示されます。

\envvar {name}
環境変数です。索引エントリを生成します。

\exception {name}
例外の名前です。ドット名表記を使えます。

\file {file or dir}
ファイルやディレクトリの名前です。PDF と PostScript 形式の出力では ファイル名を表現するのに単引用符で囲ってフォントを変更しますが、 HTML 出力では引用符囲いを行いません。 警告: 処理上の制約により、\file マクロはセクションタイトル内の 内容には使えません。

\filenq {file or dir}
\file に似ていますが、単引用符を使いません。テーブルと組み合わせる 際に、カラムにファイルやディレクトリ名だけが入るような場合に使えます。 警告: 処理上の制約により、\filenq マクロはセクションタイトル内の 内容には使えません。

\function {name}
Python 関数の名前です; ドット名表記を使えます。

\infinity
数学的な無限大を表すシンボル: ∞です。このシンボルの HTML 表現を適切に描画できないブラウザもありますが、サポートは 拡大しています。

\kbd {key sequence}
キーシーケンスをマークします。key sequence がどんな形式になるかは プラットフォームやアプリケーション固有の取り決めに依存します。 適当な取り決めがない場合には、初心者や別のシステムを利用している 人たちが分かりやすいように、モディファイアキー名を書き下さねば なりません。例えば、xemacs のキーシーケンスは \kbd{C-x C-f} のようにマークできますが、特定のアプリケーション やプラットフォームに対する参照を行わない場合には、 \kbd{Control-x Control-f} とマークせねばなりません。

\keyword {name}
プログラミング言語における予約語 (keyword) の名前です。

\mailheader {name}
RFC 822 形式のメイルヘッダ名です。このマークアップは、そのヘッダが 電子メイルメッセージ中で使われていることを示すのではなく、 同じ ``スタイル'' のヘッダを表すのに使える名前であることを示します。 様々な MIME 仕様が定義しているヘッダに対しても使います。 ヘッダ名の表現方法は、実際に通常使われているのと同じ方法で入力しなくては なりません。また、複数の用法があり、いずれも広く使われている場合には、 キャメル形式 (camel-casting) を優先します。ヘッダ名の後ろに続くコロンは 含めてはなりません。 例: \mailheader{Content-Type}。

\makevar {name}
make における変数名です。

\manpage {name}{section}
Unix マニュアルページへの参照です。

\member {name}
オブジェクトのデータ属性名です。

\method {name}
オブジェクトのメソッド名です。name にはメソッド名とその後ろに続く 丸括弧を入れねばなりません。ドット名表記を使えます。

\mimetype {name}
MIME タイプの名前か、 MIME タイプの要素 (メジャータイプはマイナータイプのいずれか) の名前です。

\module {name}
モジュールの名前です: ドット名表記を使えます。 パッケージ名にもこれを使います。

\newsgroup {name}
Usenet のニュースグループ名です。

\note {text}
ある API について、ユーザがその API を一部でも利用する場合には知って おかねばならないような特に重要な情報です。このマクロは注釈が終了する 場所を視覚的にマークしないので、段落の末尾の内容にせねばなりません。 text の内容は完全な文で書き、適切な区切りを入れねばなりません。

\pep {number}
Python Enhancement Proposal への参照です。このマクロは索引エントリを 生成します。 "PEP number" という出力を生成します; HTML 出力の場合、テキストは指定された PEP のオンラインコピーに対する ハイパーリンクになります。

\plusminus
ある値が、指定した量に対して正負の値をとることを示すシンボルで、 通常はマイナス記号の上にプラス記号を置いて表します。例: \plusminus 3%

\program {name}
実行可能形式のプログラム名です。プラットフォームによっては、 実行可能形式のファイル名とは異なる場合があります。特に、 Windows プログラムでは .exe (やその他の) 拡張子を 省略します。

\programopt {option}
実行可能プログラムのコマンドラインオプションです。 ``短い'' オプションだけに使い、先頭にハイフンを入れてください。

\longprogramopt {option}
実行可能プログラムの長いコマンドラインオプションです。 このマクロは二つのハイフンから始まる長いオプション名だけに使います; ハイフンを option に入れてはなりません。

\refmodule [key]{name}
\module に似ていますが、指定したモジュールに対する ハイパーリンクを生成します。このマクロに対応する\declaremodule は同じドキュメント内に入っていなければなりません。 \declaremodule がモジュール名とは異なるモジュールキーを 定義している場合、\refmodule マクロ内でも key として 指定せねばなりません。

\regexp {string}
正規表現をマークします。

\rfc {number}
Internet Request for Commments への参照です。適切な索引エントリを 生成します。テキスト "RFC number" を生成します; HTML 出力 では、テキストは指定した RFC のオンラインコピーに対するハイパーリンクに なります。

\samp {text}
短いコード例で、\code で指定するには長すぎる場合に使います。 引用符記号を追加するので、テキストにスペースを入れてもかまいません。

\shortversion
プリアンブルの\setshortversion マクロに指定されているような、 ドキュメントの対象となっているソフトウェアの ``短い'' バージョン番号です。 Python の場合、あるリリースに対する短いバージョン番号とは。 sys.version 値の最初の三文字です。例えば、バージョン 2.0b1 と 2.0.1 の短いバージョン番号はいずれも 2.0 になります。 全てのパッケージにこれが当てはまるわけではありません; \setshortversion を使わなければ、このマクロは 空文字に展開されます。\version マクロも参照してください。

\strong {text}
強く強調されたテキストです; ボールドフォントで表現されます。

\ulink {text}{url}
URL で指定したターゲットを指すハイパーテキストリンクになりますが、 リンクテキストをドキュメントリソース中のタイトルにしてはなりません。 名前を使ってリソースを参照する場合には、\citetitle マクロを 使ってください。 全ての形式の出力が任意のハイパーテキストリンクをサポートしている わけではありません。LATEX 特有の多くの文字や、このマクロ特有の 文字を使った場合、たいてい正しい出力になりません。特に、 チルダ文字 ("~") は誤って処理されます; hex 形式の配列 にエンコードすればうまくいくので、チルダの代わりには"%7e" を 使ってください。

\url {url}
URL (または URN) です。 URL はテキストで与えます。 HTML や PDF の出力形式では、URL 文字列自体もハイパーリンクになります。 このマクロは、特定のタイトルを持たない外部リソースを参照する際に 利用できます; タイトルのあるリソースへの参照は \citetitle マクロを使ってマークしてください。特殊文字に関する特別な扱いについては、 \ulink マクロの記述中のコメントを参照してください。

\var {name}
テキスト中で変数や仮引数の名前です。

\version
プリアンブルの\release マクロに指定されているような、 ドキュメントの対象となっているソフトウェアのバージョン番号です。 \shortversion マクロも参照してください。

\versionadded [explanation]{version}
記述対象の機能が C API のライブラリに追加された時点の Python の バージョン番号です。explanation は変更内容の短い 説明で、 大文字から始まる文章断片からなります; 末尾のピリオドは書式化の 処理時に追加されます。このマクロは普通、機能を説明する文の第一パラグラフ の末尾で、かつ利用可能条件に関する注釈よりも前に追加します。 マクロを追加する場所は説明文の意味が通るように選ばねばならず、 必要に応じて場所を変えてもかまいません。

\versionchanged [explanation]{version}
記述対象の機能が変化 (新たなパラメタ、副作用の変化、など) した時点の Python のバージョンです。explanation は変更内容の短い 説明で、 大文字から始まる文章断片からなります; 末尾のピリオドは書式化の 処理時に追加されます。このマクロは普通、機能を説明する文の第一パラグラフ の末尾で、かつ利用可能条件に関する注釈と\versionadded マクロよりも 前に追加します。マクロを追加する場所は説明文の意味が通るように選ばねば ならず、必要に応じて場所を変えてもかまいません。

\warning {text}
ある API について、ユーザがその API を一部でも利用する場合には警告して おかねばならないような重要な情報です。このマクロは注釈が終了する 場所を視覚的にマークしないので、段落の末尾の内容にせねばなりません。 text の内容は完全な文で書き、適切な区切りを入れねばなりません。 \note との違いは、セキュリティに関する情報の場合いは、 \warning の方が推奨されているという点です。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 6.4 コードの例示 Up: 6 特殊マークアップ構文 Next: 6.6 雑多なテキストマークアップ


6.6 雑多なテキストマークアップ

インラインマークアップに加えて、 ``ブロック'' マークアップがいくつか 定義されていて、様々なテキスト断片に対して読者の注意を引かせやすく しています。 この節で述べているマークアップは、こうした目的の他に、 (\verbatim 環境のように) 一つ以上の段落や、他のブロック構造を マークする際に使うためのものです。

\begin{notice}
    [type]
\end{notice}
読者がさらに注意を払うべき段落をラベルします。どの種の注意を求めて いるかは、type に指定します。type 用に定義されている値は note とwarning です; これらは、同名のインラインマークアップ と同じ目的に使います。types を省略すると、note を使います。 type が撮りうる値は将来新たに追加されるかもしれません。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 6.5 インラインマークアップ Up: 6 特殊マークアップ構文 Next: 6.7 モジュール特有のマークアップ


6.7 モジュール特有のマークアップ

この節で説明しているマークアップは、記述対象のモジュールに関する 情報を提供するために使います。このマークアップは、モジュールを説明 している節の先頭でよく使います。典型的な例は、以下のようになります:

\section{\module{spam} ---
         SPAM 機能へのアクセス}

\declaremodule{extension}{spam}
  \platform{Unix}
\modulesynopsis{\UNIX の SPAM 機能へのアクセス手段。}
\moduleauthor{Jane Doe}{jane.doe@frobnitz.org}

Python のパッケージ-- ひとまとまりの単位として 記述できるようなモジュールの集合 -- は、モジュールと同じ マークアップを使って解説します。パッケージ内のモジュール名は ``完全限定 (fully qualified)'' 形式で入力せねばなりません (つまり、パッケージ名を含めねばなりません)。 例えば、 ``bar'' というパッケージ内の ``foo'' というモジュールは \module{bar.foo} と書き、リファレンスの先頭は以下のように なります:

\section{\module{bar.foo} ---
         \module{bar} パッケージ内のモジュール}

\declaremodule{extension}{bar.foo}
\modulesynopsis{\module{bar} パッケージ内の小さなモジュール}
\moduleauthor{Jane Doe}{jane.doe@frobnitz.org}

パッケージの名前もまた、\module でマークします。

\declaremodule [key]{type}{name}
二つのパラメタ: モジュールの種類 ("standard"、"builtin"、 "extension"、または"") と、モジュールの名前を必要とします。 この節にリンクを張ったり参照を行ったりするための ``キー'' によっては、 オプションのパラメタを指定せねばなりません。 ``キー'' は、モジュールの名前にアンダースコアが入っている場合にのみ 用い、モジュール名からアンダースコアを取り除いた名前でなければなりません。 type パラメタは上に述べた値のいずれかでなければならず、そうでない 値を指定するとエラーが出力されるので注意してください。 パッケージに入っているようなモジュールの場合、name パラメタには 完全限定形式の名前を指定せねばなりません。 このマクロはモジュールを紹介する\section の先頭に置かねば なりません。

\platform {specifier}
モジュールの可搬性について述べるために使います。specifier は モジュールを利用できるようなプラットフォームを指定するキーをコンマで 区切ったリストです。キーは短い識別子にします; 実際に使われている例には "IRIX"、"Mac"、"Windows"、"Unix" があります。 あるプラットフォームを表す場合、すでに使われているキーがあるなら、 それを使うようにするのが重要です。この情報は、モジュール索引や、 HTML形式、GNU info 形式の出力における注釈情報に使われます。

\modulesynopsis {text}
text はモジュールの短い ``一行の'' 説明で、各章の紹介の一部 として使われることがあります。このマクロは \declaremodule の後ろに配置せねばなりません。モジュールの概要は、 \localmoduletable マクロによって挿入される一覧表の 内容を構築する際に使われます。マークアップを行った場所では 何のテキストも生成されません。

\moduleauthor {name}{email}
このマクロはモジュールの作者についての情報を符号化するために使われます。 現在は出力生成に使われていませんが、モジュールの起源を判断する際に 役立つはずです。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 6.6 雑多なテキストマークアップ Up: 6 特殊マークアップ構文 Next: 6.8 ライブラリレベルのマークアップ


6.8 ライブラリレベルのマークアップ

このマークアップは、一そろいのモジュールについて説明する際に使います。 例えば、 Macintosh ライブラリモジュール ドキュメントでは、モジュールの集まりを概観できるようにするために このマクロを役立てています。また、 Python ライブラリリファレンス も同様の 目的にこのマクロを利用しています。

\localmoduletable
現在の章 (howto ドキュメントの場合はドキュメント全体) に対して .syn ファイルが存在する場合には、.syn ファイルから 読み出した内容で\synopsistable を作成します。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 6.7 モジュール特有のマークアップ Up: 6 特殊マークアップ構文 Next: 6.9 表のマークアップ


6.9 表のマークアップ

表環境には汎用の三つの形式があり、できる限りこの環境を使うように してください。こうした環境は標準の LATEX 表環境を置き換える ためのものではなく、Python ドキュメントを作成するための処理ツール で処理する際に便利なように作られています。とりわけ、この表環境で 生成した HTML は見栄えがよくなります! また、いつかドキュメントを XML 形式に変換する時にも (8 節、 ``将来の方向性'' を 参照してください)、利点があるでしょう。

各環境は \tablecols という形式の名前がついています。 cols には、表のカラム数を小文字のローマ数字で指定します。 各々の環境について、追加のマクロ\linecols が定義されて います。この場合cols は表環境のcolsに対応します。 サポートされているcols にはii、iii、iv、 v があります。どの環境も全て\tabular 環境の上に構築されて います。\longtable 環境に基づく変化形も提供されています。

標準 Python ドキュメント内の全ての表がカラム間に垂直線を 使っており、各表のマークアップでこの垂直線を指定しなければならないので 注意してください。表の外側の境界線はマークアップに使いませんが、 これは処理ツール側の役割です; ドキュメントのマークアップ時には 外側の境界線を含めてはなりません。

\longtable に基づいた表環境の変化形では、前後に余分にスペースを 入れて書式化を行うため、表が長すぎて、複数のページに分割したほうが 合理的な場合にのみ使ってください; 20 行よりも行数の少ない表の場合、 決して長形式の表環境を使ってマークをしないようにしてください。 ヘッダ行は、表の各ページにおける部分の先頭に繰り返し表示されます。

\begin{tableii}
    {colspec}{col1font}{heading1}{heading2}
\end{tableii}
LATEX のカラム情報指定子 (column specifier) colspec を使って、 2 カラムの表を作成します。カラム情報指定子には表によって適切なカラム 分割垂直線が入るように指定を行わねばなりませんが、表の外側の垂直線は 指定してはなりません (この部分の指定はスタイルシートの問題と考えられて いるからです)。con1font パラメタは、テーブルの最初のカラムの 表示スタイルをどうするかを指定します: その結果として、最初のカラムは \col1font{column1} のようになります。 最初のカラムを特別扱いしないために、col1font を"textrm" に してもかまいません。カラムのヘッダは heading1 および heading2 からとります。

\begin{longtableii} ...
\end{longtableii}
\tableii に似ていますが、ページ境界を割って配置できるような 表を生成します。パラメタは\tableii と同じです。

\lineii {column1}{column2}
\tableii や\longtableii 環境内の単一の行を生成します。 第一カラムのテキストは\tableii 環境を始めたときに指定した col1font を適用して生成します。

\begin{tableiii}
    {colspec}{col1font}{heading1}{heading2}{heading3}
\end{tableiii}
\tableii 環境に似ていますが、第三カラムがあります。 第三カラムのヘッダは heading3 に指定します。

\begin{longtableiii} ...
\end{longtableiii}
\tableiii に似ていますが、ページ境界を割って配置できるような 表を生成します。パラメタは\tableiii と同じです。

\lineiii {column1}{column2}{column3}
\lineii マクロに似ていますが、第三カラムがあります。 第三カラムのテキストは column3 に指定します。

\begin{tableiv}
    {colspec}{col1font}{heading1}{heading2}{heading3}{heading4}
\end{tableiv}
\tableiii 環境に似ていますが、第四カラムがあります。 第四カラムのヘッダは heading4 に指定します。

\begin{longtableiv} ...
\end{longtableiv}
\tableiv に似ていますが、ページ境界を割って配置できるような 表を生成します。パラメタは\tableiv と同じです。

\lineiv {column1}{column2}{column3}{column4}
\lineiv マクロに似ていますが、第四カラムがあります。 第四カラムのテキストは column4 に指定します。

\begin{tablev}
    {colspec}{col1font}{heading1}{heading2}{heading3}{heading4}{heading5}
\end{tablev}
\tableiii 環境に似ていますが、第五カラムがあります。 第五カラムのヘッダは heading5 に指定します。

\begin{longtablev} ...
\end{longtablev}
\tablev に似ていますが、ページ境界を割って配置できるような 表を生成します。パラメタは\tablev と同じです。

\linev {column1}{column2}{column3}{column4}{column5}
\lineiv マクロに似ていますが、第五カラムがあります。 第五カラムのテキストは column5 に指定します。

表に似たもう一つ環境として \synopsistable があります。 この環境が生成する表は二つのカラムからなり、各行は別のマクロ定義 \modulesynopsis 中に定義されています。通常ドキュメントの作者が この環境を使うことはありませんが、\localmoduletable マクロ を使うとこの表を作成します。

ここでwarning モジュールのドキュメントにある小さな表の例を 示します; 表のマークアップ自体がかなり識別しやすく作られているので、 表セル内のマークアップは最小限にしています。 以下が表のマークアップです。

\begin{tableii}{l|l}{exception}{クラス}{説明}
\lineii{Warning}{全ての警告カテゴリの基底クラスです。
\exception{Exception} のサブクラスです。}
\lineii{UserWarning}{\function{warn()} の標準のカテゴリです。}
\lineii{DeprecationWarning}{機能の撤廃を警告するカテゴリの基底クラスです。}
\lineii{SyntaxWarning}{文法機能のあいまいさを警告するカテゴリの基底クラスです。}
\lineii{RuntimeWarning}{実行時システム機能のあいまいさを警告するカテゴリの基底クラスです。}
\lineii{FutureWarning}{変更予定のセマンティクスを警告するカテゴリの基底クラスです。}
\end{tableii}

これは以下のような表になります。

クラス | 説明
Warning | 全ての警告カテゴリの基底クラスです。 Exception のサブクラスです。
UserWarning | warn() の標準のカテゴリです。
DeprecationWarning | 機能の撤廃を警告するカテゴリの基底クラスです。
SyntaxWarning | 文法機能のあいまいさを警告するカテゴリの基底クラスです。
RuntimeWarning | 実行時システム機能のあいまいさを警告するカテゴリの基底クラスです。
FutureWarning | 変更予定のセマンティクスを警告するカテゴリの基底クラスです。

クラス名は\exception マクロを使って非明示的にマークされますが、 これは\exception が\tableii 環境のcol1font の 値として指定されているからです。最初のカラムを別のマークアップにした 表を作成するには、textrm を col1font の値に指定して、 各エントリを個別にマークしてください。

表を垂直方向に分割するために水平線を追加するには、標準のマクロ \hline を分割したい行の間に入れます:

\begin{tableii}{l|l}{constant}{言語}{対象読者}
  \lineii{APL}{マゾヒスト}
  \lineii{BASIC}{PC ハードウェア使いのプログラム初心者}
  \lineii{C}{\UNIX{} \&\ Linux カーネル開発者}
    \hline
  \lineii{Python}{誰でも!}
\end{tableii}

全ての出力形式でこの場所に水平線を引けるとは限らないので注意してください。 今読者が読んでいるドキュメントの出力形式では、上の表は以下のように なります:

Language | Audience
APL | Macintosh 野郎
BASIC | PC ハードウェア使いのプログラム初心者
C | Unix & Linux カーネル開発者
Python | 誰でも!

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 6.8 ライブラリレベルのマークアップ Up: 6 特殊マークアップ構文 Next: 6.10 参考文献リストのマークアップ


6.10 参考文献リストのマークアップ

ドキュメントの各節の多くには、モジュールドキュメントや外部ドキュメント を指す参考文献のリストが入っています。こうしたリストは、\seealso や\seealso* 環境を使って作成します。 これらの環境では、参考文献エントリを合理的なやり方で作成するための 追加のマクロを定義しています。

\seealso 環境は通常、節中で何らかの小節に入る直前の場所に配置 します。これは、ある節に関係した参考文献リンクが、 ドキュメントのハイパーテキスト解析を行う際に小節内に入り込んで しまわないようにするためです。 HTML 出力の場合、このマクロの内容は本文の外側の ``サイドバー'' に 表示されます。\seealso* 環境は、参考文献リストを主コンテンツ の一部として表示したい場合に使う点が異なります; \seealso* を 使うと、リストを特別扱いしてテキスト内から押し出したりしません。

\begin{seealso}
\end{seealso}
この環境はヘッダ ``See also:'' を作成し、個々の参考文献を記述 するためのマークアップを定義します。

\begin{seealso*}
\end{seealso*}
この環境は主コンテンツの一部として参考文献リストを生成する際に使います。 リストに特別にヘッダをつけることはなく、ドキュメントの本文から 押し出されることもありません。個々の参考文献を記述するために、 上と同じマークアップを提供しています。

以下のマクロの各々において、why は一つかそれ以上の完全な 文章で、大文字から始めねばなりません (文が識別子から始まる場合には 別で、大文字にする必要はありません)。また、適切な区切り文字で 終えねばなりません。

これらのマクロは \seealso や \seealso* 環境の中でしか 定義できません。

\seemodule [key]{name}{why}
別のモジュールへの参照です。why は、なぜその参考文献が 興味の対象となるのかを示す短い説明にせねばなりません。 モジュール名は name で指定し、必要があれば key でリンクキーを指定します。HTML および PDF 版では、 モジュール名部分は参照先のモジュールを指すハイパーリンクになります。 注意: 該当のモジュールは同じドキュメント内で記述されていなければ なりません (対応する\declaremodule が必要です)。

\seepep {number}{title}{why}
Python Enhancement Proposal (PEP) への参照です。number は PEP 編集者が割り当てた公式 PEP 番号でなければならず、 tiutle は PEP ドキュメントの公式版に書かれている人間可読な タイトルでなければなりません。 このマクロは、ドキュメント中の注釈がつけられている節の内容が関係 しているインタフェースや言語機能 PEP への参照を読者に示すために 使います。

\seerfc {number}{title}{why}
IETF による Request for Comment (RFC) を参照します。 それ以外の点では、 \seepep とほとんど同じです。 このマクロは、ドキュメント中の注釈がつけられている節の内容が関係 しているプロトコルやデータ形式を仕様記述している RFC への参照を 読者に示すために使います。

\seetext {text}
任意のテキストtext を ``See also:'' リストに追加します。 このマクロはオフラインやオンラインの資料を \url マクロで 参照するために使えます。テキストは一つかそれ以上の完全な文で 構成しなければなりません。

\seetitle [url]{title}{why}
title という名前の外部ドキュメントに対する参照を追加します。 url を指定した場合、HTML 版では外部ドキュメントのタイトル部分が ハイパーリンクになり、組版版のドキュメントでは表題の下に URL が 表示されます。

\seeurl {url}{why}
特定のオンラインリソースで、意味のあるタイトルがない場合には \seeurl マクロを使って参照を行います。 はっきりしたタイトルのあるオンラインドキュメントの場合には、 \seetitle マクロを使い、そのオプションパラメタに URL を指定 して参照を行ってください。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 6.9 表のマークアップ Up: 6 特殊マークアップ構文 Next: 6.11 索引生成のためのマークアップ


6.11 索引生成のためのマークアップ

技術文書における索引の効果的な作成は、とりわけ作者がある事柄には詳しくても 索引の生成には不慣れな場合には非常に困難です。ドキュメントの困難さの ほとんどは技術用語の範囲からきています: ある概念を説明する際に、 熟練者が使うような用語を入れるだけでは不十分です。ドキュメントの 作者は普通、自分の書いているドキュメントの領域においては熟練者であり、 初心者が立ち止まってしまうような用語を見つけ出すのはかなり難しいのです。

索引生成の本当に困難な側面は、ドキュメント作成ツールで補助できるような 領域のことがらではありません。とはいえ、ひとたび用語の内容を決めたら、 索引の作成を簡単にするのはツールの役割です。 様々な種類の索引を最小限の努力で生成できるようにするために ドキュメント生成ソフトウェアが利用できるようなマークアップが提供 されています。加えて、6.3 節、 ``情報単位'' で説明した 多くの環境は、総合索引やモジュール索引上に適切なエントリを作成します。

以下のマクロは、索引情報を生成するために利用できます。これらはドキュメント のプリアンブル内で使わねばなりません。

\makemodindex
ドキュメントで多くのモジュールに対する参照が入った ``モジュール索引'' が必要な場合、プリアンブル内で使います。 このマクロは一連の\declaremodule マクロからデータファイル libjobname.idx を生成します。このファイルは makeindex プログラムで使われ、モジュール索引を入れたい場所に \input を使って取り込めるようなファイルを生成します。

様々な概念について索引エントリを追加する上で便利なマクロがあります。 これらの多くはプログラミング言語や、Python に特有の概念です。

\bifuncindex {name}
name という名前の組み込み関数に対する索引エントリを追加します; name の後ろに丸括弧を入れてはなりません。

\exindex {exception}
exception という名前の例外に対する索引エントリを追加します。 例外はクラスベースの例外でなければなりません。

\kwindex {keyword}
言語における予約語 (keyword、関数やメソッド呼び出しにおけるキーワード 引数とは違います) に対する索引エントリを追加します。

\obindex {object type}
組み込みオブジェクト型に対する索引エントリを追加します。

\opindex {operator}
"+" のような演算子に対する索引エントリを追加します。

\refmodindex [key]{module}
モジュール module に対する索引エントリを追加します; module にアンダースコアが入っている場合、オプションのパラメタ key には、module からアンダースコアを除去した名前を 指定せねばなりません。索引エントリ ``module (module)'' を生成 します。Python で書かれた非標準モジュールで使うためのものです。

\refexmodindex [key]{module}
\refmodindex のようなものですが、索引エントリは ``module (extension module)'' になります。 このマクロは Python 以外で書かれた非標準モジュールで使うためのものです。

\refbimodindex [key]{module}
\refmodindex のようなものですが、索引エントリは ``module (built-in module)'' になります。 このマクロは Python 以外で書かれた標準モジュールで使うためのものです。

\refstmodindex [key]{module}
\refmodindex のようなものですが、索引エントリは ``module (standard module)'' になります。 このマクロは Python で書かれた標準モジュールで使うためのものです。

\stindex {statement}
print やtry/finally のような、 構文型に対する索引エントリを追加します。

総合索引を簡単に作成する上で便利なマクロが提供されています。 索引エントリは、索引の様々な場所で語順を入れ替えて表示しなければ なりません。これらのマクロは単に \index を使って複数の 索引エントリを作成するような単純なマクロです。こうしたマクロを 使って構築された索引エントリには、一次および二次の索引テキストが 入ります。

\indexii {word1}{word2}
二つの索引語からなる索引エントリを構築します。 \index{word1!word2} と \index{word2!word1} を組み合わせて使うのと 同じです。

\indexiii {word1}{word2}{word3}
三つの索引語からなる索引エントリを構築します。 \index{word1!word2 word3}、 \index{word2!word3, word1}、および \index{word3!word1 word2} を 組み合わせて使うのと同じです。

\indexiv {word1}{word2}{word3}{word4}
四つの索引語からなる索引エントリを構築します。 \index{word1!word2 word3 word4}、 \index{word2!word3 word4, word1}、 \index{word3!word4, word1 word2}、 および \index{word4!word1 word2 word3} を 組み合わせて使うのと同じです。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 6.10 参考文献リストのマークアップ Up: 6 特殊マークアップ構文 Next: 6.12 文法における導出の表示


6.12 文法における導出の表示

形式文法における導出 (producution) を表示するために、特殊なマークアップ を使えます。マークアップは単純なもので、 BNF (やその派生形) の 全ての側面をモデル化しようとはしていませんが、 シンボルを記述するとそのシンボルの定義へのハイパーリンクになるような 表示を文脈自由文法に対して実現しています。 環境が一つと、二つのマクロがあります:

\begin{productionlist}
    [language]
\end{productionlist}
この環境は、ひとまとまりの導出規則を囲むために使います。 この環境ではマクロを二つだけ定義しています。ドキュメントで 二つ以上の言語について説明する場合、オプションのパラメタ language を使って、言語間で導出規則を区別せねばなりません。パラメタの値は ファイル名の一部に使えるような短い名前にせねばなりません; コロンや、 複数のプラットフォーム間で同時にファイル名に使えないような文字は 含めてはなりません。

\production {name}{definition}
文法における導出規則です。導出規則は、name をdefinition であると定義します。name にはマークアップを入れてはならず、 ハイフンを使った一つ以上の文法のサポートは定義されていません。 一つの \production には単一のシンボルだけを定義できます -- 複数シンボルの定義を行ってはなりません。

\token {name}
\production マクロが定義しているシンボルの名前で、 シンボルのdefinition の中で使います。シンボルname は 可能な場合にはシンボル定義へのハイパーリンクになります。

必ずしも文法全体を単一の\productionlist 環境に定義する必要は ないので注意してください; 任意の数のグループを作って文法を 記述してかまいません。\token を使う場合には常に \production と対応付けせねばなりません。

以下はPython リファレンスマニュアル からとった例です:

\begin{productionlist}
  \production{identifier}
             {(\token{letter}|"_") (\token{letter} | \token{digit} | "_")*}
  \production{letter}
             {\token{lowercase} | \token{uppercase}}
  \production{lowercase}
             {"a"..."z"}
  \production{uppercase}
             {"A"..."Z"}
  \production{digit}
             {"0"..."9"}
\end{productionlist}

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 6.11 索引生成のためのマークアップ Up: 6 特殊マークアップ構文 Next: 6.13 グラフィカルインタフェースの構成要素


6.13 グラフィカルインタフェースの構成要素

グラフィカルインタフェースの構成要素についてマークアップを割り当てる ことになっていますが、その詳細はまだほとんど決まっていません。

\menuselection {menupath}
メニューの選択肢は \menuselection と \sub を組み合わせて マークします。このマクロは、サブメニューを選択して特定の操作を選択する といった完全な形のメニュー選択手順や、任意の部分的な手順をマークする ために使います。個々の選択肢の名前は \sub を入れて分割せねば なりません。

例えば、``スタート > プログラム'' をマークするには、以下 のコードを使います:

\menuselection{スタート \sub プログラム}

選択肢がダイアログを開くようなコマンドであることを示すために オペレーティングシステムが使う省略記号のように、選択肢の末尾に 末尾に識別記号が入っている場合、選択肢名からは識別記号を省いて ください。

\sub
複数の階層からなるメニュー選択肢を分割するための記号です。 このマクロは \menuselection マクロのコンテキスト下でしか 定義されていません。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 6.12 文法における導出の表示 Up: 6 特殊マークアップ構文 Next: 7 処理ツール


7 処理ツール

  • 7.1 外部ツール
  • 7.2 内部用ツール
  • 7.3 Cygwin での作業
Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 6.13 グラフィカルインタフェースの構成要素 Up: Python ドキュメントの作成 Next: 7.1 外部ツール


7.1 外部ツール

Python ドキュメントがサポートしている全ての出力形式を処理できるように するには、数多くのツールが必要です。この節では、処理に使われている 各ツールについて列挙し、各々がいつ必要になるのか説明しています。 これらのツールのいずれかが特定のバージョンを要求しているかどうかは、 Doc/README ファイルを調べてみてください。

dvips
このプログラムはよく TEX インストールの一部になっています。 dvips は ``デバイス非依存 (dvice independent)'' の .dvi ファイルから PostScript を生成するために使われます。 PostScript への変換を行う際に必要です。

emacs
Emacs はごちゃまぜ (kitchen sink) の、さらに言うとクソ素晴らしい ごちゃまぜのプログラマ向けエディタです。info 形式に変換したい場合に、 Texinfo ドキュメントの適切なメニュー階層の構築をサポートする上で必要な 処理に関係しています。FSF の emacs の代わりに xemacs を使うと、変換がうまくいかないことがありますが、これは誰も Emacs の Texinfo コードをメンテナンスして可搬性のあるものにしないからだと 思われます。

latex
LATEX は、Laslie Lamport による拡張可能な大規模マクロパッケージ で、Donald Knuth が作成した世界規模で使われているタイプセッタTEXに基づいています。PostScript 形式への変換に必要で、 HTML への変換にも 必要です (LATEX2HTML はLATEX が生成する中間ファイルの一つを 必要とするためです)。

latex2html
これまでにメンテナンスされたことのある Perl スクリプトの中で おそらく最長のスクリプトでしょう。このツールは LATEX ドキュメントを HTML ドキュメントに変換し、そこそこ立派な仕事をします。 HTML や GNU info 形式への変換に必要です。

lynx
HTML から平文テキストへの変換機能を持つテキストモードの Web ブラウザです。 howto ドキュメントをテキスト形式に変換する際に使います。

make
どのバージョンの make も標準ドキュメントの処理に使えるはず ですが、 実験段階にあるDoc/tools/sgmlconv/ の処理には、 少なくとも実験段階にある間は GNU make が必要です。 mkhowto スクリプトを走らせる場合には必要ありません。

makeindex
LATEX の索引データを書式化済みの索引に変換するための標準プログラムです; 全てのLATEX インストール物に入っているはずです。PDF 形式と PostScript 形式への変換に必要です。

makeinfo
Texinfo から GNU info ファイルへの変換には GNU makeinfo を使います。Texinfo は info への変換における中間形式の処理に使われる ので、info への変換にもこのプログラムが必要です。

pdflatex
pdfTEX は比較的新しく登場した TEXの変種で、マニュアルの PDF 版を 生成するために使います。通常、ほとんどの大規模な TEX 配布物の一部 としてインストールされています。pdflatex は LATEX 形式を 扱う pdfTEX です。

perl
LATEX2HTML やLATEX2HTML 出力に対する仕上げ作業、HTMLからTexinfo への変換には Perl が必要です。 HTML 形式や GNU info 形式への変換に 必要です。

python
Python は Doc/tools/ ディレクトリ内の多くのスクリプトで 使われています; 全ての形式への変換で必要です。 Python のドキュメントを書こうと思っているのなら、何も問題はないはず ですよね!

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 7 処理ツール Up: 7 処理ツール Next: 7.2 内部用ツール


7.2 内部用ツール

この節では、ドキュメント処理の様々な段階を実装したり、ビルド手順全体 を演出する様々なスクリプトについて説明します。これらのツールの ほとんどは標準ドキュメントを構築するというコンテキストでのみ有用 ですが、汎用的なものもあります。

mkhowto
サードパーティ製のドキュメントを書式化する際に最初に使うスクリプトです。 このスクリプトには、 ``正しく作業を行う'' 上で必要なロジックが 全て入っています。このスクリプトを正しく使うには、スクリプトに 対するシンボリックリンクを張って、その場所で実行します; 実際の スクリプトファイルはドキュメントソースツリーの一部として 収められていなければなりませんが、ツリーの外部にあるドキュメントの 書式化にも利用できます。コマンドラインオプションのリストを見るには、 mkhowto --help を使ってください。

mkhowto は howto と manual クラスの どちらのドキュメントにも使えます。このツールは、古い Python の ソースリリースに入っているバージョンではなく、常に最新のバージョンを 使うようにするのがよいでしょう。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 7.1 外部ツール Up: 7 処理ツール Next: 7.3 Cygwin での作業


7.3 Cygwin での作業

多くのパッケージは Cygwin 環境下でのインストールが難しいために、 Cygwin 用に必要なツールの Cygwin 環境下でのインストールは少し厄介です。

Cygwin インストーラを使って、 Cygwin のインストールによって Perl、 Python、そして TEX パッケージが入っていることを確認してください。 Perl と Python はインストーラの Interpreters セクションの下に配置されています。TEX パッケージは Text セクションの下です; tetex-beta、texmkf、texmf-base、 および texmf-extra をインストールすると、必要な全てのパッケージ を利用できるようになります。 (より小規模な構成もありますが、筆者は インストール構成の縮小を試みるために時間を費やしたことがありません。)

LATEX2HTML はnetpbm パッケージを使うので、たとえ Python ドキュメントのほとんどがnetpbm を使わないとしても、 LATEX2HTML をインストールする前にインストール しておかねばなりません。 ダウンロードできる場所に関する参考文献は、 netpbm README にあります。 説明に従ってインストールしてください。

LATEX2HTML はソースアーカイブからのインストールもできますが、 配布物中のあるファイルをいじってからでないとできません。 展開した配布物のトップレベルにある L2hos.pm を編集してください; ファイルの末尾近くにある、$^O というテキストを 'unix' に変更してください。以下のコマンドを使ってソフトウェアを ビルドしてインストールします:

% configure && make install

これで少なくとも HTML、PDF、および PostScript 形式版の書式化済み ドキュメントをビルドできます。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 7.2 内部用ツール Up: 7 処理ツール Next: 8 将来の方向性


8 将来の方向性

Python ドキュメントは変更に次ぐ変更の歴史を重ねてきており、そのほとんどは やや小規模の漸進的なものでした。マークアップ言語やドキュメントの処理に 使われるツールに関して非常に多くの話し合いが行われてきました。 この節では、変更のさまと、将来の開発において最もありえそうな道筋に ついて議論します。

  • 8.1 構造化ドキュメント
  • 8.2 議論の場
Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 7.3 Cygwin での作業 Up: Python ドキュメントの作成 Next: 8.1 構造化ドキュメント


8.1 構造化ドキュメント

LATEX マークアップに対する小規模な変更のほとんどは、 マークアップから表現方法を切り離すためとメンテナンス性の向上の両方を 狙ってなされてきたものです。 1998 年からこのかた、まさにこの目的の もとに数多くの変更が行われました; それ以前は、変更はありましたが あまり体系的なやりかたではなく、既存の内容を更新する必要はない と考えられていました。その結果、高度に構造化され、意味論的には LATEX の上に読み出されることになるような、LATEX で実装された マークアップ言語になってしまいました。とはいえ、基本的なTEX や LATEX によるマークアップが使われていなければ、実際のドキュメントソース でLATEX が使われている証拠となるのはマークアップの構文法くらいです。

この副作用のせいで、例えばLATEX やLATEX2HTML のような、ドキュメント を操作するための標準の ``エンジン'' を使えるにも関わらず、実際の 変換のほとんどは Python に特化して作られてしまいました。 LATEX ドキュメントクラスとLATEX2HTML サポートは、いずれもこの ドキュメントのために設計された特殊なマークアップを完全に実装 しています。

高度にカスタマイズされたマークアップが、ドキュメントを処理するための 深遠なる機構と組み合さってしまうと、こんな疑問が出てきます: もっと簡単にできないの? あるいは、もっとましにならないの? コミュニティとのたくさんの議論を重ねた結果、我々は 近代的な構造化ドキュメント生成システムの追求にも時間を費やす価値が あるという結論に達しました。

この議論の場には、二つの現実的な競合案: 標準化汎用マークアップ言語 (Standard General Markup Language, SGML) と拡張可能なマークアップ 言語 (Extensible Markup Language, XML) が挙がっています。 これらの標準には、いずれも長所と短所があり、多くの長所を共有しています。

SGML はほとんどのドキュメント作者、とりわけ普通のテキストエディタ を利用している人たちをそそらせるような長所を持っています。 また、コンテンツのモデルを定義できるという別の機能もあります。 完成度が実証されている多くの高品質なツールを利用できますが、 そのほとんどはフリーではありません; またこれらのツールでは、 可搬性がいまだに問題になっています。

XML には、多数の発展中のツールを使えるという利点があります。 残念ながら、XML の標準自体の多くがまだ発展中なので、ツールも 当分はそれに追従しなければならないでしょう。つまり、基本 XML 1.0 勧告 を超えた仕様を利用するような安定したツールセットを短い期間で開発 するのは不可能です。 最も重要な関連標準仕様をのいくつかをサポートするような広範な種類の 高品質ツールが利用できると自信を持っていえるのははまだ先の話です。 多くのツールはフリーのようであり、ツール間の可搬性はまだ明らかでは ないようです。

XML から SGML システムへの変換が、トランスレータにとって有望であることも 判明しました。トランスレータの負荷を軽減するためにどれだけのことを 行わねばならないかはそのうち判明し、スキーマや使われている特定の技術に 対してインパクトを与えることになるかもしれません。

将来はドキュメントを XML に移行することになっていて、ドキュメントを 現在の形式から変換して、最終的なバージョンに近いものにするツールを開発 しているところです。開発は必要な情報が変換後のドキュメントに入るという 程度まで進んでいます。基礎的な XML 形式を HTML 形式に表現するような XSLT スタイルシートの開発も始まりましたが、成果はまだ荒削りの状態です。

作業にかける十分な時間がないため、変換にどれくらいかかるかははっきり していませんが、変換によってもたらされうる利益はかなり早いペースで 現実的なものになりつつあります。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 8 将来の方向性 Up: 8 将来の方向性 Next: 8.2 議論の場


8.2 議論の場

Python ドキュメント作成の将来に関する議論とドキュメントに関する議論は、 Documentation Special Interest Group 、``Doc-SIG'' で行われています。 Doc-SIG にはメーリングリストのアーカイブや購読情報があり、 http://www.python.org/sigs/doc-sig/ で利用できます。 SIG はドキュメンテーションに関心を持つ全ての人々に解放されています。

標準ドキュメントに対するコメントやバグ報告は docs@python.org に送ってください。 これには書式化、内容、文法的間違いやつづり間違い、 そしてこのドキュメント自体に対するコメントも含みます。 このドキュメントに対するコメントは作者である fdrake@acm.org に直接送っていただいてもかまいません。

注意: 和訳に対するコメントやバグ報告は、SourceForge.jp の プロジェクトページにお寄せください。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 8.1 構造化ドキュメント Up: 8 将来の方向性 Next: A. 日本語訳について


A. 日本語訳について

  • A..1 このドキュメントについて
  • A..2 翻訳者一覧
Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: 8.2 議論の場 Up: Python ドキュメントの作成 Next: A..1 このドキュメントについて


A..1 このドキュメントについて

この文書は、Pythonドキュメント翻訳プロジェクトによる Documenting Python の日本語訳版です。日本語訳に対する質問や 提案などがありましたら、Pythonドキュメント翻訳プロジェクトのメーリングリスト

http://www.python.jp/mailman/listinfo/python-doc-jp

または、プロジェクトのバグ管理ページ

http://sourceforge.jp/tracker/?atid=116&group_id=11&func=browse

までご報告ください。

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: A. 日本語訳について Up: A. 日本語訳について Next: A..2 翻訳者一覧


A..2 翻訳者一覧

2.3.3 和訳 sakito, Yasushi Masuda (May 21, 2004)

Previous Page Up One Level Next Page Python ドキュメントの作成 Contents
Previous: A..1 このドキュメントについて Up: A. 日本語訳について Next: この文書について...


Python モジュールのインストール

Greg Ward

Python Software Foundation
Email: distutils-sig@python.org

日本語訳: Python ドキュメント翻訳プロジェクト

概要:

このドキュメントでは、 Python モジュール配布ユーティリティ (Python Distribution Utilities, ``Distutils'') について、 エンドユーザの視点に立ち、サードパーティ製のモジュールや 拡張モジュールの構築やインストールによって標準の Python に 機能を追加する方法について述べます。

  • 1 はじめに
    • 1.1 もっとも簡単な場合: ありふれたインストール作業
    • 1.2 新しい標準: Distutils
  • 2 標準的なビルド・インストール作業
    • 2.1 プラットフォームによる違い
    • 2.2 ビルド作業とインストール作業を分割する
    • 2.3 ビルドの仕組み
    • 2.4 インストールの仕組み
  • 3 別の場所へのインストール
    • 3.1 別の場所へのインストール: Unix (home スキーム)
    • 3.2 別の場所へのインストール: Unix (prefix スキーム)
    • 3.3 別の場所へのインストール: Windows
    • 3.4 別の場所へのインストール: Mac OS 9
  • 4 カスタムのインストール
    • 4.1 Python サーチパスの変更
  • 5 Distutils 設定ファイル
    • 5.1 設定ファイルの場所と名前
    • 5.2 設定ファイルの構文
  • 6 拡張モジュールのビルド: 小技と豆知識
    • 6.1 コンパイラ/リンカのフラグをいじるには
    • 6.2 Windows で非 Microsoft コンパイラを使ってビルドするには
      • 6.2.1 Borland C++
      • 6.2.2 GNU C / Cygwin / MinGW
  • 7 日本語訳について
    • 7.1 このドキュメントについて
    • 7.2 翻訳者
  • この文書について...
Up One Level Next Page Python モジュールのインストール
Up: Python ドキュメントインデクス Next: 1 はじめに


1 はじめに

Python の広範な標準ライブラリは、プログラミングにおける多くの 要求をカバーしていますが、時には何らかの新たな機能をサードパーティ製 モジュールの形で追加する必要に迫られます。 自分がプログラムを書くときのサポートとして必要な場合もあるし、 自分が使いたいアプリケーションがたまたま Python で書かれていて、 そのサポートとして必要な場合もあるでしょう。

以前は、すでにインストール済みの Python に対して、サードパーティ製 モジュールを追加するためのサポートはほとんどありませんでした。 しかしPython 配布ユーティリティ (Python Distribution Utilities, 略して Distutils) が Python 2.0 から取り入れられ、状況は変わりました。

このドキュメントが主要な対象としているのは、サードパーティモジュール をインストールする必要がある人たち: 単に何らかの Python アプリケーション を稼動させたいだけのエンドユーザやシステム管理者、そしてすでに Python プログラマであって、新たな道具を自分のツールキットに加えたい と思っている人たちです。このドキュメントを読むために、 Python に ついて知っておく必要はありません; インストールしたモジュールを 調べるために Python の対話モードにちょっとだけ手を出す必要が ありますが、それだけです。自作の Python モジュールを他人が使える ようにするために配布する方法を探しているのなら、 Python モジュールの配布 マニュアルを 参照してください。

1.1 もっとも簡単な場合: ありふれたインストール作業

最も楽なのは、インストールしたいモジュール配布物の特殊なバージョンを インストールしたいプラットフォーム向けに誰かがすでに用意してくれていて、 他のアプリケーションと同じようにインストールするだけであるような場合です。 例えば Windows ユーザ向けには実行可能形式のインストーラ、 RPM ベースの Linux システム (Red Hat, SuSE, Mandrake その他多数) 向けには RPM パッケージ、 Debian ベースの Linux システム向けには Debian パッケージといった具合に、モジュール開発者はビルド済み 配布物を作成しているかもしれません。

このような場合、自分のプラットフォームに合ったインストーラをダウンロード して、実行可能形式なら実行し、RPM なら rpm -install するといった、 分かりきった作業をするだけです。 Python を起動したり、 setup スクリプトを実行する必要はなく、 何もコンパイルする必要はありません -- 説明書きを読む必要すら 全くないかもしれません (とはいえ、説明書きを読むのはよいことですが)。

もちろん、いつもこう簡単とは限りません。自分のプラットフォーム向けの お手軽なインストーラがないモジュール配布物に興味を持つこともあるでしょう。 そんな場合には、モジュールの作者やメンテナがリリースしている ソース配布物から作業をはじめねばなりません。 ソース配布物からのインストールは、モジュールが標準的な方法でパッケージ 化されている限りさほど大変ではありません。このドキュメントの大部分は、 標準的なソース配布物からのビルドとインストールに関するものです。

1.2 新しい標準: Distutils

モジュールのソースコード配布物をダウンロードしたら、配布物が 標準のやり方、すなわち Distutils のやり方に従ってパッケージされて 配布されているかどうかすぐに分かります。Distutils の場合、まず配布物の 名前とバージョン番号が、例えば foo-1.0.tar.gz や widget-0.9.7.zip のように、ダウンロードされたアーカイブファイルの 名前にはっきりと反映されます。次に、アーカイブは同様の名前の ディレクトリ、例えば foo-1.0 や widget-0.9.7 に展開されます。 さらに、配布物には setup スクリプト setup.py が入っています。 また、README.txt 場合によっては README という名前の ファイルも入っていて、そこには、モジュール配布物の構築とインストールは 簡単で、

python setup.py install
とするだけだ、という説明が書かれているはずです。

上記の全てが当てはまるなら、ダウンロードしたものをビルドして インストールする方法はすでに知っていることになります: 上記のコマンドを 実行するだけです。 非標準の方法でインストールを行ったり、ビルドプロセスをカスタマイズ 行いたいのでない限り、このマニュアルは必要ありません。 別の言葉で言えば、上のコマンドこそが、このマニュアルから習得すべき 全てということになります。

Previous Page Up One Level Next Page Python モジュールのインストール
Previous: Python モジュールのインストール Up: Python モジュールのインストール Next: 2 標準的なビルド・インストール作業


2 標準的なビルド・インストール作業

1.2 節で述べたよいうに、 Distutils を使ったモジュール 配布物のビルドとインストールは、通常は単純なコマンド:

python setup.py install
で行います。

Unixでは、このコマンドをシェルプロンプトで行います; Windows では、 コマンドプロンプトウィンドウ (``DOS ボックス'') を開いて、そこで 行います; Mac OS の場合、作業はもう少しだけ複雑です (下記参照)

2.1 プラットフォームによる違い

setup コマンドは常に配布物ルートディレクトリ、すなわちモジュールの ソース配布物を展開した際のトップレベルのサブディレクトリ内で 実行しなければなりません。例えば、あるモジュールのソース配布物 foo-1.0.tar.gz を Unix システム上にダウンロードしたなら、 通常は以下の操作を行います:

gunzip -c foo-1.0.tar.gz | tar xf -    # unpacks into directory foo-1.0
cd foo-1.0
python setup.py install
Windows では、おそらく foo-1.0.zip をダウンロードしている でしょう。アーカイブファイルを C:\Temp に ダウンロードしたのなら、(WinZip のような) グラフィカルユーザ インタフェースつきのアーカイブ操作ソフトや、 (unzip や pkunzip のような) コマンドラインツールを使って アーカイブを展開します。次に、コマンドプロンプトウィンドウ (``DOS ボックス'') を開いて、以下を実行します:

cd c:\Temp\foo-1.0
python setup.py install
Mac OS 9 では、 setup.py スクリプトをダブルクリックします。 ダイアログが表示されるので、ダイアログで install コマンドを 選択します。次に、 run ボタンを押すと、配布物をインストール します。ダイアログは動的に生成されるので、現在作業している配布物固有の コマンドやオプションがリスト表示されます。

2.2 ビルド作業とインストール作業を分割する

setup.py install を実行すると、一度の実行で全てのモジュールを ビルドしてインストールします。段階的に作業をしたい場合 -- ビルド プロセスをカスタマイズしたり、作業がうまくいかない場合に特に便利 です -- には、setup スクリプトに一度に一つづつ作業を行わせるよう にできます。この機能は、ビルドとインストールを異なるユーザで 行う場合にも便利です -- 例えば、モジュール配布物をビルドしておいて システム管理者に渡して (または、自分でスーパユーザになって) 、 インストールしたくなるかもしれません.

最初のステップでは全てをビルドしておき、次のステップで 全てをインストールするには、 setup スクリプトを二度起動します:

python setup.py build
python setup.py install
この作業を行ってみれば、install コマンドを実行すると まず build コマンドを実行し、さらに -- この場合には -- build ディレクトリの中が全て最新の状態になっているので、 build は何も行わなくてよいと判断していることが わかるでしょう。

インターネットからダウンロードしたモジュールをインストールしたい だけなら、上のように作業を分割する機能は必要ないかもしれませんが、 この機能はより進んだ使い方をする際にはとても便利です。 自作の Python モジュールや拡張モジュールを配布することになれば、 個々の Distutils コマンドを自分で何度も実行することになるでしょう。

2.3 ビルドの仕組み

上で示唆したように、 build コマンドは、インストールすべき ファイルを ビルドディレクトリ (build directory) に置く働きが あります。デフォルトでは、ビルドディレクトリは配布物ルート下の build になります; システムの処理速度に強いこだわりがあったり、 ソースツリーに指一本触れたくないのなら、--build-base オプションを使ってビルドディレクトリを変更できます。例えば:

python setup.py build --build-base=/tmp/pybuild/foo-1.0
(あるいは、システム全体向け、あるいは個人用の Distutils 設定ファイルに ディレクティブを書いて、永続的に設定を変えられます; 5 節を参照してください。) 通常は必要ない作業です。

ビルドツリーのデフォルトのレイアウトは以下のようになっています:

--- build/ --- lib/
または
--- build/ --- lib.<plat>/
               temp.<plat>/
<plat> は、現在の OS/ハードウェアプラットフォームと Python のバージョンを記述する短い文字列に展開されます。 第一の lib ディレクトリだけの形式は、 ``pure モジュール配布物'' -- すなわち、pure Python モジュールだけの入ったモジュール配布物 -- の場合に使われます。モジュール配布物に何らかの拡張モジュール (C/C++で書かれたモジュール) が入っている場合、第二の <plat> 付きディレクトリが二つある形式が使われます。この場合、 temp.plat ディレクトリには、コンパイル/リンク 過程で生成され、実際にはインストールされない一時ファイルが収められます。 どちらの場合にも、lib (または lib.plat) ディレクトリには、最終的にインストールされることになる全ての Python モジュール (pure Python モジュールおよび拡張モジュール) が入ります。

今後、 Python スクリプト、ドキュメント、バイナリ実行可能形式、 その他 Python モジュールやアプリケーションのインストール作業に 必要なディレクトリが追加されるかもしれません。

2.4 インストールの仕組み

build コマンドを実行した後 (明示的に実行した場合も、 install コマンドが代わりに実行してくれた場合も) は、 install コマンドの仕事は比較的単純なもの: build/lib (または build/lib.plat) の下にあるもの全ての 指定したインストールディレクトリへのコピー、になります。

インストールディレクトリを選ばなかった場合 -- すなわち、 setup.py install を実行しただけの場合 -- には、install コマンドはサードパーティ製 Python モジュールを置くための標準の場所に インストールを行います。この場所は、プラットフォームや、Python 自体を どのようにビルド/インストールしたかで変わります。 Unix や Mac OS では、インストールしようとするモジュール配布物が pure Python なのか、 拡張モジュールを含む (``非 pure'') のかによっても異なります:
プラットフォーム | 標準のインストール場所 | デフォルト値 | 注記
Unix (pure) | prefix/lib/python2.0/site-packages | /usr/local/lib/python2.0/site-packages | (1)
Unix (非 pure) | exec-prefix/lib/python2.0/site-packages | /usr/local/lib/python2.0/site-packages | (1)
Windows | prefix | C:\Python | (2)
Mac OS (pure) | prefix:Lib:site-packages | Python:Lib:site-packages |
Mac OS (非 pure) | prefix:Lib:site-packages | Python:Lib:site-packages |

注記:

(1)
ほとんどの Linux ディストリビューションには、システムの 標準インストール物として Python が入っているので、 Linux では普通、 prefix や exec-prefix はどちらも /usr になります。 Linux (または Unixライクなシステム) 上で自分で Python をビルドした場合、デフォルトの prefix および exec-prefix は /usr/local になります。
(2)
Windows での Python のデフォルトインストールディレクトリは、 Python 1.6a1、 1.5.2、およびそれ以前のバージョンでは C:\Program Files\Python です。

prefix および exec-prefix は、 Python がインストール されているディレクトリと、実行時にライブラリを探しにいく場所を表します。 これらのディレクトリは、Windows と Mac OS では常に同じで、 Unixでも ほぼ常に同じです。自分の Python がどんな prefix や exec-prefix を使っているかは、Python を対話モードで起動して、 単純なコマンドをいくつか入力すればわかります。 Windows では、スタート > (すべての) プログラム > Python 2.1 > Python (command line) を選びます。 Mac OS 9 では、 PythonInterpreter を起動します。 インタプリタを起動すると、プロンプトに Python コードを入力 できます。例えば、作者の使っている Linux システムで、三つの Python 文を以下のように入力すると、出力から作者のシステムの prefix と exec-prefix を得られます:

Python 1.5.2 (#1, Apr 18 1999, 16:03:16)  [GCC pgcc-2.91.60 19981201 (egcs-1.1.1  on linux2
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>> import sys
>>> sys.prefix
'/usr'
>>> sys.exec_prefix
'/usr'

モジュールを標準の場所にインストールしたくない場合や、標準の場所に インストールするためのファイル権限を持っていない場合、 3 節にある、別の場所へのインストール方法の説明を読んでください。 インストール先のディレクトリを大幅にカスタマイズしければ、 4 節のカスタムインストールに関する説明を読んでください。

Previous Page Up One Level Next Page Python モジュールのインストール
Previous: 1 はじめに Up: Python モジュールのインストール Next: 3 別の場所へのインストール


3 別の場所へのインストール

しばしば、サードパーティ製 Python モジュールをインストールするための 標準の場所以外にモジュールをインストールしなければならなかったり、 単にそうしたくなるときがあります。例えばUnix システムでは、標準のサード パーティ製モジュールディレクトリに対する書き込み権限を持っていないかも しれません。または、あるモジュールを、ローカルで使っている Python に 標準のモジュールの一部として組み込む前にテストしてみたいと思う かもしれません。既存の配布物をアップグレードする際には特にそうでしょう: 実際にアップグレードする前に、既存のスクリプトの基本となる部分が 新たなバージョンでも動作するか確認したいはずです。

Distutils の install コマンドは、別の場所へ配布物をインストール する作業を単純で苦労のない作業にするように設計されています。 基本的なアイデアは、インストール先のベースディレクトリを指定しておき、 install コマンドがそのベースディレクトリ下にファイル群を インストールするための一連のディレクトリ (インストールスキーム : installation scheme) を作成するというものです。 詳細はプラットフォームによって異なるので、以下の節から自分の プラットフォームに当てはまるものを読んでください。

3.1 別の場所へのインストール: Unix (home スキーム)

Unix環境下では、別の場所へのインストールを行う方法が二つあります。 ``prefix スキーム'' は、Windows や Mac OS で別の場所にインストール する方法と似ていますが、個人用の Python ライブラリを維持する上で 必ずしも最も便利な方法とはいえません。そこで、より手軽で便利な ``home スキーム'' をまず説明します。

``home スキーム'' の背後にある考え方は、Python モジュールを 個人用のモジュール置き場、おそらくホームディレクトリでビルドし、 維持するというものです。 新たなモジュールのインストールは単純で、

python setup.py install --home=<dir>
のようにします。このとき、--home オプションを使って ディレクトリを指定します。面倒臭がりの人は、単にチルダ (~) をタイプするだけでかまいません; install コマンドがチルダをホームディレクトリに 展開してくれます:

python setup.py install --home=~
--home オプションは、インストールのベースディレクトリ を指定します。ファイルはインストールベース下の以下のディレクトリに 保存されます:
ファイルの種類 | インストール先ディレクトリ | オーバライドするためのオプション
pure モジュール配布物 | home/lib/python | --install-purelib
非 pure モジュール配布物 | home/lib/python | --install-platlib
スクリプト | home/bin | --install-scripts
データ | home/share | --install-data

3.2 別の場所へのインストール: Unix (prefix スキーム)

あるインストール済みの Python を使ってモジュールのビルド/インストール を (例えば setup スクリプトを実行して) 行いたいけれども、 別のインストール済みの Python のサードパーティ製モジュール置き場 (あるいは、そう見えるようなディレクトリ構造) に、ビルドされた モジュールをインストールしたい場合には、``prefix スキーム'' が 便利です。そんな作業はまったくありえそうにない、と思うなら、 確かにその通りです -- ``home スキーム'' を先に説明したのも そのためです。とはいえ、prefix スキームが有用なケースは少なくとも 二つあります。

まず、多くの Linux ディストリビューションは、 Python を /usr/local ではなく /usr に置いていることを考えてください。この場合は、 Python はローカルの計算機ごとのアドオン (add-on) ではなく、``システム'' の一部となっているので、/usr に置くのは全く正当なことです。 しかしながら、 Python モジュールをソースコードからインストール していると、モジュールを /usr/lib/python2.X ではなく /usr/local/lib/python2.X に置きたいと 思うかもしれません。これを行うには

/usr/bin/python setup.py install --prefix=/usr/local
と指定します。

もう一つありえるのは、ネットワークファイルシステムにおいて、 遠隔のディレクトリに対する読み出しと書き込みの際に違う名前を使う 場合です。 例えば、 /usr/local/bin/python でアクセスするような Python インタプリタは、 /usr/local/lib/python2.X から モジュールを探すでしょうが、モジュールは別の場所、例えば /mnt/@server/export/lib/python2.X に インストールしなければならないかもしれません。この場合には、

/usr/local/bin/python setup.py install --prefix=/mnt/@server/export
のようにします。

どちらの場合も、--prefix オプションでインストール ベースディレクトリを決め、 --exec-prefix で プラットフォーム固有のファイル置き場名として使う、 プラットフォーム固有インストールベースディレクトリを決めます。 (プラットフォーム固有のファイルとは、現状では単に非 pure モジュール 配布物のことを意味しますが、 C ライブラリやバイナリ実行可能形式など に拡張されるかもしれません。) --exec-prefix が指定されていなければ、デフォルトの --prefix になります。ファイルは以下のようにインストールされます:

ファイルの種類 | インストール先ディレクトリ | オーバライドするためのオプション
pure モジュール配布物 | prefix/lib/python2.X/site-packages | --install-purelib
非 pure モジュール配布物 | exec-prefix/lib/python2.X/site-packages | --install-platlib
スクリプト | prefix/bin | --install-scripts
データ | prefix/share | --install-data

--prefix や --exec-prefix が実際に 他のインストール済み Python の場所を指している必要はありません; 上に挙げたディレクトリがまだ存在しなければ、インストール時に 作成されます。

ちなみに、prefix スキームが重要な本当の理由は、単に標準の Unix インストールが prefix スキームを使っているからです。ただし、 そのときには、 --prefix や --exec-prefix は Python 自体が sys.prefix や sys.exec_prefix を使って 決めます。というわけで、読者は prefix スキームを決して使うことは あるまいと思っているかもしれませんが、python setup.py install をオプションを何もつけずに実行していれば、常に prefix スキームを 使っていることになるのです。

拡張モジュールを別のインストール済み Python にインストールしても、 拡張モジュールのビルド方法による影響を受けることはありません: 特に、拡張モジュールをコンパイルする際には、 setup スクリプトを実行する際に使う Python インタプリタと一緒に インストールされている Python ヘッダファイル (Python.h とその仲間たち) を使います。 上で述べてきたやり方でインストールされた拡張モジュールを実行する インタプリタと、インタプリタをビルドする際に用いた別のインタプリタ との互換性を保証するのはユーザの責任です。

これを行うには、二つのインタプリタが同じバージョンの Python (ビルドが違って いたり、同じビルドのコピーということもあり得ます) であるかどうかを 確かめます。(もちろん、--prefix や --exec-prefix が別のインストール済み Python の場所すら 指していなければどうにもなりません。)

3.3 別の場所へのインストール: Windows

Windows はユーザのホームディレクトリに関する決まった概念が全くなく、 Windows 環境下で標準的にインストールされた Python は Unixよりも 単純な構成をしているので、 --prefix と --home オプションを分ける利点はありません。 ベースディレクトリを指定するには、単に --prefix を使います。例えば、

python setup.py install --prefix="\Temp\Python"
とすると、モジュールを現在のドライブの \Temp\Python ディレクトリに インストールします

インストールベースディレクトリは、 --prefix オプション だけで決まります; --exec-prefix オプションは、Windows ではサポートされていません。ファイルは以下のような構成でインストール されます:
ファイルの種類 | インストール先ディレクトリ | オーバライドするためのオプション
pure モジュール配布物 | prefix | --install-purelib
非 pure モジュール配布物 | prefix | --install-platlib
スクリプト | prefix\Scripts | --install-scripts
データ | prefix\Data | --install-data

3.4 別の場所へのインストール: Mac OS 9

Windows と同様に、Mac OS にもホームディレクトリの概念が (そもそもユーザ という概念すら) なく、標準的にインストールされる Python もかなり 単純な構成です。従って、--prefix オプションだけが必要と なります。--prefix オプションでインストールベース ディレクトリが決まり、ファイル群は以下のようにインストールされます:

ファイルの種類 | インストール先ディレクトリ | オーバライドするためのオプション
pure モジュール配布物 | prefix:Lib:site-packages | --install-purelib
非 pure モジュール配布物 | prefix:Lib:site-packages | --install-platlib
スクリプト | prefix:Scripts | --install-scripts
データ | prefix:Data | --install-data

MacPython で setup スクリプトにコマンドライン引数を与えるための 情報は、 2.1 節を参照してください。

Previous Page Up One Level Next Page Python モジュールのインストール
Previous: 2 標準的なビルド・インストール作業 Up: Python モジュールのインストール Next: 4 カスタムのインストール


4 カスタムのインストール

たまに、 3 節で述べたような別の場所へのインストール スキームが、自分のやりたいインストール方法と違うことがあります。 もしかすると、同じベースディレクトリ下にあるディレクトリのうち、 一つか二つだけをいじりたかったり、インストールスキームを完全に 再定義したいと思うかもしれません。どちらの場合にせよ、こうした操作では カスタムのインストールスキーム を作成することになります。

別の場所へのインストールスキームに関するこれまでの説明で、 ``オーバライドするためのオプション'' というコラムにお気づきかも しれません。このオプションは、カスタムのインストールスキームを 定義するための手段です。各オーバライドオプションには、 相対パスを指定しても、絶対パスを指定しても、インストールベース ディレクトリのいずれかを明示的に指定してもかまいません。 (インストールベースディレクトリは二種類あり、それら二つは通常は 同じディレクトリです -- Unix の ``prefix スキーム'' を使っていて、 --prefix と --exec-prefix オプションを 使っているときだけ異なります。)

例えば、 Unix環境でモジュール配布物をホームディレクトリにインストール したい -- とはいえ、スクリプトは ~/bin ではなく ~/scripts に置きたい -- とします。 ご想像の通り、スクリプトを置くディレクトリは、 --install-scripts オプションで上書きできます; この場合は相対パスで指定もでき、インストールベースディレクトリ (この場合にはホームディレクトリ) からの相対パスとして解釈されます:

python setup.py install --home=~ --install-scripts=scripts
Unix 環境での例をもう一つ紹介します: インストール済みの Python が、 /usr/local/python を prefix にしてビルドされ、インストール されていて、標準のインストールスクリプトは /usr/local/python/bin に入るようになっているとします。 /usr/local/bin に入るように したければ、絶対パスを --install-scripts オプションに 与えて上書きすることになるでしょう:

python setup.py install --install-scripts=/usr/local/bin
(この操作を行うと、 ``prefix スキーム'' を使ったインストールに なり、 prefix は Python インタプリタがインストールされている場所 -- この場合には /usr/local/python になります。)

Windows 用の Python を管理しているのなら、サードパーティ製モジュール を prefix そのものの下ではなく、 prefix の下 にあるサブディレクトリに置きたいと考えるかもしれません。 この作業は、インストールディレクトリのカスタマイズとほぼ同じくらい 簡単です -- 覚えておかねばならないのは、モジュールには二つのタイプ、 pure モジュールと非 pure モジュール (非 pure モジュール配布物内の モジュール) があるということです。例えば以下のようにします:

python setup.py install --install-purelib=Site --install-platlib=Site

指定したインストール先ディレクトリは、prefix からの相対です。 もちろん、prefix を .pth ファイルに入れるなどして、 これらのディレクトリが Python のモジュール検索パス内に入るように しなければなりません。 Python のモジュール検索パスを修正する方法は、 4.1 節を参照してください。

インストールスキーム全体を定義したいのなら、全てのインストール ディレクトリオプションを指定しなければなりません。この作業には、 相対パスを使った指定を勧めます; 例えば、全ての Python モジュール 関連ファイルをホームディレクトリ下の python ディレクトリの 下に置き、そのホームディレクトリをマウントしている各プラットフォーム ごとに別のディレクトリを置きたければ、以下のようにインストールスキーム を定義します:

python setup.py install --home=~ \
                        --install-purelib=python/lib \
                        --install-platlib=python/lib.$PLAT \
                        --install-scripts=python/scripts
                        --install-data=python/data
また、以下のようにも指定できます:

python setup.py install --home=~/python \
                        --install-purelib=lib \
                        --install-platlib='lib.$PLAT' \
                        --install-scripts=scripts
                        --install-data=data
$PLAT は、(必ずしも) 環境変数ではありません -- この表記は、 Distutils がコマンドラインオプションの解釈と同じやり方 で展開します。設定ファイルを解釈する際と同じです。

言うまでもないことですが、毎回新たなモジュール配布物をインストールする 度にインストールスキーム全体の指定を行っていては面倒です。そこで、 オプションは Distutils 設定ファイル (5 参照) にも 指定できます:

[install]
install-base=$HOME
install-purelib=python/lib
install-platlib=python/lib.$PLAT
install-scripts=python/scripts
install-data=python/data
あるいは、以下のようにも指定できます:

[install]
install-base=$HOME/python
install-purelib=lib
install-platlib=lib.$PLAT
install-scripts=scripts
install-data=data
これら二つは、 setup スクリプトを異なるインストールベースディレクトリ から実行した場合には同じには ならない ので注意してください。 例えば、

python setup.py --install-base=/tmp
とすると、最初の書き方では pure モジュールが/tmp/python/lib に入り、二番目の書き方では /tmp/lib に入ります。(二番目の ケースでは、インストールベースを /tmp/python に指定しようと 考えるでしょう。)

読者は、設定ファイル例で、入力値に $HOME や $PLAT を 使っていることに気づいているかもしれませんね。これらは Distutils の 設定変数で、環境変数を彷彿とさせます。実際、この表記が使える プラットフォーム上では、設定ファイル中に環境変数を入れられますが、 Distutils は他にも、例えば $PLAT のようにおそらくユーザの 環境中にないような変数をいくつか持っています。(そしてもちろん、 Mac OS 9 のような環境変数のないシステムでは、設定ファイル中で 使える変数は Distutils が提供しているものだけです。)

4.1 Python サーチパスの変更

Python インタプリタが import 文を実行するとき、 インタプリタは Python コードや拡張モジュールをモジュール検索パス 中から探します。検索パスのデフォルト値は、インタプリタをビルドする 際に Python のバイナリ内に設定されます。検索パスは、 sys を import して、 sys.path を出力すれば わかります。

$ python
Python 2.2 (#11, Oct  3 2002, 13:31:27)
[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
Type ``help'', ``copyright'', ``credits'' or ``license'' for more information.
>>> import sys
>>> sys.path
['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
 '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
 '/usr/local/lib/python2.3/site-packages']
>>>
sys.path 内の空文字列は、現在の作業ディレクトリを表します。

ローカルでインストールされるパッケージは、.../site-packages/ ディレクトリに入るのが決まりですが、ユーザはどこか任意のディレクトリに Python モジュールをインストールしたいと思うかもしれません。 例えば、自分のサイトでは、 web サーバに関連する全てのソフトウェア を /www に置くという決まりがあるかもしれません。そこで、 アドオンの Python モジュールが /www/python 置かれることに なると、モジュールを import するためにはディレクトリを sys.path に追加せねばなりません。ディレクトリを検索パスに追加するには、いくつか の異なる方法が存在します。

最も手軽な方法は、パス設定ファイルをすでに Python の検索パスに 含まれるディレクトリ、通常は .../site-packages/ ディレクトリ に置くというものです。パス設定ファイルは拡張子が .pth で、 ファイルには sys.path に追加するパスを一行に一つづつ 記述しなければなりません。 (新たなパスは今の sys.path の後ろに追加されるので、追加された ディレクトリ内にあるモジュールが標準のモジュールセットを上書き することはありません。つまり、このメカニズムを使って、標準モジュール に対する修正版のインストールはできないということです。)

パスは絶対パスでも相対パスでもよく、相対パスの場合には .pth ファイルのあるパスからの相対になります。検索パスにディレクトリが追加 されると、今度はそのディレクトリに対して .pth ファイルを 検索します。詳しくは site モジュールに関するドキュメント" > site モジュールに関するドキュメント を読んでください。

やや便利さには欠けますが、Python の標準ライブラリ中にある site.py ファイルを編集することでも、sys.path を変更 できます。site.py は、 -S スイッチを与えて 抑制しないかぎり、Python インタプリタが実行される際に自動的に import されます。ただし、設定するには、単にsite.py を編集して、例えば 以下のような二行を加えます:

import sys
sys.path.append('/www/python/')
しかしながら、(例えば 2.2 から 2.2.2 にアップグレードするときのように) 同じメジャーバージョンの Python を再インストールすると、 site.py は手持ちのバージョンで上書きされてしまいます。 ファイルが変更されていることを覚えておき、インストールを行う前に コピーを忘れずとっておかねばなりません。

また、sys.path を修正できる二つの環境変数があります。 PYTHONHOME を使うと、インストールされている Python の プレフィクスを別の値に設定できます。 例えば、 PYTHONHOME を "/www/python" に設定すると、 検索パスは ['', '/www/python/lib/python2.2/', '/www/python/lib/python2.3/plat-linux2', ...] といった具合になります。

PYTHONPATH を使うと、sys.path の先頭に一連の パスを追加できます。例えば、PYTHONPATH を "/www/python:/opt/py" に設定すると、検索パスは ['/www/python', '/opt/py'] から始まります。 (sys.path にディレクトリを追加するには、そのディレクトリが 実在しなければなりません; site は実在しないディレクトリを 除去します。)

最後に、 sys.path はただの普通の Python のリストなので、 どんな Python アプリケーションもエントリを追加したり除去したりと いった修正を行えます。

Previous Page Up One Level Next Page Python モジュールのインストール
Previous: 3 別の場所へのインストール Up: Python モジュールのインストール Next: 5 Distutils 設定ファイル


5 Distutils 設定ファイル

上で述べたように、 Distutils 設定ファイルを使えば、任意の Distutils オプションに対して個人的な設定やサイト全体の設定を 記録できます。すなわち、任意のコマンドの任意のオプションを 二つか三つ (プラットフォームによって異なります) の 設定ファイルに保存でき、コマンドラインを解釈する前にオプションを 問い合わせさせるようにできます。 つまり、設定ファイルはデフォルトの値を上書きし、さらにコマンドライン 上で与えた値が設定ファイルの内容を上書きするわけです。 さらに、複数の設定ファイルが適用されると、``先に'' 適用された ファイルに指定されていた値は ``後に'' 適用されたファイル内の 値で上書きされます。

5.1 設定ファイルの場所と名前

設定ファイルの名前と場所は、非常にわずかですがプラットフォーム間で 異なります。Unixでは、三種類の設定ファイルは以下のようになります (処理される順に並んでいます):
設定ファイルのタイプ | 場所とファイル名 | 注記
system | prefix/lib/pythonver/distutils/distutils.cfg | (1)
personal | $HOME/.pydistutils.cfg | (2)
local | setup.cfg | (3)

Windows では設定ファイルは以下のようになります:
設定ファイルのタイプ | 場所とファイル名 | 注記
system | prefix\Lib\distutils\distutils.cfg | (4)
personal | %HOME%\pydistutils.cfg | (5)
local | setup.cfg | (3)

Mac OS では以下のようになります:
設定ファイルのタイプ | 場所とファイル名 | 注記
system | prefix:Lib:distutils:distutils.cfg | (6)
personal | N/A |
local | setup.cfg | (3)

注記:

(1)
厳密に言えば、システム全体向けの設定ファイルは、 Distutils がインストールされているディレクトリになります; Unixの Python 1.6 以降では、表の通りの場所になります。 Python 1.5.2 では、 Distutils は 通常 prefix/lib/python1.5/site-packages/distutils にインストールされるため、 Python 1.5.2 では設定ファイルをそこに 置かなければなりません。
(2)
Unixでは、環境変数 HOME が定義されていない場合、 標準モジュール pwd の getpwuid() 関数を使ってユーザのホームディレクトリを決定します。
(3)
現在のディレクトリ (通常は setup スクリプトがある場所) です。
(4)
(注記 (1) も参照してください) Python 1.6 およびそれ以降の バージョンでは、 Python のデフォルトの ``インストールプレフィクス'' は C:\Python なので、システム設定ファイルは通常 C:\Python\Lib\distutils\distutils.cfg になります。Python 1.5.2 ではデフォルトの プレフィクスは C:\Program Files\Python であり、Distutils は標準ライブラリの一部ではありません -- 従って、 システム設定ファイルは、 Windows 用の標準の Python 1.5.2 では C:\Program Files\Python\distutils\distutils.cfg になります。
(5)
Windows では、環境変数 HOME が設定されていない場合、 個人用の設定ファイルはどこにもなく、使われることもありません。 (言い換えれば、 Windows での Distutils はホームディレクトリが どこにあるか一切推測しようとしないということです。)
(6)
(注釈 (1) と (4) も参照してください) デフォルトの インストールプレフィクスは単に Python: なので、 Python 1.6 以降では、通常は Python:Lib:distutils:distutils.cfg になります。

5.2 設定ファイルの構文

Distutils 設定ファイルは、全て同じ構文をしています。 設定ファイルはセクションでグループ分けされています。 各 Distutils コマンドごとにセクションがあり、それに加えて 全てのコマンドに影響するグローバルオプションを設定するための global セクションがあります。各セクションには option=value の形で、一行あたり一つのオプションを指定します。

例えば、以下は全てのコマンドに対してデフォルトでメッセージを出さない よう強制するための完全な設定ファイルです:

[global]
verbose=0
この内容のファイルがシステム全体用の設定ファイルとしてインストール されていれば、そのシステムの全てのユーザによる全ての Python モジュール 配布物に対する処理に影響します。ファイルが (個人用の設定をサポート しているシステムで) 個人用の設定ファイルとしてインストールされていれば、 そのユーザが処理するモジュール配布物にのみ影響します。 この内容を特定のモジュール配布物の setup.cfg として使えば、 その配布物だけに影響します。

以下のようにして、デフォルトの ``ビルドベース'' ディレクトリを オーバライドしたり、build* コマンドが常に強制的にリビルドを 行うようにもできます:

[build]
build-base=blib
force=1
この設定は、コマンドライン引数の

python setup.py build --build-base=blib --force
に対応します。ただし、後者ではコマンドライン上で build コマンドを含めて、そのコマンドを実行するよう意味しているところが 違います。 特定のコマンドに対するオプションを設定ファイルに含めると、 このような関連付けの必要はなくなります; あるコマンドが実行されると、そのコマンドに対するオプションが適用 されます。 (また、設定ファイル内からオプションを取得するような他のコマンドを 実行した場合、それらのコマンドもまた設定ファイル内の対応するオプション の値を使います。)

あるコマンドに対するオプションの完全なリストは、 例えば以下のように、--help を使って調べます:

python setup.py build --help
グローバルオプションの完全なリストを得るには、コマンドを指定せずに --help オプションを使います:

python setup.py --help
``Python モジュールの配布'' マニュアルの、 ``リファレンスマニュアル'' の節も参照してください。

Previous Page Up One Level Next Page Python モジュールのインストール
Previous: 4 カスタムのインストール Up: Python モジュールのインストール Next: 6 拡張モジュールのビルド: 小技と豆知識


6 拡張モジュールのビルド: 小技と豆知識

Distutils は、可能なときにはいつでも、 setup.py スクリプトを 実行する Python インタプリタが提供する設定情報を使おうとします。 例えば、拡張モジュールをコンパイルする際には、コンパイラやリンカの フラグには Python をコンパイルした際と同じものが使われます。 通常、この設定はうまくいきますが、状況が複雑になると不適切な 設定になることもあります。この節では、通常の Distutils の動作を オーバライドする方法について議論します。

6.1 コンパイラ/リンカのフラグをいじるには

C や C++で書かれた Python 拡張をコンパイルする際、しばしば 特定のライブラリを使ったり、特定の種類のオブジェクトコードを 生成したりする上で、コンパイラやリンカに与えるフラグをカスタマイズ する必要があります。ある拡張モジュールが自分のプラットフォームでは テストされていなかったり、クロスコンパイルを行わねばならない 場合にはこれが当てはまります。

最も一般的なケースでは、拡張モジュールの作者はすでに 拡張モジュールのコンパイルが複雑になることを見越していて、 Setup ファイルを提供して編集できるようにしています。 Setup ファイルの編集は、モジュール配布物に多くの個別の拡張 モジュールがあったり、コンパイラに拡張モジュールをコンパイルさせる ために細かくフラグをセットする必要があるような場合にのみ行うことに なるでしょう。

Setup ファイルが存在する場合、ビルドするべき拡張モジュールの リストを得るために解釈されます。Setup ファイルの各行には 単一のモジュールを書きます。各行は以下のような構造をとります:

 module ... [sourcefile ...] [cpparg ...] [library ...]
次に、各フィールドについて見てみましょう。

  • module はビルドする拡張モジュールの名前で、Python の 識別子名として有効でなければなりません。モジュールの名前変更は、 このフィールドを変えるだけではできない (ソースコードの編集も必要です) ので、このフィールドに手を加えるべきではありません。

  • sourcefile は、少なくともファイル名から何の言語で書かれて いるかがわかるようになっているソースコードファイル名です。 .c で終わるファイルは C で書かれているとみなされ、 .C、.cc、および .c++ で終わるファイルは C++で書かれているとみなされます。.m や .mm で 終わるファイルは Objective C で書かれているとみなされます。

  • cpparg は C プリプロセッサへの引数で、 -I、 -D、-U または -C のいずれかから始まる文字列です。

  • library は .a で終わるか、 -l または -L のいずれかから始まる文字列です。

特定のプラットフォームにおいて、プラットフォーム上の特殊なライブラリ が必要な場合、 Setup ファイルを編集して python setup.py build を実行すればライブラリを追加できます。 例えば、以下の行

foo foomodule.c
で定義されたモジュールを、自分のプラットフォーム上の数学ライブラリ libm.a とリンクしなければならない場合、Setup 内の 行に -lm を追加するだけです:

foo foomodule.c -lm
コンパイラやリンカ向けの任意のスイッチオプションは、 -Xcompiler arg や -Xlinker arg オプションで与えます:

foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm
-Xcompiler および -Xlinker の後にくる オプションは、それぞれ適切なコマンドラインに追加されます。 従って、上の例では、コンパイラには -o32 オプションが 渡され、リンカには -shared が渡されます。 コンパイラオプションに引数が必要な場合、複数の -Xcompiler オプションを与えます; 例えば、 -x c++ を渡すには、 Setup ファイルには -Xcompiler -x -Xcompiler c++ を渡さねばなりません。

コンパイラフラグは、環境変数 CFLAGS の設定でも与えられます。 CFLAGS が設定されていれば、Setup ファイル内で指定 されているコンパイラフラグに CFLAGS の内容が追加されます。

6.2 Windows で非 Microsoft コンパイラを使ってビルドするには

6.2.1 Borland C++

この小節では、 Borland C++ コンパイラのバージョン 5.5 で Distutils を使うために必要な手順について述べています。

まず、 Borland のオブジェクトファイル形式 (OMF) は、Python 公式サイトや ActiveState の Web サイトからダウンロード できるバージョンの Python が使っている形式とは違うことを知って おかねばなりません (Python は通常、 Microsoft Visual C++でビルド されています。Microsoft Visual C++は COFF をオブジェクトファイル 形式に使います。) このため、以下のようにして、 Python のライブラリ python20.lib を Borland の形式に変換する必要があります:

coff2omf python20.lib python20_bcpp.lib
coff2omf プログラムは、 Borland コンパイラに付属しています。 python20.lib は Python インストールディレクトリの Libs ディレクトリ内にあります。拡張モジュールで他のライブラリ (zlib, ...) を使っている場合、それらのライブラリも変換しなければなりません。

変換されたファイルは、通常のライブラリと同じディレクトリに置かねば なりません。

さて、 Distutils は異なる名前を持つこれらのライブラリをどのように 扱うのでしょうか? 拡張モジュールで (例えば foo という名の) ライブラリが必要な場合、 Distutils はまず _bcpp が後ろに 付いたライブラリ (例えば foo_bcpp.lib) が見つかるかどうか 調べ、あればそのライブラリを使います。該当するライブラリがなければ、 デフォルトの名前 (foo.lib) を使います1。

Borland C++ を使って Distutils に拡張モジュールをコンパイル させるには、以下のように入力します:

python setup.py build --compiler=bcpp

Borland C++ コンパイラをデフォルトにしたいなら、自分用、または システム全体向けに、 Distutils の設定ファイルを書くことを検討した 方がよいでしょう ( 5 節を参照してください)。

参考資料:

C++Builder Compiler
Borland によるフリーの C++ コンパイラに関する情報で、 コンパイラのダウンロードページへのリンクもあります。

Creating Python Extensions Using Borland's Free Compiler
Borland 製のフリーのコマンドライン C++ を使って Python を ビルドする方法について述べたドキュメントです。

6.2.2 GNU C / Cygwin / MinGW

この節では、 Cygwin や MinGW 2配布物中の GNU C/C++ コンパイラ で Distutils を使うために必要な手順について述べます。 Cygwin 向けにビルドされている Python インタプリタを使っているなら、 以下の手順をとらなくても Distutils はまったく問題なく動作します。

上記のコンパイラは、いくつかの特殊なライブラリを必要とします。 この作業は Borland の C++よりもやや複雑です。というのは、 ライブラリを変換するためのプログラムが存在しないからです。

まず、 Python DLL が公開している全てのシンボルからなるリストを 作成しなければなりません。 (この作業むけのプログラムは、 http://starship.python.net/crew/kernr/mingw32/Notes.htmlにあります。そのページで PExports 0.42h を探してください。)

pexports python20.dll >python20.def
これで、上で得られた情報をもとに、 gcc 用の import ライブラリを作成 できます。

dlltool --dllname python20.dll --def python20.def --output-lib libpython20.a
出来上がったライブラリは、 python20.lib と同じディレクトリ (Python インストールディレクトリの libs ディレクトリに なるはずです) に置かなければなりません。

拡張モジュールが他のライブラリ (zlib, ... ) を必要とする場合、 それらのライブラリも変換しなければなりません。 変換されたファイルは、それぞれ通常のライブラリが置かれているのと 同じディレクトリに置かねばなりません。

Cygwin を使って Distutils に拡張モジュールをコンパイルさせるには、

python setup.py build --compiler=cygwin
のように入力します。また、非 cygwin モードの Cygwin 3 や MinGW では、

python setup.py build --compiler=mingw32
のように入力します。

上記のオプションやコンパイラをデフォルトにしたいなら、自分用、または システム全体向けに、 Distutils の設定ファイルを書くことを検討した 方がよいでしょう ( 5 節を参照してください)。

参考資料:

Building Python modules on MS Windows platform with MinGW
MinGW 環境で必要なライブラリのビルドに関する情報があります。

http://pyopengl.sourceforge.net/ftp/win32-stuff/
Cygwin/MinGW および Borland 形式に変換済みの import ライブラリと、 Distutils がビルド済みの Python の場所を特定するために必要なレジストリ エントリを作成するためのスクリプトがあります。

... を使います1
つまり、全ての既存の COFF ライブラリを同名の OMF ライブラリに 置き換えてもかまわないということです
... MinGW2
詳しくは http://sources.redhat.com/cygwin/ や http://www.mingw.org/ を参照してください
... Cygwin3
このモードでは POSIX エミュレーションを利用できませんが、 cygwin1.dll も必要なくなります。
Previous Page Up One Level Next Page Python モジュールのインストール
Previous: 5 Distutils 設定ファイル Up: Python モジュールのインストール Next: 7 日本語訳について


7 日本語訳について

7.1 このドキュメントについて

この文書は、Pythonドキュメント翻訳プロジェクトによる Installing Python Modules の日本語訳版です。日本語訳に対する質問や 提案などがありましたら、Pythonドキュメント翻訳プロジェクトのメーリングリスト

http://www.python.jp/mailman/listinfo/python-doc-jp

または、プロジェクトのバグ管理ページ

http://sourceforge.jp/tracker/?atid=116&group_id=11&func=browse

までご報告ください。

7.2 翻訳者

2.3.3 和訳 Yasushi Masuda <y.masuda at acm.org> (April 2, 2004)

Previous Page Up One Level Next Page Python モジュールのインストール
Previous: 6 拡張モジュールのビルド: 小技と豆知識 Up: Python モジュールのインストール Next: この文書について...


この文書について...

Python モジュールのインストール

このドキュメントは、 LaTeX2HTML 変換ツールを 使って生成されています。

LaTeX2HTML の著作権は、 Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds, and Copyright © 1997, 1998, Ross Moore, Mathematics Department, Macquarie University, Sydney.
となっています。

Python ドキュメントの LaTeX2HTML への対応は、 Fred L. Drake, Jr. の多大な努力で実現しました。 オリジナルのナビゲーションアイコンは、 Christopher Petrilli によるものです。

Comments and Questions

General comments and questions regarding this document should be sent by email to docs@python.org. If you find specific errors in this document, either in the content or the presentation, please report the bug at the Python Bug Tracker at SourceForge.

Questions regarding how to use the information in this document should be sent to the Python news group, comp.lang.python, or the Python mailing list (which is gated to the newsgroup and carries the same content).

For any of these channels, please be sure not to send HTML email. Thanks.

和訳に関するコメントや質問について

本和訳プロジェクトは、少なくとも 2004 年 4 月の時点では、 Python 本体の開発プロジェクトや Python 国際化 SIG による 取り組みの一部では ありません 。 和訳の内容、和訳プロジェクトに関するご意見やご質問は、 これらのプロジェクトあてにお送りにならないようお願いします。

和訳ドキュメントに関する誤りのご指摘やご質問、コメントは、 SourceForge.jp の Python ドキュメント和訳プロジェクト バグトラッカ から お送りください。

Python でのプログラミングに関する疑問など、このドキュメントに 書かれている情報の使い方についての質問は、 日本 Python ユーザ会メーリングリスト で行うとよいでしょう。

Previous Page Up One Level Python モジュールのインストール
Previous: 7 日本語訳について Up: Python モジュールのインストール


Python モジュールの配布

Greg Ward

Email: distutils-sig@python.org

日本語訳: Python ドキュメント翻訳プロジェクト

概要:

このドキュメントでは、 Python モジュール配布ユーティリティ (Python Distribution Utilities, ``Distutils'') について、 モジュール開発者の視点に立ち、多くの人々がビルド/リリース/インストール の負荷をほとんどかけずに Python モジュールや拡張モジュールを 入手できるようにする方法について述べます。

  • 1 はじめに
  • 2 概念と用語
    • 2.1 簡単な例
    • 2.2 Python 一般の用語
    • 2.3 Distutils 固有の用語
  • 3 setup スクリプトを書く
    • 3.1 パッケージを全て列挙する
    • 3.2 個々のモジュールを列挙する
    • 3.3 拡張モジュールについて記述する
      • 3.3.1 拡張モジュールの名前とパッケージ
      • 3.3.2 拡張モジュールのソースファイル
      • 3.3.3 プリプロセッサオプション
      • 3.3.4 ライブラリオプション
      • 3.3.5 その他の操作
    • 3.4 スクリプトをインストールする
    • 3.5 追加のファイルをインストールする
    • 3.6 追加のメタデータ
    • 3.7 setup スクリプトをデバッグする
  • 4 setup 設定ファイル (setup configuration file) を書く
  • 5 ソースコード配布物を作成する
    • 5.1 配布するファイルを指定する
    • 5.2 マニフェスト (manifest) 関連のオプション
  • 6 ビルド済み配布物を作成する
    • 6.1 ダム形式のビルド済み配布物を作成する
    • 6.2 RPM パッケージを作成する
    • 6.3 Windows インストーラを作成する
      • 6.3.1 インストール後実行スクリプト (postinstallation script)
  • 7 パッケージインデクスに登録する
  • 8 例
    • 8.1 pure Python 配布物 (モジュール形式)
    • 8.2 pure Python 配布物 (パッケージ形式)
    • 8.3 単体の拡張モジュール
  • 9 リファレンスマニュアル
    • 9.1 モジュールをインストールする: install コマンド群
      • 9.1.1 install_data
      • 9.1.2 install_scripts
    • 9.2 ソースコード配布物を作成する: sdist command
  • 10 distutils.sysconfig -- システム設定情報
  • 11 日本語訳について
    • 11.1 このドキュメントについて
    • 11.2 翻訳者
  • この文書について...
Up One Level Next Page Python モジュールの配布
Up: Python ドキュメントインデクス Next: 1 はじめに


1 はじめに

このドキュメントで扱っている内容は、 Distutils を使った Python モジュールの配布で、とりわけ開発者/配布者の役割に重点を置いています: Python モジュールのインストールに関する情報を探しているのなら、 Installing Python Modules マニュアル を参照してください。

Previous Page Up One Level Next Page Python モジュールの配布
Previous: Python モジュールの配布 Up: Python モジュールの配布 Next: 2 概念と用語


2 概念と用語

Distutils の使い方は、モジュール開発者とサードパーティ製のモジュールを インストールするユーザ/管理者のどちらにとってもきわめて単純です。 開発者側のやるべきことは (もちろん、しっかりした実装で、詳しく 文書化され、よくテストされたコードを書くことは別として！) 以下の 項目になります:

  • setup スクリプト (setup.py という名前にするのがならわし) を書く
  • (必要があれば) setup 設定ファイルを書く
  • ソースコード配布物を作成する
  • (必要があれば) 一つまたはそれ以上のビルド済み (バイナリ) 形式の 配布物を作成する
これらの作業については、いずれもこのドキュメントで扱っています。

全てのモジュール開発者が複数の実行プラットフォームを利用できるわけでは ないので、全てのプラットフォーム向けにビルド済みの配布物を提供して もらえると期待するわけにはいきません。ですから、仲介を行う人々、 いわゆる パッケージ作成者 (packager) がこの問題を解決すべく 立ち上がってくれることが望ましいでしょう。パッケージ作成者は モジュール開発者がリリースしたソースコード配布物を、一つまたはそれ以上 のプラットフォーム上でビルドして、得られたビルド済み配布物をリリース することになります。したがって、ほとんどの一般的なプラットフォームに おけるユーザは、setup スクリプト一つ実行せず、コードを一行たりとも コンパイルしなくても、使っているプラットフォーム向けのきわめて普通の 方法でほとんどの一般的な Python モジュール配布物をインストールできる でしょう。

2.1 簡単な例

setup スクリプトは通常単純なものですが、Python で書かれているため、ス クリプト中で何かを処理しようと考えたとき特に制限はありません。とはい え、 setup スクリプト中に何かコストの大きな処理を行うときは十分 注意してください。 autoconf 形式の設定スクリプトとは違い、 setup スクリプトはモジュール 配布物をビルドしてインストールする中で複数回実行されることがあります。

foo.py という名前のファイルに収められている foo という 名前のモジュールを配布したいだけなら、setup スクリプトは以下のような 単純なものになります:

from distutils.core import setup
setup(name="foo",
      version="1.0",
      py_modules=["foo"])

以下のことに注意してください:

  • Distutils に与えなければならない情報のほとんどは、 setup() 関数のキーワード引数として与えます。
  • キーワード引数は二つのカテゴリ: パッケージのメタデータ (パッケージ名、バージョン番号) 、パッケージに何が収められているか の情報 (上の場合は pure Python モジュールのリスト)、に行き着きます。
  • モジュールはファイル名ではなく、モジュール名で指定します (パッケージと拡張モジュールについても同じです)
  • 作者名、電子メールアドレス、プロジェクトの URL といった 追加のメタデータを入れておくよう奨めます ( 3 の 例を参照してください)

このモジュールのソースコード配布物を作成するには、 上記のコードが入った setup スクリプト setup.py を作成して、以下のコマンド:

python setup.py sdist
を実行します。

この操作を行うと、アーカイブファイル (例えば Unixでは tarball、Windows では ZIP ファイル) を作成します。アーカイブファイル には、setup スクリプト setup.py と、配布したいモジュール foo.py が入っています。アーカイブファイルの名前は foo-1.0.targ.gz (または .zip) になり、展開すると ディレクトリ foo-1.0 を作成します。

エンドユーザが foo モジュールをインストールしたければ、 foo-1.0.tar.gz (または .zip) をダウンロードし、 パッケージを展開して、以下のスクリプトを -- foo-1.0 ディレクトリ中で -- 実行します:

python setup.py install

この操作を行うと、インストールされている Python での適切な サードパーティ製モジュール置き場にfoo.py を完璧に コピーします．

ここで述べた簡単な例では、 Distutils の基本的な概念のいくつかを 示しています。まず、開発者とインストール作業者は同じ基本 インタフェース、すなわち setup スクリプトを使っています。 二人の作業の違いは、使っている Distutils コマンド (command) にあります: sdist コマンドは、ほぼ完全に開発者だけが 対象となる一方、install はどちらかというとインストール 作業者向けです (とはいえ、ほとんどの開発者は自分のコードをインストール したくなることがあるでしょう)。

ユーザにとって本当に簡単なものにしたいのなら、一つまたはそれ以上の ビルド済み配布物を作ってあげられます。例えば、Windows マシン 上で作業をしていて、他の Windows ユーザにとって簡単な配布物を提供したいのな ら、実行可能な形式の (このプラットフォーム向けのビルド済み配布物としては もっとも適切な) インストーラを作成できます。これには bdist_wininst を使います。例えば:

python setup.py bdist_wininst
とすると、実行可能なインストーラ形式、foo-1.0.win32.exe が 現在のディレクトリに作成されます。

その他の有用な配布形態としては、bdist_rpm に実装 されている RPM 形式、 Solaris pkgtool (bdist_pkgtool) 、 HP-UX swinstall (bdist_sdux) があります。例えば、以下のコマンドを実行すると、 foo-1.0.noarch.rpm という名前の RPM ファイルを作成します:

python setup.py bdist_rpm

(bdist_rpm コマンドは rpm コマンドを使うため、 Red Hat Linux や SuSE Linux、 Mandrake Linux といった RPM ベースの システムで実行しなければなりません)

どの配布形式が利用できるかは、

python setup.py bdist --help-formats
を実行すれば分かります。

2.2 Python 一般の用語

このドキュメントを読んでいるのなら、モジュール (module)、 拡張モジュール (extension) などが何を表すのかをよく知っているかも しれません。とはいえ、読者がみな共通のスタートポイントに 立って Distutils の操作を始められるように、ここで一般的な Python 用語 について以下のような用語集を示しておきます:

モジュール (module)
Python においてコードを再利用する際の 基本単位: すなわち、他のコードから import されるひとかたまりのコード です。ここでは、三種類のモジュール: pure Python モジュール、 拡張モジュール、パッケージが関わってきます。
pure Python モジュール
Python で書かれ、単一の .py ファイル内に収められたモジュールです (.pyc かつ/または .pyo ファイルと関連があります) 。 ``pure モジュール (pure module)'' と呼ばれることもあります。
拡張モジュール (extension module)
Python を実装している 低水準言語: Python の場合は C/C++ 、 Jython の場合は Java 、 で書かれたモジュールです。 通常は、動的にロードできるコンパイル済みの単一のファイルに入っています。 例えば、Unix向け Python 拡張のための共有オブジェクト (.so) 、 Windows 向け Python 拡張のための DLL (.pyd という拡張子が与えら れています)、 Jython 拡張のための Java クラスといった具合です。 (現状では、 Distutils は Python 向けの C/C++ 拡張モジュールしか 扱わないので注意してください。)
パッケージ (package)
他のモジュールが入っているモジュールです; 通常、ファイルシステム内のあるディレクトリに収められ、 __init__.py が入っていることで通常のディレクトリと区別 できます。
ルートパッケージ (root package)
階層的なパッケージの根 (root) の部分にあたるパッケージです。(この部分には __init__.py ファイルがないので、本当のパッケージではありませんが、便宜上 そう呼びます。) 標準ライブラリの大部分はルートパッケージに入って います、また、多くの小規模な単体のサードパーティモジュールで、他の 大規模なモジュールコレクションに属していないものもここに入ります。 正規のパッケージと違い、ルートパッケージ上のモジュールの実体は様々な ディレクトリにあります: 実際は、sys.path に列挙されている ディレクトリ全てが、ルートパッケージに配置されるモジュールの内容に 影響します。

2.3 Distutils 固有の用語

以下は Distutils を使って Python モジュールを配布する際に使われる 特有の用語です:
モジュール配布物 (module distribution)
一個のファイルとして ダウンロード可能なリソースの形をとり、一括して インストールされることになっている形態で配られる Python モジュールの コレクションです。よく知られたモジュール配布物には、Numeric Python、 PyXML、 PIL (the Python Imaging Library)、 mxBase などがあります。 (パッケージ (package) と呼ばれることもありますが、 Python 用語としてのパッケージとは意味が違います: 一つのモジュール配布物 の中には、場合によりゼロ個、一つ、それ以上の Python パッケージが 入っています。)
pure モジュール配布物 (pure module distribution)
pure Python モジュールやパッケージだけが入ったモジュール配布物 です。``pure 配布物 (pure distribution)'' とも呼ばれます。

非 pure モジュール配布物 (non-pure module distribution)
少なくとも一つの拡張モジュールが入ったモジュール配布物です。 ``非 pure 配布物''とも呼びます。

配布物ルートディレクトリ (distribution root)
ソースコードツリー (またはソース配布物) ディレクトリの最上階層で、 setup.py の ある場所です。一般的には、 setup.py はこのディレクトリ上で 実行します。

Previous Page Up One Level Next Page Python モジュールの配布
Previous: 1 はじめに Up: Python モジュールの配布 Next: 3 setup スクリプトを書く


3 setup スクリプトを書く

Previous Page Up One Level Next Page Python モジュールの配布
Previous: 2 概念と用語 Up: Python モジュールの配布 Next: 4 setup 設定ファイル (setup
  • 3.1 パッケージを全て列挙する
  • 3.2 個々のモジュールを列挙する
  • 3.3 拡張モジュールについて記述する
    • 3.3.1 拡張モジュールの名前とパッケージ
    • 3.3.2 拡張モジュールのソースファイル
    • 3.3.3 プリプロセッサオプション
    • 3.3.4 ライブラリオプション
    • 3.3.5 その他の操作
  • 3.4 スクリプトをインストールする
  • 3.5 追加のファイルをインストールする
  • 3.6 追加のメタデータ
  • 3.7 setup スクリプトをデバッグする

3 setup スクリプトを書く

setup スクリプトは、Distutils を使ってモジュールをビルドし、配布し、 インストールする際の全ての動作の中心になります。 setup スクリプトの主な目的は、モジュール配布物について Distutils に 伝え、モジュール配布を操作するための様々なコマンドを正しく動作させる ことにあります。 上の 2.1 の節で見てきたように、 setup スクリプトは主に setup() の呼び出しからなり、 開発者が distuils に対して与えるほとんどの情報は setup() のキーワード引数として指定されます。

ここではもう少しだけ複雑な例: Distutils 自体の setup スクリプト、を 示します。これについては、以降の二つの節でフォローします。 (Distutils が入っているのは Python 1.6 以降であり、 Python 1.5.2 ユーザが他のモジュール配布物をインストールできるようにするための 独立したパッケージがあることを思い出してください。 ここで示した、Distutils 自身の setup スクリプトは、Python 1.5.2 に Distutils パッケージをインストールする際に使います。)

#!/usr/bin/env python

from distutils.core import setup

setup(name="Distutils",
      version="1.0",
      description="Python Distribution Utilities",
      author="Greg Ward",
      author_email="gward@python.net",
      url="http://www.python.org/sigs/distutils-sig/",
      packages=['distutils', 'distutils.command'],
     )

上の例と、 2.1 で示したファイル一つからなる小さな 配布物とは、違うところは二つしかありません: メタデータの追加と、 モジュールではなくパッケージとして pure Python モジュール群を 指定しているという点です。この点は重要です。というのも、 Distutils は 2 ダースものモジュールが (今のところ) 二つのパッケージに分かれて入って いるからです; 各モジュールについていちいち明示的に記述したリストは、 作成するのが面倒だし、維持するのも難しくなるでしょう。 その他のメタデータについては、 3.7 を参照してください。

setup スクリプトに与えるパス名 (ファイルまたはディレクトリ) は、 Unix におけるファイル名規約、つまりスラッシュ ('/') 区切りで 書かねばなりません。Distutils はこのプラットフォーム中立の表記を、 実際にパス名として使う前に、現在のプラットフォームに適した表記に 注意深く変換します。この機能のおかげで、setup スクリプトを異なる オペレーティングシステム間にわたって可搬性があるものにできます。 言うまでもなく、これは Distutils の大きな目標の一つです。 この精神に従って、このドキュメントでは全てのパス名をスラッシュ区切り にしています。 (MacOS プログラマは、先頭にスラッシュが ない 場合は、 相対パス を表すということを心に留めておかねば なりません。この規約は、コロンを使った MacOS での規約と逆だからです。)

もちろん、この取り決めは Distutils に渡すパス名だけに適用されます。 もし、例えば glob.glob() や os.listdir() の ような、標準の Python 関数を使ってファイル群を指定するのなら、 パス区切り文字 (path separator) をハードコーディングせず、 以下のように可搬性のあるコードを書くよう注意すべきです:

    glob.glob(os.path.join('mydir', 'subdir', '*.html'))
    os.listdir(os.path.join('mydir', 'subdir'))

3.1 パッケージを全て列挙する

packages オプションは、 packages リスト中で 指定されている各々のパッケージについて、パッケージ内に見つかった 全ての pure Python モジュールを処理 (ビルド、配布、インストール、等) するよう Distutils に指示します。このオプションを指定するためには、 当然のことながら各パッケージ名はファイルシステム上のディレクトリ名と 何らかの対応付けができなければなりません。デフォルトで使われる 対応関係はきわめてはっきりしたものです。すなわち、パッケージ distutils が配布物ルートディレクトリからの相対パス distutils で表されるディレクトリ中にあるというものです。 つまり、setup スクリプト中で packages = ['foo'] と指定したら、 スクリプトの置かれたディレクトリからの相対パスで foo/__init__.py を探し出せると Distutils に確約した ことになります。この約束を裏切ると Distutils は警告を出しますが、 そのまま壊れたパッケージの処理を継続します。

ソースコードディレクトリの配置について違った規約を使っていても、 まったく問題はありません: 単に package_dir オプションを 指定して、 Distutils に自分の規約を教えればよいのです。 例えば、全ての Python ソースコードを lib 下に置いて、 ``ルートパッケージ'' 内のモジュール (つまり、どのパッケージ にも入っていないモジュール) を lib 内に入れ、 foo パッケージを lib/foo に入れる、といった 具合にしたいのなら、

package_dir = {'': 'lib'}
を setup スクリプト内に入れます。辞書内のキーはパッケージ名で、 空のパッケージ名はルートパッケージを表します。キーに対応する値は ルートパッケージからの相対ディレクトリ名です、この場合、 packages = ['foo'] を指定すれば、 lib/foo/__init__.py が存在すると Distutils に 確約したことになります。

もう一つの規約のあり方は foo パッケージを lib に 置き換え、foo.bar パッケージが lib/bar にある、 などとするものです。このような規約は、 setup スクリプトでは

package_dir = {'foo': 'lib'}
のように書きます。 package_dir 辞書に package: dir のようなエントリがあると、 package の下にある全てのパッケージに対してこの規則が 暗黙のうちに適用され、その結果 foo.bar の場合が自動的に 処理されます。 この例では、 packages = ['foo', 'foo.bar'] は、 Distutils に lib/__init__.py と lib/bar/__init__.py を探すように指示します。 (package_dir は再帰的に適用されますが、この場合 packages の下にある全てのパッケージを明示的に指定 しなければならないことを心に留めておいてください: Distutils は __init__.py を持つディレクトリを ソースツリーから再帰的にさがしたりは しません 。)

3.2 個々のモジュールを列挙する

小さなモジュール配布物の場合、パッケージを列挙するよりも、 全てのモジュールを列挙するほうがよいと思うかもしれません -- 特に、単一のモジュールが ``ルートパッケージ'' にインストール される (すなわち、パッケージは全くない) ような場合がそうです。 この最も単純なケースは 2.1 で示しました; ここではもうちょっと入り組んだ例を示します:

py_modules = ['mod1', 'pkg.mod2']
ここでは二つのモジュールについて述べていて、一方は ``ルート'' パッケージに入り、他方は pkg パッケージに入ります。 ここでも、デフォルトのパッケージ/ディレクトリのレイアウトは、 二つのモジュールが mod1.py と pkg/mod2.py にあり、pkg/__init__.py が存在することを暗示して います。また、パッケージ/ディレクトリの対応関係は package_dir オプションでも上書きできます。

3.3 拡張モジュールについて記述する

pure Python モジュールを書くより Python 拡張モジュールを書く方が ちょっとだけ複雑なように、 Distutils での拡張モジュールに関する 記述もちょっと複雑です。pure モジュールと違い、単にモジュールや パッケージを列挙して、Distutils が正しいファイルを見つけてくれる と期待するだけでは十分ではありません; 拡張モジュールの名前、 ソースコードファイル (群) 、そして何らかのコンパイル/リンクに 関する必要事項 (include ディレクトリ、リンクすべきライブラリ、等) を指定しなければなりません。

こうした指定は全て、 setup() の別のキーワード 引数、 extensions オプションを介して行えます。 extensions は、 Extensions インスタンスから なるただのリストで、各インスタンスに一個の拡張モジュールを 記述するようになっています。仮に、foo.c で実装された 拡張モジュール foo が、配布物に一つだけ入ってるとします。 コンパイラ/リンカに他の情報を与える必要がない場合、この拡張 モジュールのための記述はきわめて単純です:

Extension("foo", ["foo.c"])

Extension クラスは、 setup() によって、 distutils.core から import されます。 従って、拡張モジュールが一つだけ入っていて、他には何も入っていない モジュール配布物を作成するための setup スクリプトは、以下のように なるでしょう:

from distutils.core import setup, Extension
setup(name="foo", version="1.0",
      ext_modules=[Extension("foo", ["foo.c"])])

Explained クラス (実質的には、Explained クラスの 根底にある build_ext コマンドで実装されている、拡張 モジュールをビルドする機構) は、Python 拡張モジュールをきわめて 柔軟に記述できるようなサポートを提供しています。 これについては後の節で説明します。

3.3.1 拡張モジュールの名前とパッケージ

Extension クラスのコンストラクタに与える最初の引数は、 常に拡張モジュールの名前にします。これにはパッケージ名も含めます。 例えば、

Extension("foo", ["src/foo1.c", "src/foo2.c"]p)

とすると、拡張モジュールをルートパッケージに置くことになります。一方、

Extension("pkg.foo", ["src/foo1.c", "src/foo2.c"])

は、同じ拡張モジュールを pkg パッケージの下に置くよう 記述しています。ソースコードファイルと、作成されるオブジェクトコードは どちらの場合でも同じです; 作成された拡張モジュールがファイルシステム 上のどこに置かれるか (すなわち Python の名前空間上のどこに置かれるか) が違うにすぎません。

同じパッケージ内に (または、同じ基底パッケージ下に) いくつもの拡張 モジュールがある場合、ext_package キーワード引数を setup() に指定します。例えば、

setup(...
      ext_package="pkg",
      ext_modules=[Extension("foo", ["foo.c"]),
                   Extension("subpkg.bar", ["bar.c"])]
     )

とすると、 foo.c をコンパイルして pkg.foo にし、 bar.c をコンパイルして pkg.subpkg.bar にします。

3.3.2 拡張モジュールのソースファイル

Extension コンストラクタの二番目の引数は、ソースファイルの リストです。 Distutils は現在のところ、C、C++、そして Objective-C の拡張しかサポートしていないので、引数は通常 C/C++/Objective-C ソースコードファイルになります。 (C++ソースコードファイルを区別 できるよう、正しいファイル拡張子を使ってください: .cc や .cpp にすれば、 Unix と Windows 用の双方のコンパイラで 認識されるようです。)

ただし、 SWIG インタフェース (.i) ファイルはリストに含め られます; build_ext コマンドは、 SWIG で書かれた 拡張パッケージをどう扱えばよいか心得ています: build_ext は、インタフェースファイルを SWIG にかけ、得られた C/C++ ファイルをコンパイルして拡張モジュールを生成します。

3.3.3 プリプロセッサオプション

Extension には三種類のオプション引数: include_dirs, define_macros, そして undef_macros があり、検索対象に するインクルードディレクトリを指定したり、プリプロセッサマクロを 定義 (define)/定義解除 (undefine) したりする必要があるとき役立ちます。

例えば、拡張モジュールが配布物ルート下の include ディレクトリにあるヘッダファイルを必要とするときには、 include_dirs オプションを使います:

Extension("foo", ["foo.c"], include_dirs=["include"])

ここには絶対パスも指定できます; 例えば、自分の拡張モジュールが、 /usr の下にX11R6 をインストールした Unix システムだけで ビルドされると知っていれば、

Extension("foo", ["foo.c"], include_dirs=["/usr/include/X11"])

のように書けます。

自分のコードを配布する際には、このような可搬性のない使い方は 避けるべきです: おそらく、 C のコードを

#include <X11/Xlib.h>

のように書いた方がましでしょう。

他の Python 拡張モジュール由来のヘッダを include する必要があるなら、 Distutils の install_header コマンドが一貫した方法で ヘッダファイルをインストールするという事実を活用できます。 例えば、 Numerical Python のヘッダファイルは、 (標準的な Unix が インストールされた環境では) /usr/local/include/python1.5/Numerical にインストールされます。 (実際の場所は、プラットフォームやどの Python をインストールしたかで 異なります。) Python の include ディレクトリ -- 今の例では /usr/local/include/python1.5 -- は、 Python 拡張モジュールを ビルドする際に常にヘッダファイル検索パスに取り込まれるので、 C コードを書く上でもっともよいアプローチは、

#include <Numerical/arrayobject.h>
となります。

Numerical インクルードディレクトリ自体をヘッダ検索パス に置きたいのなら、このディレクトリを Distutils の sysconfig モジュールを使って見つけさせられます:

from distutils.sysconfig import get_python_inc
incdir = os.path.join(get_python_inc(plat_specific=1), "Numerical")
setup(...,
      Extension(..., include_dirs=[incdir]))

この書き方も可搬性はあります -- プラットフォームに関わらず、 どんな Python がインストールされていても動作します -- が、 単に実践的な書き方で C コードを書く方が簡単でしょう。

define_macros および undef_macros オプションを使って、 プリプロセッサマクロを定義 (define) したり、定義解除 (undefine) したりもできます。 define_macros はタプル (name, value) からなるリストを 引数にとります。name は定義したいマクロの名前 (文字列) で、 value はその値です: value は文字列か None に なります。(マクロ FOO を None にすると、C ソースコード内 で #define FOO と書いたのと同じになります: こう書くと、 ほとんどのコンパイラは FOO を文字列 1 に設定します。) undef_macros には、定義解除したいマクロ名からなるリストを 指定します。

例えば、以下の指定:

Extension(...,
          define_macros=[('NDEBUG', '1'),
                         ('HAVE_STRFTIME', None)],
          undef_macros=['HAVE_FOO', 'HAVE_BAR'])

は、全ての C ソースコードファイルの先頭に、以下のマクロ:

#define NDEBUG 1
#define HAVE_STRFTIME
#undef HAVE_FOO
#undef HAVE_BAR

があるのと同じになります。

3.3.4 ライブラリオプション

拡張モジュールをビルドする際にリンクするライブラリや、ライブラリを 検索するディレクトリも指定できます。 libraries はリンクするライブラリのリストで、 library_dirs はリンク時にライブラリを検索するディレクトリの リストです。また、runtime_library_dirs は、実行時に 共有ライブラリ (動的にロードされるライブラリ) を検索するディレクトリの リストです。

例えば、ビルド対象システムの標準ライブラリ検索パスにあることが分かって いるライブラリをリンクする時には、以下のようにします。

Extension(...,
          libraries=["gdbm", "readline"])

非標準のパス上にあるライブラリをリンクしたいなら、その場所を library_dirs に入れておかなければなりません:

Extension(...,
          library_dirs=["/usr/X11R6/lib"],
          libraries=["X11", "Xt"])

(繰り返しになりますが、この手の可搬性のない書き方は、コードを配布する のが目的なら避けるべきです。)

3.3.5 その他の操作

他にもいくつかオプションがあり、特殊な状況を扱うために使います。

extra_objects オプションには、リンカに渡すオブジェクトファイル のリストを指定します。ファイル名には拡張子をつけてはならず、コンパイラ で使われているデフォルトの拡張子が使われます。

extra_compile_args および extra_link_args には、 それぞれコンパイラとリンカに渡す追加のコマンドライン引数を指定します。

export_symbols は Windows でのみ意味があります。 このオプションには、公開 (export) する (関数や変数の) シンボルのリスト を入れられます。コンパイルして拡張モジュールをビルドする際には、 このオプションは不要です: Distutils は公開するシンボルを自動的に initmodule に渡すからです。

3.4 スクリプトをインストールする

ここまでは、スクリプトから import され、それ自体では実行されない ような pure Python モジュールおよび非 pure Python モジュール について扱ってきました。

スクリプトとは、Python ソースコードを含むファイルで、コマンドライン から実行できるよう作られているものです。スクリプトは Distutils に 複雑なことを一切させません。唯一の気の利いた機能は、スクリプトの 最初の行が #! で始まっていて、 ``python'' という単語が 入っていた場合、Distutils は最初の行を現在使っているインタプリタを 参照するよう置き換えます。

scripts オプションには、単に上で述べた方法で取り扱うべき ファイルのリストを指定するだけです。PyXML の setup スクリプトを 例に示します:

setup (...
       scripts = ['scripts/xmlproc_parse', 'scripts/xmlproc_val']
      )

3.5 追加のファイルをインストールする

data_files オプションを使うと、モジュール配布物で必要な 追加のファイル: 設定ファイル、メッセージカタログ、データファイル、 その他これまで述べてきたカテゴリに収まらない全てのファイルを指定 できます。

data_files には、(directory, files) の ペアを以下のように指定します:

setup(...
      data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
                  ('config', ['cfg/data.cfg']),
                  ('/etc/init.d', ['init-script'])]
     )

データファイルのインストール先ディレクトリ名は指定できますが、 データファイル自体の名前の変更はできないので注意してください。

各々の (directory, files) ペアには、インストール先の ディレクトリ名と、そのディレクトリにインストールしたいファイルを 指定します。directory が相対パスの場合、インストール プレフィクス (installation prefix、 pure Python パッケージなら sys.prefix 、拡張モジュールの入ったパッケージなら sys.exec_prefix) からの相対パスと解釈されます。 files 内の各ファイル名は、パッケージソースコード配布物 の最上階層の、 setup.py のあるディレクトリからの相対パスと 解釈されます。files に書かれたディレクトリ情報は、 ファイルを最終的にどこにインストールするかを決めるときには使われ ません; ファイルの名前だけが使われます。

data_files オプションは、ターゲットディレクトリを指定せずに、 単にファイルの列を指定できます。しかし、このやり方は推奨されておらず、 指定すると install コマンドが警告を出力します。 ターゲットディレクトリにデータファイルを直接インストールしたいなら、 ディレクトリ名として空文字列を指定してください。

3.6 追加のメタデータ

setup スクリプトには、名前やバージョンにとどまらず、その他の メタデータを含められます。以下のような情報を含められます:

メタデータ | 説明 | 値 | 注記
name | パッケージの名前 | 短い文字列 | (1)
version | リリースのバージョン | 短い文字列 | (1)(2)
author | パッケージ作者の名前 | 短い文字列 | (3)
author_email | パッケージ作者の電子メールアドレス | 電子メールアドレス | (3)
maintainer | パッケージメンテナンス担当者の名前 | 短い文字列 | (3)
maintainer_email | パッケージメンテナンス担当者の 電子メールアドレス | 電子メールアドレス | (3)
url | パッケージのホームページ | URL | (1)
description | パッケージについての簡潔な概要説明 | 短い文字列 |
long_description | パッケージについての詳細な説明 | 長い文字列 |
download_url | パッケージをダウンロードできる場所 | URL | (4)
classifiers | Trove 分類語 | 文字列からなるリスト | (4)

注記:

(1)
必須のフィールドです。
(2)
バージョン番号は major.minor[.patch[.sub]] の形式をとるよう奨めます。
(3)
作者かメンテナのどちらかは必ず区別してください。
(4)
これらのフィールドは、2.2.3 および 2.3 より以前の バージョンの Python でも互換性を持たせたい場合には指定しては なりません。 リストは PyPI ウェブサイト にあります。

「短い文字列」
200 文字以内の一行のテキスト。
「長い文字列」
複数行からなり、ReStructuredText 形式で書かれた プレーンテキスト (http://docutils.sf.net/ を参照してください)。
「文字列のリスト」
下記を参照してください。

これらの文字列はいずれも Unicode であってはなりません。

バージョン情報のコード化は、それ自体が一つのアートです。 Python のパッケージは一般的に、 major.minor[.patch][sub] という バージョン表記に従います。 メジャー (major) 番号は最初は 0 で、これはソフトウェアが実験的リリース にあることを示します。メジャー番号は、パッケージが主要な開発目標を 達成したとき、それを示すために加算されてゆきます。マイナー (minor) 番号は、パッケージに重要な新機能が追加されたときに加算されてゆきます。 パッチ (patch) 番号は、バグフィクス版のリリースが作成されたときに 加算されます。末尾にバージョン情報が追加され、サブリリースを示す こともあります。これは "a1,a2,...,aN" (アルファリリースの場合で、 機能や API が変更されているとき)、 "b1,b2,...,bN" (ベータリリース の場合で、バグフィクスのみのとき) 、そして "pr1,pr2,...,prN" (プレリリースの最終段階で、リリーステストのとき) になります。 以下に例を示します:

0.1.0
パッケージの最初の実験的なリリース
1.0.1a2
1.0 の最初のパッチバージョンに対する、2 回目のアルファ リリース

classifiers は、 Python のリスト型で指定します:

setup(...
      classifiers = [
          'Development Status :: 4 - Beta',
          'Environment :: Console',
          'Environment :: Web Environment',
          'Intended Audience :: End Users/Desktop',
          'Intended Audience :: Developers',
          'Intended Audience :: System Administrators',
          'License :: OSI Approved :: Python Software Foundation License',
          'Operating System :: MacOS :: MacOS X',
          'Operating System :: Microsoft :: Windows',
          'Operating System :: POSIX',
          'Programming Language :: Python',
          'Topic :: Communications :: Email',
          'Topic :: Office/Business',
          'Topic :: Software Development :: Bug Tracking',
          ],
      )

setup.py に classifiers を入れておき、なおかつ 2.2.3 よりも以前のバージョンの Python と後方互換性を保ちたいなら、 setup.py 中で setup() を呼び出す前に、以下のコードを 入れます。

# patch distutils if it can't cope with the "classifiers" or
# "download_url" keywords
if sys.version < '2.2.3':
    from distutils.dist import DistributionMetadata
    DistributionMetadata.classifiers = None
    DistributionMetadata.download_url = None

3.7 setup スクリプトをデバッグする

setup スクリプトのどこかがまずいと、開発者の思い通りに動作 してくれません。

Distutils は setup 実行時の全ての例外を捉えて、簡単なエラーメッセージ を出力してからスクリプトを終了します。このような仕様にしているのは、 Python にあまり詳しくない管理者がパッケージをインストールする際に 混乱しなくてすむようにするためです。 もし Distutils のはらわた深くからトレースバックした長大な メッセージを見たら、管理者はきっと Python のインストール自体が おかしくなっているのだと勘違いして、トレースバックを最後まで読み進んで 実はファイルパーミッションの問題だったと気づいたりはしないでしょう。

しかし逆に、この仕様は開発者にとってはうまくいかない理由を見つける 役には立ちません。そこで、 DISTUTILS_DEBUG 環境変数を空文字以外の 何らかの値に設定しておけば、 Distutils が何を実行しているか詳しい 情報を出力し、例外が発生した場合には完全なトレースバックを出力 するようにできます。

Previous Page Up One Level Next Page Python モジュールの配布
Previous: 2 概念と用語 Up: Python モジュールの配布 Next: 4 setup 設定ファイル (setup


4 setup 設定ファイル (setup configuration file) を書く

時に、配布物をビルドする際に必要な全ての設定をあらかじめ 書き きれない状況が起きます: 例えば、ビルドを進めるために、ユーザに関する 情報や、ユーザのシステムに関する情報を必要とするかもしれません。 こうした情報が単純 -- C ヘッダファイルやライブラリを検索する ディレクトリのリストのように -- であるかぎり、ユーザに 設定ファイル (configuration file) setup.cfg を提供して 編集してもらうのが、安上がりで簡単な特定方法になります。 設定ファイルはまた、あらゆるコマンドにおけるオプションにデフォルト値 を与えておき、インストール作業者がコマンドライン上や設定ファイルの 編集でデフォルト設定を上書きできるようにします。

setup 設定ファイルは setup スクリプト --理想的にはインストール作業者 から見えないもの 1 --と、作者の手を離れて、全てインストール 作業者次第となる setup スクリプトのコマンドライン引数との間を 橋渡しする中間層として有効です。 実際、setup.cfg (と、ターゲットシステム上にある、その他の Distutils 設定ファイル) は、 setup スクリプトの内容より後で、 かつコマンドラインで上書きする前に処理されます。 この仕様の結果、いくつかの利点が生まれます:

  • インストール作業者は、作者が setup.py に設定した項目の いくつかを setup.cfg を変更して上書きできます。
  • setu.py では簡単に設定できないような、標準でない オプションのデフォルト値を設定できます。
  • インストール作業者は、setup.cfg に書かれたどんな設定も setup.py のコマンドラインオプションで上書きできます。

設定ファイルの基本的な構文は簡単なものです:

[command]
option=value
...

ここで、 command は Distutils コマンドのうちの一つ (例えば build_py, install) で、option はそのコマンドでサポートされているオプションのうちの一つです。 各コマンドには任意の数のオプションを設定でき、一つの設定ファイル 中には任意の数のコマンドセクションを収められます。 空白行は無視されます、 "#" 文字で開始して行末まで続く コメントも同様に無視されます。 長いオプション設定値は、継続行をインデントするだけで複数行に わたって記述できます。

あるコマンドがサポートしているオプションのリストは、 --help オプションで調べられます。例えば以下のように。

> python setup.py --help build_ext
[...]
Options for 'build_ext' command:
  --build-lib (-b)     directory for compiled extension modules
  --build-temp (-t)    directory for temporary files (build by-products)
  --inplace (-i)       ignore build-lib and put compiled extensions into the
                       source directory alongside your pure Python modules
  --include-dirs (-I)  list of directories to search for header files
  --define (-D)        C preprocessor macros to define
  --undef (-U)         C preprocessor macros to undefine
[...]

コマンドライン上で --foo-bar と綴るオプションは、 設定ファイル上では foo_bar と綴るので注意してください。

例えば、拡張モジュールを ``インプレース (in-place)'' でビルドしたい とします -- すなわち、pkg.ext という拡張モジュールを 持っていて、コンパイル済みの拡張モジュールファイル (例えば Unix では ext.so) を pure Python モジュール pkg.mod1 および pkg.mod2 と同じソースディレクトリに置きたいとします。 こんなときには、--inplace を使えば、確実にビルドを 行えます。

python setup.py build_ext --inplace

しかし、この操作では、常に build_ext を明示的に指定 しなければならず、 --inplace オプションを忘れずに 与えなければなりません。 こうした設定を ``設定しっ放しにする'' 簡単な方法は、 setup.cfg に書いておくやり方で、設定ファイルは以下のように なります:

[build_ext]
inplace=1

この設定は、明示的に build_ext を指定するかどうかに 関わらず、モジュール配布物の全てのビルドに影響します。 ソース配布物に setup.cfg を含めると、エンドユーザの手で 行われるビルドにも影響します -- このオプションの例に関しては setup.cfg を含めるのはおそらくよくないアイデアでしょう。 というのは、拡張モジュールをインプレースでビルドすると常に インストールしたモジュール配布物を壊してしまうからです。 とはいえ、ある特定の状況では、モジュールをインストールディレクトリ の下に正しく構築できるので、機能としては有用だと考えられます。 (ただ、インストールディレクトリ上でのビルドを想定するような 拡張モジュールの配布は、ほとんどの場合よくない考え方です。)

もう一つ、例があります: コマンドによっては、実行時にほとんど 変更されないたくさんのオプションがあります; 例えば、 bdist_rpm には、RPM 配布物を作成する際に、``spec'' ファイルを作成するために必要な情報を全て与えなければなりません。 この情報には setup スクリプトから与えるものもあり、 (インストールされるファイルのリストのように) Distutils が自動的に 生成するものもあります。しかし、こうした情報の中には bdist_rpm のオプションとして与えるものがあり、 毎回実行するごとにコマンドライン上で指定するのが面倒です。 そこで、以下のような内容が Distutils 自体の setup.cfg には入っています:

[bdist_rpm]
release = 1
packager = Greg Ward <gward@python.net>
doc_files = CHANGES.txt
            README.txt
            USAGE.txt
            doc/
            examples/

doc_files オプションは、単に空白で区切られた文字列で、 ここでは可読性のために複数行をまたぐようにしています。

参考資料:

Installing Python Modules
設定ファイルに関する詳細情報は、システム管理者 向けのこのマニュアルにあります。

... から見えないもの1
Distutils が自動設定機能 (auto-configuration) をサポートするまで、おそらくこの理想状態を 達成することはないでしょう
Previous Page Up One Level Next Page Python モジュールの配布
Previous: 3 setup スクリプトを書く Up: Python モジュールの配布 Next: 5 ソースコード配布物を作成する


5 ソースコード配布物を作成する

2.1 節で示したように、ソースコード配布物を作成 するには sdist コマンドを使います。最も単純な例では、

python setup.py sdist
のようにします (ここでは、sdist に関するオプションを setup スクリプトや設定ファイル中で行っていないものと仮定します)。 sdist は、現在のプラットフォームでのデフォルトのアーカイブ形式 でアーカイブを生成します。デフォルトの形式は Unixでは gzip で圧縮された tar ファイル形式 (.tar.gz) で、Windows では ZIP 形式です。

5.1 配布するファイルを指定する

明確なファイルのリスト (またはファイルリストを生成する方法) を明示的に 与えなかった場合、sdist コマンドはソース配布物に以下のような 最小のデフォルトのセットを含めます:

  • py_modules と packages オプションに指定された Python ソースファイル全て
  • ext_modules や libraries オプションに記載 された C ソースファイル

    5.2 マニフェスト (manifest) 関連のオプション

    sdist コマンドが通常行う処理の流れは、以下のようになって います:

    • マニフェストファイル MANIFEST が存在しなければ、 MANIFEST.in を読み込んでマニフェストファイルを作成します
    • MANIFEST も MANIFEST.in もなければ、 デフォルトのファイルセットだけでできたマニフェストファイルを 作成します
    • MANIFEST.in または (setup.py) が MANIFEST より新しければ、MANIFEST.in を読み込んで MANIFEST を生成します
    • (生成されたか、読み出された) MANIFEST 内にあるファイル のリストを使ってソース配布物アーカイブを作成します
    上の動作は二種類のオプションを使って修正できます。まず、 標準の ``include'' および ``exclude'' セットを無効化するには --no-defaults および --no-prune を使います

    第二に、マニフェストファイルの再生成を強制できます -- 例えば、 現在マニフェストテンプレート内に指定しているパターンにマッチする ファイルやディレクトリを追加したり削除したりすると、マニフェストを 再生成しなくてはなりません:

    python setup.py sdist --force-manifest

    また、単にマニフェストを (再) 生成したいだけで、ソース配布物は 作成したくない場合があるかもしれません:

    python setup.py sdist --manifest-only

    --manifest-only を行うと、 --force-manifest を呼び出します。 -o は --manifest-only のショートカット、 -f は --force-manifest のショートカットです。

    Previous Page Up One Level Next Page Python モジュールの配布
    Previous: 4 setup 設定ファイル (setup Up: Python モジュールの配布 Next: 6 ビルド済み配布物を作成する


6 ビルド済み配布物を作成する

``ビルド済み配布物'' とは、おそらく皆さんが通常 ``バイナリパッケージ'' とか ``インストーラ'' (背景にしている知識によって違います) と考えて いるものです。とはいえ、配布物が必然的にバイナリ形式になるわけでは ありません。配布物には、 Python ソースコード、かつ/またはバイトコード が入るからです; また、我々はパッケージという呼び方もしません。 すでに Python の用語として使っているからです (また、 ``インストーラ'' という言葉は Windows 特有の用語です

6.1 ダム形式のビルド済み配布物を作成する

6.2 RPM パッケージを作成する

RPM 形式は、Red Hat, SuSE, Mandrake といった、多くの一般的な Linux ディストリビューションで使われています。普段使っているのがこれらの 環境のいずれか (またはその他の RPM ベースの Linux ディストリビューション) なら、同じディストリビューションを使っている 他のユーザ用に RPM パッケージを作成するのはとるに足らないことでしょう。 一方、モジュール配布物の複雑さや、 Linux ディストリビューション間の 違いにもよりますが、他の RPM ベースのディストリビューションでも動作 するような RPM を作成できるかもしれません。

通常、モジュール配布物の RPM を作成するには、bdist_rpm コマンドを使います:

python setup.py bdist_rpm

あるいは、bdist コマンドを --format オプション付きで使います:

python setup.py bdist --formats=rpm

前者の場合、 RPM 特有のオプションを指定できます; 後者の場合、 一度の実行で複数の形式を指定できます。両方同時にやりたければ、 それぞれの形式について各コマンドごとにオプション付きで bdist_* コマンドを並べます:

python setup.py bdist_rpm --packager="John Doe <jdoe@python.net>" \
                bdist_wininst --target_version="2.0"

Distutils が setup スクリプトで制御されているのとほとんど同じく、 RPM パッケージの作成は、 .spec で制御されています。 RPM の作成を簡便に解決するため、bdist_rpm コマンドでは 通常、 setup スクリプトに与えた情報とコマンドライン、そして Distutils 設定ファイルに基づいて .spec ファイルを作成します。 .spec ファイルの様々なオプションやセクション情報は、 以下のようにして setup スクリプトから取り出されます:
RPM .spec ファイルのオプションまたはセクション | Distutils setup スクリプト内のオプション
Name | name
Summary (preamble 内) | description
Version | version
Vendor | author と author_email, または & maintainer と maintainer_email
Copyright | licence
Url | url
%description (セクション) | long_description

また、.spec ファイル内の多くのオプションは、 setup スクリプト 中に対応するオプションがありません。これらのほとんどは、以下に示す bdist_rpm コマンドのオプションで扱えます:
RPM .spec ファイルのオプションまたはセクション | bdist_rpm オプション | デフォルト値
Release | release | ``1''
Group | group | ``Development/Libraries''
Vendor | vendor | (上記参照)
Packager | packager | (none)
Provides | provides | (none)
Requires | requires | (none)
Conflicts | conflicts | (none)
Obsoletes | obsoletes | (none)
Distribution | distribution_name | (none)
BuildRequires | build_requires | (none)
Icon | icon | (none)
言うまでもなく、こうしたオプションをコマンドラインで指定するのは 面倒だし、エラーの元になりますから、普通は setup.cfg に 書いておくのがベストです -- 4 節を参照してください。 沢山の Python モジュール配布物を配布したりパッケージ化したりしている のなら、配布物全部に当てはまるオプションを個人用の Distutils 設定 ファイル (~/.pydistutils.cfg) に入れられます。

バイナリ形式の RPM パッケージを作成する際には三つの段階があり、 Distutils はこれら全ての段階を自動的に処理します:

  1. RPM パッケージの内容を記述する .spec ファイルを作成します (.spec ファイルは setup スクリプトに似たファイルです; 実際、 setup スクリプトのほとんどの情報が .spec ファイルから 引き揚げられます)
  2. ソース RPM を作成します
  3. ``バイナリ (binary)'' RPM を生成します (モジュール配布物に Python 拡張モジュールが入っているか否かで、バイナリコードが 含まれることも含まれないこともあります)
通常、RPM は最後の二つのステップをまとめて行います; Distutils を使うと、普通は三つのステップ全てをまとめて行います。

望むなら、これらの三つのステップを分割できます。bdist_rpm コマンドに --spec-only を指定すれば、単に .spec を作成して終了します; この場合、.spec ファイルは ``配布物ディレクトリ (distribution directory)''-- 通常は dist/ に作成されますが、 --dist-dir オプションで変更することもできます。(通常、 .spec ファイルは ``ビルドツリー (build tree)''、すなわち build_rpm が作成する一時ディレクトリの中から引き揚げられます。)

6.3 Windows インストーラを作成する

実行可能なインストーラは、Windows 環境ではごく自然なバイナリ配布形式 です。インストーラは結構なグラフィカルユーザインタフェースを表示して、 モジュール配布物に関するいくつかの情報を setup スクリプト内のメタデータ から取り出して示し、ユーザがいくつかのオプションを選んだり、インストール を決行するか取りやめるか選んだりできるようにします。

メタデータは setup スクリプトから取り出されるので、Windows インストーラ の作成は至って簡単で、以下を実行するだけです:

python setup.py bdist_wininst

あるいは、bdist コマンドを --formats オプション付きで実行します:

python setup.py bdist --formats=wininst

(pure Python モジュールとパッケージだけの入った) pure モジュール 配布物の場合、作成されるインストーラは実行バージョンに依存しない 形式になり、 foo-1.0.win32.exe のような名前になります。 pure モジュールの Windows インストーラは Unix や MacOS といったプラットフォームでも作成できます。

非 pure 配布物の場合、拡張モジュールは Windows プラットフォーム上 だけで作成でき、Python のバージョンに依存したインストーラになります。 インストーラのファイル名もバージョン依存性を反映して、 foo-1.0.win32-py2.0.exe のような形式になります。 従って、サポートしたい全てのバージョンの Python に対して、 別々のインストーラを作成しなければなりません。

インストーラは、ターゲットとなるシステムにインストールを実行 した後、 pure モジュールを通常 (normal) モードと最適化 (optimizing) モードでコンパイルしようと試みます。何らかの理由があってコンパイル させたくなければ、bdist_wininst コマンドを --no-target-compile かつ/または --no-target-optimize オプション付きで実行します。

デフォルトでは、インストーラは実行時にクールな ``Python Powered'' ロゴを表示しますが、自作のビットマップ画像も指定できます。 画像は Windows の .bmp ファイル形式でなくてはならず、 --bitmap オプションで指定します。

インストーラを起動すると、デスクトップの背景ウィンドウ上にでっかい タイトルも表示します。タイトルは配布物の名前とバージョン番号から 作成します。--title オプションを使えば、 タイトルを別のテキストに変更できます。

インストーラファイルは ``配布物ディレクトリ (distribution directory)'' -- 通常は dist/ に作成されますが、--dist-dir オプションで指定することもできます。

6.3.1 インストール後実行スクリプト (postinstallation script)

Python 2.3 からは、インストール実行後スクリプトを --install-script オプションで指定できるように なりました。スクリプトはディレクトリを含まないベースネーム (basename) で指定しなければならず、スクリプトファイル名は setup 関数の scripts 引数中に挙げられていなければなりません。

指定したスクリプトは、インストール時、ターゲットとなるシステム上で 全てのファイルがコピーされた後に実行されます。このとき argv[1] を ``-install'' に設定します。また、アンインストール時には、 ファイルを削除する前に argv[1] を ``-remove'' に設定して 実行します。

Windows インストーラでは、インストールスクリプトは埋め込みで実行 され、全ての出力 (sys.stdout、 sys.stderr) はバッファにリダイレクト され、スクリプトの終了後に GUI 上に表示されます。

インストール後実行スクリプトでは、インストール/アンインストール のコンテキストで特に有用な機能をいくつか使えます。

directory_created(pathname)
file_created(pathname)

これらの関数は、インストール後実行スクリプトがディレクトリやファイル を作成した際に呼び出さなければなりません。この関数はアンインストーラ に作成されたパス名を登録し、配布物をアンインストールする際にファイルが 消されるようにします。安全を期すために、ディレクトリは空の時にのみ 削除されます。

get_special_folder_path(csidl_string)

この関数は、「スタートメニュー」や「デスクトップ」といった、 Windows における特殊なフォルダ位置を取得する際に使えます。 この関数はフォルダのフルパスを返します。 'csidl_string' は 以下の文字列のいずれかでなければなりません:

"CSIDL_APPDATA"

"CSIDL_COMMON_STARTMENU"
"CSIDL_STARTMENU"

"CSIDL_COMMON_DESKTOPDIRECTORY"
"CSIDL_DESKTOPDIRECTORY"

"CSIDL_COMMON_STARTUP"
"CSIDL_STARTUP"

"CSIDL_COMMON_PROGRAMS"
"CSIDL_PROGRAMS"

"CSIDL_FONTS"

該当するフォルダを取得できなかった場合、 OSError が送出されます。

どの種類のフォルダを取得できるかは、特定の Windows のバージョン ごとに異なります。また、おそらく設定によっても異なるでしょう。 詳細については、 SHGetSpecialFolderPath 関数に関する Microsoft の ドキュメントを参照してください。

create_shortcut(target, description, filename[, arguments[,
                workdir[, iconpath[, iconindex]]]])

この関数はショートカットを作成します。 target はショートカットによって起動されるプログラムへのパスです。 description はショートカットに対する説明です。 filename はユーザから見えるショートカットの名前です。 コマンドライン引数があれば、arguments に指定します。 workdir はプログラムの作業ディレクトリです。 iconpath はショートカットのためのアイコンが入ったファイルで、 iconindex はファイル iconpath 中のアイコンへのインデクス です。これについても、詳しくはIShellLink インタフェースに 関する Microsoft の ドキュメントを参照してください。

Previous Page Up One Level Next Page Python モジュールの配布
Previous: 5 ソースコード配布物を作成する Up: Python モジュールの配布 Next: 7 パッケージインデクスに登録する


7 パッケージインデクスに登録する

Python パッケージインデクス (Python Package Index, PyPI) は、 distutils でパッケージ化された配布物に関するメタデータを保持 しています。配布物のメタデータをインデクスに提出するには、 Distutils のコマンド register を使います。 register は以下のように起動します:

python setup.py register

Distutils は以下のようなプロンプトを出します:

running register
We need to know who you are, so please choose either:
 1. use your existing login,
 2. register as a new user,
 3. have the server generate a new password for you (and email it to you), or
 4. quit
Your selection [default 1]:

注意: ユーザ名とパスワードをローカルの計算機に保存しておくと、 このメニューは表示されません。

まだ PyPI に登録したことがなければ、まず登録する必要があります。 この場合選択肢 2 番を選び、リクエストされた詳細情報を入力して ゆきます。詳細情報を提出し終えると、登録情報の承認を行うための メールを受け取るはずです。

すでに登録を行ったことがあれば、選択肢 1 を選べます。この選択肢を 選ぶと、PyPI ユーザ名とパスワードを入力するよう促され、 register がメタデータをインデクスに自動的に提出します。

配布物の様々なバージョンについて、好きなだけインデクスへの提出 を行ってかまいません。特定のバージョンに関するメタデータを 入れ替えたければ、再度提出を行えば、インデクス上のデータが 更新されます。

PyPI は提出された配布物の (名前、バージョン) の各組み合わせについて 記録を保持しています。ある配布物名について最初に情報を提出したユーザが、 その配布物名のオーナ (owner) になります。オーナは register コマンドか、web インタフェースを介して変更を提出できます。 オーナは他のユーザをオーナやメンテナとして指名できます。 メンテナはパッケージ情報を編集できますが、他の人をオーナやメンテナに 指名することはできません。

デフォルトでは、 PyPI はあるパッケージについて全てのバージョンを 表示します。特定のバージョンを非表示にしたければ、パッケージの Hidden プロパティを yes に設定します。この値は web インタフェース で編集しなければなりません。

Previous Page Up One Level Next Page Python モジュールの配布
Previous: 6 ビルド済み配布物を作成する Up: Python モジュールの配布 Next: 8 例


8 例

8.1 pure Python 配布物 (モジュール形式)

単に二つのモジュール、特定のパッケージに属しないモジュールを 配布するだけなら、setup スクリプト中で py_modules オプションを使って個別に指定できます。

もっとも単純なケースでは、二つのファイル: setup スクリプト自体と、 配布したい単一のモジュール、この例では foo.py について 考えなければなりません:

<root>/
        setup.py
        foo.py

(この節の全ての図において、 <root> は配布物ルートディレクトリ を参照します。) この状況を扱うための最小の setup スクリプトは 以下のようになります:

from distutils.core import setup
setup(name = "foo", version = "1.0",
      py_modules = ["foo"])

配布物の名前は name オプションで個々に指定し、配布される モジュールの一つと配布物を同じ名前にする必要はないことに注意して ください (とはいえ、この命名方法はよいならわしでしょう)。 ただし、配布物名はファイル名を作成するときに使われるので、 文字、数字、アンダースコア、ハイフンだけで構成しなければなりません。

py_modules はリストなので、もちろん複数のモジュールを 指定できます。例えば、モジュール foo と bar を 配布しようとしているのなら、 setup スクリプトは以下のようになります:

<root>/
        setup.py
        foo.py
        bar.py

また、セットアップスクリプトは以下のようになります．

from distutils.core import setup
setup(name = "foobar", version = "1.0",
      py_modules = ["foo", "bar"])

モジュールのソースファイルは他のディレクトリに置けますが、 そうしなければならないようなモジュールを沢山持っているのなら、 モジュールを個別に列挙するよりもパッケージを指定した方が 簡単でしょう。

8.2 pure Python 配布物 (パッケージ形式)

二つ以上のモジュールを配布する場合、とりわけ二つのパッケージに 分かれている場合、おそらく個々のモジュールよりもパッケージ全体を 指定する方が簡単です。たとえモジュールがパッケージ内に入っていなくても 状況は同じで、その場合はルートパッケージにモジュールが入っていると Distutils に教えることができ、他のパッケージと同様にうまく処理されます (ただし、__init__.py があってはなりません)。

最後の例で挙げた setup スクリプトは、

from distutils.core import setup
setup(name = "foobar", version = "1.0",
      packages = [""])
のようにも書けます (空文字はルートパッケージを意味します)

これら二つのファイルをサブディレクトリ下に移動しておいて、 インストール先はルートパッケージのままにしておきたい、例えば:

<root>/
        setup.py
        src/      foo.py
                  bar.py
のような場合には、パッケージ名にはルートパッケージをそのまま 指定しておきますが、ルートパッケージに置くソースファイルが どこにあるかを Distutils に教えなければなりません:

from distutils.core import setup
setup(name = "foobar", version = "1.0",
      package_dir = {"": "src"},
      packages = [""])

もっと典型的なケースでは、複数のモジュールを同じパッケージ (またはサブパッケージ) に入れて配布しようと思うでしょう。 例えば、foo と bar モジュールがパッケージ foobar に属する場合、ソースツリーをレイアウトする 一案として、以下が考えられます。

<root>/
        setup.py
        foobar/
                 __init__.py
                 foo.py
                 bar.py

実際、 Distutils ではこれをデフォルトのレイアウトとして想定して いて、setup スクリプトを書く際にも最小限の作業しか必要ありません:

from distutils.core import setup
setup(name = "foobar", version = "1.0",
      packages = ["foobar"])

モジュールを入れるディレクトリをパッケージの名前にしたくない 場合、ここでも package_dir オプションを使う必要があります。 例えば、パッケージ foobar のモジュールが src に 入っているとします:

<root>/
        setup.py
        src/
                 __init__.py
                 foo.py
                 bar.py

適切な setup スクリプトは、

from distutils.core import setup
setup(name = "foobar", version = "1.0",
      package_dir = {"foobar" : "src"},
      packages = ["foobar"])
のようになるでしょう。

また、メインパッケージ内のモジュールを配布物ルート下に 置くことがあるかもしれません:

<root>/
        setup.py
        __init__.py
        foo.py
        bar.py

この場合、 setup スクリプトは

from distutils.core import setup
setup(name = "foobar", version = "1.0",
      package_dir = {"foobar" : ""},
      packages = ["foobar"])
のようになるでしょう。 (空文字列も現在のディレクトリを表します。)

サブパッケージがある場合、packages で 明示的に列挙しなければなりませんが、package_dir はサブパッケージへのパスを自動的に展開します。 (別の言い方をすれば、 Distutils はソースツリーを走査せず、 どのディレクトリが Python パッケージに相当するのかを __init__.py files. を探して調べようとします。) このようにして、デフォルトのレイアウトはサブパッケージ形式に 展開されます:

<root>/
        setup.py
        foobar/
                 __init__.py
                 foo.py
                 bar.py
                 subfoo/
                           __init__.py
                           blah.py

対応する setup スクリプトは以下のようになります。

from distutils.core import setup
setup(name = "foobar", version = "1.0",
      packages = ["foobar", "foobar.subfoo"])

(ここでも、package_dir を空文字列にすると現在のディレクトリ を表します。)

8.3 単体の拡張モジュール

拡張モジュールは、ext_modules オプションを使って指定します。 package_dir は、拡張モジュールのソースファイルをどこで 探すかには影響しません; pure Python モジュールのソースのみに影響します。 もっとも単純なケースでは、単一の C ソースファイルで書かれた単一の拡張 モジュールは:

<root>/
        setup.py
        foo.c
になります。

foo 拡張をルートパッケージ下に所属させたい場合、 setup スクリプトは

from distutils.core import setup
setup(name = "foobar", version = "1.0",
      ext_modules = [Extension("foo", ["foo.c"])])
になります。

同じソースツリーレイアウトで、この拡張モジュールを foopkg の下に置き、拡張モジュールの名前を変えるには:

from distutils.core import setup
setup(name = "foobar", version = "1.0",
      ext_modules = [Extension("foopkg.foo", ["foo.c"])])
のようにします。

Previous Page Up One Level Next Page Python モジュールの配布
Previous: 7 パッケージインデクスに登録する Up: Python モジュールの配布 Next: 9 リファレンスマニュアル


9 リファレンスマニュアル

9.1 モジュールをインストールする: install コマンド群

install コマンドは最初にビルドコマンドを実行済みに しておいてから、サブコマンド install_lib を実行します。 install_data and install_scripts.

9.1.1 install_data

このコマンドは配布物中に提供されている全てのデータファイルを インストールします。

9.1.2 install_scripts

このコマンドは配布物中の全ての (Python) スクリプトをインストール します。

9.2 ソースコード配布物を作成する: sdist command

Previous Page Up One Level Next Page Python モジュールの配布
Previous: 8 例 Up: Python モジュールの配布 Next: 10 distutils.sysconfig


10 distutils.sysconfig -- システム設定情報

distutils.sysconfig モジュールでは、 Python の低水準の 設定情報へのアクセス手段を提供しています。 どの設定情報変数にアクセスできるかは、プラットフォームと設定自体に 大きく左右されます。また、特定の変数は、使っている Python の バージョンに対するビルドプロセスに左右されます; こうした変数は、 Unix システムでは、Makefile や Python と一緒にインストール される設定ヘッダから探し出されます。 設定ファイルのヘッダは、2.2 以降のバージョンでは pyconfig.h 、それ以前のバージョンでは config.h です。

他にも、distutils パッケージの別の部分を操作 する上で便利な関数がいくつか提供されています。

PREFIX
os.path.normpath(sys.prefix) の結果です。

EXEC_PREFIX
os.path.normpath(sys.exec_prefix) の結果です。

get_config_var( name)
ある一つの設定変数に対する値を返します。 get_config_vars().get(name) と同じです。

get_config_vars( ...)
定義されている変数のセットを返します。引数を指定しなければ、 設定変数名を変数の値に対応付けるマップ型を返します。 引数を指定する場合、引数の各値は文字列でなければならず、戻り値は 引数に関連付けられた各設定変数の値からなる配列になります。 引数に指定した名前の設定変数に値がない場合、その変数値には None が入ります。

get_config_h_filename( )
設定ヘッダのフルパス名を返します。 Unixの場合、このヘッダファイルは configure スクリプトによって生成されるヘッダファイル名です; 他のプラットフォームでは、ヘッダは Python ソース配布物中で直接 与えられています。ファイルはプラットフォーム固有のテキストファイル です。

get_makefile_filename( )
Python をビルドする際に用いる Makefile のフルパスを返します。 Unixの場合、このファイルは configure スクリプトによって 生成されます; 他のプラットフォームでは、この関数の返す値の 意味は様々です。有意なファイル名を返す場合、ファイルは プラットフォーム固有のテキストファイル形式です。 この関数は POSIX プラットフォームでのみ有用です。

get_python_inc( [plat_specific[, prefix]])
C インクルードファイルディレクトリについて、一般的なディレクトリ名か、 プラットフォーム依存のディレクトリ名のいずれかを返します。 plat_specific が真であれば、プラットフォーム依存の インクルードディレクトリ名を返します; plat_specific が偽か、 省略された場合には、プラットフォームに依存しないディレクトリを 返します。 prefix が指定されていれば、PREFIX の代わりに用いられます。また、 plat_specific が真の場合、 EXEC_PREFIX の代わりに用いられます。

get_python_lib( [plat_specific[, standard_lib[, prefix]]])
ライブラリディレクトリについて、一般的なディレクトリ名か、 プラットフォーム依存のディレクトリ名のいずれかを返します。 plat_specific が真であれば、プラットフォーム依存の ライブラリディレクトリ名を返します; plat_specific が偽か、 省略された場合には、プラットフォームに依存しないディレクトリを 返します。prefix が指定されていれば、PREFIX の代わりに用いられます。また、 plat_specific が真の場合、 EXEC_PREFIX の代わりに用いられます。 standard_lib が真であれば、サードパーティ製の拡張モジュール をインストールするディレクトリの代わりに、標準ライブラリのディレクトリ を返します。

以下の関数は、distutils パッケージ内の使用だけを 前提にしています。

customize_compiler( compiler)
distutils.ccompiler.CCompiler インスタンスに対して、 プラットフォーム固有のカスタマイズを行います。

この関数は現在のところ、Unix だけで必要ですが、将来の互換性を 考慮して一貫して常に呼び出されます。この関数は様々な Unix の 変種ごとに異なる情報や、Python のMakefile に書かれた情報 をインスタンスに挿入します。この情報には、選択されたコンパイラや コンパイラ/リンカのオプション、そして共有オブジェクトを扱うために リンカに指定する拡張子が含まれます。

この関数はもっと特殊用途向けで、Python 自体のビルドプロセスで しか使われません。

set_python_build( )
distutils.sysconfig モジュールに、モジュールが Python の ビルドプロセスの一部として使われることを知らせます。これによって、 ファイルコピー先を示す相対位置が大幅に変更され、インストール済みの Python ではなく、ビルド作業領域にファイルが置かれるようになります。

Previous Page Up One Level Next Page Python モジュールの配布
Previous: 9 リファレンスマニュアル Up: Python モジュールの配布 Next: 11 日本語訳について


11 日本語訳について

11.1 このドキュメントについて

この文書は、Pythonドキュメント翻訳プロジェクトによる Distributing Python Modules の日本語訳版です。日本語訳に対する質問や提案などが ありましたら、Pythonドキュメント翻訳プロジェクトのメーリングリスト

http://www.python.jp/mailman/listinfo/python-doc-jp

または、プロジェクトのバグ管理ページ

http://sourceforge.jp/tracker/?atid=116&group_id=11&func=browse

までご報告ください。

11.2 翻訳者

2.3.3 和訳 Yasushi Masuda <y.masuda at acm.org> (March 12, 2004)

Previous Page Up One Level Next Page Python モジュールの配布
Previous: 10 distutils.sysconfig Up: Python モジュールの配布 Next: この文書について...


この文書について...

Python モジュールの配布

このドキュメントは、 LaTeX2HTML 変換ツールを 使って生成されています。

LaTeX2HTML の著作権は、 Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds, and Copyright © 1997, 1998, Ross Moore, Mathematics Department, Macquarie University, Sydney.
となっています。

Python ドキュメントの LaTeX2HTML への対応は、 Fred L. Drake, Jr. の多大な努力で実現しました。 オリジナルのナビゲーションアイコンは、 Christopher Petrilli によるものです。

Comments and Questions

General comments and questions regarding this document should be sent by email to docs@python.org. If you find specific errors in this document, either in the content or the presentation, please report the bug at the Python Bug Tracker at SourceForge.

Questions regarding how to use the information in this document should be sent to the Python news group, comp.lang.python, or the Python mailing list (which is gated to the newsgroup and carries the same content).

For any of these channels, please be sure not to send HTML email. Thanks.

和訳に関するコメントや質問について

本和訳プロジェクトは、少なくとも 2004 年 4 月の時点では、 Python 本体の開発プロジェクトや Python 国際化 SIG による 取り組みの一部では ありません 。 和訳の内容、和訳プロジェクトに関するご意見やご質問は、 これらのプロジェクトあてにお送りにならないようお願いします。

和訳ドキュメントに関する誤りのご指摘やご質問、コメントは、 SourceForge.jp の Python ドキュメント和訳プロジェクト バグトラッカ から お送りください。

Python でのプログラミングに関する疑問など、このドキュメントに 書かれている情報の使い方についての質問は、 日本 Python ユーザ会メーリングリスト で行うとよいでしょう。

Previous Page Up One Level Python モジュールの配布
Previous: 11 日本語訳について Up: Python モジュールの配布


Python ドキュメントについて

Python ドキュメントは、もともと Guido van Rossum 一人の手で 書かれたものですが、ここ数年ではだんだんと Python コミュニティ自体の 取り組みになってきています。まだまだ成長を続けているこの ドキュメント集は、様々な形式で利用でき、印刷向けにタイプセットされた PDF や PostScript のバージョンもあります。これらは Python Web サイト から入手できます。

貢献した人々の一覧です。

コメントや質問

ドキュメントに関する一般的なコメントや質問は、電子メールなら docs@python.org に送ってください。 ドキュメントに関して何か間違いを発見した場合には、 SourceForge.net の Python バグ追跡システムに報告してください。(訳注: 日本語ドキュメント に関するバグ報告は、 SourceForge.jp の Python ドキュメント 和訳プロジェクトのバグ追跡システム に報告してください。)

このドキュメントに書かれている情報の使い方に関する質問は、 Python のニュースグループ、 comp.lang.python、または Python メーリングリスト (ニュースグループと橋渡しされていて、 同じ情報が流れます) に送ってください。

上で挙げたチャネルではいずれも、決して HTML メールを送らない ようにしてください。よろしくお願いします。


Acknowledgements

These people have contributed in some way to the Python documentation. This list is probably not complete -- if you feel that you or anyone else should be on this list, please let us know (send email to docs@python.org), and we will be glad to correct the problem.

It is only with the input and contributions of the Python community that Python has such wonderful documentation -- Thank You!

Aahz | Ben Gertzfield | Detlef Lannert | Donald Wallace Rouse II
Michael Abbott | Nadim Ghaznavi | Piers Lauder | Nick Russo
Steve Alexander | Jonathan Giddy | Glyph Lefkowitz | Chris Ryland
Jim Ahlstrom | Shelley Gooch | Marc-André Lemburg | Constantina S.
Fred Allen | Nathaniel Gray | Ulf A. Lindgren | Hugh Sasse
A. Amoroso | Grant Griffin | Everett Lipman | Bob Savage
Pehr Anderson | Thomas Guettler | Mirko Liss | Scott Schram
Oliver Andrich | Anders Hammarquist | Martin von Löwis | Neil Schemenauer
Jesús Cea Avión | Mark Hammond | Fredrik Lundh | Barry Scott
Daniel Barclay | Harald Hanche-Olsen | Jeff MacDonald | Joakim Sernbrant
Chris Barker | Manus Hand | John Machin | Justin Sheehy
Don Bashford | Gerhard Häring | Andrew MacIntyre | Michael Simcich
Anthony Baxter | Travis B. Hartwell | Vladimir Marangozov | Ionel Simionescu
Bennett Benson | Janko Hauser | Vincent Marchetti | Roy Smith
Jonathan Black | Bernhard Herzog | Laura Matson | Clay Spence
Robin Boerdijk | Magnus L. Hetland | Daniel May | Nicholas Spies
Michal Bozon | Konrad Hinsen | Doug Mennella | Tage Stabell-Kulo
Aaron Brancotti | Stefan Hoffmeister | Paolo Milani | Frank Stajano
Keith Briggs | Albert Hofkamp | Skip Montanaro | Anthony Starks
Lee Busby | Gregor Hoffleit | Paul Moore | Greg Stein
Lorenzo M. Catucci | Steve Holden | Ross Moore | Peter Stoehr
Mauro Cicognini | Thomas Holenstein | Sjoerd Mullender | Mark Summerfield
Gilles Civario | Gerrit Holl | Dale Nagata | Reuben Sumner
Mike Clarkson | Rob Hooft | Ng Pheng Siong | Kalle Svensson
Steve Clift | Brian Hooper | Koray Oner | Jim Tittsler
Dave Cole | Randall Hopper | Tomas Oppelstrup | Ville Vainio
Matthew Cowles | Michael Hudson | Denis S. Otkidach | Martijn Vries
Jeremy Craven | Eric Huss | Zooko O'Whielacronx | Charles G. Waldman
Andrew Dalke | Jeremy Hylton | William Park | Greg Ward
Ben Darnell | Roger Irwin | Joonas Paalasmaa | Barry Warsaw
L. Peter Deutsch | Jack Jansen | Harri Pasanen | Corran Webster
Robert Donohue | Philip H. Jensen | Tim Peters | Glyn Webster
Fred L. Drake, Jr. | Pedro Diaz Jimenez | Christopher Petrilli | Bob Weiner
Jeff Epler | Lucas de Jonge | Justin D. Pettit | Eddy Welbourne
Michael Ernst | Andreas Jung | Chris Phoenix | Mats Wichmann
Blame Andy Eskilsson | Robert Kern | François Pinard | Gerry Wiener
Carey Evans | Jim Kerr | Paul Prescod | Timothy Wild
Martijn Faassen | Jan Kim | Eric S. Raymond | Blake Winton
Carl Feynman | Greg Kochanski | Edward K. Ream | Dan Wolfe
Hernán Martínez Foffani | Guido Kollerie | Sean Reifschneider | Steven Work
Stefan Franke | Peter A. Koren | Bernhard Reiter | Thomas Wouters
Jim Fulton | Daniel Kozan | Armin Rigo | Ka-Ping Yee
Peter Funk | Andrew M. Kuchling | Wes Rishel | Moshe Zadka
Lele Gaifax | Dave Kuhlman | Jim Roskind | Milan Zamazal
Matthew Gallagher | Erno Kuusela | Guido van Rossum | Cheng Zhang
up Acknowledgements
Up: Python Documentation Index
‚²ˆÓŒ©‚â‚²Žw“E‚ð‚¨Šñ‚¹‚É‚È‚è‚½‚¢•û‚ÍA ‚±‚ÌƒhƒLƒ…ƒƒ“ƒg‚É‚Â‚¢‚Ä... ‚ð‚²——‚‚¾‚³‚¢B


この文書について...

Python/C API リファレンスマニュアル, December 19, 2003, Release 2.3.3

このドキュメントは、 LaTeX2HTML 変換ツールを 使って生成されています。

LaTeX2HTML の著作権は、 Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds, and Copyright © 1997, 1998, Ross Moore, Mathematics Department, Macquarie University, Sydney.
となっています。

Python ドキュメントの LaTeX2HTML への対応は、 Fred L. Drake, Jr. の多大な努力で実現しました。 オリジナルのナビゲーションアイコンは、 Christopher Petrilli によるものです。

Comments and Questions

General comments and questions regarding this document should be sent by email to docs@python.org. If you find specific errors in this document, either in the content or the presentation, please report the bug at the Python Bug Tracker at SourceForge.

Questions regarding how to use the information in this document should be sent to the Python news group, comp.lang.python, or the Python mailing list (which is gated to the newsgroup and carries the same content).

For any of these channels, please be sure not to send HTML email. Thanks.

和訳に関するコメントや質問について

本和訳プロジェクトは、少なくとも 2004 年 4 月の時点では、 Python 本体の開発プロジェクトや Python 国際化 SIG による 取り組みの一部では ありません 。 和訳の内容、和訳プロジェクトに関するご意見やご質問は、 これらのプロジェクトあてにお送りにならないようお願いします。

和訳ドキュメントに関する誤りのご指摘やご質問、コメントは、 SourceForge.jp の Python ドキュメント和訳プロジェクト バグトラッカ から お送りください。

Python でのプログラミングに関する疑問など、このドキュメントに 書かれている情報の使い方についての質問は、 日本 Python ユーザ会メーリングリスト で行うとよいでしょう。

Previous Page Up One Level Python/C API リファレンスマニュアル Contents Index
Previous: 索引 Up: Python/C API リファレンスマニュアル
Release 2.3.3, documentation updated on December 19, 2003.


7.3.2.1 組み込み codec (built-in codec)

Python では、処理速度を高めるために C で書かれた一そろいの codec を提供しています。これらの codec は全て以下の関数を介して 直接利用できます。

以下の API の多くが、 encoding と errors という二つの 引数をとります。これらのパラメタは、組み込みの Unicode オブジェクト コンストラクタである unicode() における同名のパラメタと同じ セマンティクスになっています。

encoding を NULL にすると、デフォルトエンコーディング である ASCIIを使います。ファイルシステムに関する関数の呼び出し では、ファイル名に対するエンコーディングとして Py_FileSystemDefaultEncoding を使わねばなりません。 この変数は読み出し専用の変数として扱わねばなりません: この変数は、あるシステムによっては静的な文字列に対するポインタで あったり、また別のシステムでは、例えばアプリケーションが setlocale を読んだときなどに変わったりもします。

errors で指定するエラー処理もまた、 NULL を指定できます。 NULL を指定すると、codec で定義されているデフォルト処理の使用を 意味します。全ての組み込み codec で、デフォルトのエラー処理は ``strict'' (ValueError を送出する) になっています。

個々の codec は全て同様のインタフェースを使っています。個別の codec の説明では、説明を簡単にするために以下の汎用のインタフェースとの 違いだけを説明しています。

以下は汎用 codec の API です:

PyObject* PyUnicode_Decode( const char *s, int size, const char *encoding, const char *errors)
戻り値: 新たな参照.
何らかのエンコード方式でエンコードされた、 size バイトの 文字列 s をデコードして Unicode オブジェクトを生成します。 encoding と errors は、組み込み関数 unicode() の同名の パラメタと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_Encode( const Py_UNICODE *s, int size, const char *encoding, const char *errors)
戻り値: 新たな参照.
size で指定されたサイズの Py_UNICODE バッファを エンコードした Python 文字列オブジェクトを返します。 encoding および errors は Unicode 型の encode() メソッドに与える同名のパラメタと 同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsEncodedString( PyObject *unicode, const char *encoding, const char *errors)
戻り値: 新たな参照.
Unicode オブジェクトをエンコードし、その結果を Python 文字列 オブジェクトとして返します。encoding および errors は Unicode 型の encode() メソッドに与える同名のパラメタと 同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。

以下は UTF-8 codec の APIです:

PyObject* PyUnicode_DecodeUTF8( const char *s, int size, const char *errors)
戻り値: 新たな参照.
UTF-8 でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_EncodeUTF8( const Py_UNICODE *s, int size, const char *errors)
戻り値: 新たな参照.
size で指定された長さを持つ Py_UNICODE 型バッファを UTF-8 でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsUTF8String( PyObject *unicode)
戻り値: 新たな参照.
UTF-8 で Unicode オブジェクトをエンコードし、結果を Python 文字列 オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

以下は UTF-16 codec の APIです:

PyObject* PyUnicode_DecodeUTF16( const char *s, int size, const char *errors, int *byteorder)
戻り値: 新たな参照.
UTF-16 でエンコードされたバッファ s から size バイト デコードして、結果を Unicode オブジェクトで返します。 errors は (NULLでない場合) エラー処理方法を定義します。 デフォルト値は ``strict'' です。

byteorder が NULLでない場合、デコード機構は以下の ように指定されたバイト整列 (byte order) に従ってデコードを開始 します:

   *byteorder == -1: リトルエンディアン
   *byteorder == 0:  ネイティブ
   *byteorder == 1:  ビッグエンディアン

その後、入力データ中に見つかった全てのバイト整列マーカ (byte order mark, BOM) に従って、バイト整列を切り替えます。 BOM はデコード結果の Unicode 文字列中にはコピーされません。 デコードを完結した後、*byteorder は入力データの終点現在に おけるバイト整列に設定されます。

byteorder が NULLの場合、 codec はネイティブバイト整列の モードで開始します。

codec が例外を送出した場合にはNULL を返します。

PyObject* PyUnicode_EncodeUTF16( const Py_UNICODE *s, int size, const char *errors, int byteorder)
戻り値: 新たな参照.

s 中の Unicode データを UTF-16 でエンコードした結果が入っている Python 文字列オブジェクトを返します。 byteorder が 0 でない場合、出力は以下のバイト整列 指定に従って書き出されます:

   byteorder == -1: リトルエンディアン
   byteorder == 0:  ネイティブ (BOM マーカを書き出します)
   byteorder == 1:  ビッグエンディアン

バイトオーダが 0 の場合、出力結果となる文字列は常に Unicode BOM マーカ (U+FEFF) で始まります。それ以外のモードでは、 BOM マーカを頭につけません。

Py_UNICODE データは UCS-2 に縮小された UTF-16 として解釈 されることに注意してください。このトリックによって、API を傷つける ことなく、完全な UTF-16 機能を後で追加できます。

codec が例外を送出した場合にはNULL を返します。

PyObject* PyUnicode_AsUTF16String( PyObject *unicode)
戻り値: 新たな参照.
ネイティブバイトオーダの UTF-16 でエンコードされた Python 文字列を返します。 文字列は常に BOM マーカから始まります。エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

以下は ``Unicode Escape'' codec の APIです:

PyObject* PyUnicode_DecodeUnicodeEscape( const char *s, int size, const char *errors)
戻り値: 新たな参照.
Unicode-Escape でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_EncodeUnicodeEscape( const Py_UNICODE *s, int size, const char *errors)
戻り値: 新たな参照.
size で指定された長さを持つ Py_UNICODE 型バッファを Unicode-Escape でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsUnicodeEscapeString( PyObject *unicode)
戻り値: 新たな参照.
Unicode-Escape で Unicode オブジェクトをエンコードし、結果を Python 文字列オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

以下は ``Raw Unicode Escape'' codec の APIです:

PyObject* PyUnicode_DecodeRawUnicodeEscape( const char *s, int size, const char *errors)
戻り値: 新たな参照.
Raw-Unicode-Escape でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_EncodeRawUnicodeEscape( const Py_UNICODE *s, int size, const char *errors)
戻り値: 新たな参照.
size で指定された長さを持つ Py_UNICODE 型バッファを Raw-Unicode-Escape でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsRawUnicodeEscapeString( PyObject *unicode)
戻り値: 新たな参照.
Raw-Unicode-Escape で Unicode オブジェクトをエンコードし、結果を Python 文字列オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

以下は Latin-1 codec の APIです: Latin-1 は、 Unicode 序数の最初の 256 個に対応し、 エンコード時にはこの 256 個だけを受理します。

PyObject* PyUnicode_DecodeLatin1( const char *s, int size, const char *errors)
戻り値: 新たな参照.
Latin-1 でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_EncodeLatin1( const Py_UNICODE *s, int size, const char *errors)
戻り値: 新たな参照.
size で指定された長さを持つ Py_UNICODE 型バッファを Latin-1 でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsLatin1String( PyObject *unicode)
戻り値: 新たな参照.
Latin-1 で Unicode オブジェクトをエンコードし、結果を Python 文字列 オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

以下は ASCII codec の APIです: 7 ビットの ASCII データだけを受理します。その他のコードは エラーになります。

PyObject* PyUnicode_DecodeASCII( const char *s, int size, const char *errors)
戻り値: 新たな参照.
ASCII でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_EncodeASCII( const Py_UNICODE *s, int size, const char *errors)
戻り値: 新たな参照.
size で指定された長さを持つ Py_UNICODE 型バッファを ASCII でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsASCIIString( PyObject *unicode)
戻り値: 新たな参照.
ASCII で Unicode オブジェクトをエンコードし、結果を Python 文字列 オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

以下は mapping codec の APIです:

この codec は、多くの様々な codec を実装する際に使われるという点で 特殊な codec です (実際、encodings パッケージに入っている 標準 codecs のほとんどは、この codec を使っています)。 この codec は、文字のエンコードやデコードにマップ型 (mapping) を使います。

デコード用のマップ型は、文字列型の字列一組みを、 Unicode 型の字列一組、 整数 (Unicode 序数として解釈されます) または None ("定義されていない 対応付け(undefined mapping)" を意味し、エラーを引き起こします) の いずれかに対応付けなければなりません。

デコード用のマップ型は、Unicode 型の字列一組みを、 string 型の字列一組、 整数 (Latin-1 序数として解釈されます) または None ("定義されていない 対応付け(undefined mapping)" を意味し、エラーを引き起こします) の いずれかに対応付けなければなりません。

マップ型オブジェクトは、 __getitem__ マップ型インタフェース をサポートしなければなりません。

ある文字の検索が LookupError によって失敗すると、その文字は そのままコピーされます。すなわち、その文字の序数値がそれぞれ Unicode または Latin-1 として解釈されます。このため、codec を 実現するマップ型に入れる必要がある対応付け関係は、ある文字を別の コード点に対応付けるものだけです。

PyObject* PyUnicode_DecodeCharmap( const char *s, int size, PyObject *mapping, const char *errors)
戻り値: 新たな参照.

エンコードされた size バイトの文字列 s から mapping に指定されたオブジェクトを使って Unicode オブジェクトを 生成します。codec が例外を送出した場合にはNULL を返します。

PyObject* PyUnicode_EncodeCharmap( const Py_UNICODE *s, int size, PyObject *mapping, const char *errors)
戻り値: 新たな参照.
size で指定された長さを持つ Py_UNICODE 型バッファを mapping に指定されたオブジェクトを使ってエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsCharmapString( PyObject *unicode, PyObject *mapping)
戻り値: 新たな参照.
Unicode オブジェクトを mapping に指定されたオブジェクトを使って エンコードし、結果を Python 文字列オブジェクトとして返します。 エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

以下の codec API は Unicode から Unicode への対応付けを行う 特殊なものです。

PyObject* PyUnicode_TranslateCharmap( const Py_UNICODE *s, int size, PyObject *table, const char *errors)
戻り値: 新たな参照.
で 指定された長さを持つ Py_UNICODE バッファを、 文字変換マップ table を適用して変換し、変換結果を Unicode オブジェクトで返します。codec が例外を発行した場合には NULL を返します。

対応付けを行う table は、 Unicode 序数を表す整数を Unicode 序数を表す整数または None に対応付けます。 (None の場合にはその文字を削除します)

対応付けテーブルが提供する必要があるメソッドは __getitem__() インタフェースだけです; 従って、辞書や 配列型を使ってもうまく動作します。対応付けを行っていない (LookupError を起こすような) 文字序数に対しては、 変換は行わず、そのままコピーします。

以下は MBCS codec の API です。この codec は現在のところ、 Windows 上だけで利用でき、変換の実装には Win32 MBCS 変換機構 (Win32 MBCS converter) を使っています。 MBCS (または DBCS) はエンコード方式の種類 (class) を表す言葉で、単一の エンコード方式を表すわけでなないので注意してください。 利用されるエンコード方式 (target encoding) は、 codec を動作 させているマシン上のユーザ設定で定義されています。

PyObject* PyUnicode_DecodeMBCS( const char *s, int size, const char *errors)
戻り値: 新たな参照.
MBCS でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_EncodeMBCS( const Py_UNICODE *s, int size, const char *errors)
戻り値: 新たな参照.
size で指定された長さを持つ Py_UNICODE 型バッファを MBCS でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsMBCSString( PyObject *unicode)
戻り値: 新たな参照.
MBCS で Unicode オブジェクトをエンコードし、結果を Python 文字列 オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.3.2 Unicode オブジェクト (Unicode Up: 7.3.2 Unicode オブジェクト (Unicode Next: 7.3.2.2 メソッドおよびスロット関数 (slot function)
Release 2.3.3, documentation updated on December 19, 2003.


目次

  • 1. はじめに
    • 1.1 インクルードファイル
    • 1.2 オブジェクト、型および参照カウント
      • 1.2.1 参照カウント
      • 1.2.2 型
    • 1.3 例外
    • 1.4 Python の埋め込み
  • 2. 超高レベルレイヤ
  • 3. 参照カウント
  • 4. 例外処理
    • 4.1 標準例外
    • 4.2 文字列例外の廃止
  • 5. ユーティリティ関数
    • 5.1 オペレーティングシステム関連のユーティリティ
    • 5.2 プロセス制御
    • 5.3 モジュールの import
    • 5.4 データ整列化 (data marshalling) のサポート
    • 5.5 引数の解釈と値の構築
  • 6. 抽象オブジェクトレイヤ (abstract objects layer)
    • 6.1 オブジェクトプロトコル (object protocol)
    • 6.2 数値型プロトコル (number protocol)
    • 6.3 配列プロトコル (sequence protocol)
    • 6.4 マップ型プロトコル (mapping protocol)
    • 6.5 イテレータプロトコル (iterator protocol)
    • 6.6 バッファプロトコル (buffer protocol)
  • 7. 具象オブジェクト (concrete object) レイヤ
    • 7.1 基本オブジェクト (fundamental object)
      • 7.1.1 型オブジェクト (type object)
      • 7.1.2 None オブジェクト
    • 7.2 数値型オブジェクト (numeric object)
      • 7.2.1 (通常)整数型オブジェクト (plain integer object)
      • 7.2.2 長整数型オブジェクト (long integer object)
      • 7.2.3 浮動小数点型オブジェクト (floating point object)
      • 7.2.4 浮動小数点オブジェクト (complex number object)
    • 7.3 配列オブジェクト (sequence object)
      • 7.3.1 文字列オブジェクト (string object)
      • 7.3.2 Unicode オブジェクト (Unicode object)
      • 7.3.3 Buffer Objects
      • 7.3.4 タプルオブジェクト (tuple object)
      • 7.3.5 List Objects
    • 7.4 マップ型オブジェクト (mapping object)
      • 7.4.1 辞書オブジェクト (dictionary object)
    • 7.5 その他のオブジェクト
      • 7.5.1 ファイルオブジェクト (file object)
      • 7.5.2 インスタンスオブジェクト (instance object)
      • 7.5.3 メソッドオブジェクト (method object)
      • 7.5.4 モジュールオブジェクト (module object)
      • 7.5.5 イテレータオブジェクト (iterator object)
      • 7.5.6 デスクリプタオブジェクト (descriptor object)
      • 7.5.7 スライスオブジェクト (slice object)
      • 7.5.8 弱参照オブジェクト (weak reference object)
      • 7.5.9 Cオブジェクト (CObject)
      • 7.5.10 セルオブジェクト (cell object)
  • 8. 初期化 (initialization)、終了処理 (finalization)、スレッド
    • 8.1 スレッド状態 (thread state) とグローバルインタプリタロック (global interpreter lock)
    • 8.2 プロファイルとトレース (profiling and tracing)
    • 8.3 高度なデバッガサポート (advanced debugger support)
  • 9. メモリ管理
    • 9.1 概要
    • 9.2 メモリインタフェース
    • 9.3 例
  • 10. オブジェクト実装サポート (object implementation support)
    • 10.1 オブジェクトをヒープ上にメモリ確保する
    • 10.2 共通のオブジェクト構造体 (common object structure)
    • 10.3 型オブジェクト
    • 10.4 マップ型オブジェクト構造体 (mapping object structure)
    • 10.5 数値オブジェクト構造体 (number object structure)
    • 10.6 配列オブジェクト構造体 (sequence object structure)
    • 10.7 バッファオブジェクト構造体 (buffer object structure)
    • 10.8 イテレータプロトコルをサポートする
    • 10.9 循環参照ガベージコレクションをサポートする
  • A. バグ報告
  • B. 歴史とライセンス
    • B.1 History of the software
    • B.2 Terms and conditions for accessing or otherwise using Python
  • C. 日本語訳について
    • C.1 このドキュメントについて
    • C.2 翻訳者一覧 (敬称略)
  • 索引

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Index
Previous: 序 Up: Python/C API リファレンスマニュアル Next: 1. はじめに
Release 2.3.3, documentation updated on December 19, 2003.


序

Copyright © 2001, 2002, 2003 Python Software Foundation. All rights reserved.

Copyright © 2000 BeOpen.com. All rights reserved.

Copyright © 1995-2000 Corporation for National Research Initiatives. All rights reserved.

Copyright © 1991-1995 Stichting Mathematisch Centrum. All rights reserved.

Translation Copyright © 2003 Python Document Japanese Translation Project. All rights reserved.

ライセンスおよび許諾に関する完全な情報は、このドキュメントの末尾を 参照してください。

概要:

このマニュアルでは、拡張モジュールを書いたり Python インタプリタを アプリケーションに埋め込んだりしたい C および C++ プログラマ が利用できる API について述べています。 Extending and Embedding the Python Interpreter は拡張モジュールを書く際の一般的な決まりごとについて 記述していますが、API の詳細までは記述していないので、 このドキュメントが手引きになります。

警告: このドキュメントの現在のバージョンはまだ不完全です。 とはいえ、役に立つだろうと思います。引き続きドキュメントの整備を 継続して、 Python ソースコードのリリースとは別に、その時々で 新たなバージョンをリリースするつもりです。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: Python/C API リファレンスマニュアル Up: Python/C API リファレンスマニュアル Next: 目次
Release 2.3.3, documentation updated on December 19, 2003.


7.2.4.1 C 構造体としての複素数

複素数の C 構造体を引数として受理したり、戻り値として返したりする 関数は、ポインタ渡しを行うのではなく 値渡し を行うので 注意してください。これは API 全体を通して一貫しています。

Py_complex
Python 複素数オブジェクトの値の部分に対応する C の構造体です。 複素数オブジェクトを扱うほとんどの関数は、この型の構造体を 場合に応じて入力や出力として使います。構造体は以下のように 定義されています:

typedef struct {
   double real;
   double imag;
} Py_complex;

Py_complex _Py_c_sum( Py_complex left, Py_complex right)
二つの複素数の和を C の Py_complex 型で返します。

Py_complex _Py_c_diff( Py_complex left, Py_complex right)
二つの複素数の差を C の Py_complex 型で返します。

Py_complex _Py_c_neg( Py_complex complex)
複素数 complex の符号反転 C の Py_complex 型で返します。

Py_complex _Py_c_prod( Py_complex left, Py_complex right)
二つの複素数の積を C の Py_complex 型で返します。

Py_complex _Py_c_quot( Py_complex dividend, Py_complex divisor)
二つの複素数の商を C の Py_complex 型で返します。

Py_complex _Py_c_pow( Py_complex num, Py_complex exp)
指数 exp の num 乗を C の Py_complex 型で返します。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.2.4 浮動小数点オブジェクト (complex number Up: 7.2.4 浮動小数点オブジェクト (complex number Next: 7.2.4.2 Python オブジェクトとしての複素数型
Release 2.3.3, documentation updated on December 19, 2003.


7.2.4.2 Python オブジェクトとしての複素数型

PyComplexObject
この PyObject のサブタイプは Python の複素数オブジェクトを 表現します。
PyTypeObject PyComplex_Type
この PyTypeObject のインスタンスは Python の複素数型を表現します。

int PyComplex_Check( PyObject *p)
引数が PyComplexObject 型か PyComplexObject 型のサブタイプのときに真を返します。 バージョン2.2 以降で変更された 仕様: サブタイプを引数にとれるようになりました

int PyComplex_CheckExact( PyObject *p)
引数が PyComplexObject 型で、かつ PyComplexObject 型のサブタイプでないときに真を返します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* PyComplex_FromCComplex( Py_complex v)
戻り値: 新たな参照.
C の Py_complex 型から Python の複素数値を生成します。

PyObject* PyComplex_FromDoubles( double real, double imag)
戻り値: 新たな参照.
新たな PyComplexObject オブジェクトを real と imag から生成します。

double PyComplex_RealAsDouble( PyObject *op)
op の実数部分を C の double 型で返します。

double PyComplex_ImagAsDouble( PyObject *op)
op の虚数部分を C の double 型で返します。

Py_complex PyComplex_AsCComplex( PyObject *op)
複素数値 op から Py_complex 型を生成します。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.2.4.1 C 構造体としての複素数 Up: 7.2.4 浮動小数点オブジェクト (complex number Next: 7.3 配列オブジェクト (sequence object)
Release 2.3.3, documentation updated on December 19, 2003.


1.2.1.1 参照カウントの詳細

Python/C API の各関数における参照カウントの振る舞いは、 説明するには、参照の所有権 (ownership of references) という言葉でうまく説明できます。所有権は参照に対するもので、 オブジェクトに対するものではありません (オブジェクトは 誰にも所有されず、常に共有されています)。 ある参照の "所有" は、その参照が必要なくなった時点で Py_DECREF() を呼び出す役割を担うことを意味します。 所有権は委譲でき、あるコードが委譲によって所有権を得ると、 今度はそのコードが参照が必要なくなった際に最終的に Py_DECREF() や Py_XDECREF() を呼び出して decref する役割を担います -- あるいは、その役割を (通常はコードを 呼び出した元に) 受け渡します。 ある関数が、関数の呼び出し側に対して参照の所有権を渡すと、 呼び出し側は 新たな 参照 (new reference) を得る、と言います。 所有権が渡されない場合、呼び出し側は参照を借りる (borrow) といいます。借りた参照に対しては、何もする必要はありません。

逆に、ある関数呼び出しで、あるオブジェクトへの参照を呼び出される 関数に渡す際には、二つの可能性: 関数がオブジェクトへの参照を 盗み取る (steal) 場合と、そうでない場合があります。 参照を盗み取る関数はほとんどありません; 例外としてよく知られているのは、 PyList_SetItem()と PyTuple_SetItem()で、 これらは配列に入れる要素に対する参照を盗み取ります (しかし、要素の 入る先のタプルやリストの参照は盗み取りません!)。これらの関数は、 リストやタプルの中に新たに作成されたオブジェクトを入れていく際の 常套的な書き方をしやすくするために、参照を盗み取るように設計されて います; 例えば、(1, 2, "three") というタプルを生成するコードは 以下のようになります (とりあえず例外処理のことは忘れておきます; もっとよい書き方を後で示します):

PyObject *t;

t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
PyTuple_SetItem(t, 2, PyString_FromString("three"));

ちなみに、PyTuple_SetItem() はタプルに値をセットする ための 唯一の 方法です; タプルは変更不能なデータ型なので、 PySequence_SetItem() や PyObject_SetItem() を使うと上の操作は拒否されてしまいます。自分でタプルの値を入れていく つもりなら、PyTuple_SetItem() だけしか使えません。

同じく、リストに値を入れていくコードは PyList_New() と
PyList_SetItem() で書けます。このコードは
以下のように PySequence_SetItem() を使っても書けます;
これを見れば、二つの違い (Py_DECREF() を別に呼び出して
いる) が分かります:

PyObject *l, *x;

l = PyList_New(3);
x = PyInt_FromLong(1L);
PySequence_SetItem(l, 0, x); Py_DECREF(x);
x = PyInt_FromLong(2L);
PySequence_SetItem(l, 1, x); Py_DECREF(x);
x = PyString_FromString("three");
PySequence_SetItem(l, 2, x); Py_DECREF(x);

``推奨されている'' アプローチのほうが、コード量が多いので奇妙に 思うかもしれませんね。しかし実際には、タプルやリストを生成して 値を入れる際には、上記のような方法はほとんど使いません。 より汎用性のある関数、Py_BuildValue() があり、 ほとんどの主要なオブジェクトをフォーマット文字列 format string の指定に基づいて C の値から生成できます。例えば、 上の二種類のコードブロックは、以下のように置き換えられます (エラーチェックにも配慮しています):

PyObject *t, *l;

t = Py_BuildValue("(iis)", 1, 2, "three");
l = Py_BuildValue("[iis]", 1, 2, "three");

自作の関数に渡す引数のように、単に参照を借りるだけの要素に 対しては、PyObject_SetItem() とその仲間を 使うのがはるかに一般的です。 その場合、参照カウントをインクリメントする必要がなく、 参照を引き渡せる (``参照を盗み取らせられる'') ので、 参照カウントに関する動作はより健全になります。 例えば、以下の関数は与えられた要素をリスト中の全ての要素の値に セットします:

int
set_all(PyObject *target, PyObject *item)
{
    int i, n;

    n = PyObject_Length(target);
    if (n < 0)
        return -1;
    for (i = 0; i < n; i++) {
        if (PyObject_SetItem(target, i, item) < 0)
            return -1;
    }
    return 0;
}

関数の戻り値の場合には、状況は少し異なります。 ほとんどの関数については、参照を渡してもその参照に対する 所有権が変わることがない一方で、あるオブジェクトに対する参照を 返すような多くの関数は、参照に対する所有権を呼び出し側に与えます。 理由は簡単です: 多くの場合、関数が返すオブジェクトはその場で (on the fly) 生成されるため、呼び出し側が得る参照は生成された オブジェクトに対する唯一の参照になるからです。 従って、PyObject_GetItem() や PySequence_GetItem() のように、オブジェクトに対する 参照を返す汎用の関数は、常に新たな参照を返します (呼び出し側 が参照の所有者になります)。

重要なのは、関数が返す参照の所有権を持てるかどうかは、どの関数を 呼び出すかだけによる、と理解することです -- 関数呼び出し時の お飾り (関数に引数として渡したオブジェクトの型) は この問題には関係ありません! 従って、PyList_GetItem() を使ってリスト内の要素を 得た場合には、参照の所有者にはなりません -- が、同じ要素を 同じリストから PySequence_GetItem() (図らずもこの関数は 全く同じ引数をとります) を使って取り出すと、返されたオブジェクト に対する参照を得ます。

以下は、整数からなるリストに対して各要素の合計を計算する関数を どのようにして書けるかを示した例です; 一つは PyList_GetItem()を使っていて、 もう一つは PySequence_GetItem()を使っています。

long
sum_list(PyObject *list)
{
    int i, n;
    long total = 0;
    PyObject *item;

    n = PyList_Size(list);
    if (n < 0)
        return -1; /* リストではない */
    for (i = 0; i < n; i++) {
        item = PyList_GetItem(list, i); /* 失敗しないはず */
        if (!PyInt_Check(item)) continue; /* 整数でなければ読み飛ばす */
        total += PyInt_AsLong(item);
    }
    return total;
}

long
sum_sequence(PyObject *sequence)
{
    int i, n;
    long total = 0;
    PyObject *item;
    n = PySequence_Length(sequence);
    if (n < 0)
        return -1; /* 長さの概念がない */
    for (i = 0; i < n; i++) {
        item = PySequence_GetItem(sequence, i);
        if (item == NULL)
            return -1; /* 配列でないか、その他の失敗 */
        if (PyInt_Check(item))
            total += PyInt_AsLong(item);
        Py_DECREF(item); /* GetItem で得た所有権を放棄する */
    }
    return total;
}

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 1.2.1 参照カウント Up: 1.2.1 参照カウント Next: 1.2.2 型
Release 2.3.3, documentation updated on December 19, 2003.


typedef struct _typeobject {
    PyObject_VAR_HEAD
    char *tp_name; /* For printing, in format "<module>.<name>" */
    int tp_basicsize, tp_itemsize; /* For allocation */

    /* Methods to implement standard operations */

    destructor tp_dealloc;
    printfunc tp_print;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    cmpfunc tp_compare;
    reprfunc tp_repr;

    /* Method suites for standard classes */

    PyNumberMethods *tp_as_number;
    PySequenceMethods *tp_as_sequence;
    PyMappingMethods *tp_as_mapping;

    /* More standard operations (here for binary compatibility) */

    hashfunc tp_hash;
    ternaryfunc tp_call;
    reprfunc tp_str;
    getattrofunc tp_getattro;
    setattrofunc tp_setattro;

    /* Functions to access object as input/output buffer */
    PyBufferProcs *tp_as_buffer;

    /* Flags to define presence of optional/expanded features */
    long tp_flags;

    char *tp_doc; /* Documentation string */

    /* Assigned meaning in release 2.0 */
    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* Assigned meaning in release 2.1 */
    /* rich comparisons */
    richcmpfunc tp_richcompare;

    /* weak reference enabler */
    long tp_weaklistoffset;

    /* Added in release 2.2 */
    /* Iterators */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

    /* Attribute descriptor and subclassing stuff */
    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
    struct _typeobject *tp_base;
    PyObject *tp_dict;
    descrgetfunc tp_descr_get;
    descrsetfunc tp_descr_set;
    long tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Low-level free-memory routine */
    inquiry tp_is_gc; /* For PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* method resolution order */
    PyObject *tp_cache;
    PyObject *tp_subclasses;
    PyObject *tp_weaklist;

} PyTypeObject;


7.3.2.2 メソッドおよびスロット関数 (slot function)

以下の API は Unicode オブジェクトおよび文字列を入力に取り (説明では、どちらも文字列と表記しています)、場合に応じて Unicode オブジェクトか整数を返す機能を持っています。

これらの関数は全て、例外が発生した場合には NULL または -1 を返します。

PyObject* PyUnicode_Concat( PyObject *left, PyObject *right)
戻り値: 新たな参照.
二つの文字列を結合して、新たな Unicode 文字列を生成します。

PyObject* PyUnicode_Split( PyObject *s, PyObject *sep, int maxsplit)
戻り値: 新たな参照.
Unicode 文字列のリストを分割して、 Unicode 文字列からなるリスト を返します。 sep が NULLの場合、全ての空白文字を使って 分割を行います。それ以外の場合、指定された文字を使って分割を 行います。最大で maxsplit 個までの分割を行います。 maxsplit が負ならば分割数に制限を設けません。 分割結果のリスト内には分割文字は含みません。

PyObject* PyUnicode_Splitlines( PyObject *s, int keepend)
戻り値: 新たな参照.
Unicode 文字列を改行文字で区切り、Unicode 文字列からなるリスト を返します。CRLF は一個の改行文字とみなします。keepend が 0 の場合、分割結果のリスト内に改行文字を含めません。

PyObject* PyUnicode_Translate( PyObject *str, PyObject *table, const char *errors)
戻り値: 新たな参照.

文字列に文字変換マップ table を適用して変換し、変換結果を Unicode オブジェクトで返します。

対応付けを行う table は、 Unicode 序数を表す整数を Unicode 序数を表す整数または None に対応付けます。 (None の場合にはその文字を削除します)

対応付けテーブルが提供する必要があるメソッドは __getitem__() インタフェースだけです; 従って、辞書や 配列型を使ってもうまく動作します。対応付けを行っていない (LookupError を起こすような) 文字序数に対しては、 変換は行わず、そのままコピーします。

errors は codecs で通常使われるのと同じ意味を持ちます。 errors は NULL にしてもよく、デフォルトエラー処理の 使用を意味します。

PyObject* PyUnicode_Join( PyObject *separator, PyObject *seq)
戻り値: 新たな参照.
指定した separator で文字列からなる配列を連結 (join) し、 連結結果を Unicode 文字列で返します。

PyObject* PyUnicode_Tailmatch( PyObject *str, PyObject *substr, int start, int end, int direction)
戻り値: 新たな参照.
substr が指定された末尾条件 (direction == -1 は 前方一致、 direction ==1 は後方一致) で str[start:end] とマッチする場合に 1 を返し、 それ以外の場合には 0 を返します。

int PyUnicode_Find( PyObject *str, PyObject *substr, int start, int end, int direction)

str[start:end] 中にsubstr が最初に 出現する場所を返します。このとき指定された検索方向 direction (direction == 1 は順方向検索、 direction == -1 は 逆方向検索) で検索します。戻り値は最初にマッチが見つかった場所の インデクスです; 戻り値 -1 はマッチが見つからなかったことを 表し、-2 はエラーが発生して例外情報が設定されていることを 表します。

int PyUnicode_Count( PyObject *str, PyObject *substr, int start, int end)
str[start:end] に substr が重複することなく出現する回数を返します。 エラーが発生した場合には -1 を返します。

PyObject* PyUnicode_Replace( PyObject *str, PyObject *substr, PyObject *replstr, int maxcount)
戻り値: 新たな参照.
str 中に出現する substr を最大で maxcount 個 replstr に置換し、置換結果を Unicode オブジェクトにして 返します。 maxcount == -1 にすると、全ての substr を置換します。

int PyUnicode_Compare( PyObject *left, PyObject *right)
二つの文字列を比較して、左引数が右引数より小さい場合、 左右引数が等価の場合、左引数が右引数より大きい場合、について、 それぞれ -1, 0, 1 を返します。

PyObject* PyUnicode_Format( PyObject *format, PyObject *args)
戻り値: 新たな参照.
新たな文字列オブジェクトを format および args から 生成して返します; このメソッドは format % args のようなものです。引数 args はタプルでなくてはなりません。

int PyUnicode_Contains( PyObject *container, PyObject *element)
element が container 内にあるか調べ、その結果に応じて 真または偽を返します。

element は単要素の Unicode 文字に型強制できなければ なりません。エラーが生じた場合には -1 を返します。

Previous Page Up One Level Next Page Python/C API リファレンスマニュアル Contents Index
Previous: 7.3.2.1 組み込み codec (built-in Up: 7.3.2 Unicode オブジェクト (Unicode Next: 7.3.3 Buffer Objects
Release 2.3.3, documentation updated on December 19, 2003.


この文書について...

Python ドキュメントの作成

このドキュメントは、 LaTeX2HTML 変換ツールを 使って生成されています。

LaTeX2HTML の著作権は、 Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds, and Copyright © 1997, 1998, Ross Moore, Mathematics Department, Macquarie University, Sydney.
となっています。

Python ドキュメントの LaTeX2HTML への対応は、 Fred L. Drake, Jr. の多大な努力で実現しました。 オリジナルのナビゲーションアイコンは、 Christopher Petrilli によるものです。

Comments and Questions

General comments and questions regarding this document should be sent by email to docs@python.org. If you find specific errors in this document, either in the content or the presentation, please report the bug at the Python Bug Tracker at SourceForge.

Questions regarding how to use the information in this document should be sent to the Python news group, comp.lang.python, or the Python mailing list (which is gated to the newsgroup and carries the same content).

For any of these channels, please be sure not to send HTML email. Thanks.

和訳に関するコメントや質問について

本和訳プロジェクトは、少なくとも 2004 年 4 月の時点では、 Python 本体の開発プロジェクトや Python 国際化 SIG による 取り組みの一部では ありません 。 和訳の内容、和訳プロジェクトに関するご意見やご質問は、 これらのプロジェクトあてにお送りにならないようお願いします。

和訳ドキュメントに関する誤りのご指摘やご質問、コメントは、 SourceForge.jp の Python ドキュメント和訳プロジェクト バグトラッカ から お送りください。

Python でのプログラミングに関する疑問など、このドキュメントに 書かれている情報の使い方についての質問は、 日本 Python ユーザ会メーリングリスト で行うとよいでしょう。

Previous Page Up One Level Python ドキュメントの作成 Contents
Previous: A..2 翻訳者一覧 Up: Python ドキュメントの作成


目次

  • 1 初めに
  • 2 ディレクトリ構造
  • 3 スタイルガイド
  • 4 LATEX 入門
    • 4.1 構文法
    • 4.2 階層構造
  • 5 ドキュメントクラス
  • 6 特殊マークアップ構文
    • 6.1 プリアンブル用のマークアップ
    • 6.2 メタ情報マークアップ
    • 6.3 情報単位
    • 6.4 コードの例示
    • 6.5 インラインマークアップ
    • 6.6 雑多なテキストマークアップ
    • 6.7 モジュール特有のマークアップ
    • 6.8 ライブラリレベルのマークアップ
    • 6.9 表のマークアップ
    • 6.10 参考文献リストのマークアップ
    • 6.11 索引生成のためのマークアップ
    • 6.12 文法における導出の表示
    • 6.13 グラフィカルインタフェースの構成要素
  • 7 処理ツール
    • 7.1 外部ツール
    • 7.2 内部用ツール
    • 7.3 Cygwin での作業
  • 8 将来の方向性
    • 8.1 構造化ドキュメント
    • 8.2 議論の場
  • A. 日本語訳について
    • A..1 このドキュメントについて
    • A..2 翻訳者一覧

Previous Page Up One Level Next Page Python ドキュメントの作成
Previous: Python ドキュメントの作成 Up: Python ドキュメントの作成 Next: 1 初めに


この文書について...

Python インタプリタの拡張と埋め込み, 平成16年6月28日, Release 2.3.3

このドキュメントは、 LaTeX2HTML 変換ツールを 使って生成されています。

LaTeX2HTML の著作権は、 Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds, and Copyright © 1997, 1998, Ross Moore, Mathematics Department, Macquarie University, Sydney.
となっています。

Python ドキュメントの LaTeX2HTML への対応は、 Fred L. Drake, Jr. の多大な努力で実現しました。 オリジナルのナビゲーションアイコンは、 Christopher Petrilli によるものです。

Comments and Questions

General comments and questions regarding this document should be sent by email to docs@python.org. If you find specific errors in this document, either in the content or the presentation, please report the bug at the Python Bug Tracker at SourceForge.

Questions regarding how to use the information in this document should be sent to the Python news group, comp.lang.python, or the Python mailing list (which is gated to the newsgroup and carries the same content).

For any of these channels, please be sure not to send HTML email. Thanks.

和訳に関するコメントや質問について

本和訳プロジェクトは、少なくとも 2004 年 4 月の時点では、 Python 本体の開発プロジェクトや Python 国際化 SIG による 取り組みの一部では ありません 。 和訳の内容、和訳プロジェクトに関するご意見やご質問は、 これらのプロジェクトあてにお送りにならないようお願いします。

和訳ドキュメントに関する誤りのご指摘やご質問、コメントは、 SourceForge.jp の Python ドキュメント和訳プロジェクト バグトラッカ から お送りください。

Python でのプログラミングに関する疑問など、このドキュメントに 書かれている情報の使い方についての質問は、 日本 Python ユーザ会メーリングリスト で行うとよいでしょう。

Previous Page Up One Level Python インタプリタの拡張と埋め込み Contents
Previous: C.2 翻訳者一覧 (敬称略) Up: Python インタプリタの拡張と埋め込み


目次

  • 1. C や C++ による Python の拡張
    • 1.1 簡単な例
    • 1.2 幕間小話: エラーと例外
    • 1.3 例に戻る
    • 1.4 モジュールのメソッドテーブルと初期化関数
    • 1.5 コンパイルとリンク
    • 1.6 C から Python 関数を呼び出す
    • 1.7 拡張モジュール関数でのパラメタ展開
    • 1.8 拡張モジュール関数のキーワードパラメタ
    • 1.9 任意の値を構築する
    • 1.10 参照カウント法
      • 1.10.1 Python における参照カウント法
      • 1.10.2 所有権にまつわる規則
      • 1.10.3 薄氷
      • 1.10.4 NULL ポインタ
    • 1.11 C++での拡張モジュール作成
    • 1.12 拡張モジュールに C API を提供する
  • 2. 新しい型を定義する
    • 2.1 基本的なこと
      • 2.1.1 基本のサンプルにデータとメソッドを追加する
      • 2.1.2 データ属性をこまかく制御する
      • 2.1.3 循環ガベージコレクションをサポートする
    • 2.2 タイプメソッド
      • 2.2.1 最終化 (finalization) と解放
      • 2.2.2 Object Presentation
      • 2.2.3 属性を管理する
      • 2.2.4 オブジェクトの比較
      • 2.2.5 抽象的なプロトコルのサポート
      • 2.2.6 その他いろいろ
  • 3. distutils による C および C++ 拡張モジュールのビルド
    • 3.1 拡張モジュールの配布
  • 4. Windows 上での C および C++ 拡張モジュールのビルド
    • 4.1 型どおりのアプローチ
    • 4.2 Unix と Windows の相違点
    • 4.3 DLL 使用の実際
  • 5. 他のアプリケーションへの Python の埋め込み
    • 5.1 高水準の埋め込み
    • 5.2 超高水準の埋め込みから踏み出す: 概要
    • 5.3 純粋な埋め込み
    • 5.4 埋め込まれた Python の拡張
    • 5.5 C++による Python の埋め込み
    • 5.6 リンクに関する要件
  • A. バグ報告
  • B. 歴史とライセンス
    • B.1 History of the software
    • B.2 Terms and conditions for accessing or otherwise using Python
  • C. 日本語訳について
    • C.1 このドキュメントについて
    • C.2 翻訳者一覧 (敬称略)

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み
Previous: 序 Up: Python インタプリタの拡張と埋め込み Next: 1. C や C++


序

Copyright © 2001, 2002, 2003 Python Software Foundation. All rights reserved.

Copyright © 2000 BeOpen.com. All rights reserved.

Copyright © 1995-2000 Corporation for National Research Initiatives. All rights reserved.

Copyright © 1991-1995 Stichting Mathematisch Centrum. All rights reserved.

Translation Copyright © 2003 Python Document Japanese Translation Project. All rights reserved.

ライセンスおよび許諾に関する完全な情報は、このドキュメントの末尾を 参照してください。

概要:

Python はインタプリタ形式の、オブジェクト指向のプログラミング言語です。 このドキュメントでは、Python インタプリタを拡張するために C やC++ でモジュールを書く方法について述べます。 拡張モジュールでは、新たな関数を定義できるだけでなく、新たな オブジェクト型とそのメソッドも定義できます。 このドキュメントではまた、Python インタプリタを別のアプリケーションに 埋め込み (embedding)、拡張言語として使う方法についても述べます。 このドキュメントの最後には、オペレーティングシステム上で (実行時に) 動的に拡張モジュールをロードする機能がサポートされている場合に、 動的ロード可能な拡張モジュールをコンパイルしてリンクする方法を 示します。

このドキュメントでは、読者は Python について基礎的な知識を持ち合わせて いるものと仮定しています。形式ばらない Python 言語の入門には、 Python チュートリアル を読んでください。 Python リファレンスマニュアル を読めば、 Python 言語についてより形式的な定義を得られます。 また、 Python ライブラリリファレンス では、Python に広い適用範囲をもたらしている既存のオブジェクト型、関数、 および (組み込み、および Python で書かれたものの両方の) モジュール について解説しています。

Python/C API 全体の詳しい説明は、別のドキュメントである、 Python/C API リファレンスマニュアル を参照してください。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: Python インタプリタの拡張と埋め込み Up: Python インタプリタの拡張と埋め込み Next: 目次


#include <Python.h>

typedef struct {
    PyObject_HEAD
    /* Type-specific fields go here. */
} noddy_NoddyObject;

static PyTypeObject noddy_NoddyType = {
    PyObject_HEAD_INIT(NULL)
    0,                         /*ob_size*/
    "noddy.Noddy",             /*tp_name*/
    sizeof(noddy_NoddyObject), /*tp_basicsize*/
    0,                         /*tp_itemsize*/
    0,                         /*tp_dealloc*/
    0,                         /*tp_print*/
    0,                         /*tp_getattr*/
    0,                         /*tp_setattr*/
    0,                         /*tp_compare*/
    0,                         /*tp_repr*/
    0,                         /*tp_as_number*/
    0,                         /*tp_as_sequence*/
    0,                         /*tp_as_mapping*/
    0,                         /*tp_hash */
    0,                         /*tp_call*/
    0,                         /*tp_str*/
    0,                         /*tp_getattro*/
    0,                         /*tp_setattro*/
    0,                         /*tp_as_buffer*/
    Py_TPFLAGS_DEFAULT,        /*tp_flags*/
    "Noddy objects",           /* tp_doc */
};

static PyMethodDef noddy_methods[] = {
    {NULL}  /* Sentinel */
};

#ifndef PyMODINIT_FUNC	/* declarations for DLL import/export */
#define PyMODINIT_FUNC void
#endif
PyMODINIT_FUNC
initnoddy(void)
{
    PyObject* m;

    noddy_NoddyType.tp_new = PyType_GenericNew;
    if (PyType_Ready(&noddy_NoddyType) < 0)
        return;

    m = Py_InitModule3("noddy", noddy_methods,
                       "Example module that creates an extension type.");

    Py_INCREF(&noddy_NoddyType);
    PyModule_AddObject(m, "Noddy", (PyObject *)&noddy_NoddyType);
}


#include <Python.h>
#include "structmember.h"

typedef struct {
    PyObject_HEAD
    PyObject *first;
    PyObject *last;
    int number;
} Noddy;

static void
Noddy_dealloc(Noddy* self)
{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    self->ob_type->tp_free((PyObject*)self);
}

static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    Noddy *self;

    self = (Noddy *)type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyString_FromString("");
        if (self->first == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->last = PyString_FromString("");
        if (self->last == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->number = 0;
    }

    return (PyObject *)self;
}

static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
    PyObject *first=NULL, *last=NULL;

    static char *kwlist[] = {"first", "last", "number", NULL};

    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                      &first, &last,
                                      &self->number))
        return -1;

    if (first) {
        Py_XDECREF(self->first);
        Py_INCREF(first);
        self->first = first;
    }

    if (last) {
        Py_XDECREF(self->last);
        Py_INCREF(last);
        self->last = last;
    }

    return 0;
}

static PyMemberDef Noddy_members[] = {
    {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
     "first name"},
    {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
     "last name"},
    {"number", T_INT, offsetof(Noddy, number), 0,
     "noddy number"},
    {NULL}  /* Sentinel */
};

static PyObject *
Noddy_name(Noddy* self)
{
    static PyObject *format = NULL;
    PyObject *args, *result;

    if (format == NULL) {
        format = PyString_FromString("%s %s");
        if (format == NULL)
            return NULL;
    }

    if (self->first == NULL) {
        PyErr_SetString(PyExc_AttributeError, "first");
        return NULL;
    }

    if (self->last == NULL) {
        PyErr_SetString(PyExc_AttributeError, "last");
        return NULL;
    }

    args = Py_BuildValue("OO", self->first, self->last);
    if (args == NULL)
        return NULL;

    result = PyString_Format(format, args);
    Py_DECREF(args);

    return result;
}

static PyMethodDef Noddy_methods[] = {
    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

static PyTypeObject NoddyType = {
    PyObject_HEAD_INIT(NULL)
    0,                         /*ob_size*/
    "noddy.Noddy",             /*tp_name*/
    sizeof(Noddy),             /*tp_basicsize*/
    0,                         /*tp_itemsize*/
    (destructor)Noddy_dealloc, /*tp_dealloc*/
    0,                         /*tp_print*/
    0,                         /*tp_getattr*/
    0,                         /*tp_setattr*/
    0,                         /*tp_compare*/
    0,                         /*tp_repr*/
    0,                         /*tp_as_number*/
    0,                         /*tp_as_sequence*/
    0,                         /*tp_as_mapping*/
    0,                         /*tp_hash */
    0,                         /*tp_call*/
    0,                         /*tp_str*/
    0,                         /*tp_getattro*/
    0,                         /*tp_setattro*/
    0,                         /*tp_as_buffer*/
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
    "Noddy objects",           /* tp_doc */
    0,		               /* tp_traverse */
    0,		               /* tp_clear */
    0,		               /* tp_richcompare */
    0,		               /* tp_weaklistoffset */
    0,		               /* tp_iter */
    0,		               /* tp_iternext */
    Noddy_methods,             /* tp_methods */
    Noddy_members,             /* tp_members */
    0,                         /* tp_getset */
    0,                         /* tp_base */
    0,                         /* tp_dict */
    0,                         /* tp_descr_get */
    0,                         /* tp_descr_set */
    0,                         /* tp_dictoffset */
    (initproc)Noddy_init,      /* tp_init */
    0,                         /* tp_alloc */
    Noddy_new,                 /* tp_new */
};

static PyMethodDef module_methods[] = {
    {NULL}  /* Sentinel */
};

#ifndef PyMODINIT_FUNC	/* declarations for DLL import/export */
#define PyMODINIT_FUNC void
#endif
PyMODINIT_FUNC
initnoddy2(void)
{
    PyObject* m;

    if (PyType_Ready(&NoddyType) < 0)
        return;

    m = Py_InitModule3("noddy2", module_methods,
                       "Example module that creates an extension type.");

    if (m == NULL)
      return;

    Py_INCREF(&NoddyType);
    PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
}


#include <Python.h>
#include "structmember.h"

typedef struct {
    PyObject_HEAD
    PyObject *first;
    PyObject *last;
    int number;
} Noddy;

static void
Noddy_dealloc(Noddy* self)
{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    self->ob_type->tp_free((PyObject*)self);
}

static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    Noddy *self;

    self = (Noddy *)type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyString_FromString("");
        if (self->first == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->last = PyString_FromString("");
        if (self->last == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->number = 0;
    }

    return (PyObject *)self;
}

static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
    PyObject *first=NULL, *last=NULL;

    static char *kwlist[] = {"first", "last", "number", NULL};

    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                      &first, &last,
                                      &self->number))
        return -1;

    if (first) {
        Py_DECREF(self->first);
        Py_INCREF(first);
        self->first = first;
    }

    if (last) {
        Py_DECREF(self->last);
        Py_INCREF(last);
        self->last = last;
    }

    return 0;
}

static PyMemberDef Noddy_members[] = {
    {"number", T_INT, offsetof(Noddy, number), 0,
     "noddy number"},
    {NULL}  /* Sentinel */
};

static PyObject *
Noddy_getfirst(Noddy *self, void *closure)
{
    Py_INCREF(self->first);
    return self->first;
}

static int
Noddy_setfirst(Noddy *self, PyObject *value, void *closure)
{
  if (value == NULL) {
    PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
    return -1;
  }

  if (! PyString_Check(value)) {
    PyErr_SetString(PyExc_TypeError,
                    "The first attribute value must be a string");
    return -1;
  }

  Py_DECREF(self->first);
  Py_INCREF(value);
  self->first = value;

  return 0;
}

static PyObject *
Noddy_getlast(Noddy *self, void *closure)
{
    Py_INCREF(self->last);
    return self->last;
}

static int
Noddy_setlast(Noddy *self, PyObject *value, void *closure)
{
  if (value == NULL) {
    PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");
    return -1;
  }

  if (! PyString_Check(value)) {
    PyErr_SetString(PyExc_TypeError,
                    "The last attribute value must be a string");
    return -1;
  }

  Py_DECREF(self->last);
  Py_INCREF(value);
  self->last = value;

  return 0;
}

static PyGetSetDef Noddy_getseters[] = {
    {"first",
     (getter)Noddy_getfirst, (setter)Noddy_setfirst,
     "first name",
     NULL},
    {"last",
     (getter)Noddy_getlast, (setter)Noddy_setlast,
     "last name",
     NULL},
    {NULL}  /* Sentinel */
};

static PyObject *
Noddy_name(Noddy* self)
{
    static PyObject *format = NULL;
    PyObject *args, *result;

    if (format == NULL) {
        format = PyString_FromString("%s %s");
        if (format == NULL)
            return NULL;
    }

    args = Py_BuildValue("OO", self->first, self->last);
    if (args == NULL)
        return NULL;

    result = PyString_Format(format, args);
    Py_DECREF(args);

    return result;
}

static PyMethodDef Noddy_methods[] = {
    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

static PyTypeObject NoddyType = {
    PyObject_HEAD_INIT(NULL)
    0,                         /*ob_size*/
    "noddy.Noddy",             /*tp_name*/
    sizeof(Noddy),             /*tp_basicsize*/
    0,                         /*tp_itemsize*/
    (destructor)Noddy_dealloc, /*tp_dealloc*/
    0,                         /*tp_print*/
    0,                         /*tp_getattr*/
    0,                         /*tp_setattr*/
    0,                         /*tp_compare*/
    0,                         /*tp_repr*/
    0,                         /*tp_as_number*/
    0,                         /*tp_as_sequence*/
    0,                         /*tp_as_mapping*/
    0,                         /*tp_hash */
    0,                         /*tp_call*/
    0,                         /*tp_str*/
    0,                         /*tp_getattro*/
    0,                         /*tp_setattro*/
    0,                         /*tp_as_buffer*/
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
    "Noddy objects",           /* tp_doc */
    0,		               /* tp_traverse */
    0,		               /* tp_clear */
    0,		               /* tp_richcompare */
    0,		               /* tp_weaklistoffset */
    0,		               /* tp_iter */
    0,		               /* tp_iternext */
    Noddy_methods,             /* tp_methods */
    Noddy_members,             /* tp_members */
    Noddy_getseters,           /* tp_getset */
    0,                         /* tp_base */
    0,                         /* tp_dict */
    0,                         /* tp_descr_get */
    0,                         /* tp_descr_set */
    0,                         /* tp_dictoffset */
    (initproc)Noddy_init,      /* tp_init */
    0,                         /* tp_alloc */
    Noddy_new,                 /* tp_new */
};

static PyMethodDef module_methods[] = {
    {NULL}  /* Sentinel */
};

#ifndef PyMODINIT_FUNC	/* declarations for DLL import/export */
#define PyMODINIT_FUNC void
#endif
PyMODINIT_FUNC
initnoddy3(void)
{
    PyObject* m;

    if (PyType_Ready(&NoddyType) < 0)
        return;

    m = Py_InitModule3("noddy3", module_methods,
                       "Example module that creates an extension type.");

    if (m == NULL)
      return;

    Py_INCREF(&NoddyType);
    PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
}


#include <Python.h>
#include "structmember.h"

typedef struct {
    PyObject_HEAD
    PyObject *first;
    PyObject *last;
    int number;
} Noddy;

static int
Noddy_traverse(Noddy *self, visitproc visit, void *arg)
{
    if (self->first && visit(self->first, arg) < 0)
        return -1;
    if (self->last && visit(self->last, arg) < 0)
        return -1;

    return 0;
}

static int
Noddy_clear(Noddy *self)
{
    Py_XDECREF(self->first);
    self->first = NULL;
    Py_XDECREF(self->last);
    self->last = NULL;

    return 0;
}

static void
Noddy_dealloc(Noddy* self)
{
    Noddy_clear(self);
    self->ob_type->tp_free((PyObject*)self);
}

static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    Noddy *self;

    self = (Noddy *)type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyString_FromString("");
        if (self->first == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->last = PyString_FromString("");
        if (self->last == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->number = 0;
    }

    return (PyObject *)self;
}

static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
    PyObject *first=NULL, *last=NULL;

    static char *kwlist[] = {"first", "last", "number", NULL};

    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                      &first, &last,
                                      &self->number))
        return -1;

    if (first) {
        Py_XDECREF(self->first);
        Py_INCREF(first);
        self->first = first;
    }

    if (last) {
        Py_XDECREF(self->last);
        Py_INCREF(last);
        self->last = last;
    }

    return 0;
}

static PyMemberDef Noddy_members[] = {
    {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
     "first name"},
    {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
     "last name"},
    {"number", T_INT, offsetof(Noddy, number), 0,
     "noddy number"},
    {NULL}  /* Sentinel */
};

static PyObject *
Noddy_name(Noddy* self)
{
    static PyObject *format = NULL;
    PyObject *args, *result;

    if (format == NULL) {
        format = PyString_FromString("%s %s");
        if (format == NULL)
            return NULL;
    }

    if (self->first == NULL) {
        PyErr_SetString(PyExc_AttributeError, "first");
        return NULL;
    }

    if (self->last == NULL) {
        PyErr_SetString(PyExc_AttributeError, "last");
        return NULL;
    }

    args = Py_BuildValue("OO", self->first, self->last);
    if (args == NULL)
        return NULL;

    result = PyString_Format(format, args);
    Py_DECREF(args);

    return result;
}

static PyMethodDef Noddy_methods[] = {
    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

static PyTypeObject NoddyType = {
    PyObject_HEAD_INIT(NULL)
    0,                         /*ob_size*/
    "noddy.Noddy",             /*tp_name*/
    sizeof(Noddy),             /*tp_basicsize*/
    0,                         /*tp_itemsize*/
    (destructor)Noddy_dealloc, /*tp_dealloc*/
    0,                         /*tp_print*/
    0,                         /*tp_getattr*/
    0,                         /*tp_setattr*/
    0,                         /*tp_compare*/
    0,                         /*tp_repr*/
    0,                         /*tp_as_number*/
    0,                         /*tp_as_sequence*/
    0,                         /*tp_as_mapping*/
    0,                         /*tp_hash */
    0,                         /*tp_call*/
    0,                         /*tp_str*/
    0,                         /*tp_getattro*/
    0,                         /*tp_setattro*/
    0,                         /*tp_as_buffer*/
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /*tp_flags*/
    "Noddy objects",           /* tp_doc */
    (traverseproc)Noddy_traverse,   /* tp_traverse */
    (inquiry)Noddy_clear,           /* tp_clear */
    0,		               /* tp_richcompare */
    0,		               /* tp_weaklistoffset */
    0,		               /* tp_iter */
    0,		               /* tp_iternext */
    Noddy_methods,             /* tp_methods */
    Noddy_members,             /* tp_members */
    0,                         /* tp_getset */
    0,                         /* tp_base */
    0,                         /* tp_dict */
    0,                         /* tp_descr_get */
    0,                         /* tp_descr_set */
    0,                         /* tp_dictoffset */
    (initproc)Noddy_init,      /* tp_init */
    0,                         /* tp_alloc */
    Noddy_new,                 /* tp_new */
};

static PyMethodDef module_methods[] = {
    {NULL}  /* Sentinel */
};

#ifndef PyMODINIT_FUNC	/* declarations for DLL import/export */
#define PyMODINIT_FUNC void
#endif
PyMODINIT_FUNC
initnoddy4(void)
{
    PyObject* m;

    if (PyType_Ready(&NoddyType) < 0)
        return;

    m = Py_InitModule3("noddy4", module_methods,
                       "Example module that creates an extension type.");

    if (m == NULL)
      return;

    Py_INCREF(&NoddyType);
    PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
}


2.2.3.1 総称的な属性を管理する

バージョン2.2 以降で新規追加された 仕様です。

ほとんどの型は単純な属性を使うだけです。では、 どのような属性が単純だといえるのでしょうか? それが満たすべき条件はごくわずかです:

  1. PyType_Ready() が呼ばれたとき、すでに 属性の名前がわかっていること。

  2. 属性を参照したり設定したりするときに、特別な 記録のための処理が必要でなく、また参照したり設定した値に対して どんな操作も実行する必要がないこと。

これらの条件は、属性の値や、値が計算されるタイミング、 または格納されたデータがどの程度妥当なものであるかといったことに なんら制約を課すものではないことに注意してください。

PyType_Ready() が呼ばれると、これはそのタイプオブジェクトに 参照されている 3つのテーブルを使って、そのタイプオブジェクトの辞書中に デスクリプタ を作成します。各デスクリプタは、インスタンスオブジェクトの属性に 対するアクセスを制御します。それぞれのテーブルはなくてもかまいません。 もしこれら 3つがすべて NULLだと、その型のインスタンスはその基底型から 継承した属性だけを持つことになります。また、tp_getattro および tp_setattro が NULL のままだった場合も、 基底型にこれらの属性の操作がまかせられます。

テーブルはタイプオブジェクト中の 3つのメンバとして宣言されています:

    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;

tp_methods が NULLでない場合、 これは PyMethodDef 構造体への配列を指している必要があります。 テーブル中の各エントリは、つぎのような構造体のインスタンスです:

typedef struct PyMethodDef {
    char        *ml_name;       /* メソッド名 */
    PyCFunction  ml_meth;       /* 実装する関数 */
    int	         ml_flags;      /* フラグ */
    char        *ml_doc;        /* docstring */
} PyMethodDef;

その型が提供する各メソッドについてひとつのエントリを定義する必要があります。 基底型から継承してきたメソッドについてはエントリは必要ありません。 これの最後には、配列の終わりを示すための見張り番 (sentinel) として 追加のエントリがひとつ必要です。この場合、ml_name メンバが sentinel として使われ、 その値は NULLでなければなりません。

2番目のテーブルは、インスタンス中に格納されるデータと直接対応づけられた属性を 定義するのに使います。いくつもの C の原始的な型がサポートされており、 アクセスを読み込み専用にも読み書き可能にもできます。 このテーブルで使われる構造体は次のように定義されています:

typedef struct PyMemberDef {
    char *name;
    int   type;
    int   offset;
    int   flags;
    char *doc;
} PyMemberDef;

このテーブルの各エントリに対してデスクリプタが作成され、 値をインスタンスの構造体から抽出しうる型に対してそれらが追加されます。 type メンバは structmember.h ヘッダで定義された 型のコードをひとつ含んでいる必要があります。この値は Python における 値と C における値をどのように変換しあうかを定めるものです。 flags メンバはこの属性がどのようにアクセスされるかを制御する フラグを格納するのに使われます。

以下のフラグ用定数は structmember.h で定義されており、 これらはビットごとの OR を取って組み合わせられます。

Constant | Meaning
READONLY | 絶対に変更できない。
RO | READONLY の短縮形。
READ_RESTRICTED | 制限モード (restricted mode) では参照できない。
WRITE_RESTRICTED | 制限モード (restricted mode) では変更できない。
RESTRICTED | 制限モード (restricted mode) では参照も変更もできない。

tp_members を使ったひとつの面白い利用法は、実行時に使われる デスクリプタを作成しておき、単にテーブル中にテキストを置いておくことによって、 この方法で定義されるどの属性は対応した docstring を持つことができるように することです。 アプリケーションはこのイントロスペクション用 API を使って、 クラスオブジェクトからデスクリプタを取り出し、その __doc__ 属性を 使って docstring を得られます。

tp_methods テーブルと同じように、ここでも name メンバの値を NULL にした見張り用エントリが必要です。

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 2.2.3 属性を管理する Up: 2.2.3 属性を管理する Next: 2.2.3.2 特定の型に特化した属性の管理


2.2.3.2 特定の型に特化した属性の管理

話を単純にするため、ここでは char* を使ったバージョンのみを 示します。name パラメータの型はインターフェイスとして char* を使うか PyObject* を使うかの違いしかありません。 この例では、上の総称的な例と同じことを効率的にやりますが、 Python 2.2 で追加された総称的な型のサポートを使わずにやります。 これを紹介することは 2つの意味をもっています。ひとつはどうやって、 古いバージョンの Python と互換性のあるやり方で、基本的な属性管理を おこなうか。そしてもうひとつはハンドラの関数がどのようにして呼ばれるのか。 これで、たとえその機能を拡張する必要があるとき、何をどうすればいいか わかるでしょう。

tp_getattr ハンドラはオブジェクトが属性への参照を要求するときに 呼ばれます。 これは、そのクラスの __getattr__() メソッドが呼ばれるであろう状況と 同じ状況下で呼び出されます。

これを処理するありがちな方法は、(1) 一連の関数 (下の例の newdatatype_getSize() や newdatatype_setSize()) を実装する、(2) これらの関数を記録したメソッドテーブルを提供する、 そして (3) そのテーブルの参照結果を返す getattr 関数を提供することです。 メソッドテーブルはタイプオブジェクトの tp_methods メンバと 同じ構造を持っています。

以下に例を示します:

static PyMethodDef newdatatype_methods[] = {
    {"getSize", (PyCFunction)newdatatype_getSize, METH_VARARGS,
     "Return the current size."},
    {"setSize", (PyCFunction)newdatatype_setSize, METH_VARARGS,
     "Set the size."},
    {NULL, NULL, 0, NULL}           /* 見張り */
};

static PyObject *
newdatatype_getattr(newdatatypeobject *obj, char *name)
{
    return Py_FindMethod(newdatatype_methods, (PyObject *)obj, name);
}

tp_setattr ハンドラは、クラスのインスタンスの __setattr__() または __delattr__() メソッドが呼ばれるであろう 状況で呼び出されます。ある属性が削除されるとき、3番目のパラメータは NULLに なります。以下の例はたんに例外を発生させるものですが、もし本当にこれと 同じことをしたいなら、tp_setattr ハンドラを NULLに設定すべきです。

static int
newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
{
    (void)PyErr_Format(PyExc_RuntimeError, "Read-only attribute: \%s", name);
    return -1;
}

Previous Page Up One Level Next Page Python インタプリタの拡張と埋め込み Contents
Previous: 2.2.3.1 総称的な属性を管理する Up: 2.2.3 属性を管理する Next: 2.2.4 オブジェクトの比較


#include <Python.h>

int
main(int argc, char *argv[])
{
    PyObject *pName, *pModule, *pDict, *pFunc;
    PyObject *pArgs, *pValue;
    int i;

    if (argc < 3) {
        fprintf(stderr,"Usage: call pythonfile funcname [args]\n");
        return 1;
    }

    Py_Initialize();
    pName = PyString_FromString(argv[1]);
    /* Error checking of pName left out */

    pModule = PyImport_Import(pName);
    Py_DECREF(pName);

    if (pModule != NULL) {
        pDict = PyModule_GetDict(pModule);
        /* pDict is a borrowed reference */

        pFunc = PyDict_GetItemString(pDict, argv[2]);
        /* pFun: Borrowed reference */

        if (pFunc && PyCallable_Check(pFunc)) {
            pArgs = PyTuple_New(argc - 3);
            for (i = 0; i < argc - 3; ++i) {
                pValue = PyInt_FromLong(atoi(argv[i + 3]));
                if (!pValue) {
                    Py_DECREF(pArgs);
                    Py_DECREF(pModule);
                    fprintf(stderr, "Cannot convert argument\n");
                    return 1;
                }
                /* pValue reference stolen here: */
                PyTuple_SetItem(pArgs, i, pValue);
            }
            pValue = PyObject_CallObject(pFunc, pArgs);
            Py_DECREF(pArgs);
            if (pValue != NULL) {
                printf("Result of call: %ld\n", PyInt_AsLong(pValue));
                Py_DECREF(pValue);
            }
            else {
                Py_DECREF(pModule);
                PyErr_Print();
                fprintf(stderr,"Call failed\n");
                return 1;
            }
            /* pDict and pFunc are borrowed and must not be Py_DECREF-ed */
        }
        else {
            if (PyErr_Occurred())
                PyErr_Print();
            fprintf(stderr, "Cannot find function \"%s\"\n", argv[2]);
        }
        Py_DECREF(pModule);
    }
    else {
        PyErr_Print();
        fprintf(stderr, "Failed to load \"%s\"\n", argv[1]);
        return 1;
    }
    Py_Finalize();
    return 0;
}


この文書について...

Python ライブラリリファレンス, 平成16年6月28日, Release 2.3.3

このドキュメントは、 LaTeX2HTML 変換ツールを 使って生成されています。

LaTeX2HTML の著作権は、 Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds, and Copyright © 1997, 1998, Ross Moore, Mathematics Department, Macquarie University, Sydney.
となっています。

Python ドキュメントの LaTeX2HTML への対応は、 Fred L. Drake, Jr. の多大な努力で実現しました。 オリジナルのナビゲーションアイコンは、 Christopher Petrilli によるものです。

Comments and Questions

General comments and questions regarding this document should be sent by email to docs@python.org. If you find specific errors in this document, either in the content or the presentation, please report the bug at the Python Bug Tracker at SourceForge.

Questions regarding how to use the information in this document should be sent to the Python news group, comp.lang.python, or the Python mailing list (which is gated to the newsgroup and carries the same content).

For any of these channels, please be sure not to send HTML email. Thanks.

和訳に関するコメントや質問について

本和訳プロジェクトは、少なくとも 2004 年 4 月の時点では、 Python 本体の開発プロジェクトや Python 国際化 SIG による 取り組みの一部では ありません 。 和訳の内容、和訳プロジェクトに関するご意見やご質問は、 これらのプロジェクトあてにお送りにならないようお願いします。

和訳ドキュメントに関する誤りのご指摘やご質問、コメントは、 SourceForge.jp の Python ドキュメント和訳プロジェクト バグトラッカ から お送りください。

Python でのプログラミングに関する疑問など、このドキュメントに 書かれている情報の使い方についての質問は、 日本 Python ユーザ会メーリングリスト で行うとよいでしょう。

Previous Page Up One Level Python ライブラリリファレンス Contents Module Index Index
Previous: 索引 Up: Python ライブラリリファレンス


2.3.4.1 整数型におけるビット文字列演算

通常および長整数型ではさらに、ビット文字列に対してのみ意味のある 演算をサポートしています。負の数はその値の 2 の補数の値として扱われます (長整数の場合、演算操作中にオーバフローが起こらないように十分なビット数 があるものと仮定します) 。

2 進のビット単位演算は全て、数値演算よりも低く、比較演算子よりも高い 優先度です; 単項演算 " " は他の単項数値演算 ("+" および "-") と同じ優先度です。

以下のテーブルでは、ビット文字列演算を優先度の低いものから順に並べています (同じボックス内の演算は同じ優先度です):

演算 | 結果 | 注釈
x | y | ビット単位の x と y の 論理和 |
x ^ y | ビット単位の x と y の 排他的論理和 |
x & y | ビット単位の x と y の 論理積 |
x « n | x の n ビット左シフト | (1), (2)
x » n | x の n ビット右シフト | (1), (3)
~x | x のビット反転 |

注釈:

(1)
負値のシフト数は不正であり、ValueError が送出 されます。
(2)
n ビットの左シフトは、オーバフローチェックを行わない pow(2, n) による乗算と等価です。
(3)
n ビットの右シフトは、オーバフローチェックを行わない pow(2, n) による除算と等価です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.4 数値型 Up: 2.3.4 数値型 Next: 2.3.5 イテレータ型


2.3.9.5 コードオブジェクト

コードオブジェクトは、関数本体のような ``擬似コンパイルされた'' Python の実行可能コードを表すために実装系によって使われます。 コードオブジェクトはグローバルな実行環境への参照を持たない点で 関数オブジェクトとは異なります。コードオブジェクトは 組み込み関数 compile() によって返され、関数オブジェクト の func_code 属性として取り出すことができます。

コードオブジェクトは exec 文や組み込み関数 eval() に(ソースコード文字列の代わりに) 渡すことで、実行したり値評価したり することができます。

詳しくは Python リファレンスマニュアル を読んで下さい。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.9.4 メソッド Up: 2.3.9 他の組み込み型 Next: 2.3.9.6 型オブジェクト


2.3.9.8 省略表記オブジェクト

このオブジェクトは拡張スライス表記によって使われます (Python Reference Manual を参照して ください)。特殊な操作は何もサポートしていません。省略表記オブジェクト は一つだけで、その名前は Ellipsis (組み込み名) です。

Ellipsis と書き表されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.9.7 ヌルオブジェクト Up: 2.3.9 他の組み込み型 Next: 2.3.9.9 ブール値


2.3.9.7 ヌルオブジェクト

このオブジェクトは明示的に値を返さない関数によって返されます。 このオブジェクトには特有の操作はありません。ヌルオブジェクト は一つだけで、None (組み込み名) と名づけられています。

None と書き表されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.9.6 型オブジェクト Up: 2.3.9 他の組み込み型 Next: 2.3.9.8 省略表記オブジェクト


2.3.9.6 型オブジェクト

型オブジェクトは様々なオブジェクト型を表します。オブジェクトの型は 組み込み関数 type() でアクセスされます。型オブジェクトには 特有の操作はありません。標準モジュール types には全ての 組み込み型名が定義されています。

型は <type 'int'> のように書き表されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.9.5 コードオブジェクト Up: 2.3.9 他の組み込み型 Next: 2.3.9.7 ヌルオブジェクト


from optparse import Option, OptionParser, _match_abbrev

# This case-insensitive option parser relies on having a
# case-insensitive dictionary type available.  Here's one
# for Python 2.2.  Note that a *real* case-insensitive
# dictionary type would also have to implement __new__(),
# update(), and setdefault() -- but that's not the point
# of this exercise.

class caseless_dict (dict):
    def __setitem__ (self, key, value):
        dict.__setitem__(self, key.lower(), value)

    def __getitem__ (self, key):
        return dict.__getitem__(self, key.lower())

    def get (self, key, default=None):
        return dict.get(self, key.lower())

    def has_key (self, key):
        return dict.has_key(self, key.lower())

class CaselessOptionParser (OptionParser):

    def _create_option_list (self):
        self.option_list = []
        self._short_opt = caseless_dict()
        self._long_opt = caseless_dict()
        self._long_opts = []
        self.defaults = {}

    def _match_long_opt (self, opt):
        return _match_abbrev(opt.lower(), self._long_opt.keys())

if __name__ == "__main__":
    from optik.errors import OptionConflictError

    # test 1: no options to start with
    parser = CaselessOptionParser()
    try:
        parser.add_option("-H", dest="blah")
    except OptionConflictError:
        print "ok: got OptionConflictError for -H"
    else:
        print "not ok: no conflict between -h and -H"

    parser.add_option("-f", "--file", dest="file")
    #print `parser.get_option("-f")`
    #print `parser.get_option("-F")`
    #print `parser.get_option("--file")`
    #print `parser.get_option("--fIlE")`
    (options, args) = parser.parse_args(["--FiLe", "foo"])
    assert options.file == "foo", options.file
    print "ok: case insensitive long options work"

    (options, args) = parser.parse_args(["-F", "bar"])
    assert options.file == "bar", options.file
    print "ok: case insensitive short options work"


4.9.1.1 Codec オブジェクト

Codec クラスは以下のメソッドを定義します。これらのメソッドは、状 態を保持しないエンコーダとデコーダ関数のインターフェイスを定義します。

encode( input[, errors])
オブジェクト input エンコードし、(出力 オブジェクト, 消費した 長 さ) のタプルを返します。codecs は Unicode 専用で はありませんが、 Unicode の文脈では、エンコーディングは Unicode オブ ジェクトを、特定 の 文字集合エンコーディング（たとえば cp1252 や iso-8859-1） を使って文字 列オブジェクトに変換します。

errors は適用するエラー処理を定義します。'strict' 処理が デフォルトです。

このメソッドは Codec の状態を保持しなくてかまいません。 効率 よくエンコード／デコードするために、状態を保持しなければならない codecs には StreamCodec を使いましょう。

エンコーダは長さが0の入力を受け付け、その場合には、空のオブジェクトを 出力オブジェクトとして返す必要があります。

decode( input[, errors])
オブジェクト input をデコードし、(出力オブジェクト, 消費した長 さ) のタプルを返します。Unicode の文脈では、デコードは特定の 文字集合 エンコーディングでエンコードされた文字列を Unicode オブジェクトに変換 します。

input は bf_getreadbuf バッファスロットを提供するオブジェ クトでなければいけません。Python 文字列オブジェクト、バッファオブジェ クト、メモリにマップされたファイルが、バッファスロットの例です。

errors は適用するエラー処理を定義します。'strict' がデフ ォルト値です。

このメソッドは、Codec インスタンス内部の状態を保持しなくてもか まいません。効率よくエンコード／デコードするために、状態を保持しなけれ ばならない codecs には StreamCodec を使いましょう。

エンコーダは長さが0の入力を受け付け、その場合には、空のオブジェクトを 出力オブジェクトとして返す必要があります。

StreamWriter と StreamReader クラスは、新しいエンコーデ ィングモジュールを、非常に簡単に実装するのに使用できる、一般的なインターフ ェイス提供します。実装例は encodings.utf_8 をご覧ください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.9.1 Codec 基底クラス Up: 4.9.1 Codec 基底クラス Next: 4.9.1.2 StreamWriter オブジェクト


目次

  • 1. はじめに
  • 2. 組み込みオブジェクト
    • 2.1 組み込み関数
    • 2.2 非必須組み込み関数 (Non-essential Built-in Functions)
    • 2.3 組み込み型
      • 2.3.1 真値テスト
      • 2.3.2 ブール演算
      • 2.3.3 比較
      • 2.3.4 数値型
      • 2.3.5 イテレータ型
      • 2.3.6 配列型
      • 2.3.7 マップ型
      • 2.3.8 ファイルオブジェクト
      • 2.3.9 他の組み込み型
      • 2.3.10 特殊な属性
    • 2.4 組み込み例外
    • 2.5 組み込み定数
  • 3. Python ランタイム サービス
    • 3.1 sys -- システムパラメータと関数
    • 3.2 gc -- ガベージコレクタ インターフェース
    • 3.3 weakref -- 弱参照
      • 3.3.1 弱参照オブジェクト
      • 3.3.2 例
      • 3.3.3 拡張型における弱参照
    • 3.4 fpectl -- 浮動小数点例外の制御
      • 3.4.1 例
      • 3.4.2 制限と他に考慮すべきこと
    • 3.5 atexit -- 終了ハンドラ
      • 3.5.1 atexit 例
    • 3.6 types -- 組み込み型の名前
    • 3.7 UserDict -- 辞書オブジェクトのためのクラスラッパー
    • 3.8 UserList -- リストオブジェクトのためのクラスラッパー
    • 3.9 UserString -- 文字列オブジェクトのためのクラスラッパー
    • 3.10 operator -- 関数形式の標準演算子
      • 3.10.1 演算子から関数への対応表
    • 3.11 inspect -- 使用中のオブジェクトを調査
      • 3.11.1 型とメンバ
      • 3.11.2 ソース参照
    • 3.12 traceback -- スタックトレースの表示や取り出し
      • 3.12.1 トレースバックの例
    • 3.13 linecache -- テキストラインにランダムアクセスする
    • 3.14 pickle -- Python オブジェクトの整列化
      • 3.14.1 他の Python モジュールとの関係
      • 3.14.2 データストリームの形式
      • 3.14.3 使用法
      • 3.14.4 何を pickle 化したり unpickle 化できるのか?
      • 3.14.5 pickle 化プロトコル
      • 3.14.6 Unpickler をサブクラス化する
      • 3.14.7 例
    • 3.15 cPickle -- より高速な pickle
    • 3.16 copy_reg -- pickleサポート関数を登録する
    • 3.17 shelve -- Python オブジェクトの永続化
      • 3.17.1 制限事項
      • 3.17.2 使用例
    • 3.18 copy -- 浅いコピーおよび深いコピー操作
    • 3.19 marshal -- 内部使用向けの Python オブジェクト整列化
    • 3.20 warnings -- 警告の制御
      • 3.20.1 警告カテゴリ
      • 3.20.2 警告フィルタ
      • 3.20.3 利用可能な関数
    • 3.21 imp -- import内部へアクセスする
      • 3.21.1 例
    • 3.22 pkgutil -- パッケージ拡張ユーティリティ
    • 3.23 code -- インタプリタ基底クラス
      • 3.23.1 対話的なインタプリタオブジェクト
      • 3.23.2 対話的なコンソールオブジェクト
    • 3.24 codeop -- Pythonコードをコンパイルする
    • 3.25 pprint -- データ出力の整然化
      • 3.25.1 PrettyPrinter オブジェクト
    • 3.26 repr -- もう一つのrepr()の実装
      • 3.26.1 Reprオブジェクト
      • 3.26.2 Reprオブジェクトをサブクラス化する
    • 3.27 new -- ランタイム内部オブジェクトの作成
    • 3.28 site -- サイト固有の設定フック
    • 3.29 user -- ユーザー設定のフック
    • 3.30 __builtin__ -- 組み込み関数
    • 3.31 __main__ -- トップレベルのスクリプト環境
    • 3.32 __future__ -- Future ステートメントの定義
  • 4. 文字列処理
    • 4.1 string -- 一般的な文字列操作
    • 4.2 re -- 正規表現操作
      • 4.2.1 正規表現のシンタックス
      • 4.2.2 マッチング vs 検索
      • 4.2.3 モジュール コンテンツ
      • 4.2.4 正規表現オブジェクト
      • 4.2.5 MatchObject オブジェクト
      • 4.2.6 例
    • 4.3 struct -- 文字列データをパックされたバイナリデータとして解釈する
    • 4.4 difflib -- 差異の計算を助ける
      • 4.4.1 SequenceMatcherオブジェクト
      • 4.4.2 SequenceMatcher の例
      • 4.4.3 Differ オブジェクト
      • 4.4.4 Differ の例
    • 4.5 fpformat -- 浮動小数点の変換
    • 4.6 StringIO -- ファイルのように文字列を読み書きする
    • 4.7 cStringIO -- 高速化された StringIO
    • 4.8 textwrap -- テキストの折り返しと詰め込み
    • 4.9 codecs -- codec レジストリと基底クラス
      • 4.9.1 Codec 基底クラス
      • 4.9.2 標準エンコーディング
      • 4.9.3 encodings.idna -- アプリケーションにおける国際化ドメイン名 (IDNA)
    • 4.10 unicodedata -- Unicode データベース
    • 4.11 stringprep -- インターネットのための文字列調製
  • 5. 各種サービス
    • 5.1 pydoc -- ドキュメント生成とオンラインヘルプシステム
    • 5.2 doctest -- ドキュメンテーション文字列に本当のことが書かれているか調べる
      • 5.2.1 通常の利用法
      • 5.2.2 どのドキュメンテーション文字列が検証されるのか?
      • 5.2.3 実行コンテキストとは何か?
      • 5.2.4 例外については?
      • 5.2.5 進んだ使い方
      • 5.2.6 ドキュメンテーション文字列内の例をどうやって認識するのか?
      • 5.2.7 注意事項
      • 5.2.8 提言
    • 5.3 unittest -- 単体テストフレームワーク
      • 5.3.1 基礎的な例
      • 5.3.2 テストの構成
      • 5.3.3 既存テストコードの再利用
      • 5.3.4 クラスと関数
      • 5.3.5 TestCase オブジェクト
      • 5.3.6 TestSuite オブジェクト
      • 5.3.7 TestResultオブジェクト
      • 5.3.8 TestLoader オブジェクト
    • 5.4 test -- Python用回帰テストパッケージ
      • 5.4.1 testパッケージのためのユニットテストを書く
      • 5.4.2 test.regrtestを使ってテストを実行する
      • 5.4.3 test.test_support -- テストのためのユーティリティ関数
    • 5.5 math -- 数学関数
    • 5.6 cmath -- 複素数のための数学関数
    • 5.7 random -- 擬似乱数を生成する
    • 5.8 whrandom -- 擬似乱数生成器
    • 5.9 bisect -- 配列二分法アルゴリズム
      • 5.9.1 使用例
    • 5.10 heapq -- ヒープキューアルゴリズム
      • 5.10.1 理論
    • 5.11 array -- 効率のよい数値配列
    • 5.12 sets -- ユニークな要素の順序なしコレクション
      • 5.12.1 Set オブジェクト
      • 5.12.2 使用例
      • 5.12.3 不変に自動変換するためのプロトコル
    • 5.13 itertools -- 効率的なループ実行のためのイテレータ生成関数
      • 5.13.1 Itertool関数
      • 5.13.2 例
    • 5.14 ConfigParser -- 設定ファイルの構文解析器
      • 5.14.1 RawConfigParser オブジェクト
      • 5.14.2 ConfigParser オブジェクト
    • 5.15 fileinput -- 複数の入力ストリームをまたいだ行の繰り返し処理をサポートする。
    • 5.16 xreadlines -- ファイルの各行に対する効率のよい反復処理
    • 5.17 calendar -- 一般的なカレンダーに関する関数群
    • 5.18 cmd -- 行指向のコマンドインタープリタのサポート
      • 5.18.1 Cmdオブジェクト
    • 5.19 shlex -- 単純な字句解析
      • 5.19.1 モジュールの内容
      • 5.19.2 shlex オブジェクト
      • 5.19.3 解析規則
  • 6. 汎用オペレーティングシステムサービス
    • 6.1 os -- 雑多なオペレーティングシステムインタフェース
      • 6.1.1 プロセスのパラメタ
      • 6.1.2 ファイルオブジェクトの生成
      • 6.1.3 ファイル記述子の操作
      • 6.1.4 ファイルとディレクトリ
      • 6.1.5 プロセス管理
      • 6.1.6 雑多なシステム情報
    • 6.2 os.path -- 共通のパス名操作
    • 6.3 dircache -- キャッシュされたディレクトリ一覧の生成
    • 6.4 stat -- stat() の返す内容を解釈する
    • 6.5 statcache -- os.stat() の最適化
    • 6.6 statvfs -- os.statvfs() で使われる定数群
    • 6.7 filecmp -- ファイルおよびディレクトリの比較
      • 6.7.1 dircmp クラス
    • 6.8 popen2 -- アクセス可能な I/O ストリームを持つ子プロセス生成
      • 6.8.1 Popen3 および Popen4 オブジェクト
      • 6.8.2 フロー制御の問題
    • 6.9 datetime -- 基本的な日付型および時間型
      • 6.9.1 利用可能なデータ型
      • 6.9.2 timedelta オブジェクト
      • 6.9.3 date オブジェクト
      • 6.9.4 datetime オブジェクト
      • 6.9.5 time オブジェクト
      • 6.9.6 tzinfo オブジェクト
      • 6.9.7 strftime() の振る舞い
    • 6.10 time -- 時刻データへのアクセスと変換
    • 6.11 sched -- イベントスケジューラ
      • 6.11.1 スケジューラオブジェクト
    • 6.12 mutex -- 排他制御
      • 6.12.1 mutex オブジェクト
    • 6.13 getpass -- 可搬性のあるパスワード入力機構
    • 6.14 curses -- 文字セル表示のための端末操作
      • 6.14.1 関数
      • 6.14.2 Window オブジェクト
      • 6.14.3 定数
    • 6.15 curses.textpad -- curses プログラムのためのテキスト入力ウィジェット
      • 6.15.1 Textbox オブジェクト
    • 6.16 curses.wrapper -- curses プログラムのための端末ハンドラ
    • 6.17 curses.ascii -- ASCII 文字に関するユーティリティ
    • 6.18 curses.panel -- curses のためのパネルスタック拡張
      • 6.18.1 関数
      • 6.18.2 Panel オブジェクト
    • 6.19 getopt -- コマンドラインオプションのパーザ
    • 6.20 optparse -- 強力なコマンドラインオプション解析器
      • 6.20.1 オプション解析への道
      • 6.20.2 基本的な使い方
      • 6.20.3 進んだ使い方
      • 6.20.4 callback オプション
      • 6.20.5 optparse を拡張する
    • 6.21 tempfile -- 一時的なファイルやディレクトリの生成
    • 6.22 errno -- 標準の errno システムシンボル
    • 6.23 glob -- Unix 形式のパス名のパターン展開
    • 6.24 fnmatch -- Unix ファイル名のパターンマッチ
    • 6.25 shutil -- 高レベルなファイル操作
      • 6.25.1 使用例
    • 6.26 locale -- 国際化サービス
      • 6.26.1 ロケールの背景、詳細、ヒント、助言および補足説明
      • 6.26.2 Python 拡張の作者と、Python を埋め込むようなプログラムに関して
      • 6.26.3 メッセージカタログへのアクセス
    • 6.27 gettext -- 多言語対応に関する国際化サービス
      • 6.27.1 GNU gettext API
      • 6.27.2 クラスに基づいた API
      • 6.27.3 プログラムやモジュールを国際化する
      • 6.27.4 謝辞
    • 6.28 logging -- Python用ロギング機能
      • 6.28.1 Logger オブジェクト
      • 6.28.2 Handler オブジェクト
      • 6.28.3 Formatter オブジェクト
      • 6.28.4 Filter オブジェクト
      • 6.28.5 LogRecord オブジェクト
      • 6.28.6 スレッド安全性
      • 6.28.7 環境設定
      • 6.28.8 Using the logging package
  • 7. オプションのオペレーティングシステムサービス
    • 7.1 signal -- 非同期イベントにハンドラを設定する
      • 7.1.1 例
    • 7.2 socket -- 低レベルネットワークインターフェース
      • 7.2.1 socket オブジェクト
      • 7.2.2 SSL オブジェクト
      • 7.2.3 例
    • 7.3 select -- I/O 処理の完了を待機する
      • 7.3.1 ポーリングオブジェクト
    • 7.4 thread -- マルチスレッドのコントロール
    • 7.5 threading -- 高レベルスレッドインターフェース
      • 7.5.1 Lock オブジェクト
      • 7.5.2 RLock オブジェクト
      • 7.5.3 Condition オブジェクト
      • 7.5.4 Semaphore オブジェクト
      • 7.5.5 Event オブジェクト
      • 7.5.6 Thread オブジェクト
      • 7.5.7 Timer オブジェクト
    • 7.6 dummy_thread -- thread の代替モジュール
    • 7.7 dummy_threading -- threading の代替モジュール
    • 7.8 Queue -- 同期キュークラス
      • 7.8.1 キューオブジェクト
    • 7.9 mmap -- メモリマップファイル
    • 7.10 anydbm -- DBM 形式のデータベースへの汎用アクセスインタフェース
    • 7.11 dbhash -- BSD データベースライブラリへの DBM 形式のインタフェース
      • 7.11.1 データベースオブジェクト
    • 7.12 whichdb -- どのDBMモジュールがデータベースを作ったかを推測する
    • 7.13 bsddb -- Berkeley DB ライブラリへのインタフェース
      • 7.13.1 ハッシュ、BTree、およびレコードオブジェクト
    • 7.14 dumbdbm -- 可搬性のある DBM 実装
      • 7.14.1 Dumbdbm オブジェクト
    • 7.15 zlib -- gzip 互換の圧縮
    • 7.16 gzip -- gzip ファイルのサポート
    • 7.17 bz2 -- bzip2 互換の圧縮ライブラリ
      • 7.17.1 ファイルの圧縮（解凍）
      • 7.17.2 逐次的な圧縮（解凍）
      • 7.17.3 一括圧縮（解凍）
    • 7.18 zipfile -- ZIP アーカイブの処理
      • 7.18.1 ZipFile オブジェクト
      • 7.18.2 PyZipFile オブジェクト
      • 7.18.3 ZipInfo オブジェクト
    • 7.19 tarfile -- tar アーカイブファイルを読み書きする
      • 7.19.1 TarFile オブジェクト
      • 7.19.2 TarInfo オブジェクト
      • 7.19.3 例
    • 7.20 readline -- GNU readline のインタフェース
      • 7.20.1 例
    • 7.21 rlcompleter -- GNU readline向け補完関数
      • 7.21.1 Completerオブジェクト
  • 8. Unix独特のサービス
    • 8.1 posix -- 最も一般的な POSIX システムコール群
      • 8.1.1 ラージファイルのサポート
      • 8.1.2 モジュールの内容
    • 8.2 pwd -- パスワードデータベースへのアクセスを提供する
    • 8.3 grp -- グループデータベースへのアクセス
    • 8.4 crypt -- Unix パスワードをチェックするための関数
    • 8.5 dl -- 共有オブジェクトのC関数の呼び出し
      • 8.5.1 Dlオブジェクト
    • 8.6 dbm -- UNIX dbmのシンプルなインタフェース
    • 8.7 gdbm -- GNU による dbm の再実装
    • 8.8 termios -- POSIX スタイルの端末制御
      • 8.8.1 使用例
    • 8.9 TERMIOS -- termios モジュールで使われる定数
    • 8.10 tty -- 端末制御のための関数群
    • 8.11 pty -- 擬似端末ユーティリティ
    • 8.12 fcntl -- fcntl() および ioctl() システムコール
    • 8.13 pipes -- シェルパイプラインへのインタフェース
      • 8.13.1 テンプレートオブジェクト
    • 8.14 posixfile -- ロック機構をサポートするファイル類似オブジェクト
    • 8.15 resource -- リソース使用状態の情報
      • 8.15.1 リソースの制限
      • 8.15.2 リソースの使用状態
    • 8.16 nis -- Sun の NIS (Yellow Pages) へのインタフェース
    • 8.17 syslog -- Unix syslog ライブラリルーチン群
    • 8.18 commands -- コマンド実行ユーティリティ
  • 9. Pythonデバッガ
    • 9.1 デバッガコマンド
    • 9.2 どのように動作しているか
  • 10. Python プロファイラ
    • 10.1 プロファイラとは
    • 10.2 旧バージョンのプロファイラとの違い
    • 10.3 インスタント・ユーザ・マニュアル
    • 10.4 決定論的プロファイリングとは何か?
    • 10.5 リファレンス・マニュアル
      • 10.5.1 Stats クラス
    • 10.6 制限事項
    • 10.7 キャリブレーション(補正)
    • 10.8 拡張 -- プロファイラの改善
    • 10.9 hotshot -- ハイパフォーマンス・ロギング・プロファイラ
      • 10.9.1 プロファイル・オブジェクト
      • 10.9.2 hotshot データの利用
      • 10.9.3 使用例
    • 10.10 timeit -- 小さなコード断片の実行時間計測
      • 10.10.1 コマンドライン・インターフェース
      • 10.10.2 使用例
  • 11. インターネットプロトコルとその支援
    • 11.1 webbrowser -- 便利なウェブブラウザコントローラー
      • 11.1.1 ブラウザコントローラーオブジェクト
    • 11.2 cgi -- CGI (ゲートウェイインタフェース規格) のサポート
      • 11.2.1 はじめに
      • 11.2.2 cgi モジュールを使う
      • 11.2.3 高レベルインタフェース
      • 11.2.4 古いクラス群
      • 11.2.5 関数
      • 11.2.6 セキュリティへの配慮
      • 11.2.7 CGI スクリプトを Unix システムにインストールする
      • 11.2.8 CGI スクリプトをテストする
      • 11.2.9 CGI スクリプトをデバッグする
      • 11.2.10 よくある問題と解決法
    • 11.3 cgitb -- CGI スクリプトのトレースバック管理機構
    • 11.4 urllib -- URL による任意のリソースへのアクセス
      • 11.4.1 URLopener オブジェクト
      • 11.4.2 使用例
    • 11.5 urllib2 -- URL を開くための拡張可能なライブラリ
      • 11.5.1 Request オブジェクト
      • 11.5.2 OpenerDirector オブジェクト
      • 11.5.3 BaseHandler オブジェクト
      • 11.5.4 HTTPRedirectHandler オブジェクト
      • 11.5.5 ProxyHandler オブジェクト
      • 11.5.6 HTTPPasswordMgr オブジェクト
      • 11.5.7 AbstractBasicAuthHandler オブジェクト
      • 11.5.8 HTTPBasicAuthHandler オブジェクト
      • 11.5.9 ProxyBasicAuthHandler オブジェクト
      • 11.5.10 AbstractDigestAuthHandler オブジェクト
      • 11.5.11 HTTPDigestAuthHandler オブジェクト
      • 11.5.12 ProxyDigestAuthHandler オブジェクト
      • 11.5.13 HTTPHandler オブジェクト
      • 11.5.14 HTTPSHandler オブジェクト
      • 11.5.15 FileHandler オブジェクト
      • 11.5.16 FTPHandler オブジェクト
      • 11.5.17 CacheFTPHandler オブジェクト
      • 11.5.18 GopherHandler オブジェクト
      • 11.5.19 UnknownHandler オブジェクト
      • 11.5.20 例
    • 11.6 httplib -- HTTP プロトコルクライアント
      • 11.6.1 HTTPConnection オブジェクト
      • 11.6.2 HTTPResponse オブジェクト
      • 11.6.3 例
    • 11.7 ftplib -- FTPプロトコルクライアント
      • 11.7.1 FTP オブジェクト
    • 11.8 gopherlib -- gopher プロトコルのクライアント
    • 11.9 poplib -- POP3 プロトコルクライアント
      • 11.9.1 POP3 オブジェクト
      • 11.9.2 POP3 の例
    • 11.10 imaplib -- IMAP4 プロトコルクライアント
      • 11.10.1 IMAP4 オブジェクト
      • 11.10.2 IMAP4 の使用例
    • 11.11 nntplib -- NNTP プロトコルクライアント
      • 11.11.1 NNTP オブジェクト
    • 11.12 smtplib -- SMTP プロトコル クライアント
      • 11.12.1 SMTP オブジェクト
      • 11.12.2 SMTP 使用例
    • 11.13 telnetlib -- Telnet クライアント
      • 11.13.1 Telnet オブジェクト
      • 11.13.2 Telnet Example
    • 11.14 urlparse -- URL を解析して構成要素にする
    • 11.15 SocketServer -- ネットワークサーバ構築のための フレームワーク
    • 11.16 BaseHTTPServer -- 基本的な機能を持つ HTTP サーバ
    • 11.17 SimpleHTTPServer -- 簡潔な HTTP リクエストハンドラ
    • 11.18 CGIHTTPServer -- CGI 実行機能付き HTTP リクエスト処理機構
    • 11.19 Cookie -- HTTPの状態管理
      • 11.19.1 Cookieオブジェクト
      • 11.19.2 Morselオブジェクト
      • 11.19.3 例
    • 11.20 xmlrpclib -- XML-RPC クライアントアクセス
      • 11.20.1 ServerProxy オブジェクト
      • 11.20.2 Boolean オブジェクト
      • 11.20.3 DateTime オブジェクト
      • 11.20.4 Binary オブジェクト
      • 11.20.5 Fault オブジェクト
      • 11.20.6 ProtocolError オブジェクト
      • 11.20.7 補助関数
      • 11.20.8 クライアントのサンプル
    • 11.21 SimpleXMLRPCServer -- 基本的なXML-RPCサーバー
      • 11.21.1 SimpleXMLRPCServer オブジェクト
      • 11.21.2 CGIXMLRPCRequestHandler
    • 11.22 DocXMLRPCServer -- セルフ-ドキュメンティング XML-RPC サーバ
      • 11.22.1 DocXMLRPCServer オブジェクト
      • 11.22.2 DocCGIXMLRPCRequestHandler
    • 11.23 asyncore -- 非同期ソケットハンドラ
      • 11.23.1 asyncoreの例：簡単なHTTPクライアント
    • 11.24 asynchat -- 非同期ソケット コマンド/レスポンス ハンドラ
      • 11.24.1 asynchat - 補助クラスと関数
      • 11.24.2 asynchat 使用例
  • 12. インターネット上のデータの操作
    • 12.1 formatter -- 汎用の出力書式化機構
      • 12.1.1 formatter インタフェース
      • 12.1.2 formatter 実装
      • 12.1.3 writer インタフェース
      • 12.1.4 writer 実装
    • 12.2 email -- 電子メールと MIME 処理のためのパッケージ
      • 12.2.1 電子メールメッセージの表現
      • 12.2.2 電子メールメッセージを解析(パース)する
      • 12.2.3 MIME 文書を生成する
      • 12.2.4 電子メールおよび MIME オブジェクトをゼロから作成する
      • 12.2.5 国際化されたヘッダ
      • 12.2.6 文字セットの表現
      • 12.2.7 エンコーダ
      • 12.2.8 例外クラス
      • 12.2.9 雑用ユーティリティ
      • 12.2.10 イテレータ
      • 12.2.11 (Python 2.2.1 までの) email v1 とのちがい
      • 12.2.12 mimelib との違い
      • 12.2.13 使用例
    • 12.3 mailcap -- mailcap ファイルの操作
    • 12.4 mailbox -- 様々なメールボックス形式の読み出し
      • 12.4.1 Mailbox オブジェクト
    • 12.5 mhlib -- MH のメイルボックスへのアクセス機構
      • 12.5.1 MH オブジェクト
      • 12.5.2 Folder オブジェクト
      • 12.5.3 Message オブジェクト
    • 12.6 mimetools -- MIME メッセージを解析するためのツール
      • 12.6.1 Message オブジェクトの追加メソッド
    • 12.7 mimetypes -- ファイル名を MIME 型へマップする
      • 12.7.1 Mime型 オブジェクト
    • 12.8 MimeWriter -- 汎用 MIME ファイルライター
      • 12.8.1 MimeWriter オブジェクト
    • 12.9 mimify -- 電子メイルメッセージの MIME 処理
    • 12.10 multifile -- 個別の部分を含んだファイル群のサポート
      • 12.10.1 MultiFile オブジェクト
      • 12.10.2 MultiFile の例
    • 12.11 rfc822 -- RFC 2822 準拠のメイルヘッダ読み出し
      • 12.11.1 Message オブジェクト
      • 12.11.2 AddressList オブジェクト
    • 12.12 base64 -- MIME base64 形式データのエンコードおよびデコード
    • 12.13 binascii -- バイナリデータと ASCIIデータとの間での変換
    • 12.14 binhex -- binhex4 形式ファイルのエンコードおよびデコード
      • 12.14.1 注記
    • 12.15 quopri -- MIME quoted-printable 形式データのエンコードおよびデコード
    • 12.16 uu -- uuencode形式のエンコードとデコード
    • 12.17 xdrlib -- XDR データのエンコードおよびデコード
      • 12.17.1 Packer オブジェクト
      • 12.17.2 Unpacker オブジェクト
      • 12.17.3 例外
    • 12.18 netrc -- netrc ファイルの処理
      • 12.18.1 netrc オブジェクト
    • 12.19 robotparser -- robots.txt のためのパーザ
    • 12.20 csv -- CSV ファイルの読み書き
      • 12.20.1 モジュールの内容
      • 12.20.2 Dialect クラスと書式化パラメタ
      • 12.20.3 reader オブジェクト
      • 12.20.4 writer オブジェクト
      • 12.20.5 使用例
  • 13. 構造化マークアップツール
    • 13.1 HTMLParser -- HTML および XHTML のシンプルなパーザ
      • 13.1.1 HTML パーザアプリケーションの例
    • 13.2 sgmllib -- 単純な SGML パーザ
    • 13.3 htmllib -- HTML 文書の解析器
      • 13.3.1 HTMLParser オブジェクト
    • 13.4 htmlentitydefs -- HTML 一般エンティティの定義
    • 13.5 xml.parsers.expat -- Expat を使った高速な XML 解析
      • 13.5.1 XMLParser Objects
      • 13.5.2 ExpatError 例外
      • 13.5.3 例
      • 13.5.4 内容モデルの記述
      • 13.5.5 Expat エラー定数
    • 13.6 xml.dom -- 文書オブジェクトモデル (DOM) API
      • 13.6.1 モジュールの内容
      • 13.6.2 DOM 内のオブジェクト
      • 13.6.3 適合性
    • 13.7 xml.dom.minidom -- 軽量な DOM 実装
      • 13.7.1 DOM オブジェクト
      • 13.7.2 DOM の例
      • 13.7.3 minidom と DOM 標準
    • 13.8 xml.dom.pulldom -- 部分的な DOM ツリー構築のサポート
      • 13.8.1 DOMEventStream オブジェクト
    • 13.9 xml.sax -- SAX2 パーサのサポート
      • 13.9.1 SAXException オブジェクト
    • 13.10 xml.sax.handler -- SAX ハンドラの基底クラス
      • 13.10.1 ContentHandler オブジェクト
      • 13.10.2 DTDHandler オブジェクト
      • 13.10.3 EntityResolver オブジェクト
      • 13.10.4 ErrorHandler オブジェクト
    • 13.11 xml.sax.saxutils -- SAX ユーティリティ
    • 13.12 xml.sax.xmlreader -- XML パーサのインターフェース
      • 13.12.1 XMLReader オブジェクト
      • 13.12.2 IncrementalParser オブジェクト
      • 13.12.3 Locator オブジェクト
      • 13.12.4 InputSource オブジェクト
      • 13.12.5 The Attributes インターフェース
      • 13.12.6 AttributesNS インターフェース
    • 13.13 xmllib -- XML ドキュメントのパーサ
      • 13.13.1 XML 名前空間
  • 14. マルチメディアサービス
    • 14.1 audioop -- 生のオーディオデータの操作
    • 14.2 imageop -- 生の画像データを操作する
    • 14.3 aifc -- AIFFおよびAIFCファイルの読み書き
    • 14.4 sunau -- Sun AUファイルの読み書き
      • 14.4.1 AU_read オブジェクト
      • 14.4.2 AU_write オブジェクト
    • 14.5 wave -- WAVファイルの読み書き
      • 14.5.1 Wave_read オブジェクト
      • 14.5.2 Wave_write オブジェクト
    • 14.6 chunk -- IFFチャンクデータの読み込み
    • 14.7 colorsys -- 色体系間の変換
    • 14.8 rgbimg -- ``SGI RGB''ファイルを読み書きする
    • 14.9 imghdr -- 画像の形式を決定する
    • 14.10 sndhdr -- サウンドファイルの識別
    • 14.11 ossaudiodev -- OSS互換オーディオデバイスへのアクセス
      • 14.11.1 オーディオデバイスオブジェクト
      • 14.11.2 ミキサーデバイスオブジェクト
  • 15. 暗号関連のサービス
    • 15.1 hmac -- メッセージ認証のための鍵付きハッシュ化
    • 15.2 md5 -- MD5 メッセージダイジェストアルゴリズム
    • 15.3 sha -- SHA-1 メッセージダイジェストアルゴリズム
    • 15.4 mpz -- GNU 多倍長整数
    • 15.5 rotor -- エニグマ暗号機のような暗号化と復号化
  • 16. Tkを用いたグラフィカルユーザインターフェイス
    • 16.1 Tkinter -- Tcl/TkへのPythonインターフェイス
      • 16.1.1 Tkinterモジュール
      • 16.1.2 Tkinter Life Preserver
      • 16.1.3 Tcl/Tkに(非常に)さっと目を通す
      • 16.1.4 基本的なTkをTkinterへマッピングする
      • 16.1.5 TkとTkinterはどのように関係なのか
      • 16.1.6 便利なリファレンス
    • 16.2 Tix -- Tkの拡張ウィジェット
      • 16.2.1 Tixを使う
      • 16.2.2 Tixウィジェット
      • 16.2.3 Tixコマンド
    • 16.3 ScrolledText -- スクロールするテキストウィジェット
    • 16.4 turtle -- Tkのためのタートルグラフィックス
      • 16.4.1 PenとRawPenオブジェクト
    • 16.5 Idle
      • 16.5.1 メニュー
      • 16.5.2 基本的な編集とナビゲーション
      • 16.5.3 構文の色づけ
    • 16.6 他のグラフィカルユーザインターフェイスパッケージ
  • 17. 制限実行 (restricted execution)
    • 17.1 rexec -- 制限実行のフレームワーク
      • 17.1.1 RExec オブジェクト
      • 17.1.2 制限された環境を定義する
      • 17.1.3 例
    • 17.2 Bastion -- オブジェクトに対するアクセスの制限
  • 18. Python言語サービス
    • 18.1 parser -- Python解析木にアクセスする
      • 18.1.1 ASTオブジェクトを作成する
      • 18.1.2 ASTオブジェクトを変換する
      • 18.1.3 ASTオブジェクトに対する問い合わせ
      • 18.1.4 例外とエラー処理
      • 18.1.5 ASTオブジェクト
      • 18.1.6 例
    • 18.2 symbol -- Python解析木と共に使われる定数
    • 18.3 token -- Python解析木と共に使われる定数
    • 18.4 keyword -- Pythonキーワードチェック
    • 18.5 tokenize -- Pythonソースのためのトークナイザ
    • 18.6 tabnanny -- あいまいなインデントの検出
    • 18.7 pyclbr -- Python クラスブラウザーサポート
      • 18.7.1 クラス記述オブジェクト
      • 18.7.2 関数記述オブジェクト (Function Descriptor Object)
    • 18.8 py_compile -- Pythonソースファイルのコンパイル
    • 18.9 compileall -- Pythonライブラリをバイトコンパイル
    • 18.10 dis -- Pythonバイトコードの逆アセンブラ
      • 18.10.1 Pythonバイトコード命令
    • 18.11 distutils -- Python モジュールの構築とインストール
  • 19. Python コンパイラパッケージ
    • 19.1 基本的なインターフェイス
    • 19.2 制限
    • 19.3 Python 抽象構文
      • 19.3.1 AST ノード
      • 19.3.2 代入ノード
      • 19.3.3 サンプル
    • 19.4 Visitor を使って AST をわたり歩く
    • 19.5 バイトコード生成
  • 20. SGI IRIX 特有のサービス
    • 20.1 al -- SGIのオーディオ機能
      • 20.1.1 コンフィギュレーションオブジェクト
      • 20.1.2 ポートオブジェクト
    • 20.2 AL -- alモジュールで使われる定数
    • 20.3 cd -- SGIシステムのCD-ROMへのアクセス
      • 20.3.1 プレーヤーオブジェクト
      • 20.3.2 パーザオブジェクト
    • 20.4 fl -- グラフィカルユーザーインターフェースのためのFORMSライブラリ
      • 20.4.1 flモジュールに定義されている関数
      • 20.4.2 フォームオブジェクト
      • 20.4.3 FORMSオブジェクト
    • 20.5 FL -- flモジュールで使用される定数
    • 20.6 flp -- 保存されたFORMSデザインをロードする関数
    • 20.7 fm -- Font Manager インターフェース
    • 20.8 gl -- Graphics Library インターフェース
    • 20.9 DEVICE -- glモジュールで使われる定数
    • 20.10 GL -- glモジュールで使われる定数
    • 20.11 imgfile -- SGI imglib ファイルのサポート
    • 20.12 jpeg -- JPEGファイルの読み書きを行う
  • 21. SunOS 特有のサービス
    • 21.1 sunaudiodev -- Sunオーディオハードウェアへのアクセス
      • 21.1.1 オーディオデバイスオブジェクト
    • 21.2 SUNAUDIODEV -- sunaudiodevで使われる定数
  • 22. MS Windows 特有のサービス
    • 22.1 msvcrt - MS VC++実行時システムの有用なルーチン群
      • 22.1.1 ファイル操作関連
      • 22.1.2 コンソール I/O 関連
      • 22.1.3 その多の関数
    • 22.2 _winreg - Windows レジストリへのアクセス
      • 22.2.1 レジストリハンドルオブジェクト
    • 22.3 winsound -- Windows 用の音声再生インタフェース
  • A. ドキュメント化されていないモジュール
    • A.1 フレームワーク
    • A.2 雑多な有用ユーティリティ
    • A.3 プラットフォーム特有のモジュール
    • A.4 マルチメディア関連
    • A.5 撤廃されたもの
    • A.6 SGI 特有の拡張モジュール
  • B. バグ報告
  • C. 歴史とライセンス
    • C.1 History of the software
    • C.2 Terms and conditions for accessing or otherwise using Python
  • D. 日本語訳について
    • D.1 このドキュメントについて
    • D.2 翻訳者一覧 (敬称略)
  • Module Index
  • 索引

Previous Page Up One Level Next Page Python ライブラリリファレンス Module Index Index
Previous: 序 Up: Python ライブラリリファレンス Next: 1. はじめに


13.6.3.2 アクセサメソッド

OMG IDL から Python への対応付けは、 IDL attribute 宣言へのアクセサ関数の定義を、Java による対応付けが行うのと ほとんど同じように行います。

IDL 宣言の対応付け

readonly attribute string someValue;
         attribute string anotherValue;

は、三つのアクセサ関数: someValue に対する ``get'' メソッド (_get_someValue())、そしてanotherValue に対する ``get'' および ``set'' メソッド (_get_anotherValue() および _set_anotherValue()) を生み出します。 とりわけ、対応付けでは、IDL 属性が通常の Python 属性としてアクセス 可能であることは必須ではありません: object.someValue が 動作することは必須 ではなく 、AttributeError を送出してもかまいません。

しかしながら、Python DOM API では、通常の属性アクセスが動作することが 必須です。これは、Python IDL コンパイラによって生成された典型的な サロゲーションはまず動作することはなく、DOM オブジェクトが CORBA を解してアクセスされる場合には、クライアント上で ラッパオブジェクトが必要であることを意味します。 CORBA DOM クライアントでは他にもいくつか考慮すべきことがある一方で、 CORBA を介して DOM を使った経験を持つ実装者はこのことを問題視して いません。readonly であると宣言された属性は、全ての DOM 実装で書き込みアクセスを制限しているとは限りません。

さらに、アクセサ関数は必須ではありません。アクセサ関数が提供された場合、 Python IDL 対応付けによって定義された形式をとらなければなりませんが、 属性は Python から直接アクセスすることができるので、それらのメソッドは 必須ではないと考えられます。readonly であると宣言された 属性に対しては、 ``set'' アクセサを提供してはなりません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.3.1 型の対応付け Up: 13.6.3 適合性 Next: 13.7 xml.dom.minidom


13.6.2.7 Attr オブジェクト

Attr は Node を継承しており、全ての属性を受け継いで います。

name
要素型名です。名前空間使用の文書では、要素型名中にコロンが あるかもしれません。

localName
名前にコロンがあればコロン以降の部分に、なければ名前全体になります。

prefix
名前にコロンがあればコロン以前の部分に、なければ空文字列になります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.2.6 Element オブジェクト Up: 13.6.2 DOM 内のオブジェクト Next: 13.6.2.8 NamedNodeMap Objects


13.6.2.8 NamedNodeMap Objects

NamedNodeMap は Node を継承して いません 。

length
属性リストの長さです。

item( index)
特定のインデクスを持つ属性を返します。属性の並び方は任意ですが、 DOM 文書が生成されている間は一定になります。各要素は属性 ノードです。属性値はノードの value 属性で取得してください。

このクラスをよりマップ型的な動作ができるようにする実験的なメソッド もあります。そうしたメソッドを使うこともできますし、 Element オブジェクトに対して、標準化された getAttribute*() ファミリのメソッドを使うこともできます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.2.7 Attr オブジェクト Up: 13.6.2 DOM 内のオブジェクト Next: 13.6.2.9 Comment オブジェクト


13.6.2.9 Comment オブジェクト

Comment は XML 文書中のコメントを表現します。 Comment は Node のサブクラスですが、 子ノードを持つことはありません。

data
文字列によるコメントの内容です。この属性には、コメントの先頭にある <!-- と末尾にある --> 間の全ての文字 が入っていますが、<!-- と--> 自体は 含みません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.2.8 NamedNodeMap Objects Up: 13.6.2 DOM 内のオブジェクト Next: 13.6.2.10 Text オブジェクトおよび CDATASection


13.6.2.5 Document オブジェクト

Document は XML ドキュメント全体を表現し、その構成要素 である要素、属性、処理命令、コメント等が入っています。 Document は Node からプロパティを継承していることを 思い出してください。

documentElement
ドキュメントの唯一無二のルート要素です。

createElement( tagName)
新たな要素ノードを生成して返します。要素は、生成された時点では ドキュメント内に挿入されません。insertBefore() や appendChild() のような他のメソッドの一つを使って 明示的に挿入を行う必要があります。

createElementNS( namespaceURI, tagName)
名前空間を伴う新たな要素ノードを生成して返します。tagName にはプレフィクス (prefix) があってもかまいません。要素は、生成された 時点では文書内に挿入されません。insertBefore() や appendChild() のような他のメソッドの一つを使って 明示的に挿入を行う必要があります。 appendChild().

createTextNode( data)
パラメタで渡されたデータの入ったテキストノードを生成して返します。 他の生成 (create) メソッドと同じく、このメソッドは生成された ノードをツリーに挿入しません。

createComment( data)
パラメタで渡されたデータの入ったコメントノードを生成して返します。 他の生成 (create) メソッドと同じく、このメソッドは生成された ノードをツリーに挿入しません。

createProcessingInstruction( target, data)
パラメタで渡された target および data の入った処理命令 ノードを生成して返します。他の生成 (create) メソッドと同じく、 このメソッドは生成されたノードをツリーに挿入しません。

createAttribute( name)
属性ノードを生成して返します。このメソッドは属性ノードを特定の 要素に関連づけることはしません。新たに生成された属性インスタンス を使うには、適切な Element オブジェクトの setAttributeNode() を使わなければなりません。

createAttributeNS( namespaceURI, qualifiedName)
名前空間を伴う新たな属性ノードを生成して返します。tagName にはプレフィクス (prefix) があってもかまいません。 このメソッドは属性ノードを特定の要素に関連づけることはしません。 新たに生成された属性インスタンスを使うには、適切な Element オブジェクトの setAttributeNode() を使わなければなりません。

getElementsByTagName( tagName)
全ての下位要素 (直接の子要素、子要素の子要素、等) から、特定の 要素型名を持つものを検索します。

getElementsByTagNameNS( namespaceURI, localName)
全ての下位要素 (直接の子要素、子要素の子要素、等) から、特定の 名前空間 URI とローカル名 (local name) を持つものを検索します。 ローカル名は名前空間におけるプレフィクス以降の部分です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.2.4 DocumentType オブジェクト Up: 13.6.2 DOM 内のオブジェクト Next: 13.6.2.6 Element オブジェクト


13.6.2.4 DocumentType オブジェクト

文書で宣言されている記法 (notation) やエンティティ (entity) に関する (外部サブセット(external subset) がパーザから利用でき、情報 を提供できる場合にはそれも含めた) 情報は、 DocumentType オブジェクトから手に入れることができます。文書の DocumentType は、Document オブジェクトの doctype 属性で入手することが できます; 文書の DOCTYPE 宣言がない場合、文書の doctype 属性は、このインタフェースを持つインスタンスの代わりに None に設定されます。

DocumentType は Node を特殊化したもので、以下の 属性を加えています:

publicId
文書型定義 (document type definition) の外部サブセットに対する 公開識別子 (public identifier) です。文字列または None になります。

systemId
文書型定義 (document type definition) の外部サブセットに対する システム識別子 (system identifier) です。文字列の URI または None になります。

internalSubset
ドキュメントの完全な内部サブセットを与える文字列です。 サブセットを囲むブラケットは含みません。ドキュメントが内部サブセット を持たない場合、この値は None です。

name
DOCTYPE 宣言でルート要素の名前が与えられている場合、その 値になります。

entities
外部エンティティの定義を与える NamedNodeMap です。 複数回定義されているエンティティに対しては、最初の定義だけが 提供されます (その他は XML 勧告での要求仕様によって無視されます)。 パーザによって情報が提供されないか、エンティティが定義されていない 場合には、この値は None になることがあります。

notations
記法の定義を与える NamedNodeMap です。 複数回定義されている記法名に対しては、最初の定義だけが 提供されます (その他は XML 勧告での要求仕様によって無視されます)。 パーザによって情報が提供されないか、エンティティが定義されていない 場合には、この値は None になることがあります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.2.3 NodeList オブジェクト Up: 13.6.2 DOM 内のオブジェクト Next: 13.6.2.5 Document オブジェクト


13.6.2.6 Element オブジェクト

Element は Node のサブクラスです。このため Node クラスの全ての属性を継承します。

tagName
要素型名です。名前空間使用の文書では、要素型名中にコロンが あるかもしれません。値は文字列です。

getElementsByTagName( tagName)
Document クラス内における同名のメソッドと同じです。

getElementsByTagNameNS( tagName)
Document クラス内における同名のメソッドと同じです。

getAttribute( attname)
属性値を文字列で返します。

getAttributeNode( attrname)
attrname で指定された属性の Attr ノードを返します。

getAttributeNS( namespaceURI, localName)
指定した namespaceURI および localName を持つ属性値を 文字列として返します。

getAttributeNodeNS( namespaceURI, localName)
指定した namespaceURI および localName を持つ属性値を ノードとして返します。

removeAttribute( attname)
名前で指定された属性を削除します。該当する属性がなくても例外は送出 されません。

removeAttributeNode( oldAttr)
oldAttr が属性リストにある場合、削除して返します。 oldAttr が存在しない場合、NotFoundErr が送出されます。

removeAttributeNS( namespaceURI, localName)
名前で指定された属性を削除します。このメソッドは qname では なく localName を使うので注意してください。該当する 属性がなくても例外は送出されません。

setAttribute( attname, value)
文字列を使って属性値を設定します。

setAttributeNode( newAttr)
新たな属性ノードを要素に追加します。name 属性が 既存の属性に一致した場合、必要に応じて属性を置き換えます。 置換が生じると、古い属性ノードが返されます。 newAttr がすでに使われていれば、 InuseAttributeErr が送出されます。

setAttributeNodeNS( newAttr)
新たな属性ノードを要素に追加します。namespaceURI および localName 属性が既存の属性に一致した場合、必要に応じて 属性を置き換えます。置換が生じると、古い属性ノードが返されます。 newAttr がすでに使われていれば、 InuseAttributeErr が送出されます。

setAttributeNS( namespaceURI, qname, value)
指定された namespaceURI および qname で与えられた属性 の値を文字列で設定します。qname は属性の完全な名前であり、この点が 上記のメソッドと違うので注意してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.2.5 Document オブジェクト Up: 13.6.2 DOM 内のオブジェクト Next: 13.6.2.7 Attr オブジェクト


13.6.2.12 例外

バージョン2.1 以降で新規追加された 仕様です。

DOM レベル 2 勧告では、単一の例外 DOMException と、 どの種のエラーが発生したかをアプリケーションが決定できるようにする 多くの定数を定義しています。 DOMException インスタンスは、特定の例外に関する 適切な値を提供する code 属性を伴っています。

Python DOM インタフェースでは、上記の定数を提供していますが、 同時に一連の例外を拡張して、DOM で定義されている各例外コードに対して 特定の例外が存在するようにしています。 DOM の実装では、適切な特定の例外を送出しなければならず、 各例外は code 属性に対応する適切な値を伴わなければ なりません。

exception DOMException
全ての特定の DOM 例外で使われている基底例外クラスです。この例外 クラスは直接インスタンス化することができません。

exception DomstringSizeErr
指定された範囲のテキストが文字列に収まらない場合に送出されます。 この例外は Python の DOM 実装で使われるかどうかは判っていませんが、 Python で書かれていない DOM 実装から送出される場合があります。

exception HierarchyRequestErr
挿入できない型のノードを挿入しようと試みたときに送出されます。

exception IndexSizeErr
メソッドに与えたインデクスやサイズパラメタが負の値や許容範囲の 値を超えた際に送出されます。

exception InuseAttributeErr
文書中にすでに存在する Attr ノードを挿入しようと試みた 際に送出されます。

exception InvalidAccessErr
パラメタまたは操作が根底にあるオブジェクトでサポートされていない 場合に送出されます。

exception InvalidCharacterErr
この例外は、文字列パラメタが、現在使われているコンテキストで XML 1.0 勧告によって許可されていない場合に送出されます。 例えば、要素型に空白の入った Element ノードを生成 しようとすると、このエラーが送出されます。

exception InvalidModificationErr
ノードの型を変更しようと試みた際に送出されます。

exception InvalidStateErr
利用できないオブジェクトや、もはや利用できなくなったオブジェクトを 使おうと試みた際に送出されます。

exception NamespaceErr
Namespaces in XML に照らして許可されていない方法でオブジェクトを変更しようと 試みた場合、この例外が送出されます。

exception NotFoundErr
参照しているコンテキスト中に目的のノードが存在しない場合に送出される 例外です。例えば、NamedNodeMap.removeNamedItem() は 渡されたノードがノードマップ中に存在しない場合にこの例外を送出 します。

exception NotSupportedErr
要求された方のオブジェクトや操作が実装でサポートされていない場合に 送出されます。

exception NoDataAllowedErr
データ属性をサポートしないノードにデータを指定した際に送出されます。

exception NoModificationAllowedErr
オブジェクトに対して (読み出し専用ノードに対する修正のように) 許可されていない修正を行おうと試みた際に送出されます。

exception SyntaxErr
無効または不正な文字列が指定された際に送出されます。

exception WrongDocumentErr
ノードが現在属している文書と異なる文書に挿入され、 かつある文書から別の文書へのノードの移行が実装でサポート されていない場合に送出されます。

DOM 勧告で定義されている例外コードは、以下のテーブルに従って 上記の例外と対応付けられます:

定数 | 例外
DOMSTRING_SIZE_ERR | DomstringSizeErr
HIERARCHY_REQUEST_ERR | HierarchyRequestErr
INDEX_SIZE_ERR | IndexSizeErr
INUSE_ATTRIBUTE_ERR | InuseAttributeErr
INVALID_ACCESS_ERR | InvalidAccessErr
INVALID_CHARACTER_ERR | InvalidCharacterErr
INVALID_MODIFICATION_ERR | InvalidModificationErr
INVALID_STATE_ERR | InvalidStateErr
NAMESPACE_ERR | NamespaceErr
NOT_FOUND_ERR | NotFoundErr
NOT_SUPPORTED_ERR | NotSupportedErr
NO_DATA_ALLOWED_ERR | NoDataAllowedErr
NO_MODIFICATION_ALLOWED_ERR | NoModificationAllowedErr
SYNTAX_ERR | SyntaxErr
WRONG_DOCUMENT_ERR | WrongDocumentErr

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.2.11 ProcessingInstruction オブジェクト Up: 13.6.2 DOM 内のオブジェクト Next: 13.6.3 適合性


13.6.2.1 DOMImplementation オブジェクト

DOMImplementation インタフェースは、利用している DOM 実装 において特定の機能が利用可能かどうかを決定するための方法を アプリケーションに提供します。DOM レベル 2 では、 DOMImplementation を使って新たなDocument オブジェクト や DocumentType オブジェクトを生成する機能も追加しています。

hasFeature( feature, version)

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.2 DOM 内のオブジェクト Up: 13.6.2 DOM 内のオブジェクト Next: 13.6.2.2 Node オブジェクト


13.6.2.2 Node オブジェクト

XML 文書の全ての構成要素は Node のサブクラスです。

nodeType
ノード (node) の型を表現する整数値です。型に対応する以下の シンボル定数: ELEMENT_NODE 、 ATTRIBUTE_NODE 、 TEXT_NODE 、 CDATA_SECTION_NODE 、 ENTITY_NODE 、 PROCESSING_INSTRUCTION_NODE 、 COMMENT_NODE 、 DOCUMENT_NODE 、 DOCUMENT_TYPE_NODE 、 NOTATION_NODE 、 が Node オブジェクトで定義されています。 読み出し専用の属性です。

parentNode
現在のノードの親ノードか、文書ノードの場合には None になります。この値は常に Node オブジェクトか None になります。Element ノードの場合、この値はルート要素 (root element) の場合を除き親要素 (parent element) となり、 ルート要素の場合には Document オブジェクトとなります。 Attr ノードの場合、この値は常に None となります。 読み出し専用の属性です。

attributes
属性オブジェクトの NamedNodeMap です。要素だけがこの属性に 実際の値を持ちます; その他のオブジェクトでは、この属性を None にします。 読み出し専用の属性です。

previousSibling
このノードと同じ親ノードを持ち、直前にくるノードです。例えば、 self 要素のの開始タグの直前にくる終了タグを持つ要素です。 もちろん、XML 文書は要素だけで構成されているだけではないので、 直前にくる兄弟関係にある要素 (sibling) はテキストやコメント、 その他になる可能性があります。このノードが親ノードにおける 先頭の子ノードである場合、属性値は None になります。 読み出し専用の属性です。

nextSibling
このノードと同じ親ノードを持ち、直後にくるノードです。例えば、 previousSibling も参照してください。 このノードが親ノードにおける末尾頭の子ノードである場合、 属性値は None になります。 読み出し専用の属性です。

childNodes
このノード内に収められているノードからなるリストです。 読み出し専用の属性です。

firstChild
このノードに子ノードがある場合、その先頭のノードです。 そうでない場合 None になります。 読み出し専用の属性です。

lastChild
このノードに子ノードがある場合、その末尾のノードです。 そうでない場合 None になります。 読み出し専用の属性です。

localName
tagName にコロンがあれば、コロン以降の部分に、なければ tagName 全体になります。値は文字列です。

prefix
tagName のコロンがあれば、コロン以前の部分に、なければ 空文字列になります。値は文字列か、None になります。

namespaceURI
要素名に関連付けられた名前空間です。文字列か None に なります。読み出し専用の属性です。

nodeName
この属性はノード型ごとに異なる意味を持ちます; 詳しくは DOM 仕様を 参照してください。この属性で得られることになる情報は、全てのノード 型では tagName 、属性では name プロパティといった ように、常に他のプロパティで得ることができます。全てのノード型で、 この属性の値は文字列か None になります。 読み出し専用の属性です。

nodeValue
この属性はノード型ごとに異なる意味を持ちます; 詳しくは DOM 仕様を 参照してください。その序今日は nodeName と似ています。 この属性の値は文字列か None になります。

hasAttributes( )
ノードが何らかの属性を持っている場合に真を返します。

hasChildNodes( )
ノードが何らかの子ノードを持っている場合に真を返します。

isSameNode( other)
other がこのノードと同じノードを参照している場合に真を返します。 このメソッドは、何らかのプロキシ (proxy) 機構を利用するような DOM 実装で特に便利です (一つ以上のオブジェクトが同じノードを参照 するかもしれないからです)。

注意: このメソッドは DOM レベル 3 API で提案されており、まだ ``ワーキングドラフト(working draft)'' の段階です。しかし、 このインタフェースだけは議論にはならないと考えられます。 W3C による変更は必ずしも Python DOM インタフェースにおける このメソッドに影響するとは限りません (ただしこのメソッドに 対する何らかの新たな W3C API もサポートされるかもしれません)。

appendChild( newChild)
現在のノードの子ノードリストの末尾に新たな子ノードを追加し、 newChild を返します。

insertBefore( newChild, refChild)
新たな子ノードを既存の子ノードの前に挿入します。refChild は現在のノードの子ノードである場合に限られます; そうでない場合、 ValueError が送出されます。 newChild が返されます。

removeChild( oldChild)
子ノードを削除します。oldChild はこのノードの子ノードでなければ なりません。そうでない場合、ValueError が送出されます。 成功した場合 oldChild が返されます。 oldChild をそれ以降使わない場合、unlink() メソッドを 呼び出さなければなりません。

replaceChild( newChild, oldChild)
既存のノードと新たなノードを置き換えます。この操作は oldChild が現在のノードの子ノードである場合に限られます; そうでない場合、 ValueError が送出されます。

normalize( )
一続きのテキスト全体を一個の Text インスタンスとして保存する ために隣接するテキストノードを結合します。これにより、多くの アプリケーションで DOM ツリーからのテキスト処理が簡単になります。 バージョン2.1 以降で新規追加された 仕様です。

cloneNode( deep)
このノードを複製 (clone) します。deep を設定すると、子ノードも 同様に複製することを意味します。複製されたノードを返します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.2.1 DOMImplementation オブジェクト Up: 13.6.2 DOM 内のオブジェクト Next: 13.6.2.3 NodeList オブジェクト


13.6.2.3 NodeList オブジェクト

NodeList は、ノードからなる配列を表現します。これらのオブジェクト は DOM コア勧告 (DOM Core recommendation) において、二通りに使われて います: Element オブジェクトでは、子ノードのリストを提供するのに NodeList を利用します。また、このインタフェースにおける Node の getElementsByTagName() および getElementsByTagNameNS() メソッドは、クエリに対する結果 を表現するのにNodeList を利用します。

DOM レベル 2 勧告では、これらのオブジェクトに対し、メソッドと属性を 一つづつ定義しています:

item( i)
配列に i 番目の要素がある場合にはその要素を、そうでない場合には None を返します。i はゼロよりも小さくてはならず、 配列の長さ以上であってはなりません。

length
配列中のノードの数です。

この他に、Python の DOM インタフェースでは、NodeList オブジェクトを Python の配列として使えるようにするサポートが 追加されていることが必要です。NodeList の実装では、全て __len__() と __getitem__() をサポートしなければ なりません; このサポートにより、for 文内で NodeList にわたる繰り返しと、組み込み関数 len() の適切なサポートができるようになります。

DOM 実装が文書の変更をサポートしている場合、NodeList の 実装でも __setitem__() および __delitem__() メソッドを サポートしなければなりません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.2.2 Node オブジェクト Up: 13.6.2 DOM 内のオブジェクト Next: 13.6.2.4 DocumentType オブジェクト


13.6.2.11 ProcessingInstruction オブジェクト

XML 文書内の処理命令を表現します; Node インタフェース を継承していますが、子ノードを持つことはできません。

target
最初の空白文字までの処理命令の内容です。 読み出し専用の属性です。

data
最初の空白文字以降の処理命令の内容です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.2.10 Text オブジェクトおよび CDATASection Up: 13.6.2 DOM 内のオブジェクト Next: 13.6.2.12 例外


13.6.2.10 Text オブジェクトおよび CDATASection オブジェクト

Text インタフェースは XML 文書内のテキストを表現します。 パーザおよび DOM 実装が DOM の XML 拡張をサポートしている場合、 CDATA でマークされた区域 (section) に入れられている部分テキスト は CDATASection オブジェクトに記憶されます。 これら二つのインタフェースは同一のものですが、nodeType 属性が異なります。

これらのインタフェースは Node インタフェースを拡張したもの です。しかし子ノードを持つことはできません。

data
文字列によるテキストノードの内容です。

注意: CDATASection ノードの利用は、ノードが完全な CDATA マーク区域 を表現するという意味ではなく、ノードの内容が CDATA 区域の一部である ということを意味するだけです。 単一の CDATA セクションは文書ツリー内で複数のノードとして表現 されることがあります。二つの隣接する CDATASection ノードが、異なる CDATA マーク区域かどうかを決定する方法はありません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.2.9 Comment オブジェクト Up: 13.6.2 DOM 内のオブジェクト Next: 13.6.2.11 ProcessingInstruction オブジェクト


13.6.3.1 型の対応付け

DOM 仕様で使われている基本的な IDL 型は、以下のテーブルに従って Python の型に対応付けられています。

IDL 型 | Python 型
boolean | IntegerType (値 0 または 1) による
int | IntegerType
long int | IntegerType
unsigned int | IntegerType

さらに、勧告で定義されている DOMString は、Python 文字列 または Unicode 文字列に対応付けられます。アプリケーションでは、 DOM から文字列が返される際には常に Unicode を扱えなければ なりません。

IDL の null 値は None に対応付けられており、 API で null の使用が許されている場所では常に受理されるか、 あるいは実装によって提供されるはずです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 13.6.3 適合性 Up: 13.6.3 適合性 Next: 13.6.3.2 アクセサメソッド


#!/usr/bin/env python

"""Send the contents of a directory as a MIME message.

Usage: dirmail [options] from to [to ...]*

Options:
    -h / --help
        Print this message and exit.

    -d directory
    --directory=directory
        Mail the contents of the specified directory, otherwise use the
        current directory.  Only the regular files in the directory are sent,
        and we don't recurse to subdirectories.

`from' is the email address of the sender of the message.

`to' is the email address of the recipient of the message, and multiple
recipients may be given.

The email is sent by forwarding to your local SMTP server, which then does the
normal delivery process.  Your local machine must be running an SMTP server.
"""

import sys
import os
import getopt
import smtplib
# For guessing MIME type based on file name extension
import mimetypes

from email import Encoders
from email.Message import Message
from email.MIMEAudio import MIMEAudio
from email.MIMEBase import MIMEBase
from email.MIMEMultipart import MIMEMultipart
from email.MIMEImage import MIMEImage
from email.MIMEText import MIMEText

COMMASPACE = ', '

def usage(code, msg=''):
    print >> sys.stderr, __doc__
    if msg:
        print >> sys.stderr, msg
    sys.exit(code)

def main():
    try:
        opts, args = getopt.getopt(sys.argv[1:], 'hd:', ['help', 'directory='])
    except getopt.error, msg:
        usage(1, msg)

    dir = os.curdir
    for opt, arg in opts:
        if opt in ('-h', '--help'):
            usage(0)
        elif opt in ('-d', '--directory'):
            dir = arg

    if len(args) < 2:
        usage(1)

    sender = args[0]
    recips = args[1:]

    # Create the enclosing (outer) message
    outer = MIMEMultipart()
    outer['Subject'] = 'Contents of directory %s' % os.path.abspath(dir)
    outer['To'] = COMMASPACE.join(recips)
    outer['From'] = sender
    outer.preamble = 'You will not see this in a MIME-aware mail reader.\n'
    # To guarantee the message ends with a newline
    outer.epilogue = ''

    for filename in os.listdir(dir):
        path = os.path.join(dir, filename)
        if not os.path.isfile(path):
            continue
        # Guess the content type based on the file's extension.  Encoding
        # will be ignored, although we should check for simple things like
        # gzip'd or compressed files.
        ctype, encoding = mimetypes.guess_type(path)
        if ctype is None or encoding is not None:
            # No guess could be made, or the file is encoded (compressed), so
            # use a generic bag-of-bits type.
            ctype = 'application/octet-stream'
        maintype, subtype = ctype.split('/', 1)
        if maintype == 'text':
            fp = open(path)
            # Note: we should handle calculating the charset
            msg = MIMEText(fp.read(), _subtype=subtype)
            fp.close()
        elif maintype == 'image':
            fp = open(path, 'rb')
            msg = MIMEImage(fp.read(), _subtype=subtype)
            fp.close()
        elif maintype == 'audio':
            fp = open(path, 'rb')
            msg = MIMEAudio(fp.read(), _subtype=subtype)
            fp.close()
        else:
            fp = open(path, 'rb')
            msg = MIMEBase(maintype, subtype)
            msg.set_payload(fp.read())
            fp.close()
            # Encode the payload using Base64
            Encoders.encode_base64(msg)
        # Set the filename parameter
        msg.add_header('Content-Disposition', 'attachment', filename=filename)
        outer.attach(msg)

    # Now send the message
    s = smtplib.SMTP()
    s.connect()
    s.sendmail(sender, recips, outer.as_string())
    s.close()

if __name__ == '__main__':
    main()


# Import smtplib for the actual sending function
import smtplib

# Here are the email pacakge modules we'll need
from email.MIMEImage import MIMEImage
from email.MIMEMultipart import MIMEMultipart

COMMASPACE = ', '

# Create the container (outer) email message.
msg = MIMEMultipart()
msg['Subject'] = 'Our family reunion'
# me == the sender's email address
# family = the list of all recipients' email addresses
msg['From'] = me
msg['To'] = COMMASPACE.join(family)
msg.preamble = 'Our family reunion'
# Guarantees the message ends in a newline
msg.epilogue = ''

# Assume we know that the image files are all in PNG format
for file in pngfiles:
    # Open the files in binary mode.  Let the MIMEImage class automatically
    # guess the specific image type.
    fp = open(file, 'rb')
    img = MIMEImage(fp.read())
    fp.close()
    msg.attach(img)

# Send the email via our own SMTP server.
s = smtplib.SMTP()
s.connect()
s.sendmail(me, family, msg.as_string())
s.close()


# Import smtplib for the actual sending function
import smtplib

# Import the email modules we'll need
from email.MIMEText import MIMEText

# Open a plain text file for reading.  For this example, assume that
# the text file contains only ASCII characters.
fp = open(textfile, 'rb')
# Create a text/plain message
msg = MIMEText(fp.read())
fp.close()

# me == the sender's email address
# you == the recipient's email address
msg['Subject'] = 'The contents of %s' % textfile
msg['From'] = me
msg['To'] = you

# Send the message via our own SMTP server, but don't include the
# envelope header.
s = smtplib.SMTP()
s.connect()
s.sendmail(me, [you], msg.as_string())
s.close()


#!/usr/bin/env python

"""Unpack a MIME message into a directory of files.

Usage: unpackmail [options] msgfile

Options:
    -h / --help
        Print this message and exit.

    -d directory
    --directory=directory
        Unpack the MIME message into the named directory, which will be
        created if it doesn't already exist.

msgfile is the path to the file containing the MIME message.
"""

import sys
import os
import getopt
import errno
import mimetypes
import email

def usage(code, msg=''):
    print >> sys.stderr, __doc__
    if msg:
        print >> sys.stderr, msg
    sys.exit(code)

def main():
    try:
        opts, args = getopt.getopt(sys.argv[1:], 'hd:', ['help', 'directory='])
    except getopt.error, msg:
        usage(1, msg)

    dir = os.curdir
    for opt, arg in opts:
        if opt in ('-h', '--help'):
            usage(0)
        elif opt in ('-d', '--directory'):
            dir = arg

    try:
        msgfile = args[0]
    except IndexError:
        usage(1)

    try:
        os.mkdir(dir)
    except OSError, e:
        # Ignore directory exists error
        if e.errno <> errno.EEXIST: raise

    fp = open(msgfile)
    msg = email.message_from_file(fp)
    fp.close()

    counter = 1
    for part in msg.walk():
        # multipart/* are just containers
        if part.get_content_maintype() == 'multipart':
            continue
        # Applications should really sanitize the given filename so that an
        # email message can't be used to overwrite important files
        filename = part.get_filename()
        if not filename:
            ext = mimetypes.guess_extension(part.get_type())
            if not ext:
                # Use a generic bag-of-bits extension
                ext = '.bin'
            filename = 'part-%03d%s' % (counter, ext)
        counter += 1
        fp = open(os.path.join(dir, filename), 'wb')
        fp.write(part.get_payload(decode=1))
        fp.close()

if __name__ == '__main__':
    main()


序

Copyright © 2001, 2002, 2003 Python Software Foundation. All rights reserved.

Copyright © 2000 BeOpen.com. All rights reserved.

Copyright © 1995-2000 Corporation for National Research Initiatives. All rights reserved.

Copyright © 1991-1995 Stichting Mathematisch Centrum. All rights reserved.

Translation Copyright © 2003 Python Document Japanese Translation Project. All rights reserved.

ライセンスおよび許諾に関する完全な情報は、このドキュメントの末尾を 参照してください。

概要:

Pythonは拡張性のあるインタプリタ形式のオブジェクト指向言語です。簡単なテキスト処理スクリプトから対話型のWWWブラウザまで、幅広い用途に対応しています。

Pythonリファレンスマニュアル では、言語に関する厳密な構文と意味づけを記述していますが、Python をすぐに役立てられるようにする上で大いに貢献する、言語とともに配付される標準ライブラリについては記述されていません。このライブラリには、ファイル I/O のように Python プログラマが直接アクセスできないシステム機能へのアクセス機能を提供する (Cで書かれた) 組み込みモジュール や、Python で記述された、日々のプログラミングで生じる多くの問題に標準的な解決策を提供するモジュールが入っています。これらのモジュールのいくつかには、Pythonプログラムに移植性を持たせ、それを高めるという明確な意図があります。

このライブラリリファレンスマニュアルでは、Pythonの標準ライブラリだけでなく、多くのオプションのライブラリモジュール (プラットフォームがサポートしているかどうか、あるいはコンパイル時の設定により、使える場合と使えない場合がある) について説明しています。また、言語の標準の型、組み込みの関数と例外、Pythonリファレンスマニュアルに説明がなかったり不足している多くの点についても説明しています。

このマニュアルは、読者が Python 言語について基礎的な知識を持っていることを仮定しています。形式ばらない Python への入門には、Pythonチュートリアルを参照してください。Pythonリファレンスマニュアル は、高度な文法と意味づけについて疑問があるときに参照してください。最後に、Pythonインタプリタの拡張と組み込みと題されたマニュアルには、Pythonに新しい機能を追加する方法と、他のアプリケーションに Python を組み込む方法を記述しています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: Python ライブラリリファレンス Up: Python ライブラリリファレンス Next: 目次


Demo slideshow

import xml.dom.minidom document = """\ Demo slideshow Slide title This is a demo Of a program for processing slides Another demo slide It is important To have more than one slide """ dom = xml.dom.minidom.parseString(document) def getText(nodelist): rc = "" for node in nodelist: if node.nodeType == node.TEXT_NODE: rc = rc + node.data return rc def handleSlideshow(slideshow): print "" handleSlideshowTitle(slideshow.getElementsByTagName("title")[0]) slides = slideshow.getElementsByTagName("slide") handleToc(slides) handleSlides(slides) print "" def handleSlides(slides): for slide in slides: handleSlide(slide) def handleSlide(slide): handleSlideTitle(slide.getElementsByTagName("title")[0]) handlePoints(slide.getElementsByTagName("point")) def handleSlideshowTitle(title): print "%s" % getText(title.childNodes) def handleSlideTitle(title): print "

%s

" % getText(title.childNodes) def handlePoints(points): print "
    " for point in points: handlePoint(point) print "
" def handlePoint(point): print "
  • %s
    • " % getText(point.childNodes) def handleToc(slides): for slide in slides: title = slide.getElementsByTagName("title")[0] print "

    %s

    " % getText(title.childNodes) handleSlideshow(dom)


2.3.9.9 ブール値

ブール値とは二つの定数オブジェクト False および True です。 これらは真偽値を表すために使われます (他の値も偽または真とみなされ ます) 数値処理のコンテキスト (例えば算術演算子の引数として使われた 場合) では、これらはそれぞれ 0 および 1 と同様に振舞います。 任意の値に対して真偽値を変換できる場合、組み込み関数 bool() は 値をブール値にキャストするのに使われます (真値テストの節を参照 してください)

これらはそれぞれ False および True と書き表されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.9.8 省略表記オブジェクト Up: 2.3.9 他の組み込み型 Next: 2.3.9.10 内部オブジェクト


3.14.5.2 拡張型の pickle 化および unpickle 化

Pickler が全く未知の型の -- 拡張型のような -- オブジェクトに 遭遇した場合、pickle 化方法のヒントとして 2 個所を探します。 第一は __reduce__() メソッドを実装しているかどうかです。 もし実装されていれば、pickle 化時に __reduce__() メソッド が引数なしで呼び出され、この呼び出しに対しては文字列またはタプルの どちらかが返されなくてはなりません。

文字列が返された場合、文字列は通常通りに pickle 化されるグローバルな 変数を表します。タプルが返される場合、タプルの長さは 2 または 3 でなければならず、以下のような意味構成になっていなければなりません:

  • 呼び出し可能なオブジェクトで、unpickle 化環境において、クラスか、 ``安全なコンストラクタ (safe constructor)'' (下を参照してください) として登録 されているか、属性 __safe_for_unpickling__ を持ち値が真に 設定されているような呼び出し可能なオブジェクトでなければなりません。 そうでない場合、 unpickle 化環境で UnpicklingError が 送出されます。通常通り、呼び出しオブジェクト自体はその名前が pickle 化されます。

  • 呼び出し可能なオブジェクトのための引数からなるタプルか、あるいは None
    リリース 2.3 以降で撤廃された仕様です。 引数のタプルを使ってください
    。

  • オプションとして、オブジェクトの状態。 3.14.5 節で記述されているようにして、オブジェクトの __setstate__() メソッドに渡されます。オブジェクトが __setstate__() メソッドを持たない場合、上記のように、 この値は辞書でなくてはならず、オブジェクトの __dict__ に追加されます。

unpickle 化の際、(上の条件に合致する場合) 呼び出し可能 オブジェクトは引数のタプルを渡して呼び出されます; オブジェクトは unpickle 化されたオブジェクトを返さなくてはなりません。

タプルの二つ目の要素が None だった場合、呼び出し可能 オブジェクトを直接呼び出す代わりに、オブジェクトの __basicnew__() メソッドが引数なしで呼び出されます。 オブジェクトは同様に unpickle 化されたオブジェクトを返さなければ なりません。

リリース 2.3 以降で撤廃された仕様です。 引数のタプルを使ってください。

pickle 化するオブジェクト上で __reduce__() メソッドを実装 する代わりに、copy_reg モジュールを使って 呼び出し可能オブジェクトを登録する方法もあります。このモジュール はプログラムに ``縮小化関数 (reduction function)'' と ユーザ定義型のためのコンストラクタを登録する方法を提供します。 縮小化関数は、単一の引数として pickle 化するオブジェクトをとる ことを除き、上で述べた __reduce__() メソッドと同じ意味 とインタフェースを持ちます。

登録されたコンストラクタは上で述べたような unpickle 化については ``安全なコンストラクタ'' であると考えられます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.14.5.1 通常のクラスインスタンスの pickle 化および Up: 3.14.5 pickle 化プロトコル Next: 3.14.5.3 外部オブジェクトの pickle 化および


3.14.5.3 外部オブジェクトの pickle 化および unpickle 化

オブジェクトの永続化を便利にするために、pickle は pickle 化されたデータ列上にないオブジェクトに対して参照を 行うという概念をサポートしています。これらのオブジェクトは ``永続化 id (persistent id)'' で参照されており、この id は 単に印字可能な ASCII 文字からなる任意の文字列です。 これらの名前の解決方法は pickle モジュールでは定義されて いません; オブジェクトはこの名前解決を pickler および unpickler 上のユーザ定義関数にゆだねます 3.8。

外部永続化 id の解決を定義するには、pickler オブジェクトの persistent_id 属性と、 unpickler オブジェクトの persistent_load 属性を設定する必要があります。

外部永続化 id を持つオブジェクトを pickle 化するには、pickler は自作の persistent_id() メソッドを 持たなければなりません。このメソッドは一つの引数をとり、 None とオブジェクトの永続化 id のうちどちらかを 返さなければなりません。None が返された場合、 pickler は単にオブジェクトを通常のように pickle 化するだけ です。永続化 id 文字列が返された場合、 piclkler はその 文字列に対して、、unpickler がこの文字列を永続化 id として 認識できるように、マーカと共に pickle 化します。

外部オブジェクトを unpickle 化するには、unpickler は自作の persistent_load() 関数を持たなければなりません。 この関数は永続化 id 文字列を引数にとり、参照されているオブジェクト を返します。

多分 より理解できるようになるようなちょっとした 例を以下に示します:

import pickle
from cStringIO import StringIO

src = StringIO()
p = pickle.Pickler(src)

def persistent_id(obj):
    if hasattr(obj, 'x'):
        return 'the value %d' % obj.x
    else:
        return None

p.persistent_id = persistent_id

class Integer:
    def __init__(self, x):
        self.x = x
    def __str__(self):
        return 'My name is integer %d' % self.x

i = Integer(7)
print i
p.dump(i)

datastream = src.getvalue()
print repr(datastream)
dst = StringIO(datastream)

up = pickle.Unpickler(dst)

class FancyInteger(Integer):
    def __str__(self):
        return 'I am the integer %d' % self.x

def persistent_load(persid):
    if persid.startswith('the value '):
        value = int(persid.split()[2])
        return FancyInteger(value)
    else:
        raise pickle.UnpicklingError, 'Invalid persistent id'

up.persistent_load = persistent_load

j = up.load()
print j

cPickle モジュール内では、 unpickler の persistent_load 属性は Python リスト型として設定することができます。この場合、 unpickler が永続化 id に遭遇しても、永続化 id 文字列は単にリストに 追加されるだけです。この仕様は、pickle データ中の全てのオブジェクトを 実際にインスタンス化しなくても、 pickle データ列中でオブジェクトに対する 参照を ``嗅ぎ回る'' ことができるようにするために存在しています 3.9。 リストに persistent_load を設定するやり方は、 よく Unpickler クラスの noload() メソッドと共に使われます。

... 上のユーザ定義関数にゆだねます3.8
ユーザ定義関数に関連付けを行うための実際のメカニズムは、 pickle および cPickle では少し異なります。 pickle のユーザは、サブクラス化を行い、 persistend_id() および persistent_load() メソッドを上書きすることで同じ効果を得ることができます
... ことができるようにするために存在しています3.9
Guide と Jim が居間に座り込んでピクルス (pickles) を 嗅いでいる光景を想像してください。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.14.5.2 拡張型の pickle 化および Up: 3.14.5 pickle 化プロトコル Next: 3.14.6 Unpickler をサブクラス化する


6.27.2.1 NullTranslations クラス

翻訳クラスは、元のソースファイル中のメッセージ文字列から 翻訳されたメッセージ文字列への変換を実際に実装しているクラスです。 全ての翻訳クラスが基底クラスとして用いるクラスが NullTranslations です; このクラスでは独自の特殊な翻訳 クラスを実装するために使うことができる基本的なインタフェースを 以下に NullTranslations のメソッドを示します:

__init__( [fp])
オプションのファイルオブジェクト fp を取ります。この引数 は基底クラスでは無視されます。このメソッドは ``保護された (protected)'' インスタンス変数 _info および _charset を初期化します。これらの変数の値は導出クラスで設定 することができます。同様に _fallback も初期化しますが、 この値は add_fallback で設定されます。その後、 fp が None でない場合 self._parse(fp) を 呼び出します。

_parse( fp)
基底クラスでは何もしない (no-op) ようになっています。このメソッド の役割はファイルオブジェクト fp を引数に取り、ファイルからデータを 読み出し、メッセージカタログを初期化することです。サポートされていない メッセージカタログ形式を使っている場合、その形式を解釈するためには このメソッドを上書きしなくてはなりません。

add_fallback( fallback)
fallback を現在の翻訳オブジェクトの代替オブジェクトとして追加 します。翻訳オブジェクトが与えられたメッセージに対して翻訳メッセージ を提供できない場合、この代替オブジェクトに問い合わせることになります。

gettext( message)
代替オブジェクトが設定されている場合、gettext を代替オブジェクト に転送します。そうでない場合、翻訳されたメッセージを返します。 導出クラスで上書きするメソッドです。

ugettext( message)
代替オブジェクトが設定されている場合、gettext を代替オブジェクト に転送します。そうでない場合、翻訳されたメッセージを Unicode 文字列 で返します。導出クラスで上書きするメソッドです。

ngettext( singular, plural, n)
代替オブジェクトが設定されている場合、ngettext を代替オブジェクト に転送します。そうでない場合、翻訳されたメッセージを返します。 導出クラスで上書きするメソッドです。 バージョン2.3 以降で新規追加された 仕様です。

ungettext( singular, plural, n)
代替オブジェクトが設定されている場合、ungettext を代替オブジェクト に転送します。そうでない場合、翻訳されたメッセージを Unicode 文字列 で返します。導出クラスで上書きするメソッドです。 バージョン2.3 以降で新規追加された 仕様です。

info( )
``保護されている'' _info 変数を返します。

charset( )
``保護されている'' _charset 変数を返します。

install( [unicode])
unicode フラグが偽の場合、このメソッドは self.gettext() を組み込み名前空間に組み入れ、"_" と結び付けます。 unicode が真の場合、self.gettext() の代わりに self.ugettext() を結び付けます。 標準では unicode は偽です。

この方法はアプリケーションで _ 関数を利用できるようにする ための最も便利な方法ですが、唯一の手段でもあるので注意してください。 この関数はアプリケーション全体、とりわけ組み込み名前空間に影響する ので、地域化されたモジュールで _ を組み入れることが できないのです。その代わりに、以下のコード:

import gettext
t = gettext.translation('mymodule', ...)
_ = t.gettext

を使って _ を使えるようにしなければなりません。

この操作は _ をモジュール内だけのグローバル名前空間に 組み入れるので、モジュール内の _ の呼び出しだけに影響 します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.27.2 クラスに基づいた API Up: 6.27.2 クラスに基づいた API Next: 6.27.2.2 GNUTranslations クラス


6.27.2.2 GNUTranslations クラス

gettext モジュールでは NullTranslations から 導出されたもう一つのクラス: GNUTranslations を提供しています。 このクラスはビッグエンディアン、およびリトルエンディアン両方の バイナリ形式の GNU gettext .mo ファイル を読み出せるように _parse() を上書きしています。 また、このクラスはメッセージ id とメッセージ文字列の両方を Unicode に型強制します。

このクラスではまた、翻訳カタログ以外に、オプションのメタデータ を読み込んで解釈します。GNU gettext では、空の文字列に 対する変換先としてメタデータを取り込むことが慣習になっています。 このメタデータは RFC 822 形式の key: value のペアに なっており、 Project-Id-Version キーを含んでいなければ なりません。キー Content-Type があった場合、 charset の特性値 (property) は ``保護された'' _charset インスタンス 変数を初期化するために用いられます。値がない場合には、デフォルトと して None が使われます。 エンコードに用いられる文字セットが指定されている場合、カタログから 読み出された全てのメッセージ id とメッセージ文字列は、指定された エンコードを用いて Unicode に変換されます。ugettext() は常に Unicode を返し、gettext() はエンコードされた 8 ビット文字列を返します。どちらのメソッドにおける引数 id の 場合も、Unicode 文字列か US-ASCII 文字のみを含む 8 ビット文字列 だけが受理可能です。国際化されたPython プログラムでは、メソッドの Unicode 版 (すなわち ugettext() や ungettext()) の利用が推奨されています。

key/value ペアの集合全体は辞書型データ中に配置され、``保護された'' _info インスタンス変数に設定されます。

.mo ファイルのマジックナンバーが不正な場合、あるいは その他の問題がファイルの読み出し中に発生した場合、 GNUTranslations クラスのインスタンス化で IOError が送出されることがあります。

以下のメソッドは基底クラスの実装からオーバライドされています:

gettext( message)
カタログから message id を検索して、対応するメッセージ文字列を、 カタログの文字セットが既知のエンコードの場合、エンコードされた 8 ビット 文字列として返します。message id に対するエントリがカタログに 存在せず、フォールバックが設定されている場合、フォールバック 検索はオブジェクトの gettext() メソッドに転送されます。 そうでない場合、message id 自体が返されます。

ugettext( message)
カタログから message id を検索して、対応するメッセージ文字列を、 Unicode でエンコードして返します。message id に対するエントリが カタログに存在せず、フォールバックが設定されている場合、フォールバック 検索はオブジェクトの ugettext() メソッドに転送されます。 そうでない場合、message id 自体が返されます。

ngettext( singular, plural, n)
メッセージ id に対する複数形を検索します。カタログに対する検索では singular がメッセージ id として用いられ、 n には どの複数形を用いるかを指定します。返されるメッセージ文字列は 8 ビットの文字列で、カタログの文字セットが既知の場合にはその 文字列セットでエンコードされています。

メッセージ id がカタログ中に見つからず、フォールバックオブジェクト が指定されている場合、メッセージ検索要求はフォールバックオブジェクトの ngettext() メソッドに転送されます。そうでない場合、 n が 1 ならば singular が返され、それ以外に対しては plural が返されます。

バージョン2.3 以降で新規追加された 仕様です。

ungettext( singular, plural, n)
メッセージ id に対する複数形を検索します。カタログに対する検索では singular がメッセージ id として用いられ、 n には どの複数形を用いるかを指定します。返されるメッセージ文字列は Unicode 文字列です。

メッセージ id がカタログ中に見つからず、フォールバックオブジェクト が指定されている場合、メッセージ検索要求はフォールバックオブジェクトの ungettext() メソッドに転送されます。そうでない場合、 n が 1 ならば singular が返され、それ以外に対しては plural が返されます。

以下に例を示します。:

n = len(os.listdir('.'))
cat = GNUTranslations(somefile)
message = cat.ungettext(
    'There is %(num)d file in this directory',
    'There are %(num)d files in this directory',
    n) % {'n': n}

バージョン2.3 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.27.2.1 NullTranslations クラス Up: 6.27.2 クラスに基づいた API Next: 6.27.2.3 Solaris メッセージカタログ機構のサポート


6.27.2.3 Solaris メッセージカタログ機構のサポート

Solaris オペレーティングシステムでは、独自の .mo バイナリファイル形式を定義していますが、この形式に関する ドキュメントが手に入らないため、現時点ではサポートされていません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.27.2.2 GNUTranslations クラス Up: 6.27.2 クラスに基づいた API Next: 6.27.2.4 Catalog コンストラクタ


6.27.2.4 Catalog コンストラクタ

GNOMEでは、James Henstridge によるあるバージョンの gettext モジュールを使っていますが、このバージョンは 少し異なった API を持っています。ドキュメントに書かれている 利用法は:

import gettext
cat = gettext.Catalog(domain, localedir)
_ = cat.gettext
print _('hello world')

となっています。過去のモジュールとの互換性のために、 Catalog() は前述の translation() 関数の別名になっています。

このモジュールと Henstridge のバージョンとの間には一つ相違点が あります: 彼のカタログオブジェクトはマップ型の API を介した アクセスがサポートされていましたが、この API は使われていない らしく、現在はサポートされていません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.27.2.3 Solaris メッセージカタログ機構のサポート Up: 6.27.2 クラスに基づいた API Next: 6.27.3 プログラムやモジュールを国際化する


6.27.3.1 モジュールを地域化する

モジュールを地域化する場合、グローバルな変更、例えば組み込み名前空間 への変更を行わないように注意しなければなりません。GNU gettext API ではなく、クラスベースの API を使うべきです。

仮に対象のモジュール名を ``spam'' とし、モジュールの各言語における 翻訳が収められた .mo ファイルが /usr/share/locale に GNU gettext 形式で置かれているとします。 この場合、モジュールの最初で以下のようにします:

import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.gettext

翻訳オブジェクトが .po ファイル中の Unicode 文字列を返す ようになっているのなら、上の代わりに以下のようにします:

import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.ugettext

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.27.3 プログラムやモジュールを国際化する Up: 6.27.3 プログラムやモジュールを国際化する Next: 6.27.3.2 アプリケーションを地域化する


6.27.3.2 アプリケーションを地域化する

アプリケーションを地域化するのなら、関数 _() を グローバルな組み込み名前空間に組み入れなければならず、これは 通常アプリケーションの主ドライバ (main driver) ファイル で 行います。この操作によって、アプリケーション独自のファイルは 明示的に各ファイルで _() の組み入れを行わなくても 単に _('...') を使うだけで済むようになります。

単純な場合では、単に以下の短いコードをアプリケーションの 主ドライバファイルに追加するだけです:

import gettext
gettext.install('myapplication')

ロケールディレクトリや unicode フラグを設定する必要が ある場合、それらの値を install() 関数に渡すことが できます:

import gettext
gettext.install('myapplication', '/usr/share/locale', unicode=1)

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.27.3.1 モジュールを地域化する Up: 6.27.3 プログラムやモジュールを国際化する Next: 6.27.3.3 動作中 (on the


6.27.3.3 動作中 (on the fly) に言語を切り替える

多くの言語を同時にサポートする必要がある場合、複数の翻訳インスタンスを 生成して、例えば以下のコード:

import gettext

lang1 = gettext.translation(languages=['en'])
lang2 = gettext.translation(languages=['fr'])
lang3 = gettext.translation(languages=['de'])

# start by using language1
lang1.install()

# ... time goes by, user selects language 2
lang2.install()

# ... more time goes by, user selects language 3
lang3.install()

のように、インスタンスを明示的に切り替えてもかまいません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.27.3.2 アプリケーションを地域化する Up: 6.27.3 プログラムやモジュールを国際化する Next: 6.27.3.4 翻訳処理の遅延解決


6.27.3.4 翻訳処理の遅延解決

コードを書く上では、ほとんどの状況で文字列はコードされた場所で 翻訳されます。しかし場合によっては、翻訳対象として文字列をマーク はするが、その後実際に翻訳が行われるように遅延させる必要が 生じます。古典的な例は以下のようなコートです:

animals = ['mollusk',
           'albatross',
       'rat',
       'penguin',
       'python',
       ]
# ...
for a in animals:
    print a

ここで、リスト animals 内の文字列は翻訳対象としてマーク はしたいが、文字列が出力されるまで実際に翻訳を行うのは避けたい とします。

こうした状況を処理する一つの方法を以下に示します:

def _(message): return message

animals = [_('mollusk'),
           _('albatross'),
       _('rat'),
       _('penguin'),
       _('python'),
       ]

del _

# ...
for a in animals:
    print _(a)

ダミーの _() 定義が単に文字列をそのまま返すように なっているので、上のコードはうまく動作します。かつ、このダミーの 定義は、組み込み名前空間に置かれた _() の定義で (del 命令を実行するまで) 一時的に上書きすることが できます。もしそれまでに _ をローカルな名前空間に 持っていたら注意してください。

二つ目の例における _() の使い方では、``a'' は文字列 リテラルではないので、pygettext プログラムが翻訳可能な 対象として識別しません。

もう一つの処理法は、以下の例のようなやり方です:

def N_(message): return message

animals = [N_('mollusk'),
           N_('albatross'),
       N_('rat'),
       N_('penguin'),
       N_('python'),
       ]

# ...
for a in animals:
    print _(a)

この例の場合では、翻訳可能な文字列を関数 N_() で マーク付けしており 6.6 、_() の定義とは全く衝突しません。しかしメッセージ 展開プログラムには翻訳対象の文字列が N_() でマーク されていることを教える必要が出てくるでしょう。 pygettext および xpot は両方とも、コマンドライン 上のスイッチでこの機能をサポートしています。

... マーク付けしており6.6
この N_() をどうするかは全くの自由です; MarkThisStringForTranslation() などとしてもかまいません。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.27.3.3 動作中 (on the Up: 6.27.3 プログラムやモジュールを国際化する Next: 6.27.4 謝辞


6.28.2.1 StreamHandler

StreamHandler クラスはログ出力を sys.stdout、 sys.stderr あるいは何らかのファイル類似オブジェクト (あるいは、もっと正確にいえば、write() および flush() メソッドをサポートする何らかのオブジェクト) といったストリーム に送信します。

class StreamHandler( [strm])
StreamHandler クラスの新たなインスタンスを返します。 strm が指定された場合、インスタンスはログ出力先として 指定されたストリームを使います; そうでない場合、 sys.stderr が使われます。

emit( record)
フォーマッタが指定されていれば、フォーマッタを使ってレコードを書式化 します。次に、レコードがストリームに書き込まれ、末端に 改行がつけられます。例外情報が存在する場合、 traceback.print_exception() を使って書式化され、 ストリームの末尾につけられます。

flush( )
ストリームの flush() メソッドを呼び出してバッファを
フラッシュします。close() メソッドは Handler から
継承しているため何も行わないので、flush() 呼び出しを
明示的に行う必要があります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.2 Handler オブジェクト Up: 6.28.2 Handler オブジェクト Next: 6.28.2.2 FileHandler


6.28.2.2 FileHandler

FileHandler クラスはログ出力をディスク上のファイルに 送信します。このクラスは出力機能を StreamHandler から継承 しています。

class FileHandler( filename[, mode])
FileHandler クラスの新たなインスタンスを返します。 指定されたファイルが開かれ、ログ記録のためのストリームとして 使われます。mode が指定されなかった場合、 'a' が使われます。デフォルトでは、ファイルは無制限に大きくなりつづけます。

close( )
ファイルを閉じます。

emit( record)
record をファイルに出力します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.2.1 StreamHandler Up: 6.28.2 Handler オブジェクト Next: 6.28.2.3 RotatingFileHandler


6.28.2.3 RotatingFileHandler

RotatingFileHandler クラスはディスク上のログファイルに対する ローテーション処理をサポートします。

class RotatingFileHandler( filename[, mode[, maxBytes[, backupCount]]])
RotatingFileHandler クラスの新たなインスタンスを返します。 指定されたファイルが開かれ、ログ記録のためのストリームとして 使われます。mode が指定されなかった場合、 "a" が使われます。デフォルトでは、ファイルは無制限に大きくなりつづけます。

あらかじめ決められたサイズでファイルをロールオーバ (rollover) させられるように、maxBytes および backupCount 値を 指定することができます。指定サイズを超えそうになると、ファイルは 閉じられ、暗黙のうちに新たなファイルが開かれます。ロールオーバは 現在のログファイルの長さが maxBytes に近くなると常に起きます。 backupCount が非ゼロの場合、システムは古いログファイルを ファイル名に ".1", ".2" といった拡張子を追加して保存します． 例えば、backupCount が 5 で、基本のファイル名が app.log なら、 app.log、 app.log.1、 app.log.2、 ... と続き、 app.log.5 までを得ることになります。ログの書き込み対象になる ファイルは常に app.log です。このファイルが満杯になると、 ファイルは閉じられ、app.log.1 に名称変更されます。 app.log.1、app.log.2 などが存在する場合、それらの ファイルはそれぞれapp.log.2、app.log.3 といった具合に 名前変更されます。

doRollover( )
上で記述したようにして、ロールオーバを行います。

emit( record)
setRollover() で記述したようなロールオーバを行いながら、 レコードをファイルに出力します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.2.2 FileHandler Up: 6.28.2 Handler オブジェクト Next: 6.28.2.4 SocketHandler


6.28.2.4 SocketHandler

SocketHandler クラスはログ出力をネットワークソケットに 送信します。基底クラスでは TCP ソケットを用います。

class SocketHandler( host, port)
アドレスが host および port で与えられた遠隔のマシン と通信するようにした SocketHandler クラスのインスタンスを 生成して返します。

close( )
ソケットを閉じます。

handleError( )

emit( )
レコードの属性辞書を pickle 化し、バイナリ形式でソケットに書き込み ます。ソケット操作でエラーが生じた場合、暗黙のうちにパケットは 捨てられます。前もって接続が失われていた場合、接続を再度確立 します。受信端でレコードを逆 pickle 化して LogRecord にするには、 makeLogRecord 関数を使ってください。

handleError( )
emit() の処理中に発生したエラーを処理します。 よくある原因は接続の消失です。次のイベント発生時に再度 接続確立を試みることができるようにソケットを閉じます。

makeSocket( )
サブクラスで必要なソケット形式を詳細に定義できるようにするための ファクトリメソッドです。デフォルトの実装では、TCP ソケット (socket.SOCK_STREAM) を生成します。

makePickle( record)
レコードの属性辞書を pickle 化して、長さを指定プレフィクス付きの バイナリにし、ソケットを介して送信できるようにして返します。

send( packet)
pickle 化された文字列 packet をソケットに送信します。 この関数はネットワークが処理待ち状態の時に発生しうる部分的送信を 行えます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.2.3 RotatingFileHandler Up: 6.28.2 Handler オブジェクト Next: 6.28.2.5 DatagramHandler


6.28.2.5 DatagramHandler

DatagramHandler クラスは SocketHandler を 継承しており、ログ記録メッセージを UDP ソケットを介して 送れるようサポートしています。

class DatagramHandler( host, port)
アドレスが host および port で与えられた遠隔のマシン と通信するようにした DatagramHandler クラスのインスタンスを 生成して返します。

emit( )
レコードの属性辞書を pickle 化し、バイナリ形式でソケットに書き込み ます。ソケット操作でエラーが生じた場合、暗黙のうちにパケットは 捨てられます。前もって接続が失われていた場合、接続を再度確立 します。受信端でレコードを逆 pickle 化して LogRecord にするには、 makeLogRecord 関数を使ってください。

makeSocket( )
ここで SocketHandler のファクトリメソッドをオーバライド して UDP ソケット (socket.SOCK_DGRAM) を生成しています。

send( s)
pickle 化された文字列をソケットに送信します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.2.4 SocketHandler Up: 6.28.2 Handler オブジェクト Next: 6.28.2.6 SysLogHandler


6.28.2.6 SysLogHandler

SysLogHandler クラスでは、ログ記録メッセージを遠隔またはローカル の Unix syslog に送信する機能をサポートしています。

class SysLogHandler( [address[, facility]])
遠隔のUnix マシンと通信するための、SysLogHandler クラスの 新たなインスタンスを返します。マシンのアドレスは (host, port) のタプル形式をとる address で与えられます。 address が指定されない場合、('localhost', 514) が 使われます。アドレスは UDP ソケットを使って開かれます。 facility が指定されない場合、LOG_USER が使われます。

close( )
遠隔ホストのソケットを閉じます。

emit( record)
レコードは書式化された後、syslog サーバに送信されます。 例外情報が存在しても、サーバには 送信されません 。

encodePriority( facility, priority)
便宜レベル (facility) および優先度を整数に符号化します。値は文字列 でも整数でも渡すことができます。文字列が渡された場合、内部の 対応付け辞書が使われ、整数に変換されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.2.5 DatagramHandler Up: 6.28.2 Handler オブジェクト Next: 6.28.2.7 NTEventLogHandler


6.28.2.7 NTEventLogHandler

NTEventLogHandler クラスでは、ログ記録メッセージをローカルな Windows NT、Windows 2000 、または Windows XP のイベントログ (event log) に送信する機能をサポートします。この機能を使えるようにするには、 Mark Hammond による Python 用 Win32 拡張パッケージをインストール する必要があります。

class NTEventLogHandler( appname[, dllname[, logtype]])
NTEventLogHandler クラスの新たなインスタンスを返します。 appname はイベントログに表示する際のアプリケーション名を定義する ために使われます。この名前を使って適切なレジストリエントリが生成されます。 dllname はログに保存するメッセージ定義の入った .dll または .exe ファイルへの完全に限定的な (fully qualified) パス名を与えなければ なりません (指定されない場合、'win32service.pyd' が 使われます - このライブラリは Win32 拡張とともにインストールされ、 いくつかのプレースホルダとなるメッセージ定義を含んでいます)。 これらのプレースホルダを利用すると、メッセージの発信源全体がログに 記録されるため、イベントログは巨大になるので注意してください。 logtype は 'Application'、 'System' または 'Security' のいずれかであるか、デフォルトの 'Application' でなければなりません。

close( )
現時点では、イベントログエントリの発信源としての アプリケーション名をレジストリから除去することができます。 しかしこれを行うと、イベントログビューアで意図したログをみることが できなくなるでしょう - これはイベントログが .dll 名を取得するために レジストリにアクセスできなければならないからです。現在のバージョン ではこの操作を行いません (実際、このメソッドは何も行いません)。

emit( record)
メッセージ ID、イベントカテゴリおよびイベント型を決定し、 メッセージを NT イベントログに記録します。

getEventCategory( record)
レコードに対するイベントカテゴリを返します。自作のカテゴリを 指定したい場合、このメソッドをオーバライドしてください。 このクラスのバージョンのメソッドは 0 を返します。

getEventType( record)
レコードのイベント型を返します。自作の型を指定したい場合、 このメソッドをオーバライドしてください。 このクラスのバージョンのメソッドは、ハンドラの typemap 属性を 使って対応付けを行います。この属性は __init__() で初期化 され、DEBUG、INFO、 WARNING、 ERROR、および CRITICAL が入っています。 自作のレベルを使っているのなら、このメソッドをオーバライドするか、 ハンドラの typemap 属性に適切な辞書を配置する必要があるでしょう。

getMessageID( record)
レコードのメッセージ ID を返します。自作のメッセージを使っているの なら、ロガーに渡されるmsg を書式化文字列ではなく ID に します。その上で、辞書参照を行ってメッセージ ID を得ます。 このクラスのバージョンでは 1 を返します。この値は win32service.pyd における基本となるメッセージ ID です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.2.6 SysLogHandler Up: 6.28.2 Handler オブジェクト Next: 6.28.2.8 SMTPHandler


6.28.2.8 SMTPHandler

SMTPHandler クラスでは、SMTP を介したログ記録メッセージの 送信機能をサポートします。

class SMTPHandler( mailhost, fromaddr, toaddrs, subject)
新たな SMTPHandler クラスのインスタンスを返します。 インスタンスは email の from および to アドレス行、および subject 行と ともに初期化されます。 toaddrs はドメイン名 (mailost )を含まない文字列からなるリストで なければなりません 非標準の SMTP ポートを指定するには、mailhost 引数に (host, port) のタプル形式を指定します。文字列を使った場合、標準の SMTP ポートが 使われます。

emit( record)
レコードを書式化し、指定されたアドレスに送信します。

getSubject( record)
レコードに応じたサブジェクト行を指定したいなら、このメソッドを オーバライドしてください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.2.7 NTEventLogHandler Up: 6.28.2 Handler オブジェクト Next: 6.28.2.9 MemoryHandler


6.28.2.9 MemoryHandler

MemoryHandler では、ログ記録するレコードをメモリ上にバッファし、 定期的にその内容をターゲット (target) となるハンドラに フラッシュする機能をサポートしています。 フラッシュ処理はバッファが一杯になるか、ある深刻さかそれ以上のレベル をもったイベントが観測された際に行われます。

MemoryHandler はより一般的な抽象クラス、 BufferingHandler のサブクラスです。この抽象クラスでは、 ログ記録するレコードをメモリ上にバッファします。各レコードがバッファに 追加される毎に、shouldFlush() を呼び出してバッファをフラッシュ すべきかどうか調べます。フラッシュする必要がある場合、flush() が必要にして十分な処理を行うものと想定しています。

class BufferingHandler( capacity)
指定し許容量のバッファでハンドラを初期化します。

emit( record)
レコードをバッファに追加します。 shouldFlush() が真を 返す場合、バッファを処理するために flush() を呼び出します。

flush( )
このメソッドをオーバライドして、自作のフラッシュ動作を実装することが できます。このクラスのバージョンのメソッドでは、単にバッファの内容を 削除して空にします。

shouldFlush( record)
バッファが許容量に達している場合に真を返します。このメソッドは 自作のフラッシュ処理方針を実装するためにオーバライドすることが できます。

class MemoryHandler( capacity[, flushLevel [, target]])
MemoryHandler クラスの新たなインスタンスを返します。 インスタンスはサイズ capacity のバッファとともに初期化されます。 flushLevel が指定されていない場合、ERROR が使われます。 target が指定されていない場合、ハンドラが何らかの有意義な 処理を行う前に setTarget() でターゲットを指定する必要があります。

close( )
flush() を呼び出し、ターゲットを None に 設定してバッファを消去します。

flush( )
MemoryHandler の場合、フラッシュ処理は単に、バッファされた レコードをターゲットがあれば送信することを意味します。 違った動作を行いたい場合、オーバライドしてください。

setTarget( target)
ターゲットハンドラをこのハンドラに設定します。

shouldFlush( record)
バッファが満杯になっているか、 flushLevel またはそれ以上の レコードでないかを調べます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.2.8 SMTPHandler Up: 6.28.2 Handler オブジェクト Next: 6.28.2.10 HTTPHandler


6.28.2.10 HTTPHandler

HTTPHandler クラスでは、ログ記録メッセージを "GET" または "POST" セマンティクスを使って Web サーバに送信する機能をサポートしています。

class HTTPHandler( host, url[, method])
HTTPHandler クラスの新たなインスタンスを返します。 インスタンスはホストアドレス、URL および HTTP メソッドと ともに初期化されます。method が指定されなかった場合 "GET" が使われます。

emit( record)
レコードを URL エンコードされた辞書形式で Web サーバに送信します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.2.9 MemoryHandler Up: 6.28.2 Handler オブジェクト Next: 6.28.3 Formatter オブジェクト


6.28.7.1 環境設定のための関数

以下の関数では、logging モジュールを環境設定できるようにします。 これらの関数を使えるようにするには、logging.config を import しなければなりません。これらの関数の使用はオプションです - logging モジュールは全て、 (logging 自体で 定義されている) 主要な API を呼び出し、 logging か logging.handlers で宣言されているハンドラを定義することで 設定することができます。

fileConfig( fname[, defaults])
ログ記録の環境設定をファイル名 fname の ConfigParser 形式ファイル から読み出します。この関数はアプリケーションから何度も呼び出すことが でき、これによって、(設定の選択と、選択された設定を読み出す機構を デベロッパが提供していれば) 複数のお仕着せの設定からエンドユーザが 選択するようにできます。ConfigParser に渡すためのデフォルト値は defaults 引数で指定できます。

listen( [port])
指定されたポートでソケットサーバを開始し、新たな設定を待ち受け (listen) ます。ポートが指定されなければ、モジュールのデフォルト設定 である DEFAULT_LOGGING_CONFIG_PORT が使われます。 ログ記録の環境設定は fileConfig() で処理できるような ファイルとして送信されます。 Thread インスタンスを返し、サーバを開始するために start() を呼び、適切な状況で join() を 呼び出すことができます。サーバを停止するには stopListening() を呼んでください。

stopListening( )
listen() を呼び出して作成された、待ち受け中のサーバを 停止します。通常 listen() の戻り値に対して join() が呼ばれる前に呼び出します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.7 環境設定 Up: 6.28.7 環境設定 Next: 6.28.7.2 環境設定ファイルの書式


6.28.7.2 環境設定ファイルの書式

fileConfig が解釈できる環境設定ファイルの形式は、 ConfigParser の機能に基づいています。 ファイルには、[loggers]、 [handlers]、および [formatters] といったセクションが入っていなければならず、 各セクションではファイル中で定義されている各タイプのエンティティを 名前で指定しています。こうしたエンティティの各々について、 そのエンティティをどう設定するかを示した個別のセクションがあります。 すなわち、log01 という名前の [loggers] セクションにある ロガーに対しては、対応する詳細設定がセクション [logger_log01] に収められています。同様に、 hand01 という名前の [handlers] セクションにあるハンドラは [handler_hand01] と呼ばれるセクションに設定をもつことになり、[formatters] セクションにある form01 は [formatter_form01] というセクションで設定が指定されています。ルートロガーの 設定は [logger_root] と呼ばれるセクションで指定 されていなければなりません。

ファイルにおけるこれらのセクションの例を以下に示します。

[loggers]
keys=root,log02,log03,log04,log05,log06,log07

[handlers]
keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09

[formatters]
keys=form01,form02,form03,form04,form05,form06,form07,form08,form09

ルートロガーでは、レベルとハンドラのリストを指定しなければ なりません。ルートロガーのセクションの例を以下に示します。

[logger_root]
level=NOTSET
handlers=hand01

level エントリは DEBUG, INFO, WARNING, ERROR, CRITICAL のうちの一つか、NOTSET になります。ルートロガーの場合にのみ、 NOTSET は全てのメッセージがログ記録されることを意味します。 レベル値は logging パッケージの名前空間のコンテキストに おいて eval() されます。

handlers エントリはコンマで区切られたハンドラ名からなる リストで、[handlers] セクションになくてはなりません。 また、これらの各ハンドラの名前に対応するセクションが設定ファイルに 存在しなければなりません。

ルートロガー以外のロガーでは、いくつか追加の情報が必要になります。 これは以下の例のように表されます。

[logger_parser]
level=DEBUG
handlers=hand01
propagate=1
qualname=compiler.parser

level および handlers エントリはルートロガーのエントリ と同様に解釈されますが、非ルートロガーのレベルが NOTSET に指定された場合、ログ記録システムはロガー階層のより上位のロガー にロガーの実効レベルを問い合わせるところが違います。 propagate エントリは、メッセージをロガー階層におけるこの ロガーの上位のハンドラに伝播させることを示す 1 に設定されるか、 メッセージを階層の上位に伝播しない ことを示す 0 に 設定されます。 qualname エントリはロガーのチャネル名を階層的に表した もので、例えばアプリケーションがこのロガーを取得する際に使う 名前になります。

ハンドラの環境設定を指定しているセクションは以下の例のようになります。

[handler_hand01]
class=StreamHandler
level=NOTSET
formatter=form01
args=(sys.stdout,)

class エントリはハンドラのクラス (logging パッケージの 名前空間において eval() で決定されます) を示します。 level はロガーの場合と同じように解釈され、NOTSET は "全てを記録する (log everything)" と解釈されます。

formatter エントリはこのハンドラのフォーマッタに対するキー名 を表します。空文字列の場合、デフォルトのフォーマッタ (logging._defaultFormatter) が使われます。名前が指定 されている場合、その名前は [formatters] セクションになくては ならず、対応するセクションが設定ファイル中になければなりません。

args エントリは、logging パッケージの名前空間の コンテキストで eval() される際、ハンドラクラスの コンストラクタに対する引数からなるリストになります。 典型的なエントリがどうやって作成されるかについては、対応するハンドラのコンストラクタか、以下の例を参照してください。

[handler_hand02]
class=FileHandler
level=DEBUG
formatter=form02
args=('python.log', 'w')

[handler_hand03]
class=handlers.SocketHandler
level=INFO
formatter=form03
args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)

[handler_hand04]
class=handlers.DatagramHandler
level=WARN
formatter=form04
args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)

[handler_hand05]
class=handlers.SysLogHandler
level=ERROR
formatter=form05
args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)

[handler_hand06]
class=NTEventLogHandler
level=CRITICAL
formatter=form06
args=('Python Application', '', 'Application')

[handler_hand07]
class=SMTPHandler
level=WARN
formatter=form07
args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')

[handler_hand08]
class=MemoryHandler
level=NOTSET
formatter=form08
target=
args=(10, ERROR)

[handler_hand09]
class=HTTPHandler
level=NOTSET
formatter=form09
args=('localhost:9022', '/log', 'GET')

フォーマッタの環境設定を指定しているセクションは以下のような形式です。

[formatter_form01]
format=F1 %(asctime)s %(levelname)s %(message)s
datefmt=

format エントリは全体を書式化する文字列で、datefmt エントリは strftime() 互換の日付/時刻書式化文字列です。 空文字列の場合、パッケージによって ISO8601 形式の 日付/時刻に置き換えられ、 日付書式化文字列 "ISO8601 形式ではミリ秒も指定しており、上の書式化文字列の結果にカンマ で区切って追加されます。ISO8601 形式の時刻の例は 2003-01-23 00:29:50,411 です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.7.1 環境設定のための関数 Up: 6.28.7 環境設定 Next: 6.28.8 Using the logging


6.28.8.1 Basic example - log to a file

ログをファイルに記録する例を、以下に示します。この例では Logger インスタンスを作り、その後 FileHandler とFormatter を作 ります。続いて FileHandler に Formatter を付加し、 Logger に FileHandler を付加します。最後に、ロガーのデバ ッグ・レベルを設定します。

import logging
logger = logging.getLogger('myapp')
hdlr = logging.FileHandler('/var/tmp/myapp.log')
formatter = logging.Formatter('%(asctime)s %(levelname)s %(message)s')
hdlr.setFormatter(formatter)
logger.addHandler(hdlr)
logger.setLevel(logging.WARNING)

このロガーオブジェクトを使うと、エントリをログファイルに書き出せます。

logger.error('We have a problem')
logger.info('While this is just chatty')

書き出されたファイルの中には、次のように書かれているでしょう。

2003-07-08 16:49:45,896 ERROR We have a problem

info メッセージは、ファイルに書き出されません。setLevel メソッドで WARNING 以上のログだけを要求したので、info メッセージは捨てられたのです。

タイムスタンプは ``year-month-day hour:minutes:seconds,milliseconds'' 形 式です。ミリ秒のフィールドは 3桁ありますが、全てのシステムにおいて、この 精度で時刻を得られるわけではありません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.28.8 Using the logging Up: 6.28.8 Using the logging Next: 7. オプションのオペレーティングシステムサービス


12.2.1.1 推奨されないメソッド

以下のメソッドは email バージョン 2 ではもはや時代遅れとなっており、 推奨されません。万全を記すためここに記載しておきます。

add_payload( payload)
そのメッセージオブジェクトに存在するペイロードに payload を追加します。 もしこのメソッドを呼ぶ前にそのメッセージのペイロードが None だった (つまり一度もセットされていない) 場合、呼び出し後のペイロードは引数 payload になります。

もしそのメッセージのペイロードがリストだった (つまり is_multipart() が 1 を返した) 場合、 すでに存在するペイロードのリストの末尾に payload が付加されます。

ペイロードがこれ以外の形式だった場合、add_payload() は 新しいペイロードを古いペイロードと payload からなる リストに自動的に変換します。が、これはそのドキュメントが すでに MIME multipart ドキュメントであるときだけです。 この条件が満たされるのはそのメッセージの Content-Type: ヘッダの 主形式 (maintype) が multipart であるときか、 あるいはそのメッセージに Content-Type: がないときだけです。 これ以外の場合、メソッドは MultipartConversionError を発生します。

リリース 2.2.2 以降で撤廃された仕様です。 これのかわりに attach() メソッドを使ってください。

get_type( [failobj])
そのメッセージの content-type を Content-Type: ヘッダから 取得した maintype/subtype という 形式の文字列で返します。 取得した文字列は強制的に小文字に変換されます。

そのメッセージ中に Content-Type: ヘッダが 存在しなかった場合、 failobj (デフォルトは None) が返されます。

リリース 2.2.2 以降で撤廃された仕様です。 これのかわりに get_content_type() メソッドを使ってください。

get_main_type( [failobj])
そのメッセージの 主 content-type を返します。 これは get_type() によって 返される文字列の maintype 部分です。 failobj の働きは get_type() と同じです。

リリース 2.2.2 以降で撤廃された仕様です。 これのかわりに get_content_maintype() メソッドを使ってください。

get_subtype( [failobj])
そのメッセージの副 content-type (sub content-type、subtype) を返します。 これは get_type() によって 返される文字列の subtype 部分です。 failobj の働きは get_type() と同じです。

リリース 2.2.2 以降で撤廃された仕様です。 これのかわりに get_content_subtype() メソッドを使ってください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.1 電子メールメッセージの表現 Up: 12.2.1 電子メールメッセージの表現 Next: 12.2.2 電子メールメッセージを解析(パース)する


12.2.2.1 Parser クラスの API

class Parser( [_class[, strict]])
Parser クラスのコンストラクタです。 オプション引数 _class をとることができ、これは呼び出し可能な オブジェクト (関数やクラス) でなければならず、 メッセージ内コンポーネント (sub-message object) が作成されるときは いつでもその“工場”として使用できなければなりません。 デフォルトではこれは Message になっています (email.Message 参照)。この“工場”は引数なしで呼び出されます。

オプション引数である strict フラグは、strict 解析と lax 解析の どちらをおこなうかを指定します。MIME 終端文字列が欠けているとか、 メッセージにその他の書式上の問題がある場合、Parser は MessageParseError を発生させます。しかし、lax 解析が 有効になっている場合、Parser は崩れた書式からなんとかして 有効なメッセージ構造を生成しようと試みます (これは MessageParseError が 絶対に発生しないということではありません、ある種の異常な書式の メッセージはやはり解析できません)。デフォルトでは、strict フラグは False になっています。これは通常 lax 解析がもっとも理にかなった ふるまいを提供するためです。

バージョン2.2.2 以降で変更された 仕様: strict フラグが追加されました

それ以外の Parser メソッドは以下のとおりです:

parse( fp[, headersonly])
ファイルなどストリーム形式 12.1 のオブジェクト fp から すべてのデータを読み込み、得られたテキストを解析して基底 (root) メッセージ オブジェクト構造を返します。fp はストリーム形式のオブジェクトで readline() および read() 両方のメソッドを サポートしている必要があります。

fp に格納されているテキスト文字列は、一連の RFC 2822 形式の ヘッダおよびヘッダ継続行 (header continuation lines) によって構成されている 必要があります。オプションとして、最初にエンペローブヘッダが来ることもできます。 ヘッダ部分はデータの終端か、ひとつの空行によって終了したとみなされます。 ヘッダ部分に続くデータはメッセージ本体となります (MIME エンコードされた subpart を含んでいるかもしれません)。

オプション引数 headersonly はヘッダ部分を解析しただけで終了するか 否かを指定します。デフォルトの値は False で、これはそのファイルの 内容すべてを解析することを意味しています。

バージョン2.2.2 以降で変更された 仕様: headersonly フラグが追加されました

parsestr( text[, headersonly])
メソッドに似ていますが、ファイルなどのストリーム形式のかわりに 文字列を引数としてとるところが違います。文字列に対してこのメソッドを 呼ぶことは、text を StringIO インスタンスとして作成して parse() を適用するのと同じです。

オプション引数 headersonly は parse() メソッドと同じです。

バージョン2.2.2 以降で変更された 仕様: headersonly フラグが追加されました

ファイルや文字列からメッセージオブジェクト構造を作成するのは かなりよくおこなわれる作業なので、便宜上次のような 2つの関数が 提供されています。これらは email パッケージのトップレベルの 名前空間で使用できます。

message_from_string( s[, _class[, strict]])
文字列からメッセージオブジェクト構造を作成し返します。 これは Parser().parsestr(s) とまったく同じです。 オプション引数 _class および strict は Parser クラスの コンストラクタと同様に解釈されます。

バージョン2.2.2 以降で変更された 仕様: strict フラグが追加されました

message_from_file( fp[, _class[, strict]])
Open されたファイルオブジェクトからメッセージオブジェクト構造を作成し返します。 これは Parser().parse(fp) とまったく同じです。 オプション引数 _class および strict は Parser クラスの コンストラクタと同様に解釈されます。

バージョン2.2.2 以降で変更された 仕様: strict フラグが追加されました

対話的な Python プロンプトでこの関数を使用するとすれば、このようになります:

>>> import email
>>> msg = email.message_from_string(myString)

... ファイルなどストリーム形式12.1
file-like object
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.2 電子メールメッセージを解析(パース)する Up: 12.2.2 電子メールメッセージを解析(パース)する Next: 12.2.2.2 追加事項


12.2.2.2 追加事項

以下はテキスト解析の際に適用されるいくつかの規約です:

  • ほとんどの 非multipart形式のメッセージは単一の文字列ペイロードをもつ 単一のメッセージオブジェクトとして解析されます。このオブジェクトは is_multipart() に対して False を返します。このオブジェクトに 対する get_payload() メソッドは文字列オブジェクトを返します。

  • multipart形式のメッセージはすべてメッセージ内 コンポーネント (sub-message object) のリストとして解析されます。 外側のコンテナメッセージオブジェクトは is_multipart() に対して True を返し、このオブジェクトに対する get_payload() メソッドは Message subpart のリストを返します。

  • message/* の Content-Type をもつほどんどのメッセージ (例: message/deliver-status や message/rfc822 など) も コンテナメッセージオブジェクトとして解析されますが、 ペイロードのリストの長さは 1 になります。このオブジェクトは is_multipart() メソッドに対して True を返し、 リスト内にあるひとつだけの要素がメッセージ内のコンポーネントオブジェクトになります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.2.1 Parser クラスの API Up: 12.2.2 電子メールメッセージを解析(パース)する Next: 12.2.3 MIME 文書を生成する


12.2.3.1 Deprecated methods

以下のメソッドは email バージョン 2 ではもはや時代遅れとなっており、 推奨されません。万全を記すためここに記載しておきます。

__call__( msg[, unixfrom])

このメソッドは flatten() メソッドと同じです。

リリース 2.2.2 以降で撤廃された仕様です。 これのかわりに flatten() メソッドを使ってください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 12.2.3 MIME 文書を生成する Up: 12.2.3 MIME 文書を生成する Next: 12.2.4 電子メールおよび MIME オブジェクトをゼロから作成する


16.1.2.1 この節の使い方

この節は二つの部分からできています: 最初の半分は(大雑把に)背景となる事柄を対象としています。二番目の半分はすぐ手に届くリファレンスとしてキーボードのところへ持って行くことができます。

``blahするにはどうしたら良いのだろうか''という形の問いに答えるとき、Tkそのもので``blah''する方法を調べてから、対応するTkinter呼び出しへ変換するのがもっとも良いということがよくあります。PythonプログラマがTkドキュメンテーションを見ると、たいてい正しいPythonコマンドの見当をつけることができます。これが意味するのは、Tkinterを使うにはTkについてほんの少しだけ知っていなければならないということです。このドキュメントはその役割を果たすことができていません。だから、我々にできるのは、既存の最も良いドキュメンテーションをあなたに示すことです。ここにはいくつものヒントがあります:

  • 著者たちはTkのmanページのコピーを手に入れることを強く勧めています。特に、mannディレクトリ内のmanページはもっとも役に立ちます。man3 manページはTkライブラリに対するCインターフェイスについて説明しており、従って、スクリプト書きにとって特に役に立つ訳ではありません。

  • Addison-WesleyはJohn Ousterhoutが書いたTcl and the Tk Toolkit (ISBN 0-201-63337-X)という名前の本を出版しており、初心者にとってはTclとTkへの良い入門書です。この本は網羅的なものではなく、細部の多くでmanページに沿ったものです。

  • Tkinter.pyを見るのはほとんどの場合に最後の手段ですが、他に何も意味をなさないときには行ってみると良い場所であることもあるでしょう。

参考資料:

ActiveState Tclホームページ
Tk/Tclの開発の大部分はActiveStateで行われています。
Tcl and the Tk Toolkit
Tclの発明者であるJohn Ousterhoutが書いた本。
Practical Programming in Tcl and Tk
百科事典のようなBrent Welchの本。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.2 Tkinter Life Preserver Up: 16.1.2 Tkinter Life Preserver Next: 16.1.2.2 簡単なHello Worldプログラム


16.1.2.2 簡単なHello Worldプログラム

from Tkinter import *

class Application(Frame):
    def say_hi(self):
        print "hi there, everyone!"

    def createWidgets(self):
        self.QUIT = Button(self)
        self.QUIT["text"] = "QUIT"
        self.QUIT["fg"]   = "red"
        self.QUIT["command"] =  self.quit

        self.QUIT.pack({"side": "left"})

        self.hi_there = Button(self)
        self.hi_there["text"] = "Hello",
        self.hi_there["command"] = self.say_hi

        self.hi_there.pack({"side": "left"})

    def __init__(self, master=None):
        Frame.__init__(self, master)
        self.pack()
        self.createWidgets()

app = Application()
app.mainloop()

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.2.1 この節の使い方 Up: 16.1.2 Tkinter Life Preserver Next: 16.1.3 Tcl/Tkに(非常に)さっと目を通す


16.1.6.2 Packer

packerはTkのジオメトリマネジメント・メカニズムの一つです。the Packer class interfaceも参照してくだい。

ジオメトリマネージャは、コンテナ - ウィジェットが共有するマスター(上位のウィジェット) - 内部のウィジェットの相対的な位置を指定するために用いられます。もっと扱いにくいplacer(packerより一般的に使われておらず、ここで取り上げません)とは対照的に、packerは定性的な関係の指定を受け取ります - 上、～の左、引き延ばしなど - そして、あなたのために厳密な座標位置が決まるようにすべてを調整します。

どんなマスターウィジェットでもその大きさは内部の"スレイブウィジェット"の大きさによって決まります。スレイブウィジェットがpackされるマスター内部で表示される場所を制御するためにpackerが用いられます。だいたいあなたが望んだ通りのレイアウトになるように、ウィジェットをフレーム内部へ、さらに、フレームは別のフレーム内部へpackすることがきます。さらに、一度packされると、追加の設定変更に合わせるために並べ方は動的に調整されます。

ジオメトリマネージャによってウィジェットのジオメトリが確定されるまで、ウィジェットが表示されないことに注意してください。ジオメトリを確定するのを忘れるというのは初めのころによくやってしまう間違いで、そういうときにウィジェットが作られたのに何も表示されず驚くことになります。ウィジェットはジオメトリ確定された(例えばpackerのpack()メソッドを適用された)後にのみ表示されます。

pack()メソッドを呼び出す時に、ウィジェットがそのコンテナ内部で表示される場所とメイン・アプリケーション・ウィンドウのサイズが変更されたときにどうするかを制御するためのキーワードオプション/値の組を指定することができます。いくつか例を示します:

    fred.pack()                     # デフォルトでは、side = "top"
    fred.pack(side = "left")
    fred.pack(expand = 1)

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.6.1 オプションの設定 Up: 16.1.6 便利なリファレンス Next: 16.1.6.3 Packer Options


16.1.6.3 Packer Options

packerとその取り得るオプションについてのより多くの情報を得るには、manページとJohn Ousterhoutの本の183ページを参照してください。

anchor
アンカー型。 packerが区画内に各スレイブを配置する位置を示します。

expand
ブール値、0または1。

fill
指定できる値: 'x'、'y'、'both'、'none'。

ipadxとipady
距離 - スレイブウィジェットのそれぞれの面の内部パッドを指定します。

padxとpady
距離 - スレイブウィジェットのそれぞれの面の外部パッドを指定します。

side
指定できる値は: 'left', 'right', 'top', 'bottom'。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.6.2 Packer Up: 16.1.6 便利なリファレンス Next: 16.1.6.4 ウィジェット変数を結びつける


16.1.6.4 ウィジェット変数を結びつける

(テキストエントリ・ウィジェットのような)いくつかのウィジェットの現在の値の設定は特別なオプションを使うことでアプリケーション変数に直接関連付けられています。これらのオプションとはvariable、textvariable、onvalue、offvalueおよびvalueです。この関連付けは双方向に機能します: 変数が何らかの理由で変化した場合は、それが関連付けられているウィジェットは新しい値を反映するように更新される。

不幸なことに、Tkinterの現在の実装では、任意のPython変数をウィジェットにvariableあるいはtextvariableオプションを通して渡すことができません。これが機能するような変数のただ一つの種類は、Tkinterで定義されているVariableと呼ばれるクラスからサブクラス化された変数です。

既に定義された多くの便利なVariableのサブクラスがあります: StringVar、IntVar、DoubleVarおよびBooleanVar。このような変数の現在の値を読むためには、それのget()メソッドを呼び出し下さい。また、その値を変更するには、set()メソッドを呼び出します。あなたがこのプロトコルに従えば、あなた側のこれ以上の介入が無くてもウィジェットは常に変数の値を追跡記録します。

例えば:

class App(Frame):
    def __init__(self, master=None):
        Frame.__init__(self, master)
        self.pack()

        self.entrythingy = Entry()
        self.entrythingy.pack()

        self.button.pack()
        # ここではアプリケーション変数
        self.contents = StringVar()
        # それをある値に設定します
        self.contents.set("this is a variable")
        # エントリウィジェットにこの変数を監視するように指示します
        self.entrythingy["textvariable"] = self.contents

        # そして、ここではユーザがリターンを押したときにコールバックを得ます。
        # ユーザがリターンを押したときに、アプリケーション変数の値を表示する
        # プログラムとなります。
        self.entrythingy.bind('<Key-Return>',
                              self.print_contents)

    def print_contents(self, event):
        print "hi. contents of entry is now ---->", \
              self.contents.get()

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.6.3 Packer Options Up: 16.1.6 便利なリファレンス Next: 16.1.6.5 ウィンドウマネージャ


16.1.6.5 ウィンドウマネージャ

Tkには、ウィンドウマネージャとやり取りするために、便利なコマンドwmがあります。wmコマンドへのオプションを使うとタイトル、位置、アイコン・ビットマップなどのようなものをコントロールすることができます。Tkinterでは、これらのコマンドがWmクラスのメソッドとして実装されています。トップレベル・ウィジェットはWmクラスからサブクラス化されるので、直接Wmのメソッドを呼び出します。

与えられたウィジェットを含むトップレベル・ウィンドウを得るために、多くの場合ウィジェットのマスタへ問い合わせることができます。もちろん、ウィジェットがフレームの内部にパックされているならば、マスタはトップレベル・ウィンドウを意味しないでしょう。任意のウィジェットのトップレベル・ウィンドウを得るために、_root()メソッドを呼び出すことができます。このメソッドはこの関数が実装の一部であり、Tk機能へのインターフェイスではないという事実を示す下線で始まっています。

以下に典型的な使い方の例をいくつか挙げます:

import Tkinter
class App(Frame):
    def __init__(self, master=None):
        Frame.__init__(self, master)
        self.pack()

# アプリケーションを作成します
myapp = App()

#
# ここは、ウィンドウマネージャ・クラスへのメソッド呼び出し
#
myapp.master.title("My Do-Nothing Application")
myapp.master.maxsize(1000, 400)

# プログラムを開始します
myapp.mainloop()

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.6.4 ウィジェット変数を結びつける Up: 16.1.6 便利なリファレンス Next: 16.1.6.6 Tkオプションデータ型


16.1.6.6 Tkオプションデータ型

anchor
指定できる値はコンパスの方位です: "n"、"ne"、"e"、"se"、"s"、"sw"、"w"、"nw"、および"center"。

bitmap
八つの組み込み、名前付きビットマップ: 'error'、'gray25'、'gray50'、'hourglass'、'info'、'questhead'、'question'、'warning'。 Xビットマップファイル名を指定するために、"@/usr/contrib/bitmap/gumby.bit"のような@を先頭に付けたファイルへの完全なパスを与えてください。

boolean
整数0または1、あるいは、文字列"yes"または"no"を渡すことができます。

callback
これは引数を取らないPython関数ならどれでも構いません。例えば:
    def print_it():
            print "hi there"
    fred["command"] = print_it

color
色はrgb.txtファイルのXカラーの名前か、またはRGB値を表す文字列として与えられます。RGB値を表す文字列は、4ビット: "#RGB", 8 bit: "#RRGGBB", 12 bit" "#RRRGGGBBB", あるいは、16 bit "#RRRRGGGGBBBB"の範囲を取ります。ここでは、R,G,Bは適切な十六進数ならどんなものでも表します。詳細は、Ousterhoutの本の160ページを参照してください。

cursor
cursorfont.hの標準Xカーソル名を、接頭語XC_無しで使うことができます。例えば、handカーソル(XC_hand2)を得るには、文字列"hand2"を使ってください。あなた自身のビットマップとマスクファイルを指定することもできます。Ousterhoutの本の179ページを参照してください。

distance
スクリーン上の距離をピクセルか絶対距離のどちらかで指定できます。ピクセルは数として与えられ、絶対距離は文字列として与えられます。絶対距離を表す文字列は、単位を表す終了文字(センチメートルにはc、インチにはi、ミリメートルにはm、プリンタのポイントにはp)を伴います。例えば、3.5インチは"3.5i"と表現します。

font
Tkは{courier 10 bold}のようなリストフォント名形式を使います。正の数のフォントサイズはポイント単位で表され。負の数のサイズはピクセル単位で表されます。

geometry
これは"widthxheight"形式の文字列です。ここでは、ほとんどのウィジェットに対して幅と高さピクセル単位で(テキストを表示するウィジェットに対しては文字単位で)表されます。例えば: fred["geometry"] = "200x100"。

justify
指定できる値は文字列です: "left"、"center"、"right"、and "fill"。

region
これは空白で区切られた四つの要素をもつ文字列です。各要素は指定可能な距離です(以下を参照)。例えば: "2 3 4 5"と"3i 2i 4.5i 2i"と"3c 2c 4c 10.43c"は、すべて指定可能な範囲です。

relief
ウィジェットのボーダのスタイルが何かを決めます。指定できる値は: "raised"、"sunken"、"flat"、"groove"、and "ridge"。

scrollcommand
これはほとんど常にスクロールバー・ウィジェットのset()メソッドですが、一引数を取るどんなウィジェットメソッドでもあり得ます。例えば、Pythonソース配布のDemo/tkinter/matt/canvas-with-scrollbars.pyファイルを参照してください。

wrap:
次の中の一つでなければならない: "none"、"char"、あるいは"word"。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.6.5 ウィンドウマネージャ Up: 16.1.6 便利なリファレンス Next: 16.1.6.7 バインドとイベント


16.1.6.7 バインドとイベント

ウィジェットコマンドからのbindメソッドによって、あるイベントを待つことと、そのイベント型が起きたときにコールバック関数を呼び出すことができるようになります。bindメソッドの形式は:

    def bind(self, sequence, func, add=''):
ここでは:

sequence
は対象とするイベントの型を示す文字列です。(詳細については、bindのmanページとJohn Ousterhoutの本の201ページをを参照してください。)

func
は一引数を取り、イベントが起きるときに呼び出されるPython関数です。イベント・インスタンスが引数として渡されます。(このように実施される関数は、一般にcallbacksとして知られています。)

add
はオプションで、""か"+"のどちらかです。 空文字列を渡すことは、このイベントが関係する他のどんなバインドをもこのバインドが置き換えることを意味します。 "+"を使う仕方は、この関数がこのイベント型にバインドされる関数のリストに追加されることを意味しています。

例えば:

    def turnRed(self, event):
        event.widget["activeforeground"] = "red"

    self.button.bind("<Enter>", self.turnRed)

イベントのウィジェットフィールドがturnRed()コールバック内でどのようにアクセスされているかに注意してください。 このフィールドはXイベントを捕らえるウィジェットを含んでいます。 以下の表はあなたがアクセスできる他のイベントフィールドとそれらのTkでの表現方法の一覧です。Tk manページを参照するときに役に立つでしょう。

Tk      Tkinterイベントフィールド       Tk      Tkinterイベントフィールド
--      -------------------------       --      -------------------------
%f      focus                           %A      char
%h      height                          %E      send_event
%k      keycode                         %K      keysym
%s      state                           %N      keysym_num
%t      time                            %T      type
%w      width                           %W      widget
%x      x                               %X      x_root
%y      y                               %Y      y_root

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.6.6 Tkオプションデータ型 Up: 16.1.6 便利なリファレンス Next: 16.1.6.8 index パラメータ


16.1.6.8 index パラメータ

たくさんのウィジェットが渡される``index''パラメータを必要とします。これらはテキストウィジェットでの特定の場所や、エントリウィジェットでの特定の文字、あるいは、メニューウィジェットでの特定のメニュー項目を指定するために使われます。

エントリウィジェットのインデックス(インデックス、ビューインデックスなど)
エントリウィジェットは表示されているテキスト内の文字位置を参照するオプションを持っています。 テキストウィジェットにおけるこれらの特別な位置にアクセスするために、これらのTkinter関数を使うことができます:

AtEnd()
テキストの最後の位置を参照します

AtInsert()
テキストカーソルの位置を参照します

AtSelFirst()
選択されたテキストの先頭の位置を指します

AtSelLast()
選択されているテキストおよび最終的に選択されたテキストの末尾の位置を示します。

At(x[, y])
ピクセル位置x, y(テキストを一行だけ含むテキストエントリウィジェットの場合にはyは使われない)の文字を参照します。

テキストウィジェットのインデックス
テキストウィジェットに対するインデックス記法はとても機能が豊富で、Tk manページでよく説明されています。

メニューのインデックス(menu.invoke()、menu.entryconfig()など)

メニューに対するいくつかのオプションとメソッドは特定のメニュー項目を操作します。メニューインデックスはオプションまたはパラメータのために必要とされるときはいつでも、以下のものを渡すことができます:

  • 頭から数えられ、0で始まるウィジェットの数字の位置を指す整数。
  • 文字列'active'、現在カーソルがあるメニューの位置を指します。
  • 最後のメニューを指す文字列"last"。
  • @6のような@が前に来る整数。ここでは、整数がメニューの座標系におけるyピクセル座標として解釈されます。
  • 文字列"none"、どんなメニューエントリもまったく指しておらず、ほとんどの場合、すべてのエントリの動作を停止させるためにmenu.activate()と一緒に使われます。そして、最後に、
  • メニューの先頭から一番下までスキャンしたときに、メニューエントリのラベルに一致したパターンであるテキスト文字列。このインデックス型は他すべての後に考慮されることに注意してください。その代わりに、それはlast、activeまたはnoneとラベル付けされたメニュー項目への一致は上のリテラルとして解釈されることを意味します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.6.7 バインドとイベント Up: 16.1.6 便利なリファレンス Next: 16.1.6.9 画像


16.1.6.9 画像

Bitmap/Pixelmap画像をTkinter.Imageのサブクラスを使って作ることができます:

  • BitmapImageはX11ビットマップデータに対して使えます。
  • PhotoImageはGIFとPPM/PGMカラービットマップに対して使えます。

画像のどちらの型でもfileまたはdataオプションを使って作られます(その上、他のオプションも利用できます)。

imageオプションがウィジェットにサポートされるところならどこでも、画像オブジェクトを使うことができます(例えば、ラベル、ボタン、メニュー)。これらの場合では、Tkは画像への参照を保持しないでしょう。画像オブジェクトへの最後のPythonの参照が削除されたときに、おまけに画像データが削除されます。そして、どこで画像が使われていようとも、Tkは空の箱を表示します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.6.8 index パラメータ Up: 16.1.6 便利なリファレンス Next: 16.2 Tix


16.2.2.1 基本ウィジェット

class Balloon( )
ヘルプを提示するためにウィジェット上にポップアップするBalloon。ユーザがカーソルをBalloonウィジェットが束縛されているウィジェット内部へ移動させたとき、説明のメッセージが付いた小さなポップアップウィンドウがスクリーン上に表示されます。

class ButtonBox( )
ButtonBoxウィジェットは、Ok Cancelのためだけに普通は使われるようなボタンボックスを作成します。

class ComboBox( )
ComboBoxウィジェットはMS Windowsのコンボボックスコントロールに似ています。ユーザはエントリ・サブウィジェットでタイプするか、リストボックス・サブウィジェットから選択するかのどちらかで選択肢を選びます。

class Control( )
ControlウィジェットはSpinBoxウィジェットとしても知られています。ユーザは二つの矢印ボタンを押すか、またはエントリに直接値を入力して値を調整します。新しい値をユーザが定義した上限と下限に対してチェックします。

class LabelEntry( )
LabelEntryウィジェットはエントリウィジェットとラベルを一つのメガウィジェットにまとめたものです。``記入形式''型のインターフェイスの作成を簡単に行うために使うことができます。

class LabelFrame( )
LabelFrameウィジェットはフレームウィジェットとラベルを一つのメガウィジェットにまとめたものです。LabelFrameウィジェット内部にウィジェットを作成するためには、frameサブウィジェットに対して新しいウィジェットを作成し、それらをframeサブウィジェット内部で取り扱います。

class Meter( )
Meterウィジェットは実行に時間のかかるバックグラウンド・ジョブの進み具合を表示するために使用できます。

class OptionMenu( )
OptionMenuはオプションのメニューボタンを作成します。

class PopupMenu( )
PopupMenuウィジェットはtk_popupコマンドの代替品として使用できます。Tix PopupMenuウィジェットの利点は、操作するためにより少ないアプリケーション・コードしか必要としないことです。

class Select( )
Selectウィジェットはボタン・サブウィジェットのコンテナです。ユーザに対する選択オプションのラジオボックスまたはチェックボックス形式を提供するために利用することができます。

class StdButtonBox( )
StdButtonBoxウィジェットは、Motifに似たダイアログボックスのための標準的なボタンのグループです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.2.2 Tixウィジェット Up: 16.2.2 Tixウィジェット Next: 16.2.2.2 ファイルセレクタ


16.2.2.2 ファイルセレクタ

class DirList( )
DirListウィジェットは、ディレクトリのリストビュー(その前のディレクトリとサブディレクトリ)を表示します。ユーザはリスト内の表示されたディレクトリの一つを選択したり、あるいは他のディレクトリへ変更したりできます。

class DirTree( )
DirTreeウィジェットはディレクトリのツリービュー(その前のディレクトリとそのサブディレクトリ)を表示します。ユーザはリスト内に表示されたディレクトリの一つを選択したり、あるいは他のディレクトリに変更したりできます。

class DirSelectDialog( )
DirSelectDialogウィジェットは、ダイアログウィンドウにファイルシステム内のディレクトリを提示します。望みのディレクトリを選択するために、ユーザはファイルシステムを介して操作するこのダイアログウィンドウを利用できます。

class DirSelectBox( )
DirSelectBoxは標準Motif(TM)ディレクトリ選択ボックスに似ています。ユーザがディレクトリを選択するために一般的に使われます。DirSelectBoxは主に最近ComboBoxウィジェットに選択されたディレクトリを保存し、すばやく再選択できるようにします。

class ExFileSelectBox( )
ExFileSelectBoxウィジェットは、たいていtixExFileSelectDialogウィジェット内に組み込まれます。ユーザがファイルを選択するのに便利なメソッドを提供します。ExFileSelectBoxウィジェットのスタイルは、MS Windows 3.1の標準ファイルダイアログにとてもよく似ています。

class FileSelectBox( )
FileSelectBoxは標準的なMotif(TM)ファイル選択ボックスに似ています。ユーザがファイルを選択するために一般的に使われます。FileSelectBoxは主に最近ComboBoxウィジェットに選択されたファイルを保存し、素早く再選択できるようにします。

class FileEntry( )
FileEntryウィジェットはファイル名を入力するために使うことができます。ユーザは手でファイル名をタイプできます。その代わりに、ユーザはエントリの横に並んでいるボタンウィジェットを押すことができます。それはファイル選択ダイアログを表示します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.2.2.1 基本ウィジェット Up: 16.2.2 Tixウィジェット Next: 16.2.2.3 ハイアラキカルリストボックス


16.2.2.3 ハイアラキカルリストボックス

class HList( )
HListウィジェットは階層構造をもつどんなデータ(例えば、ファイルシステムディレクトリツリー)でも表示するために使用できます。リストエントリは字下げされ、階層のそれぞれの場所に応じて分岐線で接続されます。

class CheckList( )
CheckListウィジェットは、ユーザが選ぶ項目のリストを表示します。CheckListはTkのチェックリストやラジオボタンより多くの項目を扱うことができることを除いて、チェックボタンあるいはラジオボタンウィジェットと同じように動作します。

class Tree( )
Treeウィジェットは階層的なデータをツリー形式で表示するために使うことができます。ユーザはツリーの一部を開いたり閉じたりすることによって、ツリーの見えを調整できます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.2.2.2 ファイルセレクタ Up: 16.2.2 Tixウィジェット Next: 16.2.2.4 タビュラーリストボックス


16.2.2.4 タビュラーリストボックス

class TList( )
TListウィジェットは、表形式でデータを表示するために使うことができます。TListウィジェットのリスト・エントリは、Tkのリストボックス・ウィジェットのエントリに似ています。主な差は、(1) TListウィジェットはリスト・エントリを二次元形式で表示でき、(2) リスト・エントリに対して複数の色やフォントだけでなく画像も使うことができるということです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.2.2.3 ハイアラキカルリストボックス Up: 16.2.2 Tixウィジェット Next: 16.2.2.5 管理ウィジェット


16.2.2.5 管理ウィジェット

class PanedWindow( )
PanedWindowウィジェットは、ユーザがいくつかのペインのサイズを対話的に操作できるようにします。ペインは垂直または水平のどちらかに配置されます。ユーザは二つのペインの間でリサイズ・ハンドルをドラッグしてペインの大きさを変更します。

class ListNoteBook( )
ListNoteBookウィジェットは、TixNoteBookウィジェットにとてもよく似ています。ノートのメタファを使って限られた空間をに多くのウィンドウを表示するために使われます。ノートはたくさんのページ(ウィンドウ)に分けられています。ある時には、これらのページの一つしか表示できません。ユーザはhlistサブウィジェットの中の望みのページの名前を選択することによって、これらのページを切り替えることができます。

class NoteBook( )
NoteBookウィジェットは、ノートのメタファを多くのウィンドウを表示することができます。ノートはたくさんのページに分けられています。ある時には、これらのページの一つしか表示できません。ユーザはNoteBookウィジェットの一番上にある目に見える``タブ''を選択することで、これらのページを切り替えることができます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.2.2.4 タビュラーリストボックス Up: 16.2.2 Tixウィジェット Next: 16.2.2.6 画像タイプ


16.2.2.6 画像タイプ

Tixモジュールは次のものを追加します:

  • 全てのTixとTkinterウィジェットに対してXPMファイルからカラー画像を作成するpixmap機能。

  • Compound画像タイプは複数の水平方向の線から構成される画像を作成するために使うことができます。それぞれの線は左から右に並べられた一連のアイテム(テキスト、ビットマップ、画像あるいは空白)から作られます。例えば、TkのButtonウィジェットの中にビットマップとテキスト文字列を同時に表示するためにcompound画像は使われます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.2.2.5 管理ウィジェット Up: 16.2.2 Tixウィジェット Next: 16.2.2.7 その他のウィジェット


16.2.2.7 その他のウィジェット

class InputOnly( )
InputOnlyウィジェットは、ユーザから入力を受け付けます。それは、bindコマンドを使って行われます(Unixのみ)。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.2.2.6 画像タイプ Up: 16.2.2 Tixウィジェット Next: 16.2.2.8 ジオメトリマネージャを作る


16.2.2.8 ジオメトリマネージャを作る

加えて、Tixは次のものを提供することでTkinterを補強します:

class Form( )
Tkウィジェットに対する接続ルールに基づいたジオメトリマネージャを作成(Form)します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.2.2.7 その他のウィジェット Up: 16.2.2 Tixウィジェット Next: 16.2.3 Tixコマンド


16.5.1.1 Fileメニュー

New window
新しい編集ウィンドウを作成します
Open...
既存のファイルをオープンします
Open module...
既存のモジュールをオープンします(sys.pathを検索します)
Class browser
現在のファイルの中のクラスとモジュールを示します
Path browser
sys.pathディレクトリ、モジュール、クラスおよびメソッドを示します

Save
現在のウィンドウを対応するファイルにセーブします(未セーブのウィンドウには、ウィンドウタイトルの前後に*があります)

Save As...
現在のウィンドウを新しいファイルへセーブします。そのファイルが対応するファイルになります
Save Copy As...
現在のウィンドウを対応するファイルを変えずに異なるファイルにセーブします。

Close
現在のウィンドウを閉じます(未セーブの場合はセーブするか質問します)
Exit
すべてのウィンドウを閉じてIDLEを終了します(未セーブの場合はセーブするか質問します)

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.5.1 メニュー Up: 16.5.1 メニュー Next: 16.5.1.2 Editメニュー


16.5.1.2 Editメニュー

Undo
現在のウィンドウに対する最後の変更をUndo(取り消し)します(最大で1000個の変更)
Redo
現在のウィンドウに対する最後にundoされた変更をRedo(再実行)します

Cut
システムのクリップボードへ選択された部分をコピーします。それから選択された部分を削除します
Copy
選択された部分をシステムのクリップボードへコピーします
Paste
システムのクリップボードをウィンドウへ挿入します
Select All
編集バッファの内容全体を選択します

Find...
たくさんのオプションをもつ検索ダイアログボックスを開きます
Find again
最後の検索を繰り返します
Find selection
選択された文字列を検索します
Find in Files...
検索するファイルに対する検索ダイアログボックスを開きます
Replace...
検索と置換ダイアログボックスを開きます
Go to line
行番号を尋ね、その行を表示します

Indent region
選択された行を右へ空白4個分シフトします
Dedent region
選択された行を左へ空白4個分シフトします
Comment out region
選択された行の先頭に##を挿入します
Uncomment region
選択された行から先頭の#あるいは##を取り除きます
Tabify region
先頭の一続きの空白をタブに置き換えます
Untabify region
すべてのタブを適切な数の空白に置き換えます
Expand word
あなたがタイプした語を同じバッファの別の語に一致するように展開します。そして、異なる展開が得るために繰り返します
Format Paragraph
現在の空行で区切られた段落を再フォーマットします

Import module
現在のモジュールをインポートまたはリロードします
Run script
現在のファイルを__main__名前空間内で実行します

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.5.1.1 Fileメニュー Up: 16.5.1 メニュー Next: 16.5.1.3 Windowsメニュー


16.5.1.3 Windowsメニュー

Zoom Height
ウィンドウを標準サイズ(24x80)と最大の高さの間で切り替えます

このメニューの残りはすべての開いたウィンドウの名前の一覧になっています。一つを選ぶとそれを最前面に持ってくることができます(必要ならばアイコン化をやめさせます)

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.5.1.2 Editメニュー Up: 16.5.1 メニュー Next: 16.5.1.4 Debugメニュー(Pythonシェルウィンドウ内のみ)


16.5.1.4 Debugメニュー(Pythonシェルウィンドウ内のみ)

Go to file/line
挿入ポイントの周りからファイル名と行番号を探し、ファイルをオープンし、その行を表示します
Open stack viewer
最後の例外のスタックトレースバックを表示します
Debugger toggle
デバッガの下、シェル内でコマンドを実行します
JIT Stack viewer toggle
トレースバック上のスタックビューアをオープンします

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.5.1.3 Windowsメニュー Up: 16.5.1 メニュー Next: 16.5.2 基本的な編集とナビゲーション


16.5.2.1 自動的な字下げ

ブロックの始まりの文の後、次の行は4つの空白(Python Shellウィンドウでは、一つのタブ)で字下げされます。あるキーワード(break、returnなど)の後では、次の行は字下げが解除(dedent)されます。先頭の字下げでは、Backspaceは4つの空白があれば削除します。Tabは1-4つの空白(Python Shellウィンドウでは一つのタブ)を挿入します。editメニューのindent/dedent regionコマンドも参照してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.5.2 基本的な編集とナビゲーション Up: 16.5.2 基本的な編集とナビゲーション Next: 16.5.2.2 Python Shellウィンドウ


16.5.2.2 Python Shellウィンドウ

  • C-C 実行中のコマンドを中断します
  • C-D ファイル終端(end-of-file)を送り、"»> "プロンプトでタイプしていた場合はウィンドウを閉じます

  • Alt-p あなたがタイプしたことに一致する以前のコマンドを取り出します
  • Alt-n 次を取り出します
  • Return 以前のコマンドを取り出しているときは、そのコマンド
  • Alt-/ (語を展開します)ここでも便利です

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.5.2.1 自動的な字下げ Up: 16.5.2 基本的な編集とナビゲーション Next: 16.5.3 構文の色づけ


16.5.3.1 コマンドラインの使い方

idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ...

-c コマンド このコマンドを実行します
-d          デバッガを有効にします
-e          編集モード、引数は編集するファイルです
-s          $IDLESTARTUPまたは$PYTHONSTARTUPを最初に実行します
-t タイトル シェルウィンドウのタイトルを設定します

引数がある場合:

  1. -eが使われる場合は、引数は編集のためにオープンされるファイルで、sys.argvはIDLE自体へ渡される引数を反映します。

  2. そうではなく、-cが使われる場合には、すべての引数がsys.argv[1:...]の中に置かれ、sys.argv[0]が'-c'に設定されます。

  3. そうではなく、-eでも-cでも使われない場合は、最初の引数はsys.argv[1:...]にある残りの引数とスクリプト名に設定されるsys.argv[0]と一緒に実行されるスクリプトです。スクリプト名が'-'のときは、実行されるスクリプトはありませんが、対話的なPythonセッションが始まります。引数はまだsys.argvにあり利用できます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.5.3 構文の色づけ Up: 16.5.3 構文の色づけ Next: 16.6 他のグラフィカルユーザインターフェイスパッケージ


18.1.6.1 compile()のエミュレーション

たくさんの有用な演算を構文解析とバイトコード生成の間に行うことができますが、もっとも単純な演算は何もしないことです。このため、parserモジュールを使って中間データ構造を作ることは次のコードと等価です。

>>> code = compile('a + 5', 'file.py', 'eval')
>>> a = 5
>>> eval(code)
10

parserモジュールを使った等価な演算はやや長くなりますが、ASTオブジェクトとして中間内部解析木が維持されるようにします:

>>> import parser
>>> ast = parser.expr('a + 5')
>>> code = ast.compile('file.py')
>>> a = 5
>>> eval(code)
10

ASTとコードオブジェクトの両方が必要なアプリケーションでは、このコードを簡単に利用できる関数にまとめることができます:

import parser

def load_suite(source_string):
    ast = parser.suite(source_string)
    return ast, ast.compile()

def load_expression(source_string):
    ast = parser.expr(source_string)
    return ast, ast.compile()

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.1.6 例 Up: 18.1.6 例 Next: 18.1.6.2 情報発見


18.1.6.2 情報発見

あるアプリケーションでは解析木へ直接アクセスすることが役に立ちます。この節の残りでは、importを使って調査中のコードを実行中のインタープリタにロードする必要も無しに、解析木を使ってdocstringsに定義されたモジュールのドキュメンテーションへのアクセスを可能にする方法を示します。これは信頼性のないコードを解析するためにとても役に立ちます。

一般に、例は興味のある情報を引き出すために解析木をどのような方法でたどればよいかを示しています。二つの関数と一連のクラスが開発され、モジュールが提供する高レベルの関数とクラスの定義をプログラムから利用できるようになります。クラスは情報を解析木から引き出し、便利な意味レベルでその情報へアクセスできるようにします。一つの関数は単純な低レベルのパターンマッチング機能を提供し、もう一つの関数は呼び出し側の代わりにファイル操作を行うという点でクラスへの高レベルなインターフェイスです。ここで言及されていてPythonのインストールに必要ないすべてのソースファイルは、ディストリビューションのDemo/parser/ディレクトリにあります。

Pythonの動的な性質によってプログラマは非常に大きな柔軟性を得ることができます。しかし、クラス、関数およびメソッドを定義するときには、ほとんどのモジュールがこれの限られた部分しか必要としません。この例では、考察される定義だけがコンテキストのトップレベルにおいて定義されるものです。例を挙げると、モジュールのゼロ列目にdef文によって定義される関数で、if ... elseコンストラクトの枝の中に定義されていない関数(ある状況ではそうすることにもっともな理由があるのですが)。例で開発するコードによって、定義の入れ子を扱う予定です。

より上位レベルの抽出メソッドを作るために知る必要があるのは、解析木構造がどのようなものかということと、それのどの程度まで関心を持つ必要があるのかということです。Pythonはやや深い解析木を使いますので、たくさんの中間ノードがあります。Pythonが使う形式文法を読んで理解することは重要です。これは配布物に含まれるファイルGrammar/Grammarに明記されています。docstringsを探すときに対象として最も単純な場合について考えてみてください: docstringの他に何も無いモジュール。(ファイルdocstring.pyを参照してください。)

"""Some documentation.
"""

インタープリタを使って解析木を調べると、数と括弧が途方に暮れるほど多くて、ドキュメンテーションが入れ子になったタプルの深いところに埋まっていることがわかります。

>>> import parser
>>> import pprint
>>> ast = parser.suite(open('docstring.py').read())
>>> tup = ast.totuple()
>>> pprint.pprint(tup)
(257,
 (264,
  (265,
   (266,
    (267,
     (307,
      (287,
       (288,
        (289,
         (290,
          (292,
           (293,
            (294,
             (295,
              (296,
               (297,
                (298,
                 (299,
                  (300, (3, '"""Some documentation.\n"""'))))))))))))))))),
   (4, ''))),
 (4, ''),
 (0, ''))

木の各ノードの最初の要素にある数はノード型です。それらは文法の終端記号と非終端記号に直接に対応します。残念なことに、それらは内部表現の整数で表されていて、生成されたPythonの構造でもそのままになっています。しかし、symbolとtokenモジュールはノード型の記号名と整数からノード型の記号名へマッピングする辞書を提供します。

上に示した出力の中で、最も外側のタプルは四つの要素を含んでいます: 整数257と三つの付加的なタプル。ノード型257の記号名はfile_inputです。これらの各内部タプルは最初の要素として整数を含んでいます。これらの整数264と4、0は、ノード型stmt、NEWLINE、ENDMARKERをそれぞれ表しています。これらの値はあなたが使っているPythonのバージョンに応じて変化する可能性があることに注意してください。マッピングの詳細については、symbol.pyとtoken.pyを調べてください。もっとも外側のノードがファイルの内容ではなく入力ソースに主に関係していることはほとんど明らかで、差し当たり無視しても構いません。stmtノードはさらに興味深いです。特に、すべてのdocstringsは、このノードが作られるのとまったく同じように作られ、違いがあるのは文字列自身だけである部分木にあります。同様の木のdocstringと説明の対象である定義されたエンティティ(クラス、関数あるいはモジュール)の関係は、前述の構造を定義している木の内部におけるdocstring部分木の位置によって与えられます。

実際のdocstringを木の変数要素を意味する何かと置き換えることによって、簡単なパターンマッチング方法で与えられたどんな部分木でもdocstringsに対する一般的なパターンと同等かどうかを調べられるようになります。例では情報の抽出の実例を示しているので、['variable_name']という単純な変数表現を念頭において、リスト形式ではなくタプル形式の木を安全に要求できます。簡単な再帰関数でパターンマッチングを実装でき、その関数は真偽値と変数名から値へのマッピングの辞書を返します。(ファイルexample.pyを参照してください。)

from types import ListType, TupleType

def match(pattern, data, vars=None):
    if vars is None:
        vars = {}
    if type(pattern) is ListType:
        vars[pattern[0]] = data
        return 1, vars
    if type(pattern) is not TupleType:
        return (pattern == data), vars
    if len(data) != len(pattern):
        return 0, vars
    for pattern, data in map(None, pattern, data):
        same, vars = match(pattern, data, vars)
        if not same:
            break
    return same, vars

この構文の変数用の簡単な表現と記号のノード型を使うと、docstring部分木の候補のパターンがとても読みやすくなります。(ファイルexample.pyを参照してください。)

import symbol
import token

DOCSTRING_STMT_PATTERN = (
    symbol.stmt,
    (symbol.simple_stmt,
     (symbol.small_stmt,
      (symbol.expr_stmt,
       (symbol.testlist,
        (symbol.test,
         (symbol.and_test,
          (symbol.not_test,
           (symbol.comparison,
            (symbol.expr,
             (symbol.xor_expr,
              (symbol.and_expr,
               (symbol.shift_expr,
                (symbol.arith_expr,
                 (symbol.term,
                  (symbol.factor,
                   (symbol.power,
                    (symbol.atom,
                     (token.STRING, ['docstring'])
                     )))))))))))))))),
     (token.NEWLINE, '')
     ))

このパターンとmatch()関数を使うと、前に作った解析木からモジュールのdocstringを簡単に抽出できます:

>>> found, vars = match(DOCSTRING_STMT_PATTERN, tup[1])
>>> found
1
>>> vars
{'docstring': '"""Some documentation.\n"""'}

特定のデータを期待された位置から抽出できると、次は情報を期待できる場所はどこかという疑問に答える必要がでてきます。docstringを扱う場合、答えはとても簡単です: docstringはコードブロック(file_inputまたはsuiteノード型)の最初のstmtノードです。モジュールは一つのfile_inputノードと、正確にはそれぞれが一つのsuiteノードを含むクラスと関数の定義で構成されます。クラスと関数は(stmt, (compound_stmt, (classdef, ...または(stmt, (compound_stmt, (funcdef, ...で始まるコードブロックノードの部分木として簡単に識別されます。これらの部分木はmatch()によってマッチさせることができないことに注意してください。なぜなら、数を無視して複数の兄弟ノードにマッチすることをサポートしていないからです。この限界を超えるためにより念入りにつくったマッチング関数を使うことができますが、例としてはこれで充分です。

文がdocstringかどうかを決定し、実際の文字列をその文から抽出する機能について考えると、ある作業にはモジュール全体の解析木を巡回してモジュールの各コンテキストにおいて定義される名前についての情報を抽出し、その名前とdocstringsを結び付ける必要があります。この作業を行うコードは複雑ではありませんが、説明が必要です。

そのクラスへの公開インターフェイスは簡単で、おそらく幾分かより柔軟でしょう。モジュールのそれぞれの``主要な''ブロックは、問い合わせのための幾つかのメソッドを提供するオブジェクトと、少なくともそれが表す完全な解析木の部分木を受け取るコンストラクタによって記述されます。ModuleInfoコンストラクタはオプションのnameパラメータを受け取ります。なぜなら、そうしないとモジュールの名前を決められないからです。

公開クラスにはClassInfo、FunctionInfoおよびModuleInfoが含まれます。すべてのオブジェクトはメソッドget_name()、get_docstring()、get_class_names()およびget_class_info()を提供します。ClassInfoオブジェクトはget_method_names()とget_method_info()をサポートしますが、他のクラスはget_function_names()とget_function_info()を提供しています。

公開クラスが表すコードブロックの形式のそれぞれにおいて、トップレベルで定義された関数が``メソッド''として参照されるという違いがクラスにはありますが、要求される情報のほとんどは同じ形式をしていて、同じ方法でアクセスされます。クラスの外側で定義される関数との実際の意味の違いを名前の付け方が違うことで反映しているため、実装はこの違いを保つ必要があります。そのため、公開クラスのほとんどの機能が共通の基底クラスSuiteInfoBaseに実装されており、他の場所で提供される関数とメソッドの情報に対するアクセサを持っています。関数とメソッドの情報を表すクラスが一つだけであることに注意してください。これは要素の両方の型を定義するためにdef文を使うことに似ています。

アクセサ関数のほとんどはSuiteInfoBaseで宣言されていて、サブクラスでオーバーライドする必要はありません。より重要なこととしては、解析木からのほとんどの情報抽出がSuiteInfoBaseコンストラクタに呼び出されるメソッドを通して行われるということがあります。平行して形式文法を読めば、ほとんどのクラスのコード例は明らかです。しかし、再帰的に新しい情報オブジェクトを作るメソッドはもっと調査が必要です。example.pyのSuiteInfoBase定義の関連する箇所を以下に示します:

class SuiteInfoBase:
    _docstring = ''
    _name = ''

    def __init__(self, tree = None):
        self._class_info = {}
        self._function_info = {}
        if tree:
            self._extract_info(tree)

    def _extract_info(self, tree):
        # extract docstring
        if len(tree) == 2:
            found, vars = match(DOCSTRING_STMT_PATTERN[1], tree[1])
        else:
            found, vars = match(DOCSTRING_STMT_PATTERN, tree[3])
        if found:
            self._docstring = eval(vars['docstring'])
        # discover inner definitions
        for node in tree[1:]:
            found, vars = match(COMPOUND_STMT_PATTERN, node)
            if found:
                cstmt = vars['compound']
                if cstmt[0] == symbol.funcdef:
                    name = cstmt[2][1]
                    self._function_info[name] = FunctionInfo(cstmt)
                elif cstmt[0] == symbol.classdef:
                    name = cstmt[2][1]
                    self._class_info[name] = ClassInfo(cstmt)

初期状態に初期化した後、コンストラクタは_extract_info()メソッドを呼び出します。このメソッドがこの例全体で行われる情報抽出の大部分を実行します。抽出には二つの別々の段階があります: 渡された解析木のdocstringの位置の特定、解析木が表すコードブロック内の付加的な定義の発見。

最初のifテストは入れ子のsuiteが``短い形式''または``長い形式''かどうかを決定します。以下のコードブロックの定義のように、コードブロックが同じ行であるときに短い形式が使われます。

def square(x): "Square an argument."; return x ** 2

長い形式では字下げされたブロックを使い、入れ子になった定義を許しています:

def make_power(exp):
    "Make a function that raises an argument to the exponent `exp'."
    def raiser(x, y=exp):
        return x ** y
    return raiser

短い形式が使われるとき、コードブロックはdocstringを最初のsmall_stmt要素として(ことによるとそれだけを)持っています。このようなdocstringの抽出は少し異なり、より一般的な場合に使われる完全なパターンの一部だけを必要とします。実装されているように、simple_stmtノードにsmall_stmtノードが一つだけある場合には、docstringしかないことがあります。短い形式を使うほとんどの関数とメソッドがdocstringを提供しないため、これで充分だと考えられます。docstringの抽出は前述のmatch()関数を使って進み、docstringがSuiteInfoBaseオブジェクトの属性として保存されます。

docstringを抽出した後、簡単な定義発見アルゴリズムをsuiteノードのstmtノードに対して実行します。短い形式の特別な場合はテストされません。短い形式ではstmtノードが存在しないため、アルゴリズムは黙ってsimple_stmtノードを一つスキップします。正確に言えば、どんな入れ子になった定義も発見しません。

コードブロックのそれぞれの文をクラス定義(関数またはメソッドの定義、あるいは、何か他のもの)として分類します。定義文に対しては、定義された要素の名前が抽出され、コンストラクタに引数として渡される部分木の定義とともに定義に適した代理オブジェクトが作成されます。代理オブジェクトはインスタンス変数に保存され、適切なアクセサメソッドを使って名前から取り出されます。

公開クラスはSuiteInfoBaseクラスが提供するアクセサより具体的で、必要とされるどんなアクセサでも提供します。しかし、実際の抽出アルゴリズムはコードブロックのすべての形式に対して共通のままです。高レベルの関数をソースファイルから完全な情報のセットを抽出するために使うことができます。(ファイルexample.pyを参照してください。)

def get_docs(fileName):
    import os
    import parser

    source = open(fileName).read()
    basename = os.path.basename(os.path.splitext(fileName)[0])
    ast = parser.suite(source)
    return ModuleInfo(ast.totuple(), basename)

これはモジュールのドキュメンテーションに対する使いやすいインターフェイスです。この例のコードで抽出されない情報が必要な場合は、機能を追加するための明確に定義されたところで、コードを拡張することができます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 18.1.6.1 compile()のエミュレーション Up: 18.1.6 例 Next: 18.2 symbol


6.20.5.2 新たなアクションを追加する

アクションの追加は少しだけ厄介です。というのは、optparse がアクションを二種類に分類していることを理解しなければならないからです:

"store" アクション
結果的に optparse の OptionValues インスタンスの属性に値を 保存することになるアクションです; このアクションをとるオプションは Option のコンストラクタに 'dest' 属性を指定する必要があります。
"typed" アクション
コマンドラインから値をとり、それが特定の型か、あるいは特定の型に 変換される文字列になるはずのアクションです。このアクションをとる オプションは Option のコンストラクタに 'type' 属性を指定する必要があります。

デフォルトの ``store'' アクションには、``store''、 ``store_const''、 ``append''、および ``count'' があります。デフォルトの ``typed'' アクションは、``store''、 ``append''、および ``callback'' です。

アクションを追加する際、 アクションが ``store''、``typed''、 どちらでもない、両方である、のいずれか決めなければなりません。 Option (または Option サブクラス) の3つのクラス属性 がこの決定を制御します:

ACTIONS
すべてのアクションは ACTIONS に文字列で列挙されていなければなりません。
STORE_ACTIONS
"store" 系のアクションはここに列挙されていなければなりません。
TYPED_ACTIONS
"typed" 系のアクションはここに列挙されていなければなりません。

自前の新たなアクションを実際に実装するには、Option の take_action() メソッドを上書きして、自前のアクションを 認識する場合を追加しなければなりません。

例として、``extend'' アクションを追加してみましょう。このアクションは 標準の ``append'' アクションに似ていますが、コマンドラインから単一の 値をとって既存のリストに追加する代わりに、 ``extend'' では コンマで区切られた単一の文字列から複数の値をとり、既存のリストに 追加します。すなわち、--names が ``extend'' のタイプの オプション文字列であれば、以下のコマンドライン:

--names=foo,bar --names blah --names ding,dong

は以下のリスト:

["foo", "bar", "blah", "ding", "dong"]

になります。

再び Option のサブクラスを定義します:

class MyOption (Option):

    ACTIONS = Option.ACTIONS + ("extend",)
    STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
    TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)

    def take_action (self, action, dest, opt, value, values, parser):
        if action == "extend":
            lvalue = value.split(",")
            values.ensure_value(dest, []).extend(lvalue)
        else:
            Option.take_action(
                self, action, dest, opt, value, values, parser)

以下のことに注意します:

  • ``extend'' は値をコマンドラインから要求し、その値をどこかへ 保存するという両方の操作を行うので、STORE_ACTIONS と TYPED_ACTIONS の両方に相当します。

  • MyOption.take_action() ではこの新しいアクションだけを 実装し、標準のOption.take_action() で optparse アクションへ 制御を戻します。

  • values は Values クラスのインスタンスで、 非常に便利な ensure_value() メソッドを提供しています。 ensure_value() は実質的には安全値 (safety value) のある getattr() です; このメソッドは以下のようにして 呼び出されます:

    values.ensure_value(attr, value)

values の attr 属性が存在しないか、または None の 場合、ensure_value() は属性の値を value に設定して から value を返します。この機能は ``extend''、 ``append''、 および ``count'' で便利です。というのは、これらのアクションは すべて、データを変数に蓄積し、その変数が特定の型であるはず (最初の二つはリストで、最後の一つは整数) だからです。 ensure_value() を使うことで、アクションを使う スクリプトにおいて、オプションの目的変数にデフォルトの値を設定 するよう配慮しなくてよくなります; こうした目的変数はデフォルトを None にしておいてよく、ensure_value() が必要なときに 正しい値にするよう面倒を見ることになります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.5.1 新たな型を追加する Up: 6.20.5 optparse を拡張する Next: 6.20.5.3 拡張を行う他の理由 optparse


6.20.5.1 新たな型を追加する

新たな型を追加するには、optparse の Option クラス から自前のサブクラスを定義する必要があります。 このクラスは optparse の型を定義する二つの属性: TYPES と TYPE_CHECKER を持っています。

TYPES は型の名前からなるタプルです; サブクラスでは、 標準のタプルに基づいて新たなタプル TYPES を定義するだけです。

TYPE_CHECKER は型の名前を型チェック関数に対応付ける辞書 です。型チェック関数は以下の形式をとります:

def check_foo (option : Option, opt : string, value : string)
               -> foo

この関数はどんな名前にしてもよく、どんな型を返すようにもできます。 型チェック関数が返す値は OptionParser.parse_args() が返す OptionValues インスタンスになるか、value パラメタと してコールバック関数に渡されます。

自前の型チェック関数が問題に遭遇した場合、OptionValueError を送出しなければなりません。OptionValueError は単一の 文字列引数をとり、この引数はそのまま OptionParser の error() メソッドに渡されます。 error() メソッドは プログラム名と文字列 ``error:'' を渡された文字列の前に付け、 プロセスを終了する前に全てを標準エラー出力に出力します。

以下のつまらない例では、コマンドライン上の Python 形式の複素数を解析 するために ``複素数 (complex)'' 型を追加する操作を実演します。 (この例は今ではさらにつまらなくなっていましました。というのは、 optparse 1.3 からは組み込みで [純粋に完備性のためだけに] 複素数のサポートが追加されるようになったからです。ですが、気にしない ことにします。)

まず、必要な import を行います:

from copy import copy
from optparse import Option, OptionValueError

まず型チェック関数を定義する必要があります。というのは、型チェック 関数は後で (自前の Option サブクラスにおける TYPE_CHECKER 属性で) 参照されるからです:

def check_complex (option, opt, value):
    try:
        return complex(value)
    except ValueError:
        raise OptionValueError(
            "option %s: invalid complex value: %r" % (opt, value))

最後に、Option サブクラスを定義します:

class MyOption (Option):
    TYPES = Option.TYPES + ("complex",)
    TYPE_CHECKER = copy(Option.TYPE_CHECKER)
    TYPE_CHECKER["complex"] = check_complex

(Option.TYPE_CHECKER の copy() を作成しなければ、 optparse の Option クラスにおける TYPE_CHECKER 属性を変更するだけで済みます。 Python では、良いマナーと常識以外にこうした省略をとどめるものは ありません。)

これで完成です！もう、新たなオプション型を使うようなスクリプトを 他の optparse ベースのスクリプトと同じように書くことができます。 ただし、OptionParser に Option ではなく MyOption を使うように指示しなければなりません:

parser = OptionParser(option_class=MyOption)
parser.add_option("-c", action="store", type="complex", dest="c")

別の方法として、自前のオプションリストを構築して、 OptionParser に渡すこともできます; 上の方法で add_option() を使わなければ、OptionParser に どのオプションクラスを使うかを教える必要はありません:

option_list = [MyOption("-c", action="store", type="complex", dest="c")]
parser = OptionParser(option_list=option_list)

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.5 optparse を拡張する Up: 6.20.5 optparse を拡張する Next: 6.20.5.2 新たなアクションを追加する


6.20.2.7 全てをつなぎ合わせる

optparse を使った私のスクリプトがだいたいどのようになって いるかを以下に示します:

from optparse import OptionParser

...

def main ():
    usage = "usage: %prog [options] arg"
    parser = OptionParser(usage)
    parser.add_option("-f", "--file", type="string", dest="filename",
                      help="read data from FILENAME")
    parser.add_option("-v", "--verbose",
                      action="store_true", dest="verbose")
    parser.add_option("-q", "--quiet",
                      action="store_false", dest="verbose")
    # more options ...

    (options, args) = parser.parse_args()
    if len(args) != 1:
        parser.error("incorrect number of arguments")

    if options.verbose:
        print "reading %s..." % options.filename

    # go to work ...

if __name__ == "__main__":
    main()

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.2.6 エラー処理 Up: 6.20.2 基本的な使い方 Next: 6.20.3 進んだ使い方


6.20.4.3 エラー処理

オプションやその引数に関して問題が発生した場合、 コールバック関数は OptionValueError を送出しなければ なりません。optparse はこの例外を捕捉し、プログラムを終了 します。このとき指定したエラーメッセージを標準出力に出力します。 メッセージは明快、簡潔、正確で、問題がみつかったオプションについて 触れなければなりません。そうでなければ、ユーザは指定したオプションの 何が問題なのか解決するのに苦労するでしょう。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.4.2 コールバック関数はどのように呼び出されるか Up: 6.20.4 callback オプション Next: 6.20.4.4 例


6.20.4.4 例

以下に引数をとらず、単に見つかったオプションを記録するだけの コールバックオプションの例を示します:

def record_foo_seen (option, opt, value, parser):
    parser.saw_foo = 1

parser.add_option("--foo", action="callback", callback=record_foo_seen)

もちろん、``store_true'' アクションを使っても同じことができます。 もう少し興味深い例もあります: -a がコマンドライン上に 見つかった事実を記録するが、-b が見つかると -a を消し去るというものです。

def check_order (option, opt, value, parser):
    if parser.values.b:
        raise OptionValueError("can't use -a after -b")
    parser.values.a = 1
...
parser.add_option("-a", action="callback", callback=check_order)
parser.add_option("-b", action="store_true", dest="b")

このコールバックを同様のオプションに対して複数回使いたい (オプションが見つかるとフラグが設定されるが、-b が見つかると常に消し去られる) 場合、少しだけ作業する必要が あります: すなわち、エラーメッセージと設定されるフラグを 一般化しておかなければなりません。

def check_order (option, opt, value, parser):
    if parser.values.b:
        raise OptionValueError("can't use %s after -b" % opt)
    setattr(parser.values, option.dest, 1)
...
parser.add_option("-a", action="callback", callback=check_order, dest='a')
parser.add_option("-b", action="store_true", dest="b")
parser.add_option("-c", action="callback", callback=check_order, dest='c')

もちろん、ここでは任意の条件を入れることができます -- できることは、 すでに定義されたオプションの値に対するチェックにとどまりません。 例えば、満月 (full moon) にならないと呼び出してはならないオプション があったとすると、やらなければならない作業は以下のようになります:

def check_moon (option, opt, value, parser):
    if is_full_moon():
        raise OptionValueError("%s option invalid when moon full" % opt)
    setattr(parser.values, option.dest, 1)
...
parser.add_option("--foo",
                  action="callback", callback=check_moon, dest="foo")

(is_full_moon() の定義は読者の練習用に残しておきます。)

固定個の引数

決まった数の引数をとるような callback オプションを定義する際には、 状況は少し興味深いものとなります。callback オプションが引数を とるよう定義する操作は ``store'' や ``append'' オプションと同様です: type を定義すると、オプションは単一の引数をとり、この値は 指定された型に変換可能でなくてはなりません; 加えて nargs を定義すると、オプションは指定数の引数をとるようになります。

標準的な ``store'' アクションをエミュレートするだけの例を以下に 示します:

def store_value (option, opt, value, parser):
    setattr(parser.values, option.dest, value)
...
parser.add_option("--foo",
                  action="callback", callback=store_value,
                  type="int", nargs=3, dest="foo")

optparse は 3 つの引数を取り出し、整数に変換しようと配慮 することに気をつけてください; これらの値を保存する必要があります (あるいは、何らかの処理を行う必要があります: 明らかに、この例 ではコールバックを使う必要はありません。想像力を働かせてください！)

可変個の引数

オプションが可変個の引数をとるようにしたいのなら、状況はやや 困難になります。この場合、コールバックを書かなければなりません; optparse では可変個の引数に対する組み込みの機能は まったく提供していません。このため、慣習的な Unix コマンドライン 解析のための本格的な書法を扱わなくてはなりません。 (以前は、optparse はこの問題に対する配慮を行っていましたが、 これは不具合がありました。この不具合は、この種のコールバックを より複雑にすることで修正されました。) とりわけ、コールバックでは、裸の -- や - 引数のことを考えなければなりません; やりかたは以下のようになります:

  • 裸の -- が存在し、何らかのオプションの引数で ない場合、コマンドライン処理を停止させ、-- 自体は消失します。

  • 裸の - も同様にコマンドライン処理を停止させますが、 - 自体は残されます。

  • -- か - のいずれかがオプションに 対する引数となり得ます。

オプションが可変個の引数をとるようにさせたいなら、いくつかの 巧妙で厄介な問題に配慮しなければなりません。どういう実装を とるかは、アプリケーションでどのようなトレードオフを考慮するか によります (このため、optparse では可変個の引数に 関する問題を直接的に取り扱わないのです)。

とはいえ、可変個の引数をもつオプションに対するスタブ (stub、仲介 インタフェース) を以下に示しておきます:

def varargs (option, opt, value, parser):
    assert value is None
    done = 0
    value = []
    rargs = parser.rargs
    while rargs:
        arg = rargs[0]

        # Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f",
        # etc.  Note that this also stops on "-3" or "-3.0", so if
        # your option takes numeric values, you will need to handle
        # this.
        if ((arg[:2] == "--" and len(arg) > 2) or
            (arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")):
            break
        else:
            value.append(arg)
            del rargs[0]

     setattr(parser.values, option.dest, value)

...
parser.add_option("-c", "--callback",
                  action="callback", callback=varargs)

この実装固有の弱点は、-c 以後に続いて負の数を表す 引数があった場合、-c の引数ではなく次のオプションとして 解釈されるということです。この問題の修正は読者の練習課題として おきます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.4.3 エラー処理 Up: 6.20.4 callback オプション Next: 6.20.5 optparse を拡張する


6.20.4.2 コールバック関数はどのように呼び出されるか

コールバックは全て以下のようにして呼び出されます:

func(option, opt, value, parser, *args, **kwargs)

ここで、

option
は、このコールバックを呼び出している Option のインスタンス です。

opt
は、コールバック呼び出しのきっかけとなったコマンドライン上の オプション文字列です。(長形式のオプションに対する省略形が使われている 場合、opt は完全な、正式な形のオプション文字列となります -- 例えば、ユーザが --foobar の短縮形として --foo をコマンドラインに入力した時には、opt は --foobar となります。)

value
は、このオプションの引数で、コマンドライン上に見つかったものです。 optparse は、type が設定されている場合、 単一の引数しかとりません;value の型はオプションの型 ( 6.20.3, ``オプションの型'' 参照) で示された 型になります。このオプションに対する type が None である (引数はない) 場合、value は None になります。"nargs > 1"なら、 value は適切な型をもつ値のタプルとなります。

parser
は、現在のオプション解析の全てを駆動している OptionParser インスタンスです。主に、この値を介して、インスタンス属性としていくつかの 興味深いデータにアクセスできるために便利です:

parser.rargs
現在未処理の引数からなるリスト、すなわち、opt (と、あれば value ) が除去され、それ以降の引数だけが 残っているリストです。parser.rargs の変更、例えば さらに引数を取り出すといった変更は、自由に行ってかまいません。

parser.largs
現在放置されている引数のセット、すなわち処理はされたが、 オプション (やオプションの引数) として取り出されてはいない 引数のセットです。parser.largs の変更、例えば さらに引数を追加するといった変更は、自由に行ってかまいません。

parser.values
オプションの値がデフォルトで保存されるオブジェクトです。 この値は、コールバック関数がオプションの値を記憶するために、 他のoptparse と同じ機構を使えるようにするので便利です; これでグローバル変数や閉包 (closure) を台無しにすることがありません。 コマンドライン上にすでに現れているオプションの値にアクセスすることも できます。

args
callback_args オプション属性で与えられた任意の固定引数 からなるタプルです。

kwargs
callback_args オプション属性で与えられた任意のキーワード引数 からなるタプルです。

args と kwargs は省略可能 (callback_args や callback_kwargs をコールバック定義の際に与えたときのみ 渡されます) なので、最小のコールバック関数定義は以下のようになります:

def my_callback (option, opt, value, parser):
    pass

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.4.1 callback オプションを定義する Up: 6.20.4 callback オプション Next: 6.20.4.3 エラー処理


6.20.3.6 オプション間の衝突

注意が足りないと、衝突するオプションを定義しやすくなります:

parser.add_option("-n", "--dry-run", ...)
...
parser.add_option("-n", "--noisy", ...)

(標準的なオプションを実装済みの OptionParser から自前の サブクラスを定義した場合にはさらによく起きます)

optparse はこのような定義は通常間違いによるものだと仮定 しており、デフォルトでは例外 (OptionConflictError) を 送出します。この誤りは簡単に修正できるプログラム上のエラーなので、 例外を catch しようとしないほうがせず -- 間違いを直しておくべき です。

時に、故意に新たなオプションで以前のオプションを置き換えたいこと があります。これは以下の呼び出し:

parser.set_conflict_handler("resolve")

で行えます。この操作は optparse にオプションの衝突を 賢く解決するよう指示します。

からくりはこうなっています: オプションを追加するたびに、 optparse は以前に追加されたオプションとの衝突がないか 調べます。何らかの衝突が見つかると、OptionParser の コンストラクタでの指定:

parser = OptionParser(..., conflict_handler="resolve")

か、set_conflict_handler() で指定されたいずれかの衝突処理 機構 (conflict-handling mechanism ) が起動されます。

デフォルトの衝突処理メカニズムは ``error'' です。その他の唯一の 選択肢は ``ignore'' で、これはバージョン 1.1 またはそれ以前の optparse の (おそらく壊れている) 挙動を修正します。

以下に例を示します: まず、衝突を解決するように設定された OptionParser を定義しましょう:

parser = OptionParser(conflict_handler="resolve")

ここでオプションを全て定義します:

parser.add_option("-n", "--dry-run", ..., help="original dry-run option")
...
parser.add_option("-n", "--noisy", ..., help="be noisy")

この時点で、optparse は以前に追加されたオプションで すでに -n オプション文字列が使用されていることを 検出します。conflict_handler == "resolve" であるため、 この状況は -n を以前のオプションにおけるオプション 文字列リストから削除することによって解決します。こうして、 以前のオプションを有効にする方法は --dry-run だけと なります。ユーザがヘルプメッセージを要求すると、ヘルプ文字列は 上の結果を反映します。例えば以下のようになります:

options:
  --dry-run     original dry-run option
  ...
  -n, --noisy   be noisy

以前に追加されたオプション文字列を切り詰めていって何も残らない ようにすることは可能ですが、そのオプションをコマンドラインから 起動する手段がなくなってしまうので注意してください。この場合、 optparse はオプションを完全に除去してしまうので、 こうしたオプションはヘルプテキストやその他のいずれにも表示 されなくなります。例えば、現在の OptionParser で 続けると:

parser.add_option("--dry-run", ..., help="new dry-run option")

この操作を行った時点で、最初の -n/--dry-run オプションはもはやアクセスできなくなり、optparse は 最初のオプションを除去します。ユーザがヘルプを要求すると、 以下のようなヘルプ:

options:
  ...
  -n, --noisy   be noisy
  --dry-run     new dry-run option

を読むことになるでしょう。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.3.5 オプションパーザへのクエリと操作 Up: 6.20.3 進んだ使い方 Next: 6.20.4 callback オプション


6.20.3.1 パーザを生成してオプションを追加する

パーザにオプションを加えていく方法はいくつかあります。一つ Options からなるリストを OptionParser のコンストラクタ に渡す方法です:

parser = OptionParser(option_list=[
    make_option("-f", "--filename",
                action="store", type="string", dest="filename"),
    make_option("-q", "--quiet",
                action="store_false", dest="verbose")])

(make_option() は Option クラスの別名、 すなわち Option のコンストラクタを呼び出すだけです。 optparse の将来のバージョンでは、おそらく Option を 複数のクラスに分割し、 make_option() は正しいクラスを 取り出してインスタンス化するファクトリ関数になるはずです。)

長い形式のオプションリストについては、リストを別に生成する方が しばしば便利です:

option_list = [make_option("-f", "--filename",
                           action="store", type="string", dest="filename"),
               # 17 other options ...
               make_option("-q", "--quiet",
                           action="store_false", dest="verbose")]
parser = OptionParser(option_list=option_list)

また、OptionParser の add_option() メソッドを 使って、オプションを一つ一つ追加することもできます:

parser = OptionParser()
parser.add_option("-f", "--filename",
                  action="store", type="string", dest="filename")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose")

このメソッドは Option コンストラクタが送出する例外を 簡単に追跡できるようにします。例外が発生するのはよくあることで、 これは数多くのキーワード引数間で複雑な相互依存関係が発生する ためです -- うまく指定がされていない場合、optparse は OptionError を送出します。

add_option() は以下の二つの方法のいずれかで呼び出す ことができます:

  • (make_option() が返すような) Option インスタンスを渡す 。
  • make_option() (すなわち Option の コンストラクタ) が受理できるような固定引数およびキーワード引数の 組み合わせを渡し、 Option インスタンスを生成する (上述)。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.3 進んだ使い方 Up: 6.20.3 進んだ使い方 Next: 6.20.3.2 オプションを定義する


6.20.4.1 callback オプションを定義する

例によって、コールバックオプションの定義は、直接 Option クラスをインスタンス化するか、OptionParser オブジェクト の add_option() メソッドを使うことで定義できます。 指定しなければならない属性は唯一 callback で、呼び出したい 関数を指定します:

parser.add_option("-c", callback=my_callback)

ここでは関数オブジェクトを与えなければならないことに注意して ください -- つまり、callback オプションを定義する時点で、 関数 my_callback() はすでに定義済みにしていなければ なりません。上の単純なケースでは、 optparse は -c が必要とする引数について何の知識もありません。 通常、これはオプションが何ら引数をとらない - コマンドライン上に -c が存在するかどうかだけが知りたいことの全てである - ことを意味します。しかし、状況によっては、コールバック関数 が任意の数の引数をコマンドライン引数から取り出したいと思うかも しれません。 これがコールバック関数の記述を難しくしているところです; これについては本ドキュメントの後の方でカバーします。

オプションの属性を定義する際に指定できる属性はいくつかあります:

type
通常の意味を持ちます: ``store'' や ``append'' アクションのように、 optparse に対して引数を一つ消費するように指示します。 この引数は type に変換できなければなりません。 optparse は値をどこかに保存する のではなく、type に変換してコールバック関数に渡します。

nargs
これも通常の意味を持ちます: この属性が与えられ、"nargs > 1"であるばあい、optparse は nargs 個の引数を取り出します。 各値は type に変換可能でなくてはなりません。その後、 変換された値からなるタプルがコールバック関数に渡されます。

callback_args
コールバックに渡す外部の固定引数からなるタプルです。

callback_kwargs
コールバックに渡す外部のキーワード引数です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.4 callback オプション Up: 6.20.4 callback オプション Next: 6.20.4.2 コールバック関数はどのように呼び出されるか


6.20.3.2 オプションを定義する

各 Option インスタンスは、同じ意味を持つ一群のコマンドライン オプション、すなわち同じ意味と効果をもつが、つづりが異なるような オプションを表します。任意の数の短いオプションと長いオプションを 指定することができますが、少なくとも一つのオプション文字列を与え なければなりません。

短い形式のオプション文字列を一つだけもつオプションを定義するには 以下のようにします:

make_option("-f", ...)

長い形式のオプション文字列を一つだけもつオプションを定義するには 以下のようにします:

make_option("--foo", ...)

``...'' は、Option オブジェクトの属性を定義する一群の キーワード引数を表しています。ある Option に対してどのような キーワードを与えれば十分かという問題はかなり複雑です (信じられない というなら、Option の数々の _check_*() メソッド群を 調べてみてください) が、だいたい 何がしか 指定しなければ なりません。うまく指定されていなければ、optparse は OptionError 例外を送出し、犯した間違いを説明してくれます。

オプションの中でもっとも重要な属性はアクション、すなわちコマンドライン 中でそのオプションが見つかったときにどうするかを決める属性です。 とりうるアクションを以下に挙げます:

store
[default] このオプションに対する引数を値として保存します。
store_const
定数値を保存します。
store_true
真を表す値を保存します。
store_false
偽を表す値を保存します。
append
このオプションに対する引数をリストに追加します。
count
カウンタを 1 増やします。
callback
指定された関数を呼び出します。
help
全てのオプションとそれに対するドキュメントを含めた、使用法メッセージ を出力します。

(アクションを指定しなければ、デフォルト値は ``store'' になります。 このアクションでは、 type と dest キーワードを 与えることができます; 以下を参照してください。)

ご覧のとおり、ほとんどのアクションは何らかの値を保存したり 更新したりする処理を含んでいます。optparse はこの処理の ために、常に特定のオブジェクト(Values クラスのインスタンス) を生成します。オプション引数 (とその他数々の値) は、 make_option()/add_option() の引数 dest (目的変数) に従って、このオブジェクトの属性として保存されます。

例えば、以下の呼び出し:

parser.parse_args()

を行うと、optparse は最初に行うことの一つとして、 values オブジェクトを生成します:

values = Values()

このパーザのオプションの一つが、以下:

make_option("-f", "--file", action="store", type="string", dest="filename")

のように定義されており、解析しているコマンドライン中に以下:

-ffoo
-f foo
--file=foo
--file foo

の文字列が含まれていれば、optparse は -f や --file オプションを見つけた際に、以下のコード:

  values.filename = "foo"

と同じ処理を行います。 明らかに、type と dest 引数は (大抵) action と ほぼ同じくらい大事なものです。 action は *全ての* オプションで 意味をなす唯一の属性ですが、最も重要な属性でもあります。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.3.1 パーザを生成してオプションを追加する Up: 6.20.3 進んだ使い方 Next: 6.20.3.3 オプションに対するアクション


6.20.2.6 エラー処理

基本的な使い方をする上でもう一つ知っておかなければならないのは、 optparse がコマンドライン上でエラーに遭遇した -- 例えば、-n が整数値のオプションの時に -n4x が指定された -- ときに、どのように振舞うかということです。

optparse は標準エラー出力に使用法メッセージを出力し、 有用かつ人間が読めるエラーメッセージを続けます。その後、 プログラムをゼロでない終了状態で終了し (sys.exit() を 呼び出し) ます。

この動作が気に入らないなら、OptionParser をサブクラスして error() メソッドを上書きしてください。 6.20.5 節、``optparse を拡張する'' を参照してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.2.5 バージョン番号を出力する Up: 6.20.2 基本的な使い方 Next: 6.20.2.7 全てをつなぎ合わせる


6.20.5.4 拡張の例

以下に optparse モジュールを拡張する例をいくつか示します。

まず、オプション解析で大小文字の区別をしないように変更しましょう:

from optparse import Option, OptionParser, _match_abbrev

# This case-insensitive option parser relies on having a
# case-insensitive dictionary type available.  Here's one
# for Python 2.2.  Note that a *real* case-insensitive
# dictionary type would also have to implement __new__(),
# update(), and setdefault() -- but that's not the point
# of this exercise.

class caseless_dict (dict):
    def __setitem__ (self, key, value):
        dict.__setitem__(self, key.lower(), value)

    def __getitem__ (self, key):
        return dict.__getitem__(self, key.lower())

    def get (self, key, default=None):
        return dict.get(self, key.lower())

    def has_key (self, key):
        return dict.has_key(self, key.lower())

class CaselessOptionParser (OptionParser):

    def _create_option_list (self):
        self.option_list = []
        self._short_opt = caseless_dict()
        self._long_opt = caseless_dict()
        self._long_opts = []
        self.defaults = {}

    def _match_long_opt (self, opt):
        return _match_abbrev(opt.lower(), self._long_opt.keys())

if __name__ == "__main__":
    from optik.errors import OptionConflictError

    # test 1: no options to start with
    parser = CaselessOptionParser()
    try:
        parser.add_option("-H", dest="blah")
    except OptionConflictError:
        print "ok: got OptionConflictError for -H"
    else:
        print "not ok: no conflict between -h and -H"

    parser.add_option("-f", "--file", dest="file")
    #print `parser.get_option("-f")`
    #print `parser.get_option("-F")`
    #print `parser.get_option("--file")`
    #print `parser.get_option("--fIlE")`
    (options, args) = parser.parse_args(["--FiLe", "foo"])
    assert options.file == "foo", options.file
    print "ok: case insensitive long options work"

    (options, args) = parser.parse_args(["-F", "bar"])
    assert options.file == "bar", options.file
    print "ok: case insensitive short options work"
Download as text (original file name: caseless.py).

次に、 optparse で ``必須オプション'' を実装する方法を二つ 挙げます。

その 1: アプリケーションが引数を解析した後に必ず呼び出すメソッドを OptionParser に追加します:

import optparse

class OptionParser (optparse.OptionParser):

    def check_required (self, opt):
      option = self.get_option(opt)

      # Assumes the option's 'default' is set to None!
      if getattr(self.values, option.dest) is None:
          self.error("%s option not supplied" % option)

parser = OptionParser()
parser.add_option("-v", action="count", dest="verbose")
parser.add_option("-f", "--file", default=None)
(options, args) = parser.parse_args()

print "verbose:", options.verbose
print "file:", options.file
parser.check_required("-f")
Download as text (original file name: required_1.py).

その 2: Option を拡張して required 属性を追加します; OptionParser を拡張して、必須オプションが引数解析語に存在する ことを確認させます:

import optparse

class Option (optparse.Option):
    ATTRS = optparse.Option.ATTRS + ['required']

    def _check_required (self):
        if self.required and not self.takes_value():
            raise OptionError(
                "required flag set for option that doesn't take a value",
                 self)

    # Make sure _check_required() is called from the constructor!
    CHECK_METHODS = optparse.Option.CHECK_METHODS + [_check_required]

    def process (self, opt, value, values, parser):
        optparse.Option.process(self, opt, value, values, parser)
        parser.option_seen[self] = 1

class OptionParser (optparse.OptionParser):

    def _init_parsing_state (self):
        optparse.OptionParser._init_parsing_state(self)
        self.option_seen = {}

    def check_values (self, values, args):
        for option in self.option_list:
            if (isinstance(option, Option) and
                option.required and
                not self.option_seen.has_key(option)):
                self.error("%s not supplied" % option)
        return (values, args)

parser = OptionParser(option_list=[
    Option("-v", action="count", dest="verbose"),
    Option("-f", "--file", required=1)])
(options, args) = parser.parse_args()

print "verbose:", options.verbose
print "file:", options.file
Download as text (original file name: required_2.py).
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.5.3 拡張を行う他の理由 optparse Up: 6.20.5 optparse を拡張する Next: 6.21 tempfile


6.20.5.3 拡張を行う他の理由 optparse

新たな型やアクションの追加は、optparse を拡張しようと考える 大きな、かつ明白な理由です。その他に少なくとも二つの分野がかかわって くると考えています。

一つ目の理由は簡単なものです: OptionParser は必要に応じて、 すなわちコマンドラインにエラーが生じたときはユーザがヘルプを要求 した際に sys.exit() を呼び出して役に立とうとします。 前者の場合、スクリプトをクラッシュさせてトレースバックを出力する 伝統的なやり方は受け入れがたいものです; このような応答を行うと、 ユーザはコマンドラインエラーを起こしたときにスクリプトにバグが あるのだと考えさせてしまいます。後者の場合、一般的にはヘルプを 出力した後に継続する利点はあまりありません。

この動作が目障りなら、 ``修正'' するのはさほど難しいことでは ありません。以下の実装をおこなわねばなりません。

  1. OptionParser をサブクラス化して error() メソッドを上書きします
  2. Option をサブクラス化して take_action() メソッドを上書きします -- アクション "help" の処理を自前で提供し、sys.exit() を呼ばない 用にする必要があるでしょう

もう一つの理由は、より複雑ですが、optparse で実装されている コマンドライン文法をオーバライドするということです。 この場合、オプションに対するアクションと型の機構はすべて捨ておき、 sys.argv を処理するコードを上書きします。 いずれの場合も、OptionParser をサブクラス化する必要があります; どれくらい徹底的に書き換えたいかによって、 parse_args()、 _process_long_opt()、および _process_short_opts() について、一つからすべてのメソッド を上書きする必要があるでしょう。

これらは両方とも、読者の練習課題として残しておきます。 実は私は両方とも自分では書いたことがありません。というのも、 optparse のデフォルトの (自然な) 動作で十分ハッピーで いられるからです。

Happy hacking、 そしてこの言葉を忘れないでください: ルークよ、source を使え (Use the Source, Luke)。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.5.2 新たなアクションを追加する Up: 6.20.5 optparse を拡張する Next: 6.20.5.4 拡張の例


6.20.2.4 ヘルプを作成する

どのスクリプトでも使うことになる機能の最後の一つは、optparse の機能を使ったヘルプメッセージの生成です。やらなければならないことは、 オプションを追加する際に help 値を指定することだけです。 新たなパーザを作成し、ユーザに優しい (ドキュメント付きになっている) オプションを追加していきましょう:

usage = "usage: %prog [options] arg1 arg2"
parser = OptionParser(usage=usage)
parser.add_option("-v", "--verbose",
                  action="store_true", dest="verbose", default=1,
                  help="make lots of noise [default]")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose",
                  help="be vewwy quiet (I'm hunting wabbits)")
parser.add_option("-f", "--file", dest="filename",
                  metavar="FILE", help="write output to FILE"),
parser.add_option("-m", "--mode",
                  default="intermediate",
                  help="interaction mode: one of 'novice', "
                       "'intermediate' [default], 'expert'")

optparse がコマンドラインの解析中に -h か ---help に遭遇するか、または単に parser.print_help() を呼び出すと、以下の内容を 標準出力に出力します:

usage: <yourscript> [options] arg1 arg2

options:
  -h, --help           show this help message and exit
  -v, --verbose        make lots of noise [default]
  -q, --quiet          be vewwy quiet (I'm hunting wabbits)
  -fFILE, --file=FILE  write output to FILE
  -mMODE, --mode=MODE  interaction mode: one of 'novice', 'intermediate'
                       [default], 'expert'

optparse に可能な限り親切なヘルプメッセージを出力させる 上で役に立つと思われることを以下にざっと述べます:

  • スクリプト自体の使用法メッセージ (usage) を以下のようにして定義 します:

    usage = "usage: %prog [options] arg1 arg2"

    optparse は、使用法メッセージ文字列中の "%prog" に 現在のスクリプト名、すなわち os.path.basename(sys.argv[0]) を展開します。展開された文字列は、詳細なオプションヘルプの前に 出力されます。

    使用法メッセージ文字列を与えなければ、optparse は面白みの ない、とはいえ気の利いたデフォルト値: ``usage: %prog [options]'' を使います。スクリプトが固定引数を採っていなければ、この値で かまわないでしょう。

  • 各オプションはヘルプ文字列を定義していますが、行の折り返しに ついて悩むことはありません -- optparse が行を折り返し、 ヘルプメッセージ出力の見栄えがよくなるよう気を配ります。

  • 値をとるオプションについては、そのことを示す内容が ヘルプメッセージ内に自動的に生成されます。例えば、``mode'' オプションは:

    -mMODE, --mode=MODE

    となります。ここで、``MODE'' はメタ変数と呼ばれます: この値は ユーザが -m/--mode に対して指定するよう スクリプトが期待している引数を表します。デフォルトでは、 optparse は目的変数の名前を大文字に変換して、メタ変数として使います。 時にこれは期待通りの値になりません -- 例えば、上の例の filename オプションでは明示的に metavar="FILE" を設定しており、その結果 自動生成されたオプション説明は以下のようになります:

    -fFILE, --file=FILE

    この機能は重要なもので、それは表示スペースを節約するといった理由 にとどまりません: 上の例では、手作業で書かれたヘルプテキストの 中では、メタ変数として ``FILE'' を使っています。その結果、 ユーザに対して、堅苦しく表現された書法 ``-fFILE'' とくだけた 意味付け説明 ``write output to FILE'' が対応しているという情報 を与えます。これは、ヘルプテキストをエンドユーザに対してより明快で より有用にする上では、単純でありながら効果的な手法です。

数多くのオプションを扱うときには、オプションをグループ化すると ヘルプメッセージ出力をよりよくする上で便利です。OptionParser は複数のオプショングループを収めることができ、各グループは 複数のオプションを収めることができます。

上で定義されたパーザに続けて OptionGroup を追加するのは 簡単です:

group = OptionGroup(parser, "Dangerous Options",
                    "Caution: use these options at your own risk."
                    "  It is believed that some of them bite.")
group.add_option("-g", action="store_true", help="Group option.")
parser.add_option_group(group)

このコードは以下のヘルプ出力になります:

usage:  [options] arg1 arg2

options:
  -h, --help           show this help message and exit
  -v, --verbose        make lots of noise [default]
  -q, --quiet          be vewwy quiet (I'm hunting wabbits)
  -fFILE, --file=FILE  write output to FILE
  -mMODE, --mode=MODE  interaction mode: one of 'novice', 'intermediate'
                       [default], 'expert'

  Dangerous Options:
    Caution: use of these options is at your own risk.  It is believed that
    some of them bite.
    -g                 Group option.

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.2.3 デフォルト値を設定する Up: 6.20.2 基本的な使い方 Next: 6.20.2.5 バージョン番号を出力する


6.20.3.3 オプションに対するアクション

オプションに対する様々なアクションは全て、わずかに異なる要求事項と 効果を持っています。 ``help'' アクションを除き、Optionを 生成する際には少なくとも一つの別のキーワード引数を指定する必要があります; 各アクションに対する厳密な要求事項を以下に挙げます。

store
[relevant: type, dest, nargs, choices]

オプションの後には必ず引数が続き、type に従った値に変換されて dest に保存されます。nargs > 1 の場合、複数の引数が コマンドラインから取り出されます; 引数は全て type に従って 変換され、dest にタプルとして保存されます。 以下の 6.20.3 節、 ``オプションの型'' を 参照してください。

choices を指定 (文字列のリストかタプル) していれば、 型のデフォルト値は ``choice'' になります。

type が指定されなければ、デフォルト値は ``string'' になります。

dest が指定されない場合、 optparse は目的変数 を最初の長い形式のオプション文字列から導出します (例えば、 --foo-bar -> foo_bar)。長い形式のオプション文字列 がない場合、optparse は最初の短い形式のオプションから 目的変数名を導出します (例えば -f -> f)。

例:

make_option("-f")
make_option("-p", type="float", nargs=3, dest="point")

以下のコマンド:

-f foo.txt -p 1 -3.5 4 -fbar.txt

を与えると、 optparse は以下のように変数を設定します:

values.f = "bar.txt"
values.point = (1.0, -3.5, 4.0)

(実際のところ、 values.f は二度値設定されますが、 最終的には二回目の設定値だけが読み取れます。)

store_const
[required: const, dest]

Option コンストラクタに与えられた const 値が dest に保存されます。

例:

make_option("-q", "--quiet",
       action="store_const", const=0, dest="verbose"),
make_option("-v", "--verbose",
       action="store_const", const=1, dest="verbose"),
make_option(None, "--noisy",
       action="store_const", const=2, dest="verbose"),

--noisy がなければ、 optparse は以下のように 値を設定します:

values.verbose = 2

store_true
[required: dest]

``store_const'' の特殊なケースで、真値 (厳密には整数の 1) を dest に保存します。

store_false
[required: dest]

``store_true'' と同じですが、偽値 (整数の 0) を保存します。

例:

make_option(None, "--clobber", action="store_true", dest="clobber")
make_option(None, "--no-clobber", action="store_false", dest="clobber")

append
[relevant: type, dest, nargs, choices]

オプションの後ろには引数が一つ続かなければなりません。この引数は dest に入っているリストに追加されます。dest のデフォルト値が 指定されていない (すなわち、デフォルト値が Noneである) 場合、 optparse が最初にコマンドライン中にこのオプションを見つけた際に 空のリストが自動的に生成されます。 "nargs > 1" であれば、複数の引数が取り出され、長さ nargs のタプルが dest に追加されます。

type と dest のデフォルト値は ``store'' アクションの値と 同じです。

例:

make_option("-t", "--tracks", action="append", type="int")

-t3 がコマンドライン上で見つかると、optparse は以下と等価な処理を行います:

values.tracks = []
values.tracks.append(int("3"))

その後で "-tracks=4" が見つかると、さらに以下の処理を行います:

values.tracks.append(int("4"))

optparse が "-tracks=x" のような指定をどのように 扱うかについての情報は、 ``エラー処理'' ( 6.20.2 節) を参照してください。

count
[required: dest]

dest に保持されている整数値をインクリメント (1 増加) させます。 dest は (デフォルトの値を指定しない限り) 最初にインクリメントを 行う前にゼロに設定されます。

例:

make_option("-v", action="count", dest="verbosity")

最初に -v がコマンドライン上で見つかった際、 optparse は以下と等価な処理:

values.verbosity = 0
values.verbosity += 1

を行います。その後 -v が見つかると、さらに以下の処理:

values.verbosity += 1

を行います。

callback
[required: 'callback'; relevant: type, nargs, callback_args, callback_kwargs]

callback に指定された関数を呼び出します。この関数の 用法は以下のようになっています:

func(option : Option,
     opt : string,
     value : any,
     parser : OptionParser,
     *args, **kwargs)

callback オプションについての詳細は、 6.20.4 節、 ``callback オプション'' でカバーされています。

help
[required: none]

現在のオプションパーザ内にある全てのオプション対する完全な ヘルプメッセージを出力します。ヘルプメッセージは OptionParser のコンストラクタに渡された usage 文字列と、各オプションに 渡された help 文字列から生成されます。

オプションに help 文字列が指定されていなくても、ヘルプメッセージ 中には列挙されます。オプションを完全に表示させないようにするには、 特殊な値 optparse.SUPPRESS_HELP を使います。

例:

from optparse import Option, OptionParser, SUPPRESS_HELP

usage = "usage: %prog [options]"
parser = OptionParser(usage, option_list=[
  make_option("-h", "--help", action="help"),
  make_option("-v", action="store_true", dest="verbose",
              help="Be moderately verbose")
  make_option("--file", dest="filename",
              help="Input file to read data from"),
  make_option("--secret", help=SUPPRESS_HELP)

optparse がコマンドライン上に --h または --help を見つけると、以下のようなヘルプメッセージを 標準出力に出力します:

usage: <yourscript> [options]

options:
  -h, --help        Show this help message and exit
  -v                Be moderately verbose
  --file=FILENAME   Input file to read data from

ヘルプメッセージの出力後、optparse は sys.exit(0) でプロセスを終了します。

version
[required: none]

OptionParser に指定されているバージョン番号を標準出力に 出力して終了します。バージョン番号は、実際には OptionParser のprint_version() メソッドで書式化されてから出力されます。 通常、 OptionParser のコンストラクタに version が指定されたときのみ関係のあるアクションです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.3.2 オプションを定義する Up: 6.20.3 進んだ使い方 Next: 6.20.3.4 オプションの型


6.20.3.4 オプションの型

optparse は 6 種類のすばらしいオプション型: string (文字列)、int (整数)、 long (長整数)、 choice (選択項目)、 float (浮動小数点数) および complex (複素数) をサポートしています。(この中で、string、 int、 float、および choice が最もよく使われます - long と complex は主にオプション型を完全に そろえるするために存在しています。) 新たなオプションの型は、Option クラスをサブクラス化することで 簡単に追加できます; 6.20.5 節、 ``optparse を拡張する'' を参照してください。

文字列オプションの引数は、チェックしたり変換したりはしません: コマンドライン上のテキストが目的変数にそのまま保存されます (または コールバックに渡されます)。

整数引数は int() に渡され、Python 整数に変換されます。 int() が失敗すると optparse も失敗に終わりますが、 より役に立つエラーメッセージを伴います。 内部的には、optparse は optparse.check_builtin() で OptionValueError を送出します; より高水準 (OptionParser 内) では、この例外が捕捉され、 optparse はエラーメッセージを伴ってプログラムを停止させます。

同様に、浮動小数点数引数は float() 、 長整数引数は long() 、複素数引数は complex() に渡されて変換されます。それ以外では、値は整数引数の場合と同様に 扱われます。

選択項目オプションは文字列オプションのサブタイプです。 マスタリストや選択項目のリスト (文字列) はオプションコンストラクタ (make_option() や OptionParser.add_option()) に ``choices'' キーワード引数として渡されなければなりません。 選択項目オプション引数は optparse.check_choice() 内でマスタリストと比較され、マスタリストにない文字列が指定された 場合には OptionValueError が送出されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.3.3 オプションに対するアクション Up: 6.20.3 進んだ使い方 Next: 6.20.3.5 オプションパーザへのクエリと操作


6.20.1.2 オプションはどう使うのでしょうか？

オプションはプログラムの実行をチューニングしたり、カスタマイズ したりするための補足的な情報を与えるために使われます。 補足すると、オプションは通常 選択可能 (optional) となっています。 プログラムはいかなるオプションが指定されていなくても、きちんと 動作できなくてはなりません。(Unix や GNU ツールセットから プログラムをランダムに取り出してみてください。プログラムは オプション無しで動作して、意味のある結果になるでしょう？ 私の知っている例外は find 、 tar 、 dd といったプログラムです -- これらは全て 変種のはみだし者で、インタフェースが非標準で混乱をまねくものだと 批判されてきました。)

大多数の人々が、プログラムに ``必須オプション'' を持たせたいと 望んでいます。しかし考えてみてください。もしオプションが必須だと いうのなら、そのオプションは オプション:選択可能項目 など ではありません！ プログラムがうまく動作するために絶対的に必要とする 情報があるとするなら、固定引数を使うべきです。(とはいえ、 どうしても ``必須オプション'' をプログラムに組み込みたいというのなら、 optparse を使った実装方法については ``拡張の例'' ( 6.20.5 節) を読んでください。

ファイルをコピーする地味なユーティリティ cp について 考えてみましょう。ファイルをコピーしようと試みるときに、コピー先 や少なくとも一つのコピー元を指定しなければ、このコマンドは意味を なしません。従って、cp は引数無しで実行すると失敗します。 しかしながら、このコマンドは、拡張性のある便利な書法を持っており、 オプションに全然頼っていません:

$ cp SOURCE DEST
$ cp SOURCE ... DEST-DIR

You can get pretty far with just that. ほとんどの cp の実装では、ファイルをどのようにしてコピー するかを的確に微調整するためのオプション: 例えばファイルモードや最終更新時刻を変更しないようにしたり、 シンボリックリンクの追跡を避けたり、既存のファイルをぶちこわし (clobber) にする前に同意を求めたり、などを一そろい提供しています。 しかし、これらのオプションはいずれも、 ファイルを別のファイルにコピーしたり N 個のファイルを他のディレクトリ にコピーしたりするといった、cp の主要な役割を混乱 させることはありません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.1.1 用語 Up: 6.20.1 オプション解析への道 Next: 6.20.1.3 固定引数はどう使うのでしょうか？


6.20.2.2 その他の "store_*" 操作

フラグオプション -- 特定のオプションが見つかったときに、ある変数を 真または偽にする -- は、とても一般的な機能です。optparse では、フラグオプションを二つの別個のアクション ``store_true'' と ``store_false'' でサポートします。例えば、 verbose フラグが -v でオンにされ、 -q でオフにされると します:

parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose")

ここで二つのオプションを同じ目的変数に設定しましたが、これは全く 問題ありません。 (ただし、デフォルト値を設定する際に少しだけ 注意する必要があります -- 以下を参照してください。)

optparse が -v をコマンドライン内に見つけると、 特殊な option values オブジェクトのverbose 属性を 1 に 設定します; -q が見つかれば、 verbose を 0 に 設定します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.2.1 "store" アクション Up: 6.20.2 基本的な使い方 Next: 6.20.2.3 デフォルト値を設定する


6.20.1.3 固定引数はどう使うのでしょうか？

上の例について補足します: 固定引数とは、プログラムを動作させる ために、絶対的にかつ明確に必要とされる情報の断片です。

よいユーザインタフェースとは、可能な限り少ない固定引数をもつ べきです。プログラムを正しく動作させるために 17 個もの別個の情報が 必要だとしたら、その情報をユーザからどうやって引き出そうかという ことはさほど問題にはなりません -- ほとんどの人はプログラム を正しく動作させられるようになる前にあきらめて立ち去るでしょう。 これはユーザインタフェースがコマンドラインでも、設定ファイルでも GUI やその他のいずれであっても当てはまることがらです: 多くの要求をユーザに押し付ければ、ほとんどのユーザはただ 音をあげるだけなのです。

要するに、ユーザが絶対に提供しなければならない情報だけに制限する -- 可能な限りよく練られたデフォルト設定を使うよう試みてください。 もちろん、プログラムには適度な柔軟性を持たせたいとも望むはずですが、 それこそがオプションの果たす役割です。繰り返しますが、 設定ファイルのエントリであろうが、 GUI の ``環境設定'' ダイアログにあるチェックボックスであろうが、 コマンドライン上のオプションであろうが関係ありません -- より多くオプションを実装すればプログラムはより柔軟性を持ち、 実装はより難解になります。高すぎる柔軟性でユーザ (あなた自身もですよ！) を閉口させるのは至って簡単なのです。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.1.2 オプションはどう使うのでしょうか？ Up: 6.20.1 オプション解析への道 Next: 6.20.2 基本的な使い方


6.20.2.5 バージョン番号を出力する

要約された使用法メッセージ文字列と同様に、optparse は プログラムのバージョン文字列を出力できます。これを行うには、 version 引数を OptionParser に文字列で渡さなければ なりません:

parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")

``%prog'' が usage とまったく同じように展開されることに注意して ください。またこれとは別に、version には何でも必要なものを 入れることができます。version を指定すると、optparse は自動的に --version オプションをパーザに追加します。 コマンドライン上でこのオプションが見つかると、 version 文字列を (``%prog'' を置換して) 展開し、標準出力に 出力してから終了します。

例えば、スクリプトが /usr/bin/foo という名前なら、ユーザは以下のように するはずです:

$ /usr/bin/foo --version
foo 1.0
$

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.2.4 ヘルプを作成する Up: 6.20.2 基本的な使い方 Next: 6.20.2.6 エラー処理


6.20.3.5 オプションパーザへのクエリと操作

自前のオプションパーザをつつきまわして、何が起こるかを調べると便利 なことがあります。OptionParser では便利な二つのメソッドを提供 しています:

has_option( opt_str)
-q や --verbose のようなオプション文字列 に対して、OptionParser がオプションに対応している場合に 真を返します。

get_option( opt_str)
指定されたオプションを実装している Option インスタンスを 返します。実装されていなければ None を返します。

remove_option( opt_str)
OptionParser が opt_str に対するオプションを持っている 場合、そのオプションは削除されます。そのオプションが他の文字列で 指定することができる場合、それらのオプション文字列もすべて無効に なります。

opt_str がこの OptionParser オブジェクトのどのオプション にも属さない場合、ValueError を送出します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.3.4 オプションの型 Up: 6.20.3 進んだ使い方 Next: 6.20.3.6 オプション間の衝突


6.20.2.3 デフォルト値を設定する

上で述べてきた例は全て、あるコマンドラインオプションが見つかった 際に何らかの変数 (``destination: 目的変数'') の設定を伴うもの でした。ではこれらのオプションがなければどうなるのでしょうか？ デフォルト値を与えていないので、これらの値は全て None になります。 これはこれでよいときもあります (デフォルトで None になるように しているのはこのためです) が、もっときちんと制御したい場合も あります。その要求を満たすために、optparse では各目的変数 ごとにデフォルトの値を指定できるようにしており、デフォルト値は コマンドラインが解析される前に代入されます。

まず、 verbose/quiet の例を考えてみましょう。optparse に 対して、-q がない限り verbose を 1 に設定させたい なら、以下のようにします:

parser.add_option("-v", action="store_true", dest="verbose", default=1)
parser.add_option("-q", action="store_false", dest="verbose")

奇妙なことに、上のコードは以下とまったく等価です: Oddly enough, this is exactly equivalent:

parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose", default=1)

これらのコードが等価なのは、オプションの 目的変数 に対して デフォルト値を指定しており、各コードの二つのオプションは同じ 目的変数 (verbose 変数) を持っているからです。

以下のコード:

parser.add_option("-v", action="store_true", dest="verbose", default=0)
parser.add_option("-q", action="store_false", dest="verbose", default=1)

を考えてみましょう。繰り返しますが、verbose のデフォルト値は 1 です: 特定の目的変数に対するデフォルト値として有効なのは、最後に指定 した値です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.2.2 その他の "store_*" 操作 Up: 6.20.2 基本的な使い方 Next: 6.20.2.4 ヘルプを作成する


6.20.2.1 "store" アクション

アクションは、action が設定されているオプションがコマンド ライン内に見つかったときに optparse が行うべきことを 教えます。例えば、 store はこういう意味です: 次の引数 (または現在の引数の残りの部分) を取り上げ、正しい型であるか 確認して、決められた目的変数に保存します。

例として、先ほどのオプションの "..." を埋めてみましょう:

parser.add_option("-f", "--file",
                  action="store", type="string", dest="filename")

次に、架空のコマンドラインをでっち上げて、optparse に解析してもらいましょう:

args = ["-f", "foo.txt"]
(options, args) = parser.parse_args(args)

(引数リストを parse_args() に渡さなければ、 自動的に sys.argv[1:] を使うので注意してください。)

optparse が -f を見つけると、次の引数 -- ``foo.txt'' -- を吸出し、特殊なオブジェクトの filename 属性に記憶します。このオブジェクトは parse_args() の 戻り値の最初の値です。従って以下のコード:

print options.filename

は ``foo.txt'' を出力します。

optparse でサポートされている他のオプションの型は ``int'' と ``float'' です。以下に整数型の引数を要求するオプションの例を示し ます:

parser.add_option("-n", type="int", dest="num")

長い文字列によるオプションを与えていないことに注意してください。 これはまったく問題なく受理されます。 また、actionを指定していません -- これはアクションがデフォルト で ``store'' になるからです。

架空のコマンドラインをもう一つ解析してみましょう。今度は、 オプション引数をオプションの右側にぴったりくっつけて一緒くたに します -- -n42 (一つの引数のみ) は -n 42 (二つの引数からなる) と等価になります:

(options, args) = parser.parse_args(["-n42"])
print options.num

は ``42'' を出力します。

``float'' 型を使った例は、読者のための練習課題として残しておきます。

型を指定しない場合、 optparse は引数を ``string'' 型と 仮定します。デフォルトのアクションが ``store'' であることも 併せて考えると、最初の例はもっと短くなります:

parser.add_option("-f", "--file", dest="filename")

目的変数名を与えなければ、optparse はオプション文字列 から気の利いたデフォルト値を決めます: 最初の長い形式のオプション 文字列が --foo-bar だったとすると、デフォルトの 目的変数は foo_bar となります。長い形式のオプションが ない場合、optparse は最初の短いオプションに注目します: -f に対するデフォルトの目的変数は f となります。

型を追加するのはかなり簡単です; 6.20.5 節、 ``新しい型を追加する'' を参照してください。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.2 基本的な使い方 Up: 6.20.2 基本的な使い方 Next: 6.20.2.2 その他の "store_*" 操作


6.20.1.1 用語

まずは用語の定義を行う必要があります。

引数 (argument)
コマンドラインでユーザが入力するテキストの塊で、シェルが execl() や execv() に引き渡すものです。 Python では、引数は sys.argv[1:] の要素となります。 (sys.argv[0] は実行しようとしているプログラムの名前です。 引数解析に関しては、この要素はあまり重要ではありません。) Unix シェルでは、 ``語 (word)'' という用語も使います。

場合によっては sys.argv[1:] 以外の引数リストを代入する方が 望ましいことがあるので、``引数'' は ``sys.argv[1:] または sys.argv[1:] の代替として提供される別のリストの要素'' と読解するべきでしょう。

オプション (option)
追加的な情報を与えるための引数で、プログラムの実行に対する教示や カスタマイズを行います。オプションには多様な文法が存在します; 伝統的な Unix における書法は - の後ろに一文字 が続くもので、例えば -x や -F です。 また、伝統的な Unix における書法では、複数のオプションを 一つの引数にまとめることができ、例えば -x -F は -xF と等価です。 GNU プロジェクトでは -- の後ろにハイフンで区切られた 語を続ける方法、例えば --file や --dry-run を導入しています。optparse ではこれら二種類のオプション書法 だけを提供しています。

他に見られる他のオプション書法には以下のようなものがあります:

  • ハイフンの後ろに数個の文字が続くもので、例えば -pf 。 (このオプションは複数のオプションを一つにまとめたものとは *違います*。)
  • ハイフンの後ろに語が続くもので、例えば -file 。 (これは技術的には上の書式と同じですが、通常同じプログラム上で一緒に 使われることはありません。)
  • プラス記号の後ろに一文字、数個の文字、または語を続けたもので、例えば +f 、 +rgb 。
  • スラッシュ記号の後ろに一文字、数個の文字、または語を続けたもので、例えば /f 、 /file 。

これらのオプション書法は optparse ではサポートされておらず、 将来にわたってサポートされることもありません。 (これらのオプション 書法のいずれかを本当に使いたいのなら、 OptionParser をサブクラス化 して、難解な部分を全て上書きしなければならないでしょう。しかし できればやめてください！ optparse は熟慮の上で伝統的な Unix/GNU 的書法を採っています; 最初の 3 つの書法は場所によっては非標準 ですし、最後の書法は MS-DOS/Windows かつ/または VMS をターゲットに しているときしか意味をなしません。)

オプション引数 (option argument)
あるオプションの後ろに続く引数で、そのオプションに密接な関連を もち、オプションと同時に引数リストから取り出されます。 しばしば、オプション引数はオプションと一体の引数としてとりこまれる ことがあります。例えば以下:

    ["-f", "foo"]

は以下の引数:

    ["-ffoo"]

と等価なことがあります。(optparse ではこの書法をサポート しています)

あるオプションは引数をとることがなく、またあるオプションは 常に引数をとります。多くの人々が ``オプションのオプション引数'' 機能を欲しています。これ、あるオプションについては引数 が存在するときだけ引数をとり、そうでないときには引数をとらない ようにするという機能です。この機能は引数解析をあいまいにするため、 議論の的となる点です: 例えば、もし -a がオプション引数を とり、-b がまったく別のオプションだとしたら、 -ab をどうやって解析すればいいのでしょうか？ optparse は今のところこの機能をサポートしていません。

固定引数 (positional argument)
他のオプションが解析される、すなわち他のオプションとその引数が 解析されて引数リストから除去された後に引数リストに置かれている ものです。

必須のオプション (required option)
コマンドラインで与えなければならないオプションです; ``必須なオプション'' という言葉は矛盾のある語法であり、通常は貧弱なユーザインタフェース デザインと考えられています。 optparse では必須オプションの 実装を妨げはしませんが、とりたてて実装の役に立つようにもなっていません。 optparse で必須オプションを実装する方法については ``拡張の例'' (6.20.5 節) を参照してください。

例えば、以下のような架空のコマンドラインを考えてみてください:

  prog -v --report /tmp/report.txt foo bar

-v と --report は両方ともオプションです。 --report が引数を一つとると仮定すると、 ``/tmp/report.txt'' はオプション引数です。 ``foo'' および ``bar'' は固定引数です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 6.20.1 オプション解析への道 Up: 6.20.1 オプション解析への道 Next: 6.20.1.2 オプションはどう使うのでしょうか？


3.14.5.1 通常のクラスインスタンスの pickle 化および unpickle 化

pickle 化されたクラスインスタンスが unpickle 化されたとき、
__init__() メソッドは通常呼び出されません 。
unpickle 化の際に __init__() が呼び出される方が望ましい場合、
クラスにおいてメソッド __getinitargs__() を定義することが
できます。このメソッドはクラスコンストラクタ (すなわち __init__())
に渡されるべき タプルを 返さなければなりません。
__getinitargs__() メソッドは pickle 時に呼び出されます;
この関数が返すタプルはインスタンスの pickle 化データに組み込まれます。

クラスは、インスタンスの pickle 化方法にさらに影響を与えることが できます; クラスが __getstate__() メソッドを定義している 場合、このメソッドが呼び出され、返された状態値はインスタンスの内容 として、インスタンスの辞書の代わりに pickle 化されます。 __getstate__() メソッドが定義されていない場合、 インスタンスの __dict__ の内容が pickle 化されます。

unpickle 化では、クラスが __setstate__() も定義していた 場合、unpickle 化された状態値とともに呼び出されます 3.6。__setstate__() メソッドが定義 されていない場合、pickle 化された状態は辞書型でなければならず、 その要素は新たなインスタンスの辞書に代入されます。クラスが __getstate__() と __setstate__() の両方を定義して いる場合、状態値オブジェクトは辞書である必要はなく、これらのメソッド は期待通りの動作を行います。 3.7

警告: 新しいスタイルのクラスにおいて __getstate__() が負値を返す場合、__setstate__() メソッドは呼ばれません。

... 化された状態値とともに呼び出されます3.6
これらのメソッドはクラスインスタンスのコピーを 実装する際にもｔ用いられます
... は期待通りの動作を行います。3.7
このプロトコルはまた、 copy で定義されている浅いコピーや深いコピー操作でも用いら れます。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 3.14.5 pickle 化プロトコル Up: 3.14.5 pickle 化プロトコル Next: 3.14.5.2 拡張型の pickle 化および


import optparse

class OptionParser (optparse.OptionParser):

    def check_required (self, opt):
      option = self.get_option(opt)

      # Assumes the option's 'default' is set to None!
      if getattr(self.values, option.dest) is None:
          self.error("%s option not supplied" % option)

parser = OptionParser()
parser.add_option("-v", action="count", dest="verbose")
parser.add_option("-f", "--file", default=None)
(options, args) = parser.parse_args()

print "verbose:", options.verbose
print "file:", options.file
parser.check_required("-f")


import optparse

class Option (optparse.Option):
    ATTRS = optparse.Option.ATTRS + ['required']

    def _check_required (self):
        if self.required and not self.takes_value():
            raise OptionError(
                "required flag set for option that doesn't take a value",
                 self)

    # Make sure _check_required() is called from the constructor!
    CHECK_METHODS = optparse.Option.CHECK_METHODS + [_check_required]

    def process (self, opt, value, values, parser):
        optparse.Option.process(self, opt, value, values, parser)
        parser.option_seen[self] = 1

class OptionParser (optparse.OptionParser):

    def _init_parsing_state (self):
        optparse.OptionParser._init_parsing_state(self)
        self.option_seen = {}

    def check_values (self, values, args):
        for option in self.option_list:
            if (isinstance(option, Option) and
                option.required and
                not self.option_seen.has_key(option)):
                self.error("%s not supplied" % option)
        return (values, args)

parser = OptionParser(option_list=[
    Option("-v", action="count", dest="verbose"),
    Option("-f", "--file", required=1)])
(options, args) = parser.parse_args()

print "verbose:", options.verbose
print "file:", options.file


7.5.4.1 Semaphore の例

セマフォはよく有限なリソースを保護するために使われます。 例えばデータベースサーバーなどです。 リソースのサイズが固定されているすべての状況で、 有限セマフォを使用するべきです。 様々な労働者スレッドを産み出す前に、あなたのメインスレッドは セマフォを初期化するべきです:

maxconnections = 5
...
pool_sema = BoundedSemaphore(value=maxconnections)

いったん産み出せば、サーバーへ接続する必要が生じたときに、 労働者スレッドはセマフォのacquireとreleaseを呼出します:

pool_sema.acquire()
conn = connectdb()
... use connection ...
conn.close()
pool_sema.release()

有限セマフォの使用は、獲得した以上に解放したことを検出できないという プログラミングエラーを減らします。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 7.5.4 Semaphore オブジェクト Up: 7.5.4 Semaphore オブジェクト Next: 7.5.5 Event オブジェクト


4.9.1.3 StreamReader オブジェクト

StreamReader クラスは Codec のサブクラスで、以下のよう なメソッドを定義します。Python の codec レジストリと互換性を保つには、こ れらのメソッド全てを定義しなければなりません。

class StreamReader( stream[, errors])
StreamReader インスタンスのコンストラクタ。

全てのストリーム・リーダは、このインターフェースを持つコンストラクタを 定義しなければいけません。キーワード引数を追加しても構いませんが、ここ で定義されているものだけが、Python の codec レジストリから使われます。

ここでは Python の codec レジストリが使うものを説明します。

stream は（バイナリ）データを読み込み可能なファイル的オブジェク トでなければいけません。

The StreamReader は、errors キーワード引数を受けて、異なった エラー処理の仕組みを実装しても構いません。以下のパラメータは、あらか じめ定義されています。

  • 'strict' ValueError (または、そのサブクラス) を発生。これがデフォルトです。
  • 'ignore' 文字を無視して、次の文字から続ける。
  • 'replace' 適切な置換文字で置換。

errors 引数は、同名の属性に代入されます。この属性を変更するこ とで、StreamReader オブジェクトが生きている間に、異なるエ ラー処理に変更することができます。

errors 引数が取り得る値の種類は、register_error() で 拡張できます。

read( [size])
ストリームからのデータをデコードし、デコード済のオブジェクトを返す。

size は、デコードするためにストリームから読み込む、およその最大バ イト数を意味します。デコーダは、この値を適切な値に変更できます。デフォ ルト値 -1 にすると、可能な限りたくさんのデータを読み込みます。 size の目的は、巨大なファイルを1度にデコードするのを防ぐことです。

このメソッドは貪欲な読み込み戦略を取るべきです。すなわち、エンコーディ ング定義と size の値が許す範囲で、できるだけ多くのデータを読むべきだと いうことです。たとえば、ストリーム上にエンコーディングの終端や状態の目 印があれば、それも読み込みます。

readline( [size])
入力ストリームから1行読み込み、デコード済みのデータを返す。

readlines() とは異なり、このメソッドは改行情報を、元のストリ ームの readline() メソッドから継承します。- 行バッファの不足 のため、 現在、cedec のデコーダを使った改行のサポートはありません。し かし、サブクラスは可能であるなら、独自の改行情報を使って、このメソッド の実装を試みるべきです。

size が与えられた場合、ストリームにおける readline() の size 引数に渡されます。

readlines( [sizehint])
インプットストリームから全ての行を読み込み、行のリストとして返します。

改行は、codec デコーダ のメソッド実装され、リスト要素の中に含まれます。

sizehint が与えられた場合、 ストリームの read() メソッ ドに size 引数として渡されます。

reset( )
状態保持に使われた codec のバッファをリセットする。

ストリームの再配置を行うべきではないので注意してください。このメソッドは デコードの際のエラーから復帰できるようにすることを目的としたものです。

ここまでで挙げたメソッドに加えて、StreamReader は、元になってい るストリームから、他の全てのメソッドや属性を、継承しなければなりません。

次に挙げる2つの基底クラスは、利便性のために含まれています。codec レジスト リは、これらを必要としませんが、実際のところ、あると有用なものでしょう。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.9.1.2 StreamWriter オブジェクト Up: 4.9.1 Codec 基底クラス Next: 4.9.1.4 StreamReaderWriter オブジェクト


4.9.1.4 StreamReaderWriter オブジェクト

StreamReaderWriter を使って、読み書き両方に使えるストリームをラ ップできます。

lookup() 関数が返すファクトリ関数を使って、インスタンスを生成 するという設計です。

class StreamReaderWriter( stream, Reader, Writer, errors)
StreamReaderWriter インスタンスを生成する。 stream はフ ァイル的オブジェクトです。 Reader と Writer は、それぞれ StreamReader と StreamWriter インターフェイスを提供 するファクトリ関数かファク トリクラスでなければなりません。 エラー処 理は、ストリーム・リーダーとライターで定義したものと同じように行 われ ます。

StreamReaderWriter インスタンスは、StreamReader クラスと StreamWriterクラスを合わせたインターフェイスを継承します。元にな るストリームからは、他のメソッドや属性を継承します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.9.1.3 StreamReader オブジェクト Up: 4.9.1 Codec 基底クラス Next: 4.9.1.5 StreamRecoder オブジェクト


4.9.1.5 StreamRecoder オブジェクト

StreamRecoder はエンコーディングデータの、フロントエンド-バック エンドを観察する機能を提供します。異なるエンコーディング環境を扱うとき、 便利な場合があります。

lookup() 関数が返すファクトリ関数を使って、インスタンスを生成 するという設計になっています。

class StreamRecoder( stream, encode, decode, Reader, Writer, errors)
双方向変換を実装する StreamRecoder インスタンスを生成します。 encode と decode はフロントエンド (read() への入 力とwrite()からの出力) を処理し、Reader と Writer は バックエンド (ストリームに対する読み書き) を処理します。

これらのオブジェクトを使って、たとえば、Latin-1 から UTF-8、あるいは逆 向きの変換を、透過に記録することができます。

stream はファイル的オブジェクトでなくてはいけません。

encode と decode は Codec のインターフェイスに忠 実でなくてはいけません。Reader と Writer は、それぞれ StreamReader と StreamWriter のインターフェイスを提供 するオブジェクトのファクトリ関数かクラスでなくてはいけません。

encode と decode はフロントエンドの変換に必要で、 Reader と Writer はバックエンドの変換に必要です。中間のフ ォーマットはコデックの組み合わせによって決定されます。たとえば、 Unicode コデックは中間エンコーディングに Unicode を使います。

エラー処理はストリーム・リーダやライタで定義されている方法と同じように 行われます。

StreamRecoder インスタンスは、StreamReader と StreamWriter クラスを合わせたインターフェイスを定義します。また、 元のストリームのメソッドと属性も継承します。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.9.1.4 StreamReaderWriter オブジェクト Up: 4.9.1 Codec 基底クラス Next: 4.9.2 標準エンコーディング


4.9.1.2 StreamWriter オブジェクト

StreamWriter クラスは Codec のサブクラスで、以下のメソッ ドを定義しています。全てのストリーム・ライターは、Python の codec レジス トリとの互換性を保つために、これらのメソッドを定義する必要があります。

class StreamWriter( stream[, errors])
Constructor for a StreamWriter instance. StreamWriter インスタンスのコンストラクタ。

全てのストリーム・ライターのコンストラクタは、このインターフェイスを提 供しなければなりません。キーワード引数を追加しても構いませんが、Python の codec レジストリは、ここで定義される引数だけを使います。

stream は、（バイナリで）書き込み可能なファイル的なオブジェクト でなくてはいけ ません。

StreamWriter は、errors キーワード引数を受けて、異なった エラー処理の仕組みを実装しても構いません。以下のパラメータは、あらか じめ定義されています。

  • 'strict' ValueError (または、そのサブクラス) を発生。これがデフォルトです。
  • 'ignore' 文字を無視して、次の文字から続ける。
  • 'replace' 適切な置換文字で置換。
  • 'xmlcharrefreplace' 適切な XML 文字参照で置換。
  • 'backslashreplace' バックスラッシュ付きのエスケープシー ケンスで置換。

errors 引数は、同名の属性に代入されます。この属性を変更するこ とで、StreamWriter オブジェ クトが生きている間に、異なるエ ラー処理に変更することができます。

errors 引数が取り得る値の種類は、register_error() で 拡張できます。

write( object)
Writes the object's contents encoded to the stream. エンコードされた object の内容をストリームに書き出す。

writelines( list)
連結した、文字列リストを(おそらくは write() メソッドを再利 用して)ストリームに書き出す。

reset( )
状態保持に使われていた codec のバッファを、強制的に出力し、リセットす る。

このメソッドの呼び出したとき、出力先データをきれいな状態にし、状態を 元に戻すのにストリーム全体 を再スキャンすることなく、新しくフラッシュ するデータを追加できるように保障するべきです。

ここまでで挙げたメソッドに加えて、StreamWriter は、元になってい るストリームから、他の全てのメソッドや属性を、継承しなければなりません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 4.9.1.1 Codec オブジェクト Up: 4.9.1 Codec 基底クラス Next: 4.9.1.3 StreamReader オブジェクト


2.3.6.1 文字列メソッド

以下は 8 ビット文字列および Unicode オブジェクトでサポートされる メソッドです:

capitalize( )
最初の文字を大文字にした文字列のコピーを返します。

center( width)
width の長さをもつ中央寄せされた文字列を返します。パディングには 空白が使われます。

count( sub[, start[, end]])
文字列 S[start:end] 中に部分文字列 sub が出現する回数を返します。オプション引数 start および end はスライス表記と同じように解釈されます。

decode( [encoding[, errors]])
codec に登録された文字コード系 encoding を使って文字列をデコード します。encoding は標準でデフォルトの文字列エンコーディング になります。標準とは異なるエラー処理を行うために errors を 与えることができます。標準のエラー処理は 'strict' で、エンコード に関するエラーは ValueError を送出します。 他に利用できる値は 'ignore' および 'replace' です。 バージョン2.2 以降で新規追加された 仕様です。

encode( [encoding[,errors]])
文字列のエンコードされたバージョンを返します。標準のエンコーディング は現在のデフォルト文字列エンコーディングです。 標準とは異なるエラー処理を行うために errors を 与えることができます。標準のエラー処理は 'strict' で、エンコード に関するエラーは ValueError を送出します。 他に利用できる値は 'ignore' および 'replace' です。 バージョン2.0 以降で新規追加された 仕様です。

endswith( suffix[, start[, end]])
文字列の一部が suffix で終わるときに True を返します。そう でない場合 False を返します。オプション引数 start がある場 合、文字列の start から比較を始めます。end がある場合、文字 列の end で比較を終えます。

expandtabs( [tabsize])
全てのタブ文字が空白で展開された文字列のコピーを返します。 tabsize が与えられていない場合、タブ幅は 8 文字分 と仮定します。

find( sub[, start[, end]])
文字列中の領域 [start, end) に sub が含まれる場合、 その最小のインデクスを返します。 オプション引数 start および end はスライス表記と 同様に解釈されます。sub が見つからなかった場合 -1 を返します。

index( sub[, start[, end]])
find() と同様ですが、sub が見つからなかった場合 ValueError を送出します。

isalnum( )
文字列中の全ての文字が英数文字で、かつ 1 文字以上ある場合には真を返し、 そうでない場合は偽を返します。

isalpha( )
文字列中の全ての文字が英文字で、かつ 1 文字以上ある場合には真を返し、 そうでない場合はを返します。

isdigit( )
文字列中に数字しかない場合には真を返し、その他の場合は偽を返します。

islower( )
文字列中の大小文字の区別のある文字全てが小文字で、かつ 1 文字以上 ある場合には真を返し、そうでない場合は偽を返します。

isspace( )
文字列が空白文字だけからなり、かつ 1 文字以上ある場合には真を返し、 そうでない場合は偽を返します。

istitle( )
文字列がタイトルケース文字列であり、かつ 1 文字以上ある場合、 すなわち大文字は大小文字の区別のない文字の後にのみ続き、 小文字は大小文字の区別のある文字の後ろにのみ続く場合には真を返します。 そうでない場合は偽を返します。

isupper( )
文字列中の大小文字の区別のある文字全てが大文字で、かつ 1 文字以上 ある場合には真を返し、そうでない場合は偽を返します。

join( seq)
配列 seq 中の文字列を結合した文字列を返します。文字列を 結合するときの区切り文字は、このメソッドを適用する対象の文字列に なります。

ljust( width)
width の長さをもつ左寄せした文字列を返します。 パディングには空白が使われます。width が len(s) よりも小さい場合、元の文字列が返されます。

lower( )
文字列をコピーし、小文字に変換して返します。

lstrip( [chars])
文字列をコピーし、文字列の先頭部分を除去して返します。 chars が省略されるか None の場合、空白文字が 除去されます。chars が与えられていてかつ None でない場合、chars は文字列でなければなりません; このメソッドを適用した対象の文字列の先頭部分から chars 中の 文字が除去されます。 バージョン2.2.2 以降で変更された 仕様: 引数 chars をサポートしました

replace( old, new[, count])
文字列をコピーし、部分文字列 old のある部分全てを new に置換して返します。オプション引数 count が与えられて いる場合、先頭から count 個の old だけを置換します。

rfind( sub [,start [,end]])
文字列中の領域 [start, end) に sub が含まれる場合、 その最大のインデクスを返します。 オプション引数 start および end はスライス表記と 同様に解釈されます。sub が見つからなかった場合 -1 を返します。

rindex( sub[, start[, end]])
find() と同様ですが、sub が見つからなかった場合 ValueError を送出します。

rjust( width)
width の長さをもつ右寄せした文字列を返します。 パディングには空白が使われます。width が len(s) よりも小さい場合、元の文字列が返されます。

rstrip( [chars])
文字列をコピーし、文字列の末尾部分を除去して返します。 chars が省略されるか None の場合、空白文字が 除去されます。chars が与えられていてかつ None でない場合、chars は文字列でなければなりません; このメソッドを適用した対象の文字列の末端部分から chars 中の 文字が除去されます。 バージョン2.2.2 以降で変更された 仕様: 引数 chars をサポートしました

split( [sep [,maxsplit]])
sep を単語の境界として文字列を単語に分割し、分割された単語 からなるリストを返します。maxsplit が与えられた場合、最大 で maxsplit 個になるように分割します。sep が指定されて いないか None の場合、すべての空白文字が単語の境界になります。

splitlines( [keepends])
文字列を改行部分で分解し、各行からなるリストを返します。 keepends が与えられていて、かつその値が真でない限り、 返されるリストには改行文字は含まれません。

startswith( prefix[, start[, end]])
文字列の一部が prefix で始まるときに True を返します。そう でない場合 False を返します。オプション引数 start がある場 合、文字列の start から比較を始めます。end がある場合、文字 列の end で比較を終えます。

strip( [chars])
文字列をコピーし、文字列の先頭および末尾部分を除去して返します。 chars が省略されるか None の場合、空白文字が 除去されます。chars が与えられていてかつ None でない場合、chars は文字列でなければなりません; このメソッドを適用した対象の文字列の両端から chars 中の 文字が除去されます。 バージョン2.2.2 以降で変更された 仕様: 引数 chars をサポートしました

swapcase( )
文字列をコピーし、大文字は小文字に、小文字は大文字に変換して返します。

title( )
文字列をタイトルケースにして返します: 大文字から始まり、残りの 文字のうち大小文字の区別があるものは全て小文字にします。

translate( table[, deletechars])
文字列をコピーし、オプション引数の文字列 deletechars の中に 含まれる文字を全て除去します。その後、残った文字を変換テーブル table に従ってマップして返します。変換テーブルは長さ 256 の文字列でなければなりません。

Unicode オブジェクトの場合、translate() メソッドはオプションの deletechars 引数を受理しません。その代わり、メソッドは すべての文字が与えられた変換テーブルで対応付けされている s の コピーを返します。この変換テーブルは Unicode 順 (ordinal) から Unicode 順、Unicode 文字列、または None への対応付け でなくてはなりません。対応付けされていない文字は何もせず放置されます。 None に対応付けられた文字は削除されます。ちなみに、 より柔軟性のあるアプローチは、自作の文字対応付けを行う codec を codecs モジュールを使って作成することです (例えば encodings.cp1251 を参照してください。

upper( )
文字列をコピーし、大文字に変換して返します。

zfill( width)
数値文字列の左側をゼロ詰めし、幅 width にして返します。 width が len(s) よりも短い場合もとの文字列自体が 返されます。 バージョン2.2.2 以降で新規追加された 仕様です。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.6 配列型 Up: 2.3.6 配列型 Next: 2.3.6.2 文字列フォーマット操作


16.1.6.1 オプションの設定

オプションは色やウィジェットの境界線幅のようなものを制御します。オプションを三通りの方法で設定することができます:

オブジェクト作成時にキーワード引数を使用
:
fred = Button(self, fg = "red", bg = "blue")
オブジェクト作成後にオプション名を辞書インデックスのように扱う
:
fred["fg"] = "red"
fred["bg"] = "blue"
オブジェクト生成の後で複数の属性を更新するためのconfig()メソッドを使う
:
fred.config(fg = "red", bg = "blue")

あるオプションとその振る舞いの完全な説明には、問題のウィジェットのTkのmanページを参照してください。

manページには各ウィジェットの"STANDARD OPTIONS(標準オプション)"と"WIDGET SPECIFIC OPTIONS(ウィジェット固有のオプション)"が記載されていることに注意してください。前者は多くのウィジェットに共通のオプションのリストで、後者は特定のウィジェットに特有のオプションです。Standard Optionsはoptions(3) manページに記述されます。

このドキュメントでは標準とウィジェット特有のオプションを区別しません。あるオプションはある種のウィジェットに適用できません。任意のウィジェットが特定のオプションに応答するかどうかは、ウィジェットのクラスに依存します。ボタンはcommandオプションを持っていますが、ラベルは持っていません。

任意のウィジェットによってサポートされるオプションは、ウィジェットのmanページに記載されています。または、config()メソッドを引数なしで呼び出すか、ウィジェットのkeys()メソッドを呼び出すことで実行時に調べことができます。これらの呼び出しの戻り値は、キーがオプションの名前の文字列(例えば、'relief')で、値が5-タプルである辞書です。

bgのようないくつかのオプションは長い名前を持つ共通オプションに対する同義語です(bgは"background"を短縮したものです)。config()メソッドに省略オプション名を渡すと、5-タプルではなく2-タプルが返されます。返された2-タプルには、同義語の名前と``本物の''オプション(例えば、('bg', 'background'))が含まれています。

インデックス | 意味 | 例
0 | オプション名 | 'relief'
1 | データベース検索のためのオプション名 | 'relief'
2 | データベース検索のためのオプションクラス | 'Relief'
3 | デフォルト値 | 'raised'
4 | 現在の値 | 'groove'

例:

>>> print fred.config()
{'relief' : ('relief', 'relief', 'Relief', 'raised', 'groove')}

もちろん、表示された辞書はすべての利用可能なオプションと値を含んでいます。これは例としての意味しかありません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 16.1.6 便利なリファレンス Up: 16.1.6 便利なリファレンス Next: 16.1.6.2 Packer


2.3.9.3 関数

関数オブジェクトは関数定義によって生成されます。関数オブジェクトに 対する唯一の操作は、それを呼び出すことです: func(argument-list).

関数オブジェクトには実際には 2 つの種: 組み込み関数とユーザ定義関数 があります。両方とも同じ操作 (関数の呼び出し) をサポートしますが、 実装は異なるので、オブジェクトの型も異なります。

関数の実装では、 2 つの読み出し専用属性を追加しています: f.func_code は関数の コードオブジェクト (以下を参照) であり、 f.func_globals は関数のグローバル名前空間として使われる辞書です (f が定義されているモジュールを m としたときの m.__dict__ と同じです)。

関数オブジェクトはまた、例えば関数のメタ情報を関数に 付属させるといったことに使える、任意の属性の取得や設定をサポート しています。それらの属性の取得や設定には、正規の属性をドット表記する 方法が使われます。現在の実装では、関数の属性をサポートしている のはユーザ定義関数のみなので注意してください。組み込み関数の属性は 将来サポートされるかもしれません。

関数はもう一つの特殊な属性 f.__dict__ (f.func_dict として知られています) を持っており、 関数属性をサポートするために使われる名前空間を含んでいます。 __dict__ および func_dict は直接アクセスしたり、 辞書オブジェクトを設定することができます。関数の辞書は削除する ことができません。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.9.2 クラスおよびクラスインスタンス Up: 2.3.9 他の組み込み型 Next: 2.3.9.4 メソッド


2.3.9.10 内部オブジェクト

この情報については Python リファレンスマニュアル を読んで 下さい。このオブジェクトではスタックフレーム、トレースバック、 スライスオブジェクトを記述しています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.9.9 ブール値 Up: 2.3.9 他の組み込み型 Next: 2.3.10 特殊な属性


2.3.9.4 メソッド

メソッドは属性表記を使って呼び出される関数です。メソッドには二つの 種類があります: (リストへのappend()のような) 組み込みメソッド と、クラスインスタンスのメソッドです。組み込みメソッドはそれをサポート する型と一緒に記述されています。

実装では、クラスインスタンスのメソッドに 2 つの読み込み専用の属性 を追加しています: m.im_self はメソッドが操作するオブジェクト で、m.im_func はメソッドを実装している関数です。 m(arg-1, arg-2, ..., arg-n) の呼び出しは、m.im_func(m.im_self, arg-1, arg-2, ..., arg-n) の呼び出しと完全に等価です。

クラスインスタンスメソッドには、 メソッドがインスタンスからアクセス されるかクラスからアクセスされるかによって、それぞれバインド または 非バインド　があります。メソッドが非バインドメソッドの 場合、im_self 属性は None になるため、呼び出す際 には self オブジェクトを明示的に第一引数として指定しなければ なりません。この場合、self は非バインドメソッドのクラス (サブクラス) のインスタンスでなければならず、そうでなければ TypeError が送出されます。

関数オブジェクトと同じく、メソッドオブジェクトは任意の属性を取得 できます。しかし、メソッド属性は実際には背後の関数オブジェクト (meth.im_func) に記憶されているので、バインド、ヒバインド メソッドへのメソッド属性の設定は許されていません。 メソッド属性の設定を試みると TypeError が送出されます。 メソッド属性を設定するためには、その背後の関数オブジェクトで 明示的に:

class C:
    def method(self):
        pass

c = C()
c.method.im_func.whoami = 'my name is c'

のように設定しなければなりません。 詳しくは Python リファレンスマニュアル を読んで下さい。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.9.3 関数 Up: 2.3.9 他の組み込み型 Next: 2.3.9.5 コードオブジェクト


2.3.9.1 モジュール

モジュールに対する唯一の特殊な演算は属性へのアクセス: m.name です。ここで m はモジュールで、 name は m のシンボルテーブル上に定義された名前に アクセスします。モジュール属性も代入することができます。 (import 文は、厳密にいえば、モジュールオブジェクトに 対する演算です; import foo は foo と名づけられた モジュールオブジェクトが存在することを必要とはせず、 むしろ foo と名づけられた (外部の) モジュールの定義 を必要とします。)

各モジュールの特殊なメンバは __dict__ です。 これはモジュールのシンボルテーブルを含む辞書です。 この辞書を修正すると、実際にはモジュールのシンボルテーブルを変更 しますが、__dict__ 属性を直接代入することはできません (m.__dict__['a'] = 1 と書いて m.a を 1 に定義することはできますが、m.__dict__ = {} と 書くことはできません) 。

インタプリタ内に組み込まれたモジュールは、 <module 'sys' (built-in)> のように書かれます。 ファイルから読み出された場合、 <module 'os' from '/usr/local/lib/python2.3/os.pyc'> と書かれます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.9 他の組み込み型 Up: 2.3.9 他の組み込み型 Next: 2.3.9.2 クラスおよびクラスインスタンス


2.3.9.2 クラスおよびクラスインスタンス

これらに関しては、Python リファレンスマニュアル の 3 章および 7 章を読んで下さい。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.9.1 モジュール Up: 2.3.9 他の組み込み型 Next: 2.3.9.3 関数


2.3.6.4 変更可能な配列型

リストオブジェクトはオブジェクト自体の変更を可能にする追加の操作を サポートします。他の変更可能な配列型 (を言語に追加する場合) も、 それらの操作をサポートしなければなりません。 文字列およびタプルは変更不可能な配列型です: これらのオブジェクトは 一度生成されたらそのオブジェクト自体を変更することができません。 以下の操作は変更可能な配列型で定義されています (ここで x は 任意のオブジェクトとします):

操作 | 結果 | 注釈
s[i] = x | s の要素 s を x と入れ替えます |
s[i:j] = t | s の i から j 番目までの要素を t と入れ替えます |
del s[i:j] | s[i:j] = [] と同じです |
s[i:j:k] = t | s[i:j:k] の要素を t と入れ替えます | (1)
del s[i:j:k] | リストから s[i:j:k] の要素を削除します |
s.append(x) | s[len(s):len(s)] = [x] と同じです | (2)
s.extend(x) | s[len(s):len(s)] = x と同じです | (3)
s.count(x) | s[i] == x となる i の個数を返します |
s.index(x[, i[, j]]) | s[k] == x かつ i <= k < j となる最小の k を返します。 | (4)
s.insert(i, x) | i >= 0 の場合の s[i:i] = [x] と同じです | (5)
s.pop([i]) | x = s[i]; del s[i]; return x と同じです | (6)
s.remove(x) | del s[s.index(x)] と同じです | (4)
s.reverse() | s の値の並びを反転します | (7)
s.sort([cmpfunc=None]) | s の要素を並べ替えます | (7), (8), (9), (10)
Notes:

(1)
t は入れ替えるスライスと同じ長さでなければいけません。

(2)
かつての Python の C 実装では、複数パラメタを受理し、 非明示的にそれらをタプルに結合していました。この間違った機能は Python 1.4 で廃用され、Python 2.0 の導入とともにエラーにする ようになりました。

(3)
x がリストオブジェクトでない場合、例外を送出します。 extend() は実験的なメソッドであり、リスト以外の変更可能な 配列型ではサポートされていません。

(4)
x が s 中に見つからなかった場合 ValueError を送出します。　 負のインデクスが二番目または三番目のパラメタとして index() メソッドに渡されると、これらの値にはスライスのインデクスと同様に リストの長さが加算されます。加算後もまだ負の場合、その値はスライス のインデクスと同様にゼロに切り詰められます。 バージョン2.3 以降で変更された 仕様: 以前は、index() は開始位置や終了位置を 指定するのに負の数を使うことができませんでした

(5)
insert() の最初のパラメタとして負のインデクスが渡された場合、スライスのインデクスと同じく、リストの長さが加算されます。それでも負の値を取る場合、スライスのインデクスと同じく、0 に丸められます。 バージョン2.3 以降で変更された 仕様: 以前は、すべての負値は 0 に丸められていました。
(5)
配列の先頭に新しい要素が追加されます。

(6)
pop() メソッドはリストおよびアレイ型のみでサポート されています。オプションの引数 i は標準で -1 なので、 標準では最後の要素をリストから除去して返します。

(7)
sort() および reverse() メソッドは 大きなリストを並べ替えたり反転したりする際、容量の節約のために リストを直接変更します。副作用があることをユーザに思い出させるために、 これらの操作は並べ替えまたは反転されたリストを返しません。

(8)
sort() メソッドはオプションの引数として比較関数 をとります。この比較関数は二つの引数 (list items) をとり、最初の引数 が二つ目の引数と比べてより小さいか、等しいか、より大きいかによって、 それぞれ負、ゼロ、正の値を返します。この指定は並べ替え 処理をかなり低速化するので注意してください;

たとえば、リストを逆順に並べ替えるためにには、要素を反転して順序づけする ような比較関数で sort() を使うより、sort() の後に reverse() を呼ぶほうがはるかに高速です。比較関数として None を渡すことは、比較関数なしで sort() を呼ぶのと 同じ意味です。 バージョン2.3 以降で変更された 仕様: None を渡すのと、varcmpfunc を省略した場合とで、 同等に扱うサポートを追加

sort() メソッドに cmpfunc 引数を使う例として、シーケンスのリストを、シーケンスの 2 つ目の要素でソートする場合を考えてみましょう。

def mycmp(a, b):
    return cmp(a[1], b[1])

mylist.sort(mycmp)

それなりにサイズの大きいデータ構造に対しては、より時間効率のよりアプローチが、頻繁に使われます。

tmplist = [(x[1], x) for x in mylist]
tmplist.sort()
mylist = [x for (key, x) in tmplist]

(9)
sort() メソッドが安定しているかどうかは 言語上では定義されていません (比較結果が等しい要素の相対的な位置を 変えないことを保証しているとき、並べ替えが安定しているといいます)。 Python の C 実装では、Python 2.2 まで並べ替えはただ偶然に安定 していました。Python 2.3 の C 実装は安定な sort() メソッド を導入しましたが、異なる Python の実装間やバージョンの間での可搬性を 見込んだコードでは、この安定性に依存してはいけません。

(10)
リストが並べ替えられている間は、リストの変更はもとより、 その値の閲覧すらその結果は未定義です。

Python 2.3 の C 実装では、この間リストは空に見えるようになり、 並べ替え中にリストが変更されたことが検出されると ValueError が送出されます。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.6.3 XRange 型 Up: 2.3.6 配列型 Next: 2.3.7 マップ型


2.3.6.2 文字列フォーマット操作

文字列および Unicode オブジェクトには固有の操作: % 演算子 (モジュロ) があります。この演算子は文字列 フォーマット化 または 補間 演算としても知られています。 format % values (format は文字列または Unicode オブジェクト)とすると、format 中の % 変換指定は values 中のゼロ個またはそれ以上の要素で置換されます。 この動作は C 言語における sprintf() に似ています。 format が Unicode オブジェクトであるか、または %s 変換を使って Unicode オブジェクトが変換される場合、その結果も Unicode オブジェクトになります。

format が単一の引数しか要求しない場合、values は タプルでない単一のオブジェクトでもかまいません。 2.9それ以外の場合、values はフォーマット文字列中で指定された項目と 正確に同じ数の要素からなるタプルか、単一のマップオブジェクトでなければ なりません。

一つの変換指定子は 2 またはそれ以上の文字を含み、その構成要素は 以下からなりますが、示した順に出現しなければなりません:

  1. 変換指定子が開始することを示す文字 "%"。
  2. マップキー (オプション)。 丸括弧で囲った文字配列からなります (例えば (someone)) 。
  3. 変換フラグ (オプション)。一部の変換型の結果に影響します。
  4. 最小のフィールド幅 (オプション). "*" (アスタリスク) を指定した場合、実際の文字列幅が values タプルの次の要素から読み 出されます。タプルには最小フィールド幅やオプションの精度指定の後に 変換したいオブジェクトがくるようにします。
  5. 精度 (オプション)。"." (ドット) とその後に続く精度 で与えられます。"*" (アスタリスク) を指定した場合、精度 の桁数はタプルの次の要素から読み出されます。タプルには精度指定の 後に変換したい値がくるようにします。
  6. 精度長変換子 (オプション)。
  7. 変換型。

% 演算子の右側の引数が辞書の場合 (またはその他のマップ型の場合)、 文字列中のフォーマットには、辞書に挿入されているキーを丸括弧で囲い、文字 "%" の直後にくるようにしたものが含まれていなければ なりません 。マップキーはフォーマット化したい値をマップから 選び出します。例えば:

>>> print '%(language)s has %(#)03d quote types.' % \
          {'language': "Python", "#": 2}
Python has 002 quote types.

この場合、 * 指定子をフォーマットに含めてはいけません (* 指定子は順番付けされたパラメタのリストが必要だからです。)

変換フラグ文字を以下に示します:

フラグ | 意味
# | 値の変換に (下で定義されている) ``別の形式'' を使います。
0 | 数値型に対してゼロによるパディングを行います。
- | 変換された値を左寄せにします ("0" と同時に与えた 場合、"0" を上書きします) 。
 | (スペース) 符号付きの変換で正の数の場合、前に一つスペースを空けます (そうでない場合は空文字になります) 。
+ | 変換の先頭に符号文字 ("+" または "-") を付けます("スペース" フラグを上書きします) 。

精度長変換子として、h 、 l 、および L を使う ことができますが、Python では必要ないため無視されます。

変換型を以下に示します:

変換 | 意味 | 注釈
d | 符号付き 10 進整数。 |
i | 符号付き 10 進整数。 |
o | 符号なし 8 進数。 | (1)
u | 符号なし 10 進数。 |
x | 符号なし 16 進数 (小文字)。 | (2)
X | 符号なし 16 進数 (大文字)。 | (2)
e | 指数表記の浮動小数点数 (小文字). |
E | 指数表記の浮動小数点数 (大文字). |
f | 10 進浮動小数点数。 |
F | 10 進浮動小数点数。 |
g | 指数部が -4 以上または精度以下の場合には "e" 、それ以外の場合には "f" と同じ。 |
G | 指数部が -4 以上または精度以下の場合には "E" 、それ以外の場合には "F" と同じ。 |
c | 文字一文字 (整数または一文字からなる文字列を受理します)。 |
r | 文字列 (python オブジェクトを repr() で変換します)。 | (3)
s | 文字列 (python オブジェクトを str() で変換します)。 | (4)
% | 引数を変換せず、返される文字列中では文字 "%" になります。 |

注釈:

(1)
別形式の出力にした場合、変換結果の先頭の数字がゼロ ("0") でないときには、数字の先頭と左側のパディングとの間にゼロを挿入します。
(2)
別形式にした場合、変換結果の先頭の数字がゼロでないときには、 数字の先頭と左側のパディングとの間に '0x' または '0X' (フォーマット文字が "x" か "X" かに依存します) が挿入されます。
(3)
%r 変換は Python 2.0 で追加されました。
(4)
オブジェクトや与えられた書式が unicode 文字列の場合、変換後の文字列も unicode になります。

Python 文字列には明示的な長さ情報があるので、%s 変換において '\0' を文字列の末端と仮定したりはしません。

安全上の理由から、浮動小数点数の精度は 50 桁でクリップされます; 絶対値が 1e25 を超える値の %f による変換は %g 変換で置換されます 2.10その他のエラーは例外を送出します。

その他の文字列操作は標準モジュール string および re.で定義されています。

... タプルでない単一のオブジェクトでもかまいません。2.9
従って、一個のタプルだけをフォーマット出力したい場合には出力したいタプルを唯一の要素とする単一のタプルを values に与えなくてはなりません。
... 変換で置換されます2.10
この範囲に関する値はかなり適当なものです。 この仕様は、正しい使い方では障害とならず、かつ特定のマシンにおける 浮動小数点数の正確な精度を知らなくても、際限なく長くて意味のない数字から なる文字列を印字しないですむようにするためのものです。
Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.6.1 文字列メソッド Up: 2.3.6 配列型 Next: 2.3.6.3 XRange 型


2.3.6.3 XRange 型

xrange 型は値の変更不能な配列で、広範なループ処理に 使われています。xrange 型の利点は、 xrange オブジェクトは表現する 値域の大きさに関わらず常に同じ量のメモリしか占めないということです。 はっきりしたパフォーマンス上の利点はありません。

XRange オブジェクトは非常に限られた振る舞い、すなわち、インデクス検索、反復、 len() 関数のみをサポートしています。

Previous Page Up One Level Next Page Python ライブラリリファレンス Contents Module Index Index
Previous: 2.3.6.2 文字列フォーマット操作 Up: 2.3.6 配列型 Next: 2.3.6.4 変更可能な配列型


from datetime import tzinfo, timedelta, datetime

ZERO = timedelta(0)
HOUR = timedelta(hours=1)

# A UTC class.

class UTC(tzinfo):
    """UTC"""

    def utcoffset(self, dt):
        return ZERO

    def tzname(self, dt):
        return "UTC"

    def dst(self, dt):
        return ZERO

utc = UTC()

# A class building tzinfo objects for fixed-offset time zones.
# Note that FixedOffset(0, "UTC") is a different way to build a
# UTC tzinfo object.

class FixedOffset(tzinfo):
    """Fixed offset in minutes east from UTC."""

    def __init__(self, offset, name):
        self.__offset = timedelta(minutes = offset)
        self.__name = name

    def utcoffset(self, dt):
        return self.__offset

    def tzname(self, dt):
        return self.__name

    def dst(self, dt):
        return ZERO

# A class capturing the platform's idea of local time.

import time as _time

STDOFFSET = timedelta(seconds = -_time.timezone)
if _time.daylight:
    DSTOFFSET = timedelta(seconds = -_time.altzone)
else:
    DSTOFFSET = STDOFFSET

DSTDIFF = DSTOFFSET - STDOFFSET

class LocalTimezone(tzinfo):

    def utcoffset(self, dt):
        if self._isdst(dt):
            return DSTOFFSET
        else:
            return STDOFFSET

    def dst(self, dt):
        if self._isdst(dt):
            return DSTDIFF
        else:
            return ZERO

    def tzname(self, dt):
        return _time.tzname[self._isdst(dt)]

    def _isdst(self, dt):
        tt = (dt.year, dt.month, dt.day,
              dt.hour, dt.minute, dt.second,
              dt.weekday(), 0, -1)
        stamp = _time.mktime(tt)
        tt = _time.localtime(stamp)
        return tt.tm_isdst > 0

Local = LocalTimezone()

# A complete implementation of current DST rules for major US time zones.

def first_sunday_on_or_after(dt):
    days_to_go = 6 - dt.weekday()
    if days_to_go:
        dt += timedelta(days_to_go)
    return dt

# In the US, DST starts at 2am (standard time) on the first Sunday in April.
DSTSTART = datetime(1, 4, 1, 2)
# and ends at 2am (DST time; 1am standard time) on the last Sunday of Oct.
# which is the first Sunday on or after Oct 25.
DSTEND = datetime(1, 10, 25, 1)

class USTimeZone(tzinfo):

    def __init__(self, hours, reprname, stdname, dstname):
        self.stdoffset = timedelta(hours=hours)
        self.reprname = reprname
        self.stdname = stdname
        self.dstname = dstname

    def __repr__(self):
        return self.reprname

    def tzname(self, dt):
        if self.dst(dt):
            return self.dstname
        else:
            return self.stdname

    def utcoffset(self, dt):
        return self.stdoffset + self.dst(dt)

    def dst(self, dt):
        if dt is None or dt.tzinfo is None:
            # An exception may be sensible here, in one or both cases.
            # It depends on how you want to treat them.  The default
            # fromutc() implementation (called by the default astimezone()
            # implementation) passes a datetime with dt.tzinfo is self.
            return ZERO
        assert dt.tzinfo is self

        # Find first Sunday in April & the last in October.
        start = first_sunday_on_or_after(DSTSTART.replace(year=dt.year))
        end = first_sunday_on_or_after(DSTEND.replace(year=dt.year))

        # Can't compare naive to aware objects, so strip the timezone from
        # dt first.
        if start <= dt.replace(tzinfo=None) < end:
            return HOUR
        else:
            return ZERO

Eastern  = USTimeZone(-5, "Eastern",  "EST", "EDT")
Central  = USTimeZone(-6, "Central",  "CST", "CDT")
Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
Pacific  = USTimeZone(-8, "Pacific",  "PST", "PDT")


この文書について...

Macintoshモジュールリファレンス, 平成16年6月28日, Release 2.3.3

このドキュメントは、 LaTeX2HTML 変換ツールを 使って生成されています。

LaTeX2HTML の著作権は、 Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds, and Copyright © 1997, 1998, Ross Moore, Mathematics Department, Macquarie University, Sydney.
となっています。

Python ドキュメントの LaTeX2HTML への対応は、 Fred L. Drake, Jr. の多大な努力で実現しました。 オリジナルのナビゲーションアイコンは、 Christopher Petrilli によるものです。

Comments and Questions

General comments and questions regarding this document should be sent by email to docs@python.org. If you find specific errors in this document, either in the content or the presentation, please report the bug at the Python Bug Tracker at SourceForge.

Questions regarding how to use the information in this document should be sent to the Python news group, comp.lang.python, or the Python mailing list (which is gated to the newsgroup and carries the same content).

For any of these channels, please be sure not to send HTML email. Thanks.

和訳に関するコメントや質問について

本和訳プロジェクトは、少なくとも 2004 年 4 月の時点では、 Python 本体の開発プロジェクトや Python 国際化 SIG による 取り組みの一部では ありません 。 和訳の内容、和訳プロジェクトに関するご意見やご質問は、 これらのプロジェクトあてにお送りにならないようお願いします。

和訳ドキュメントに関する誤りのご指摘やご質問、コメントは、 SourceForge.jp の Python ドキュメント和訳プロジェクト バグトラッカ から お送りください。

Python でのプログラミングに関する疑問など、このドキュメントに 書かれている情報の使い方についての質問は、 日本 Python ユーザ会メーリングリスト で行うとよいでしょう。

Previous Page Up One Level Macintoshモジュールリファレンス Contents Module Index Index
Previous: 索引 Up: Macintoshモジュールリファレンス


目次

  • 1. Mac OS 9でPythonを利用する
    • 1.1 MacPython-OSXの取得とインストール
      • 1.1.1 Pythonスクリプト実行方法
      • 1.1.2 GUIを利用したスクリプトの実行
      • 1.1.3 設定
    • 1.2 MacPython-OS9の取得とインストール
      • 1.2.1 対話型インタプリタを使う
      • 1.2.2 Pythonスクリプトの走らせ方
      • 1.2.3 コマンドライン引数をシミュレートする
      • 1.2.4 Pythonスクリプトを作成する
      • 1.2.5 設定を行なう
    • 1.3 統合開発環境
      • 1.3.1 ``Python Interactive''ウィンドウを使う
      • 1.3.2 Pythonスクリプトを書く
      • 1.3.3 統合開発環境の中からスクリプトを実行する
      • 1.3.4 ``Save as''対``Save as Applet''
  • 2. MacPython モジュール
    • 2.1 mac -- os モジュールの実装
    • 2.2 macpath -- MacOS のパス操作関数
    • 2.3 macfs -- 各種のファイルシステムのサービス
      • 2.3.1 FSSpecオブジェクト
      • 2.3.2 エイリアスオブジェクト
      • 2.3.3 FInfoオブジェクト
    • 2.4 ic -- インターネット設定へのアクセス
      • 2.4.1 ICオブジェクト
    • 2.5 MacOS -- Mac OS インタプリタ機能へのアクセス
    • 2.6 macostools -- ファイル操作に便利なルーチン
    • 2.7 findertools -- finderのApple Eventsインターフェース
    • 2.8 EasyDialogs -- 基本的なMacintoshダイアログ
      • 2.8.1 プログレスバーオブジェクト
    • 2.9 FrameWork -- 対話型アプリケーション・フレームワーク
      • 2.9.1 アプリケーションオブジェクト
      • 2.9.2 ウィンドウオブジェクト
      • 2.9.3 コントロールウィンドウオブジェクト
      • 2.9.4 スクロールウィンドウオブジェクト
      • 2.9.5 ダイアログウィンドウオブジェクト
    • 2.10 autoGIL -- イベントループ中のグローバルインタープリタの取り扱い
  • 3. MacPython OSA モジュール
    • 3.1 gensuitemodule -- OSA スタプ作成パッケージ
    • 3.2 aetools -- OSA クライアントのサポート
    • 3.3 aepack -- Python変数とAppleEventデータコンテナ間の変換
    • 3.4 aetypes -- AppleEvent オブジェクト
    • 3.5 MiniAEFrame -- オープンスクリプティングアーキテクチャサーバのサポート
      • 3.5.1 AEServer オブジェクト
  • 4. MacOS ツールボックスモジュール
    • 4.1 Carbon.AE -- Apple Events
    • 4.2 Carbon.AH -- Apple ヘルプ
    • 4.3 Carbon.App -- アピアランスマネージャ
    • 4.4 Carbon.CF -- Core Foundation
    • 4.5 Carbon.CG -- Core Graphics
    • 4.6 Carbon.CarbonEvt -- Carbon Event Manager
    • 4.7 Carbon.Cm -- Component Manager
    • 4.8 Carbon.Ctl -- Control Manager
    • 4.9 Carbon.Dlg -- Dialog Manager
    • 4.10 Carbon.Evt -- Event Manager
    • 4.11 Carbon.Fm -- Font Manager
    • 4.12 Carbon.Folder -- Folder Manager
    • 4.13 Carbon.Help -- Help Manager
    • 4.14 Carbon.List -- List Manager
    • 4.15 Carbon.Menu -- Menu Manager
    • 4.16 Carbon.Mlte -- MultiLingual Text Editor
    • 4.17 Carbon.Qd -- QuickDraw
    • 4.18 Carbon.Qdoffs -- QuickDraw Offscreen
    • 4.19 Carbon.Qt -- QuickTime
    • 4.20 Carbon.Res -- Resource Manager and Handles
    • 4.21 Carbon.Scrap -- Scrap Manager
    • 4.22 Carbon.Snd -- Sound Manager
    • 4.23 Carbon.TE -- TextEdit
    • 4.24 Carbon.Win -- Window Manager
    • 4.25 ColorPicker -- 色選択ダイアログ
  • 5. 文書化されていないモジュール
    • 5.1 applesingle -- AppleSingle デコーダー
    • 5.2 buildtools -- BuildAppletとその仲間のヘルパーモジュール
    • 5.3 py_resource -- Python コードからのリソース生成
    • 5.4 cfmfile -- コードフラグメントリソースを扱うモジュール
    • 5.5 icopen -- open()と Internet Config の置き換え
    • 5.6 macerrors -- MacOSのエラー
    • 5.7 macresource -- スクリプトのリソースを見つける
    • 5.8 Nav -- NavServices の呼出し
    • 5.9 mkcwproject -- CodeWarrior プロジェクトの作成
    • 5.10 nsremote -- Netscape OSAモジュールのラッパー
    • 5.11 PixMapWrapper -- PixMapオブジェクトのラッパー
    • 5.12 preferences -- アプリケーション初期設定管理プログラム
    • 5.13 pythonprefs -- Python の初期設定管理プログラム
    • 5.14 quietconsole -- 不可視の標準出力
    • 5.15 videoreader -- QuickTime ムービーの読み込み
    • 5.16 W -- FrameWork 上に作られたウイジェット
    • 5.17 waste -- Apple製ではない TextEdit の置き換え
  • A. 歴史とライセンス
    • A.1 History of the software
    • A.2 Terms and conditions for accessing or otherwise using Python
  • B. 日本語訳について
    • B.1 このドキュメントについて
    • B.2 翻訳者一覧 (敬称略)
  • Module Index
  • 索引

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Module Index Index
Previous: 序 Up: Macintoshモジュールリファレンス Next: 1. Mac OS 9でPythonを利用する


1.2.2.2 クリエータをセットしてダブルクリックする

起動したいスクリプトが適当なクリエータコードとファイルタイプを持ってい るなら、スクリプトを起動するには単にダブルクリックすれば良い。 ``ダブ ルクリック可能''にするには、ファイルが "TEXT" タイプで、クリエー タコード"Pyth" である必要があります。

クリエータコードとファイルタイプをセットするには、IDEで行うか (節 1.3.2 と 1.3.4 を参照) Python モードを持つエディタ (BBEdit など)で行うか - これについては節 2 を参照、あるいは他のMacのユーティリティで 行えます。しかし、スクリプト(fixfiletypes.py)が MacPython に同 梱されていて、このスクリプトで Python により適切なタイプとクリエータコー ドをセットできるようになっています。

fixfiletypes.py スクリプトは、指定したディレクトリに対してファ イルタイプとクリエータコードを変えます。fixfiletypes.py は以下 のよう使います。

  1. スクリプトを、MacPython 配布物の Mac フォルダの中にある scripts フォル ダに置く。

  2. 修正したいスクリプトを、全部ひとつのフォルダに入れる。

  3. fixfiletypes.py アイコンをダブルクリックする。

  4. 修正したいファイルの入ったフォルダを選んで``Select current folder'' ボタンを押す。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.2.2.1 ドラッグ＆ドロップする Up: 1.2.2 Pythonスクリプトの走らせ方 Next: 1.2.3 コマンドライン引数をシミュレートする


1.2.5.3 デフォルトの起動オプション

EditPythonPrefs ダイアログボックスの ``Default startup options...''ボタンは、多くのオプションを提供します。例えば、スクリプト が終了した後で``Output''ウィンドウを開いたままにしたり、スクリプトの実行 が終了した後で対話モードに入るようにしたりできます。後者は、スクリプト の途中で生成されたオブジェクトを検査する場合にとても便利です。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.2.5.2 モジュール検索パスにモジュールを追加する Up: 1.2.5 設定を行なう Next: 1.3 統合開発環境


1.2.5.1 EditPythonPrefs

EditPythonPrefs を利用して自分が望むような動作を Python にさ せるための設定をする事ができます。EditPythonPrefs は、初期設 定を設定することと、特別版のPython実行ファイルをドロップしてカスタマイ ズすること、の2つの事ができます。例えば、普段は正常終了したら出力ウィ ンドウが閉じるが、正常終了した時に出力ウィンドウを開きっぱなしにしたい などの理由で PythonInterpreter の別のコピーを持ちたい場合、 後者の方法で手軽にできます。

デフォルト初期設定を変更するためには、単に EditPythonPrefs をダブルクリックしてください。インタープリタの1つのコピーのみに対す る変更は、EditPythonPrefs に対象となるコピーをドロップしてく ださい。さらに、Python IDE および任意のアプレットの初期設定 を設定するために、この方法で EditPythonPrefs を使用すること ができます。節 1.3.4 を参照してください。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.2.5 設定を行なう Up: 1.2.5 設定を行なう Next: 1.2.5.2 モジュール検索パスにモジュールを追加する


序

Copyright © 2001, 2002, 2003 Python Software Foundation. All rights reserved.

Copyright © 2000 BeOpen.com. All rights reserved.

Copyright © 1995-2000 Corporation for National Research Initiatives. All rights reserved.

Copyright © 1991-1995 Stichting Mathematisch Centrum. All rights reserved.

Translation Copyright © 2003 Python Document Japanese Translation Project. All rights reserved.

ライセンスおよび許諾に関する完全な情報は、このドキュメントの末尾を 参照してください。

概要:

このライブラリリファレンスマニュアルでは、Macintosh用のPython拡張に関 して詳しく記述します。Python Library Reference も同時に参照しながら利用するようにしてください。標準ライブラリと組み込み型はそちら に詳しく書かれています。

このマニュアルを読むにあたっては、Python言語の基礎知識を持っていること が必要です。Pythonの肩のこらない入門編が必要なら、 Python Tutorialを読んでください。 Python Reference Manualは、構文や意味論に 関する疑問を解決するため、それなりに分かった人が読むべきものです。最 後にひとつ。インタプリタの拡張と組み込み Extending and Embedding the Python Interpreter という名のマニュアルでは、Pythonへ新たに拡張機能を追加す る方法と、他のアプリケーションに組み込む方法について述べています。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: Macintoshモジュールリファレンス Up: Macintoshモジュールリファレンス Next: 目次


1.2.2.1 ドラッグ＆ドロップする

一番簡単に Python スクリプトを起動させるのは、``ドラッグ＆ドロップ''経 由で行うことです。これはファインダで、テキストファイルをワードプロセッ サのアイコンの上に``ドラッグ''し、そこに``ドロップ''して起動させるのに 似ています。``ドラッグ＆ドロップ''による Python スクリプトの起動には PythonInterpreter を使うように気をつけてください。 IDE や Idle では、以下に示すのとは、異なる振る舞い になってしまいます。

ただ問題もいくつかあります。

  • PythonInterpreter の上にスクリプトをドロップした後にウィン ドウがフラッシュするが、その後消えてしまう場合。恐らく、これはシステ ムの設定関連の問題です。PythonInterpreter は実行完了の後す ぐに終了するよう設定されているのに、スクリプトが何か表示するものがあっ たらしばらく待つ事を想定して作成されている場合です。これを修正するに は、節 1.2.5 を参照してください。

  • スクリプトのアイコンを PythonInterpreter の上に重ねようとふ らふらさせても、 PythonInterpreter がハイライトにならない場 合。これは、たぶんクリエータコードと文書のタイプがセットされていない(ある いは誤ってセットされている)ためです。 - こういうことは、ファイルを Mac でないコ ンピュータから持ってきた場合に時々おこることです。詳細は節 1.2.2 を参照してください。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.2.2 Pythonスクリプトの走らせ方 Up: 1.2.2 Pythonスクリプトの走らせ方 Next: 1.2.2.2 クリエータをセットしてダブルクリックする


1.2.4.1 エディタでスクリプトを作成

MSWord や AppleWorks などのワードプロセッサプログ ラムでテキストファイルを作成することもできますが、ファイルを``ASCII'' か``プレインテキスト''で保存するよう気を付けてください。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.2.4 Pythonスクリプトを作成する Up: 1.2.4 Pythonスクリプトを作成する Next: 1.2.4.2 Pythonモード付きのエディタ


1.2.4.2 Pythonモード付きのエディタ

テキストエディタのうちいくつかは、Python スクリプトを作成するための機 能が付加されています。例えば、コードを読みやすくするために Python キー ワードに色を付けたり、モジュールのブラウズ、組み込みデバッガなどの機能 が含まれています。こうしたエディタには、Alpha、 Pepper、 BBedit、MacPython IDE(節 1.3)があり ます。1.2

... ます。1.2
訳注：mi(http://www.mimikaki.net/)にも Python モードがありますので利用してみてください。
Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.2.4.1 エディタでスクリプトを作成 Up: 1.2.4 Pythonスクリプトを作成する Next: 1.2.4.3 BBedit


1.2.4.3 BBedit

BBEdit でスクリプトを作成する時は、保存したファイルをダブル クリックすると起動できるように、エディタで Python クリエータコードを与 えると便利です。

  • BBEdit を立ち上げる。
  • ``Preferences''を``Edit''メニューを選択する。
  • スクローリングリストから``File Types''を選択する。
  • ``Add...''ボタンをクリックし、ナヴィゲーションダイアログから MacPython 配布物のディレクトリから PythonInterpreter を選んで、``open''をクリックする。
  • 設定パネルの``Save''ボタンをクリックする。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.2.4.2 Pythonモード付きのエディタ Up: 1.2.4 Pythonスクリプトを作成する Next: 1.2.5 設定を行なう


1.2.5.2 モジュール検索パスにモジュールを追加する

import 文を実行する時、Python は sys.path で定義し た場所のモジュールを探します。Mac 上で sys.path を編集するに は、EditPythonPrefs を起動し、パスを上部の大きめのフィールド に入力します(1行に1パス)。

MacPython はメイン Python ディレクトリを定義しているので、フォルダをメ イン Python ディレクトリに追加するのが最も簡単な方法です。作成したスク リプトを入れた``My Folder''という名前のフォルダをメイン Python ディレ クトリに追加するには、"$(PYTHON):My Folder" を新規行として入力し ます。

OS 9 かそれ以前の OS でデスクトップを追加するには、 "StartupDriveName:Desktop Folder" を新規行として入力します。

Previous Page Up One Level Next Page Macintoshモジュールリファレンス Contents Module Index Index
Previous: 1.2.5.1 EditPythonPrefs Up: 1.2.5 設定を行なう Next: 1.2.5.3 デフォルトの起動オプション


この文書について...

Python リファレンスマニュアル, 平成16年6月28日, Release 2.3.3

このドキュメントは、 LaTeX2HTML 変換ツールを 使って生成されています。

LaTeX2HTML の著作権は、 Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds, and Copyright © 1997, 1998, Ross Moore, Mathematics Department, Macquarie University, Sydney.
となっています。

Python ドキュメントの LaTeX2HTML への対応は、 Fred L. Drake, Jr. の多大な努力で実現しました。 オリジナルのナビゲーションアイコンは、 Christopher Petrilli によるものです。

Comments and Questions

General comments and questions regarding this document should be sent by email to docs@python.org. If you find specific errors in this document, either in the content or the presentation, please report the bug at the Python Bug Tracker at SourceForge.

Questions regarding how to use the information in this document should be sent to the Python news group, comp.lang.python, or the Python mailing list (which is gated to the newsgroup and carries the same content).

For any of these channels, please be sure not to send HTML email. Thanks.

和訳に関するコメントや質問について

本和訳プロジェクトは、少なくとも 2004 年 4 月の時点では、 Python 本体の開発プロジェクトや Python 国際化 SIG による 取り組みの一部では ありません 。 和訳の内容、和訳プロジェクトに関するご意見やご質問は、 これらのプロジェクトあてにお送りにならないようお願いします。

和訳ドキュメントに関する誤りのご指摘やご質問、コメントは、 SourceForge.jp の Python ドキュメント和訳プロジェクト バグトラッカ から お送りください。

Python でのプログラミングに関する疑問など、このドキュメントに 書かれている情報の使い方についての質問は、 日本 Python ユーザ会メーリングリスト で行うとよいでしょう。

Previous Page Up One Level Python リファレンスマニュアル Contents Index
Previous: 索引 Up: Python リファレンスマニュアル


目次

  • 1. 導入
    • 1.1 本マニュアルにおける表記法
  • 2. 字句解析
    • 2.1 行構造
      • 2.1.1 論理行 (logical line)
      • 2.1.2 物理行 (physical line)
      • 2.1.3 コメント
      • 2.1.4 エンコード宣言 (encoding declaration)
      • 2.1.5 明示的な行継続
      • 2.1.6 非明示的な行継続
      • 2.1.7 空行
      • 2.1.8 インデント
      • 2.1.9 トークン間の空白
    • 2.2 その他のトークン
    • 2.3 識別子 (identifier) およびキーワード (keyword)
      • 2.3.1 キーワード (keyword)
      • 2.3.2 予約済みの識別子種 (reserved classes of identifiers)
    • 2.4 リテラル (literal)
      • 2.4.1 文字列リテラル
      • 2.4.2 文字列リテラルの結合 (concatenation)
      • 2.4.3 数値リテラル
      • 2.4.4 整数および長整数リテラル
      • 2.4.5 浮動小数点数リテラル
      • 2.4.6 虚数 (imaginary) リテラル
    • 2.5 演算子 (operator)
    • 2.6 デリミタ (delimiter)
  • 3. データモデル
    • 3.1 オブジェクト、値、および型
    • 3.2 標準型の階層
    • 3.3 特殊メソッド名
      • 3.3.1 基本的なカスタマイズ
      • 3.3.2 属性値アクセスをカスタマイズする
      • 3.3.3 クラス生成をカスタマイズする
      • 3.3.4 呼び出し可能オブジェクトをエミュレートする
      • 3.3.5 コンテナをエミュレートする
      • 3.3.6 配列型エミュレーションで使われるその他のメソッド
      • 3.3.7 数値型をエミュレーションする
      • 3.3.8 型強制規則 (coercion rule)
  • 4. 実行モデル
    • 4.1 名前づけと束縛 (naming and binding)
      • 4.1.1 動的な機能とのやりとり
    • 4.2 例外
  • 5. 式 (expression)
    • 5.1 算術変換 (arithmetic conversion)
    • 5.2 アトム、原子的要素 (atom)
      • 5.2.1 識別子 (identifier、または名前 (name))
      • 5.2.2 リテラル
      • 5.2.3 丸括弧形式 (parenthesized form)
      • 5.2.4 リスト表現
      • 5.2.5 辞書表現
      • 5.2.6 文字列変換
    • 5.3 一次語 (primary)
      • 5.3.1 属性参照
      • 5.3.2 添字表記 (subscription)
      • 5.3.3 スライス表記 (slicing)
      • 5.3.4 呼び出し (call)
    • 5.4 べき乗演算 (power operator)
    • 5.5 単項算術演算 (unary arithmetic operation)
    • 5.6 二項算術演算 (binary arithmetic operation)
    • 5.7 シフト演算 (shifting operation)
    • 5.8 ビット単位演算の二項演算 (binary bit-wise operation)
    • 5.9 比較 (comparison)
    • 5.10 ブール演算 (boolean operation)
    • 5.11 ラムダ (lambda)
    • 5.12 式のリスト
    • 5.13 評価順序
    • 5.14 まとめ
  • 6. 単純文 (simple statement)
    • 6.1 式文 (expression statement)
    • 6.2 Assert 文 (assert statement)
    • 6.3 代入文 (assignment statement)
      • 6.3.1 累算代入文 (augmented assignment statement)
    • 6.4 pass 文
    • 6.5 del 文
    • 6.6 print 文
    • 6.7 return 文
    • 6.8 yield 文
    • 6.9 raise 文
    • 6.10 break 文
    • 6.11 continue 文
    • 6.12 import 文
      • 6.12.1 future 文 (future statement)
    • 6.13 global 文
    • 6.14 exec 文
  • 7. 複合文 (compound statement)
    • 7.1 if 文
    • 7.2 while 文
    • 7.3 for 文
    • 7.4 try 文
    • 7.5 関数定義
    • 7.6 クラス定義
  • 8. トップレベル要素
    • 8.1 完全な Python プログラム
    • 8.2 ファイル入力
    • 8.3 対話的入力
    • 8.4 式入力
  • A. 歴史とライセンス
    • A.1 History of the software
    • A.2 Terms and conditions for accessing or otherwise using Python
  • B. 日本語訳について
    • B.1 このドキュメントについて
    • B.2 翻訳者一覧 (敬称略)
  • 索引

Previous Page Up One Level Next Page Python リファレンスマニュアル Index
Previous: 序 Up: Python リファレンスマニュアル Next: 1. 導入


3.3.2.3 デスクリプタを呼び出す

一般にデスクリプタとは、 特殊な ``束縛に関する動作 (binding behaviour)'' をもつオブジェクト属性のことです。デスクリプタは、デスクリプタ プロトコル (descriptor protocol) のメソッド: __get__(), __set__(), および __delete__() を使って、属性アクセスをオーバライドしているものです。 これらのメソッドのいずれかがオブジェクトに対して定義されている場合、 オブジェクトはデスクリプタであるといいます。

属性アクセスのデフォルトの動作は、オブジェクトの辞書から値を取り出したり、 値を設定したり、削除したりするというものです。例えば、a.x による 属性の検索では、まず a.__dict__['x'] 、次に type(a).__dict__['x'] 、そしてtype(a) の基底クラスで メタクラスでないものに続く、といった具合に連鎖が起こります。

しかしながら、検索対象となる値が、デスクリプタメソッドのいずれかを 定義しているオブジェクトの属性値である場合、Python はデフォルトの動作を オーバライドして、デスクリプタメソッドの方を呼び出します。

前後する呼び出し連鎖の中のどこでデスクリプタメソッドが呼び出されるかは、 どのデスクリプタメソッドが定義されているかと、どうやってデスクリプタ メソッドが呼ばれるかに依存します。デスクリプタは新しい形式のオブジェクトや クラス (object() や type() をサブクラス化したもの) だけに 対して呼び出されるので注意してください。

デスクリプタ呼び出しの基点となるのは、属性名への束縛 (binding) 、すなわち a.x です。引数がどのようにデスクリプタに結合されるかは a に 依存します:

直接呼出し (Direct Call)
最も単純で、かつめったに使われない 呼び出し操作は、コード中で直接デスクリプタメソッドの呼び出し: x.__get__(a) を行うというものです。

インスタンス束縛 (Instance Binding)
新しい形式のクラスの インスタンスに対する束縛では、a.x は呼び出し: type(a).__dict__['x'].__get__(a, type(a)) に変換されます。

クラス束縛 (Class Binding)
新しい形式のクラスに対する束縛では、 A.x は呼び出し: A.__dict__['x'].__get__(None, A) に変換されます。

スーパクラス束縛 (Super Binding)
a が super のインスタンスである場合、束縛 super(B, obj).m() を行うと まず A 、続いて Bに対して obj.__class_.__mro__ を 検索し、次に呼び出し: A.__dict__['m'].__get__(obj, A) で デスクリプタを呼び出します。

インスタンス束縛では、デスクリプタ呼び出しの優先順位はどのデスクリプタが 定義されているかに依存します。データデスクリプタでは、 __get__() と __set__() を定義します。非データ デスクリプタには __get__() メソッドしかありません。 インスタンス辞書内で属性値が再定義されても、データデスクリプタは常に この値をオーバライドします。対照的に、非データデスクリプタの 場合には、属性値はインスタンス側でオーバライドされます。

(staticmethod() や classmethod() を含む) Python メソッドは、非データデスクリプタとして実装されています。その結果、 インスタンスではメソッドを再定義したりオーバライドできます。 このことにより、個々のインスタンスが同じクラスの他のインスタンスと 互いに異なる動作を獲得することができます。

property() 関数はデータデスクリプタとして実装されています。 従って、インスタンスはあるプロパティの動作をオーバライドすることが できません。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3.3.2.2 デスクリプタ (descriptor) の実装 Up: 3.3.2 属性値アクセスをカスタマイズする Next: 3.3.2.4 __slots__


3.3.2.2 デスクリプタ (descriptor) の実装

以下のメソッドは、デスクリプタメソッドを持っているクラス (いわゆる デスクリプタ (descriptor) クラス) のインスタンスが 別の新たな形式のクラス、いわゆる オーナ (owner) クラスの クラス辞書に存在する場合にのみ適用されます。 以下の例での ``属性'' とは、属性の名前が オーナクラスの __dict__ に入っているプロパティ (porperty) を検索するためのキーになっているような属性を指します。

__get__( self, instance, owner)
オーナクラスやの属性を取得する (クラス属性へのアクセス) 際や、 オーナクラスのインスタンスの属性を取得する (インスタンス属性への アクセス) 場合に呼び出されます。owner は常にオーナクラスです。 一方、instance は属性へのアクセスを仲介するインスタンスか 属性が owner を介してアクセスされる場合は None に なります。このメソッドは (計算された) 属性値を返すか、 AttributeError 例外を送出しなければなりません。

__set__( self, instance, value)
オーナクラスのインスタンス instance 上の属性を新たな値 value に設定する際に呼び出されます。

__delete__( self, instance)
オーナクラスのインスタンス instance 上の属性を削除する際に 呼び出されます。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3.3.2.1 新しい形式のクラスのための別の属性アクセス Up: 3.3.2 属性値アクセスをカスタマイズする Next: 3.3.2.3 デスクリプタを呼び出す


序

Copyright © 2001, 2002, 2003 Python Software Foundation. All rights reserved.

Copyright © 2000 BeOpen.com. All rights reserved.

Copyright © 1995-2000 Corporation for National Research Initiatives. All rights reserved.

Copyright © 1991-1995 Stichting Mathematisch Centrum. All rights reserved.

Translation Copyright © 2003 Python Document Japanese Translation Project. All rights reserved.

ライセンスおよび許諾に関する完全な情報は、このドキュメントの末尾を 参照してください。

概要:

Python はインタプリタ形式の、オブジェクト指向な高レベルプログラミング 言語で、動的なセマンティクスを持っています。Python の高レベルな組み込み データ構造は、動的な型付け機能や動的な結合機能と組み合わせることで、 迅速なアプリケーション開発や既存のソフトウェアコンポーネント間をつなぐ スクリプト言語、または糊 (glue) 言語として Python を魅力的な存在に しています。Python は単純で学びやすい文法なので、可読性が高まり、 プログラムのメンテナンスにかかるコストを低減します。 Python は、プログラムのモジュール化や再利用を助けるモジュールとパッケージ をサポートします。Python インタプリタと多数の標準ライブラリは、 ほとんどのプラットフォームでソースコード形式でもバイナリ形式でも無料で 入手することができ、無料で配布することができます。

このリファレンスマニュアルでは、Python 言語の文法と、``コアとなる セマンティクス'' について記述します。このマニュアルはそっけない書き方 かもしれませんが、的確かつ完璧な記述を目指しています。 必須でない組み込みオブジェクト型や組み込み関数、組み込みモジュール に関するセマンティクスは、 Python ライブラリリファレンス で述べられています。 形式ばらない Python 言語入門には、 Python チュートリアル を参照してください。 C 言語あるいは C++ プログラマ向けには、このマニュアルとは別に二つの マニュアルがあります: Python インタプリタの拡張と埋め込み では、Python 拡張モジュールを書くための高レベルな様式について述べています。 また、Python/C API リファレンスマニュアル では、C/C++ プログラマが利用できるインタフェースについて詳細に 記述しています。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: Python リファレンスマニュアル Up: Python リファレンスマニュアル Next: 目次


identifier ::=
             (letter|"_") (letter | digit | "_")*

letter ::=
             lowercase | uppercase

lowercase ::=
             "a"..."z"

uppercase ::=
             "A"..."Z"

digit ::=
             "0"..."9"

stringliteral ::=
             [stringprefix](shortstring | longstring)

stringprefix ::=
             "r" | "u" | "ur" | "R" | "U" | "UR" | "Ur" | "uR"

shortstring ::=
             "'" shortstringitem* "'"
              | '"' shortstringitem* '"'

longstring ::=
             "'''" longstringitem* "'''"
                | '"""' longstringitem* '"""'

shortstringitem ::=
             shortstringchar | escapeseq

longstringitem ::=
             longstringchar | escapeseq

shortstringchar ::=
             <any ASCII character except "\" or newline or the quote>

longstringchar ::=
             <any ASCII character except "\">

escapeseq ::=
             "\" <any ASCII character>

longinteger ::=
             integer ("l" | "L")

integer ::=
             decimalinteger | octinteger | hexinteger

decimalinteger ::=
             nonzerodigit digit* | "0"

octinteger ::=
             "0" octdigit+

hexinteger ::=
             "0" ("x" | "X") hexdigit+

nonzerodigit ::=
             "1"..."9"

octdigit ::=
             "0"..."7"

hexdigit ::=
             digit | "a"..."f" | "A"..."F"

floatnumber ::=
             pointfloat | exponentfloat

pointfloat ::=
             [intpart] fraction | intpart "."

exponentfloat ::=
             (intpart | pointfloat)
              exponent

intpart ::=
             digit+

fraction ::=
             "." digit+

exponent ::=
             ("e" | "E") ["+" | "-"] digit+

imagnumber ::= (floatnumber | intpart) ("j" | "J")

atom ::=
             identifier | literal | enclosure

enclosure ::=
             parenth_form | list_display
                | dict_display | string_conversion

literal ::=
             stringliteral | integer | longinteger
                | floatnumber | imagnumber

parenth_form ::=
             "(" [expression_list] ")"

test ::=
             and_test ( "or" and_test )*
              | lambda_form

testlist ::=
             test ( "," test )* [ "," ]

list_display ::=
             "[" [listmaker] "]"

listmaker ::=
             expression ( list_for
              | ( "," expression )* [","] )

list_iter ::=
             list_for | list_if

list_for ::=
             "for" expression_list "in" testlist
              [list_iter]

list_if ::=
             "if" test [list_iter]

dict_display ::=
             "\{" [key_datum_list] "\}"

key_datum_list ::=
             key_datum ("," key_datum)* [","]

key_datum ::=
             expression ":" expression

string_conversion ::=
             "`" expression_list "`"

primary ::=
             atom | attributeref
              | subscription | slicing | call

attributeref ::=
             primary "." identifier

subscription ::=
             primary "[" expression_list "]"

slicing ::=
             simple_slicing | extended_slicing

simple_slicing ::=
             primary "[" short_slice "]"

extended_slicing ::=
             primary "[" slice_list "]"

slice_list ::=
             slice_item ("," slice_item)* [","]

slice_item ::=
             expression | proper_slice | ellipsis

proper_slice ::=
             short_slice | long_slice

short_slice ::=
             [lower_bound] ":" [upper_bound]

long_slice ::=
             short_slice ":" [stride]

lower_bound ::=
             expression

upper_bound ::=
             expression

stride ::=
             expression

ellipsis ::=
             "..."

call ::=
             primary "(" [argument_list [","]] ")"

argument_list ::=
             positional_arguments ["," keyword_arguments]
                                     ["," "*" expression]
                                     ["," "**" expression]
                | keyword_arguments ["," "*" expression]
                                    ["," "**" expression]
                | "*" expression ["," "**" expression]
                | "**" expression

positional_arguments ::=
             expression ("," expression)*

keyword_arguments ::=
             keyword_item ("," keyword_item)*

keyword_item ::=
             identifier "=" expression

power ::=
             primary ["**" u_expr]

u_expr ::=
             power | "-" u_expr
              | "+" u_expr | "\~" u_expr

m_expr ::=
             u_expr | m_expr "*" u_expr
              | m_expr "//" u_expr
              | m_expr "/" u_expr
                | m_expr "\%" u_expr

a_expr ::=
             m_expr | a_expr "+" m_expr
              | a_expr "-" m_expr

shift_expr ::=
             a_expr
              | shift_expr ( "<<" | ">>" ) a_expr

and_expr ::=
             shift_expr | and_expr "\;SPMamp;" shift_expr

xor_expr ::=
             and_expr | xor_expr "\textasciicircum" and_expr

or_expr ::=
             xor_expr | or_expr "|" xor_expr

comparison ::=
             or_expr ( comp_operator or_expr )*

comp_operator ::=
             "<" | ">" | "==" | ">=" | "<=" | "<>" | "!="
                | "is" ["not"] | ["not"] "in"

expression ::=
             or_test | lambda_form

or_test ::=
             and_test | or_test "or" and_test

and_test ::=
             not_test | and_test "and" not_test

not_test ::=
             comparison | "not" not_test

lambda_form ::=
             "lambda" [parameter_list]: expression

expression_list ::=
             expression ( "," expression )* [","]

simple_stmt ::= expression_stmt
                | assert_stmt
                | assignment_stmt
                | augmented_assignment_stmt
                | pass_stmt
                | del_stmt
                | print_stmt
                | return_stmt
                | yield_stmt
                | raise_stmt
                | break_stmt
                | continue_stmt
                | import_stmt
                | global_stmt
                | exec_stmt

expression_stmt ::=
             expression_list

assert_stmt ::=
             "assert" expression ["," expression]

assignment_stmt ::=
             (target_list "=")+ expression_list

target_list ::=
             target ("," target)* [","]

target ::=
             identifier
                | "(" target_list ")"
                | "[" target_list "]"
                | attributeref
                | subscription
                | slicing

augmented_assignment_stmt ::=
             target augop expression_list

augop ::=
             "+=" | "-=" | "*=" | "/=" | "\%=" | "**="
                | ">>=" | "<<=" | "\&=" | "\textasciicircum=" | "|="

pass_stmt ::=
             "pass"

del_stmt ::=
             "del" target_list

print_stmt ::=
             "print" ( \optionalexpression ("," expression)* \optional","
                | ">\code>" expression
                  \optional("," expression)+ \optional"," )

return_stmt ::=
             "return" [expression_list]

yield_stmt ::=
             "yield" expression_list

raise_stmt ::=
             "raise" [expression ["," expression
              ["," expression]]]

break_stmt ::=
             "break"

continue_stmt ::=
             "continue"

import_stmt ::=
             "import" module ["as" name]
                ( "," module ["as" name] )*
                | "from" module "import" identifier
                    ["as" name]
                  ( "," identifier ["as" name] )*
                | "from" module "import" "*"

module ::=
             (identifier ".")* identifier

global_stmt ::=
             "global" identifier ("," identifier)*

exec_stmt ::=
             "exec" expression
              ["in" expression ["," expression]]

compound_stmt ::=
             if_stmt
                | while_stmt
                | for_stmt
                | try_stmt
                | funcdef
                | classdef

suite ::=
             stmt_list NEWLINE
              | NEWLINE INDENT statement+ DEDENT

statement ::=
             stmt_list NEWLINE | compound_stmt

stmt_list ::=
             simple_stmt (";" simple_stmt)* [";"]

if_stmt ::=
             "if" expression ":" suite
                ( "elif" expression ":" suite )*
                ["else" ":" suite]

while_stmt ::=
             "while" expression ":" suite
                ["else" ":" suite]

for_stmt ::=
             "for" target_list "in" expression_list
              ":" suite
                ["else" ":" suite]

try_stmt ::=
             try_exc_stmt | try_fin_stmt

try_exc_stmt ::=
             "try" ":" suite
                ("except" [expression
                             ["," target]] ":" suite)+
                ["else" ":" suite]

try_fin_stmt ::=
             "try" ":" suite
              "finally" ":" suite

funcdef ::=
             "def" funcname "(" [parameter_list] ")"
              ":" suite

parameter_list ::=
             (defparameter ",")*
                ("*" identifier [, "**" identifier]
                | "**" identifier
                  | defparameter [","])

defparameter ::=
             parameter ["=" expression]

sublist ::=
             parameter ("," parameter)* [","]

parameter ::=
             identifier | "(" sublist ")"

funcname ::=
             identifier

classdef ::=
             "class" classname [inheritance] ":"
              suite

inheritance ::=
             "(" [expression_list] ")"

classname ::=
             identifier

file_input ::=
             (NEWLINE | statement)*

interactive_input ::=
             [stmt_list] NEWLINE | compound_stmt NEWLINE

eval_input ::=
             expression_list NEWLINE*

input_input ::=
             expression_list NEWLINE


3.3.2.1 新しい形式のクラスのための別の属性アクセス

以下のメソッドは新しい形式のクラス (new-style class) のみに 適用されます。

__getattribute__( self, name)
クラスのインスタンスに対する属性アクセスを実装するために、無条件に 呼び出されます。クラスが __getattr__() も定義している 場合、__getattr__() は (明示的に呼び出さない限り) 呼び出されることはありません。このメソッドは (計算された) 属性値を 返すか、AttributeError 例外を送出します。 このメソッドが再帰的に際限なく呼び出されてしまうのを防ぐため、 実装の際には常に、例えば "object.__getattribute__(self, name)" のように基底クラスのメソッドを同じ属性名を使って呼び出し、 必要な属性値全てにアクセスしなければなりません。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3.3.2 属性値アクセスをカスタマイズする Up: 3.3.2 属性値アクセスをカスタマイズする Next: 3.3.2.2 デスクリプタ (descriptor) の実装


3.3.2.4 __slots__

デフォルトでは、新旧どちらのクラスも、属性の記憶領域として使うための 辞書を持っています。この仕様は、ほとんどインスタンス変数を持たない ようなオブジェクトの場合には記憶領域の無駄遣いになります。 記憶領域の消費量は、大量のインスタンスを生成する際には深刻です。

このデフォルトの設定は、新たな形式のクラス定義において __slots__ を 定義することでオーバライドできます。__slots_ 宣言はインスタンス 変数の配列を受け取ります。各々のインスタンス上には、各変数の値を 記憶するのにちょうど必要な量だけの記憶領域を確保します。 各々のインスタンスに対して __dict__ が生成されることがないので、 記憶領域が節約されます。

__slots__
このクラス変数には、文字列、反復可能オブジェクト、あるいはインスタンスが 用いる変数名を表す文字列からなる配列を代入することができます。 この変数が新しい形式のクラスで定義されている場合、__slots__ は、各インスタンスに対して宣言された変数に必要な記憶領域を確保し、 __dict__ と__weakref__ が自動的に生成されないようにします。 バージョン2.2 以降で新規追加された 仕様です。

__slots__ を利用する際の注意

  • __dict__ 変数がない場合、__slots__ に列挙されていない 新たな変数をインスタンスに代入することはできません。 列挙されていない変数名を使って代入しようとした場合、 AttributeError が送出されます。 新たな変数を動的に代入したいのなら、__slots__ を宣言する際に '__dict__' を変数名の配列に追加してください。

    バージョン2.3 以降で変更された 仕様: これまでは、'__dict__' を __slots__ 宣言に追加しても、インスタンス変数名として他にリストされていない 新たな属性の代入はできませんでした。

  • __slots__ を定義しているクラスの各インスタンスに __weakref__ 変数がない場合、インスタンスに対する弱参照 (weak reference) はサポートされません。 弱参照のサポートが必要なら、 __slots__ を宣言する際に '__weakref__' を変数名の配列に追加してください。 バージョン2.3 以降で変更された 仕様: これまでは、'__weakref__' を __slots__ 宣言に追加しても、弱参照のサポートを有効にできませんでした。
  • __slots__ は、クラスのレベルで各変数に対するデスクリプタ (3.3.2 を参照) を使って実装されます。その結果、 __slots__ に定義されているインスタンス変数のデフォルト値は クラス属性を使って設定できなくなっています; そうしないと、 デスクリプタによる代入をクラス属性が上書きしてしまうからです。

  • あるクラスで、基底クラスですでに定義されているスロットを 定義した場合、基底クラスのスロットで定義されているインスタンス変数は (デスクリプタを基底クラスから直接取得しない限り) アクセスできなく なります。これにより、プログラムの趣意が不定になってしまいます。 将来は、この問題を避けるために何らかのチェックが追加されるかもしれません。

  • __slots__ 宣言が動作するのは、定義が行われたクラスだけに 限られています。その結果、サブクラスでは、__slots__ を定義 しない限り __dict__ を持つことになります。

  • __slots__ は、long、 str、および tuple といった、``可変長 (variable-length)'' の組み込み型 から導出されたクラスでは動作しません。

  • __slots__ には、文字列でない反復可能オブジェクトを 代入することができます。辞書型も使うことができます; しかし将来、 辞書の各キーに相当する値に何らかの特殊な意味が割り当てられる かもしれません。

Previous Page Up One Level Next Page Python リファレンスマニュアル Contents Index
Previous: 3.3.2.3 デスクリプタを呼び出す Up: 3.3.2 属性値アクセスをカスタマイズする Next: 3.3.3 クラス生成をカスタマイズする


この文書について...

Python チュートリアル, 平成16年6月28日, Release 2.3.3

このドキュメントは、 LaTeX2HTML 変換ツールを 使って生成されています。

LaTeX2HTML の著作権は、 Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds, and Copyright © 1997, 1998, Ross Moore, Mathematics Department, Macquarie University, Sydney.
となっています。

Python ドキュメントの LaTeX2HTML への対応は、 Fred L. Drake, Jr. の多大な努力で実現しました。 オリジナルのナビゲーションアイコンは、 Christopher Petrilli によるものです。

Comments and Questions

General comments and questions regarding this document should be sent by email to docs@python.org. If you find specific errors in this document, either in the content or the presentation, please report the bug at the Python Bug Tracker at SourceForge.

Questions regarding how to use the information in this document should be sent to the Python news group, comp.lang.python, or the Python mailing list (which is gated to the newsgroup and carries the same content).

For any of these channels, please be sure not to send HTML email. Thanks.

和訳に関するコメントや質問について

本和訳プロジェクトは、少なくとも 2004 年 4 月の時点では、 Python 本体の開発プロジェクトや Python 国際化 SIG による 取り組みの一部では ありません 。 和訳の内容、和訳プロジェクトに関するご意見やご質問は、 これらのプロジェクトあてにお送りにならないようお願いします。

和訳ドキュメントに関する誤りのご指摘やご質問、コメントは、 SourceForge.jp の Python ドキュメント和訳プロジェクト バグトラッカ から お送りください。

Python でのプログラミングに関する疑問など、このドキュメントに 書かれている情報の使い方についての質問は、 日本 Python ユーザ会メーリングリスト で行うとよいでしょう。

Previous Page Up One Level Python チュートリアル Contents Index
Previous: 索引 Up: Python チュートリアル


Python チュートリアル

Guido van Rossum

PythonLabs
Email: docs@python.org

Fred L. Drake, Jr., editor

リリース 2.3.3
平成16年6月28日

日本語訳: Python ドキュメント翻訳プロジェクト

  • 序
  • 目次
  • 1. Python への意欲を高める
    • 1.1 ここからどこへ
  • 2. Python インタプリタを使う
    • 2.1 インタプリタを起動する
      • 2.1.1 引数の受け渡し
      • 2.1.2 対話モード
    • 2.2 インタプリタとその環境
      • 2.2.1 エラー処理
      • 2.2.2 実行可能な Python スクリプト
      • 2.2.3 ソースコードの文字コード方式 (encoding)
      • 2.2.4 対話モード用の起動時実行ファイル
  • 3. 形式ばらない Python の紹介
    • 3.1 Python を電卓として使う
      • 3.1.1 数
      • 3.1.2 文字列
      • 3.1.3 Unicode 文字列
      • 3.1.4 リスト
    • 3.2 プログラミングへの第一歩
  • 4. その他の制御フローツール
    • 4.1 if 文
    • 4.2 for 文
    • 4.3 range() 関数
    • 4.4 break 文と continue 文と ループの else 節
    • 4.5 pass 文
    • 4.6 関数を定義する
    • 4.7 関数定義についてもう少し
      • 4.7.1 デフォルトの引数値
      • 4.7.2 キーワード引数
      • 4.7.3 任意引数リスト
      • 4.7.4 引数リストのアンパック
      • 4.7.5 ラムダ形式
      • 4.7.6 ドキュメンテーション文字列
  • 5. データ構造
    • 5.1 リスト型についてもう少し
      • 5.1.1 リストをスタックとして使う
      • 5.1.2 リストをキューとして使う
      • 5.1.3 実用的なプログラミングツール
      • 5.1.4 リストの内包表記
    • 5.2 del 文
    • 5.3 タプルと配列
    • 5.4 辞書
    • 5.5 ループのテクニック
    • 5.6 条件についてもう少し
    • 5.7 配列とその他の型の比較
  • 6. モジュール
    • 6.1 モジュールについてもうすこし
      • 6.1.1 モジュール検索パス
      • 6.1.2 ``コンパイル'' された Python ファイル
    • 6.2 標準モジュール
    • 6.3 dir() 関数
    • 6.4 パッケージ
      • 6.4.1 パッケージから * を import する
      • 6.4.2 パッケージ内での参照
      • 6.4.3 複数ディレクトリ中のパッケージ
  • 7. 入力と出力
    • 7.1 ファンシーな出力の書式化
    • 7.2 ファイルを読み書きする
      • 7.2.1 ファイルオブジェクトのメソッド
      • 7.2.2 pickle モジュール
  • 8. エラーと例外
    • 8.1 構文エラー
    • 8.2 例外
    • 8.3 例外を処理する
    • 8.4 例外を送出する
    • 8.5 ユーザ定義の例外
    • 8.6 後片付け動作を定義する
  • 9. クラス
    • 9.1 用語について一言
    • 9.2 Python のスコープと名前空間
    • 9.3 クラス初見
      • 9.3.1 クラス定義の構文
      • 9.3.2 クラスオブジェクト
      • 9.3.3 インスタンスオブジェクト
      • 9.3.4 メソッドオブジェクト
    • 9.4 いろいろな注意点
    • 9.5 継承
      • 9.5.1 多重継承
    • 9.6 プライベート変数
    • 9.7 残りのはしばし
      • 9.7.1 例外はクラスであってもよい
    • 9.8 イテレータ (iterator)
    • 9.9 ジェネレータ (generator)
  • 10. 標準ライブラリの簡単なツアー
    • 10.1 オペレーティングシステムへのインタフェース
    • 10.2 ファイルのワイルドカード表記
    • 10.3 コマンドライン引数
    • 10.4 エラー出力のリダイレクトとプログラムの終了
    • 10.5 文字列のパターンマッチング
    • 10.6 数学
    • 10.7 インターネットへのアクセス
    • 10.8 日付と時刻
    • 10.9 データ圧縮
    • 10.10 パフォーマンスの計測
    • 10.11 品質管理
    • 10.12 一揃いあつらえ済み
  • 11. さあ何を？
  • A. 対話入力編集とヒストリ置換
    • A.1 行編集
    • A.2 ヒストリ置換
    • A.3 キー割り当て
    • A.4 解説
  • B. 浮動小数点演算、その問題と制限
    • B.1 表現エラー
  • C. 歴史とライセンス
    • C.1 History of the software
    • C.2 Terms and conditions for accessing or otherwise using Python
  • D. 日本語訳について
    • D.1 このドキュメントについて
    • D.2 翻訳者一覧 (敬称略)
  • E. 用語集
  • 索引
  • この文書について...
Up One Level Next Page Python チュートリアル Contents Index
Up: Python ドキュメントインデクス Next: 序


序

Copyright © 2001, 2002, 2003 Python Software Foundation. All rights reserved.

Copyright © 2000 BeOpen.com. All rights reserved.

Copyright © 1995-2000 Corporation for National Research Initiatives. All rights reserved.

Copyright © 1991-1995 Stichting Mathematisch Centrum. All rights reserved.

Translation Copyright © 2003 Python Document Japanese Translation Project. All rights reserved.

ライセンスおよび許諾に関する完全な情報は、このドキュメントの末尾を 参照してください。

概要:

Python は簡単に学ぶことができ、それでいて強力な言語の一つです。 Python には高レベルなデータ構造が効率的に実装されており、 オブジェクト指向プログラミングに対しても、単純でありがながら 効果的なアプローチをしています。洗練された文法とデータ型を動的に 決定する機能は、そのインタプリタの特性とあいまって Python を 理想的なスクリプトプログラミング言語にするとともに、多くの プラットフォームにおける幅広い対象領域において迅速にアプリケーションを 開発できるようにしています。

Python インタプリタ自体と拡張可能な標準ライブラリは、 ソースコード、または多くの主要な計算機環境向けのバイナリ形式として、 いずれも Python Web サイト http://www.python.org/ から無料で 入手でき、かつ無料で配布することができます。 このサイトではまた、無料で手に入るたくさんのサードパーティ製 Python モジュール、プログラム、ツール類、追加のドキュメントに ついて、その配布物やポインタが置かれています。

Python インタプリタは C 言語や C++ 言語 (あるいは C 言語から 呼び出すことができるその他の言語) で実装された新たな関数やデータ 構造を組み込んで拡張することが簡単にできます。Python はまた、 カスタマイズ可能なアプリケーションを作るための拡張機能記述言語 としてぴったりです。

このチュートリアルでは、Python の言語仕様と仕組みについて、その 基本的な概念と機能をざっと紹介します。例として挙げた題について 自分の手で体験するには手元に Python インタプリタがあると便利ですが、 どの題もそれ自体で完結した話になっているので、このチュートリアルを オフラインで読むことも可能です。

標準のオブジェクトやモジュールの記述については、ドキュメント 「Python ライブラリリファレンス (Python Library Reference)」 を 参照してください。C 言語や C++ 言語で拡張モジュールを書くなら、 「Python インタプリタの拡張と埋め込み (Extending and Embedding the Python Interpreter)」、および 「Python/C API リファレンス (Python/C API Reference)」を参照してください。Python について広く深くカバーしている 書籍もいくつかあります。

このチュートリアルは網羅的な内容ではありません。また、個別の機能 について全てをカバーしているわけでもありません。通常使われている 機能すら全てカバーされていません。その代わり、このチュートリアルでは Python の特筆すべき機能をたくさん紹介して、この言語の持ち味やスタイル について好印象を持ってもらうつもりです。このチュートリアルを読んだ 後には、読者のみなさんは Python のモジュールやプログラムを読み書き できるようになり、 「Python ライブラリリファレンス (Python Library Reference)」 に記述されているさまざまな Python ライブラリモジュールについて学ぶ 準備ができていることでしょう。

Previous Page Up One Level Next Page Python チュートリアル Contents Index
Previous: Python チュートリアル Up: Python チュートリアル Next: 目次


目次

  • 1. Python への意欲を高める
    • 1.1 ここからどこへ
  • 2. Python インタプリタを使う
    • 2.1 インタプリタを起動する
      • 2.1.1 引数の受け渡し
      • 2.1.2 対話モード
    • 2.2 インタプリタとその環境
      • 2.2.1 エラー処理
      • 2.2.2 実行可能な Python スクリプト
      • 2.2.3 ソースコードの文字コード方式 (encoding)
      • 2.2.4 対話モード用の起動時実行ファイル
  • 3. 形式ばらない Python の紹介
    • 3.1 Python を電卓として使う
      • 3.1.1 数
      • 3.1.2 文字列
      • 3.1.3 Unicode 文字列
      • 3.1.4 リスト
    • 3.2 プログラミングへの第一歩
  • 4. その他の制御フローツール
    • 4.1 if 文
    • 4.2 for 文
    • 4.3 range() 関数
    • 4.4 break 文と continue 文と ループの else 節
    • 4.5 pass 文
    • 4.6 関数を定義する
    • 4.7 関数定義についてもう少し
      • 4.7.1 デフォルトの引数値
      • 4.7.2 キーワード引数
      • 4.7.3 任意引数リスト
      • 4.7.4 引数リストのアンパック
      • 4.7.5 ラムダ形式
      • 4.7.6 ドキュメンテーション文字列
  • 5. データ構造
    • 5.1 リスト型についてもう少し
      • 5.1.1 リストをスタックとして使う
      • 5.1.2 リストをキューとして使う
      • 5.1.3 実用的なプログラミングツール
      • 5.1.4 リストの内包表記
    • 5.2 del 文
    • 5.3 タプルと配列
    • 5.4 辞書
    • 5.5 ループのテクニック
    • 5.6 条件についてもう少し
    • 5.7 配列とその他の型の比較
  • 6. モジュール
    • 6.1 モジュールについてもうすこし
      • 6.1.1 モジュール検索パス
      • 6.1.2 ``コンパイル'' された Python ファイル
    • 6.2 標準モジュール
    • 6.3 dir() 関数
    • 6.4 パッケージ
      • 6.4.1 パッケージから * を import する
      • 6.4.2 パッケージ内での参照
      • 6.4.3 複数ディレクトリ中のパッケージ
  • 7. 入力と出力
    • 7.1 ファンシーな出力の書式化
    • 7.2 ファイルを読み書きする
      • 7.2.1 ファイルオブジェクトのメソッド
      • 7.2.2 pickle モジュール
  • 8. エラーと例外
    • 8.1 構文エラー
    • 8.2 例外
    • 8.3 例外を処理する
    • 8.4 例外を送出する
    • 8.5 ユーザ定義の例外
    • 8.6 後片付け動作を定義する
  • 9. クラス
    • 9.1 用語について一言
    • 9.2 Python のスコープと名前空間
    • 9.3 クラス初見
      • 9.3.1 クラス定義の構文
      • 9.3.2 クラスオブジェクト
      • 9.3.3 インスタンスオブジェクト
      • 9.3.4 メソッドオブジェクト
    • 9.4 いろいろな注意点
    • 9.5 継承
      • 9.5.1 多重継承
    • 9.6 プライベート変数
    • 9.7 残りのはしばし
      • 9.7.1 例外はクラスであってもよい
    • 9.8 イテレータ (iterator)
    • 9.9 ジェネレータ (generator)
  • 10. 標準ライブラリの簡単なツアー
    • 10.1 オペレーティングシステムへのインタフェース
    • 10.2 ファイルのワイルドカード表記
    • 10.3 コマンドライン引数
    • 10.4 エラー出力のリダイレクトとプログラムの終了
    • 10.5 文字列のパターンマッチング
    • 10.6 数学
    • 10.7 インターネットへのアクセス
    • 10.8 日付と時刻
    • 10.9 データ圧縮
    • 10.10 パフォーマンスの計測
    • 10.11 品質管理
    • 10.12 一揃いあつらえ済み
  • 11. さあ何を？
  • A. 対話入力編集とヒストリ置換
    • A.1 行編集
    • A.2 ヒストリ置換
    • A.3 キー割り当て
    • A.4 解説
  • B. 浮動小数点演算、その問題と制限
    • B.1 表現エラー
  • C. 歴史とライセンス
    • C.1 History of the software
    • C.2 Terms and conditions for accessing or otherwise using Python
  • D. 日本語訳について
    • D.1 このドキュメントについて
    • D.2 翻訳者一覧 (敬称略)
  • E. 用語集
  • 索引

Previous Page Up One Level Next Page Python チュートリアル Index
Previous: 序 Up: Python チュートリアル Next: 1. Python への意欲を高める


この文書について...

What's New in Python 2.3

このドキュメントは、 LaTeX2HTML 変換ツールを 使って生成されています。

LaTeX2HTML の著作権は、 Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds, and Copyright © 1997, 1998, Ross Moore, Mathematics Department, Macquarie University, Sydney.
となっています。

Python ドキュメントの LaTeX2HTML への対応は、 Fred L. Drake, Jr. の多大な努力で実現しました。 オリジナルのナビゲーションアイコンは、 Christopher Petrilli によるものです。

Comments and Questions

General comments and questions regarding this document should be sent by email to docs@python.org. If you find specific errors in this document, either in the content or the presentation, please report the bug at the Python Bug Tracker at SourceForge.

Questions regarding how to use the information in this document should be sent to the Python news group, comp.lang.python, or the Python mailing list (which is gated to the newsgroup and carries the same content).

For any of these channels, please be sure not to send HTML email. Thanks.

和訳に関するコメントや質問について

本和訳プロジェクトは、少なくとも 2004 年 4 月の時点では、 Python 本体の開発プロジェクトや Python 国際化 SIG による 取り組みの一部では ありません 。 和訳の内容、和訳プロジェクトに関するご意見やご質問は、 これらのプロジェクトあてにお送りにならないようお願いします。

和訳ドキュメントに関する誤りのご指摘やご質問、コメントは、 SourceForge.jp の Python ドキュメント和訳プロジェクト バグトラッカ から お送りください。

Python でのプログラミングに関する疑問など、このドキュメントに 書かれている情報の使い方についての質問は、 日本 Python ユーザ会メーリングリスト で行うとよいでしょう。

Previous Page Up One Level What's New in Python 2.3 Contents
Previous: 22 Acknowledgements Up: What's New in Python
Release 1.00.


目次

  • 1 PEP 218: A Standard Set Datatype
  • 2 PEP 255: Simple Generators
  • 3 PEP 263: Source Code Encodings
  • 4 PEP 273: Importing Modules from Zip Archives
  • 5 PEP 277: Unicode file name support for Windows NT
  • 6 PEP 278: Universal Newline Support
  • 7 PEP 279: enumerate()
  • 8 PEP 282: The logging Package
  • 9 PEP 285: A Boolean Type
  • 10 PEP 293: Codec Error Handling Callbacks
  • 11 PEP 301: Package Index and Metadata for Distutils
  • 12 PEP 302: New Import Hooks
  • 13 PEP 305: Comma-separated Files
  • 14 PEP 307: Pickle Enhancements
  • 15 Extended Slices
  • 16 Other Language Changes
    • 16.1 String Changes
    • 16.2 Optimizations
  • 17 New, Improved, and Deprecated Modules
    • 17.1 Date/Time Type
    • 17.2 The optparse Module
  • 18 Pymalloc: A Specialized Object Allocator
  • 19 Build and C API Changes
    • 19.1 Port-Specific Changes
  • 20 Other Changes and Fixes
  • 21 Porting to Python 2.3
  • 22 Acknowledgements

This article explains the new features in Python 2.3. Python 2.3 was released on July 29, 2003.

The main themes for Python 2.3 are polishing some of the features added in 2.2, adding various small but useful enhancements to the core language, and expanding the standard library. The new object model introduced in the previous version has benefited from 18 months of bugfixes and from optimization efforts that have improved the performance of new-style classes. A few new built-in functions have been added such as sum() and enumerate(). The in operator can now be used for substring searches (e.g. "ab" in "abc" returns True).

Some of the many new library features include Boolean, set, heap, and date/time data types, the ability to import modules from ZIP-format archives, metadata support for the long-awaited Python catalog, an updated version of IDLE, and modules for logging messages, wrapping text, parsing CSV files, processing command-line options, using BerkeleyDB databases... the list of new and enhanced modules is lengthy.

This article doesn't attempt to provide a complete specification of the new features, but instead provides a convenient overview. For full details, you should refer to the documentation for Python 2.3, such as the Python Library Reference and the Python Reference Manual. If you want to understand the complete implementation and design rationale, refer to the PEP for a particular new feature.

Previous Page Up One Level Next Page What's New in Python 2.3
Previous: What's New in Python Up: What's New in Python Next: 1 PEP 218: A
Release 1.00.