組み込み型

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

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

コレクションクラスには、ミュータブルなものがあります。コレクションのメンバをインプレースに足し、引き、または並べ替えて、特定の要素を返さないメソッドは、コレクション自身ではなく None を返します。

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

真理値判定

どのようなオブジェクトでも真理値として判定でき、 if や while の条件あるいは以下のブール演算の被演算子として使えます。

オブジェクトは、デフォルトでは真と判定されます。ただし、そのクラスが __bool__() メソッドを定義していて False を返す場合、または __len__() メソッドを定義していてゼロを返す場合は偽と判定されます。 [1] 以下は偽と判定される主な組み込みオブジェクトです:

• 偽であると定義されている定数: None と False

• 数値型におけるゼロ: 0, 0.0, 0j, Decimal(0), Fraction(0, 1)

• 空のシーケンスまたはコレクション: '', (), [], {}, set(), range(0)

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

ブール演算 --- and, or, not

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

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

注釈:

1. この演算子は短絡評価されます。つまり第一引数が偽のときにのみ、第二引数が評価されます。

2. この演算子は短絡評価されます。つまり第一引数が真のときにのみ、第二引数が評価されます。

3. not は非ブール演算子よりも優先度が低いので、 not a == b は not (a == b) と解釈され、 a == not b は構文エラーです。

比較

Python には 8 種の比較演算があります。比較演算の優先順位は全て同じです (ブール演算より高い優先順位です)。比較は任意に連鎖できます; 例えば、 x < y <= z は x < y and y <= z とほぼ等価ですが、この y は一度だけしか評価されません (どちらにしても、 x < y が偽となれば z は評価されません)。

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

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

異なる数値型の場合を除き、異なる型のオブジェクト同士は等価になることはありません。 == 演算子は常に定義されていますが、いくつかのオブジェクト型 (たとえばクラスオブジェクト) では is と同等になります。 <, <=, > および >= 演算子は、それらの意味が明快である場合に限って定義されます; たとえば、オペランドのいずれかが複素数である場合、これらの演算子は TypeError 例外を送出します。

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

クラスのインスタンスは、そのクラスがメソッド __lt__() 、 __le__() 、 __gt__() 、 __ge__() のうち十分なものを定義していない限り、同じクラスの別のインスタンスや他の型のオブジェクトとは順序付けできません (一般に、比較演算子の通常の意味を求めるなら、 __lt__() と __eq__() だけで十分です)。

is および is not 演算子の振る舞いはカスタマイズできません。また、これらはいかなる 2 つのオブジェクトにも適用でき、決して例外を送出しません。

in と not in という構文上で同じ優先度を持つ演算子がさらに 2 つあり、 iterable または __contains__() を実装した型でサポートされています。

数値型 int, float, complex

There are three distinct numeric types: integers, floating point numbers, and complex numbers. In addition, Booleans are a subtype of integers. Integers have unlimited precision. Floating point numbers are usually implemented using double in C; information about the precision and internal representation of floating point numbers for the machine on which your program is running is available in sys.float_info. Complex numbers have a real and imaginary part, which are each a floating point number. To extract these parts from a complex number z, use z.real and z.imag. (The standard library includes the additional numeric types fractions.Fraction, for rationals, and decimal.Decimal, for floating-point numbers with user-definable precision.)

Numbers are created by numeric literals or as the result of built-in functions and operators. Unadorned integer literals (including hex, octal and binary numbers) yield integers. Numeric literals containing a decimal point or an exponent sign yield floating point numbers. Appending 'j' or 'J' to a numeric literal yields an imaginary number (a complex number with a zero real part) which you can add to an integer or float to get a complex number with real and imaginary parts.

Python は型混合の算術演算に完全に対応しています: ある二項算術演算子の被演算子の数値型が互いに異なるとき、"より狭い方" の型の被演算子はもう片方の型に合わせて広げられます。ここで整数は浮動小数点数より狭く、浮動小数点数は複素数より狭いです。 たくさんの異なる型の数値間での比較は、それらの厳密な数で比較したかのように振る舞います。 [2]

コンストラクタ int() 、 float() 、 complex() で、特定の型の数を生成できます。

全ての (複素数を除く) 組み込み数値型は以下の演算に対応しています (演算の優先順位については、 演算子の優先順位 を参照してください):

演算	結果	注釈	完全なドキュメント
x + y	x と y の和
x - y	x と y の差
x * y	x と y の積
x / y	x と y の商
x // y	x と y の商を切り下げたもの	(1)(2)
x % y	x / y の剰余	(2)
-x	x の符号反転
+x	x そのまま
abs(x)	x の絶対値または大きさ		abs()
int(x)	x の整数への変換	(3)(6)	int()
float(x)	x の浮動小数点数への変換	(4)(6)	float()
complex(re, im)	実部 re, 虚部 im の複素数。 im の既定値はゼロ。	(6)	complex()
c.conjugate()	複素数 c の共役複素数
divmod(x, y)	(x // y, x % y) からなるペア	(2)	divmod()
pow(x, y)	x の y 乗	(5)	pow()
x ** y	x の y 乗	(5)

注釈:

1. 整数の除算とも呼ばれます。 int 型のオペランドに対しては、結果は int 型になります。 float 型のオペランドに対しては、結果は float 型になります。一般に結果の型は必ずしも int 型ではありませんが、結果は常に整数です。結果は常に負の無限大の方向に丸められます: 1//2 は 0 、 (-1)//2 は -1 、 1//(-2) は -1 、そして (-1)//(-2) は 0 です。

2. 複素数型には使えません。適用可能な場合には代わりに abs() で浮動小数点型に変換してください。

3. float から int への変換は小数点以下を切り捨てます。別の変換方法については関数 math.floor() や math.ceil() を参照してください。

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

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

6. 受け付けられる数値リテラルは数字 0 から 9 または等価な Unicode (Nd プロパティを持つコードポイント) を含みます。

   See https://www.unicode.org/Public/14.0.0/ucd/extracted/DerivedNumericType.txt for a complete list of code points with the Nd property.

全ての numbers.Real 型 (int 、 float) は以下の演算も含みます:

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

その他の数値演算は、 math や cmath モジュールをご覧ください。

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

ビット単位演算は整数についてのみ意味を持ちます。 ビット単位演算の結果は、あたかも両方の値の先頭を無限個の符号ビットで埋めたものに対して計算したかのような値になります。

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

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

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

注釈:

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

2. n ビットの左シフトは、 pow(2, n) による乗算と等価です。

3. n ビットの右シフトは、 pow(2, n) による切り捨て除算と等価です。

4. 桁の長い方の値に少なくとも 1 つ余計に符号ビットを付け加えた幅 (計算するビット幅は 1 + max(x.bit_length(), y.bit_length()) かそれ以上) でこれらの計算を行えば、無限個の符号ビットがあるかのように計算したのと同じ結果を得るのに十分です。

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

整数型は numbers.Integral 抽象基底クラス を実装します。さらに、追加のメソッドをいくつか提供します:

int.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

バージョン 3.1 で追加.

int.bit_count()

整数の絶対値の二進数表現における 1 の数を返します。これは population count としても知られています。 例:

>>> n = 19
>>> bin(n)
'0b10011'
>>> n.bit_count()
3
>>> (-n).bit_count()
3

次と等価です:

def bit_count(self):
    return bin(self).count("1")

バージョン 3.10 で追加.

int.to_bytes(length=1, byteorder='big', *, signed=False)

整数を表すバイト列を返します。

>>> (1024).to_bytes(2, byteorder='big')
b'\x04\x00'
>>> (1024).to_bytes(10, byteorder='big')
b'\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00'
>>> (-1024).to_bytes(10, byteorder='big', signed=True)
b'\xff\xff\xff\xff\xff\xff\xff\xff\xfc\x00'
>>> x = 1000
>>> x.to_bytes((x.bit_length() + 7) // 8, byteorder='little')
b'\xe8\x03'

整数は length バイトで表されます、デフォルト値は 1 です。整数が与えられた数のバイトで表せなければ、 OverflowError が送出されます。

byteorder 引数は、整数を表すのに使われるバイトオーダーを決定します。デフォルト値は "big" です。 byteorder が "big" なら、最上位のバイトがバイト配列の最初に来ます。 byteorder が "little" なら、最上位のバイトがバイト配列の最後に来ます。

signed 引数は、整数を表すのに 2 の補数を使うかどうかを決定します。 signed が False で、負の整数が与えられたなら、 OverflowError が送出されます。 signed のデフォルト値は False です。

上記のデフォルト値は整数を 1 バイトのオブジェクトに適切に変換するのに使うことができます:

>>> (65).to_bytes()
b'A'

ただし、デフォルト引数で 255 より大きな整数を変換しないでください。 そうでなければ OverflowError 例外を引き起こします。

次と等価です:

def to_bytes(n, length=1, byteorder='big', signed=False):
    if byteorder == 'little':
        order = range(length)
    elif byteorder == 'big':
        order = reversed(range(length))
    else:
        raise ValueError("byteorder must be either 'little' or 'big'")

    return bytes((n >> i*8) & 0xff for i in order)

バージョン 3.2 で追加.

バージョン 3.11 で変更: length と byteorder 引数にデフォルト値を追加しました。

classmethod int.from_bytes(bytes, byteorder='big', *, signed=False)

与えられたバイト列の整数表現を返します。

>>> int.from_bytes(b'\x00\x10', byteorder='big')
16
>>> int.from_bytes(b'\x00\x10', byteorder='little')
4096
>>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=True)
-1024
>>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=False)
64512
>>> int.from_bytes([255, 0, 0], byteorder='big')
16711680

引数 bytes は bytes-like object か、または bytes を生成する iterable でなければなりません。

byteorder 引数は、整数を表すのに使われるバイトオーダーを決定します。デフォルト値は "big" です。 byteorder が "big" なら、最上位のバイトがバイト配列の最初に来ます。 byteorder が "little" なら、最上位のバイトがバイト配列の最後に来ます。ホストシステムにネイティブのバイトオーダーを要求するには、 sys.byteorder をバイトオーダーの値として使ってください。

signed 引数は、整数を表すのに 2 の補数を使うかどうかを決定します。

次と等価です:

def from_bytes(bytes, byteorder='big', signed=False):
    if byteorder == 'little':
        little_ordered = list(bytes)
    elif byteorder == 'big':
        little_ordered = list(reversed(bytes))
    else:
        raise ValueError("byteorder must be either 'little' or 'big'")

    n = sum(b << i*8 for i, b in enumerate(little_ordered))
    if signed and little_ordered and (little_ordered[-1] & 0x80):
        n -= 1 << 8*len(little_ordered)

    return n

バージョン 3.2 で追加.

バージョン 3.11 で変更: byteorder 引数にデフォルト値を追加しました。

int.as_integer_ratio()

Return a pair of integers whose ratio is exactly equal to the original integer and with a positive denominator. The integer ratio of integers (whole numbers) is always the integer as the numerator and 1 as the denominator.

バージョン 3.8 で追加.

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

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

float.as_integer_ratio()

Return a pair of integers whose ratio is exactly equal to the original float and with a positive denominator. Raises OverflowError on infinities and a ValueError on NaNs.

float.is_integer()

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

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

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

float.hex()

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

classmethod float.fromhex(s)

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

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

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

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

sign は必須ではなく、 + と - のどちらかです。 integer と fraction は 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'

数値型のハッシュ化

数 x と y に対して、型が異なっていたとしても、 x == y であれば必ず hash(x) == hash(y) であることが要請されます (詳細は __hash__() メソッドドキュメントを参照してください)。実装の簡単さと 複数の数値型 (int 、 float 、 decimal.Decimal 、 fractions.Fraction を含みます) 間の効率のため、Python の 数値型に対するハッシュ値はある単一の数学的関数に基づいていて、 その関数はすべての有理数に対し定義されているため、 int と fractions.Fraction のすべてのインスタンスと、 float と decimal.Decimal のすべての有限なインスタンスに 対して適用されます。本質的には、この関数は定数の素数 P に対して P を法とする還元で与えられます。 値 P は、 sys.hash_info の modulus 属性として Python で利用できます。

CPython 実装の詳細: 現在使われている素数は、32 bit C long のマシンでは P = 2**31 - 1 、 64-bit C long のマシンでは P = 2**61 - 1 です。

詳細な規則はこうです:

• x = m / n が非負の有理数で、 n が P で割り切れないなら、 invmod(n, P) を n を P で割った剰余の (剰余演算の意味での) 逆数を与えるものとして、 hash(x) を m * invmod(n, P) % P と定義します。

• x = m / n が非負の有理数で、 n が P で割り切れる (が m は割り切れない) なら、 n は P で割った余りの逆数を持たず、上の規則は適用できません。この場合、 hash(x) を定数 sys.hash_info.inf と定義します。

• x = m / n が負の有理数なら、 hash(x) を -hash(-x) と定義します。その結果のハッシュが -1 なら、 -2 に置き換えます。

• 特定の値 sys.hash_info.inf 、 -sys.hash_info.inf は、正の無限大、負の無限大のハッシュ値を (それぞれ) 表すのに使われます。

• 複素 (complex) 数 z に対して、実部と虚部のハッシュ値は、 hash(z.real) + sys.hash_info.imag * hash(z.imag) の 2**sys.hash_info.width を法とする還元を計算することにより組み合わせられ、よってこれは range(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - 1)) に収まります。再び、結果が -1 なら、 -2 で置き換えられます。

上述の規則をわかりやすくするため、有理数 float や、 complex のハッシュを計算する組み込みのハッシュと等価な Python コードの例を挙げます:

import sys, math

def hash_fraction(m, n):
    """Compute the hash of a rational number m / n.

    Assumes m and n are integers, with n positive.
    Equivalent to hash(fractions.Fraction(m, n)).

    """
    P = sys.hash_info.modulus
    # Remove common factors of P.  (Unnecessary if m and n already coprime.)
    while m % P == n % P == 0:
        m, n = m // P, n // P

    if n % P == 0:
        hash_value = sys.hash_info.inf
    else:
        # Fermat's Little Theorem: pow(n, P-1, P) is 1, so
        # pow(n, P-2, P) gives the inverse of n modulo P.
        hash_value = (abs(m) % P) * pow(n, P - 2, P) % P
    if m < 0:
        hash_value = -hash_value
    if hash_value == -1:
        hash_value = -2
    return hash_value

def hash_float(x):
    """Compute the hash of a float x."""

    if math.isnan(x):
        return object.__hash__(x)
    elif math.isinf(x):
        return sys.hash_info.inf if x > 0 else -sys.hash_info.inf
    else:
        return hash_fraction(*x.as_integer_ratio())

def hash_complex(z):
    """Compute the hash of a complex number z."""

    hash_value = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag)
    # do a signed reduction modulo 2**sys.hash_info.width
    M = 2**(sys.hash_info.width - 1)
    hash_value = (hash_value & (M - 1)) - (hash_value & M)
    if hash_value == -1:
        hash_value = -2
    return hash_value

イテレータ型

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

コンテナオブジェクトが イテラブル のサポートを提供するためには、一つのメソッドが定義されていなければなりません:

container.__iter__()

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

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

iterator.__iter__()

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

iterator.__next__()

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

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

イテレータの __next__() メソッドが一旦 StopIteration を送出したなら、以降の呼び出しでも例外を送出し続けなければなりません。この特性に従わない実装は壊れているとみなされます。

ジェネレータ型

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

シーケンス型 --- list, tuple, range

