pytho****@googl*****
pytho****@googl*****
2011年 11月 10日 (木) 21:17:52 JST
3 new revisions: Revision: 88fc23e00dc9 Author: Arihiro TAKASE <hinac****@gmail*****> Date: Thu Nov 10 02:54:07 2011 Log: 差分翻訳 2.7.2: documenting/style http://code.google.com/p/python-doc-ja/source/detail?r=88fc23e00dc9 Revision: 22b8c52879e4 Author: Arihiro TAKASE <hinac****@gmail*****> Date: Thu Nov 10 02:54:27 2011 Log: merge http://code.google.com/p/python-doc-ja/source/detail?r=22b8c52879e4 Revision: f04d1cb8d3c3 Author: Arihiro TAKASE <hinac****@gmail*****> Date: Thu Nov 10 04:16:36 2011 Log: 差分翻訳 2.7.2: library/string http://code.google.com/p/python-doc-ja/source/detail?r=f04d1cb8d3c3 ============================================================================== Revision: 88fc23e00dc9 Author: Arihiro TAKASE <hinac****@gmail*****> Date: Thu Nov 10 02:54:07 2011 Log: 差分翻訳 2.7.2: documenting/style http://code.google.com/p/python-doc-ja/source/detail?r=88fc23e00dc9 Modified: /documenting/style.rst ======================================= --- /documenting/style.rst Sat Mar 19 10:54:49 2011 +++ /documenting/style.rst Thu Nov 10 02:54:07 2011 @@ -1,29 +1,25 @@ .. highlightlang:: rest -.. Style Guide -.. =========== - スタイルガイド ============== -.. The Python documentation should follow the `Apple Publications Style Guide`_ -.. wherever possible. This particular style guide was selected mostly because it -.. seems reasonable and is easy to get online. - Python ドキュメントは、可能な限り `Apple Publications Style Guide`_ に 準拠することになっています。内容の合理性と、オンラインで容易に取得できるこ とから、 このスタイルガイドが選ばれました。 -.. Topics which are not covered in the Apple's style guide will be discussed in -.. this document if necessary. - Apple のスタイルガイドがカバーしていないトピックについては、この ドキュメントで必要に応じて議論していきます。 -.. Footnotes are generally discouraged, though they may be used when they are the -.. best way to present specific information. When a footnote reference is added at -.. the end of the sentence, it should follow the sentence-ending punctuation. The -.. reST markup should appear something like this:: +すべての reST ファイルは 3 スペースのインデントを使います。 +長さの上限は通常のテキストでは 80 文字ですが、テーブルや、深くインデントさ れた +コードサンプルや、長いリンクはそれ以上にもなります。 + +空行を適切なところに惜しみなく使ってください。 +これはグループ化の助けになります。 + +センテンスの終わりのピリオドには、1 つか 2 つのスペースを +続けることができます。reST は二つ目のスペースを無視しますが、Emacs の +オートフィルモードを補助するためになど、慣習的に置かれることがあります。 脚注は、何かの情報を提供するのにもっとも適した方法である場合は利用されます が、 普通はお勧めできません。 @@ -32,43 +28,21 @@ この文には脚注への参照があります。 [#]_ ここは次の文になります。 -.. Footnotes should be gathered at the end of a file, or if the file is very long, -.. at the end of a section. The docutils will automatically create backlinks to the -.. footnote reference. - 脚注はファイルの終端か、ファイルが非常に大きい場合は節の終わりに集められま す。 docutils は自動的に、脚注の参照への逆リンクを作成します。 -.. Footnotes may appear in the middle of sentences where appropriate. - 脚注は、文の途中でも適切な場所で使用することができます。 -.. Many special names are used in the Python documentation, including the names of -.. operating systems, programming languages, standards bodies, and the like. Most -.. of these entities are not assigned any special markup, but the preferred -.. spellings are given here to aid authors in maintaining the consistency of -.. presentation in the Python documentation. - Python ドキュメントの中では、オペレーティングシステムやプログラミング言語、 標準機関、その他の名前を含む沢山の特殊な名前を使っています。 それらの名前のほとんどには特別なマークアップを割り当てていませんが、推奨さ れる 表記法をここで提供して、ドキュメント作者が Python ドキュメント内の表現の一 貫性を 維持しやすくします。 -.. Other terms and words deserve special mention as well; these conventions should -.. be used to ensure consistency throughout the documentation: - その他の用語や単語についても特に説明しておく必要があるでしょう; ドキュメントの作者はこれらの規約に従い、ドキュメント全体を通して 一貫性を保証しなければなりません。 -.. CPU -.. For "central processing unit." Many style guides say this should be spelled -.. out on the first use (and if you must use it, do so!). For the Python -.. documentation, this abbreviation should be avoided since there's no -.. reasonable way to predict which occurrence will be the first seen by the -.. reader. It is better to use the word "processor" instead. - CPU "central processing unit" (中央処理装置) のことです。多くのスタイルガイ ドが、 この語を最初に利用するときには略さずに書かねばならないとしています @@ -77,33 +51,117 @@ 略語の使用を避けねばなりません。 代わりに "processor (プロセッサ)" を使う方がよいでしょう。 -.. POSIX -.. The name assigned to a particular group of standards. This is always -.. uppercase. - POSIX ある一連の標準仕様につけられた名前です。常に大文字だけからなります。 -.. Python -.. The name of our favorite programming language is always capitalized. - Python 私たちの大好きなプログラミング言語の名前は、常に大文字で始めます。 -.. Unicode -.. The name of a character set and matching encoding. This is always written -.. capitalized. - Unicode ある文字セットと、それに対応する符号化方式の名前です。 常に大文字で始めます。 -.. Unix -.. The name of the operating system developed at AT&T Bell Labs in the early -.. 1970s. - Unix 1970年代初頭に AT&T ベル研究所で開発されたオペレーティングシステムの名 前です。 +肯定的な論調 +------------ + +ドキュメントの焦点は、言語が何をするか、またはどうすれば効率がいいかを、 +肯定的に述べるようにすることです。 + +ある種のセキュリティ上の問題やセグメンテーション違反を除き、ドキュメントは +"機能 x は危険です" や "上級者専用" などといった言い回しを避けるべきです。 +これらの価値判断は、コアドキュメントではなく外部のブログや +wiki で行うものです。 + +悪い例 (読者を心配させてしまう): + + 警告: 明示的にファイルを閉じないと、データの損失や莫大なリソースの + 消費につながります。決して、参照カウントが自動的にファイルを閉じること に + 頼らないでください。 + +良い例 (言語の効率的な使い方について、確かな知識を確立する): + + ファイルを使うための最高のプラクティスは、try/finally の対を使い、 + ファイルが使われた後に明示的に閉じることです。その代わりに、 + with 文でも同じことができます。これは、適切な時にファイルが流され + ファイルディスクリプタリソースが解放されることを保証します。 + +簡潔な表現 +---------- + +多いドキュメントが良いドキュメントであるとは限りません。簡潔すぎるくらいに +しましょう。 + +ドキュメントを長くすることは理解の障碍となり、テキストの誤読や誤解釈に +つながります。特殊な例や警告が多い長い記述は、関数が実際より複雑で +使いづらいものであるかのような印象を与えてしまします。 + +:func:`super` のドキュメントは、多くの情報が短いパラグラフに凝縮された +いい例です。:func:`super` についての議論は本の一章ほどの内容がありますが、 +長い説話より簡潔な記述の方が理解しやすいことが多いのです。 + + +コード例 +------------- + +短いコード例は理解の助けになります。正式な散文体の記述より、 +簡単な例の方が読者にとって理解しやすいことが多いです。 + +特定のユースケースに合った、実際的で動機づけのある例があれば、習得が +早くなります。例えば、\ :func:`str.rpartition` メソッドは、Monty Python の +会話文の最後の単語を取り除く例よりも、 URL をドメインに分割する例を +挙げて実演したほうがいいです。 + +入力行と出力行を区別するべきところでは、 +:attr:`sys.ps2` 第二インタプリタプロンプトの省略は控えるべきです。 +見てわかりづらくなるだけでなく、読者が例をカットアンドペーストして +変化させながら実験することも難しくしています。 + +等価なコード +------------ + +等価な (またはほぼ等価な) コードを与えると、散文記述を補助するのに便利で す。 +ドキュメント記述者は、等価なコードが価値を加えるかよく考えるべきです。 + +良い例は、 :func:`all` の等価なコードです。短い 4 行のコードで簡単に +要約できます。できるだけ早く抜けるふるまいを最強調します。また、イテラブル が +空であったときの特殊な例の扱いを明確にします。さらに、:func:`all` 関数が +早く終了した時、False と評価された特定のオブジェクトを返すような、 +よく要求される変形版を実装したい人々のためのモデルとしても役立ちます。 + +微妙な例は :func:`itertools.groupby` のコードです。この等価なコードは +迅速な理解の助けとなるには複雑すぎるかもしれません。 +その複雑さにもかかわらず、この等価なコードは、別の実装のモデルとして、ま た、 +「グループ処理」は英語の散文で書くよりもコードで示したほうが簡単なために、 +残されています。 + +等価なコードを使うべきでない時の例は、\ :func:`oct` 関数です。 +数を八進数に変換するための手順は、ユーザーがこの関数の性質を学ぶときに +価値があるものではないからです。 + +読者 +---- + +チュートリアル (とすべてのドキュメント) の論調は、読者の知性を尊重した +ものでなくてはなりません。読者が愚かであると考えないでください。 +関連情報を配置し、動機付けとなるユースケースを示し、用語集へのリンクを提供 し、 +点をつなぎ合わせることに最善を尽くしてください。しかし、それを読者に +しゃべり尽くして読者の時間を無駄にするようなことはしないでください。 + +チュートリアルは新参者を意識したもので、彼らの多くはチュートリアルで +言語全体を評価しようとします。チュートリアルの経験は肯定的であるべきです。 +読者に、間違いを起こすと何か悪いことが起きるというような心配を +させないでください。チュートリアルは、知的で好奇心旺盛な読者のための +ガイドとして振る舞い、詳細は how-to ガイドその他のソースに取っておきます。 + +プログラミングエラーを正当化したがる少数の遠慮無い読者 (「誤りを犯して +しましました。だから、ドキュメントに間違いがあるに違いありません……」) +からドキュメント変更の要請を受け付ける時には注意してください。 +典型的に、ドキュメントは誤りが見つかるまで調べられません。残念ながら、 +典型的にはドキュメントの編集によってユーザが間違った予想をすることを +避けることは出来なかったでしょう (「驚きました……」) + .. _Apple Publications Style Guide: http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2009.pdf ============================================================================== Revision: 22b8c52879e4 Author: Arihiro TAKASE <hinac****@gmail*****> Date: Thu Nov 10 02:54:27 2011 Log: merge http://code.google.com/p/python-doc-ja/source/detail?r=22b8c52879e4 ============================================================================== Revision: f04d1cb8d3c3 Author: Arihiro TAKASE <hinac****@gmail*****> Date: Thu Nov 10 04:16:36 2011 Log: 差分翻訳 2.7.2: library/string http://code.google.com/p/python-doc-ja/source/detail?r=f04d1cb8d3c3 Modified: /library/string.rst ======================================= --- /library/string.rst Fri Jun 3 08:50:44 2011 +++ /library/string.rst Thu Nov 10 04:16:36 2011 @@ -17,6 +17,11 @@ :ref:`string-formatting` に記載の ``%`` 演算子を使用して下さい。 正規表現に関する文字列操作の関数は :mod:`re` を参照してください。 +.. seealso:: + + 最新のバージョンの `string モジュール Python ソースコード + <http://svn.python.org/view/python/branches/release27-maint/Lib/string.py?view=markup>`_ + 文字列定数 ---------- @@ -116,7 +121,7 @@ :class:`Formatter` クラスは、以下のメソッドを持ちます。 : - .. method:: format(format_string, *args, *kwargs) + .. method:: format(format_string, *args, **kwargs) :meth:`format` は主たる API メソッドです。引数は、書式指定テンプ レート文字列、および、任意のポジション、キーワード引数をとります。 @@ -221,37 +226,50 @@ 置換フィールドの文法は以下です: .. productionlist:: sf - replacement_field: "{" `field_name` ["!" `conversion`] [":" `format_spec`] "}" - field_name: (`identifier` | `integer`) ("." `attribute_name` | "[" `element_index` "]")* + replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}" + field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")* + arg_name: [`identifier` | `integer`] attribute_name: `identifier` element_index: `integer` | `index_string` index_string: <any source character except "]"> + conversion: "r" | "s" format_spec: <described in the next section> -公式な用語はさておき、置換フィールドは *field_name* (ポジション引数としての -数字でも構いません) 、あるいは、 (キーワード引数の) 識別子から始まります。 -次いで、感嘆符 ``'!'`` を挟んでオプションの *conversion* フィールドを書きま す。 -最後にコロン ``':'`` を挟んで、 *format_spec* を書きます。 +もっと簡単にいうと、置換フィールドは *field_name* で始められます。 +これによって指定したオブジェクトの値が、置換フィールドの代わりに +書式化され出力に挿入されます。 +その後に、感嘆符 ``'!'`` を挟んで *conversion* フィールドを続けることができ ます。 +最後にコロン ``':'`` を挟んで、 *format_spec* を書くことができます。 +これは、置換される値の非デフォルトの書式を指定します。 :ref:`formatspec` 節も参照して下さい。 -*field_name* は数字かキーワードで始まります。数字である場合、ポジショ -ン引数として扱われます。キーワードである場合、キーワード引数として扱わ -れます。これに他の数字やインデックスや属性表現が続いても構いません。 -``'.name'`` 形式の表現の場合、 :func:`getattr` 使って属性が選択され、 -``'[index]'`` 形式の表現の場合、 :func:`__getitem__` を使ってインデッ +*field_name* 自体は、数字かキーワードである *arg_name* で始まります。 +数字である場合、ポジション引数を参照します。キーワードである場合、 +指名されたキーワード引数を参照します。 +書式指定文字列中の数の *arg_name* が 0, 1, 2, ... と並んでいるなら、 +これらは (一部ではなく) すべて省略でき、数 0, 1, 2, ... がその順に +自動的に挿入されます。 +*arg_name* の後に数字インデックスや属性式を続けることができます。 +``'.name'`` 形式の式の場合、 :func:`getattr` 使って指名された属性が選択さ れ、 +``'[index]'`` 形式の式の場合、 :func:`__getitem__` を使ってインデッ クス検索されます。 +.. versionchanged:: 2.7 + ポジション引数指定子は省略できるようになりました。 + ``'{} {}'`` は ``'{0} {1}'`` と等価です。 + 簡単な書式指定文字列の例を挙げます:: "First, thou shalt count to {0}" # 最初のポジション引数を参照します + "Bring me a {}" # 暗示的に第一ポジション引数を参照しま す + "From {} to {}" # "From {0} to {1}" と同じです "My quest is {name}" # キーワード引数 'name' を参照します "Weight in tons {0.weight}" # 最初のポジション引数の属性 'weight' を参照します "Units destroyed: {players[0]}" # キーワード引数 'players' の最初の要素 を参照します -*conversion* フィールドにより書式変換前に型の強制変換が実施されます。 +*置換 (conversion)* フィールドにより書式変換前に型の強制変換が実施されま す。 通常、値の書式変換は :meth:`__format__` によって実施されます。しかしな がら、場合によっては、文字列として変換することを強制したり、書式指定の 定義をオーバーライドしたくなることもあります。 :meth:`__format__` の呼 @@ -303,7 +321,7 @@ 一般的な書式指定子 (*standard format specifier*) の書式は以下です: .. productionlist:: sf - format_spec: [[`fill`]`align`][`sign`][#][0][`width`][.`precision`][`type`] + format_spec: [[`fill`]`align`][`sign`][#][0][`width`][,][.`precision`][`type`] fill(詰め方): <'}'以外の文字> align(整列): "<" | ">" | "=" | "^" sign(符号): "+" | "-" | " " @@ -311,8 +329,8 @@ precision(精度): `整数` type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%" -*fill* は、 (フィールドの終わりを示す) '}' 以外のどんな文字でもかまいませ ん。 -fill 文字の有無は、 align オプションが続くことによって、示されます。 +*fill* 文字は、'{' と '}' 以外のどんな文字でもかまいません。 +fill 文字があることは、 align オプションが続くことで示されます。 もし、 *format_spec* の二つめの文字が align オプションで無い場合は、 fill と align の両方のオプションが無いものと解釈されます。 @@ -322,10 +340,10 @@ | オプション | 意味 | +============+==========================================================+ | ``'<'`` | 利用可能なスペースにおいて、左詰めを強制します。 | - | | (デフォルト) | + | | (ほとんどのオブジェクトにおいてのデフォルト) | +------------+----------------------------------------------------------+ | ``'>'`` | 利用可能なスペースにおいて、右詰めを強制します。 | - | | | + | | (いくつかのオブジェクトにおいてのデフォルト) | +------------+----------------------------------------------------------+ | ``'='`` | 符号 (があれば) の後ろを埋めます。 | | | '+000000120' のような形で表示されます。 | @@ -359,6 +377,12 @@ 指定されれば、出力は、 ``'0b'``, ``'0o'``, もしくは ``'0x'``, のプリフィッ クスが 付与されます。 +``','`` オプションは、千の位のセパレータにカンマを使うことを合図します。 +ロケール依存のセパレータには、代わりに ``'n'`` の整数表現形式を使ってくださ い。 + +.. versionchanged:: 2.7 + ``','`` オプションを追加しました (:pep:`378` も参照してください)。 + *width* は10進数の整数で、最小のフィールド幅を規程します。 もし指定されなければ、フィールド幅は内容により規程されます。 @@ -444,7 +468,8 @@ | | 書式指定されます。この両方の場合で重要でない、 | | | 連続した 0 は取り除かれます, そして残った桁が無い場合 | | | 小数点は取り除かれます。 | - | | 正と負の無限大と0 および NaN はそれぞれ精度に関係なく | + | | | + | | 正と負の無限大と 0 および NaN は精度に関係なくそれぞれ | | | ``inf``, ``-inf``, ``0``, ``-0`` および ``nan`` | | | となります。 | | | | @@ -473,7 +498,7 @@ 多くの場合、 ``%`` の代わりに ``{}`` を加えることで新構文は 古い ``%``-書式に類似した書式になります。 -例えば、 ``'%03.2f'`` は ``'{0:03.2f}'`` に翻訳できます。 +例えば、 ``'%03.2f'`` は ``'{:03.2f}'`` に翻訳できます。 以下の例で示すように、新構文はさらに新たに様々なオプションもサポートしてい ます、 @@ -481,6 +506,8 @@ >>> '{0}, {1}, {2}'.format('a', 'b', 'c') 'a, b, c' + >>> '{}, {}, {}'.format('a', 'b', 'c') # 2.7+ 専用 + 'a, b, c' >>> '{2}, {1}, {0}'.format('a', 'b', 'c') 'c, b, a' >>> '{2}, {1}, {0}'.format(*'abc') # 引数シークエンスをアンパック @@ -497,7 +524,7 @@ >>> 'Coordinates: {latitude}, {longitude}'.format(**coord) 'Coordinates: 37.24N, -115.81W' -引数の属性へのアクセル:: +引数の属性へのアクセス:: >>> c = 3-5j >>> ('The complex number {0} is formed from the real part {0.real} ' @@ -520,28 +547,28 @@ ``%s`` と ``%r`` の置換:: - >>> "repr() shows quotes: {0!r}; str() doesn't: {1!s}".format('test1', 'test2') + >>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2') "repr() shows quotes: 'test1'; str() doesn't: test2" テキストの幅を指定した整列:: - >>> '{0:<30}'.format('left aligned') + >>> '{:<30}'.format('left aligned') 'left aligned ' - >>> '{0:>30}'.format('right aligned') + >>> '{:>30}'.format('right aligned') ' right aligned' - >>> '{0:^30}'.format('centered') + >>> '{:^30}'.format('centered') ' centered ' - >>> '{0:*^30}'.format('centered') # 詰め文字に '*' を使う + >>> '{:*^30}'.format('centered') # 詰め文字に '*' を使う '***********centered***********' ``%+f`` と ``%-f``, ``% f`` の置換、そして符号の指定:: - >>> '{0:+f}; {0:+f}'.format(3.14, -3.14) # 常に表示する + >>> '{:+f}; {:+f}'.format(3.14, -3.14) # 常に表示する '+3.140000; -3.140000' - >>> '{0: f}; {0: f}'.format(3.14, -3.14) # 正の数にはスペースを表示 + >>> '{: f}; {: f}'.format(3.14, -3.14) # 正の数にはスペースを表示 ' 3.140000; -3.140000' - >>> '{0:-f}; {0:-f}'.format(3.14, -3.14) # マイナスだけを表示 -- '{0:f}; {0:f}' と同じ + >>> '{:-f}; {:-f}'.format(3.14, -3.14) # マイナスだけを表示 -- '{:f}; {:f}' と同じ '3.140000; -3.140000' ``%x`` と ``%o`` の置換、そして値に対する異なる底の変換:: @@ -553,31 +580,36 @@ >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}".format(42) 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010' +千の位のセパレータにカンマを使用する:: + + >>> '{:,}'.format(1234567890) + '1,234,567,890' + パーセントを表示する:: >>> points = 19.5 >>> total = 22 - >>> 'Correct answers: {0:.2%}.'.format(points/total) + >>> 'Correct answers: {:.2%}.'.format(points/total) 'Correct answers: 88.64%' 型特有の書式指定を使う:: >>> import datetime >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58) - >>> '{0:%Y-%m-%d %H:%M:%S}'.format(d) + >>> '{:%Y-%m-%d %H:%M:%S}'.format(d) '2010-07-04 12:15:58' 引数をネストする、さらに複雑な例:: >>> for align, text in zip('<^>', ['left', 'center', 'right']): - ... '{0:{align}{fill}16}'.format(text, fill=align, align=align) + ... '{:{align}{fill}16}'.format(text, fill=align, align=align) ... 'left<<<<<<<<<<<<' '^^^^^center^^^^^' '>>>>>>>>>>>right' >>> >>> octets = [192, 168, 0, 1] - >>> '{0:0X}{1:02X}{2:02X}{3:02X}'.format(*octets) + >>> '{:0X}{:02X}{:02X}{:02X}'.format(*octets) 'C0A80001' >>> int(_, 16) 3232235521
