.. XXX: reference/datamodel and this have quite a few overlaps!

.. _bltin-types:

**********
組み込み型
**********

以下のセクションでは、インタプリタに組み込まれている標準の型について記述します。

.. note::

   これまでの (リリース 2.2 までの) Python の歴史では、組み込み型はオ
   ブジェクト指向における継承を行う際に雛型にできないという点で、ユー
   ザ定義型とは異なっていました。いまではこのような制限はなくなってい
   ます。

.. index:: pair: built-in; types

主要な組み込み型は数値型、シーケンス型、マッピング型、ファイル、クラス、
インスタンス型、および例外です。

.. index:: statement: print

演算によっては、複数の型でサポートされているものがあります; 特に、ほぼ
全てのオブジェクトについて、比較、真理値テスト、 (:func:`repr` 関数や、
わずかに異なる :func:`str` 関数による) 文字列への変換を行うことができ
ます。オブジェクトが :func:`print` 関数によって書かれていると、後の方の
文字列への変換が暗黙に行われます。


.. _truth:

真理値テスト
============

.. index::
   statement: if
   statement: while
   pair: truth; value
   pair: Boolean; operations
   single: false

どのオブジェクトも :keyword:`if` または :keyword:`while` 条件文の中や、
以下のブール演算における被演算子として真理値テストを行うことができます。
以下の値は偽であると見なされます:

  .. index:: single: None (Built-in object)

* ``None``

  .. index:: single: False (Built-in object)

* ``False``

* 数値型におけるゼロ。例えば ``0``, ``0L``, ``0.0``, ``0j`` 。

* 空のシーケンス型。例えば ``''``, ``()``, ``[]`` 。

* 空のマッピング型。例えば ``{}`` 。