基本的なシーケンス型は 3 つあります: リスト、タプル、range オブジェクトです。バイナリデータ や テキスト文字列 を処理するように仕立てられたシーケンス型は、セクションを割いて解説します。

共通のシーケンス演算

以下の表にある演算は、ほとんどのミュータブル、イミュータブル両方のシーケンスでサポートされています。カスタムのシーケンス型にこれらの演算を完全に実装するのが簡単になるように、 collections.abc.Sequence ABC が提供されています。

以下のテーブルで、シーケンス演算を優先順位が低い順に挙げます。表内で、 s と t は同じ型のシーケンス、 n、 i、 j 、 k は整数、x は s に課された型と値の条件を満たす任意のオブジェクトです。

in および not in 演算の優先順位は比較演算と同じです。+ (結合) および * (繰り返し)の優先順位は対応する数値演算と同じです。 [3]

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

同じ型のシーケンスは比較もサポートしています。特に、タプルとリストは対応する要素を比較することで辞書式順序で比較されます。つまり、等しいとされるためには、すべての要素が等しく、両シーケンスの型も長さも等しくなければなりません。(完全な詳細は言語リファレンスの 比較 を参照してください。)

ミュータブルなシーケンスに対する前方および逆方向イテレータはインデックスを使って要素にアクセスします。インデックスは、仮に参照するシーケンスが変化したとしても前方 (または後方) に進み続けます。イテレータは IndexError または StopIteration に出会った場合 (またはインデックスがゼロより小さくなった場合) にのみ終了します。

注釈:

1. in および not in 演算は、一般に単純な包含判定にのみ使われますが、(str, bytes, bytearray のような) 特殊なシーケンスでは部分シーケンス判定にも使われます:

   >>> "gg" in "eggs"
   True
   

2. 0 未満の値 n は 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. s の i から j へのスライスは i <= k < j となるようなインデックス k を持つ要素からなるシーケンスとして定義されます。 i または j が len(s) よりも大きい場合、 len(s) を使います。 i が省略されるか None だった場合、 0 を使います。 j が省略されるか None だった場合、 len(s) を使います。 i が j 以上の場合、スライスは空のシーケンスになります。

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

6. イミュータブルなシーケンスの結合は、常に新しいオブジェクトを返します。これは、結合の繰り返しでシーケンスを構築する実行時間コストがシーケンスの長さの合計の二次式になることを意味します。実行時間コストを線形にするには、代わりに以下のいずれかにしてください:

   • str オブジェクトを結合するには、リストを構築して最後に str.join() を使うか、 io.StringIO インスタンスに書き込んで完成してから値を取得してください

   • bytes オブジェクトを結合するなら、同様に bytes.join() や io.BytesIO を使うか、 bytearray オブジェクトでインプレースに結合できます。 bytearray オブジェクトはミュータブルで、効率のいい割り当て超過機構を備えています

   • tuple オブジェクトを結合するなら、代わりに list を拡張してください

   • その他の型については、関連するクラスのドキュメントを調べてください

7. シーケンス型には、 (range のように) 特殊なパターンに従う項目のシーケンスのみをサポートするものがあり、それらはシーケンスの結合や繰り返しをサポートしません。

8. index は x が s 中に見つからないとき ValueError を送出します。追加の引数 i と j は、すべての実装がサポートしているわけではありません。追加の引数を渡すのは、おおよそ s[i:j].index(x) を使うのと等価ですが、データをコピーしなくて済むし、返されるのはスライスの最初ではなくシーケンスの最初からの相対インデクスです。

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

イミュータブルなシーケンス型が一般に実装している演算のうち、ミュータブルなシーケンス型がサポートしていないのは、組み込みの hash() だけです。

このサポートにより、tuple インスタンスのようなイミュータブルなシーケンスは、 dict のキーとして使え、 set や frozenset インスタンスに保存できます。

ハッシュ不可能な値を含むイミュータブルなシーケンスをハッシュ化しようとすると、 TypeError となります。

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

以下のテーブルにある演算は、ほとんどのミュータブルなシーケンスでサポートされています。カスタムのシーケンス型にこれらの演算を完全に実装するのが簡単になるように、 collections.abc.MutableSequence ABC が提供されています。

このテーブルで、 s はミュータブルなシーケンス型のインスタンス、 t は任意のイテラブルオブジェクト、 x は s に課された型と値の条件を満たす任意のオブジェクト (例えば、 bytearray は値の制限 0 <= x <= 255 に合う整数のみを受け付けます) です。

演算	結果	注釈
s[i] = x	s の要素 i を x と入れ替えます
s[i:j] = t	s の i から j 番目までのスライスをイテラブル t の内容に入れ替えます
del s[i:j]	s[i:j] = [] と同じです
s[i:j:k] = t	s[i:j:k] の要素を t の要素と入れ替えます	(1)
del s[i:j:k]	リストから s[i:j:k] の要素を削除します
s.append(x)	x をシーケンスの最後に加えます (s[len(s):len(s)] = [x] と同じ)
s.clear()	s から全ての要素を取り除きます (del s[:] と同じ)	(5)
s.copy()	s の浅いコピーを作成します (s[:] と同じ)	(5)
s.extend(t) または s += t	s を t の内容で拡張します (ほとんど s[len(s):len(s)] = t と同じ)
s *= n	s をその内容を n 回繰り返したもので更新	(6)
s.insert(i, x)	s の i で与えられたインデックスに x を挿入します。 (s[i:i] = [x] と同じ)
s.pop() または s.pop(i)	s から i 番目の要素を取り出し、また取り除きます	(2)
s.remove(x)	remove the first item from s where s[i] is equal to x	(3)
s.reverse()	s をインプレースに逆転させます	(4)

注釈:

1. t must have the same length as the slice it is replacing.

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

3. remove() は s に x が見つからなければ ValueError を送出します。

4. reverse() メソッドは、大きなシーケンスを反転するときの容量の節約のため、シーケンスをインプレースに変化させます。副作用としてこの演算が行われることをユーザに気づかせるために、これは反転したシーケンスを返しません。

5. clear() および copy() は、スライシング操作をサポートしないミュータブルなコンテナ (dict や set など) のインターフェースとの一貫性のために含まれています。 copy() は collections.abc.MutableSequence ABC の一部ではありませんが、ほとんどのミュータブルなシーケンスクラスが提供しています。

   バージョン 3.3 で追加: clear() および copy() メソッド。

6. 値 n は整数であるか、__index__() を実装したオブジェクトです。 n の値がゼロまたは負数の場合、シーケンスをクリアします。共通のシーケンス演算 で s * n について説明したとおり、シーケンスの要素はコピーされないので注意してください; コピーではなく要素に対する参照カウントが増えます。

リスト型 (list)

リストはミュータブルなシーケンスで、一般的に同種の項目の集まりを格納するために使われます (厳密な類似の度合いはアプリケーションによって異なる場合があります)。

class list([iterable])

リストの構成にはいくつかの方法があります:

• 角括弧の対を使い、空のリストを表す: []

• 角括弧を使い、項目をカンマで区切る: [a]、[a, b, c]

• リスト内包表記を使う: [x for x in iterable]

• 型コンストラクタを使う: list() または list(iterable)

コンストラクタは、 iterable の項目と同じ項目で同じ順のリストを構築します。 iterable は、シーケンス、イテレートをサポートするコンテナ、またはイテレータオブジェクトです。 iterable が既にリストなら、 iterable[:] と同様にコピーが作られて返されます。例えば、 list('abc') は ['a', 'b', 'c'] を、 list( (1, 2, 3) ) は [1, 2, 3] を返します。引数が与えられなければ、このコンストラクタは新しい空のリスト [] を作成します。

リストを作る方法は、他にも組み込み関数 sorted() などいろいろあります。

リストは 共通の および ミュータブルの シーケンス演算をすべて実装します。リストは、更に以下のメソッドも提供します:

sort(*, key=None, reverse=False)

このメソッドは、項目間の < 比較のみを用いてリストをインプレースにソートします。例外は抑制されません。比較演算がどこかで失敗したら、ソート演算自体が失敗します (そしてリストは部分的に変更された状態で残されるでしょう)。

sort() は、キーワードでしか渡せない 2 つの引数 (キーワード専用引数) を受け付けます:

key は一引数をとる関数を指定し、リストのそれぞれの要素から比較キーを取り出すのに使います (例えば、 key=str.lower)。それぞれの項目に対応するキーは一度計算され、ソート処理全体に使われます。デフォルトの値 None は、別のキー値を計算せず、リストの値が直接ソートされることを意味します。

2.x 形式の cmp 関数を key 関数に変換するために、functools.cmp_to_key() ユーティリティが利用できます。

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

このメソッドは、大きなシーケンスをソートするときの容量の節約のため、シーケンスをインプレースに変化させます。副作用としてこの演算が行われることをユーザに気づかせるために、これはソートしたシーケンスを返しません (新しいリストインスタンスを明示的に要求するには sorted() を使ってください)。

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

ソートの例と簡単なチュートリアルは Sorting HOW TO を参照して下さい。

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

タプル型 (tuple)

タプルはイミュータブルなシーケンスで、一般的に異種のデータの集まり (組み込みの enumerate() で作られた 2-タプルなど) を格納するために使われます。タプルはまた、同種のデータのイミュータブルなシーケンスが必要な場合 (set インスタンスや dict インスタンスに保存できるようにするためなど) にも使われます。

class tuple([iterable])

タプルの構成にはいくつかの方法があります:

• 丸括弧の対を使い、空のタプルを表す: ()

• カンマを使い、単要素のタプルを表す: a, または (a,)

• 項目をカンマで区切る: a, b, c または (a, b, c)

• 組み込みの tuple() を使う: tuple() または tuple(iterable)

コンストラクタは、 iterable の項目と同じ項目で同じ順のタプルを構築します。 iterable は、シーケンス、イテレートをサポートするコンテナ、またはイテレータオブジェクトです。 iterable が既にタプルなら、そのまま返されます。例えば、 tuple('abc') は ('a', 'b', 'c') を、 tuple( [1, 2, 3] ) は (1, 2, 3) を返します。引数が与えられなければ、このコンストラクタは新しい空のタプル () を作成します。

なお、タプルを作るのはカンマであり、丸括弧ではありません。丸括弧は省略可能ですが、空のタプルの場合や構文上の曖昧さを避けるのに必要な時は例外です。例えば、 f(a, b, c) は三引数の関数呼び出しですが、f((a, b, c)) は 3-タプルを唯一の引数とする関数の呼び出しです。

タプルは 共通の シーケンス演算をすべて実装します。

異種のデータの集まりで、インデックスによってアクセスするよりも名前によってアクセスしたほうが明確になるものには、単純なタプルオブジェクトよりも collections.namedtuple() が向いているかもしれません。

range

range 型は、数のイミュータブルなシーケンスを表し、一般に for ループにおいて特定の回数のループに使われます。

class range(stop)

class range(start, stop[, step])

range コンストラクタの引数は整数 (組み込みの int または __index__() 特殊メソッドを実装するオブジェクト) でなければなりません。step 引数が省略された場合のデフォルト値は 1 です。start 引数が省略された場合のデフォルト値は 0 です。 step が 0 の場合、ValueError が送出されます。

step が正の場合、range r の内容は式 r[i] = start + step*i で決定されます。ここで、 i >= 0 かつ r[i] < stop です。

step が負の場合も、range r の内容は式 r[i] = start + step*i で決定されます。ただし、制約条件は i >= 0 かつ r[i] > stop です。

r[0] が値の制約を満たさない場合、range オブジェクトは空になります。range は負のインデックスをサポートしますが、これらは正のインデックスにより決定されるシーケンスの末尾からのインデックス指定として解釈されます。

range は sys.maxsize より大きい絶対値を含むことができますが、いくつかの機能 (len() など) は OverflowError を送出することがあります。

range の例:

>>> list(range(10))
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> list(range(1, 11))
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> list(range(0, 30, 5))
[0, 5, 10, 15, 20, 25]
>>> list(range(0, 10, 3))
[0, 3, 6, 9]
>>> list(range(0, -10, -1))
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
>>> list(range(0))
[]
>>> list(range(1, 0))
[]

range は 共通の シーケンス演算を、結合と繰り返し以外すべて実装します (range オブジェクトは厳格なパターンに従うシーケンスのみを表せ、繰り返しと結合はたいていそのパターンを破るという事実によります)。

start

引数 start の値 (この引数が与えられていない場合は 0)

stop

引数 stop の値

step

引数 step の値 (この引数が与えられていない場合は 1)

range 型が通常の list や tuple にまさる点は、range オブジェクトがサイズや表す範囲にかかわらず常に一定の (小さな) 量のメモリを使うことです (start、stop、step の値のみを保存し、後は必要に応じて個々の項目や部分 range を計算するためです)。

range オブジェクトは collections.abc.Sequence ABC を実装し、包含判定、要素インデックス検索、スライシングのような機能を提供し、負のインデックスをサポートします (シーケンス型 --- list, tuple, range を参照):

>>> r = range(0, 20, 2)
>>> r
range(0, 20, 2)
>>> 11 in r
False
>>> 10 in r
True
>>> r.index(10)
5
>>> r[5]
10
>>> r[:5]
range(0, 10, 2)
>>> r[-1]
18

== および != による range オブジェクトの等価性の判定は、これらをシーケンスとして比較します。つまり、二つの range オブジェクトは同じ値のシーケンスを表すなら等しいとみなされます。(なお、二つの等しいとされる range オブジェクトが異なる start, stop および step 属性を持つことがあります。例えば range(0) == range(2, 1, 3) や range(0, 3, 2) == range(0, 4, 2)。)

バージョン 3.2 で変更: シーケンス ABC を実装。スライスと負のインデックスのサポート。int オブジェクトの帰属判定を、すべてのアイテムをイテレートする代わりに、定数時間で行います。

バージョン 3.3 で変更: (オブジェクトの同一性に基づいて比較する代わりに) range オブジェクトをそれらが定義する値のシーケンスに基づいて比較するように '==' と '!=' を定義しました。

属性 start, stop および step が追加。

参考

• The linspace recipe shows how to implement a lazy version of range suitable for floating point applications.

テキストシーケンス型 --- str

Python のテキストデータは str オブジェクト、すなわち 文字列 として扱われます。文字列は Unicode コードポイントのイミュータブルな シーケンス です。文字列リテラルには様々な記述方法があります:

• シングルクォート: '"ダブル" クォートを埋め込むことができます'

• ダブルクォート: "'シングル' クォートを埋め込むことができます"。

• 三重引用符: '''三つのシングルクォート''', """三つのダブルクォート"""

三重引用符文字列は、複数行に分けることができます。関連付けられる空白はすべて文字列リテラルに含まれます。

単式の一部であり間に空白のみを含む文字列リテラルは、一つの文字列リテラルに暗黙に変換されます。つまり、("spam " "eggs") == "spam eggs" です。

サポートされている エスケープシーケンス や、ほとんどのエスケープシーケンスの処理を無効化する r ("raw") 接頭辞など、文字列リテラルのさまざまな形式についての詳細は 文字列およびバイト列リテラル を参照してください。

文字列は他のオブジェクトに str コンストラクタを使うことでも生成できます。

"character" 型が特別に用意されているわけではないので、文字列のインデックス指定を行うと長さ 1 の文字列を作成します。つまり、空でない文字列 s に対し、s[0] == s[0:1] です。

ミュータブルな文字列型もありませんが、ミュータブルな断片から効率よく文字列を構成するのに str.join() や io.StringIO が使えます。

