5. 組み込み型

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

注釈

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

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

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

5.1. 真理値判定

どのオブジェクトも真理値を判定でき、 ifwhile 条件に、または以下のブール演算の被演算子に使えます。以下の値は偽と見なされます:

  • None

  • False

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

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

  • 空のマッピング。例えば {}

  • ユーザ定義クラスのインスタンスで、そのクラスが __nonzero__() または __len__() メソッドを定義していれば、それらのメソッドが整数 0 または boolFalse を返すとき。 [1]

それ以外の全ての値は真と見なされます — 従って、多くの型のオブジェクトは常に真です。

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

5.2. ブール演算 — and, or, not

以下にブール演算を、優先順位が低い順に示します:

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

注釈:

  1. この演算子は短絡評価されます。つまり第一引数が偽のときにのみ、第二引数が評価されます。
  2. この演算子は短絡評価されます。つまり第一引数が真のときにのみ、第二引数が評価されます。
  3. not は非ブール演算子よりも優先度が低いので、 not a == bnot (a == b) と解釈され、 a == not b は構文エラーです。

5.3. 比較

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

以下の表に比較演算をまとめます:

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

注釈:

  1. !=<> とも書けますがこれは時代遅れの書き方で、後方互換性維持のためだけに残されています。新しいコードでは常に != を使うべきです。

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

あるクラスの同一でないインスタンスは、通常等価でないとされますが、そのクラスが __eq__() メソッドか __cmp__() メソッドを定義している場合は除きます。

クラスのインスタンスは、そのクラスが十分なだけの拡張比較メソッド (__lt__(), __le__(), __gt__(), __ge__()) または __cmp__() メソッドを定義していない限り、同じクラスの別のインスタンスや他の型のオブジェクトとは順序付けできません。

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

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

5.4. 数値型 int, float, long, complex

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

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

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

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

演算 結果 注釈
x + y xy の和  
x - y xy の差  
x * y xy の積  
x / y xy の商 (1)
x // y xy の商 (を切り下げたもの) (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)(4)
pow(x, y) xy (3)(7)
x ** y xy (7)

注釈:

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

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

  3. 完全な記述については、 組み込み関数,を参照してください。

  4. バージョン 2.3 で撤廃: 切り捨て除算演算子、モジュロ演算子、および divmod() 関数は、複素数に対してはもはや定義されていません。目的に合うならば、代わりに abs() を使って浮動小数点に変換してください。

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

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

    バージョン 2.6 で追加.

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

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

演算 結果
math.trunc(x) xIntegral (整数) に切り捨てます
round(x[, n]) xn 桁に丸めます。丸め方は四捨五入です。 n が省略されれば 0 がデフォルトとなります。(–訳注: Python 3 と仕様が違うので注意してください。1.5 と 2.5 の round は、Python 2 ではそれぞれ 2、3 となり、Python 3 では 2、2 となります。後者の丸めは .5 を丸める際に偶数になる方へ丸めるので、「偶数丸め」と言います。–)
math.floor(x) x 以下の最大の整数を浮動小数点数として返します
math.ceil(x) x 以上の最小の整数を浮動小数点数として返します

5.4.1. 整数型におけるビット単位演算

ビット単位演算は、整数に対してのみ意味があります。負の数は、その 2 の補数の値として扱われます (演算中にオーバフローが起こらないように十分なビット数があるものと仮定します) 。

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

以下の表では、ビット単位演算を優先順位が低い順に並べています:

演算 結果 注釈
x | y xy のビット単位 論理和  
x ^ y xy のビット単位 排他的論理和  
x & y xy のビット単位 論理積  
x << n xn ビット左シフト (1)(2)
x >> n xn ビット右シフト (1)(3)
~x x のビット反転  

注釈:

  1. 負値のシフト数は不正であり、 ValueError が送出されます。
  2. n ビットの左シフトは、 pow(2, n) による乗算と等価です。通常整数の範囲を超える結果になる場合は長整数で返されます。
  3. n ビットの右シフトは、 pow(2, n) による除算と等価です。

5.4.2. 整数型における追加のメソッド

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

int.bit_length()
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

バージョン 2.7 で追加.

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

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

float.as_integer_ratio()

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

バージョン 2.6 で追加.

float.is_integer()

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

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

バージョン 2.6 で追加.

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

float.hex()

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

バージョン 2.6 で追加.

float.fromhex(s)

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

バージョン 2.6 で追加.

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

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

[sign] ['0x'] integer ['.' fraction] ['p' exponent]

sign は必須ではなく、 +- のどちらかです。 integerfraction は 16 進数の文字列で、 exponent は 10 進数で符号もつけられます。大文字・小文字は区別されず、最低でも 1 つの 16 進数文字を整数部もしくは小数部に含む必要があります。この制限は C99 規格のセクション 6.4.4.2 で規定されていて、 Java 1.5 以降でも使われています。特に、 float.hex() の出力は C や Java コード中で、浮動小数点数の 16 進表記として役に立つでしょう。また、 C の %a 書式や、 Java の Double.toHexString で書きだされた文字列は 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'

5.5. イテレータ型

バージョン 2.2 で追加.

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

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

container.__iter__()