* :meth:`__nonzero__` または :meth:`__len__` メソッドが定義されている
  ようなユーザ定義クラスのインスタンスで、それらのメソッドが整数値ゼ
  ロまたは :class:`bool` 値の ``False`` を返すとき。
  [#]_

.. index:: single: true

それ以外の値は全て真であると見なされます --- 従って、ほとんどの型のオ
ブジェクトは常に真です。

.. index::
   operator: or
   operator: and
   single: False
   single: True

ブール値の結果を返す演算および組み込み関数は、特に注釈のない限り常に
偽値として ``0`` または ``False`` を返し、真値として ``1``  または
``True`` を返します (重要な例外: ブール演算 ``or`` および ``and`` は常
に被演算子の中の一つを返します)。


.. _boolean:

ブール演算 --- :keyword:`and`, :keyword:`or`, :keyword:`not`
============================================================

.. index:: pair: Boolean; operations

以下にブール演算子を示します。優先度の低いものから順に並んでいます。:

+-------------+----------------------------------------+------+
| 演算        | 結果                                   | 注釈 |
+=============+========================================+======+
| ``x or y``  | *x* が偽なら *y*, そうでなければ *x*   | \(1) |
+-------------+----------------------------------------+------+
| ``x and y`` | *x* が偽なら *x*, そうでなければ *y*   | \(2) |
+-------------+----------------------------------------+------+
| ``not x``   | *x* が偽なら ``True``, そうでなければ  | \(3) |
|             | ``False``                              |      |
+-------------+----------------------------------------+------+

.. index::
   operator: and
   operator: or
   operator: not

注釈:

(1)
   これは、短絡的な演算子であり、一つめの引数が :const:`False` のとき
   にのみ、二つめの引数を評価します。


(2)
   これは、短絡的な演算子であり、一つめの引数が :const:`True` のとき
   にのみ、二つめの引数を評価します。

(3)
   ``not`` は非ブール演算子よりも低い演算優先度なので、 ``not a == b``
   は ``not (a == b)`` と評価され、 ``a == not b`` は構文エラーとなり
   ます。


.. _stdcomparisons:

比較
====

.. index::
   pair: chaining; comparisons
   operator: ==
   operator: <
   operator: <=
   operator: >
   operator: >=
   operator: !=
   operator: is
   operator: is not

比較演算は全てのオブジェクトでサポートされています。比較演算子は全て
同じ演算優先度を持っています (ブール演算より高い演算優先度です)。
比較は任意の形で連鎖させることができます; 例えば、 ``x < y <= z`` は
``x < y and y <= z`` と等価で、違うのは *y* が一度だけしか評価され
ないということです (どちらの場合でも、 ``x < y`` が偽となった場合には
*z* は評価されません)。

以下のテーブルに比較演算をまとめます:

+------------+--------------------------+
| 演算       | 意味                     |
+============+==========================+
| ``<``      | より小さい               |
+------------+--------------------------+
| ``<=``     | 以下                     |
+------------+--------------------------+
| ``>``      | より大きい               |
+------------+--------------------------+
| ``>=``     | 以上                     |
+------------+--------------------------+
| ``==``     | 等しい                   |
+------------+--------------------------+
| ``!=``     | 等しくない               |
+------------+--------------------------+
| ``is``     | 同一のオブジェクトである |
+------------+--------------------------+
| ``is not`` | 同一のオブジェクトでない |
+------------+--------------------------+

.. index::
   pair: object; numeric
   pair: objects; comparing

数値型間の比較か文字列間の比較でないかぎり、異なる型のオブジェクトを比
較しても等価になることはありません; これらのオブジェクトの順番付けは一
貫してはいますが任意のものです (従って要素の型が一様でないシーケンスを
ソートした結果は一貫したものになります)。
さらに、 (例えばファイルオブジェクトのように) 型によっては、その型の
2 つのオブジェクトの不等性だけの、縮退した比較の概念しかサポートしない
ものもあります。繰り返しますが、そのようなオブジェクトも任意の順番付け
をされていますが、それは一貫したものです。被演算子が複素数の場合、演算
子 ``<``, ``<=``, ``>`` および ``>=`` は例外 :exc:`TypeError` を送
出します。

.. index:: single: __cmp__() (instance method)

あるクラスのインスタンス間の比較は、そのクラスで :meth:`__cmp__` メソッ
ドが定義されていない限り等しくなりません。
このメソッドを使ってオブジェクトの比較方法に影響を及ぼすための情報につ
いては :ref:`customization` を参照してください。

.. impl-detail::

   数値型を除き、異なる型のオブジェクトは型の名前で
   順番付けされます; 適当な比較をサポートしていないある型のオブジェクトは
   アドレスによって順番付けされます。

.. index::
   operator: in
   operator: not in

同じ優先度を持つ演算子としてさらに 2 つ、シーケンス型でのみ ``in`` お
よび ``not in`` がサポートされています (以下を参照)。


.. _typesnumeric:

数値型 :class:`int`, :class:`float`, :class:`long`, :class:`complex`
====================================================================

.. index::
   object: numeric
   object: Boolean
   object: integer
   object: long integer
   object: floating point
   object: complex number
   pair: C; language

4 つの異なる数値型があります: :dfn:`通常の整数型`, :dfn:`長整数型`,
:dfn:`浮動小数点型`, :dfn:`複素数型` です。
さらに、真偽値(Boolean)型も通常の整数型のサブタイプです。通常の整数 (単に
:dfn:`整数型` とも呼ばれます) は C言語の :c:type:`long` 型を使って実装され
ており、少なくとも 32 ビットの精度があります (``sys.maxint`` は常に通
常の整数の各プラットフォームにおける最大値にセットされており、最小値は
``-sys.maxint - 1`` になります)。
長整数型には精度の制限がありません。
浮動小数点型はたいていは C の :c:type:`double` を使って実装されています;
あなたのプログラムが動作するマシンでの浮動小数点型の精度と内部表現は、
:data:`sys.float_info` から利用できます。
複素数型は実部と虚部を持ち、それぞれ浮動小数点数です。
複素数 *z* から実部および虚部を取り出すには、
``z.real`` および ``z.imag`` を使ってください。
(標準ライブラリには、追加の数値型、分数を保持する :mod:`fractions` や、
ユーザ定義の精度の浮動小数点数を保持する :mod:`decimal` があります。)

.. index::
   pair: numeric; literals
   pair: integer; literals
   triple: long; integer; literals
   pair: floating point; literals
   pair: complex number; literals
   pair: hexadecimal; literals
   pair: octal; literals

数値は、数値リテラルや組み込み関数や演算子の戻り値として生成されます。
修飾のない整数リテラル ( 2 進表現や、 16 進表現や 8 進表現の値も含みま
す) は、通常の整数値を表します。値が通常の整数で表すには大きすぎる場合、
``'L'`` または ``'l'`` が末尾につく整数リテラルは長整数型を表します
(``'L'`` が望ましいです。というのは ``1l`` は 11 と非常に紛らわしいか
らです!) 小数点または指数表記のある数値リテラルは浮動小数点数を表しま
す。数値リテラルに ``'j'`` または ``'J'`` をつけると実数部がゼロの複素
数を表します。
複素数の数値リテラルは実数部と虚数部を足したものです。

.. index::
   single: arithmetic
   builtin: int
   builtin: long
   builtin: float
   builtin: complex
   operator: +
   operator: -
   operator: *
   operator: /
   operator: //
   operator: %
   operator: **

Python は型混合の演算を完全にサポートします: ある 2 項演算子が互いに異
なる数値型の被演算子を持つ場合、より "制限された" 型の被演算子は他方の
型に合わせて広げられます。ここで通常の整数は長整数より制限されており、
長整数は浮動小数点数より制限されており、浮動小数点は複素数より制限され
ています。型混合の数値間での比較も同じ規則に従います。 [#]_ コンストラ
クタ :func:`int`, :func:`long`, :func:`float`, および
:func:`complex` を使って、特定の型の数を生成することができます。

全ての組み込み数値型は以下の演算をサポートします。
演算子の優先度については、 :ref:`power`,および、あとのセクションを参
照下さい。

+--------------------+-------------------------------------------+--------+
| 演算               | 結果                                      |  注釈  |
+====================+===========================================+========+
| ``x + y``          | *x* と *y* の和                           |        |
+--------------------+-------------------------------------------+--------+
| ``x - y``          | *x* と *y* の差                           |        |
+--------------------+-------------------------------------------+--------+
| ``x * y``          | *x* と *y* の積                           |        |
+--------------------+-------------------------------------------+--------+
| ``x / y``          | *x* と *y* の商                           |  \(1)  |
+--------------------+-------------------------------------------+--------+
| ``x // y``         | *x* と *y* の商(を切り下げたもの)         | (4)(5) |
+--------------------+-------------------------------------------+--------+
| ``x % y``          | ``x / y`` の剰余                          |  \(4)  |
+--------------------+-------------------------------------------+--------+
| ``-x``             | *x* の符号反転                            |        |
+--------------------+-------------------------------------------+--------+
| ``+x``             | *x* の符号不変                            |        |
+--------------------+-------------------------------------------+--------+
| ``abs(x)``         | *x* の絶対値または大きさ                  |  \(3)  |
+--------------------+-------------------------------------------+--------+
| ``int(x)``         | *x* の通常整数への変換                    |  \(2)  |
+--------------------+-------------------------------------------+--------+
| ``long(x)``        | *x* の長整数への変換                      |  \(2)  |
+--------------------+-------------------------------------------+--------+
| ``float(x)``       | *x* の浮動小数点数への変換                |  \(6)  |
+--------------------+-------------------------------------------+--------+
| ``complex(re,im)`` | 実数部 *re*, 虚数部 *im* の複素数。 *im*  |        |
|                    | のデフォルト値はゼロ。                    |        |
+--------------------+-------------------------------------------+--------+
| ``c.conjugate()``  | 複素数 *c* の共役複素数(実数部に依存する) |        |
+--------------------+-------------------------------------------+--------+
| ``divmod(x, y)``   | ``(x // y, x % y)`` からなるペア          |  \(3)  |
+--------------------+-------------------------------------------+--------+
| ``pow(x, y)``      | *x* の *y* 乗                             | (3)(7) |
+--------------------+-------------------------------------------+--------+
| ``x ** y``         | *x* の *y* 乗                             |  \(7)  |
+--------------------+-------------------------------------------+--------+

.. index::
   triple: operations on; numeric; types
   single: conjugate() (complex number method)

注釈:

(1)
   .. index::
      pair: integer; division
      triple: long; integer; division

   (通常および長) 整数の割り算では、結果は整数になります。この場合値は
   常にマイナス無限大の方向に丸められます: つまり、1/2 は 0、 (-1)/2
   は -1、1/(-1) は -1、そして (-1)/(-2) は 0 になります。被演算子の両
   方が長整数の場合、計算値に関わらず結果は長整数で返されるので注意し
   てください。

(2)
   .. index::
      module: math
      single: floor() (in module math)
      single: ceil() (in module math)
      single: trunc() (in module math)
      pair: numeric; conversions

   浮動小数点数から :func:`int`,または、 :func:`long` を使った変換で
   は、関連する関数、 :func:`math.trunc` のようにゼロ方向へ丸められま
   す。下方向への丸めには :func:`math.floor` を使い、上方向への丸めに
   は :func:`math.ceil` を使って下さい。

(3)
   完全な記述については、 :ref:`built-in-funcs`,を参照してください。

(4)
   複素数の切り詰め除算演算子、モジュロ演算子、および :func:`divmod` 。

   .. deprecated:: 2.3
      複素数の切り詰め除算演算子、モジュロ演算子、および :func:`divmod`
      関数は、複素数には定義されなくなりました。
      複素数型には使えません。適切なら代わりに :func:`abs` で浮動小数点型に
      変換してください。

(5)
   整数の除算とも呼ばれます。結果の値は整数ですが、整数型(int)とは限りません。

(6)
   浮動小数点数は、文字列、オプションの接頭辞 "+" または "-" と共に
   "nan" と "inf" を、非数 (Not a Number (NaN)) や正、負の無限大として
   受け付けます。

   .. versionadded:: 2.6

(7)
   Python はプログラム言語一般でそうであるように、 ``pow(0, 0)``,お
   よび、 ``0 ** 0`` を ``1`` と定義します。

全ての :class:`numbers.Real` 型 (:class:`int`, :class:`long`,およ
び、 :class:`float`) は以下の演算を含みます。 :

+--------------------+------------------------------------------------+--------+
| 演算               | 結果                                           | 備考   |
+====================+================================================+========+
| ``math.trunc(x)``  | *x* を整数に切り捨てます。                     |        |
+--------------------+------------------------------------------------+--------+
| ``round(x[, n])``  | *x* を n 桁に丸めます。                        |        |
|                    | 丸め方は偶数丸めです。                         |        |
|                    | n が省略されれば 0 がデフォルトとなります。    |        |
+--------------------+------------------------------------------------+--------+
| ``math.floor(x)``  | *x* 以下の最大の整数を浮動少数点数で返します。 |        |
+--------------------+------------------------------------------------+--------+
| ``math.ceil(x)``   | *x* 以上の最小の整数を浮動小数点数で返します。 |        |
+--------------------+------------------------------------------------+--------+

.. XXXJH exceptions: overflow (when? what operations?) zerodivision


.. _bitstring-ops:

整数型におけるビット列演算
--------------------------

.. index::
   triple: operations on; integer; types
   pair: bit-string; operations
   pair: shifting; operations
   pair: masking; operations
   operator: ^
   operator: &
   operator: <<
   operator: >>

通常および長整数型ではさらに、ビット列に対してのみ意味のある演算をサポー
トしています。負の数はその値の 2 の補数の値として扱われます (長整数の
場合、演算操作中にオーバフローが起こらないように十分なビット数があるも
のと仮定します) 。

2 進のビット単位演算は全て、数値演算よりも低く、比較演算子よりも高い優
先度です; 単項演算 ``~`` は他の単項数値演算 (``+`` および ``-``) と同じ
優先度です。

以下のテーブルでは、ビット列演算を優先度の低いものから順に並べています。 :

+------------+------------------------------------------+----------+
| 演算       | 結果                                     | 注釈     |
+============+==========================================+==========+
| ``x | y``  | ビット単位の *x* と *y* の :dfn:`論理和` |          |
+------------+------------------------------------------+----------+
| ``x ^ y``  | ビット単位の *x* と *y* の               |          |
|            | :dfn:`排他的論理和`                      |          |
+------------+------------------------------------------+----------+
| ``x & y``  | ビット単位の *x* と *y* の :dfn:`論理積` |          |
+------------+------------------------------------------+----------+
| ``x << n`` | *x* の *n* ビット左シフト                | (1)(2)   |
+------------+------------------------------------------+----------+
| ``x >> n`` | *x* の *n* ビット右シフト                | (1)(3)   |
+------------+------------------------------------------+----------+
| ``~x``     | *x* のビット反転                         |          |
+------------+------------------------------------------+----------+

注釈:

(1)
   負値のシフト数は不正であり、 :exc:`ValueError` が送出されます。

(2)
   *n* ビットの左シフトは、 ``pow(2, n)`` による乗算と等価です。結果が
   通常の整数の範囲を越えるときには、長整数が返されます。

(3)
   *n* ビットの右シフトは、 ``pow(2, n)`` による除算と等価です。


整数型に対する追加のメソッド
----------------------------

整数型は :class:`numbers.Integral`  :term:`abstract base class` を実装します。
さらに、追加のメソッドを一つ提供します。

.. method:: int.bit_length()
.. method:: long.bit_length()

    整数を、符号と先頭の 0 は除いて二進法で表すために
    必要なビットの数を返します::

        >>> n = -37
        >>> bin(n)
        '-0b100101'
        >>> n.bit_length()
        6

    正確には、 ``x`` が非 0 なら、 ``x.bit_length()`` は
    ``2**(k-1) <= abs(x) < 2**k`` を満たす唯一の正の整数 ``k`` です。
    同様に、 ``abs(x)`` が十分小さくて対数を適切に丸められるとき、
    ``k = 1 + int(log(abs(x), 2))`` です。
    ``x`` が 0 なら、 ``x.bit_length()`` は ``0`` を返します。

    以下と等価です::

        def bit_length(self):
            s = bin(self)       # binary representation:  bin(-37) --> '-0b100101'
            s = s.lstrip('-0b') # remove leading zeros and minus sign
            return len(s)       # len('100101') --> 6

    .. versionadded:: 2.7


浮動小数点数に対する追加のメソッド
----------------------------------

浮動小数点数型は、 :class:`numbers.Real` 抽象基底クラス
(:term:`abstract base class`)
を実装しています。浮動小数点型はまた、以下の追加のメソッドを持ちます。

.. method:: float.as_integer_ratio()

   比が元の浮動小数点数とちょうど同じで分母が正である、一対の整数を返します。
   無限大に対しては、 :exc:`OverflowError` を、非
   数 (NaN) に対しては :exc:`ValueError` を送出します。

   .. versionadded:: 2.6

.. method:: float.is_integer()

   浮動小数点数インスタンスが有限の整数値なら ``True`` を、
   そうでなければ ``False`` を返します::

      >>> (-2.0).is_integer()
      True
      >>> (3.2).is_integer()
      False

   .. versionadded:: 2.6

16 進表記の文字列へ、または、 16 進表記からの変換をサポートするメ
ソッドは二つあります。 Python の浮動小数点数は内部的には2進数で保持さ
れ、若干の丸め誤差を持って *10進数* へ、または、 *10進数* から変換され
ます。それに対し、 16 進表記では浮動小数点数を、正確に表現することがで
きます。これはデバッグのときや、数学的な用途に便利でしょう。


.. method:: float.hex()

   浮動小数点数の 16 進文字列表現を返します。有限の浮動小数点数に対し、
   この表現は常に ``0x`` で始まり ``p`` と指数が続きます。

   .. versionadded:: 2.6


.. method:: float.fromhex(s)

   16 進文字列表現 *s* で表される、浮動小数点数を返すクラスメソッドで
   す。文字列 *s* は、前や後にホワイトスペースを含んでいても構いません。

   .. versionadded:: 2.6


:meth:`float.fromhex` はクラスメソッドですが、 :meth:`float.hex` はイ
ンスタンスメソッドであることに注意して下さい。

16 進文字列表現は以下の書式となります::

   [符号] ['0x'] 整数部 ['.' 小数部] ['p' 指数部]

``符号`` はオプションで、 ``+`` と ``-`` のどちらでも構いません。
``整数部`` と ``小数部`` は 16 進数の文字列で、 ``指数部`` はオプ
ションで符号がつけられる 10 進数です。大文字・小文字は区別されず、最低
でも 1 つの 16 進数文字を整数部もしくは小数部に含む必要があります。こ
の制限は C99 規格のセクション 6.4.4.2 で規定されます。また、 Java 1.5
以降で使われます。特に、 :meth:`float.hex` は C や Java コード中で、浮
動小数点数の 16 進表記として役に立つでしょう。また、 C の ``%a`` 書式
や、 Java の ``Double.toHexString`` で書きだされた文字列は
:meth:`float.fromhex` で受け取ることができます。


指数部が 16 進数ではなく、 10 進数で書かれ、 2 の累乗となることに注意
して下さい。例えば、 16 進文字列表現 ``0x3.a7p10`` は浮動小数点数
``(3 + 10./16 + 7./16**2) * 2.0**10`` もしくは ``3740.0`` を表します。::

   >>> float.fromhex('0x3.a7p10')
   3740.0


逆変換を ``3740.0`` に適用すると、元とは異なる 16 進文字列表現を返しま
す。::

   >>> float.hex(3740.0)
   '0x1.d380000000000p+11'


.. _typeiter:

イテレータ型
============

.. versionadded:: 2.2

.. index::
   single: iterator protocol
   single: protocol; iterator
   single: sequence; iteration
   single: container; iteration over

Python はコンテナの内容にわたって反復処理を行う概念をサポートしていま
す。この概念は 2 つの別々のメソッドを使って実装されています;
これらのメソッドはユーザ定義のクラスで反復を行えるようにするために使わ
れます。後に詳しく述べるシーケンス型はすべて反復処理メソッドをサポート
しています。

以下はコンテナオブジェクトに反復処理をサポートさせるために定義しなけれ
ばならないメソッドです:

.. XXX duplicated in reference/datamodel!

.. method:: container.__iter__()

   イテレータオブジェクトを返します。イテレータオブジェクトは以下で述
   べるイテレータプロトコルをサポートする必要があります。あるコンテナ
   が異なる形式の反復処理をサポートする場合、それらの反復処理形式のイ
   テレータを特定的に要求するようなメソッドを追加することができます
   (複数の形式での反復処理をサポートするようなオブジェクトとして木構造
   の例があります。木構造は幅優先走査と深さ優先走査の両方をサポートし
   ます)。
   このメソッドは Python/C API において Python オブジェクトを表す型構
   造体の :attr:`tp_iter` スロットに対応します。

イテレータオブジェクト自体は以下の 2 のメソッドをサポートする必要があ
ります。これらのメソッドは 2 つ合わせて :dfn:`イテレータプロトコル` を
成します:


.. method:: iterator.__iter__()

   イテレータオブジェクト自体を返します。このメソッドはコンテナとイテ
   レータの両方を :keyword:`for` および :keyword:`in` 文で使えるように
   するために必要です。このメソッドは Python/C API において Python オ
   ブジェクトを表す型構造体の :attr:`tp_iter` スロットに対応します。


.. method:: iterator.next()

   コンテナ内の次の要素を返します。もう要素が残っていない場合、例外
   :exc:`StopIteration` を送出します。このメソッドは Python/C API にお
   いて Python オブジェクトを表す型構造体の :attr:`tp_iternext` スロッ
   トに対応します。

Python では、いくつかのイテレータオブジェクトを定義しています。これら
は一般的および特殊化されたシーケンス型、辞書型、そして他のさらに特殊化
された形式をサポートします。特殊型であることはイテレータプロトコルの実
装が特殊になること以外は重要なことではありません。

このプロトコルの趣旨は、一度イテレータの :meth:`next` メソッドが
:exc:`StopIteration` 例外を送出した場合、以降の呼び出しでもずっと例外
を送出しつづけるところにあります。この特性に従わないような実装は変則で
あるとみなされます (この制限は Python 2.3 で追加されました; Python 2.2
では、この規則に従うと多くのイテレータが変則となります)。

.. _generator-types:

ジェネレータ型
--------------

Python における :term:`generator` (ジェネレータ) は、イテレータプロト
コルを実装する簡便な方法を提供します。コンテナオブジェクトの
:meth:`__iter__` メソッドがジェネレータとして実装されていれば、メソッ
ドは :meth:`__iter__` および :meth:`next` メソッドを提供するイテレータ
オブジェクト (技術的にはジェネレータオブジェクト) を自動的に返します。
:ref:`yield 式についてのドキュメント <yieldexpr>` に
より多くの情報があります。

.. _typesseq:

シーケンス型 --- :class:`str`, :class:`unicode`, :class:`list`, :class:`tuple`, :class:`bytearray`, :class:`buffer`, :class:`xrange`
====================================================================================================================================

シーケンス型には 7 つあります: 文字列、Unicode 文字列、リスト、タプル、
、バイト配列 (bytearray)、バッファ、
そして xrange オブジェクトです。

他のコンテナ型については、組み込みクラスの :class:`dict` および
:class:`set` を参照下さい。

.. index::
   object: sequence
   object: string
   object: Unicode
   object: tuple
   object: list
   object: bytearray
   object: buffer
   object: xrange

文字列リテラルは ``'xyzzy'`` , ``"frobozz"`` といったように、単引用符
または二重引用符の中に書かれます。
文字列リテラルについての詳細は、 :ref:`strings` を参照下さい。
Unicode 文字列はほとんど文字列と同じですが、 ``u'abc'`` , ``u"def"``
といったように先頭に文字 ``'u'`` を付けて指定します。リストは ``[a, b,
c]`` のように要素をコンマで区切り角括弧で囲って生成します。
タプルは ``a, b, c`` のようにコンマ演算子で区切って生成します (角括弧
の中には入れません)。丸括弧で囲っても囲わなくてもかまいませんが、空の
タプルは  ``()`` のように丸括弧で囲わなければなりません。要素が一つの
タプルでは、例えば ``(d,)`` のように、要素の後ろにコンマをつけなけれ
ばなりません。

バイト配列は、組み込み関数 :func:`bytearray` で構成されます。

バッファオブジェクトは Python の構文上では直接サポートされていませんが、
組み込み関数 :func:`buffer` で生成することができます。バッファオブジェ
クトは結合や反復をサポートしていません。

xrange オブジェクトは、オブジェクトを生成するための特殊な構文がない点
でバッファに似ていて、関数 :func:`xrange` で生成します。
xrange オブジェクトはスライス、結合、反復をサポートせず、 ``in`` ,
``not in`` , :func:`min` または :func:`max` は効率的ではありません。

ほとんどのシーケンス型は以下の演算操作をサポートします。 ``in`` および
``not in`` は比較演算とおなじ優先度を持っています。 ``+`` および ``*``
は対応する数値演算とおなじ優先度です。
[#]_ :ref:`typesseq-mutable` で追加のメソッドが提供されています。


以下のテーブルはシーケンス型の演算を優先度の低いものから順に挙げたもの
です (同じボックス内の演算は同じ優先度です)。テーブル内の *s* および
*t* は同じ型のシーケンスです; *n* , *i* および *j* は整数です:

+------------------+---------------------------------------------+----------+
| 演算             | 結果                                        | 注釈     |
+==================+=============================================+==========+
| ``x in s``       | *s* のある要素 *x* と等しい場合 ``True``    | \(1)     |
|                  | , そうでない場合 ``False``                  |          |
+------------------+---------------------------------------------+----------+
| ``x not in s``   | *s* のある要素が *x* と等しい場合           | \(1)     |
|                  | ``False``,  そうでない場合 ``True``         |          |
+------------------+---------------------------------------------+----------+
| ``s + t``        | *s* および *t* の結合                       | \(6)     |
+------------------+---------------------------------------------+----------+
| ``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* の最大の要素                            |          |
+------------------+---------------------------------------------+----------+
| ``s.index(i)``   | *s* 中で最初に *i* が現れる場所のインデクス |          |
+------------------+---------------------------------------------+----------+
| ``s.count(i)``   | *s* 中に *i* が現れる数                     |          |
+------------------+---------------------------------------------+----------+

シーケンス型は比較演算子もサポートします。特にタプルとリストは相当する
要素による辞書編集方式的に比較されます。つまり、等しいということは、ふ
たつのシーケンスの長さ、型が同じであり、全ての要素が等しいということで
す (詳細は言語リファレンスの :ref:`comparisons` を参照下さい) 。

.. index::
   triple: operations on; sequence; types
   builtin: len
   builtin: min
   builtin: max
   pair: concatenation; operation
   pair: repetition; operation
   pair: subscript; operation
   pair: slice; operation
   pair: extended slice; operation
   operator: in
   operator: not in

注釈:

(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つのコピーを要素とするリストです。
   しかし、リスト内の要素に含まれているリストは各コピー間で共有されて
   います。以下のようにすると、異なるリストを要素とするリストを生成で
   きます:
   上のコードで、 ``[[]]`` は空のリストを要素として含んでいるリストで
   すから、 ``[[]] * 3`` の3つの要素の全てが、空のリスト（への参照）に
   なります。 ``lists`` のいずれかの要素を修正することでこの単一のリス
   トが変更されます。以下のようにすると、異なる個別のリストを生成でき
   ます:

      >>> 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* が省略されるか ``None`` だった場合、 ``0`` を使います。 *j* が
   省略されるか ``None`` だった場合、 ``len(s)`` を使います。
   *i* が *j* 以上の場合、スライスは空のシーケンスになります。

(5)
   *s* の *i* 番目から *j* 番目まで  *k* 毎のスライスは、 ``0 <= n <
   (j-i)/k`` となるような、インデクス ``x = i + n*k`` を持つ要素からな
   るシーケンスとして定義されます。言い換えるとインデクスは ``i``,
   ``i+k``, ``i+2*k``, ``i+3*k`` などであり、 *j* に達したところ
   (しかし *j* は含みません)でストップします。 *i* または *j* が
   ``len(s)`` より大きい場合、 ``len(s)`` を使います。 *i* または *j*
   を省略するか ``None`` だった場合、"最後" (*k* の符号に依存) を示す
   値を使います。 *k* はゼロにできないので注意してください。 *k* が
   ``None`` だった場合、 ``1`` として扱われます。

(6)
   .. impl-detail::

      *s* と *t* の両者が文字列であるとき、
      CPython のような実装では、 ``s=s+t`` や ``s+=t`` という書式で
      代入をするのに in-place optimization が働きます。
      このような時、最適化は二乗の実行時間の低減をもたらします。
      この最適化はバージョンや実装に依存します。
      実行効率が必要なコードでは、バージョンと実装が変わっても、
      直線的な連結の実行効率を保証する :meth:`str.join` を使うのが
      より望ましいでしょう。

   .. versionchanged:: 2.4
      以前、文字列の連結はin-placeで再帰されませんでした.


.. _string-methods:

文字列メソッド
--------------

.. index:: pair: string; methods

Below ar8-bit 文字列と Unicode オブジェクトは、どちらも以下に挙げるメソッドに
対応しています。この中には、 :class:`bytearray` オブジェクトで使えるものも
あります。

さらに、 Python の文字列は :ref:`typesseq` に記載されるシーケンス型の
メソッドもサポートします。
書式指定して文字列を出力するためには、テンプレート文字列を使うか、
:ref:`string-formatting` に記載される ``%`` 演算子を使います。
正規表現に基づく文字列操作関数については、 :mod:`re` モジュールを参照
下さい。

.. method:: str.capitalize()

   最初の文字のみを大文字にした文字列のコピーを返します。

   8ビット文字列では、メソッドはロケール依存になります。


.. method:: str.center(width[, fillchar])

   *width* の長さをもつ中央寄せされた文字列を返します。パディングには
   *fillchar* で指定された値 (デフォルトではスペース) が使われます。

   .. versionchanged:: 2.4
      引数 *fillchar* に対応.


.. method:: str.count(sub[, start[, end]])

   [*start*, *end*] の範囲に、部分文字列 *sub* が出現する回数を返しま
   す。オプション引数 *start* および *end* はスライス表記と同じように
   解釈されます。


.. method:: str.decode([encoding[, errors]])

   codec に登録された文字コード系 *encoding* を使って文字列をデコード
   します。 *encoding* は標準でデフォルトの文字列エンコーディングにな
   ります。標準とは異なるエラー処理を行うために *errors* を与えること
   ができます。標準のエラー処理は ``'strict'`` で、エンコードに関する
   エラーは :exc:`UnicodeError` を送出します。他に利用できる値は
   ``'ignore'``, ``'replace'`` および関数
   :func:`codecs.register_error` によって登録された名前です。これにつ
   いてはセクション :ref:`codec-base-classes` 節を参照してください。

   .. versionadded:: 2.2

   .. versionchanged:: 2.3
      その他のエラーハンドリングスキーマがサポートされました.

   .. versionchanged:: 2.7
      キーワード引数のサポートが追加されました。

.. method:: str.encode([encoding[,errors]])

   文字列のエンコードされたバージョンを返します。標準のエンコーディン
   グは現在のデフォルト文字列エンコーディングです。標準とは異なるエラー
   処理を行うために *errors* を与えることができます。標準のエラー処理
   は ``'strict'`` で、エンコードに関するエラーは :exc:`UnicodeError`
   を送出します。他に利用できる値は ``'ignore'``, ``'replace'``,
   ``'xmlcharrefreplace'``, ``'backslashreplace'`` および関数
   :func:`codecs.register_error` によって登録された名前です。これにつ
   いてはセクション :ref:`codec-base-classes` を参照してください。利用
   可能なエンコーディングの一覧は、セクション
   :ref:`standard-encodings` を参照してください。

   .. versionadded:: 2.0

   .. versionchanged:: 2.3
      ``'xmlcharrefreplace'``, ``'backslashreplace'``
      およびその他のエラーハンドリングスキーマがサポートされました.


.. method:: str.endswith(suffix[, start[, end]])

   文字列の一部が *suffix* で終わるときに ``True`` を返します。そうで
   ない場合 ``False`` を返します。 *suffix* は見つけたい複数の接尾語の
   タプルでも構いません。オプション引数 *start* がある場合、文字列の
   *start* から比較を始めます。 *end* がある場合、文字列の *end* で比
   較を終えます。

   .. versionchanged:: 2.5
      *suffix* でタプルを受け付けるようになりました.


.. method:: str.expandtabs([tabsize])

   カラム数と与えられるタブサイズに依存し、全てのタブ文字をひとつ以上の
   空白で置換して文字列のコピーを返します。カラム数は文字列中に改行文
   字が現れる度に 0 にリセットされます。他の非表示文字や制御文字は解釈
   しません。


.. method:: str.find(sub[, start[, end]])

   文字列のスライス ``s[start, end]`` に *sub* が含まれる場合、その最小の
   インデクスを返します。オプション引数 *start* および *end* はスライ
   ス表記と同様に解釈されます。 *sub* が見つからなかった場合 ``-1``
   を返します。

   .. note::

      :meth:`~str.find` メソッドは、 *sub* の位置を知りたいときにのみ
      使うべきです。 *sub* が部分文字列であるかどうかのみを調べるには、
      :keyword:`in` 演算子を使ってください::

         >>> 'Py' in 'Python'
         True

.. method:: str.format(*args, **kwargs)

   文字列の書式操作を行います。このメソッドを呼び出す文字列は通常の文字、
   または、 ``{}`` で区切られた置換フィールドを含みます。
   それぞれの置換フィールドは位置引数のインデックスナンバー、
   または、キーワード引数の名前を含みます。
   返り値は、引数に応じて置換されたあとの文字列のコピーです。

      >>> "The sum of 1 + 2 is {0}".format(1+2)
      'The sum of 1 + 2 is 3'

   書式指定のオプションについては、書式指定文字列を規定する
   :ref:`formatstrings` を参照下さい。

   この文字列書式指定のメソッドは Python 3.0 での新しい標準であり、
   新しいコードでは、 :ref:`string-formatting` で規定される ``%`` を使っ
   た書式指定より好ましい書き方です。

   .. versionadded:: 2.6


.. method:: str.index(sub[, start[, end]])

   :meth:`find` と同様ですが、 *sub* が見つからなかった場合
   :exc:`ValueError` を送出します。


.. method:: str.isalnum()

   文字列中の全ての文字が英数文字で、かつ 1 文字以上ある場合には真を返
   し、そうでない場合は偽を返します。

   8 ビット文字列では、メソッドはロケール依存になります。


.. method:: str.isalpha()

   文字列中の全ての文字が英文字で、かつ 1 文字以上ある場合には真を返し、
   そうでない場合は偽を返します。

   8 ビット文字列では、メソッドはロケール依存になります。


.. method:: str.isdigit()

   文字列中に数字しかない場合には真を返し、その他の場合は偽を返します。

   8 ビット文字列では、メソッドはロケール依存になります。


.. method:: str.islower()

   文字列中の大小文字の区別のある文字全てが小文字で、かつ 1 文字以上あ
   る場合には真を返し、そうでない場合は偽を返します。

   8 ビット文字列では、メソッドはロケール依存になります。


.. method:: str.isspace()

   文字列が空白文字だけからなり、かつ 1 文字以上ある場合には真を返し、
   そうでない場合は偽を返します。

   8 ビット文字列では、メソッドはロケール依存になります。


.. method:: str.istitle()

   文字列がタイトルケース文字列であり、かつ 1 文字以上ある場合、例えば
   大文字は大小文字の区別のない文字の後にのみ続き、小文字は大小文字の
   区別のある文字の後ろにのみ続く場合には真を返します。そうでない場合
   は偽を返します。

   8 ビット文字列では、メソッドはロケール依存になります。


.. method:: str.isupper()

   文字列中の大小文字の区別のある文字全てが大文字で、かつ 1 文字以上あ
   る場合には真を返し、そうでない場合は偽を返します。

   8 ビット文字列では、メソッドはロケール依存になります。


.. method:: str.join(iterable)

   :term:`iterable` *iterable* 中の文字列を結合した文字列を返します。文字列を結合
   するときの区切り文字は、このメソッドを適用する対象の文字列になりま
   す。


.. method:: str.ljust(width[, fillchar])

   *width* の長さをもつ左寄せした文字列を返します。パディングには
   *fillchar* で指定された文字(デフォルトではスペース)が使われます。
   *width* が ``len(s)`` よりも小さい場合、元の文字列が返されます。

   .. versionchanged:: 2.4
      引数 *fillchar* が追加されました.


.. method:: str.lower()

   文字列をコピーし、小文字に変換して返します。

   8 ビット文字列では、メソッドはロケール依存になります。


.. method:: str.lstrip([chars])

   文字列の先頭部分を除去したコピーを返します。引数 *chars* は除去され
   る文字集合を指定する文字列です。 *chars* が省略されるか ``None`` の
   場合、空白文字が除去されます。 *chars* 文字列は接頭語ではなく、そこ
   に含まれる文字の組み合わせ全てがはぎ取られます。:

      >>> '   spacious   '.lstrip()
      'spacious   '
      >>> 'www.example.com'.lstrip('cmowz.')
      'example.com'

   .. versionchanged:: 2.2.2
      引数 *chars* をサポートしました.


.. method:: str.partition(sep)

   文字列を *sep* の最初の出現位置で区切り、 3 要素のタプルを返します。
   タプルの内容は、区切りの前の部分、区切り文字列そのもの、そして区切
   りの後ろの部分です。もし区切れなければ、タプルには元の文字列そのも
   のとその後ろに二つの空文字列が入ります。

   .. versionadded:: 2.5


.. method:: str.replace(old, new[, count])

   文字列をコピーし、部分文字列 *old* のある部分全てを *new* に置換し
   て返します。オプション引数 *count* が与えられている場合、先頭から
   *count* 個の *old* だけを置換します。


.. method:: str.rfind(sub [,start [,end]])

   文字列中の領域 ``s[start, end]`` に *sub* が含まれる場合、
   その最大のインデクスを返します。
   オプション引数 *start* および *end* はスライス表記と同様に解釈されます。
   *sub* が見つからなかった場合 ``-1``  を返します。


.. method:: str.rindex(sub[, start[, end]])

   :meth:`rfind` と同様ですが、 *sub* が見つからなかった場合
   :exc:`ValueError` を送出します。


.. method:: str.rjust(width[, fillchar])

   *width* の長さをもつ右寄せした文字列を返します。パディングには
   *fillchar* で指定された文字(デフォルトではスペース)が使われます。
   *width* が ``len(s)`` よりも小さい場合、元の文字列が返されます。

   .. versionchanged:: 2.4
      引数 *fillchar* が追加されました.


.. method:: str.rpartition(sep)

   文字列を *sep* の最後の出現位置で区切り、 3 要素のタプルを返します。
   タプルの内容は、区切りの前の部分、区切り文字列そのもの、そして区切
   りの後ろの部分です。もし区切れなければ、タプルには二つの空文字列と
   その後ろに元の文字列そのものが入ります。

   .. versionadded:: 2.5


.. method:: str.rsplit([sep [,maxsplit]])

   *sep* を区切り文字とした、文字列中の単語のリストを返します。
   *maxsplit* が与えられた場合、最大で *maxsplit* 個になるように分割が
   行なわれます、 *最も右側* (の単語)は 1 つになります。 *sep* が指定
   されていない、あるいは ``None`` のとき、全ての空白文字が区切り文字
   となります。右から分割していくことを除けば、 :meth:`rsplit` は後ほ
   ど詳しく述べる :meth:`split` と同様に振る舞います。

   .. versionadded:: 2.4


.. method:: str.rstrip([chars])

   文字列の末尾部分を除去したコピーを返します。引数 *chars* は除去され
   る文字集合を指定する文字列です。 *chars* が省略されるか ``None`` の
   場合、空白文字が除去されます。 *chars* 文字列は接尾語ではなく、そこ
   に含まれる文字の組み合わせ全てがはぎ取られます。:

      >>> '   spacious   '.rstrip()
      '   spacious'
      >>> 'mississippi'.rstrip('ipz')
      'mississ'

   .. versionchanged:: 2.2.2
      引数 *chars* をサポートしました.


.. method:: str.split([sep [,maxsplit]])

   *sep* を単語の境界として文字列を単語に分割し、分割された単語からな
   るリストを返します。 *maxsplit* が与えられた場合、最大で *maxsplit*
   回の分割が行われます (したがって返されるリストは ``maxsplit+1`` の要
   素を持ちます) 。
   *maxsplit* が指定されない場合、無制限に分割が行なわれます(全ての可
   能な分割が行なわれる)。

   *sep* が与えられた場合、連続した区切り文字はグループ化されず、空の
   文字列を区切っていると判断されます(例えば ``'1,,2'.split(',')`` は
   ``['1', '', '2']`` を返します)。引数 *sep* は複数の文字にもできます
   (例えば ``'1<>2<>3'.split('<>')`` は ``['1', '2', '3']`` を返します)。
   区切り文字を指定して空の文字列を分割すると、 ``['']`` を返します。

   *sep* が指定されていないか ``None`` が指定されている場合、異なる分割
   アルゴリズムが適用されます。:
   連続する空白文字はひとつの分割子とみなされます。そして、分割対象の
   文字列の先頭、または、末尾に空白文字があっても、分割結果の最初、ま
   たは、最後に空文字列を含みません。空文字列や、空白文字だけからなる
   文字列を ``None`` 分割子で分割すると ``[]`` が返されます。

   例えば、 ``' 1  2   3  '.split()`` は ``['1', '2', '3']`` を返し、
   ``'  1  2   3  '.split(None, 1)`` は ``['1', '2   3  ']`` を返しま
   す。


.. method:: str.splitlines([keepends])

   文字列を改行部分で分解し、各行からなるリストを返します。 *keepends*
   が与えられていて、かつその値が真でない限り、返されるリストには改行
   文字は含まれません。

   8 ビット文字列では、メソッドはロケール依存になります。


.. method:: str.startswith(prefix[, start[, end]])

   文字列の一部が *prefix* で始まるときに ``True`` を返します。そうで
   ない場合 ``False`` を返します。 *prefix* は複数の接頭語のタプルにし
   ても構いません。オプション引数 *start* がある場合、文字列の *start*
   から比較を始めます。 *end* がある場合、文字列の *end* で比較を終え
   ます。

   .. versionchanged:: 2.5
      *prefix* でタプルを受け付けるようになりました.


.. method:: str.strip([chars])

   文字列の先頭および末尾部分を除去したコピーを返します。引数 *chars*
   は除去される文字集合を指定する文字列です。 *chars* が省略されるか
   ``None`` の場合、空白文字が除去されます。 *chars* 文字列は接頭語で
   も接尾語でもなく、そこに含まれる文字の組み合わせ全てがはぎ取られます。:

      >>> '   spacious   '.strip()
      'spacious'
      >>> 'www.example.com'.strip('cmowz.')
      'example'

   .. versionchanged:: 2.2.2
      引数 *chars* をサポートしました.


.. method:: str.swapcase()

   文字列をコピーし、大文字は小文字に、小文字は大文字に変換して返します。

   8 ビット文字列では、メソッドはロケール依存になります。


.. method:: str.title()

   文字列を、単語ごとに大文字から始まり、
   残りの文字のうち大小文字の区別があるものは全て小文字にする、
   タイトルケースにして返します。

   このアルゴリズムは単語の定義として連続した文字列の集まり
   という単純な言語によってはうまくいかない定義を使います。
   この定義は多くの状況ではうまく機能しますが、
   短縮形や所有格のアポストロフィは単語の境界を形成してしまうため、
   望みの結果を得られない場合があります。

        >>> "they're bill's friends from the UK".title()
        "They'Re Bill'S Friends From The Uk"

   正規表現を使うことでアポストロフィに対応することができます。

        >>> import re
        >>> def titlecase(s):
                return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
                              lambda mo: mo.group(0)[0].upper() +
                                         mo.group(0)[1:].lower(),
                              s)

        >>> titlecase("they're bill's friends.")
        "They're Bill's Friends."

   8 ビット文字列では、メソッドはロケール依存になります。


.. method:: str.translate(table[, deletechars])

   文字列をコピーし、オプション引数の文字列 *deletechars* の中に含まれ
   る文字を全て除去します。その後、残った文字を変換テーブル *table* に
   従ってマップして返します。変換テーブルは長さ 256 の文字列でなければ
   なりません。

   トランスレーションテーブル作成のために、 :mod:`string` モジュールの
   :func:`~string.maketrans` 補助関数を使うこともできます。
   文字列型オブジェクトに対しては、 *table* 引数に ``None`` を与えるこ
   とで、文字の削除だけを実施します。:

      >>> 'read this short text'.translate(None, 'aeiou')
      'rd ths shrt txt'

   .. versionadded:: 2.6
      ``None`` の *table* 引数をサポートしました。

   Unicode オブジェクトの場合、 :meth:`translate` メソッドはオプション
   の *deletechars* 引数を受理しません。その代わり、メソッドはすべての
   文字が与えられた変換テーブルで対応付けされている *s* のコピーを返し
   ます。この変換テーブルは Unicode 順 (ordinal) から Unicode 順、
   Unicode 文字列、または ``None`` への対応付けでなくてはなりません。
   対応付けされていない文字は何もせず放置されます。 ``None`` に対応付
   けられた文字は削除されます。ちなみに、より柔軟性のあるアプローチは、
   自作の文字対応付けを行う codec を :mod:`codecs` モジュールを使って
   作成することです  (例えば :mod:`encodings.cp1251` を参照してください。)


.. method:: str.upper()

   文字列をコピーし、大文字に変換して返します。

   8ビット文字列では、メソッドはロケール依存になります。


.. method:: str.zfill(width)

   数値文字列の左側をゼロ詰めし、幅 *width* にして返します。符号接頭辞
   も正しく扱われます。 *width* が ``len(s)`` よりも短い場合もとの文字
   列自体が返されます。

   .. versionadded:: 2.2.2


以下のメソッドは、 Unicode オブジェクトにのみ実装されます:

.. method:: unicode.isnumeric()

   数字を表す文字のみで構成される場合、 ``True`` を返します。それ以外
   の場合は ``False`` を返します。
   数字を表す文字には、 0 から 9 までの数字と、 Unicode の数字プロパティ
   を持つ全ての文字が含まれます。 (e.g. U+2155, VULGAR FRACTION ONE
   FIFTH)


.. method:: unicode.isdecimal()

   10 進数文字のみで構成される場合、 ``True`` を返します。それ以外の場
   合は、 ``False`` を返します。 10 進数文字には 0 から 9 までの数字と、
   10 進基数表記に使われる全ての文字が含まれます。 (e.g. U+0660,
   ARABIC-INDIC DIGIT ZERO)


.. _string-formatting:

文字列フォーマット操作
----------------------

.. index::
   single: formatting, string (%)
   single: interpolation, string (%)
   single: string; formatting
   single: string; interpolation
   single: printf-style formatting
   single: sprintf-style formatting
   single: % formatting
   single: % interpolation

文字列および Unicode オブジェクトには固有の操作: ``%`` 演算子 (モジュ
ロ) があります。この演算子は文字列 *フォーマット化* または *補間* 演算
としても知られています。 ``format % values`` (*format* は文字列または
Unicode オブジェクト) とすると、 *format* 中の ``%`` 変換指定は
*values* 中のゼロ個またはそれ以上の要素で置換されます。この動作は C
言語における :c:func:`sprintf` に似ています。 *format* が Unicode オブ
ジェクトであるか、または ``%s``  変換を使って Unicode オブジェクトが変
換される場合、その結果も Unicode オブジェクトになります。

*format* が単一の引数しか要求しない場合、 *values* はタプルでない単一
のオブジェクトでもかまいません。 [#]_
それ以外の場合、 *values* はフォーマット文字列中で指定された項目と正確
に同じ数の要素からなるタプルか、単一のマップオブジェクトでなければなり
ません。

一つの変換指定子は 2 またはそれ以上の文字を含み、その構成要素は以下か
らなりますが、示した順に出現しなければなりません:

#. 変換指定子が開始することを示す文字 ``'%'`` 。

#. マップキー (オプション)。丸括弧で囲った文字列からなります (例えば
   ``(someone)``) 。

#. 変換フラグ (オプション)。一部の変換型の結果に影響します。

#. 最小のフィールド幅 (オプション)。 ``'*'`` (アスタリスク) を指定した
   場合、実際の文字列幅が *values* タプルの次の要素から読み出されます。
   タプルには最小フィールド幅やオプションの精度指定の後に変換したいオブ
   ジェクトがくるようにします。

#. 精度 (オプション)。 ``'.'`` (ドット) とその後に続く精度で与えられま
   す。 ``'*'`` (アスタリスク) を指定した場合、精度の桁数はタプルの次
   の要素から読み出されます。タプルには精度指定の後に変換したい値がく
   るようにします。

#. 精度長変換子 (オプション)。

#. 変換型。

``%`` 演算子の右側の引数が辞書の場合 (またはその他のマップ型の場合),
文字列中のフォーマットには、辞書に挿入されているキーを丸括弧で囲い、文
字 ``'%'`` の直後にくるようにしたものが含まれていなければ *なりません*
。マップキーはフォーマット化したい値をマップから選び出します。例えば:

   >>> print '%(language)s has %(number)03d quote types.' % \
   ...       {"language": "Python", "number": 2}
   Python has 002 quote types.

この場合、 ``*`` 指定子をフォーマットに含めてはいけません (``*`` 指定
子は順番付けされたパラメタのリストが必要だからです。)

変換フラグ文字を以下に示します:

+---------+---------------------------------------------------------------------+
| フラグ  | 意味                                                                |
+=========+=====================================================================+
| ``'#'`` | 値の変換に (下で定義されている) "別の形式" を使います。             |
+---------+---------------------------------------------------------------------+
| ``'0'`` | 数値型に対してゼロによるパディングを行います。                      |
+---------+---------------------------------------------------------------------+
| ``'-'`` | 変換された値を左寄せにします (``'0'`` と同時に与えた場合、 ``'0'``  |
|         | を上書きします) 。                                                  |
+---------+---------------------------------------------------------------------+
| ``' '`` | (スペース) 符号付きの変換で正の数の場合、前に一つスペースを空けます |
|         | (そうでない場合は空文字になります)  。                              |
+---------+---------------------------------------------------------------------+
| ``'+'`` | 変換の先頭に符号文字 (``'+'`` または ``'-'``) を付けます("スペース" |
|         | フラグを上書きします) 。                                            |
+---------+---------------------------------------------------------------------+

精度長変換子(``h``, ``l``,または ``L``) を使うことができますが、
Python では必要ないため無視されます。 -- つまり、例えば ``%ld`` は
``%d`` と等価です。

変換型を以下に示します:

+---------+-----------------------------------------------------------+------+
| 変換    | 意味                                                      | 注釈 |
+=========+===========================================================+======+
| ``'d'`` | 符号付き 10 進整数。                                      |      |
+---------+-----------------------------------------------------------+------+
| ``'i'`` | 符号付き 10 進整数。                                      |      |
+---------+-----------------------------------------------------------+------+
| ``'o'`` | 符号なし 8 進数。                                         | \(1) |
+---------+-----------------------------------------------------------+------+
| ``'u'`` | 符号なし 10 進数。                                        |      |
+---------+-----------------------------------------------------------+------+
| ``'x'`` | 符号なし 16 進数 (小文字)。                               | \(2) |
+---------+-----------------------------------------------------------+------+
| ``'X'`` | 符号なし 16 進数 (大文字)。                               | \(2) |
+---------+-----------------------------------------------------------+------+
| ``'e'`` | 指数表記の浮動小数点数 (小文字)。                         | \(3) |
+---------+-----------------------------------------------------------+------+
| ``'E'`` | 指数表記の浮動小数点数 (大文字)。                         | \(3) |
+---------+-----------------------------------------------------------+------+
| ``'f'`` | 10 進浮動小数点数。                                       | \(3) |
+---------+-----------------------------------------------------------+------+
| ``'F'`` | 10 進浮動小数点数。                                       | \(3) |
+---------+-----------------------------------------------------------+------+
| ``'g'`` | 浮動小数点数。指数部が -4 以上または精度以下の場合には    | \(4) |
|         | 指数表記、それ以外の場合には10進表記。                    |      |
+---------+-----------------------------------------------------------+------+
| ``'G'`` | 浮動小数点数。指数部が -4 以上または精度以下の場合には    | \(4) |
|         | 指数表記、それ以外の場合には10進表記。                    |      |
+---------+-----------------------------------------------------------+------+
| ``'c'`` | 文字一文字 (整数または一文字からなる文字列を受理します)。 |      |
+---------+-----------------------------------------------------------+------+
| ``'r'`` | 文字列 (Python オブジェクトを                             | \(5) |
|         | :func:`repr` で変換します)。                              |      |
+---------+-----------------------------------------------------------+------+
| ``'s'`` | 文字列 (Python オブジェクトを :func:`str`                 | \(6) |
|         | で変換します)。                                           |      |
+---------+-----------------------------------------------------------+------+
| ``'%'`` | 引数を変換せず、返される文字列中では文字 ``'%'``          |      |
|         | になります。                                              |      |
+---------+-----------------------------------------------------------+------+

注釈:

(1)
   この形式の出力にした場合、変換結果の先頭の数字がゼロ (``'0'``)  で
   ないときには、数字の先頭と左側のパディングとの間にゼロを挿入します。

(2)
   この形式にした場合、変換結果の先頭の数字がゼロでないときには、数字
   の先頭と左側のパディングとの間に ``'0x'`` または ``'0X'``
   (フォーマット文字が ``'x'`` か ``'X'`` かに依存します) が挿入されます。

(3)
   この形式にした場合、変換結果には常に小数点が含まれ、それはその後ろ
   に数字が続かない場合にも適用されます。

   指定精度は小数点の後の桁数を決定し、そのデフォルトは 6 です。

(4)
   この形式にした場合、変換結果には常に小数点が含まれ他の形式とは違っ
   て末尾の 0 は取り除かれません。

   指定精度は小数点の前後の有効桁数を決定し、そのデフォルトは 6 です。

(5)
   ``%r`` 変換は Python 2.0 で追加されました。

   指定精度は最大文字数を決定します。

(6)
   オブジェクトや与えられた書式が :class:`unicode` 文字列の場合、変換
   後の文字列も :class:`unicode` になります。

   指定精度は最大文字数を決定します。

(7)
   :pep:`237` を参照してください。

   Python 文字列には明示的な長さ情報があるので、 ``%s`` 変換において
   ``'\0'`` を文字列の末端と仮定したりはしません。

.. XXX Examples?

.. versionchanged:: 2.7
   絶対値が 1e50 を超える数の ``%f`` 変換は、 ``%g`` による変換に
   置き換えられなくなりました。

.. index::
   module: string
   module: re

その他の文字列操作は標準モジュール :mod:`string`  および :mod:`re` で
定義されています。


.. _typesseq-xrange:

XRange 型
---------

.. index:: object: xrange

:class:`xrange` 型は値の変更不能なシーケンスで、広範なループ処理に使わ
れています。 :class:`xrange` 型の利点は、 :class:`xrange` オブジェクト
は表現する値域の大きさにかかわらず常に同じ量のメモリしか占めないという
ことです。
はっきりしたパフォーマンス上の利点はありません。

XRange オブジェクトは非常に限られた振る舞い、すなわち、インデクス検索、
反復、 :func:`len` 関数のみをサポートしています。


.. _typesseq-mutable:

変更可能なシーケンス型
----------------------

.. index::
   triple: mutable; sequence; types
   object: list

リストとバイト配列 (:class:`bytearray`) オブジェクトは、
オブジェクトをインプレースに変更できるように
する追加の操作をサポートします。他のミュータブルなシーケンス型
(を言語に追加するとき) も、それらの操作をサポートするべきです。
文字列およびタプルはイミュータブルなシーケンス型です:
これらのオブジェクトは一度生成されたら変更できません。
ミュータブルなシーケンス型では以下の操作が定義されています
(ここで *x* は任意のオブジェクトとします)。

.. index::
   triple: operations on; sequence; types
   triple: operations on; list; type
   pair: subscript; assignment
   pair: slice; assignment
   pair: extended slice; assignment
   statement: del
   single: append() (list method)
   single: extend() (list method)
   single: count() (list method)
   single: index() (list method)
   single: insert() (list method)
   single: pop() (list method)
   single: remove() (list method)
   single: reverse() (list method)
   single: sort() (list method)

+------------------------------+--------------------------------------------+---------------------+
| 操作                         | 結果                                       | 注釈                |
+==============================+============================================+=====================+
| ``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``          | \(4)                |
|                              | となる最小の *k* を返します。              |                     |
+------------------------------+--------------------------------------------+---------------------+
| ``s.insert(i, x)``           | ``i >= 0`` の場合の ``s[i:i] =             | \(5)                |
|                              | [x]`` と同じです                           |                     |
+------------------------------+--------------------------------------------+---------------------+
| ``s.pop([i])``               | ``x = s[i]; del s[i]; return               | \(6)                |
|                              | x`` と同じです                             |                     |
+------------------------------+--------------------------------------------+---------------------+
| ``s.remove(x)``              | ``del s[s.index(x)]`` と同じです           | \(4)                |
+------------------------------+--------------------------------------------+---------------------+
| ``s.reverse()``              | *s* の値の並びを反転します                 | \(7)                |
+------------------------------+--------------------------------------------+---------------------+
| ``s.sort([cmp[, key[,        | *s* の要素を並べ替えます                   | (7), (8), (9), (10) |
| reverse]]])``                |                                            |                     |
+------------------------------+--------------------------------------------+---------------------+

Notes:

(1)
   *t* は入れ替えるスライスと同じ長さでなければいけません。

(2)
   かつての Python の C 実装では、複数パラメタを受理し、非明示的にそれ
   らをタプルに結合していました。この間違った機能は Python 1.4 で廃用
   され、 Python 2.0 の導入とともにエラーにするようになりました。

(3)
   *x* は任意のイテラブル (繰り返し可能オブジェクト) にできます。

(4)
   *x* が *s* 中に見つからなかった場合 :exc:`ValueError` を送出します。
   負のインデクスが二番目または三番目のパラメタとして :meth:`index` メ
   ソッドに渡されると、これらの値にはスライスのインデクスと同様にリス
   トの長さが加算されます。加算後もまだ負の場合、その値はスライスのイ
   ンデクスと同様にゼロに切り詰められます。

   .. versionchanged:: 2.3
      以前は、 :meth:`index` は開始位置や終了位置を指定するのに負の数
      を使うことができませんでした。

(5)
   :meth:`insert`
   の最初のパラメタとして負のインデクスが渡された場合、スライスのイン
   デクスと同じく、リストの長さが加算されます。それでも負の値を取る場
   合、スライスのインデクスと同じく、 0 に丸められます。

   .. versionchanged:: 2.3
      以前は、すべての負値は 0 に丸められていました。

(6)
   :meth:`pop` メソッドはリストおよびアレイ型のみでサポートされていま
   す。オプションの引数 *i* は標準で ``-1`` なので、標準では最後の要素
   をリストから除去して返します。

(7)
   :meth:`sort` および :meth:`reverse` メソッドは大きなリストを並べ替
   えたり反転したりする際、容量の節約のためにリストを直接変更します。
   副作用があることをユーザに思い出させるために、これらの操作は並べ替
   えまたは反転されたリストを返しません。

(8)
   :meth:`sort` メソッドは、比較を制御するためにオプションの引数をとり
   ます。

   *cmp* は2つの引数 (list items) からなるカスタムの比較関数を指定しま
   す。これは始めの引数が 2 つ目の引数に比べて小さい、等しい、大きいか
   に応じて負数、ゼロ、正数を返します。 ``cmp=lambda x,y:
   cmp(x.lower(), y.lower())`` 。デフォルト値は ``None`` です。

   *key* は1つの引数からなる関数を指定します。これは個々のリストの要素
   から比較のキーを取り出すのに使われます。 ``key=str.lower`` 。デフォ
   ルト値は ``None`` です。

   *reverse* は真偽値です。 ``True`` がセットされた場合、リストの要素
   は個々の比較が反転したものとして並び替えられます。

   一般的に、 *key* および *reverse* の変換プロセスは同等の *cmp* 関数
   を指定するより早く動作します。これは *key* および *reverse* がそれ
   ぞれの要素に一度だけ触れる間に、 *cmp* はリストのそれぞれの要素に対
   して複数回呼ばれることによるものです。
   旧式の *cmp* 関数を *key* 関数に変換するには :func:`functools.cmp_to_key` 
   を使用してください。

   .. versionchanged:: 2.3
      ``None`` を渡すのと、 *cmp* を省略した場合とで、同等に扱うサポートを追加.

   .. versionchanged:: 2.4
      *key* および *reverse* のサポートを追加.

(9)
   Python2.3 以降、 :meth:`sort` メソッドは安定していることが保証され
   ています。
   ソートは等しいとされた要素の相対オーダーが変更されないことが保証さ
   れれば、安定しています --- これは複合的なパス（例えば部署ごとにソー
   トして、それを給与の等級）でソートを行なうのに役立ちます。

(10)
   .. impl-detail::

      リストが並べ替えられている間は、リストの変更はもとより、その値の閲
      覧すらその結果は未定義です。 Python 2.3 以降の C 実装では、この間
      リストは空に見えるようになり、並べ替え中にリストが変更されたことが
      検出されると :exc:`ValueError` が送出されます。


.. _types-set:

set（集合）型 --- :class:`set`, :class:`frozenset`
==================================================

.. index:: object: set

:dfn:`set` オブジェクトは順序付けされていない :term:`hashable` (ハッシュ
可能な) オブジェクトのコレクションです。よくある使い方には、メンバーシッ
プのテスト、数列から重複を削除する、そして論理積、論理和、差集合、対称
差など数学的演算の計算が含まれます。
(他のコンテナ型については、組み込みクラスの :class:`dict`,
:class:`list`, :class:`tuple`,および、モジュール :mod:`collections`
を参照下さい)


.. versionadded:: 2.4

他のコレクションと同様、 sets は ``x in set``, ``len(set)`` および
``for x in set`` をサポートします。順序を持たないコレクションとして、
sets は要素の位置と (要素の) 挿入位置を保持しません。したがって、 sets
はインデックス、スライス、その他のシーケンス的な振る舞いをサポートしま
せん。

:class:`set` および :class:`frozenset` という、2つの組み込みset型があ
ります。 :class:`set` は変更可能な --- :meth:`add` や :meth:`remove`
のようなメソッドを使って内容を変更できます。変更可能なため、ハッシュ値
を持たず、また辞書のキーや他のsetの要素として用いることができません。
:class:`frozenset` 型はイミュータブルで、ハッシュ化可能
(:term:`hashable`) です --- 作成後に内容を改変できません。
そのため、辞書のキーや他の集合の要素として使えます。

Python 2.7 では、空でない set (frozenset ではない) は、 :class:`set`
コンストラクタに加え、要素を波カッコ中にカンマで区切って
列挙することでも生成できます。例: ``{'jack', 'sjoerd'}``.

両方のクラスのコンストラクタの働きは同じです:

.. class:: set([iterable])
           frozenset([iterable])

   *iterable* から要素と取り込んだ、新しい set もしくは frozenset オブジェ
   クトを返します。 set の要素はハッシュ可能なものでなくてはなりません。
   set の set, つまり内部 set は :class:`frozenset` オブジェクトでなく
   てはなりません。もし、 *iterable* が指定されないならば、新しい空の set
   が返されます。

   :class:`set` および :class:`frozenset` のインスタンスは以下の操作を
   提供します:

   .. describe:: len(s)

      set *s* の要素数を返します。

   .. describe:: x in s

      *x* が *s* のメンバーに含まれるか確認します。

   .. describe:: x not in s

      *x* が *s* のメンバーに含まれていないことを確認します。

   .. method:: isdisjoint(other)

      set が *other* と共通の要素を持たないとき、 True を返します。
      set はそれらの積集合が空集合となるときのみ、互いに素となります。

      .. versionadded:: 2.6

   .. method:: issubset(other)
               set <= other

      set の全ての要素が、 *other* に含まれるか確認します。

   .. method:: set < other

      set が *other* の真部分集合であるかを確認します。つまり、
      ``set <= other and set != other`` と等価です。

   .. method:: issuperset(other)
               set >= other

      *other* の全ての要素が、 set に含まれるか確認します。

   .. method:: set > other

      set が *other* の真上位集合であるかを確認します。つまり、 ``set
      >= other and set != other`` と等価です。

   .. method:: union(other, ...)
               set | other | ...

      set と全ての other の要素からなる新しい set を返します。

      .. versionchanged:: 2.6
         複数のイテラブルからの入力を受け入れるようになりました。

   .. method:: intersection(other, ...)
               set & other & ...

      set と全ての other に共通する要素を持つ、新しい set を返します。

      .. versionchanged:: 2.6
         複数のイテラブルからの入力を受け入れるようになりました。

   .. method:: difference(other, ...)
               set - other - ...

      set に含まれて、かつ、全ての other に含まれない要素を持つ、新し
      い set を返します。

      .. versionchanged:: 2.6
         複数のイテラブルからの入力を受け入れるようになりました。

   .. method:: symmetric_difference(other)
               set ^ other

      set もしくは *other* のいずれか一方だけに含まれる要素を持つ新し
      い set を返します。

   .. method:: copy()

      *s* の浅いコピーを新しい set として返します。


   演算子でないバージョンの :meth:`union`, :meth:`intersection`,
   :meth:`difference`, :meth:`symmetric_difference`, :meth:`issubset`,
   :meth:`issuperset` メソッドはいかなるイテラブルをも引数としてとるこ
   とに注意して下さい。それとは対照的に、それらの演算子版では set であ
   ることを要求します。これは、より読みやすい
   ``set('abc').intersection('cbs')`` のような書き方を支持し、
   ``set('abc') & 'cbs'`` のような、間違った構文を予防します。

   :class:`set` と :class:`frozenset` の両方とも、 set と set の比較
   をサポートします。二つの set は、それぞれの set の要素が互いに等し
   い場合にのみ等しくなります (互いに、他方の部分集合になっている場
   合です) 。
   一つめの set が二つめの set の真部分集合になっているときのみ、一つ
   め set は二つめの set より小さくなります (つまり、部分集合であり、
   かつ、等しくない場合です) 。

   :class:`set` のインスタンスは、 :class:`frozenset` のインスタンス
   との比較は、それぞれの要素に基づいて行われます。例えば、
   ``set('abc') == frozenset('abc')`` や ``set('abc') in
   set([frozenset('abc')])`` は ``True`` を返します。

   部分集合と等価性の比較は順序関数には拡張されません。例えば、互いに
   素 (等しくなく、互いに部分集合でもない) である集合は、以下の全てに、
   ``False`` を返します : ``a<b``, ``a==b``, および ``a>b`` 。そのため、
   set は :meth:`__cmp__` メソッドを実装しません。

   set は不完全な順序の定義(部分集合の関係)しか持たないため、
   :meth:`list.sort` メソッドの出力は set のリストに対して定義されませ
   ん。

   set の要素は、辞書のキーのように、 :term:`hashable` (ハッシュ可能)
   でなければなりません。

   :class:`set` インスタンスと :class:`frozenset` インスタンスを取り混
   ぜてのバイナリ演算は、ひとつめの演算対象の型のインスタンスを返しま
   す。例えば : ``frozenset('ab') | set('bc')`` は :class:`frozenset`
   インスタンスを返します。

   以下の内容を更新する操作は :class:`set` に適用されますが、変更不可
   である :class:`frozenset` のインスタンスには適用されません :

   .. method:: update(other, ...)
               set |= other | ...

      全ての other の要素を追加し、 set を更新します。

      .. versionchanged:: 2.6
         複数の入力イテラブルを受け付けるようになりました。

   .. method:: intersection_update(other, ...)
               set &= other & ...

      元の set と 全ての other に共通する要素だけを残して set を更新します。

      .. versionchanged:: 2.6
         複数の入力イテラブルを受け付けるようになりました。

   .. method:: difference_update(other, ...)
               set -= other | ...

      *other* に含まれる要素を取り除き、 set を更新します。

      .. versionchanged:: 2.6
         複数の入力イテラブルを受け付けるようになりました。

   .. method:: symmetric_difference_update(other)
               set ^= other

      どちらかにのみ含まれて、共通には持たない要素のみで set を更新し
      ます。

   .. method:: add(elem)

      要素 *elem* を set に追加します。

   .. method:: remove(elem)

      要素 *elem* を set から取り除きます。もし *elem* が set に含まれ
      なければ  :exc:`KeyError` を送出します。

   .. method:: discard(elem)

      要素 *elem* が set に含まれていれば、取り除きます。

   .. method:: pop()

      任意に要素を set から返し、それを set から取り除きます。 set が
      空であれば、 :exc:`KeyError` を送出します。

   .. method:: clear()

      set の全ての要素を取り除きます。


   非演算子版の :meth:`update`, :meth:`intersection_update`,
   :meth:`difference_update`, および
   :meth:`symmetric_difference_update` メソッドはどんなイテラブルでも
   引数として受け付けることに注意して下さい。

   :meth:`__contains__`, :meth:`remove`, および :meth:`discard` メソッ
   ドの引数 *elem* は set であっても構いません。等価な frozenset の検
   索をサポートするために、 *elem* set は一時的に検索の間は変化させら
   れ、その後、復元されます。検索の間は意味のある値を持たなくなるため、
   *elem* set を読み出したり、変更してはいけません。


.. seealso::

   :ref:`comparison-to-builtin-set`
      :mod:`sets` モジュールと組み込み set 型の違い


.. _typesmapping:

マップ型
========

.. index::
   object: mapping
   object: dictionary
   triple: operations on; mapping; types
   triple: operations on; dictionary; type
   statement: del
   builtin: len

マップ型 (:dfn:`mapping`) オブジェクトは :term:`hashable` (ハッシュ可
能) な値を任意のオブジェクトに割り付けます。
マップ型は変更可能なオブジェクトです。現時点では、ひとつだけの標準マッ
プ型として辞書型 (:dfn:`dictionary`) があります (他のコンテナ型につい
ては組み込みクラスの :class:`list`, :class:`set`, および
:class:`tuple` と、 :mod:`collections` モジュールを参照下さい) 。

辞書型のキーは *ほぼ* 任意の値です。ハッシュ可能(:term:`hashable`)でな
い、つまり、リストや辞書型を含む、変更可能な型 (値ではなく、オブジェク
トの同一性で比較されます) はキーとして使用できません。数値型は通常の数
値比較のルールに従ってキーとして使われます　: もしふたつの数値を比較し、
等しければ (例えば ``1`` と ``1.0`` のように) 同じ辞書型に対しインデッ
クスとして同じものとして使用できます (しかしながら、コンピュータ上では
近似値を浮動小数点数として保管されることに注意して下さい。これは大抵の
場合、辞書型のキーとして使用するのに良い方法ではありません) 。

辞書型は ``key: value`` の形式の対の値をカンマ区切りのリストを波括弧で
くくることで作成できます。例えば : ``{'jack': 4098, 'sjoerd': 4127}``
あるいは ``{4098: 'jack', 4127: 'sjoerd'}`` 。あるいは、 :class:`dict`
のコンストラクタでも作成できます。

.. class:: dict([arg])

   オプションのポジション引数、もしくは、一連のキーワード引数で初期化
   された新しい辞書型を返します。引数が無い場合は、空の辞書型を返しま
   す。もし、ポジション引数 *arg* がマップ型オブジェクトであれば、もと
   のマップ型オブジェクトと同じ値に同じキーを割り当てた辞書型を返しま
   す。そうでない場合は、ポジション引数はイテレーションをサポートする
   シーケンスか、イテレータオブジェクトでなければなりません。引数の要
   素もまた、それと同様でなくてはならず、かつ、それぞれがちょうどふた
   つのオブジェクトを持っている必要があります。
   最初のものが新しい辞書型において、キーとして使われます。ふたつめの
   ものがキーの値として使われます。もし、与えられたキーが二度以上現れ
   た場合は、最後に現れた値が新しい辞書型において採用されます。

   キーワード引数が与えられた場合、キーワード自身がその値として辞書型
   に加えられます。もしキーがポジション引数において、キーワード引数を
   規定した場合、キーワードに値が割り当てられ辞書に追加されます。例え
   ば以下は全て ``{"one": 1, "two": 2}`` と等しい辞書型インスタンスを
   返します :

   * ``dict(one=1, two=2)``
   * ``dict({'one': 1, 'two': 2})``
   * ``dict(zip(('one', 'two'), (1, 2)))``
   * ``dict([['two', 2], ['one', 1]])``

   最初の例では、 Python の識別子として有効なキーに対してのみ機能しま
   す ; 他の例はキーとして有効なものであればいかなるキーに対しても機能
   します。

   .. versionchanged:: 2.3
      キーワード引数からの辞書型の作成のサポートが追加されました。


   以下は辞書型がサポートする操作です (それゆえ、カスタムのマップ型も
   これらの操作をサポートするべきです):

   .. describe:: len(d)

      辞書 *d* に含まれる項目数を返します。

   .. describe:: d[key]

      *d* のキー *key* の項目を返します。もし *key* が存在しなければ、
      :exc:`KeyError` を送出します。

      .. versionadded:: 2.5

         もし、辞書型のサブクラスが :meth:`__missing__` メソッドを定義
         していれば、 *key* が存在しないとき、 ``d[key]`` により *key*
         を引数として呼び出されます。 ``d[key]`` は
         ``__missing__(key)`` が存在しないキーで呼び出されたときに返す、
         値を返すか、例外を送出します。他のいかなる操作やメソッドも
         :meth:`__missing__` を呼び出しません。
         :meth:`__missing__` が定義されていなければ、 :exc:`KeyError`
         が送出されます。 :meth:`__missing__` はメソッドで無くてはなり
         ません ; インスタンスや値であってはなりません。例は
         :class:`collections.defaultdict` を参照下さい。

   .. describe:: d[key] = value

      ``d[key]`` に *value* を設定します。

   .. describe:: del d[key]

      *d* から ``d[key]`` を削除します。もし *key* が存在しなければ、
      :exc:`KeyError` を送出します。

   .. describe:: key in d

      *d* がキー *key* を持っていれば、 ``True`` を返します。そうでな
      ければ、 ``False`` を返します。

      .. versionadded:: 2.2

   .. describe:: key not in d

      ``not key in d`` と等価です。

      .. versionadded:: 2.2

   .. describe:: iter(d)

      辞書 *d* の全てのキーに渡って、イテレータを返します。これは
      :meth:`iterkeys` メソッドへのショートカットです。

   .. method:: clear()

      辞書の全ての項目を消去します。

   .. method:: copy()

      辞書の浅いコピーを返します。

   .. method:: fromkeys(seq[, value])

      *seq* をキーとし、 *value* を値に設定した、新しい辞書を作成します。

      :func:`fromkeys` は新しい辞書を返すクラスメソッドです。 *value*
      のデフォルト値は ``None`` です。

      .. versionadded:: 2.3

   .. method:: get(key[, default])

      もし *key* が辞書にあれば、 *key* に対する値を返します。そうでな
      ければ、 *default* を返します。 *default* が与えられなかった場合、
      デフォルトでは ``None`` となります。そのため、このメソッドは
      :exc:`KeyError` を送出することはありません。

   .. method:: has_key(key)

      辞書に *key* が存在するかを確認します。 :meth:`has_key` は ``key
      in d`` と同じことです。

   .. method:: items()

      辞書のコピーを ``(key, value)`` の対のリストとして返します。

      .. impl-detail::

         キーと値のリストは任意の順序で返されますが、ランダムではなく、
         Python の実装と、辞書への挿入、および、削除操作の来歴によって
         決まります。

      もし、 :meth:`items`, :meth:`keys`, :meth:`values`,
      :meth:`iteritems`, :meth:`iterkeys` および :meth:`itervalues` が
      辞書を変更することなく呼び出されたら、リストは一致するでしょう。
      これにより、 ``(value, key)`` の対を :func:`zip`
      または ``pairs = zip(d.values(), d.keys())`` を使って生成するとができます。
      同じ関係が、 :meth:`iterkeys` および :meth:`itervalues` メソッドにもあてはまります :
      ``pairs = zip(d.itervalues(), d.iterkeys())`` は ``pairs`` と同じ値を返します。
      ``pairs = [(v, k) for (k, v) in d.iteritems()]`` も同様です。

   .. method:: iteritems()

      辞書の ``(key, value)`` の対をイテレータで返します。
      :meth:`dict.items` の Note も参照下さい。

      :meth:`iteritems` を辞書の項目の追加や削除と同時に行うと、
      :exc:`RuntimeError` を送出されるか全ての項目に対する反復に失敗することになります。

      .. versionadded:: 2.2

   .. method:: iterkeys()

      辞書のキーをイテレータで返します。 :meth:`dict.items` の Note も
      参照下さい。

      :meth:`iterkeys` を辞書の項目の追加や削除と同時に行うと、
      :exc:`RuntimeError` を送出されるか全ての項目に対する反復に失敗することになります。

      .. versionadded:: 2.2

   .. method:: itervalues()

      辞書の値をイテレータで返します。 :meth:`dict.items` の Note も参
      照下さい。

      :meth:`itervalues` を辞書の項目の追加や削除と同時に行うと、
      :exc:`RuntimeError` を送出されるか全ての項目に対する反復に失敗することになります。

      .. versionadded:: 2.2

   .. method:: keys()

      辞書のキーのリストのコピーを返します。 :meth:`dict.items` の
      Note も参照下さい。

   .. method:: pop(key[, default])

      もし *key* が辞書に存在すれば、その値を辞書から除去して返します。
      そうでなければ、 *default* を返します。 *default* が与えらず、か
      つ、 *key* が辞書に存在しなければ :exc:`KeyError` を送出します。

      .. versionadded:: 2.3

   .. method:: popitem()

      任意の ``(key, value)`` の対を辞書から除去して返します。

      set のアルゴリズムで使われるのと同じように :func:`popitem` は辞
      書に繰り返し適用して消去するのに便利です。もし辞書が空であれば、
      :func:`popitem` の呼び出しは :exc:`KeyError` を送出します。

   .. method:: setdefault(key[, default])

      もし、 *key* が辞書に存在すれば、その値を返します。そうでなけれ
      ば、値を *default* として *key* を挿入し、 *default* を返します。
      *default* のデフォルト値は ``None`` です。

   .. method:: update([other])

      辞書の内容を *other* のキーと値で更新します。既存のキーは上書き
      されます。返り値は ``None`` です。

      :func:`update` は、他の辞書オブジェクトでもキーと値の対のイテラ
      ブル (タプル、もしくは、長さが2のイテラブル) でも、どちらでも受
      け付けます。キーワード引数が指定されれば、そのキーと値で辞書を更
      新します。 : ``d.update(red=1, blue=2)``

      .. versionchanged:: 2.4
          キーと値の対のイテラブル、および、キーワード引数を引数として
          与えることができるようになりました。

   .. method:: values()

      辞書の値のリストのコピーを返します。 :meth:`dict.items` の Note
      も参照下さい。
      
   .. method:: viewitems()

      辞書の要素 (``(key, value)`` の対) の新しいビューを返します。
      ビューオブジェクトのドキュメントは下を参照してください。

      .. versionadded:: 2.7

   .. method:: viewkeys()

      辞書のキーの新しいビューを返します。
      ビューオブジェクトのドキュメントは下を参照してください。

      .. versionadded:: 2.7

   .. method:: viewvalues()

      辞書の値の新しいビューを返します。
      ビューオブジェクトのドキュメントは下を参照してください。

      .. versionadded:: 2.7


.. _dict-views:

辞書ビューオブジェクト
----------------------

:meth:`dict.keys` 、 :meth:`dict.values` 、 :meth:`dict.items` によって
返されるオブジェクトは、 *ビューオブジェクト* です。これらは、辞書の項目の
動的なビューを提供し、辞書が変更された時、ビューはその変更を反映します。

辞書ビューを通して反復することで、対応するデータを産出できます。
また、帰属検査をサポートしています。

.. describe:: len(dictview)

   辞書の項目数を返します。

.. describe:: iter(dictview)

   辞書のキー、値、または (``(key, value)`` のタプルとして表される) 要素に
   渡るイテレータを返します。

   キーと値のリストは任意の順序で反復されますが、ランダムではなく、
   Python の実装によって変わり、辞書への挿入や削除の履歴に依存します。
   キー、値、要素のビューを通して、辞書の変更を挟まずにイテレート
   されたら、その要素の順序は完全に一致します。
   これにより、 ``(value, key)`` の対を
   :func:`zip` で作成できます: ``pairs = zip(d.values(), d.keys())`` 。
   同じリストを作成する他の方法は、
   ``pairs = [(v, k) for (k, v) in d.items()]`` です。

   辞書の項目の追加や削除中にビューをイテレートすると、 :exc:`RuntimeError`
   を送出したり、すべての項目に渡ってイテレートできなかったりします。

.. describe:: x in dictview

   *x* が下にある辞書のキー、値、または要素 (要素の場合、 *x* は
   ``(key, value)`` タプルであるべきです) にあるとき ``True`` を返します。


キーのビューは、項目が一意的でハッシュ可能であるという点で、集合に似ています。
すべての値がハッシュ可能なら、 ``(key, value)`` の対も一意的で
ハッシュ可能であり、要素のビューも集合に似ています。(値のビューは、
要素が一般に一意的でないことから、集合に似ているとは考えられません。)
ですから、これらの集合演算が利用できます。
("other" は別のビューか集合です):

.. describe:: dictview & other

   辞書ビューと別のオブジェクトの共通部分を新しい集合として返します。

.. describe:: dictview | other

   辞書ビューと別のオブジェクトの合併集合を新しい集合として返します。

.. describe:: dictview - other

   辞書ビューと別のオブジェクトの差集合 (*dictview* に属して *other* に
   属さないすべての要素) を新しい集合として返します。

.. describe:: dictview ^ other

   辞書ビューと別のオブジェクトの対称差 (*dictview* と *other* のどちらかに
   属すが両方には属さないすべての要素) を新しい集合として返します。


辞書ビューの使用法の例::

   >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500}
   >>> keys = dishes.viewkeys()
   >>> values = dishes.viewvalues()

   >>> # iteration
   >>> n = 0
   >>> for val in values:
   ...     n += val
   >>> print(n)
   504

   >>> # keys and values are iterated over in the same order
   >>> list(keys)
   ['eggs', 'bacon', 'sausage', 'spam']
   >>> list(values)
   [2, 1, 1, 500]

   >>> # view objects are dynamic and reflect dict changes
   >>> del dishes['eggs']
   >>> del dishes['sausage']
   >>> list(keys)
   ['spam', 'bacon']

   >>> # set operations
   >>> keys & {'eggs', 'bacon', 'salad'}
   {'bacon'}



.. _bltin-file-objects:

ファイルオブジェクト
====================

.. index::
   object: file
   builtin: file
   module: os
   module: socket

ファイルオブジェクト  は C の ``stdio`` パッケージを使って実装されてお
り、組み込み関数の :func:`open` で生成することができます。
ファイルオブジェクトはまた、 :func:`os.popen` や :func:`os.fdopen`,
ソケットオブジェクトの :meth:`makefile` メソッドのような、他の組み込み
関数およびメソッドによっても返されます。一時ファイルは :mod:`tempfile`
モジュールを使って生成でき、ファイルやディレクトリのコピー、移動、消去
などの高次の操作は :mod:`shutil` モジュールで行います。

ファイル操作が I/O 関連の理由で失敗した場合例外 :exc:`IOError` が送出
されます。この理由には例えば :meth:`seek` を端末デバイスに行ったり、読
み出し専用で開いたファイルに書き込みを行うといった、何らかの理由によっ
てそのファイルで定義されていない操作を行ったような場合も含まれます。

ファイルは以下のメソッドを持ちます:


.. method:: file.close()

   ファイルを閉じます。閉じられたファイルはそれ以後読み書きすることは
   できません。ファイルが開かれていることが必要な操作は、ファイルが閉
   じられた後はすべて :exc:`ValueError` を送出します。 :meth:`close`
   を一度以上呼び出してもかまいません。

   Python 2.5 から :keyword:`with` 文を使えばこのメソッドを直接呼び出
   す必要はなくなりました。たとえば、以下のコードは *f* を
   :keyword:`with` ブロックを抜ける際に自動的に閉じます。 ::

      from __future__ import with_statement # これは Python 2.6 では不要です

      with open("hello.txt") as f:
          for line in f:
              print line

   古いバージョンの Python では同じ効果を得るために次のようにしなければいけませんでした。 ::

      f = open("hello.txt")
      try:
          for line in f:
              print line
      finally:
          f.close()

   .. note::

      全ての Python の "ファイル的" 型が :keyword:`with` 文用のコンテ
      キスト・マネージャとして使えるわけではありません。もし、全てのファ
      イル的オブジェクトで動くようにコードを書きたいのならば、オブジェ
      クトを直接使うのではなく :mod:`contextlib` にある
      :func:`contextlib.closing` 関数を使うと良いでしょう。


.. method:: file.flush()

   ``stdio`` の :c:func:`fflush` のように、内部バッファをフラッシュし
   ます。ファイル類似のオブジェクトによっては、この操作は何も行いません。

   .. note::

      :meth:`flush` は必ずしもファイルのデータをディスクに書き込むとは限りません。
      そのような挙動を保証するには :meth:`flush` の後に :func:`os.fsync` を使って下さい。


.. method:: file.fileno()

   .. index::
      pair: file; descriptor
      module: fcntl

   背後にある実装系がオペレーティングシステムに I/O 操作を要求するため
   に用いる、整数の "ファイル記述子" を返します。この値は他の用途とし
   て、 :mod:`fcntl` モジュールや :func:`os.read` やその仲間のような、
   ファイル記述子を必要とする低レベルのインタフェースで役に立ちます。


   .. note::

      ファイル類似のオブジェクトが実際のファイルに関連付けられていない
      場合、このメソッドを提供すべきでは *ありません* 。


.. method:: file.isatty()

   ファイルが tty (または類似の) デバイスに接続されている場合 ``True``
   を返し、そうでない場合 ``False`` を返します。

   .. note::

      ファイル類似のオブジェクトが実際のファイルに関連付けられていない
      場合、このメソッドを実装すべきでは *ありません* 。


.. method:: file.next()

   ファイルオブジェクトはそれ自身がイテレータです。すなわち、
   ``iter(f)`` は (*f* が閉じられていない限り) *f* を返します。
   :keyword:`for` ループ (例えば ``for line in f: print line``) のよう
   にファイルがイテレータとして使われた場合、 :meth:`next` メソッドが
   繰り返し呼び出されます。ファイルが読み出しモードで開かれている場合、
   このメソッドは次の入力行を返すか、または、 EOF に到達したときに
   :exc:`StopIteration` を送出します (ファイルが書き込みモードで開かれ
   ている場合、動作は未定義です) 。
   ファイル内の各行に対する :keyword:`for` ループ (非常によくある操作
   です) を効率的な方法で行うために、 :meth:`next` メソッドは隠蔽され
   た先読みバッファを使います。先読みバッファを使った結果として、
   (:meth:`readline` のような) 他のファイルメソッドと :meth:`next` を
   組み合わせて使うとうまく動作しません。しかし、 :meth:`seek` を使っ
   てファイル位置を絶対指定しなおすと、先読みバッファは消去されます。

   .. versionadded:: 2.3


.. method:: file.read([size])

   最大で *size* バイトをファイルから読み込みます (*size* バイトを取得
   する前に EOF に到達した場合、それ以下の長さになります) 。 *size* 引
   数が負であるか省略された場合、 EOF に到達するまでの全てのデータを読
   み込みます。読み出されたバイト列は文字列オブジェクトとして返されま
   す。直後に EOF に到達した場合、空の文字列が返されます。 (端末のよう
   なある種のファイルでは、 EOF に到達した後でファイルを読みつづけるこ
   とにも意味があります) 。
   このメソッドは、 *size* バイトに可能な限り近くデータを取得するため
   に、背後の C 関数 :c:func:`fread` を 1 度以上呼び出すかもしれないの
   で注意してください。また、非ブロック・モードでは、 *size* パラメー
   タが与えられなくても、要求されたよりも少ないデータが返される場合が
   あることに注意してください。

   .. note::
      この関数は単純に、背後の C 関数、 :c:func:`fread` のラッパーです。
      そのため、 EOF が見つからない場合など、特殊な状況では同様に振る
      舞います。


.. method:: file.readline([size])

   ファイルから一行全部を読み込みます。終末の改行文字は文字列に残ります
   (しかし、ファイルが不完全な行で終わっていたら、存在しないかもしれません)。 [#]_
   *size* 引数が与えられ、負でなければ、それが (終末の改行文字を含む)
   最大バイト数となり、不完全な行でも返されます。 *size* が 0 でなければ、
   空の文字列が返されるのは、即座に EOF に到達したとき *だけ* です。


   .. note::

      ``stdio`` の :c:func:`fgets` と違い、入力中にヌル文字 (``'\0'``)
      が含まれていれば、ヌル文字を含んだ文字列が返されます。


.. method:: file.readlines([sizehint])

   :meth:`readline` を使ってに到達するまで読み出し、 EOF 読み出された
   行を含むリストを返します。オプションの *sizehint* 引数が存在すれば、
   EOF まで読み出す代わりに完全な行を全体で大体 *sizehint* バイトにな
   るように (おそらく内部バッファサイズを切り詰めて) 読み出します。ファ
   イル類似のインタフェースを実装しているオブジェクトは、 *sizehint*
   を実装できないか効率的に実装できない場合には無視してもかまいません。


.. method:: file.xreadlines()

   このメソッドは ``iter(f)`` と同じ結果を返します。

   .. versionadded:: 2.1

   .. deprecated:: 2.3
      代わりに ``for line in file`` を使ってください。


.. method:: file.seek(offset[, whence])

   ``stdio`` の :c:func:`fseek` と同様に、ファイルの現在位置を設定します。
   *whence* 引数はオプションで、標準の値は ``os.SEEK_SET`` もしくは
   ``0`` (絶対位置指定) です; 他に取り得る値は ``os.SEEK_CUR`` もしく
   は ``1`` (現在のファイル位置から相対的に seek する) および
   ``os.SEEK_END`` もしくは ``2`` (ファイルの末端から相対的に seek す
   る) です。戻り値はありません。

   例えば、 ``f.seek(2, os.SEEK_CUR)`` 位置を2つ進めます。
   ``f.seek(-3, os.SEEK_END)`` では終端の3つ手前に設定します。

   ファイルを追記モード (モード ``'a'`` または ``'a+'``) で開いた場合、
   書き込みを行うまでに行った :meth:`seek` 操作はすべて元に戻されるの
   で注意してください。ファイルが追記のみの書き込みモード (``'a'``) で
   開かれた場合、このメソッドは実質何も行いませんが、読み込みが可能な
   追記モード (``'a+'``) で開かれたファイルでは役に立ちます。ファイル
   をテキストモードで (``'b'`` なしで) 開いた場合、 :meth:`tell` が返
   すオフセットのみが正しい値になります。他のオフセット値を使った場合、
   その振る舞いは未定義です。

   全てのファイルオブジェクトが seek できるとは限らないので注意してく
   ださい。


.. method:: file.tell()

   ``stdio`` の :c:func:`ftell` と同様、ファイルの現在位置を返します。

   .. note::

      Windows では、(:c:func:`fgets` の後で) Unix-スタイルの改行のファ
      イルを読むときに :meth:`tell` が不正な値を返すことがあります。
      この問題に遭遇しないためにはバイナリーモード (``'rb'``) を使うよ
      うにしてください。


.. method:: file.truncate([size])

   ファイルのサイズを切り詰めます。オプションの *size* が存在すれば、
   ファイルは (最大で) 指定されたサイズに切り詰められます。標準設定の
   サイズの値は、現在のファイル位置までのファイルサイズです。現在のファ
   イル位置は変更されません。指定されたサイズがファイルの現在のサイズ
   を越える場合、その結果はプラットフォーム依存なので注意してください:
   可能性としては、ファイルは変更されないか、指定されたサイズまでゼロ
   で埋められるか、指定されたサイズまで未定義の新たな内容で埋められる
   か、があります。利用可能な環境:  Windows, 多くの Unix 系。


.. method:: file.write(str)

   文字列をファイルに書き込みます。戻り値はありません。バッファリング
   によって、 :meth:`flush` または :meth:`close` が呼び出されるまで
   実際にファイル中に文字列が書き込まれないこともあります。


.. method:: file.writelines(sequence)

   文字列からなるシーケンスをファイルに書き込みます。シーケンスは文字
   列を生成する反復可能なオブジェクトなら何でもかまいません。よくある
   のは文字列からなるリストです。戻り値はありません。 (関数の名前は
   :meth:`readlines` と対応づけてつけられました; :meth:`writelines` は
   行間の区切りを追加しません)

ファイルはイテレータプロトコルをサポートします。各反復操作では
``file.readline()`` と同じ結果を返し、反復は :meth:`readline` メソッド
が空文字列を返した際に終了します。

ファイルオブジェクトはまた、多くの興味深い属性を提供します。これらはファ
イル類似オブジェクトでは必要ではありませんが、特定のオブジェクトにとっ
て意味を持たせたいなら実装しなければなりません。


.. attribute:: file.closed

   現在のファイルオブジェクトの状態を示すブール値です。この値は読み出
   し専用の属性です; :meth:`close` メソッドがこの値を変更します。全て
   のファイル類似オブジェクトで利用可能とは限りません。


.. attribute:: file.encoding

   このファイルが使っているエンコーディングです。 Unicode 文字列がファ
   イルに書き込まれる際、 Unicode 文字列はこのエンコーディングを使って
   バイト文字列に変換されます。さらに、ファイルが端末に接続されている
   場合、この属性は端末が使っているとおぼしきエンコーディング (この情
   報は端末がうまく設定されていない場合には不正確なこともあります) を
   与えます。この属性は読み出し専用で、すべてのファイル類似オブジェク
   トにあるとは限りません。またこの値は ``None`` のこともあり、この場
   合、ファイルは Unicode 文字列の変換のためにシステムのデフォルト
   エンコーディングを使います。

   .. versionadded:: 2.3


.. attribute:: file.errors

   エンコーディングに用いられる、 Unicode エラーハンドラです。

   .. versionadded:: 2.6


.. attribute:: file.mode

   ファイルの I/O モードです。ファイルが組み込み関数 :func:`open` で作
   成された場合、この値は引数 *mode* の値になります。この値は読み出し
   専用の属性で、全てのファイル類似オブジェクトに存在するとは限りませ
   ん。


.. attribute:: file.name

   ファイルオブジェクトが :func:`open` を使って生成された時のファイル
   の名前です。そうでなければ、ファイルオブジェクト生成の起源を示す何
   らかの文字列になり、 ``<...>`` の形式をとります。この値は読み出し専
   用の属性で、全てのファイル類似オブジェクトに存在するとは限りません。


.. attribute:: file.newlines

   Python がユニバーサル改行モードを (デフォルトどおり) 有効にして
   ビルドされているなら、この読み込み専用属性が存在し、ファイルが
   ユニバーサル改行モードで開かれたファイルで、ファイルの読み込み中に
   あった改行の種類を記録します。取り得る値は ``'\r'``, ``'\n'``, ``'\r\n'``,
   ``None`` (不明であるか、まだ改行を読み込んでいない)、または、複数の
   改行方式の種類が存在したことを表す、見つかったすべての改行の種類を含む
   タプルです。ユニバーサル改行モードで開かれたのでないファイルに対しては、
   この属性の値は ``None`` になります。


.. attribute:: file.softspace

   :keyword:`print` 文を使った場合、他の値を出力する前にスペース文字を
   出力する必要があるかどうかを示すブール値です。ファイルオブジェクト
   をシミュレート仕様とするクラスは書き込み可能な :attr:`softspace` 属
   性を持たなければならず、この値はゼロに初期化されなければなりません。
   この値は Python で実装されているほとんどのクラスで自動的に初期化さ
   れます (属性へのアクセス手段を上書きするようなオブジェクトでは注意
   が必要です); C で実装された型では、書き込み可能な :attr:`softspace`
   属性を提供しなければなりません。

   .. note::

      この属性は :keyword:`print` 文を制御するために用いられますが、
      :keyword:`print` の内部状態を乱さないために、その実装を行うこと
      はできません。


.. _typememoryview:

メモリビュー型
==============

:class:`memoryview` オブジェクトは、Python コードが
バッファプロトコルをコピーすることなく
対応しているオブジェクトの内部データにアクセス出来るようにします。
メモリは通常、単純なバイト列として解釈されます。

.. class:: memoryview(obj)

   *obj* を参照する :class:`memoryview` を作成します。 *obj* は
   バッファプロトコルをサポートしていなければなりません。
   バッファプロトコルをサポートする組み込みオブジェクトには、
   :class:`str` 、 :class:`bytearray` などがあります
   (ただし、 :class:`unicode` は違います)。

   :class:`memoryview` には *要素* の概念があり、それが起源のオブジェクト
   *obj* によって扱われる原子的なメモリの単位になります。
   多くの単純なオブジェクト、例えば :class:`str` や :class:`bytearray` では、
   要素は単バイトになりますが、他のサードパーティの型では、
   要素はより大きくなりえます。

   ``len(view)`` は、メモリビュー *view* の要素の総数を返します。
   :class:`~memoryview.itemsize` 属性は、一つの要素内のバイト数を与えます。

   :class:`memoryview` はスライスしてデータを晒すことに対応しています。
   一つのインデクスを取ると、一つの要素を :class:`str` オブジェクトとして
   返します。完全なスライシングは部分ビューになります::

      >>> v = memoryview('abcefg')
      >>> v[1]
      'b'
      >>> v[-1]
      'g'
      >>> v[1:4]
      <memory at 0x77ab28>
      >>> v[1:4].tobytes()
      'bce'

   メモリビューが基にしているオブジェクトがデータの変更に対応していれば、
   メモリビューはスライス代入に対応します::

      >>> data = bytearray('abcefg')
      >>> v = memoryview(data)
      >>> v.readonly
      False
      >>> v[0] = 'z'
      >>> data
      bytearray(b'zbcefg')
      >>> v[1:4] = '123'
      >>> data
      bytearray(b'z123fg')
      >>> v[2] = 'spam'
      Traceback (most recent call last):
        File "<stdin>", line 1, in <module>
      ValueError: cannot modify size of memoryview object

   この通り、メモリビューオブジェクトの長さは変えられません。

   :class:`memoryview` には 2 つのメソッドがあります。

   .. method:: tobytes()

      バッファ中のデータをバイト文字列 (クラス :class:`str` のオブジェクト)
      として返します::

         >>> m = memoryview("abc")
         >>> m.tobytes()
         'abc'

   .. method:: tolist()

      バッファ中のデータを整数のリストとして返します::

         >>> memoryview("abc").tolist()
         [97, 98, 99]

   読み込み専用の属性もいくつか使えます:

   .. attribute:: format

      ビューのそれぞれの要素に対する、(:mod:`struct` モジュールのスタイルでの)
      フォーマットを含む文字列です。
      デフォルトは ``'B'`` で、単純なバイト文字列です。

   .. attribute:: itemsize

      メモリビューのそれぞれの要素のバイト数です。

   .. attribute:: shape

      メモリの形状を N 次元配列として与える、長さ :attr:`ndim` の整数の
      タプルです。

   .. attribute:: ndim

      メモリが表す多次元配列が何次元かを示す整数です。

   .. attribute:: strides

      配列のそれぞれの次元に対して、それぞれの要素にアクセスするのに必要な
      バイト数を表す、長さ :attr:`ndim` の整数のタプルです。

   .. attribute:: readonly

      メモリが読み込み専用かを表すブールです。

   .. memoryview.suboffsets は C にしか役立たなさそうなので、
      ドキュメント化されていません。


.. _typecontextmanager:

コンテキストマネージャ型
========================

.. versionadded:: 2.5

.. index::
   single: context manager
   single: context management protocol
   single: protocol; context management

Python の :keyword:`with` 文はコンテキストマネージャによって定義される
実行時コンテキストの概念をサポートします。これは、ユーザ定義クラスが文
の本体が実行される前に進入し文の終わりで脱出する実行時コンテキストを定
義することを許す二つの別々のメソッドを使って実装されます。

:dfn:`コンテキスト管理プロトコル` (:dfn:`context management protocol`) は
実行時コンテキストを定義するコンテキストマネージャオブジェクトが提供す
べき一対のメソッドから成ります。


.. method:: contextmanager.__enter__()

   実行時コンテキストに入り、このオブジェクトまたは他の実行時コンテキ
   ストに関連したオブジェクトを返します。このメソッドが返す値はこのコ
   ンテキストマネージャを使う :keyword:`with` 文の :keyword:`as` 節の
   識別子に束縛されます。

   自分自身を返すコンテキストマネージャの例としてファイルオブジェクト
   があります。ファイルオブジェクトは :meth:`__enter__` から自分自身を
   返して :func:`open` が :keyword:`with` 文のコンテキスト式として使わ
   れるようにします。

   関連オブジェクトを返すコンテキストマネージャの例としては
   :func:`decimal.localcontext` が返すものがあります。
   このマネージャはアクティブな10進数コンテキストをオリジナルのコンテ
   キストのコピーにセットしてそのコピーを返します。こうすること
   で, :keyword:`with` 文の本体の内部で、外側のコードに影響を与えずに、
   10進数コンテキストを変更できます。


.. method:: contextmanager.__exit__(exc_type, exc_val, exc_tb)

   実行時コンテキストから抜け、例外 (がもし起こっていたとしても) を抑
   制することを示すブール値フラグを返します。 :keyword:`with` 文の本体
   を実行中に例外が起こったならば、引数にはその例外の型と値とトレース
   バック情報を渡します。そうでなければ、引数は全て ``None`` です。

   このメソッドから真となる値が返されると :keyword:`with` 文は例外の発
   生を抑え、 :keyword:`with` 文の直後の文に実行を続けます。そうでなけ
   れば、このメソッドの実行を終えると例外の伝播が続きます。このメソッ
   ドの実行中に起きた例外は :keyword:`with` 文の本体の実行中に起こった
   例外を置き換えてしまいます。

   渡された例外を直接的に再送出すべきではありません。その代わりに、こ
   のメソッドが偽の値を返すことでメソッドの正常終了と送出された例外を
   抑制しないことを伝えるべきです。このようにすれば
   (``contextlib.nested`` のような) コンテキストマネージャは
   :meth:`__exit__` メソッド自体が失敗したのかどうかを簡単に見分けるこ
   とができます。

Python は幾つかのコンテキストマネージャを、易しいスレッド同期・ファイ
ルなどのオブジェクトの即時クローズ・単純化されたアクティブな10進算術コ
ンテキストのサポートのために用意しています。各型はコンテキスト管理プロ
トコルを実装しているという以上の特別の取り扱いを受けるわけではありませ
ん。例については :mod:`contextlib` モジュールを参照下さい。

Python のジェネレータ (:term:`generator`) と
``contextlib.contextmanager`` デコレータ (:term:`decorator`) はこの
プロトコルの簡便な実装方法を提供します。ジェネレータ関数を
``contextlib.contextmanager`` でデコレートすると、デコレートしなければ
返されるイテレータを返す代わりに、必要な :meth:`__enter__` および
:meth:`__exit__` メソッドを実装したコンテキストマネージャを返すように
なります。

これらのメソッドのために Python/C API の中の Python オブジェクトの型構
造体に特別なスロットが作られたわけではないことに注意してください。これ
らのメソッドを定義したい拡張型については通常の Python からアクセスでき
るメソッドとして提供しなければなりません。実行時コンテキストを準備する
ことに比べたら、一つのクラスの辞書引きは無視できるオーバーヘッドです。


.. _typesother:

他の組み込み型
==============

インタプリタはその他の種類のオブジェクトをいくつかサポートします。これ
らのほとんどは 1 または 2 つの演算だけをサポートします。


.. _typesmodules:

モジュール
----------

モジュールに対する唯一の特殊な演算は属性へのアクセス: ``m.name`` です。
ここで *m* はモジュールで、 *name* は *m* のシンボルテーブル上に定義さ
れた名前にアクセスします。モジュール属性も代入することができます。
(:keyword:`import` 文は、厳密にいえば、モジュールオブジェクトに対する
演算です; ``import foo`` は *foo* と名づけられたモジュールオブジェクト
が存在することを必要とはせず、むしろ *foo* と名づけられた (外部の) モ
ジュールの *定義* を必要とします。)

各モジュールの特殊なメンバは :attr:`__dict__` です。これはモジュールの
シンボルテーブルを含む辞書です。この辞書を修正すると、実際にはモジュー
ルのシンボルテーブルを変更しますが、 :attr:`__dict__` 属性を直接代入す
ることはできません (``m.__dict__['a'] = 1`` と書いて ``m.a`` を ``1``
に定義することはできますが、 ``m.__dict__ = {}`` と書くことはできませ
ん) 。 :attr:`__dict__` を直接編集するのは推奨されません。

インタプリタ内に組み込まれたモジュールは、 ``<module 'sys'
(built-in)>`` のように書かれます。ファイルから読み出された場合、
``<module 'os' from '/usr/local/lib/pythonX.Y/os.pyc'>`` と書かれます。


.. _typesobjects:

クラスおよびクラスインスタンス
------------------------------

これらについては :ref:`objects` および :ref:`class` を参照下さい。


.. _typesfunctions:

関数
----

関数オブジェクトは関数定義によって生成されます。関数オブジェクトに対す
る唯一の操作は、それを呼び出すことです: ``func(argument-list)``

関数オブジェクトには実際には 2 つの種: 組み込み関数とユーザ定義関数が
あります。両方とも同じ操作 (関数の呼び出し) をサポートしますが、実装は
異なるので、オブジェクトの型も異なります。

詳細は、 :ref:`function` を参照下さい。


.. _typesmethods:

メソッド
--------

.. index:: object: method

メソッドは属性表記を使って呼び出される関数です。メソッドには二つの種類
があります: (リストへの :meth:`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`` は非バ
インドメソッドのクラス (サブクラス) のインスタンスでなければならず、そ
うでなければ :exc:`TypeError` が送出されます。

関数オブジェクトと同じく、メソッドオブジェクトは任意の属性を取得できま
す。しかし、メソッド属性は実際には背後の関数オブジェクト
(``meth.im_func``) に記憶されているので、バインド、非バインド、メソッ
ドへのメソッド属性の設定は許されていません。メソッド属性の設定を試みる
と :exc:`TypeError` が送出されます。メソッド属性を設定するためには、そ
の背後の関数オブジェクトで明示的に::

   class C:
       def method(self):
           pass

   c = C()
   c.method.im_func.whoami = 'my name is c'

詳細は、 :ref:`types` を参照下さい。


.. _bltin-code-objects:

コードオブジェクト
------------------

.. index:: object: code

.. index::
   builtin: compile
   single: func_code (function object attribute)

コードオブジェクトは、関数本体のような "擬似コンパイルされた" Python
の実行可能コードを表すために実装系によって使われます。
コードオブジェクトはグローバルな実行環境への参照を持たない点で関数オブ
ジェクトとは異なります。コードオブジェクトは組み込み関数
:func:`compile` によって返され、関数オブジェクトの :attr:`func_code`
属性として取り出すことができます。 :mod:`code` も参照下さい。

.. index::
   statement: exec
   builtin: eval

コードオブジェクトは :keyword:`exec` 文や組み込み関数 :func:`eval` に
(ソースコード文字列の代わりに) 渡すことで、実行したり値評価したりする
ことができます。

詳細は、 :ref:`types` を参照下さい。


.. _bltin-type-objects:

型オブジェクト
--------------

.. index::
   builtin: type
   module: types

型オブジェクトは様々なオブジェクト型を表します。オブジェクトの型は組み
込み関数 :func:`type` でアクセスされます。型オブジェクトには特有の操作
はありません。標準モジュール :mod:`types` には全ての組み込み型名が定義
されています。

型は ``<type 'int'>`` のように書き表されます。


.. _bltin-null-object:

ヌルオブジェクト
----------------

このオブジェクトは明示的に値を返さない関数によって返されます。このオブ
ジェクトには特有の操作はありません。ヌルオブジェクトは一つだけで、
``None`` (組み込み名) と名づけられています。

``None`` と書き表されます。


.. _bltin-ellipsis-object:

省略表記オブジェクト
--------------------

このオブジェクトは拡張スライス表記によって使われます (:ref:`slicings`
を参照下さい)。特殊な操作は何もサポートしていません。省略表記オブジェ
クトは一つだけで、その名前は :const:`Ellipsis` (組み込み名) です。

``Ellipsis`` と書き表されます。


ブール値
--------

ブール値とは二つの定数オブジェクト ``False`` および ``True`` です。こ
れらは真偽値を表すために使われます (他の値も偽または真とみなされます)
数値処理のコンテキスト (例えば算術演算子の引数として使われた場合) では、
これらはそれぞれ 0 および 1 と同様に振舞います。
任意の値に対して真偽値を変換できる場合、組み込み関数 :func:`bool` は値
をブール値にキャストするのに使われます (真理値テストの節を参照してくださ
い) 。

.. index::
   single: False
   single: True
   pair: Boolean; values

これらはそれぞれ ``False`` および ``True`` と書き表されます。


.. _typesinternal:

内部オブジェクト
----------------

スタックフレームオブジェクト、トレースバックオブジェクト、スライスオブ
ジェクト関しては、 :ref:`types` を参照下さい。


.. _specialattrs:

特殊な属性
==========

実装では、いくつかのオブジェクト型に対して、数個の読み出し専用の特殊な
属性を追加しています。それぞれ:


.. attribute:: object.__dict__

   オブジェクトの (書き込み可能な) 属性を保存するために使われる辞書ま
   たは他のマップ型オブジェクトです。


.. attribute:: object.__methods__

   .. deprecated:: 2.2
      オブジェクトの属性からなるリストを取得するには、組み込み関数
      :func:`dir` を使ってください。この属性はもう利用できません。


.. attribute:: object.__members__

   .. deprecated:: 2.2
      オブジェクトの属性からなるリストを取得するには、組み込み関数
      :func:`dir` を使ってください。この属性はもう利用できません。


.. attribute:: instance.__class__

   クラスインスタンスが属しているクラスです。


.. attribute:: class.__bases__

   クラスオブジェクトの基底クラスからなるタプルです。


.. attribute:: class.__name__

    クラスまたは型の名前です。


以下の属性は、新しいクラス (:term:`new-style class`) でのみサポートされます。

.. attribute:: class.__mro__

   この属性はメソッドの解決に探索される基底クラスのタプルです。


.. method:: class.mro()

   このメソッドは、メタクラスによって、そのインスタンスのメソッド解決
   の順序をカスタマイズするために、上書きされるかも知れません。
   これは、クラスインスタンスの作成と呼び、その結果は :attr:`__mro__`
   に格納されます。


.. method:: class.__subclasses__

   それぞれの新しいクラスは、それ自身の直接のサブクラスへの弱参照を保
   持します。このメソッドはそれらの参照のうち、生存しているもののリス
   トを返します。
   例 ::

      >>> int.__subclasses__()
      [<type 'bool'>]


.. rubric:: 注記

.. [#] これらの特殊なメソッドのさらなる情報は、 Python リファレンスマ
   ニュアル (:ref:`customization`) を参照下さい。


.. [#] この結果として、リスト ``[1, 2]`` は ``[1.0, 2.0]`` と等しいと
   見なされます。タプルの場合も同様です。

.. [#] パーザが被演算子の型を識別できるようにするために、このような優
   先度でなければならないのです。

.. [#] 従って、一個のタプルだけをフォーマット出力したい場合には出力し
   たいタプルを唯一の要素とする単一のタプルを *values* に与えなくては
   なりません。

.. [#] 改行を残す利点は、空の文字列が返ると EOF を示し、紛らわしくなく
   なるからです。また、ファイルの最後の行が改行で終わっているかそうで
   ない (ありえることです!) か (例えば、ファイルを行単位で読みながらそ
   の完全なコピーを作成した場合には問題になります) を調べることができ
   ます。