バージョン 3.3 で変更: Python 2 シリーズとの後方互換性のため、文字列リテラルの u 接頭辞が改めて許可されました。それは文字列リテラルとしての意味には影響がなく、 r 接頭辞と結合することはできません。

class str(object='')

class str(object=b'', encoding='utf-8', errors='strict')

object の 文字列 版を返します。 object が与えられなかった場合、空文字列が返されます。それ以外の場合 str() の動作は、 encoding や errors が与えられたかどうかによって次のように変わります。

If neither encoding nor errors is given, str(object) returns type(object).__str__(object), which is the "informal" or nicely printable string representation of object. For string objects, this is the string itself. If object does not have a __str__() method, then str() falls back to returning repr(object).

encoding か errors の少なくとも一方が与えられた場合、 object は bytes-like object (たとえば bytes や bytearray) でなくてはなりません。object が bytes (もしくは bytearray) オブジェクトである場合は、 str(bytes, encoding, errors) は bytes.decode(encoding, errors) と等価です。そうでない場合は、 bytes.decode() が呼ばれる前に buffer オブジェクトの下層にある bytes オブジェクトが取得されます。 buffer オブジェクトについて詳しい情報は、 バイナリシーケンス型 --- bytes, bytearray, memoryview や バッファプロトコル (buffer Protocol) を参照してください。

encoding 引数や errors 引数無しに bytes オブジェクトを str() に渡すと、略式の文字列表現を返す 1 つ目の場合に該当します。(Python のコマンドラインオプション -b も参照してください) 例えば:

>>> str(b'Zoot!')
"b'Zoot!'"

str クラスとそのメソッドについて詳しくは、 テキストシーケンス型 — str や 文字列メソッド の節を参照してください。フォーマットされた文字列を出力するには、 f-strings と カスタムの文字列書式化 の節を参照してください。加えて、 テキスト処理サービス の節も参照してください。

文字列メソッド

文字列は 共通の シーケンス演算全てに加え、以下に述べるメソッドを実装します。

文字列は、二形式の文字列書式化をサポートします。一方は柔軟さが高くカスタマイズできます (str.format()、 書式指定文字列の文法 、および カスタムの文字列書式化 を参照してください)。他方は C 言語の printf 形式の書式化に基づいてより狭い範囲と型を扱うもので、正しく扱うのは少し難しいですが、扱える場合ではたいていこちらのほうが高速です (printf 形式の文字列書式化)。

標準ライブラリの テキスト処理サービス 節は、その他テキストに関する様々なユーティリティ (re モジュールによる正規表現サポートなど) を提供するいくつかのモジュールをカバーしています。

str.capitalize()

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

バージョン 3.8 で変更: 最初の文字が大文字ではなくタイトルケースに置き換えられるようになりました。つまり二重音字のような文字はすべての文字が大文字にされるのではなく、最初の文字だけ大文字にされるようになります。

str.casefold()

文字列の casefold されたコピーを返します。casefold された文字列は、大文字小文字に関係ないマッチに使えます。

casefold は、小文字化と似ていますが、より積極的です。これは文字列の大文字小文字の区別をすべて取り去ることを意図しているためです。例えば、ドイツ語の小文字 'ß' は "ss" と同じです。これは既に小文字なので、lower() は 'ß' に何もしませんが、casefold() はこれを "ss" に変換します。

The casefolding algorithm is described in section 3.13 of the Unicode Standard.

バージョン 3.3 で追加.

str.center(width[, fillchar])

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

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

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

sub が空の場合は、文字と文字の間にある空文字列の数、すなわち文字列の長さに1を加えたものを返します。

str.encode(encoding='utf-8', errors='strict')

bytes にエンコードされた文字列を返します。

encoding のデフォルト値は 'utf-8' です; 指定可能な値については 標準エンコーディング を参照してください。

errors はエンコーディングエラーをどのように取り扱うかを制御します。 'strict' (デフォルト) では UnicodeError 例外が送出されます。そのほかに指定可能な値は 'ignore', 'replace', 'xmlcharrefreplace', 'backslashreplace' と、そして codecs.register_error() で登録された名前です。詳しくは エラーハンドラ を参照してください。

パフォーマンス上の理由から、 errors の値の妥当性は、エンコーディングエラーが実際に発生するか、 Python 開発モード が有効になっているか、もしくは デバッグビルド が使われていない限りチェックされません。

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

バージョン 3.9 で変更: errors 引数の値は Python 開発モード と デバッグモード でチェックされるようになりました。

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

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

str.expandtabs(tabsize=8)

文字列内の全てのタブ文字が 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'

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

注釈

数値 (int, float, complex, decimal.Decimal とサブクラス) を n の整数表現型 (例: '{:n}'.format(1234)) でフォーマットするとき、LC_CTYPE ロケールと LC_NUMERIC ロケールの一方または両方が 1 バイトより長い非 ASCII 文字であると同時に異なる値である場合、この関数は localeconv() の decimal_point と thousands_sep フィールドを読み取るため一時的に LC_CTYPE ロケールに LC_NUMERIC のロケール値を設定します。この一時的な変更は他のスレッドの動作に影響します。

バージョン 3.7 で変更: 数値を n の整数表現型でフォーマットするとき、この関数は一時的に LC_CTYPE ロケールに LC_NUMERIC のロケール値を設定する場合があります。

str.format_map(mapping)

str.format(**mapping) と似ていますが、 mapping は dict にコピーされず、直接使われます。これは例えば mapping が dict のサブクラスであるときに便利です:

>>> class Default(dict):
...     def __missing__(self, key):
...         return key
...
>>> '{name} was born in {country}'.format_map(Default(name='Guido'))
'Guido was born in country'

バージョン 3.2 で追加.

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

find() と同様ですが、部分文字列が見つからなかったとき ValueError を送出します。

str.isalnum()

文字列中の全ての文字が英数字で、かつ 1 文字以上あるなら True を、そうでなければ False を返します。文字 c は以下のいずれかが True を返せば英数字です: c.isalpha() 、 c.isdecimal() 、 c.isdigit() 、 c.isnumeric() 。

str.isalpha()

Return True if all characters in the string are alphabetic and there is at least one character, False otherwise. Alphabetic characters are those characters defined in the Unicode character database as "Letter", i.e., those with general category property being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note that this is different from the "Alphabetic" property defined in the Unicode Standard.

str.isascii()

文字列が空であるか、文字列の全ての文字が ASCII である場合に True を、それ以外の場合に False を返します。 ASCII 文字のコードポイントは U+0000-U+007F の範囲にあります。

バージョン 3.7 で追加.

str.isdecimal()

文字列中の全ての文字が十進数字で、かつ 1 文字以上あるなら True を、そうでなければ False を返します。十進数字とは十進数を書くのに使われる文字のことで、たとえば U+0660 (ARABIC-INDIC DIGIT ZERO) なども含みます。正式には、Unicode の一般カテゴリ "Nd" に含まれる文字を指します。

str.isdigit()

文字列中の全ての文字が数字で、かつ 1 文字以上あるなら True を、そうでなければ False を返します。ここでの数字とは、十進数字に加えて、互換上付き数字のような特殊操作を必要とする数字を含みます。また 10 を基数とした表現ができないカローシュティー数字のような体系の文字も含みます。正式には、数字とは、プロパティ値 Numeric_Type=Digit または Numeric_Type=Decimal を持つ文字です。

str.isidentifier()

文字列が、 識別子 (identifier) およびキーワード (keyword) 節の言語定義における有効な識別子であれば True を返します。

Call keyword.iskeyword() to test whether string s is a reserved identifier, such as def and class.

例:

>>> from keyword import iskeyword

>>> 'hello'.isidentifier(), iskeyword('hello')
(True, False)
>>> 'def'.isidentifier(), iskeyword('def')
(True, True)

str.islower()

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

str.isnumeric()

文字列中の全ての文字が数を表す文字で、かつ 1 文字以上あるなら True を、そうでなければ False を返します。数を表す文字は、数字と、Unicode の数値プロパティを持つ全ての文字を含みます。たとえば U+2155 (VULGAR FRACTION ONE FIFTH)。正式には、数を表す文字は、プロパティ値 Numeric_Type=Digit、 Numeric_Type=Decimal または Numeric_Type=Numeric を持つものです。

str.isprintable()

文字列中のすべての文字が印字可能であるか、文字列が空であれば True を、そうでなければ False を返します。非印字可能文字は、 Unicode 文字データベースで "Other" または "Separator" と定義されている文字の、印字可能と見なされる ASCII space (0x20) 以外のものです。(なお、この文脈での印字可能文字は、文字列に repr() が呼び出されるときにエスケープすべきでない文字のことです。これは sys.stdout や sys.stderr に書き込まれる文字列の操作とは関係ありません。)

str.isspace()

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

Unicode 文字データベース (unicodedata を参照) で一般カテゴリが Zs ("Seperator, space") であるか、 双方向クラスが　WS、B、 S のいずれかである場合、その文字は 空白文字(whitespace) です。

str.istitle()

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

str.isupper()

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

>>> 'BANANA'.isupper()
True
>>> 'banana'.isupper()
False
>>> 'baNana'.isupper()
False
>>> ' '.isupper()
False

str.join(iterable)

iterable 中の文字列を結合した文字列を返します。 iterable に bytes オブジェクトのような非文字列の値が存在するなら、 TypeError が送出されます。要素間のセパレータは、このメソッドを提供する文字列です。

str.ljust(width[, fillchar])

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

str.lower()

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

The lowercasing algorithm used is described in section 3.13 of the Unicode Standard.

str.lstrip([chars])

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

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

文字の集合全てではなく、指定した文字列そのものを接頭辞として削除するメソッドについては、 str.removeprefix() を参照してください。使用例:

>>> 'Arthur: three!'.lstrip('Arthur: ')
'ee!'
>>> 'Arthur: three!'.removeprefix('Arthur: ')
'three!'

static str.maketrans(x[, y[, z]])

この静的メソッドは str.translate() に使える変換テーブルを返します。

引数を 1 つだけ与える場合、それは Unicode 序数 (整数) または文字 (長さ 1 の文字列) を、Unicode 序数、(任意長の) 文字列、または None に対応づける辞書でなければなりません。このとき、文字で指定したキーは序数に変換されます。

引数を 2 つ指定する場合、それらは同じ長さの文字列である必要があり、結果の辞書では、x のそれぞれの文字が y の同じ位置の文字に対応付けられます。第 3 引数を指定する場合、文字列を指定する必要があり、それに含まれる文字が None に対応付けられます。

str.partition(sep)

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

str.removeprefix(prefix, /)

文字列が prefix で始まる場合、 string[len(prefix):] を返します。それ以外の場合、元の文字列のコピーを返します:

>>> 'TestHook'.removeprefix('Test')
'Hook'
>>> 'BaseTestCase'.removeprefix('Test')
'BaseTestCase'

バージョン 3.9 で追加.

str.removesuffix(suffix, /)

文字列が suffix で終わる場合、 string[:-len(suffix)] を返します。それ以外の場合、元の文字列のコピーを返します:

>>> 'MiscTests'.removesuffix('Tests')
'Misc'
>>> 'TmpDirMixin'.removesuffix('Tests')
'TmpDirMixin'

バージョン 3.9 で追加.

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

Return a copy of the string with all occurrences of substring old replaced by new. If the optional argument count is given, only the first count occurrences are replaced.

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 で指定された文字(デフォルトでは ASCII スペース)が使われます。 width が len(s) 以下の場合、元の文字列が返されます。

str.rpartition(sep)

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

str.rsplit(sep=None, maxsplit=-1)

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

str.rstrip([chars])

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

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

文字の集合全てではなく、指定した文字列そのものを接尾辞として削除するメソッドについては str.removesuffix() を参照してください。使用例:

>>> 'Monty Python'.rstrip(' Python')
'M'
>>> 'Monty Python'.removesuffix(' Python')
'Monty'

str.split(sep=None, maxsplit=-1)

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

If sep is given, consecutive delimiters are not grouped together and are deemed to delimit empty strings (for example, '1,,2'.split(',') returns ['1', '', '2']). The sep argument may consist of multiple characters (for example, '1<>2<>3'.split('<>') returns ['1', '2', '3']). Splitting an empty string with a specified separator returns [''].

例えば:

>>> '1,2,3'.split(',')
['1', '2', '3']
>>> '1,2,3'.split(',', maxsplit=1)
['1', '2,3']
>>> '1,2,,3,'.split(',')
['1', '2', '', '3', '']

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

例えば:

>>> '1 2 3'.split()
['1', '2', '3']
>>> '1 2 3'.split(maxsplit=1)
['1', '2 3']
>>> '   1   2   3   '.split()
['1', '2', '3']

str.splitlines(keepends=False)

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

このメソッドは以下の行境界で分解します。特に、以下の境界は universal newlines のスーパーセットです。

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

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

例えば:

>>> 'ab c\n\nde fg\rkl\r\n'.splitlines()
['ab c', '', 'de fg', 'kl']
>>> 'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=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', '']

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

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

str.strip([chars])

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

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

文字列の最も外側の先頭および末尾から、引数 chars 値がはぎ取られます。文字列の先頭から chars の文字集合に含まれない文字に達するまで、文字が削除されます。文字列の末尾に対しても同様の操作が行われます。例えば、次のようになります:

>>> comment_string = '#....... Section 3.2.1 Issue #32 .......'
>>> comment_string.strip('.#! ')
'Section 3.2.1 Issue #32'

str.swapcase()

大文字が小文字に、小文字が大文字に変換された、文字列のコピーを返します。なお、 s.swapcase().swapcase() == s が真であるとは限りません。

str.title()

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

例えば:

>>> 'Hello world'.title()
'Hello World'

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

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

string.capwords() 関数は単語をスペースでのみ分割するため、この問題はありません。

または、正規表現を使うことでアポストロフィに対応できます:

>>> import re
>>> def titlecase(s):
...     return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
...                   lambda mo: mo.group(0).capitalize(),
...                   s)
...
>>> titlecase("they're bill's friends.")
"They're Bill's Friends."

str.translate(table)

与えられた変換テーブルに基づいて文字列を構成する各文字をマッピングし、マッピング後の文字列のコピーを返します。変換テーブルは、__getitem__() によるインデックス指定を実装するオブジェクトである必要があります。一般的には、 mapping または sequence です。Unicode 序数 (整数) でインデックス指定する場合、変換テーブルのオブジェクトは次のいずれも行うことができます。Unicode 序数または文字列を返して文字を 1 文字以上の別の文字にマッピングすること、None を返して返り値の文字列から指定した文字を削除すること、例外 LookupError を送出して文字をその文字自身にマッピングすること。

文字から文字への異なる形式のマッピングから変換マップを作成するために、 str.maketrans() が使えます。

文字のマッピングを好みに合わせてより柔軟に変更する方法については、codecs モジュールも参照してください。

str.upper()

全ての大小文字の区別のある文字 [4] が大文字に変換された、文字列のコピーを返します。なお s.upper().isupper() は、 s が大小文字の区別のある文字を含まなかったり、結果の文字の Unicode カテゴリが "Lu" ではなく例えば "Lt" (Letter, titlecase) などであったら、 False になりえます。

The uppercasing algorithm used is described in section 3.13 of the Unicode Standard.

str.zfill(width)

長さが width になるよう ASCII '0' で左詰めした文字列のコピーを返します。先頭が符号接頭辞 ('+'/'-') だった場合、 '0' は符号の前ではなく 後 に挿入されます。width が len(s) 以下の場合元の文字列を返します。

例えば:

>>> "42".zfill(5)
'00042'
>>> "-42".zfill(5)
'-0042'