イテレータオブジェクトを返します。オブジェクトは後述するイテレータプロトコルをサポートする必要があります。もしコンテナが異なる型の反復処理をサポートするなら、それらの反復処理毎に追加のメソッドを提供しても構いません (複数の形式の反復処理を提供するオブジェクトの例として、幅優先探索と深さ優先探索をサポートする木構造が挙げられます)。このメソッドは Python/C API での Python オブジェクトの型構造体の tp_iter スロットに対応します。

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

iterator.__iter__()

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

iterator.next()

コンテナの次のアイテムを返します。もしそれ以上アイテム無ければ StopIteration 例外を送出します。 このメソッドは Python/C APIでのPythonオブジェクトの型構造体の tp_iternext スロットに対応します。

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

このプロトコルでは、イテレータの next() メソッドが一旦 StopIteration を送出したなら、以降の呼び出しでも例外を送出し続けることを期待します。この特性に従わない実装は壊れているとみなされます。(この制約は Python 2.3 で追加されました。Python 2.2 では色々なイテレータが、このルールによれば壊れています。)

5.5.1. ジェネレータ型

Python における generator (ジェネレータ) は、イテレータプロトコルを実装する便利な方法を提供します。コンテナオブジェクトの __iter__() メソッドがジェネレータとして実装されていれば、そのメソッドは __iter__() および next() メソッドを提供するイテレータオブジェクト (厳密にはジェネレータオブジェクト) を自動的に返します。ジェネレータに関する詳細な情報は、 yield 式のドキュメント にあります。

5.6. シーケンス型 — str, unicode, list, tuple, bytearray, buffer, xrange

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

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

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

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

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

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

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

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

演算 結果 注釈
x in s s のある要素が x と等しければ True , そうでなければ False (1)
x not in s s のある要素が x と等しければ False, そうでなければ True (1)
s + t st の結合 (6)
s * n または n * s s 自身を n 回足すのと同じ (2)
s[i] s の 0 から数えて i 番目の要素 (3)
s[i:j] si から j までのスライス (3)(4)
s[i:j:k] si から j まで、 k 毎のスライス (3)(5)
len(s) s の長さ  
min(s) s の最小の要素  
max(s) s の最大の要素  
s.index(x) s 中で x が最初に出現するインデックス  
s.count(x) s 中に x が出現する回数  

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

注釈:

  1. s が文字列または Unicode 文字列の場合、演算操作 in および not in は部分文字列の一致テストと同じように動作します。バージョン 2.3 以前の Python では、 x は長さ 1 の文字列である必要がありました。 Python 2.3 以降では、 x はどんな長さでも構いません。

  2. n0 以下の値の場合、 0 として扱われます (これは s と同じ型の空のシーケンスを表します)。シーケンス s の要素はコピーされないので注意してください; コピーではなく要素に対する参照カウントが増えます。これは Python に慣れていないプログラマをよく悩ませます。例えば以下のコードを考えます:

    >>> lists = [[]] * 3
    >>> lists
    [[], [], []]
    >>> lists[0].append(3)
    >>> lists
    [[3], [3], [3]]
    

    ここで、[[]] が空リストを含む 1 要素のリストなので、[[]] * 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]]
    

    別の説明が FAQ エントリ 多次元のリストを作るにはどうしますか? にあります。

  3. i または j が負の数の場合、インデクスはシーケンスの末端からの相対インデクスになります: len(s) + i または len(s) + j が代わりに使われます。ただし -0 はやはり 0 であることに注意してください。

  4. si から j へのスライスは i <= k < j となるようなインデクス k を持つ要素からなるシーケンスとして定義されます。 i または jlen(s) よりも大きい場合、 len(s) を使います。 i が省略されるか None だった場合、 0 を使います。 j が省略されるか None だった場合、 len(s) を使います。 ij 以上の場合、スライスは空のシーケンスになります。

  5. s の「 i から j まででステップが k のスライス」は、インデックス x = i + n*k (ただし n は 0 <= n < (j-i)/k を満たす任意の整数)を持つ要素からなるシーケンスとして定義されます。言い換えるとインデックスは i, i+k, i+2*k, i+3*k と続き、 j に達したところでストップします (ただし j は含みません)。 k が正の数である場合、 i または jlen(s) より大きければ len(s) を代わりに使用します。 k が負の数である場合、 i または jlen(s) - 1 より大きければ len(s) - 1 を代わりに使用します。 i または j を省略または None を指定すると、 "端" (どちらの端かは k の符号に依存) の値を代わりに使用します。なお k はゼロにできないので注意してください。また kNone を指定すると、 1 が指定されたものとして扱われます。

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

    バージョン 2.4 で変更: 以前、文字列の連結はin-placeで再帰されませんでした.

5.6.1. 文字列メソッド

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

さらに、 Python の文字列は シーケンス型 — str, unicode, list, tuple, bytearray, buffer, xrange に記載されるシーケンス型のメソッドもサポートします。書式指定して文字列を出力するためには、テンプレート文字列を使うか、 文字列フォーマット操作 に記載される % 演算子を使います。正規表現に基づく文字列操作関数については、 re モジュールを参照下さい。

str.capitalize()

