5. 組み込み型

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

注釈

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

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

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

5.1. 真理値テスト

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

  • None

  • False

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

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

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

  • __nonzero__() または __len__() メソッドが定義されているようなユーザ定義クラスのインスタンスで、それらのメソッドが整数値ゼロまたは bool 値の False を返すとき。 [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. これは、短絡的な演算子であり、一つめの引数が False のときにのみ、二つめの引数を評価します。
  2. これは、短絡的な演算子であり、一つめの引数が True のときにのみ、二つめの引数を評価します。
  3. not は非ブール演算子よりも低い演算優先度なので、 not a == bnot (a == b) と評価され、 a == not b は構文エラーとなります。

5.3. 比較

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

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

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

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

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

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

同じ優先度を持つ演算子としてさらに 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)
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. 複素数の切り詰め除算演算子、モジュロ演算子、および divmod()

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

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

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

    バージョン 2.6 で追加.

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

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

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

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

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

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 進表記では浮動小数点数を、正確に表現することができます。これはデバッグのときや、数学的な用途に便利でしょう。

float.hex()

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

バージョン 2.6 で追加.

float.fromhex(s)

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

バージョン 2.6 で追加.

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

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

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

符号 はオプションで、 +- のどちらでも構いません。 整数部小数部 は 16 進数の文字列で、 指数部 はオプションで符号がつけられる 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 s および t の結合 (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(i) s 中で最初に i が現れる場所のインデクス  
s.count(i) s 中に i が現れる数  

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

注釈:

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

  2. n0 以下の値の場合、 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 が代入されます。しかし -00 のままなので注意してください。

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

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

  6. CPython implementation detail: st の両者が文字列であるとき、 CPython のような実装では、 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' およびその他のエラーハンドリングスキーマがサポートされました.

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

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

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

str.expandtabs([tabsize])

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

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.0 での新しい標準であり、新しいコードでは、 文字列フォーマット操作 で規定される % を使った書式指定より好ましい書き方です。

バージョン 2.6 で追加.

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

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

str.isalnum()

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

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

str.isalpha()

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

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

str.isdigit()

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

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

str.islower()

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

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

str.isspace()

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

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

str.istitle()

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

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

str.isupper()

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

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

str.join(iterable)

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

str.ljust(width[, fillchar])

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

バージョン 2.4 で変更: 引数 fillchar が追加されました.

str.lower()

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

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 個になるように分割が行なわれます、 最も右側 (の単語)は 1 つになります。 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 が指定されない場合、無制限に分割が行なわれます(全ての可能な分割が行なわれる)。

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])

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

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

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

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

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

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

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

  1. 変換指定子が開始することを示す文字 '%'
  2. マップキー (オプション)。丸括弧で囲った文字列からなります (例えば (someone)) 。
  3. 変換フラグ (オプション)。一部の変換型の結果に影響します。
  4. 最小のフィールド幅 (オプション)。 '*' (アスタリスク) を指定した場合、実際の文字列幅が values タプルの次の要素から読み出されます。タプルには最小フィールド幅やオプションの精度指定の後に変換したいオブジェクトがくるようにします。
  5. 精度 (オプション)。 '.' (ドット) とその後に続く精度で与えられます。 '*' (アスタリスク) を指定した場合、精度の桁数はタプルの次の要素から読み出されます。タプルには精度指定の後に変換したい値がくるようにします。
  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' 符号なし 10 進数。  
'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. この形式にした場合、変換結果の先頭の数字がゼロでないときには、数字の先頭と左側のパディングとの間に '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 の要素 sx と入れ替えます  
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(x) s[len(s):len(s)] = x と同じです (3)
s.count(x) s[i] == x となる i の個数を返します  
s.index(x[, i[, j]]) s[k] == x かつ i <= k < j となる最小の k を返します。 (4)
s.insert(i, x) i >= 0 の場合の s[i:i] = [x] と同じです (5)
s.pop([i]) x = s[i]; del s[i]; return x と同じです (6)
s.remove(x) del s[s.index(x)] と同じです (4)
s.reverse() s の値の並びを反転します (7)
s.sort([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つの引数 (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 関数に変換するには functools.cmp_to_key() を使用してください。

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

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

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

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

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

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

バージョン 2.4 で追加.

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

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

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

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

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

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

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

len(s)

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

x in s

xs のメンバーに含まれるか確認します。

x not in s

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

isdisjoint(other)

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

バージョン 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(other, ...)
set | other | ...

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

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

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

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

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

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

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

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

symmetric_difference(other)
set ^ other

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

copy()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

difference_update(other, ...)
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 から取り除きます。 set が空であれば、 KeyError を送出します。

clear()

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

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

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

参考

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

5.8. マップ型

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

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

辞書型は key: value の形式の対の値をカンマ区切りのリストを波括弧でくくることで作成できます。例えば : {'jack': 4098, 'sjoerd': 4127} あるいは {4098: 'jack', 4127: 'sjoerd'} 。あるいは、 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 の識別子として有効なキーに対してのみ機能します ; 他の例はキーとして有効なものであればいかなるキーに対しても機能します。

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

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

len(d)

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

d[key]

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

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

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)

辞書 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 が存在するかを確認します。 has_key()key in d と同じことです。

items()

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

CPython implementation detail: キーと値のリストは任意の順序で返されますが、ランダムではなく、 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 と同じ値を返します。 pairs = [(v, k) for (k, v) in d.iteritems()] も同様です。

iteritems()

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

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

バージョン 2.2 で追加.

iterkeys()

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

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

バージョン 2.2 で追加.

itervalues()

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

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

バージョン 2.2 で追加.

keys()

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

pop(key[, default])

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

バージョン 2.3 で追加.

popitem()

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

set のアルゴリズムで使われるのと同じように 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() の Note も参照下さい。

viewitems()

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

バージョン 2.7 で追加.

viewkeys()

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

バージョン 2.7 で追加.

viewvalues()

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

バージョン 2.7 で追加.

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

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

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

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 # これは 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) のようにファイルがイテレータとして使われた場合、 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])

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

注釈

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])

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 できるとは限らないので注意してください。

file.tell()

stdioftell() と同様、ファイルの現在位置を返します。

注釈

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

file.truncate([size])

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

file.write(str)

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

file.writelines(sequence)

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

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

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

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

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) に記憶されているので、バインド、非バインド、メソッドへのメソッド属性の設定は許されていません。メソッド属性の設定を試みると TypeError が送出されます。メソッド属性を設定するためには、その背後の関数オブジェクトで明示的に:

class C:
    def method(self):
        pass

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

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

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. 省略表記オブジェクト

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

Ellipsis と書き表されます。

5.12.9. ブール値

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

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

5.12.10. 内部オブジェクト

スタックフレームオブジェクト、トレースバックオブジェクト、スライスオブジェクト関しては、 標準型の階層 を参照下さい。

5.13. 特殊な属性

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

object.__dict__

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

object.__methods__

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

object.__members__

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

instance.__class__

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

class.__bases__

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

class.__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]従って、一個のタプルだけをフォーマット出力したい場合には出力したいタプルを唯一の要素とする単一のタプルを values に与えなくてはなりません。
[5]改行を残す利点は、空の文字列が返ると EOF を示し、紛らわしくなくなるからです。また、ファイルの最後の行が改行で終わっているかそうでない (ありえることです!) か (例えば、ファイルを行単位で読みながらその完全なコピーを作成した場合には問題になります) を調べることができます。