pytho****@googl*****
pytho****@googl*****
2011年 11月 6日 (日) 03:22:18 JST
Revision: c65372e60e15 Author: Naoki INADA <inada****@klab*****> Date: Sat Nov 5 11:21:33 2011 Log: Update 2.7.2: getopt, imaplib, math, syslog, wave http://code.google.com/p/python-doc-ja/source/detail?r=c65372e60e15 Modified: /library/getopt.rst /library/imaplib.rst /library/math.rst /library/syslog.rst /library/wave.rst ======================================= --- /library/getopt.rst Wed Mar 9 07:12:07 2011 +++ /library/getopt.rst Sat Nov 5 11:21:33 2011 @@ -1,10 +1,17 @@ - -:mod:`getopt` --- コマンドラインオプションのパーザ -================================================== + +:mod:`getopt` --- C言語スタイルのコマンドラインオプションパーサ +=============================================================== .. module:: getopt - :synopsis: ポータブルなコマンドラインオプションのパーザ。長短の両方の形 式をサポートします。 - + :synopsis: ポータブルなコマンドラインオプションのパーサ。 + 長短の両方の形式をサポートします。 + +.. note:: + :mod:`getopt` モジュールは、 C言語の :cfunc:`getopt` 関数に慣れ親しんだ 人の + ためにデザインされたAPIを持つコマンドラインパーサです。 + C言語の :cfunc:`getopt` に慣れ親しんでいない人や、コードを少なくしたい場 合、 + より良いヘルプメッセージとエラーメッセージが欲しい場合は、代わり に :mod:`argparse` + モジュールの利用を検討してください。 このモジュールは ``sys.argv`` に入っているコマンドラインオプションの構文解 析を支援します。 '``-``' や '``--``' の特別扱いも含めて、 Unixの :cfunc:`getopt` と同じ記法をサポートしていま す。 3番目の引数(省略可能)を設定することで、 @@ -32,32 +39,23 @@ 近いものです。 *long_options* は長形式のオプションの名前を示す文字列のリストです。 - 名前には、先頭の ``'-``\ ``-'`` は含めません。引数が必要な場合には名前の + 名前には、先頭の ``'--'`` は含めません。引数が必要な場合には名前の 最後に等号(``'='``)を入れます。オプション引数はサポートしていません。 長形式のオプションだけを受けつけるためには、 *options* は空文字列である 必要があります。 長形式のオプションは、該当するオプションを一意に決定できる長さまで入力さ れて いれば認識されます。たとえば、 *long_options* が ``['foo', 'frob']`` の 場合、 - :option:`--fo` は :option:`--foo` に該当しますが、 :option:`--f` では一 意に + ``--fo`` は ``--foo`` にマッチしますが、 ``--f`` では一意に 決定できないので、 :exc:`GetoptError` が発生します。 - 返り値は2つの要素から成っています: 最初は ``(option, value)`` のタプルの リスト、2つ目はオプションリス - トを取り除いたあとに残ったプログラムの引数リストです(*args* の末尾部分の スライスになります)。 - それぞれの引数と値のタプルの最初の要素は、短形式の時はハイフン 1つで始ま る文字列(例: ``'-x'``)、長形式の時はハイフン2つで始まる文字列(例: - ``'-`` \ ``-long-option'``)となり、引数が2番目の要素になります。引数をと らない場合には空文字列が入ります。オプションは見つかった順 - に並んでいて、複数回同じオプションを指定することができます。長形式と短形 式のオプションは混在させることができます。 - - .. % The return value consists of two elements: the first is a list of - .. % \code{(\var{option}, \var{value})} pairs; the second is the list of - .. % program arguments left after the option list was stripped (this is a - .. % trailing slice of \var{args}). Each option-and-value pair returned - .. % has the option as its first element, prefixed with a hyphen for short - .. % options (e.g., \code{'-x'}) or two hyphens for long options (e.g., - .. % \code{'-}\code{-long-option'}), and the option argument as its second - .. % element, or an empty string if the option has no argument. The - .. % options occur in the list in the same order in which they were found, - .. % thus allowing multiple occurrences. Long and short options may be - .. % mixed. + 返り値は2つの要素から成っています: 最初は ``(option, value)`` のタプルの リスト、 + 2つ目はオプションリストを取り除いたあとに残ったプログラムの引数リストで す + (*args* の末尾部分のスライスになります)。 + それぞれの引数と値のタプルの最初の要素は、短形式の時はハイフン 1つで始ま る文字列 + (例: ``'-x'``)、長形式の時はハイフン2つで始まる文字列(例: ``'--long-option'``) + となり、引数が2番目の要素になります。引数をとらない場合には空文字列が入 ります。 + オプションは見つかった順に並んでいて、複数回同じオプションを指定すること ができます。 + 長形式と短形式のオプションは混在させることができます。 .. function:: gnu_getopt(args, options[, long_options]) @@ -65,19 +63,10 @@ この関数はデフォルトでGNUスタイルのスキャンモードを使う以外 は :func:`getopt` と同じように動作します。つまり、オプションと オプションでない引数とを混在させることができます。 :func:`getopt` 関数は オプションでない引数を見つけると解析をやめてしまいます。 - .. % This function works like \function{getopt()}, except that GNU style - .. % scanning mode is used by default. This means that option and - .. % non-option arguments may be intermixed. The \function{getopt()} - .. % function stops processing options as soon as a non-option argument is - .. % encountered. - - オプション文字列の最初の文字が '+'にするか、環境変 数 :envvar:`POSIXLY_CORRECT` を設定することで、 + オプション文字列の最初の文字を ``'+'`` にするか、環境変数 + :envvar:`POSIXLY_CORRECT` を設定することで、 オプションでない引数を見つけると解析をやめるように振舞いを変えることがで きます。 - .. % If the first character of the option string is `+', or if the - .. % environment variable POSIXLY_CORRECT is set, then option processing - .. % stops as soon as a non-option argument is encountered. - .. versionadded:: 2.3 @@ -159,9 +148,21 @@ if __name__ == "__main__": main() +:mod:`argparse` モジュールを使えば、より良いヘルプメッセージとエラーメッ セージを +持った同じコマンドラインインタフェースをより少ないコードで実現できます。 :: + + import argparse + + if __name__ == '__main__': + parser = argparse.ArgumentParser() + parser.add_argument('-o', '--output') + parser.add_argument('-v', dest='verbose', action='store_true') + args = parser.parse_args() + # ... do something with args.output ... + # ... do something with args.verbose .. .. seealso:: - Module :mod:`optparse` - よりオブジェクト指向的なコマンドラインオプションのパーズを提供しま す。 - + Module :mod:`argparse` + 別のコマンドラインオプションと引数の解析ライブラリ. + ======================================= --- /library/imaplib.rst Wed Apr 20 03:07:25 2011 +++ /library/imaplib.rst Sat Nov 5 11:21:33 2011 @@ -75,8 +75,9 @@ .. function:: Internaldate2tuple(datestr) - IMAP4 INTERNALDATE 文字列を標準世界時 (Coordinated Universal Time) に変 換します。 :mod:`time` - モジュール形式のタプルを返します。 + IMAP4 の ``INTERNALDATE`` 文字列を解析してそれに相当するローカルタイムを 返します。 + 戻り値は :class:`time.struct_time` のインスタンスか、文字列のフォーマッ トが不正な + 場合は None です。 .. function:: Int2AP(num) @@ -91,8 +92,13 @@ .. function:: Time2Internaldate(date_time) - :mod:`time` モジュールタプルを IMAP4 ``INTERNALDATE`` 表現形式に変換しま す。文字列形式: ``"DD-Mmm-YYYY - HH:MM:SS +HHMM"`` (二重引用符含む) を返します。 + *date_time* を IMAP4 の ``INTERNALDATE`` 表現形式に変換します。 + 戻り値は ``"DD-Mmm-YYYY HH:MM:SS +HHMM"`` (ダブルクォートを含む) の形を した + 文字列です。 + *date_time* 引数は (:func:`time.time` が返す) epoch からの経過秒数を表す 数値 + (int か float) か、(:func:`time.localtime` が返す) ローカルタイムを表現 する + 9要素タプルか、ダブルクォートされた文字列です。文字列だった場合、それが すでに + 正しいフォーマットになっていると仮定されます。 IMAP4 メッセージ番号は、メールボックスに対する変更が行われた後には変化しま す; 特に、 ``EXPUNGE`` 命令はメッセージの削除を 行いますが、残ったメッセージには再度番号を振りなおします。従って、メッセー ジ番号ではなく、 UID 命令を使い、その UID を利用するよう強く勧めます。 @@ -274,8 +280,11 @@ .. method:: IMAP4.open(host, port) - *host* 上の *port* に対するソケットを開きます。このメソッドで確立された 接続オブジェクトは ``read`` 、 - ``readline`` 、 ``send`` 、および ``shutdown`` メソッドで使われます。こ のメソッドはオーバライドすることができます。 + *host* 上の *port* に対するソケットを開きます。 + このメソッドは :class:`IMAP4` のコンストラクタから暗黙的に呼び出されま す。 + このメソッドで確立された接続オブジェクトは ``read``, + ``readline``, ``send``, ``shutdown`` メソッドで使われます。 + このメソッドはオーバライドすることができます。 .. method:: IMAP4.partial(message_num, message_part, start, length) @@ -364,7 +373,9 @@ .. method:: IMAP4.shutdown() - ``open`` で確立された接続を閉じます。このメソッドはオーバライドすること ができます。 + ``open`` で確立された接続を閉じます。 + :meth:`IMAP4.logout` は暗黙的にこのメソッドを呼び出します。 + このメソッドはオーバライドすることができます。 .. method:: IMAP4.socket() ======================================= --- /library/math.rst Fri May 13 06:42:55 2011 +++ /library/math.rst Sat Nov 5 11:21:33 2011 @@ -83,7 +83,7 @@ 桁落ちを防ぎます:: >>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1]) - 0.99999999999999989 + 0.9999999999999999 >>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1]) 1.0 @@ -151,6 +151,21 @@ ``e**x`` を返します。 +.. function:: expm1(x) + + ``e**x - 1`` を返します。 *x* が小さい float の場合は、 ``exp(x) - 1`` + の減算は桁落ちを発生させるかもしれません。 + :func:`expm1` 関数はこの計算を完全な精度で実行します。 :: + + >>> from math import exp, expm1 + >>> exp(1e-5) - 1 # gives result accurate to 11 places + 1.0000050000069649e-05 + >>> expm1(1e-5) # result accurate to full precision + 1.0000050000166668e-05 + + .. versionadded:: 2.7 + + .. function:: log(x[, base]) 引数が1つの場合、 *x* の (*e* を底とする)自然対数を返します。 @@ -295,6 +310,39 @@ *x* の双曲線正接を返します。 +.. Special functions + +特殊な関数 +----------------- + +.. function:: erf(x) + + *x* の誤差関数を返します。 + + .. versionadded:: 2.7 + + +.. function:: erfc(x) + + *x* の相補誤差関数を返します。 + + .. versionadded:: 2.7 + + +.. function:: gamma(x) + + *x* のガンマ関数を返します。 + + .. versionadded:: 2.7 + + +.. function:: lgamma(x) + + *x* のガンマ関数の絶対値の自然対数を返します。 + + .. versionadded:: 2.7 + + 定数 ---- ======================================= --- /library/syslog.rst Sat Nov 27 10:59:46 2010 +++ /library/syslog.rst Sat Nov 5 11:21:33 2011 @@ -10,6 +10,10 @@ このモジュールでは Unix ``syslog`` ライブラリルーチン群へのインタフェースを 提供します。 ``syslog`` の便宜レベルに関する詳細な記述は Unix マニュアルページを参照して ください。 +このモジュールはシステムの ``syslog`` ファミリのルーチンをラップしていま す。 +syslog サーバーと通信できる pure Python のライブラリが、 +:mod:`logging.handlers` モジュールの :class:`SysLogHandler` にあります。 + このモジュールでは以下の関数を定義しています: @@ -23,24 +27,34 @@ *priority* 中に、便宜レベルが (``LOG_INFO | LOG_USER`` のように) 論理和を使ってコード化されていない場合、 :func:`openlog` を呼び出した際 の値が使われます。 - -.. function:: openlog(ident[, logopt[, facility]]) - - 標準以外のログオプションは、 :func:`syslog` の呼び出しに先立っ て :func:`openlog` - でログファイルを開く際、明示的に設定することができます。 - 標準の値は (通常) *indent* = ``'syslog'`` 、 *logopt* = - ``0`` 、 *facility* = :const:`LOG_USER` です。 - *ident* 引数は全てのメッセージの先頭に付加する文字列です。 - オプションの *logopt* 引数はビットフィールドの値になります - とりうる組 み合わせ\ - 値については以下を参照してください。オプションの *facility* 引数は、 - 便宜レベルコードの設定が明示的になされていないメッセージに対する、 - 標準の便宜レベルを設定します。 + :func:`syslog` が呼び出される前に :func:`openlog` が呼び出されなかった場 合、 + ``openlog()`` が引数なしで呼び出されます。 + +.. function:: openlog([ident[, logopt[, facility]]]) + + :func:`openlog` 関数を呼び出すことで以降の :func:`syslog` の呼び出しに対 する + ログオプションを設定することができます。 + ログがまだ開かれていない状態で :func:`syslog` を呼び出す と :func:`openlog` + が引数なしで呼び出されます。 + + オプションの *ident* キーワード引数は全てのメッセージの先頭に付く文字列 で、 + デフォルトでは ``sys.argv[0]`` から前方のパス部分を取り除いたものです。 + + オプションの *logopt* キーワード引数 (デフォルトは 0) はビットフィールド です。 + 組み合わせられる値については下記を参照してください。 + + オプションの *facility* キーワード引数 (デフォルトは :const:`LOG_USER`) は + 明示的に facility が encode されていないメッセージに設定される facility です。 .. function:: closelog() - ログファイルを閉じます。 - + syslog モジュールの値をリセットし、システムライブラリの ``closelog()`` を呼び出します。 + + この関数を呼ぶと、モジュールが最初に import されたときと同じようにふるま います。 + 例えば、(:func:`openlog` を呼び出さないで) :func:`syslog` を最初に呼び出 したときに、 + :func:`openlog` が呼び出され、 *ident* やその他の :func:`openlog` の引数 は + デフォルト値にリセットされます。 .. function:: setlogmask(maskpri) @@ -67,3 +81,22 @@ ``<syslog.h>`` で定義されている場 合、 :const:`LOG_PID` 、 :const:`LOG_CONS` 、 :const:`LOG_NDELAY` 、 :const:`LOG_NOWAIT` 、およ び :const:`LOG_PERROR` 。 +例 +-------- + +シンプルな例 +~~~~~~~~~~~~~~ + +1つ目のシンプルな例:: + + import syslog + + syslog.syslog('Processing started') + if error: + syslog.syslog(syslog.LOG_ERR, 'Processing started') + +いくつかのログオプションを設定する例。ログメッセージにプロセスIDを含み、 +メッセージをメールのログ用の facility にメッセージを書きます。 :: + + syslog.openlog(logopt=syslog.LOG_PID, facility=syslog.LOG_MAIL) + syslog.syslog('E-mail processing initiated...') ======================================= --- /library/wave.rst Fri Jun 3 08:50:44 2011 +++ /library/wave.rst Sat Nov 5 11:21:33 2011 @@ -16,8 +16,9 @@ .. function:: open(file[, mode]) - *file* が文字列ならその名前のファイルを開き、そうでないならファイルのよ うにシーク可能なオブジェクトとして扱います。 *mode* は以下のうち - のいずれかです。 + *file* が文字列ならその名前のファイルを開き、そうでないなら + シーク可能な file like オブジェクトとして扱います。 + *mode* は以下のうちのいずれかです。 ``'r'``, ``'rb'`` 読み込みのみのモード。 @@ -31,6 +32,9 @@ *mode* が省略されていて、ファイルのようなオブジェクトが *file* として渡 されると、 ``file.mode`` が *mode* のデフォルト値として使わ れます（必要であれば、さらにフラグ ``'b'`` が付け加えられます）。 + file like オブジェクトを渡した場合、 wave オブジェクトの :meth:`close` + メソッドを呼び出してもその file like オブジェクトを close しません。 + file like オブジェクトの close は呼び出し側の責任になります。 .. function:: openfp(file, mode) @@ -52,7 +56,9 @@ .. method:: Wave_read.close() - ストリームを閉じ、このオブジェクトのインスタンスを使用できなくします。こ れはオブジェクトのガベージコレクション時に自動的に呼び出されます。 + :mod:`wave` によって開かれていた場合はストリームを閉じ、このオブジェクト の + インスタンスを使用できなくします。 + これはオブジェクトのガベージコレクション時に自動的に呼び出されます。 .. method:: Wave_read.getnchannels() @@ -137,7 +143,8 @@ .. method:: Wave_write.close() - *nframes* が正しいか確認して、ファイルを閉じます。このメソッドはオブジェ クトの削除時に呼び出されます。 + *nframes* が正しいか確認して、ファイルが :mod:`wave` によって開かれてい た場合は + 閉じます。このメソッドはオブジェクトがガベージコレクションされるときに呼 び出されます。 .. method:: Wave_write.setnchannels(n)