最初の文字を大文字にし、残りを小文字にした文字列のコピーを返します。

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

str.center(width[, fillchar])

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

バージョン 2.4 で変更: 引数 fillchar に対応.

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

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

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

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

バージョン 2.2 で追加.

バージョン 2.3 で変更: その他のエラーハンドリングスキーマがサポートされました.

バージョン 2.7 で変更: キーワード引数のサポートが追加されました。

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

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

バージョン 2.0 で追加.

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

バージョン 2.7 で変更: キーワード引数のサポートが追加されました。

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

文字列が指定された suffix で終わるなら True を、そうでなければ False を返します。 suffix は見つけたい複数の接尾語のタプルでも構いません。オプションの start があれば、その位置から判定を始めます。オプションの end があれば、その位置で比較を止めます。

バージョン 2.5 で変更: suffix でタプルを受け付けるようになりました.

str.expandtabs([tabsize])

文字列内の全てのタブ文字が 1 つ以上のスペースで置換された、文字列のコピーを返します。スペースの数は現在の桁 (column) 位置と tabsize に依存します。タブ位置は tabsize 文字毎に存在します (デフォルト値である 8 の場合、タブ位置は 0, 8, 16 などになります)。文字列を展開するため、まず現桁位置がゼロにセットされ、文字列が 1 文字ずつ調べられます。文字がタブ文字 (\t) であれば、現桁位置が次のタブ位置と一致するまで、1 つ以上のスペースが結果の文字列に挿入されます。(タブ文字自体はコピーされません。) 文字が改行文字 (\n もしくは \r) の場合、文字がコピーされ、現桁位置は 0 にリセットされます。その他の文字は変更されずにコピーされ、現桁位置は、その文字の表示のされ方 (訳注: 全角、半角など) に関係なく、1 ずつ増加します。

>>> '01\t012\t0123\t01234'.expandtabs()
'01      012     0123    01234'
>>> '01\t012\t0123\t01234'.expandtabs(4)
'01  012 0123    01234'
str.find(sub[, start[, end]])

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

注釈

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

>>> 'Py' in 'Python'
True
str.format(*args, **kwargs)

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

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

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

この文字列書式指定のメソッドは Python 3 での新しい標準であり、新しいコードでは、 文字列フォーマット操作 で規定される % を使った書式指定より好ましい書き方です。

バージョン 2.6 で追加.

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

find() と同様ですが、 sub が見つからなかった場合 ValueError を送出します。

str.isalnum()

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

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

str.isalpha()

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

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

str.isdigit()

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

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

str.islower()

文字列中の大小文字の区別のある文字 [4] 全てが小文字で、かつ大小文字の区別のある文字が 1 文字以上あるなら真を、そうでなければ偽を返します。

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

str.isspace()

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

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

str.istitle()

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

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

str.isupper()

文字列中の大小文字の区別のある文字 [4] 全てが大文字で、かつ大小文字の区別のある文字が 1 文字以上あるなら真を、そうでなければ偽を返します。

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

str.join(iterable)

イテラブル 中の文字列を結合した文字列オブジェクトを返します。 iterable に Unicode オブジェクトがある場合は、代わりに Unicode を返します。文字列でないあるいは Unicode オブジェクトでない値が存在する場合は、 TypeError が送出されます。要素間の区切り文字列は、このメソッドを提供する文字列です。

str.ljust(width[, fillchar])

長さ width の左揃えした文字列を返します。パディングは指定された fillchar (デフォルトではスペース) を使って行われます。 widthlen(s) 以下ならば、元の文字列が返されます。

バージョン 2.4 で変更: 引数 fillchar に対応.

str.lower()

全ての大小文字の区別のある文字 [4] が小文字に変換された、文字列のコピーを返します。

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

str.lstrip([chars])

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

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

バージョン 2.2.2 で変更: 引数 chars をサポートしました.

str.partition(sep)

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

バージョン 2.5 で追加.

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

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

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

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

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

rfind() と同様ですが、 sub が見つからなかった場合 ValueError を送出します。

str.rjust(width[, fillchar])

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

バージョン 2.4 で変更: 引数 fillchar に対応.

str.rpartition(sep)

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

バージョン 2.5 で追加.

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

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

バージョン 2.4 で追加.

str.rstrip([chars])

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

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

バージョン 2.2.2 で変更: 引数 chars をサポートしました.

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

文字列を sep をデリミタ文字列として区切った単語のリストを返します。maxsplit が与えられていれば、最大で maxsplit 回分割されます (つまり、リストは最大 maxsplit+1 要素になります)。 maxsplit が与えられないか -1 なら、分割の回数に制限はありません (可能なだけ分割されます)。

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  '] を返します。

str.splitlines([keepends])

文字列を改行部分で分解し、各行からなるリストを返します。 このメソッドは、行の分割に universal newlines アプローチを使います。keepends に真が与えらない限り、返されるリストに改行は含まれません。

Python は "\r", "\n", "\r\n" を 8-bit 文字列の行の境界として認識します。

例えば:

>>> 'ab c\n\nde fg\rkl\r\n'.splitlines()
['ab c', '', 'de fg', 'kl']
>>> 'ab c\n\nde fg\rkl\r\n'.splitlines(True)
['ab c\n', '\n', 'de fg\r', 'kl\r\n']