printf 形式の文字列書式化

注釈

ここで解説されているフォーマット操作には、(タプルや辞書を正しく表示するのに失敗するなどの) よくある多くの問題を引き起こす、様々な欠陥が出現します。 新しい フォーマット済み文字列リテラル や str.format() インターフェースや テンプレート文字列 が、これらの問題を回避する助けになるでしょう。 これらの代替手段には、それ自身に、トレードオフや、簡潔さ、柔軟さ、拡張性といった利点があります。

String objects have one unique built-in operation: the % operator (modulo). This is also known as the string formatting or interpolation operator. Given format % values (where format is a string), % conversion specifications in format are replaced with zero or more elements of values. The effect is similar to using the sprintf() in the C language.

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.

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

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

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

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

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

変換	意味	注釈
'd'	符号付き 10 進整数。
'i'	符号付き 10 進整数。
'o'	符号付き 8 進数。	(1)
'u'	旧式の型 -- 'd' と同じです。	(6)
'x'	符号付き 16 進数 (小文字)。	(2)
'X'	符号付き 16 進数 (大文字)。	(2)
'e'	Floating point exponential format (lowercase).	(3)
'E'	Floating point exponential format (uppercase).	(3)
'f'	Floating point decimal format.	(3)
'F'	Floating point decimal format.	(3)
'g'	Floating point format. Uses lowercase exponential format if exponent is less than -4 or not less than precision, decimal format otherwise.	(4)
'G'	Floating point format. Uses uppercase exponential format if exponent is less than -4 or not less than precision, decimal format otherwise.	(4)
'c'	文字一文字 (整数または一文字からなる文字列を受理します)。
'r'	文字列 (Python オブジェクトを repr() で変換します)。	(5)
's'	文字列 (Python オブジェクトを str() で変換します)。	(5)
'a'	文字列 (Python オブジェクトを ascii() で変換します)。	(5)
'%'	引数を変換せず、返される文字列中では文字 '%' になります。

注釈:

1. 別の形式を指定（訳注: 変換フラグ # を使用）すると 8 進数を表す接頭辞 ('0o') が最初の数字の前に挿入されます。

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

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

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

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

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

5. 精度が N なら、出力は N 文字に切り詰められます。

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

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

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

バイナリシーケンス型 --- bytes, bytearray, memoryview

バイナリデータを操作するためのコア組み込み型は bytes および bytearray です。これらは、別のバイナリオブジェクトのメモリにコピーを作成すること無くアクセスするための バッファプロトコル を利用する memoryview でサポートされています。

array モジュールは、32 ビット整数や IEEE754 倍精度浮動小数点値のような基本データ型の、効率的な保存をサポートしています。

バイトオブジェクト

bytes はバイトの不変なシーケンスです。多くのメジャーなプロトコルがASCIIテキストエンコーディングをベースにしているので、 bytes オブジェクトは ASCII 互換のデータに対してのみ動作する幾つかのメソッドを提供していて、文字列オブジェクトと他の多くの点で近いです。

class bytes([source[, encoding[, errors]]])

まず、 bytes リテラルの構文は文字列リテラルとほぼ同じで、 b というプリフィックスを付けます:

• シングルクォート: b'still allows embedded "double" quotes'

• ダブルクォート: b"still allows embedded 'single' quotes".

• 3重クォート: b'''3 single quotes''', b"""3 double quotes"""

bytes リテラルでは (ソースコードのエンコーディングに関係なく) ASCII文字のみが許可されています。 127より大きい値を bytes リテラルに記述する場合は適切なエスケープシーケンスを書く必要があります。

文字列リテラルと同じく、 bytes リテラルでも r プリフィックスを用いてエスケープシーケンスの処理を無効にすることができます。 bytes リテラルの様々な形式やサポートされているエスケープシーケンスについては 文字列およびバイト列リテラル を参照してください。

bytesリテラルと repr 出力は ASCII テキストをベースにしたものですが、 bytes オブジェクトは、各値が 0 <= x < 256 の範囲に収まるような整数 (この制限に違反しようとすると ValueError が発生します) の不変なシーケンスとして振る舞います。多くのバイナリフォーマットがASCIIテキストを元にした要素を持っていたり何らかのテキスト操作アルゴリズムによって操作されるものの、任意のバイナリデータが一般にテキストになっているわけではないことを強調するためにこのように設計されました (何も考えずにテキスト操作アルゴリズムをASCII非互換なバイナリデータフォーマットに対して行うとデータを破壊することがあります)。

リテラル以外に、幾つかの方法で bytes オブジェクトを作ることができます:

• 指定された長さの、0で埋められた bytes オブジェクト: bytes(10)

• 整数の iterable から: bytes(range(20))

• 既存のバイナリデータからバッファプロトコルでコピーする: bytes(obj)

bytes ビルトイン関数も参照してください。

16 進数で 2 桁の数は正確に 1 バイトに相当するため、16 進整はバイナリデータを表現する形式として広く使われています。 従って、 bytes 型にはその形式でデータを読み取るための追加のクラスメソッドがあります。

classmethod fromhex(string)

この bytes のクラスメソッドは、与えられた文字列オブジェクトをデコードして bytes オブジェクトを返します。それぞれのバイトを 16 進数 2 桁で表現した文字列を指定しなければなりません。ASCII 空白文字は無視されます。

>>> bytes.fromhex('2Ef0 F1f2  ')
b'.\xf0\xf1\xf2'

バージョン 3.7 で変更: bytes.fromhex() は文字列にある空白だけでなく、 ASCII の空白文字全てをスキップするようになりました。

bytes オブジェクトをその 16 進表記に変換するための、反対向きの変換関数があります。

hex([sep[, bytes_per_sep]])

インスタンス内の 1 バイトにつき 2 つの 16 進数を含む、文字列オブジェクトを返します。

>>> b'\xf0\xf1\xf2'.hex()
'f0f1f2'

16進数文字列を読みやすく表示したい場合、単一文字パラメータ sep を指定してセパレータを出力に含めることができます。デフォルトでは、セパレータはバイトごとに表示が区切られるように追加されます。2つ目のオプションパラメータ bytes_per_sep はセパレータを入れる間隔を制御します。正の整数値はセパレータの位置を右から計算し、負の整数値は左から計算します。

>>> value = b'\xf0\xf1\xf2'
>>> value.hex('-')
'f0-f1-f2'
>>> value.hex('_', 2)
'f0_f1f2'
>>> b'UUDDLRLRAB'.hex(' ', -4)
'55554444 4c524c52 4142'

バージョン 3.5 で追加.

バージョン 3.8 で変更: bytes.hex() が、16進数出力の各バイトを分割するセパレータを挿入するためのオプションパラメータ sep と bytes_per_sep をサポートするようになりました。

bytes オブジェクトは (タプルに似た) 整数のシーケンスなので、 bytes オブジェクト b について、 b[0] は整数になり、 b[0:1] は長さ 1 の bytes オブジェクトになります。 (この動作は、文字列に対するインデックス指定もスライスも長さ 1 の文字列を返すのと対照的です。)

bytes オブジェクトの repr 出力はリテラル形式 (b'...') になります。 bytes([46, 46, 46]) などの形式よりも便利な事が多いからです。 bytes オブジェクトはいつでも list(b) で整数のリストに変換できます。

bytearray オブジェクト

bytearray オブジェクトは bytes オブジェクトの可変なバージョンです。

class bytearray([source[, encoding[, errors]]])

bytearray に専用のリテラル構文はないので、コンストラクタを使って作成します:

• 空のインスタンスを作る: bytearray()

• 指定された長さの0で埋められたインスタンスを作る: bytearray(10)

• 整数の iterable から: bytearray(range(20))

• 既存のバイナリデータからバッファプロトコルを通してコピーする: bytearray(b'Hi!')

bytearray オブジェクトは可変なので、 bytes と bytearray の操作 で解説されている bytes オブジェクトと共通の操作に加えて、 mutable シーケンス操作もサポートしています。

bytearray ビルトイン関数も参照してください。

16 進数で 2 桁の数は正確に 1 バイトに相当するため、16 進整はバイナリデータを表現する形式として広く使われています。 従って、 bytearray 型にはその形式でデータを読み取るための追加のクラスメソッドがあります。

classmethod fromhex(string)

この bytearray のクラスメソッドは、与えられた文字列オブジェクトをデコードして bytearray オブジェクトを返します。それぞれのバイトを 16 進数 2 桁で表現した文字列を指定しなければなりません。ASCII 空白文字は無視されます。

>>> bytearray.fromhex('2Ef0 F1f2  ')
bytearray(b'.\xf0\xf1\xf2')

バージョン 3.7 で変更: bytearray.fromhex() は文字列にある空白だけでなく、 ASCII の空白文字全てをスキップするようになりました。

bytearray オブジェクトをその 16 進表記に変換するための、反対向きの変換関数があります。

hex([sep[, bytes_per_sep]])

インスタンス内の 1 バイトにつき 2 つの 16 進数を含む、文字列オブジェクトを返します。

>>> bytearray(b'\xf0\xf1\xf2').hex()
'f0f1f2'

バージョン 3.5 で追加.

バージョン 3.8 で変更: bytes.hex() と同様に、 bytearray.hex() が、16進数出力の各バイトを分割するセパレータを挿入するためのオプションパラメータ sep と bytes_per_sep をサポートするようになりました。

bytearray オブジェクトは整数のシーケンス (リストのようなもの) なので、 bytearray オブジェクト b について、 b[0] は整数になり、 b[0:1] は長さ 1 の bytearray オブジェクトになります。(これは、文字列においてインデックス指定もスライスも長さ 1 の文字列を返すのと対照的です。)

bytearray オブジェクトの表記はバイトのリテラル形式 (bytearray(b'...')) を使用します。これは bytearray([46, 46, 46]) などの形式よりも便利な事が多いためです。 bytearray オブジェクトはいつでも list(b) で整数のリストに変換できます。

bytes と bytearray の操作

bytes と bytearray は両方共 一般のシーケンス操作 をサポートしています。また、両方とも bytes-like object をサポートしている任意のオブジェクトを対象に操作することもできます。この柔軟性により bytes と bytearray を自由に混ぜてもエラーを起こすことなく扱うことができます。ただし、操作の結果のオブジェクトはその操作の順序に依存することになります。

注釈

文字列のメソッドが引数として bytes を受け付けないのと同様、bytes オブジェクトと bytearray オブジェクトのメソッドは引数として文字列を受け付けません。例えば、以下のように書かなければなりません:

a = "abc"
b = a.replace("a", "f")

および:

a = b"abc"
b = a.replace(b"a", b"f")

いくつかの bytes と bytearray の操作は ASCII と互換性のあるバイナリフォーマットが使われていると仮定していますので、フォーマットの不明なバイナリデータに対して使うことは避けるべきです。こうした制約については以下で説明します。

注釈

これらの ASCII ベースの演算を使って ASCII ベースではないバイナリデータを操作すると、データを破壊する恐れがあります。

以下の bytes および bytearray オブジェクトのメソッドは、任意のバイナリデータに対して使用できます。

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

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

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

検索対象の部分シーケンスは、任意の bytes-like object または 0 から 255 の範囲の整数にできます。

sub が空の場合は、文字と文字の間にある空のスライスの数、すなわちbytesオブジェクトの長さに1を加えたものを返します。

バージョン 3.3 で変更: 部分シーケンスとして 0 から 255 の範囲の整数も受け取れるようになりました。

bytes.removeprefix(prefix, /)

bytearray.removeprefix(prefix, /)

バリナリーデータが文字列 prefix で始まる場合、 bytes[len(prefix):] を返します。それ以外の場合、元のバイナリーデータのコピーを返します:

>>> b'TestHook'.removeprefix(b'Test')
b'Hook'
>>> b'BaseTestCase'.removeprefix(b'Test')
b'BaseTestCase'

prefix は、任意の bytes-like object にできます。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

バージョン 3.9 で追加.

bytes.removesuffix(suffix, /)

bytearray.removesuffix(suffix, /)

バイナリーデータが文字列 suffix で終わり、 suffix が空でない場合、 bytes[:-len(suffix)] を返します。それ以外の場合、元のバイナリーデータのコピーを返します:

>>> b'MiscTests'.removesuffix(b'Tests')
b'Misc'
>>> b'TmpDirMixin'.removesuffix(b'Tests')
b'TmpDirMixin'

suffix は、任意の bytes-like object にできます。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

バージョン 3.9 で追加.

bytes.decode(encoding='utf-8', errors='strict')

bytearray.decode(encoding='utf-8', errors='strict')

str にデコードされたbytesを返します。

encoding のデフォルト値は 'utf-8' です; 指定可能な値については 標準エンコーディング を参照してください。

errors はデコーディングエラーをどのように取り扱うかを制御します。 'strict' (デフォルト) では UnicodeError 例外が送出されます。そのほかに指定可能な値は 'ignore', 'replace' と、そして codecs.register_error() で登録された名前です。詳しくは エラーハンドラ を参照してください。

パフォーマンス上の理由から、 errors の値の妥当性は、デコーディングエラーが実際に発生するか、 Python 開発モード が有効になっているか、もしくは デバッグビルド が使われていない限りチェックされません。

注釈

引数 encoding を str に渡すと bytes-like object を直接デコードすることができます。つまり、一時的な bytes や bytearray オブジェクトを作成する必要はありません。

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

バージョン 3.9 で変更: errors 引数の値は Python 開発モード と デバッグモード でチェックされるようになりました。

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

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

バイナリデータが指定された suffix で終わる場合は True を、そうでなければ False を返します。 suffix は見つけたい複数の接尾語のタプルでも構いません。オプションの start が指定されている場合、その位置から判定を開始します。オプションの end が指定されている場合、その位置で比較を終了します。

検索対象の接尾語 (複数も可) は、任意の bytes-like object にできます。

bytes.find(sub[, start[, end]])

bytearray.find(sub[, start[, end]])

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

検索対象の部分シーケンスは、任意の bytes-like object または 0 から 255 の範囲の整数にできます。

注釈

find() メソッドは、 sub の位置を知りたいときにのみ使うべきです。 sub が部分文字列 (訳注: おそらく原文の誤り、正しくは部分シーケンス) であるかどうかのみを調べるには、 in 演算子を使ってください:

>>> b'Py' in b'Python'
True

バージョン 3.3 で変更: 部分シーケンスとして 0 から 255 の範囲の整数も受け取れるようになりました。

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

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

find() と同様ですが、部分シーケンスが見つからなかった場合 ValueError を送出します。

検索対象の部分シーケンスは、任意の bytes-like object または 0 から 255 の範囲の整数にできます。

バージョン 3.3 で変更: 部分シーケンスとして 0 から 255 の範囲の整数も受け取れるようになりました。

bytes.join(iterable)

bytearray.join(iterable)

iterable 中のバイナリデータを結合した bytes または bytearray オブジェクトを返します。 iterable に str オブジェクトなど bytes-like objects ではない値が含まれている場合、 TypeError が送出されます。なお要素間のセパレータは、このメソッドを提供する bytes または bytearray オブジェクトとなります。

static bytes.maketrans(from, to)

static bytearray.maketrans(from, to)

この静的メソッドは、 bytes.translate() に渡すのに適した変換テーブルを返します。このテーブルは、 from 中の各バイトを to の同じ位置にあるバイトにマッピングします。 from と to は両方とも同じ長さの bytes-like objects でなければなりません。

バージョン 3.1 で追加.

bytes.partition(sep)

bytearray.partition(sep)