split() とは違って、デリミタ文字列 sep が与えられたとき、このメソッドは空文字列に空リストを返し、終末の改行は結果に行を追加しません:

>>> "".splitlines()
[]
>>> "One line\n".splitlines()
['One line']

比較のために split('\n') は以下のようになります:

>>> ''.split('\n')
['']
>>> 'Two lines\n'.split('\n')
['Two lines', '']
unicode.splitlines([keepends])

str.splitlines() のように、文字列を行のリストにして返します。ただし Unicode のメソッドでは、8-bit 文字列の行の境界として認識される universal newlines よりも多くの次に挙げる行の境界で分割します。

表現 説明
\n 改行
\r 復帰
\r\n 改行 + 復帰
\v or \x0b 垂直タブ
\f or \x0c 改ページ
\x1c ファイル区切り
\x1d グループ区切り
\x1e レコード区切り
\x85 改行 (C1 制御コード)
\u2028 行区切り
\u2029 段落区切り

バージョン 2.7 で変更: \v\f が行境界のリストに追加されました。

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

文字列が指定された prefix で始まるなら True を、そうでなければ False を返します。 prefix は見つけたい複数の接頭語のタプルでも構いません。オプションの start があれば、その位置から判定を始めます。オプションの end があれば、その位置で比較を止めます。

バージョン 2.5 で変更: prefix でタプルを受け付けるようになりました.

str.strip([chars])

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

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

バージョン 2.2.2 で変更: 引数 chars をサポートしました.

str.swapcase()

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

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

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ビット文字列では、メソッドはロケール依存になります。

str.translate(table[, deletechars])

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

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

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

バージョン 2.6 で追加: Nonetable 引数をサポートしました。

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

str.upper()

Return a copy of the string with all the cased characters [4] converted to uppercase. Note that str.upper().isupper() might be False if s contains uncased characters or if the Unicode category of the resulting character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter, titlecase).

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

str.zfill(width)

数値文字列の左側をゼロ詰めし、幅 width の文字列で返します。符号接頭辞も正しく扱われます。 widthlen(s) 以下の場合もとの文字列自体が返されます。

バージョン 2.2.2 で追加.

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

unicode.isnumeric()

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

unicode.isdecimal()

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

5.6.2. 文字列フォーマット操作

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

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

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

  1. 指定子の開始を示す文字 '%'
  2. マップキー (オプション)。丸括弧で囲った文字列からなります (例えば (somename)) 。
  3. 変換フラグ (オプション)。一部の変換型の結果に影響します。
  4. 最小のフィールド幅 (オプション)。 '*' (アスタリスク) を指定した場合、実際の文字列幅が values タプルの次の要素から読み出されます。タプルには最小フィールド幅やオプションの精度指定の後に変換したいオブジェクトがくるようにします。
  5. 精度 (オプション)。 '.' (ドット) とその後に続く精度で与えられます。 '*' (アスタリスク) を指定した場合、精度の桁数は values タプルの次の要素から読み出されます。タプルには精度指定の後に変換したい値がくるようにします。
  6. 精度長変換子 (オプション)。
  7. 変換型。

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

>>> 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' 旧式の型 – 'd' と同じです。 (7)
'x' 符号付き 16 進数 (小文字)。 (2)
'X' 符号付き 16 進数 (大文字)。 (2)
'e' 指数表記の浮動小数点数 (小文字)。 (3)
'E' 指数表記の浮動小数点数 (大文字)。 (3)
'f' 10 進浮動小数点数。 (3)
'F' 10 進浮動小数点数。 (3)
'g' 浮動小数点数。指数部が -4 以上または精度以下の場合には小文字指数表記、それ以外の場合には10進表記。 (4)
'G' 浮動小数点数。指数部が -4 以上または精度以下の場合には大文字指数表記、それ以外の場合には10進表記。 (4)
'c' 文字一文字 (整数または一文字からなる文字列を受理します)。  
'r' 文字列 (Python オブジェクトを repr() で変換します)。 (5)
's' 文字列 (Python オブジェクトを str() で変換します)。 (6)
'%' 引数を変換せず、返される文字列中では文字 '%' になります。  

注釈:

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

  2. 別の形式を指定(訳注: 変換フラグ # を使用)すると 16 進数を表す接頭辞 '0x' または '0X' (使用するフォーマット文字が 'x''X' に依存します) が最初の数字の前に挿入されます。

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

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

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

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

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

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

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

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

  7. PEP 237 を参照してください。

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

バージョン 2.7 で変更: 絶対値が 1e50 を超える数値の %f 変換が %g 変換に置き換えられなくなりました。

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

5.6.3. XRange 型

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

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

5.6.4. ミュータブルなシーケンス型

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

演算 結果 注釈
s[i] = x s の要素 ix と入れ替えます  
s[i:j] = t si から 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(t) または s += t s[len(s):len(s)] = t とほとんど同じです (3)
s *= n s をその内容を n 回繰り返したもので更新 (11)
s.count(x) s[i] == x となる i の個数を返します  
s.index(x[, i[, j]]) s[k] == x かつ i <= k < j となる最小の k を返します (4)
s.insert(i, x) s[i:i] = [x] と同じです (5)
s.pop([i]) x = s[i]; del s[i]; return x と同じです (6)
s.remove(x) del s[s.index(x)] と同じです (4)
s.reverse() s をインプレースに逆転させます (7)
s.sort([cmp[, key[, reverse]]]) s の要素をインプレースに並べ替えます (7)(8)(9)(10)

注釈:

  1. t は置き換えるスライスと同じ長さでなければいけません。

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

  3. x は任意のイテラブルオブジェクトにできます。

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

    バージョン 2.3 で変更: 以前は index() には開始と終了位置を指定する引数がありませんでした。

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

    バージョン 2.3 で変更: 以前は、すべての負値は 0 に丸められていました。

  6. pop() メソッドのオプションの引数 i は標準で -1 なので、標準では最後の要素をリストから除去して返します。

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

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

    cmp は2つの引数 (リストの要素) からなるカスタムの比較関数を指定します。 これは始めの引数が 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 関数に変換するには functools.cmp_to_key() を使用してください。

    バージョン 2.3 で変更: None を渡すのと、 cmp を省略した場合とで、同等に扱うサポートを追加.

    バージョン 2.4 で変更: key および reverse のサポートを追加.

  9. Python 2.3 より、 sort() メソッドは安定していることが保証されています。ソートは、等しい要素の相対順序が変更されないことが保証されていれば、安定しています — これは複合的なパスでソートを行なう(例えば部署でソートして、それから給与の等級でソートする)のに役立ちます。

  10. CPython 実装の詳細: リストがソートされている間、または変更しようとする試みの影響中、あるいは検査中でさえ、リストは未定義です。Python 2.3 とそれ以降の C 実装では、それらが続いている間、リストは空として出力され、リストがソート中に変更されていることを検知できたら ValueError を送出します。

  11. n は整数または __index__() を実装したオブジェクトです。 n にゼロや負数を与えると、シーケンスをクリアします。シーケンス内の要素はコピーされません; コピーではなく要素に対する参照カウントが増えます。 s * n について シーケンス型 — str, unicode, list, tuple, bytearray, buffer, xrange で説明したとおりです。

5.7. set(集合)型 — set, frozenset

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

バージョン 2.4 で追加.

集合は、他のコレクションと同様、 x in set, len(set), for x in set をサポートします。コレクションには順序がないので、集合は挿入の順序や要素の位置を記録しません。従って、集合はインデクシング、スライシング、その他のシーケンス的な振舞いをサポートしません。

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

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

どちらのクラスのコンストラクタも同様に働きます:

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

iterable から要素を取り込んだ、新しい set もしくは frozenset オブジェクトを返します。 集合の要素は ハッシュ可能 なものでなくてはなりません。集合の集合を表現するためには、内側の集合は frozenset オブジェクトでなくてはなりません。iterable が指定されない場合、新しい空の集合が返されます。

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

len(s)

集合 s の要素数 (s の濃度) を返します。

x in s

xs のメンバーに含まれるか判定します。

x not in s

xs のメンバーに含まれていないことを判定します。

isdisjoint(other)

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

バージョン 2.6 で追加.

issubset(other)
set <= other

set の全ての要素が other に含まれるか判定します。

set < other

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

issuperset(other)
set >= other

other の全ての要素が set に含まれるか判定します。

set > other

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

union(*others)
set | other | ...

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

バージョン 2.6 で変更: 複数のイテラブルからの入力を受け入れるようになりました。

intersection(*others)
set & other & ...

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

バージョン 2.6 で変更: 複数のイテラブルからの入力を受け入れるようになりました。

difference(*others)
set - other - ...

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

バージョン 2.6 で変更: 複数のイテラブルからの入力を受け入れるようになりました。

symmetric_difference(other)
set ^ other

set と other のいずれか一方だけに含まれる要素を持つ新しい集合を返します。

copy()

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

なお、演算子でない版の union(), intersection(), difference(), symmetric_difference(), issubset(), issuperset() メソッドは、任意のイテラブルを引数として受け付けます。対して、演算子を使う版では、引数は集合でなくてはなりません。これは、set('abc') & 'cbs' のような誤りがちな構文を予防し、より読みやすい set('abc').intersection('cbs') を支持します。

setfrozenset のどちらも、集合同士の比較をサポートします。二つの集合は、それぞれの集合の要素全てが他方にも含まれている (互いに他方の部分集合である) とき、かつそのときに限り等しいです。一方の集合が他方の集合の真部分集合である (部分集合であるが等しくない) とき、かつそのときに限り一方の集合は他方の集合より小さいです。一方の集合が他方の集合の真上位集合である (上位集合であるが等しくない) とき、かつそのときに限り一方の集合は他方の集合より大きいです。

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

部分集合と等価性の比較は全順序付けを行う関数へと一般化することはできません。例えば、互いに素である二つの非空集合は、等しくなく、他方の部分集合でもありませんから、以下の すべてFalse を返します: a<b, a==b, そして a>b 。そのため、 set は __cmp__() メソッドを実装しません。

集合は半順序(部分集合関係)しか定義しないので、集合のリストにおける list.sort() メソッドの出力は未定義です。

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

set インスタンスと frozenset インスタンスを取り混ぜての二項演算は、第一被演算子の型を返します。例えば: frozenset('ab') | set('bc')frozenset インスタンスを返します。

以下の表に挙げる演算は set に適用されますが、frozenset のイミュータブルなインスタンスには適用されません:

update(*others)
set |= other | ...

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

バージョン 2.6 で変更: 複数のイテラブルからの入力を受け入れるようになりました。

intersection_update(*others)
set &= other & ...

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

バージョン 2.6 で変更: 複数のイテラブルからの入力を受け入れるようになりました。

difference_update(*others)
set -= other | ...

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

バージョン 2.6 で変更: 複数のイテラブルからの入力を受け入れるようになりました。

symmetric_difference_update(other)
set ^= other

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

add(elem)

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

remove(elem)

要素 elem を set から取り除きます。elem が set に含まれていなければ KeyError を送出します。

discard(elem)

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

pop()

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

clear()

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

なお、演算子でない版の update(), intersection_update(), difference_update(), および symmetric_difference_update() メソッドは、任意のイテラブルを引数として受け付けます。

__contains__(), remove(), discard() メソッドの引数 elem は集合かもしれないことに注意してください。その集合と等価な frozenset の検索をサポートするために、 elem から一時的な frozenset を作成します。

参考

組み込み set 型との比較
sets モジュールと組み込み set 型の違い

5.8. マッピング型 — dict

マッピング (mapping) オブジェクトは、ハッシュ可能 (hashable) な値を任意のオブジェクトに対応付けます。マッピングはミュータブルなオブジェクトです。現在、標準マッピング型は辞書 (dictionary) だけです。 (他のコンテナについては組み込みの list, set, および tuple クラスと、 collections モジュールを参照下さい。)

辞書のキーは ほぼ 任意の値です。ハッシュ可能 (hashable) でない値、つまり、リストや辞書その他のミュータブルな型 (オブジェクトの同一性ではなく値で比較されるもの) はキーとして使用できません。キーとして使われる数値型は通常の数値比較のルールに従います: もしふたつの数値が (例えば 11.0 のように) 等しければ、同じ辞書の項目として互換的に使用できます。 (ただし、コンピュータは浮動小数点数を近似値として保管するので、辞書型のキーとして使用するのはたいてい賢くありません。)

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

class dict(**kwarg)
class dict(mapping, **kwarg)
class dict(iterable, **kwarg)

オプションの位置引数と空集合の可能性もあるキーワード引数から初期化された新しい辞書を返します。

位置引数が何も与えられなかった場合、空の辞書が作成されます。位置引数が与えられ、それがマッピングオブジェクトだった場合、そのマッピングオブジェクトと同じキーと値のペアを持つ辞書が作成されます。それ以外の場合、位置引数は iterable オブジェクトでなければなりません。iterable のそれぞれの要素自身は、ちょうど 2 個のオブジェクトを持つイテラブルでなければなりません。それぞれの要素の最初のオブジェクトは新しい辞書のキーになり、2 番目のオブジェクトはそれに対応する値になります。同一のキーが 2 回以上現れた場合は、そのキーの最後の値が新しい辞書での対応する値になります。

キーワード引数が与えられた場合、キーワード引数とその値が位置引数から作られた辞書に追加されます。既に存在しているキーが追加された場合、キーワード引数の値は位置引数の値を置き換えます。

例を出すと、次の例は全て {"one": 1, "two": 2, "three": 3} に等しい辞書を返します:

>>> a = dict(one=1, two=2, three=3)
>>> b = {'one': 1, 'two': 2, 'three': 3}
>>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))
>>> d = dict([('two', 2), ('one', 1), ('three', 3)])
>>> e = dict({'three': 3, 'one': 1, 'two': 2})
>>> a == b == c == d == e
True