区切り sep が最初に出現する位置でシーケンスを分割し、 3 要素のタプルを返します。タプルの内容は、区切りの前の部分、その区切りオブジェクトまたはその bytearray 型のコピー、そして区切りの後ろの部分です。もし区切りが見つからなければ、タプルには元のシーケンスのコピーと、その後ろに二つの空の bytes または bytearray オブジェクトが入ります。

検索する区切りとしては、任意の bytes-like object を指定できます。

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

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

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

検索する部分シーケンスおよび置換後の部分シーケンスとしては、任意の bytes-like object を指定できます。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

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

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

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

検索対象の部分シーケンスは、任意の bytes-like object または 0 から 255 の範囲の整数にできます。

バージョン 3.3 で変更: 部分シーケンスとして 0 から 255 の範囲の整数も受け取れるようになりました。

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

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

rfind() と同様ですが、部分シーケンス sub が見つからなかった場合 ValueError を送出します。

検索対象の部分シーケンスは、任意の bytes-like object または 0 から 255 の範囲の整数にできます。

バージョン 3.3 で変更: 部分シーケンスとして 0 から 255 の範囲の整数も受け取れるようになりました。

bytes.rpartition(sep)

bytearray.rpartition(sep)

区切り sep が最後に出現する位置でシーケンスを分割し、 3 要素のタプルを返します。タプルの内容は、区切りの前の部分、その区切りオブジェクトまたはその bytearray 型のコピー、そして区切りの後ろの部分です。もし区切れなければ、タプルには二つの空の bytes または bytearray オブジェクトと、その後ろに元のシーケンスのコピーが入ります。

検索する区切りとしては、任意の bytes-like object を指定できます。

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

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

バイナリデータが指定された prefix で始まる場合は True を、そうでなければ False を返します。 prefix は見つけたい複数の接頭語のタプルでも構いません。オプションの start が指定されている場合、その位置から判定を開始します。オプションの end が指定されている場合、その位置で比較を終了します。

検索対象の接頭語 (複数も可) は、任意の bytes-like object にできます。

bytes.translate(table, /, delete=b'')

bytearray.translate(table, /, delete=b'')

オプション引数 delete に現れるすべてのバイトを除去し、残ったバイトを与えられた変換テーブルに従ってマップした、バイト列やバイト配列オブジェクトのコピーを返します。変換テーブルは長さ 256 のバイト列オブジェクトでなければなりません。

変換テーブルの作成に、 bytes.maketrans() メソッドを使うこともできます。

文字を削除するだけの変換には、 table 引数を None に設定してください:

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

バージョン 3.6 で変更: delete はキーワード引数として指定可能になりました。

以下の bytes および bytearray オブジェクトのメソッドは、 ASCII と互換性のあるバイナリフォーマットが使われていると仮定していますが、適切な引数を指定すれば任意のバイナリデータに使用できます。なお、このセクションで紹介する bytearray のメソッドはすべてインプレースで動作 せず 、新しいオブジェクトを生成します。

bytes.center(width[, fillbyte])

bytearray.center(width[, fillbyte])

長さ width の中央寄せされたシーケンスのコピーを返します。パディングには fillbyte で指定された値 (デフォルトでは ASCII スペース) が使われます。 bytes オブジェクトの場合、 width が len(s) 以下なら元のシーケンスが返されます。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.ljust(width[, fillbyte])

bytearray.ljust(width[, fillbyte])

長さ width の左寄せされたシーケンスのコピーを返します。パディングには fillbyte で指定された値 (デフォルトでは ASCII スペース) が使われます。 bytes オブジェクトの場合、 width が len(s) 以下なら元のシーケンスが返されます。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.lstrip([chars])

bytearray.lstrip([chars])

先頭から特定のバイト値を除去したコピーを返します。引数 chars は除去されるバイト値の集合を指定するバイナリシーケンスです － この名前は、このメソッドが通常は ASCII 文字列に対して使われることに由来しています。 chars が省略されるか None の場合、 ASCII の空白文字 (訳注: 空白文字の定義については bytearray.isspace() を参照) が除去されます。なお chars 引数と一致する接頭辞が除去されるのではなく、それに含まれるバイトの組み合わせ全てが除去されます:

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

削除したいバイト値のバイナリシーケンスには、 bytes-like object を指定することができます。バイナリシーケンスで指定した文字の集合全てではなく、指定した文字列そのものを接頭辞として削除するメソッドについては、 removeprefix() を参照してください。使用例:

>>> b'Arthur: three!'.lstrip(b'Arthur: ')
b'ee!'
>>> b'Arthur: three!'.removeprefix(b'Arthur: ')
b'three!'

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.rjust(width[, fillbyte])

bytearray.rjust(width[, fillbyte])

長さ width の右寄せされたシーケンスのコピーを返します。パディングには fillbyte で指定された値 (デフォルトでは ASCII スペース) が使われます。 bytes オブジェクトの場合、 width が len(s) 以下なら元のシーケンスが返されます。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.rsplit(sep=None, maxsplit=-1)

bytearray.rsplit(sep=None, maxsplit=-1)

sep を区切りとして、同じ型の部分シーケンスに分割します。 maxsplit が与えられた場合、シーケンスの 右端 から最大 maxsplit 回だけ分割を行います。 sep が指定されていないか None のとき、 ASCII 空白文字の組み合わせで作られる部分シーケンスすべてが区切りとなります。右から分割していくことを除けば、 rsplit() は後ほど詳しく述べる split() と同様に振る舞います。

bytes.rstrip([chars])

bytearray.rstrip([chars])

末尾から特定のバイト値を除去したコピーを返します。引数 chars は除去されるバイト値の集合を指定するバイナリシーケンスです － この名前は、このメソッドが通常は ASCII 文字列に対して使われることに由来しています。 chars が省略されるか None の場合、 ASCII の空白文字 (訳注: 空白文字の定義については bytearray.isspace() を参照) が除去されます。なお chars 引数と一致する接尾辞が除去されるのではなく、それに含まれるバイトの組み合わせ全てが除去されます:

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

削除したいバイト値のバイナリシーケンスには、 bytes-like object を指定することができます。バイナリシーケンスで指定した文字の集合全てではなく、指定した文字列そのものを接尾辞として削除するメソッドについては、 removesuffix() を参照してください。使用例:

>>> b'Monty Python'.rstrip(b' Python')
b'M'
>>> b'Monty Python'.removesuffix(b' Python')
b'Monty'

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.split(sep=None, maxsplit=-1)

bytearray.split(sep=None, maxsplit=-1)

sep を区切りとして、同じ型の部分シーケンスに分割します。 maxsplit が与えられ、かつ負の数でない場合、シーケンスの 左端 から最大 maxsplit 回だけ分割を行います (したがって結果のリストの要素数は最大で maxsplit+1 になります)。 maxsplit が指定されていないか -1 のとき、分割の回数に制限はありません (可能なだけ分割されます)。

If sep is given, consecutive delimiters are not grouped together and are deemed to delimit empty subsequences (for example, b'1,,2'.split(b',') returns [b'1', b'', b'2']). The sep argument may consist of a multibyte sequence (for example, b'1<>2<>3'.split(b'<>') returns [b'1', b'2', b'3']). Splitting an empty sequence with a specified separator returns [b''] or [bytearray(b'')] depending on the type of object being split. The sep argument may be any bytes-like object.

例えば:

>>> b'1,2,3'.split(b',')
[b'1', b'2', b'3']
>>> b'1,2,3'.split(b',', maxsplit=1)
[b'1', b'2,3']
>>> b'1,2,,3,'.split(b',')
[b'1', b'2', b'', b'3', b'']

sep が指定されていないか None の場合、異なる分割アルゴリズムが適用されます。連続する ASCII 空白文字はひとつの区切りとみなされ、またシーケンスの先頭や末尾に空白があっても、結果の最初や最後に空のシーケンスは含まれません。したがって区切りを指定せずに空のシーケンスや ASCII 空白文字だけのシーケンスを分割すると、 [] が返されます。

例えば:

>>> b'1 2 3'.split()
[b'1', b'2', b'3']
>>> b'1 2 3'.split(maxsplit=1)
[b'1', b'2 3']
>>> b'   1   2   3   '.split()
[b'1', b'2', b'3']

bytes.strip([chars])

bytearray.strip([chars])

先頭および末尾から特定のバイト値を除去したコピーを返します。引数 chars は除去されるバイト値の集合を指定するバイナリシーケンスです － この名前は、このメソッドが通常は ASCII 文字列に対して使われることに由来しています。 chars が省略されるか None の場合、 ASCII の空白文字 (訳注: 空白文字の定義については bytearray.isspace() を参照) が除去されます。なお chars 引数と一致する接頭辞および接尾辞が除去されるのではなく、それに含まれるバイトの組み合わせ全てが除去されます:

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

除去対象のバイト値を含むバイナリシーケンスには、任意の bytes-like object を指定できます。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

以下の bytes および bytearray オブジェクトのメソッドは、 ASCII と互換性のあるバイナリフォーマットが使われていると仮定しており、任意のバイナリデータに対して使用すべきではありません。なお、このセクションで紹介する bytearray のメソッドはすべてインプレースで動作 せず 、新しいオブジェクトを生成します。

bytes.capitalize()

bytearray.capitalize()

各バイトを ASCII 文字と解釈して、最初のバイトを大文字にし、残りを小文字にしたシーケンスのコピーを返します。 ASCII 文字と解釈できないバイト値は、変更されません。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.expandtabs(tabsize=8)

bytearray.expandtabs(tabsize=8)

桁 (column) 位置と指定されたタブ幅 (tab size) に応じて、全ての ASCII タブ文字を 1 つ以上の ASCII スペース文字に置換したシーケンスのコピーを返します。ここで tabsize バイトごとの桁位置をタブ位置とします (デフォルト値である 8 の場合、タブ位置は 0 桁目、 8 桁目、 16 桁目、と続いていきます)。シーケンスを展開するにあたって、まず現桁位置をゼロに設定し、シーケンスを 1 バイトずつ調べていきます。もしバイト値が ASCII タブ文字 (b'\t') であれば、現桁位置が次のタブ位置と一致するまで 1 つ以上の ASCII スペース文字を結果のシーケンスに挿入していきます（ASCII タブ文字自体はコピーしません）。もしバイト値が ASCII 改行文字 (b'\n' もしくは b'\r') であれば、そのままコピーした上で現桁位置を 0 にリセットします。その他のバイト値については変更せずにコピーし、そのバイト値の表示のされ方（訳注: 全角、半角など）に関わらず現桁位置を 1 つ増加させます:

>>> b'01\t012\t0123\t01234'.expandtabs()
b'01      012     0123    01234'
>>> b'01\t012\t0123\t01234'.expandtabs(4)
b'01  012 0123    01234'

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.isalnum()

bytearray.isalnum()

シーケンスが空でなく、かつ全てのバイト値が ASCII 文字のアルファベットまたは数字である場合は True を、そうでなければ False を返します。ここでの ASCII 文字のアルファベットとはシーケンス b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。 ASCII 文字の数字とは b'0123456789' に含まれるバイト値です。

例えば:

>>> b'ABCabc1'.isalnum()
True
>>> b'ABC abc1'.isalnum()
False

bytes.isalpha()

bytearray.isalpha()

シーケンスが空でなく、かつ全てのバイト値が ASCII 文字のアルファベットである場合は True を、そうでなければ False を返します。ここでの ASCII 文字のアルファベットとはシーケンス b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。

例えば:

>>> b'ABCabc'.isalpha()
True
>>> b'ABCabc1'.isalpha()
False

bytes.isascii()

bytearray.isascii()

シーケンスが空であるか、シーケンスの全てのバイトが ASCII である場合に True を、それ以外の場合に False を返します。 ASCII バイトは 0-0x7F の範囲にあります。

バージョン 3.7 で追加.

bytes.isdigit()

bytearray.isdigit()

シーケンスが空でなく、かつ全てのバイト値が ASCII 文字の数字である場合は True を、そうでなければ False を返します。ここでの ASCII 文字の数字とは b'0123456789' に含まれるバイト値です。

例えば:

>>> b'1234'.isdigit()
True
>>> b'1.23'.isdigit()
False

bytes.islower()

bytearray.islower()

シーケンス中に小文字アルファベットの ASCII 文字が一つ以上あり、かつ大文字アルファベットの ASCII 文字が一つも無い場合に True を返します。そうでなければ False を返します。

例えば:

>>> b'hello world'.islower()
True
>>> b'Hello world'.islower()
False

ここでの小文字の ASCII 文字とは b'abcdefghijklmnopqrstuvwxyz' に含まれるバイト値です。また大文字の ASCII 文字とは b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。

bytes.isspace()

bytearray.isspace()

シーケンスが空でなく、かつ全てのバイト値が ASCII 空白文字である場合は True を、そうでなければ False を返します。ここでの ASCII 空白文字とはシーケンス b' \t\n\r\x0b\f' に含まれるバイト値です (半角スペース、タブ、ラインフィード、キャリッジリターン、垂直タブ、フォームフィード) 。

bytes.istitle()

bytearray.istitle()

シーケンスが空でなく、かつ ASCII のタイトルケース文字列になっている場合は True を、そうでなければ False を返します。「タイトルケース文字列」の定義については bytes.title() を参照してください。

例えば:

>>> b'Hello World'.istitle()
True
>>> b'Hello world'.istitle()
False

bytes.isupper()

bytearray.isupper()

シーケンス中に大文字アルファベットの ASCII 文字が一つ以上あり、かつ小文字アルファベットの ASCII 文字が一つも無い場合に True を返します。そうでなければ False を返します。

例えば:

>>> b'HELLO WORLD'.isupper()
True
>>> b'Hello world'.isupper()
False

ここでの小文字の ASCII 文字とは b'abcdefghijklmnopqrstuvwxyz' に含まれるバイト値です。また大文字の ASCII 文字とは b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。

bytes.lower()

bytearray.lower()

シーケンスに含まれる大文字アルファベットの ASCII 文字を全て小文字アルファベットに変換したシーケンスのコピーを返します。

例えば:

>>> b'Hello World'.lower()
b'hello world'

ここでの小文字の ASCII 文字とは b'abcdefghijklmnopqrstuvwxyz' に含まれるバイト値です。また大文字の ASCII 文字とは b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.splitlines(keepends=False)

bytearray.splitlines(keepends=False)

バイナリシーケンスを ASCII の改行コードで分割し、各行をリストにして返します。このメソッドは universal newlines アプローチで行を分割します。 keepends 引数に真を与えた場合を除き、改行コードは結果のリストに含まれません。

例えば:

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

split() とは違って、空シーケンスに対して区切り sep を与えて呼び出すと空のリストを返します。またシーケンス末尾に改行コードがある場合、（訳註: その後ろに空行があるとは判断せず）余分な行を生成することはありません:

>>> b"".split(b'\n'), b"Two lines\n".split(b'\n')
([b''], [b'Two lines', b''])
>>> b"".splitlines(), b"One line\n".splitlines()
([], [b'One line'])

bytes.swapcase()

bytearray.swapcase()

シーケンスに含まれる小文字アルファベットの ASCII 文字を全て大文字アルファベットに変換し、さらに大文字アルファベットを同様に小文字アルファベットに変換したシーケンスのコピーを返します。

例えば:

>>> b'Hello World'.swapcase()
b'hELLO wORLD'

ここでの小文字の ASCII 文字とは b'abcdefghijklmnopqrstuvwxyz' に含まれるバイト値です。また大文字の ASCII 文字とは b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。