最初の例のようにキーワード引数を与える方法では、キーは有効な Python の識別子でなければなりません。それ以外の方法では、辞書のキーとして有効などんなキーでも使えます。

バージョン 2.2 で追加.

バージョン 2.3 で変更: キーワード引数からの辞書型の作成のサポートが追加されました。

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

len(d)

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

d[key]

d のキー key の項目を返します。マップに key が存在しなければ、 KeyError を送出します。

辞書のサブクラスが __missing__() メソッドを定義しておらず、 key が存在しないなら、 d[key] 演算はこのメソッドをキー key を引数として呼び出します。結果として、 d[key] 演算は、キーが存在しなければ、 __missing__(key) の呼び出しによって返されまたは送出されたものを何でも、返しまたは送出します。他の演算やメソッドは __missing__() を呼び出しません。 __missing__() が定義されていなければ、 KeyError が送出されます。 __missing__() はメソッドでなければならず、インスタンス変数であってはなりません:

>>> class Counter(dict):
...     def __missing__(self, key):
...         return 0
>>> c = Counter()
>>> c['red']
0
>>> c['red'] += 1
>>> c['red']
1

ここでお見せした例は collections.Counter 実装の一部です。これとは違った __missing__ が:class:collections.defaultdict で使われています。

バージョン 2.5 で追加: 辞書のサブクラスで __missing__ メソッドを認識するようになりました。

d[key] = value

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

del d[key]

d から d[key] を削除します。マップに key が存在しなければ、 KeyError を送出します。

key in d

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

バージョン 2.2 で追加.

key not in d

not key in d と等価です。

バージョン 2.2 で追加.

iter(d)

辞書のキーに渡るイテレータを返します。これは iterkeys() へのショートカットです。

clear()

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

copy()

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

fromkeys(seq[, value])

seq からキーを取り、値を value に設定した、新しい辞書を作成します。

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

バージョン 2.3 で追加.

get(key[, default])

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

has_key(key)

辞書に key が存在するかを確認します。 key in d が可能になっているので、 has_key() は廃れた用法です。

items()

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

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

items(), keys(), values(), iteritems(), iterkeys() および itervalues() は辞書に干渉して更新しなければ、返却順は直接対応関係にあります。つまり (value, key) の対を zip() を使って生成するとができます: pairs = zip(d.values(), d.keys())iterkeys()itervalues() でも同じです: pairs = zip(d.itervalues(), d.iterkeys()) は先と同じ値を返します。同じリストを得るには pairs = [(v, k) for (k, v) in d.iteritems()] としても出来ます。

iteritems()

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

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

バージョン 2.2 で追加.

iterkeys()

辞書のキーをイテレータで返します。 dict.items() の記述も参照下さい。

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

バージョン 2.2 で追加.

itervalues()

辞書の値をイテレータで返します。 dict.items() の記述も参照下さい。

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

バージョン 2.2 で追加.

keys()

辞書のキーのリストのコピーを返します。 dict.items() の記述も参照下さい。

pop(key[, default])

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

バージョン 2.3 で追加.

popitem()

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

集合のアルゴリズムで使われるのと同じように、 popitem() は辞書を破壊的にイテレートするのに便利です。辞書が空であれば、 popitem() の呼び出しは KeyError を送出します。

setdefault(key[, default])

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

update([other])

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

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

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

values()

辞書の値のリストのコピーを返します。 dict.items() の記述も参照下さい。

viewitems()

辞書のアイテム ((key, value) のペア) の新しいビューを返します。ビューオブジェクトについては下に説明があります。

バージョン 2.7 で追加.

viewkeys()

辞書のキーの新しいビューを返します。ビューオブジェクトについては下に説明があります。

バージョン 2.7 で追加.

viewvalues()

辞書の値の新しいビューを返します。ビューオブジェクトについては下に説明があります。

バージョン 2.7 で追加.

辞書は、同じ (key, value) の対を持つときのみ等しくなります。

5.8.1. 辞書ビューオブジェクト

dict.viewkeys(), dict.viewvalues(), dict.viewitems() によって返されるオブジェクトは、 ビューオブジェクト です。これらは、辞書の項目の動的なビューを提供し、辞書が変更された時、ビューはその変更を反映します。

辞書ビューは、イテレートすることで対応するデータを yield できます。また、帰属判定をサポートします:

len(dictview)

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

iter(dictview)

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

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

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

x in dictview

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

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

dictview & other

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

dictview | other

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

dictview - other

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

dictview ^ other

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

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

>>> 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'}

5.9. ファイルオブジェクト

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

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

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

file.close()

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

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

from __future__ import with_statement # This isn't required in 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()

注釈

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

file.flush()

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

注釈

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

file.fileno()

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

注釈

本物のファイルデスクリプタを持たないファイル類似のオブジェクトは、このメソッドを提供すべきでは ありません

file.isatty()

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

注釈

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

file.next()

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

バージョン 2.3 で追加.

file.read([size])

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

注釈

この関数は単純に、背後の C 関数 fread() のラッパーです。そのため、 EOF が予期せず検出されたりされなかったりといった個別の事情があっても同じように振舞うだけです。

file.readline([size])

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

注釈

C stdiofgets() と違い、入力中にヌル文字 ('\0') が含まれていれば、ヌル文字を含んだ文字列が返されます。

file.readlines([sizehint])

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

file.xreadlines()

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

バージョン 2.1 で追加.

バージョン 2.3 で撤廃: 代わりに for line in file を使ってください。

file.seek(offset[, whence])

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

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

バージョン 2.6 で変更: オフセットに浮動小数点数を渡すことは非推奨となりました。

file.tell()

C の stdioftell() のように、ファイルの現在位置を返します。

注釈

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

file.truncate([size])

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

file.write(str)

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

file.writelines(sequence)

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

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

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

file.closed

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

file.encoding

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

バージョン 2.3 で追加.

file.errors

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

バージョン 2.6 で追加.

file.mode

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

file.name

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

file.newlines

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

file.softspace

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

注釈

この属性は print 文を制御するために用いられるのではなく、 print の実装にその内部状態を追跡させるためにあります。

5.10. メモリビュー型

バージョン 2.7 で追加.

memoryview オブジェクトは、Python コードが、バッファプロトコルをサポートするオブジェクトの内部データへ、コピーすることなくアクセスすることを可能にします。メモリは通常、単純なバイト列として解釈されます。

class memoryview(obj)

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

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

len(view) は、メモリビュー view の要素の総数を返します。 itemsize 属性で一つの要素内のバイト数を取得できます。