Unlike str.swapcase(), it is always the case that bin.swapcase().swapcase() == bin for the binary versions. Case conversions are symmetrical in ASCII, even though that is not generally true for arbitrary Unicode code points.

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.title()

bytearray.title()

タイトルケース化したバイナリシーケンスを返します。具体的には、各単語が大文字アルファベットの ASCII 文字で始まり、かつ残りの文字が小文字アルファベットになっているシーケンスが返ります。大文字小文字の区別が無いバイト値については変更されずそのままになります。

例えば:

>>> b'Hello world'.title()
b'Hello World'

ここでの小文字の ASCII 文字とは b'abcdefghijklmnopqrstuvwxyz' に含まれるバイト値です。また大文字の ASCII 文字とは b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。その他のバイト値については、大文字小文字の区別はありません。

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

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

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

>>> import re
>>> def titlecase(s):
...     return re.sub(rb"[A-Za-z]+('[A-Za-z]+)?",
...                   lambda mo: mo.group(0)[0:1].upper() +
...                              mo.group(0)[1:].lower(),
...                   s)
...
>>> titlecase(b"they're bill's friends.")
b"They're Bill's Friends."

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.upper()

bytearray.upper()

シーケンスに含まれる小文字アルファベットの ASCII 文字を全て大文字アルファベットに変換したシーケンスのコピーを返します。

例えば:

>>> b'Hello World'.upper()
b'HELLO WORLD'

ここでの小文字の ASCII 文字とは b'abcdefghijklmnopqrstuvwxyz' に含まれるバイト値です。また大文字の ASCII 文字とは b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.zfill(width)

bytearray.zfill(width)

長さが width になるよう ASCII b'0' で左詰めしたシーケンスのコピーを返します。先頭が符号接頭辞 (b'+'/b'-') だった場合、 b'0' は符号の前ではなく 後 に挿入されます。 bytes オブジェクトの場合、 width が len(seq) 以下であれば元のシーケンスが返ります。

例えば:

>>> b"42".zfill(5)
b'00042'
>>> b"-42".zfill(5)
b'-0042'

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

printf 形式での bytes の書式化

注釈

ここで述べる書式化演算には様々な癖があり、よく間違いの元になっています (タプルや辞書を正しく表示できないなど)。もし表示する値がタプルや辞書かもしれない場合、それをタプルに包むようにしてください。

bytes オブジェクト (bytes/bytearray) には固有の操作: % 演算子 (モジュロ) があります。この演算子は bytes の 書式化 または 補間 演算子とも呼ばれます。format % values (format は bytes オブジェクト) とすると、format 中の % 変換指定は values 中のゼロ個またはそれ以上の要素で置換されます。この動作は C 言語における sprintf() に似ています。

format が単一の引数しか要求しない場合、 values はタプルではない単一のオブジェクトで問題ありません。 [5] それ以外の場合、 values は書式シーケンス（訳註: 先の例での format ）中で指定された項目と正確に同じ数の要素を含むタプルか、単一のマッピング型のオブジェクト (たとえば辞書) でなければなりません。

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

1. 指定子の開始を示す文字 '%' 。

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

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

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

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

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

7. 変換型。

% 演算子の右側の引数が辞書の場合 (またはその他のマッピング型の場合) 、 bytes オブジェクト中のフォーマットには、辞書のキーを丸括弧で囲って文字 '%' の直後に書いたものが含まれていなければ なりません 。マップキーは書式化したい値をマッピングから選び出します。例えば:

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

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

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

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

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

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

変換	意味	注釈
'd'	符号付き 10 進整数。
'i'	符号付き 10 進整数。
'o'	符号付き 8 進数。	(1)
'u'	旧式の型 -- 'd' と同じです。	(8)
'x'	符号付き 16 進数 (小文字)。	(2)
'X'	符号付き 16 進数 (大文字)。	(2)
'e'	Floating point exponential format (lowercase).	(3)
'E'	Floating point exponential format (uppercase).	(3)
'f'	Floating point decimal format.	(3)
'F'	Floating point decimal format.	(3)
'g'	Floating point format. Uses lowercase exponential format if exponent is less than -4 or not less than precision, decimal format otherwise.	(4)
'G'	Floating point format. Uses uppercase exponential format if exponent is less than -4 or not less than precision, decimal format otherwise.	(4)
'c'	1 バイト (整数または要素 1 つの bytes/bytearray オブジェクトを受理します)
'b'	バイナリシーケンス (buffer protocol をサポートするか、 __bytes__() メソッドがあるオブジェクト)	(5)
's'	's' は 'b' の別名です。Python 2/3 の両方を対象としたコードでのみ使用すべきです。	(6)
'a'	バイナリシーケンス (Python オブジェクトを repr(obj).encode('ascii', 'backslashreplace') で変換します)。	(5)
'r'	'r' は 'a' の別名です。Python 2/3 の両方を対象としたコードでのみ使用すべきです。	(7)
'%'	引数を変換せず、返される文字列中では文字 '%' になります。

注釈:

1. 別の形式を指定（訳注: 変換フラグ # を使用）すると 8 進数を表す接頭辞 ('0o') が最初の数字の前に挿入されます。

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

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

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

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

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

5. 精度が N なら、出力は N 文字に切り詰められます。

6. b'%s' は非推奨ですが、3.x 系では削除されません。

7. b'%r' は非推奨ですが、3.x 系では削除されません。

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

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

参考

PEP 461 - bytes と bytearray への % 書式化の追加

バージョン 3.5 で追加.

メモリビュー

memoryview オブジェクトは、Python コードが バッファプロトコル をサポートするオブジェクトの内部データへ、コピーすることなくアクセスすることを可能にします。

class memoryview(object)

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

memoryview は元となる object が扱うメモリーの最小単位を 要素 として扱います。多くの単純なオブジェクト、例えば bytes や bytearray では、要素は単バイトになりますが、他の array.array 等の型では、要素はより大きくなりえます。

len(view) is equal to the length of tolist. If view.ndim = 0, the length is 1. If view.ndim = 1, the length is equal to the number of elements in the view. For higher dimensions, the length is equal to the length of the nested list representation of the view. The itemsize attribute will give you the number of bytes in a single element.

memoryview はスライスおよびインデックス指定で内容を取得できます。一次元のスライスは部分ビューになります:

>>> v = memoryview(b'abcefg')
>>> v[1]
98
>>> v[-1]
103
>>> v[1:4]
<memory at 0x7f3ddc9f4350>
>>> bytes(v[1:4])
b'bce'

もしメモリビューの format が struct モジュールによって定義されているネイティブのフォーマット指定子であれば、整数または整数のタプルでのインデックス指定により適切な型の 要素1つ を得ることができます。一次元のメモリビューでは、整数または整数 1 つのタプルでインデックス指定できます。多次元のメモリビューでは、その次元数を ndim としたとき、ちょうど ndim 個の整数からなるタプルでインデックス指定できます。ゼロ次元のメモリビューでは、空のタプルでインデックス指定できます。

format が単バイト単位ではない例を示します:

>>> import array
>>> a = array.array('l', [-11111111, 22222222, -33333333, 44444444])
>>> m = memoryview(a)
>>> m[0]
-11111111
>>> m[-1]
44444444
>>> m[::2].tolist()
[-11111111, -33333333]

メモリビューの参照しているオブジェクトが書き込み可能であれば、一次元スライスでの代入が可能です。ただしサイズの変更はできません:

>>> data = bytearray(b'abcefg')
>>> v = memoryview(data)
>>> v.readonly
False
>>> v[0] = ord(b'z')
>>> data
bytearray(b'zbcefg')
>>> v[1:4] = b'123'
>>> data
bytearray(b'z123fg')
>>> v[2:3] = b'spam'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: memoryview assignment: lvalue and rvalue have different structures
>>> v[2:6] = b'spam'
>>> data
bytearray(b'z1spam')

'B', 'b', 'c' いずれかのフォーマットの ハッシュ可能 な (読み出し専用の) 型の1次元メモリビューもまた、ハッシュ可能です。ハッシュは hash(m) == hash(m.tobytes()) として定義されています:

>>> v = memoryview(b'abcefg')
>>> hash(v) == hash(b'abcefg')
True
>>> hash(v[2:4]) == hash(b'ce')
True
>>> hash(v[::-2]) == hash(b'abcefg'[::-2])
True

バージョン 3.3 で変更: 1 次元のメモリビューがスライス可能になりました。 'B', 'b', 'c' いずれかのフォーマットの 1 次元のメモリビューが ハッシュ可能 になりました。

バージョン 3.4 で変更: memoryview は自動的に collections.abc.Sequence へ登録されるようになりました。

バージョン 3.5 で変更: メモリビューは整数のタプルでインデックス指定できるようになりました。

memoryview にはいくつかのメソッドがあります:

__eq__(exporter)

memoryview と PEP 3118 エクスポーターは、 shape が同じで、 struct のフォーマットで解釈したときの値が同じ場合に同値になります。

tolist() がサポートしている struct フォーマットの一部では、 v.tolist() == w.tolist() が成り立つときに v == w になります:

>>> import array
>>> a = array.array('I', [1, 2, 3, 4, 5])
>>> b = array.array('d', [1.0, 2.0, 3.0, 4.0, 5.0])
>>> c = array.array('b', [5, 3, 1])
>>> x = memoryview(a)
>>> y = memoryview(b)
>>> x == a == y == b
True
>>> x.tolist() == a.tolist() == y.tolist() == b.tolist()
True
>>> z = y[::-2]
>>> z == c
True
>>> z.tolist() == c.tolist()
True

どちらかの書式文字列が struct モジュールにサポートされていなければ、 (書式文字列とバッファの内容が同一でも) オブジェクトは常に等しくないものとして比較されます:

>>> from ctypes import BigEndianStructure, c_long
>>> class BEPoint(BigEndianStructure):
...     _fields_ = [("x", c_long), ("y", c_long)]
...
>>> point = BEPoint(100, 200)
>>> a = memoryview(point)
>>> b = memoryview(point)
>>> a == point
False
>>> a == b
False

Note that, as with floating point numbers, v is w does not imply v == w for memoryview objects.

バージョン 3.3 で変更: 以前のバージョンは、要素フォーマットと論理的な配列構造を無視して生のメモリを比較していました。

tobytes(order='C')

バッファ中のデータをバイト文字列として返します。これはメモリビューに対して bytes コンストラクタを呼び出すのと同等です。

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

連続でない配列については、結果はすべての要素がバイトに変換されたものを含むフラットなリスト表現に等しくなります。 tobytes() は、 struct モジュール文法にないものを含むすべての書式文字列をサポートします。

バージョン 3.8 で追加: order は {'C', 'F', 'A'} のいずれかを取ることができます。 order が 'C' か 'F' の場合、元の配列は C または Fortran のデータ並びにそれぞれ変換されます。連続したデータに対するビューの場合、 'A' は物理メモリ上のデータの正確なコピーを返します。特に、メモリ上における Fortran のデータ並びは保存されます。不連続なデータに対するビューの場合、データはまず C のデータ並びに変換されます。 order=None は order='C' と同じです。

hex([sep[, bytes_per_sep]])

バッファ中の各バイトを 2 つの 16 進数で表した文字列を返します:

>>> m = memoryview(b"abc")
>>> m.hex()
'616263'

バージョン 3.5 で追加.

バージョン 3.8 で変更: bytes.hex() と同様に、 memoryview.hex() は、16進数出力のバイト文字列を分割するセパレータを挿入するためのオプションパラメータ sep と bytes_per_sep をサポートするようになりました。

tolist()

バッファ中のデータを要素のリストとして返します。

>>> memoryview(b'abc').tolist()
[97, 98, 99]
>>> import array
>>> a = array.array('d', [1.1, 2.2, 3.3])
>>> m = memoryview(a)
>>> m.tolist()
[1.1, 2.2, 3.3]

バージョン 3.3 で変更: tolist() が struct モジュール文法に含まれるすべての単一文字の native フォーマットと多次元の表現をサポートするようになりました。

toreadonly()

読み込み専用のメモリビューオブジェクトを返します。元のメモリビューオブジェクトは変更されません。

>>> m = memoryview(bytearray(b'abc'))
>>> mm = m.toreadonly()
>>> mm.tolist()
[97, 98, 99]
>>> mm[0] = 42
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: cannot modify read-only memory
>>> m[0] = 43
>>> mm.tolist()
[43, 98, 99]

バージョン 3.8 で追加.

release()

memoryview オブジェクトによって晒されている、元になるバッファを解放します。多くのオブジェクトはビューに支配されているときに特殊なふるまいをします (例えば、 bytearray は大きさの変更を一時的に禁止します)。ですから、release() を呼び出すことは、これらの制約をできるだけ早く取り除く (そしてぶら下がったリソースをすべて解放する) のに便利です。

After this method has been called, any further operation on the view raises a ValueError (except release() itself which can be called multiple times):

>>> m = memoryview(b'abc')
>>> m.release()
>>> m[0]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: operation forbidden on released memoryview object

コンテキストマネージャプロトコルは、 with 文を使って同様の効果を得るのに使えます:

>>> with memoryview(b'abc') as m:
...     m[0]
...
97
>>> m[0]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: operation forbidden on released memoryview object

バージョン 3.2 で追加.

cast(format[, shape])