memoryview はスライスしてデータを晒すことに対応しています。一つのインデクスを渡すと一つの要素を 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

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

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

tobytes()

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

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

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

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

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

format

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

itemsize

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

shape

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

ndim

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

strides

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

readonly

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

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

バージョン 2.5 で追加.

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

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

contextmanager.__enter__()

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

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

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

contextmanager.__exit__(exc_type, exc_val, exc_tb)

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

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

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

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

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

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

5.12. その他の組み込み型

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

5.12.1. モジュール

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

全てのモジュールにある特殊属性が __dict__ です。これはモジュールのシンボルテーブルを含む辞書です。この辞書を書き換えると実際にモジュールのシンボルテーブルを変更することができますが、__dict__ 属性を直接代入することはできません (m.__dict__['a'] = 1 と書いて m.a1 に定義することはできますが、m.__dict__ = {} と書くことはできません)。 __dict__ を直接書き換えることは推奨されません。

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

5.12.2. クラスおよびクラスインスタンス

これらについては オブジェクト、値、および型 および クラス定義 を参照下さい。

5.12.3. 関数

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

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

詳細は、 関数定義 を参照下さい。

5.12.4. メソッド

メソッドは属性表記を使って呼び出される関数です。メソッドには二種類あります: (リストの append() のような) 組み込みメソッドと、クラスインスタンスのメソッドです。組み込みメソッドは、それをサポートする型と一緒に記述されています。

実装では、クラスインスタンスのメソッドに 2 つの読み込み専用の属性を追加しています: m.im_self はメソッドが操作するオブジェクトで、 m.im_func はメソッドを実装している関数です。 m(arg-1, arg-2, ..., arg-n) の呼び出しは、 m.im_func(m.im_self, arg-1, arg-2, ..., arg-n) の呼び出しと完全に等価です。

クラスインスタンスメソッドには、メソッドがインスタンスからアクセスされるかクラスからアクセスされるかによって、それぞれ バインド (束縛) または 非バインド (非束縛) があります。メソッドが非バインドメソッドの場合、 im_self 属性は None になるため、呼び出す際には self オブジェクトを明示的に第一引数として指定しなければなりません。この場合、 self は非バインドメソッドのクラス (またはそのサブクラス) のインスタンスでなければならず、そうでなければ TypeError が送出されます。

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

>>> class C:
...     def method(self):
...         pass
...
>>> c = C()
>>> c.method.whoami = 'my name is method'  # can't set on the method
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'instancemethod' object has no attribute 'whoami'
>>> c.method.im_func.whoami = 'my name is method'
>>> c.method.whoami
'my name is method'

詳細は、 標準型の階層 を参照下さい。

5.12.5. コードオブジェクト

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

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

詳細は、 標準型の階層 を参照下さい。

5.12.6. 型オブジェクト

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

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

5.12.7. ヌルオブジェクト

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

None と書き表されます。

5.12.8. Ellipsis オブジェクト

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

Ellipsis と書き表されます。添え字として使う場合 ... とも書けます。例えば seq[...] のように。

5.12.9. NotImplemented オブジェクト

このオブジェクトは、対応していない型の演算を求められたとき、比較や二項演算から返されます。詳細は 比較 を参照してください。

NotImplemented と書き表されます。

5.12.10. ブール値

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

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

5.12.11. 内部オブジェクト

この情報は 標準型の階層 を参照下さい。スタックフレームオブジェクト、トレースバックオブジェクト、スライスオブジェクトについて記述されています。

5.13. 特殊属性

実装は、いくつかのオブジェクト型に対して、適切な場合には特殊な読み出し専用の属性を追加します。そのうちいくつかは dir() 組込み関数で報告されません。

object.__dict__

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

object.__methods__

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

object.__members__

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

instance.__class__

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

class.__bases__

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

definition.__name__

クラス、型、関数、メソッド、デスクリプタ、ジェネレータインスタンスの名前です。

以下の属性は、新スタイルクラス (new-style class) でのみサポートされます。

class.__mro__

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

class.mro()

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

class.__subclasses__()

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

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

注記

[1]これらの特殊なメソッドのさらなる情報は、 Python リファレンスマニュアル (基本的なカスタマイズ) を参照下さい。
[2]この結果として、リスト [1, 2][1.0, 2.0] と等しいと見なされます。タプルの場合も同様です。
[3]パーザが演算対象の型を識別できるようにするために、このような優先順位でなければならないのです。
[4](1, 2, 3, 4) 大小文字の区別のある文字とは、一般カテゴリプロパティが "Lu" (Letter, uppercase (大文字))、 "Ll" (Letter, lowercase (小文字))、 "Lt" (Letter、titlecase (先頭が大文字)) のいずれかであるものです。
[5]従って、一個のタプルだけをフォーマット出力したい場合には出力したいタプルを唯一の要素とする単一のタプルを values に与えなくてはなりません。
[6]改行を残す利点は、空の文字列が返ると EOF を示し、紛らわしくなくなるからです。また、ファイルの最後の行が改行で終わっているかそうでない (ありえることです!) か (例えば、ファイルを行単位で読みながらその完全なコピーを作成した場合には問題になります) を調べることができます。