memoryview を新しいフォーマットか shape にキャストします。 shape はデフォルトで [byte_length//new_itemsize] で、 1次元配列になります。戻り値は memoryview ですが、バッファー自体はコピーされません。サポートされている変換は 1次元配列 -> C言語型の連続配列 と C言語型の連続配列 -> 1次元配列 です（参考: contiguous）。

キャスト後のフォーマットは単一要素のネイティブフォーマットに限定され、 struct の文法で指定します。利用可能なフォーマットのひとつはバイトフォーマット ('B', 'b' または 'c') です。キャスト後のバイト長は元の長さと同じでなければなりません。全てのフォーマットのバイト長は、オペレーティングシステムに依存することに注意してください。

1次元 long から 1次元 unsigned byte へのキャスト:

>>> import array
>>> a = array.array('l', [1,2,3])
>>> x = memoryview(a)
>>> x.format
'l'
>>> x.itemsize
8
>>> len(x)
3
>>> x.nbytes
24
>>> y = x.cast('B')
>>> y.format
'B'
>>> y.itemsize
1
>>> len(y)
24
>>> y.nbytes
24

1次元 unsigned byte から 1次元 char へのキャスト:

>>> b = bytearray(b'zyz')
>>> x = memoryview(b)
>>> x[0] = b'a'
Traceback (most recent call last):
  ...
TypeError: memoryview: invalid type for format 'B'
>>> y = x.cast('c')
>>> y[0] = b'a'
>>> b
bytearray(b'ayz')

1次元 byte から 3次元 int へ、そして 1次元 signed char へのキャスト:

>>> import struct
>>> buf = struct.pack("i"*12, *list(range(12)))
>>> x = memoryview(buf)
>>> y = x.cast('i', shape=[2,2,3])
>>> y.tolist()
[[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]]
>>> y.format
'i'
>>> y.itemsize
4
>>> len(y)
2
>>> y.nbytes
48
>>> z = y.cast('b')
>>> z.format
'b'
>>> z.itemsize
1
>>> len(z)
48
>>> z.nbytes
48

1次元 unsigned long から 2次元 unsigned long へのキャスト:

>>> buf = struct.pack("L"*6, *list(range(6)))
>>> x = memoryview(buf)
>>> y = x.cast('L', shape=[2,3])
>>> len(y)
2
>>> y.nbytes
48
>>> y.tolist()
[[0, 1, 2], [3, 4, 5]]

バージョン 3.3 で追加.

バージョン 3.5 で変更: 単バイトのビューへキャストする場合、キャスト元のフォーマットについて制約は無くなりました。

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

obj

memoryview が参照しているオブジェクト:

>>> b  = bytearray(b'xyz')
>>> m = memoryview(b)
>>> m.obj is b
True

バージョン 3.3 で追加.

nbytes

nbytes == product(shape) * itemsize == len(m.tobytes()). その配列が連続表現において利用するスペースです。これは len(m) と一致するとは限りません:

>>> import array
>>> a = array.array('i', [1,2,3,4,5])
>>> m = memoryview(a)
>>> len(m)
5
>>> m.nbytes
20
>>> y = m[::2]
>>> len(y)
3
>>> y.nbytes
12
>>> len(y.tobytes())
12

多次元配列:

>>> import struct
>>> buf = struct.pack("d"*12, *[1.5*x for x in range(12)])
>>> x = memoryview(buf)
>>> y = x.cast('d', shape=[3,4])
>>> y.tolist()
[[0.0, 1.5, 3.0, 4.5], [6.0, 7.5, 9.0, 10.5], [12.0, 13.5, 15.0, 16.5]]
>>> len(y)
3
>>> y.nbytes
96

バージョン 3.3 で追加.

readonly

メモリが読み出し専用かどうかを示す真偽値です。

format

ビューの中の各要素に対する (struct モジュールスタイルの) フォーマットを含む文字列。 memoryview は、任意のフォーマット文字列を使ってエクスポーターから作成することができます。しかし、いくつかのメソッド(例えば tolist()) はネイティブの単一要素フォーマットに制限されます。

バージョン 3.3 で変更: フォーマット 'B' は struct モジュール構文で扱われるようになりました。これは memoryview(b'abc')[0] == b'abc'[0] == 97 ということを意味します。

itemsize

memoryview の各要素のバイト単位の大きさ:

>>> import array, struct
>>> m = memoryview(array.array('H', [32000, 32001, 32002]))
>>> m.itemsize
2
>>> m[0]
32000
>>> struct.calcsize('H') == m.itemsize
True

ndim

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

shape

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

バージョン 3.3 で変更: ndim = 0 の場合は None ではなく空のタプルとなるよう変更されました。

strides

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

バージョン 3.3 で変更: ndim = 0 の場合は None ではなく空のタプルとなるよう変更されました。

suboffsets

PILスタイルの配列の内部で利用している値。この値はただの情報として公開されています。

c_contiguous

メモリーが C 形式の順序で連続しているかどうかを示す真偽値（参考: contiguous ）。

バージョン 3.3 で追加.

f_contiguous

メモリーがFortran形式の順序で連続しているかどうかを示す真偽値（参考: contiguous ）。

バージョン 3.3 で追加.

contiguous

メモリーが連続しているかどうかを示す真偽値（参考: contiguous ）。

バージョン 3.3 で追加.

set（集合）型 --- set, frozenset

set オブジェクトは、固有の hashable オブジェクトの順序なしコレクションです。通常の用途には、帰属テスト、シーケンスからの重複除去、積集合、和集合、差集合、対称差 (排他的論理和) のような数学的演算の計算が含まれます。(他のコンテナについては組み込みの dict, list, tuple クラスや collections モジュールを参照してください。)

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

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

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

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

class set([iterable])

class frozenset([iterable])

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

集合はいくつかの方法で生成できます:

• 波括弧内にカンマ区切りで要素を列挙する: {'jack', 'sjoerd'}

• 集合内包表記を使う: {c for c in 'abracadabra' if c not in 'abc'}

• 型コンストラクタを使う: set(), set('foobar'), set(['a', 'b', 'foo'])

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

len(s)

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

x in s

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

x not in s

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

isdisjoint(other)

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

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 の要素からなる新しい集合を返します。

intersection(*others)

set & other & ...

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

difference(*others)

set - other - ...

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

symmetric_difference(other)

set ^ other

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

copy()

集合の浅いコピーを返します。

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

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

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

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

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

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

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

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

update(*others)

set |= other | ...

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

intersection_update(*others)

set &= other & ...

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

difference_update(*others)

set -= other | ...

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

symmetric_difference_update(other)

set ^= other

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

add(elem)

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

remove(elem)

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

discard(elem)

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

pop()

s から任意の要素を取り除き、それを返します。集合が空の場合、 KeyError を送出します

clear()

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

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

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

マッピング型 --- dict

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

辞書のキーには、 ほぼ どんな値も使うことができます。 キーとして使えないのは、 hashable (ハッシュ可能) でない値、すなわちリストや辞書のようなミュータブルな型 (内包する値ではなくオブジェクト自体が同一であるかによって比較が行われるような型)です。 比較した際に等しいとみなされる値 (例えば 1 と 1.0 と True) は、どれを使っても同じエントリーに関連付けられます。

class dict(**kwargs)

class dict(mapping, **kwargs)

class dict(iterable, **kwargs)

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

辞書はいくつかの方法で生成できます:

• 波括弧内にカンマ区切りで key: value 対を列挙する: {'jack': 4098, 'sjoerd': 4127} あるいは {4098: 'jack', 4127: 'sjoerd'}

• 辞書内包表記を使う: {}, {x: x ** 2 for x in range(10)}

• 型コンストラクタを使う: dict(), dict([('foo', 100), ('bar', 200)]), dict(foo=100, bar=200)

If no positional argument is given, an empty dictionary is created. If a positional argument is given and it is a mapping object, a dictionary is created with the same key-value pairs as the mapping object. Otherwise, the positional argument must be an iterable object. Each item in the iterable must itself be an iterable with exactly two objects. The first object of each item becomes a key in the new dictionary, and the second object the corresponding value. If a key occurs more than once, the last value for that key becomes the corresponding value in the new dictionary.

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

例を出すと、次の例は全て {"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})
>>> f = dict({'one': 1, 'three': 3}, two=2)
>>> a == b == c == d == e == f
True

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

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

list(d)

辞書 d で使われている全てのキーのリストを返します。

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__ が collections.defaultdict で使われています。

d[key] = value

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

del d[key]

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

key in d

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

key not in d

not key in d と等価です。

iter(d)

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

clear()

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

copy()

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

classmethod fromkeys(iterable[, value])

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

fromkeys() は新しい辞書を返すクラスメソッドです。 value はデフォルトで None となります。 作られる辞書内のすべての値が同一のインスタンスを指すことになるため、value にミュータブルなオブジェクト (例えば空のリスト) を指定しても通常意味はありません。 別々の値を指すようにしたい場合は、代わりに 辞書内包表記 を使用してください。

get(key[, default])

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

items()

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

keys()

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

pop(key[, default])

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

popitem()

任意の (key, value) 対を辞書から消去して返します。 対は LIFO の順序で返却されます。

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

バージョン 3.7 で変更: LIFO 順序が保証されるようになりました。 以前のバージョンでは、 popitem() は任意の key/value 対を返していました。

reversed(d)

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

バージョン 3.8 で追加.

setdefault(key[, default])

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

update([other])

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

update() accepts either another dictionary object or an iterable of key/value pairs (as tuples or other iterables of length two). If keyword arguments are specified, the dictionary is then updated with those key/value pairs: d.update(red=1, blue=2).

values()

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

dict.values() で得られた２つのビューの等しさを比較すると、必ず False が返ります。 dict.values() どうしを比較したときも同様です:

>>> d = {'a': 1}
>>> d.values() == d.values()
False

d | other

d と other のキーと値を統合した新しい辞書を作成します。 d と other のキーに重複がある場合は、 other の方の値が優先されます。

バージョン 3.9 で追加.

d |= other

辞書 d のキーと値を other で更新します。 other は マッピング か、またはキーと値のペアの イテラブル です。 d と other のキーに重複がある場合は、 other の方の値が優先されます。

バージョン 3.9 で追加.

複数の辞書は、(順序に関係なく) 同じ (key, value) の対を持つ場合に、そしてその場合にのみ等しくなります。順序比較 ('<', '<=', '>=', '>') は TypeError を送出します。

辞書は挿入順序を保存するようになりました。 キーの更新は順序には影響が無いことに注意してください。 いったん削除されてから再度追加されたキーは末尾に挿入されます。:

>>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
>>> d
{'one': 1, 'two': 2, 'three': 3, 'four': 4}
>>> list(d)
['one', 'two', 'three', 'four']
>>> list(d.values())
[1, 2, 3, 4]
>>> d["one"] = 42
>>> d
{'one': 42, 'two': 2, 'three': 3, 'four': 4}
>>> del d["two"]
>>> d["two"] = None
>>> d
{'one': 42, 'three': 3, 'four': 4, 'two': None}

バージョン 3.7 で変更: 辞書の順序が挿入順序であることが保証されるようになりました。この振る舞いは CPython 3.6 の実装詳細でした。

辞書と辞書のビューは reversed() で順序を逆にすることができます:

>>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
>>> d
{'one': 1, 'two': 2, 'three': 3, 'four': 4}
>>> list(reversed(d))
['four', 'three', 'two', 'one']
>>> list(reversed(d.values()))
[4, 3, 2, 1]
>>> list(reversed(d.items()))
[('four', 4), ('three', 3), ('two', 2), ('one', 1)]

バージョン 3.8 で変更: 辞書がリバース可能になりました。

参考

dict の読み出し専用ビューを作るために types.MappingProxyType を使うことができます。

辞書ビューオブジェクト

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

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

len(dictview)

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

iter(dictview)

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

キーと値は挿入順序で反復されます。 これにより、 (value, key) の対の列を pairs = zip(d.values(), d.keys()) のように zip() で作成できます。 同じリストを作成する他の方法は、 pairs = [(v, k) for (k, v) in d.items()] です。

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

バージョン 3.7 で変更: 辞書の順序が挿入順序であると保証されるようになりました。

x in dictview

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

reversed(dictview)

辞書のキーもしくは値、項目の順序を逆にしたイテレーターを返します。 戻り値のビューは、挿入された順とは逆の順でイテレートします。

バージョン 3.8 で変更: 辞書のビューがリバース可能になりました。

dictview.mapping

ビューの参照先の辞書をラップする types.MappingProxyType オブジェクト を返します。

バージョン 3.10 で追加.

Keys views are set-like since their entries are unique and hashable. If all values are hashable, so that (key, value) pairs are unique and hashable, then the items view is also set-like. (Values views are not treated as set-like since the entries are generally not unique.) For set-like views, all of the operations defined for the abstract base class collections.abc.Set are available (for example, ==, <, or ^).

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

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

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

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

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

>>> # set operations
>>> keys & {'eggs', 'bacon', 'salad'}
{'bacon'}
>>> keys ^ {'sausage', 'juice'} == {'juice', 'sausage', 'bacon', 'spam'}
True
>>> keys | ['juice', 'juice', 'juice'] == {'bacon', 'spam', 'juice'}
True

>>> # get back a read-only proxy for the original dictionary
>>> values.mapping
mappingproxy({'bacon': 1, 'spam': 500})
>>> values.mapping['spam']
500

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

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

contextmanager.__enter__()

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

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

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

contextmanager.__exit__(exc_type, exc_val, exc_tb)

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

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

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

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

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

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

型アノテーション型 --- ジェネリックエイリアス 、 ユニオン

型アノテーション の中心となる組み込みの型は ジェネリックエイリアス と ユニオン です。

ジェネリックエイリアス型

GenericAlias オブジェクトは一般的に、クラスに 添字表記 をすることで作られます。 list や dict のような コンテナ系のクラス に対して使われることがほとんどです。 例えば、 list[int] は list クラスに int という引数を与えた添字表記をすることで作られる GenericAlias オブジェクトです。 GenericAlias オブジェクトは主に 型アノテーション の用途で使われます。

注釈

一般に、クラスへの添字表記は、そのクラスが特殊メソッド __class_getitem__() を実装しているときに限り可能です。

GenericAlias オブジェクトは パラメータ付きジェネリック型 を実装したジェネリック型 (generic type) の代用として振る舞います。

コンテナクラスに対してクラスの 添字表記 に与えられた単一または複数の引数は、そのオブジェクトが包含する要素の型をあらわします。たとえば set[bytes] という表記は、全ての要素が bytes であるような set をあらわす型アノテーションとして使うことができます。

__class_getitem__() メソッドを定義しているけれどもコンテナでないクラスに対しては、クラスの添字表記に与えられた単一または複数の引数は、しばしばオブジェクトに定義された単一または複数のメソッドの戻り値の型をあらわします。たとえば、 正規表現操作 は str と bytes の両方のデータ型に対して使うことができます:

• x = re.search('foo', 'foo') とした場合、 x は re.Match オブジェクトとなり、 x.group(0) と x[0] の戻り値はどちらも str となります。このようなオブジェクトは、 GenericAlias を使った型アノテーション re.Match[str] で表現することができます。

• y = re.search(b'bar', b'bar') (ここで b は bytes 型をあらわします) とした場合、y もまた re.Match のインスタンスとなりますが、 y.group(0) と y[0] の戻り値はどちらも bytes 型になります。型アノテーションでは、このような re.Match オブジェクトは re.Match[bytes] と表現することになるでしょう。

GenericAlias オブジェクトは types.GenericAlias クラスのインスタンスです。このクラスは直接 GenericAlias オブジェクトを生成するのに使うこともできます。

T[X, Y, ...]

型 "X", "Y", またはさらに多くの引数でパラメータ化される型 T を表現する GenericAlias を生成します。引数の数は T の使われ方によって決まります。たとえば、 float 型の要素を含む list を引数にとる関数の型アノテーションは次のようになります:

def average(values: list[float]) -> float:
    return sum(values) / len(values)

もうひとつの例として mapping オブジェクトの場合を示します。ここではキーと値の2つの型をパラメータとするジェネリック型である dict を使っています。この例では、関数はキーが str 型、値が int 型であるような dict を引数にとります:

def send_post_request(url: str, body: dict[str, int]) -> None:
    ...

組み込み関数 isinstance() と issubclass() は第二引数として GenericAlias 型を指定することはできません:

>>> isinstance([1, 2], list[str])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: isinstance() argument 2 cannot be a parameterized generic

Python 実行時には 型アノテーション は強制されません。この性質はジェネリック型とその型パラメータにもおよびます。 GenericAlias からコンテナオブジェクトを生成した場合、コンテナ内の要素は型のチェックを受けません。たとえば、以下のコードは推奨されませんが、エラーになることなく実行できます:

>>> t = list[str]
>>> t([1, 2, 3])
[1, 2, 3]

しかも、パラメータ付きジェネリック型は、オブジェクト生成時にパラメータの型情報を削除します:

>>> t = list[str]
>>> type(t)
<class 'types.GenericAlias'>

>>> l = t()
>>> type(l)
<class 'list'>

repr() や str() のジェネリック型に対する呼び出しは、パラメータ型を表示します:

>>> repr(list[int])
'list[int]'

>>> str(list[int])
'list[int]'

ジェネリックコンテナ型の __getitem__() メソッドは、 dict[str][str] のようなミスを許さないように、例外を送出します:

>>> dict[str][str]
Traceback (most recent call last):
  ...
TypeError: dict[str] is not a generic class

一方で、同様の式は 型変数 が使われた場合は有効です。添字の数は``GenericAlias`` オブジェクトの __args__ 属性における型変数の数と同じでなければなりません:

>>> from typing import TypeVar
>>> Y = TypeVar('Y')
>>> dict[str, Y][int]
dict[str, int]

標準ジェネリッククラス

以下の標準ライブラリクラスは、パラメータ付きジェネリック型をサポートします。このリストは完全に網羅されていない可能性があります。

• tuple

• list

• dict

• set

• frozenset

• type

• collections.deque

• collections.defaultdict

• collections.OrderedDict

• collections.Counter

• collections.ChainMap

• ’’collections.abc.Awaitable

• collections.abc.Coroutine

• collections.abc.AsyncIterable

• collections.abc.AsyncIterator

• collections.abc.AsyncGenerator

• collections.abc.Iterable

• collections.abc.Iterator

• collections.abc.Generator

• collections.abc.Reversible

• collections.abc.Container

• collections.abc.Collection

• collections.abc.Callable

• collections.abc.Set

• collections.abc.MutableSet

• collections.abc.Mapping

• collections.abc.MutableMapping

• collections.abc.Sequence

• collections.abc.MutableSequence

• collections.abc.ByteString

• collections.abc.MappingView

• collections.abc.KeysView

• collections.abc.ItemsView

• collections.abc.ValuesView

• contextlib.AbstractContextManager

• contextlib.AbstractAsyncContextManager

• dataclasses.Field

• functools.cached_property

• functools.partialmethod

• os.PathLike

• queue.LifoQueue

• queue.Queue

• queue.PriorityQueue

• queue.SimpleQueue

• re.Pattern

• re.Match

• shelve.BsdDbShelf

• shelve.DbfilenameShelf

• shelve.Shelf

• types.MappingProxyType

• weakref.WeakKeyDictionary

• weakref.WeakMethod

• weakref.WeakSet

• weakref.WeakValueDictionary

GenericAlias オブジェクトの特別な属性

全てのパラメータ付きジェネリック型は、下記に示す読み出し専用の属性を実装しています。

genericalias.__origin__

この属性は、対応するパラメータ付きでないジェネリッククラスを指します:

>>> list[int].__origin__
<class 'list'>

genericalias.__args__

この属性は、ジェネリッククラスの元の __class_getitem__() に渡された tuple です (長さが1の場合もあります):

>>> dict[str, list[int]].__args__
(<class 'str'>, list[int])

genericalias.__parameters__

この属性は、 __args__ にある固有の型変数のタプルで、必要に応じて遅延計算されます (空の可能性もあります):

>>> from typing import TypeVar

>>> T = TypeVar('T')
>>> list[T].__parameters__
(~T,)

注釈

typing.ParamSpec パラメータを含む GenericAlias オブジェクトは、代入後に正しい __parameters__ を持たない可能性があります。これは typing.ParamSpec が主に静的な型チェックを目的としているためです。

genericalias.__unpacked__

これは、型エイリアスが * 演算子を使って取り出された場合に真となる真偽値です (TypeVarTuple を参照してください)。

バージョン 3.11 で追加.

参考

PEP 484 - 型ヒント

型アノテーションのための Python のフレームワークへの導入です。

PEP 585 - 標準コレクション型の型ヒントにおける総称型 (generics) の使用

特殊なクラスメソッド __class_getitem__() を実装している場合に、標準ライブラリのクラスに対してネイティブにパラメータ表記を可能にする機能への導入です。

ジェネリクス, ユーザー定義のジェネリック型, および typing.Generic

実行時にパラメータ設定が可能であり、かつ静的な型チェッカーが理解できるジェネリッククラスを実装する方法のドキュメントです。

バージョン 3.9 で追加.

Union 型

Unionオブジェクトは、複数の type objects を | (bit演算のor)演算した値を保持します。この型は主に type annotations に使用します。Union型の式は typing.Union と比べて型ヒントの構文がわかりやすくなります。

X | Y | ...

X と Y などの型を保持するUnionオブジェクトを定義すします。X | Y はXとYのいずれかを意味します。これは typing.Union[X, Y] と等価です。たとえば、以下の関数は引数として int 型または float 型を想定しています。:

def square(number: int | float) -> int | float:
    return number ** 2

注釈

| のオペランドは、実行時に1つ以上の前方参照をメンバーとして含むようなユニオンを定義するために使うことはできません。たとえば、 "Foo" がまだ定義されていないクラスへの参照である場合、 int | "Foo" は実行時に失敗します。前方参照を含むユニオンは、 "int | Foo" のように、ユニオン全体を文字列としてあらわしてください。

union_object == other

Unionオブジェクトは他のUnionオブジェクトとの等価性をテストできます。以下は詳細です:

• ユニオン型のユニオン型は平滑化されます:

  (int | str) | float == int | str | float
  

• 余分な型は削除されます:

  int | str | int == int | str
  

• ユニオン型を比較すると順序は無視されます:

  int | str == str | int
  

• typing.Union と互換性があります:

  int | str == typing.Union[int, str]
  

• Optional型は None とのUnion型で記述できます:

  str | None == typing.Optional[str]
  

isinstance(obj, union_object)

issubclass(obj, union_object)

isinstance() と issubclass() の呼び出しはどちらもUnionオブジェクトをサポートしています。

>>> isinstance("", int | str)
True

しかし、Unionオブジェクトの中の parameterized generics はチェックできません:

>>> isinstance(1, int | list[int])  # short-circuit evaluation
True
>>> isinstance([1], int | list[int])
Traceback (most recent call last):
  ...
TypeError: isinstance() argument 2 cannot be a parameterized generic

ユーザー定義の Union オブジェクトは types.UnionType からアクセスすることができ、 isinstance() によるチェックにも使うことができます。型からオブジェクトをインスタンスかすることができません:

>>> import types
>>> isinstance(int | str, types.UnionType)
True
>>> types.UnionType()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: cannot create 'types.UnionType' instances

注釈

X | Y 構文をサポートするために、型オブジェクトに __or__() メソッドが追加されました。メタクラスで __or__() を実装するとUnionをオーバーライドする場合があります:

>>> class M(type):
...     def __or__(self, other):
...         return "Hello"
...
>>> class C(metaclass=M):
...     pass
...
>>> C | int
'Hello'
>>> int | C
int | C

参考

PEP 604 -- X | Y 構文とUnion型を提案しているPEP

バージョン 3.10 で追加.

その他の組み込み型

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

モジュール

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

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

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

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

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

関数

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

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

詳細は、 関数定義 を参照してください。

メソッド

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

インスタンスを通してメソッド (クラスの名前空間内で定義された関数) にアクセスすると、特殊なオブジェクトが得られます。それは束縛メソッド (bound method) オブジェクトで、インスタンスメソッド (instance method) とも呼ばれます。呼び出された時、引数リストに self 引数が追加されます。束縛メソッドには 2 つの特殊読み出し専用属性があります。 m.__self__ はそのメソッドが操作するオブジェクトで、m.__func__ はそのメソッドを実装している関数です。 m(arg-1, arg-2, ..., arg-n) の呼び出しは、 m.__func__(m.__self__, arg-1, arg-2, ..., arg-n) の呼び出しと完全に等価です。

function objects と同様に、メソッドオブジェクトは任意の属性の取得をサポートしています。しかし、メソッド属性は実際には下層の関数オブジェクト (method.__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: 'method' object has no attribute 'whoami'
>>> c.method.__func__.whoami = 'my name is method'
>>> c.method.whoami
'my name is method'

詳細は インスタンスメソッド を参照してください。

コードオブジェクト

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

__code__ へのアクセスは object.__getattr__ に obj と "__code__" を渡して行いますが、 監査イベント を送出します。

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

詳細は、 標準型の階層 を参照してください。

型オブジェクト

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

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

ヌルオブジェクト

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

None と書き表されます。

Ellipsis オブジェクト

このオブジェクトは一般にスライシングによって使われます (スライス表記 (slicing) を参照してください)。特殊な演算は何もサポートしていません。Ellipsis オブジェクトは一つだけで、その名前は Ellipsis (組み込み名) です。type(Ellipsis)() は単一の Ellipsis を作成します。

Ellipsis または ... と書き表されます。

NotImplemented オブジェクト

このオブジェクトは、対応していない型に対して比較演算や二項演算が求められたとき、それらの演算から返されます。詳細は 比較 を参照してください。 NotImplemented オブジェクトは一つだけです。 type(NotImplemented)() はこの単一のインスタンスを作成します。

NotImplemented と書き表されます。

Boolean Values

Boolean values are the two constant objects False and True. They are used to represent truth values (although other values can also be considered false or true). In numeric contexts (for example when used as the argument to an arithmetic operator), they behave like the integers 0 and 1, respectively. The built-in function bool() can be used to convert any value to a Boolean, if the value can be interpreted as a truth value (see section 真理値判定 above).

They are written as False and True, respectively.

内部オブジェクト

この情報は 標準型の階層 を参照してください。stack frame objects、traceback objects、スライスオブジェクトについて記述されています。

特殊属性

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

object.__dict__

A dictionary or other mapping object used to store an object's (writable) attributes.

instance.__class__

The class to which a class instance belongs.

class.__bases__

The tuple of base classes of a class object.

definition.__name__

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

definition.__qualname__

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

バージョン 3.3 で追加.

class.__mro__

This attribute is a tuple of classes that are considered when looking for base classes during method resolution.

class.mro()

This method can be overridden by a metaclass to customize the method resolution order for its instances. It is called at class instantiation, and its result is stored in __mro__.

class.__subclasses__()

Each class keeps a list of weak references to its immediate subclasses. This method returns a list of all those references still alive. The list is in definition order. Example:

>>> int.__subclasses__()
[<class 'bool'>, <enum 'IntEnum'>, <flag 'IntFlag'>, <class 're._constants._NamedIntConstant'>]

整数と文字列の変換での長さ制限

CPythonはDoS(サービス妨害攻撃)を軽減するために int と str の間の変換に全体的な制限を設けました。この制限は10進数や2のべき乗以外の基数に のみ 適用されます。16進数、8進数と2進数は制限がありません。上限値は設定できます。

CPython の int 型は、任意の長さの数をバイナリ形式で保存したものです (一般に "bignum" または多倍長整数として知られています)。基数が2のべき乗でない限り、線形の時間で文字列をバイナリ整数に、あるいはバイナリ整数を文字列に変換できるアルゴリズムは存在しません。10進数に対するアルゴリズムでは、最もよく知られているものでさえ、2次に近い (sub-quadratic) 複雑さになります。高速な CPU でも、 int('1' * 500_000) のような大きな数の変換は1秒以上かかる可能性があります。

Limiting conversion size offers a practical way to avoid CVE-2020-10735.

制限は、非線形な変換アルゴリズムが必要とされる場合に、入力または出力文字列の桁数に対して適用されます。アンダースコアや正負の符号はカウントされません。

演算の結果が制限を超えると、ValueError が送出されます:

>>> import sys
>>> sys.set_int_max_str_digits(4300)  # Illustrative, this is the default.
>>> _ = int('2' * 5432)
Traceback (most recent call last):
...
ValueError: Exceeds the limit (4300 digits) for integer string conversion: value has 5432 digits; use sys.set_int_max_str_digits() to increase the limit
>>> i = int('2' * 4300)
>>> len(str(i))
4300
>>> i_squared = i*i
>>> len(str(i_squared))
Traceback (most recent call last):
...
ValueError: Exceeds the limit (4300 digits) for integer string conversion; use sys.set_int_max_str_digits() to increase the limit
>>> len(hex(i_squared))
7144
>>> assert int(hex(i_squared), base=16) == i*i  # Hexadecimal is unlimited.

デフォルトの上限値は4,300桁で、sys.int_info.default_max_str_digits で定義されています。設定可能な最小の上限値は 640 桁で、 sys.int_info.str_digits_check_threshold で定義されています。

確認:

>>> import sys
>>> assert sys.int_info.default_max_str_digits == 4300, sys.int_info
>>> assert sys.int_info.str_digits_check_threshold == 640, sys.int_info
>>> msg = int('578966293710682886880994035146873798396722250538762761564'
...           '9252925514383915483333812743580549779436104706260696366600'
...           '571186405732').to_bytes(53, 'big')
...

バージョン 3.11 で追加.

影響のあるAPI

制限は int と str または bytes の間での変換で時間がかかる可能性があると適用されます:

• int(string) でデフォルトの基数10。

• int(string, base) で2のべき乗以外のすべての基数。

• str(integer)

• repr(integer)

• 他の10進数での文字列変換。たとえば f"{integer}"、"{}".format(integer) や b"%d" % integer。

制限は、線形アルゴリズムの関数では適用されません。

• int(string, base) で基数が2、4、8、16または32。

• int.from_bytes() と int.to_bytes() 。

• hex(), oct(), bin().

• 書式指定ミニ言語仕様 での16進数、8進数、2進数での表現。

• str から float。

• str から decimal.Decimal。

上限値を設定する

Pythonを起動する前に環境変数またはインタープリタのコマンドラインのフラグで上限値を設定できます。

• PYTHONINTMAXSTRDIGITS、たとえば PYTHONINTMAXSTRDIGITS=640 python3 は上限値を640に設定し、PYTHONINTMAXSTRDIGITS=0 python3 は制限を無効化します。

• -X int_max_str_digits、たとえば python3 -X int_max_str_digits=640

• sys.flags.int_max_str_digits には PYTHONINTMAXSTRDIGITS または -X int_max_str_digits の値が設定されます。環境変数と -X オプションの両方が指定された場合は -X オプションが優先されます。 -1 という値はどちらも未設定であることを表し、その場合は sys.int_info.default_max_str_digits の値が初期化時に使用されます。

コードでは、以下の sys APIを使用して現在の上限値を調べ、新しい値を設定できます。

• sys.get_int_max_str_digits() と sys.set_int_max_str_digits() はインタープリタ全体での上限値を取得、設定できます。サブインタープリタはそれぞれの上限値を持ちます。

デフォルト値と最小値に関する情報は sys.int_info で参照できます:

• sys.int_info.default_max_str_digits はコンパイル時のデフォルト上限値です。

• sys.int_info.str_digits_check_threshold は上限値として指定できる最低の値です(0の場合は無効になります)。

バージョン 3.11 で追加.

注意

小さな上限値を設定することで、問題が起きる 可能性があります 。まれではありますが、ソースコード内で閾値を超える定数が10進数の整数として存在するコードが存在します。値に制限をつけることの帰結は、10進数の整数リテラルで制限を超える長さを持つ定数を含むコードのパース時、すなわち通常は起動時、モジュールのインポート時、またはインストール時など、そのコードのための .pyc ファイルが作られるまでのどこかの時点でのエラーです。大きな定数を含むソースコードに対する回避策は、その定数を、 0x を使って値の制限を持たない16進数の値に変換することです。

小さな上限値を使う場合、アプリケーションを徹底的にテストしてください。環境変数やフラグを使って、制限が起動時や、さらにはインストールの段階で Python が .py ファイルを事前にコンパイルして .pyc ファイルを作成する際にも適用されるようにした状態で、確実にテストが実行されるようにしてください。

推奨設定

The default sys.int_info.default_max_str_digits is expected to be reasonable for most applications. If your application requires a different limit, set it from your main entry point using Python version agnostic code as these APIs were added in security patch releases in versions before 3.11.

以下はプログラム例です:

>>> import sys
>>> if hasattr(sys, "set_int_max_str_digits"):
...     upper_bound = 68000
...     lower_bound = 4004
...     current_limit = sys.get_int_max_str_digits()
...     if current_limit == 0 or current_limit > upper_bound:
...         sys.set_int_max_str_digits(upper_bound)
...     elif current_limit < lower_bound:
...         sys.set_int_max_str_digits(lower_bound)

完全に無効にするには、0 に設定します。

脚注

[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] (1,2)

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