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

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

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

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

注釈:

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

次と等価です:

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

Added in version 3.1.

int.bit_count()¶

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

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

次と等価です:

defbit_count(self):returnbin(self).count("1")

Added in version 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 例外を引き起こします。

次と等価です:

defto_bytes(n,length=1,byteorder='big',signed=False):ifbyteorder=='little':order=range(length)elifbyteorder=='big':order=reversed(range(length))else:raiseValueError("byteorder must be either 'little' or 'big'")returnbytes((n>>i*8)&0xffforiinorder)

Added in version 3.2.

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

classmethodint.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 の補数を使うかどうかを決定します。

次と等価です:

deffrom_bytes(bytes,byteorder='big',signed=False):ifbyteorder=='little':little_ordered=list(bytes)elifbyteorder=='big':little_ordered=list(reversed(bytes))else:raiseValueError("byteorder must be either 'little' or 'big'")n=sum(b<<i*8fori,binenumerate(little_ordered))ifsignedandlittle_orderedand(little_ordered[-1]&0x80):n-=1<<8*len(little_ordered)returnn

Added in version 3.2.

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

int.as_integer_ratio()¶

比が元の数と等しくなるような整数のペアを返します。戻り値の分母に相当する数は正の整数です。元の数が整数の場合の比は、常にその整数が分子であり、分母は1 です。

Added in version 3.8.

int.is_integer()¶

常にTrue を返します。float.is_integer() に対するダックタイピングの互換性のために存在しています。

Added in version 3.12.

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

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

float.as_integer_ratio()¶

比が厳密に元の浮動小数点数であるような一対の整数を返します。比は既約分数として与えられ、分母は正の値です。無限大に対してはOverflowError を、非数 (NaN) に対してはValueError を送出します。

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 と指数が続きます。

classmethodfloat.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 で利用できます。

詳細な規則はこうです:

• 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 コードの例を挙げます:

importsys,mathdefhash_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.)whilem%P==n%P==0:m,n=m//P,n//Pifn%P==0:hash_value=sys.hash_info.infelse:# 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)%Pifm<0:hash_value=-hash_valueifhash_value==-1:hash_value=-2returnhash_valuedefhash_float(x):"""Compute the hash of a float x."""ifmath.isnan(x):returnobject.__hash__(x)elifmath.isinf(x):returnsys.hash_info.infifx>0else-sys.hash_info.infelse:returnhash_fraction(*x.as_integer_ratio())defhash_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.widthM=2**(sys.hash_info.width-1)hash_value=(hash_value&(M-1))-(hash_value&M)ifhash_value==-1:hash_value=-2returnhash_value

ジェネレータ型¶

Python'sgenerators provide a convenient way to implement the iteratorprotocol. If a container object's__iter__() method is implemented as agenerator, it will automatically return an iterator object (technically, agenerator object) supplying the__iter__() and__next__()methods.More information about generators can be found inthe documentation forthe yield expression.

共通のシーケンス演算¶

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

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

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

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

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

注釈:

1. in およびnotin 演算は、一般に単純な包含判定にのみ使われますが、(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=[[]foriinrange(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) を使うのと等価ですが、データをコピーしなくて済むし、返されるのはスライスの最初ではなくシーケンスの最初からの相対インデクスです。

9. AnIndexError is raised ifi is outside the sequence range.

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

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

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

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

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

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

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

注釈:

1. k が1 と等しくない場合、t はそれが入れ替えるスライスと同じ長さでなければなりません。

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

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

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

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

   Added in version 3.3:clear() およびcopy() メソッド。

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

リスト型 (list)¶

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

classlist([iterable])¶

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

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

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

• リスト内包表記を使う:[xforxiniterable]

• 型コンストラクタを使う: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() メソッドは安定していることが保証されています。ソートは、等しい要素の相対順序が変更されないことが保証されていれば、安定しています。これは複数パスのソートを行なう (例えば部署でソートして、それから給与の等級でソートする) のに役立ちます。

ソートの例と簡単なチュートリアルはソートのテクニック を参照して下さい。

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

タプル型 (tuple)¶

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

classtuple([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 ループにおいて特定の回数のループに使われます。

classrange(stop)¶

classrange(start,stop[,step])

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

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

step が負の場合も、ranger の内容は式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)>>>rrange(0, 20, 2)>>>11inrFalse>>>10inrTrue>>>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)。)

文字列メソッド¶

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

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

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

str.capitalize()¶

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

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

str.casefold()¶

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

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

The casefolding algorithm isdescribed in section 3.13 'Default Case Folding' of the Unicode Standard.

Added in version 3.3.

str.center(width[,fillchar])¶

Return centered in a string of lengthwidth. Padding is done using thespecifiedfillchar (default is an ASCII space). The original string isreturned ifwidth is less than or equal tolen(s). For example:

>>>'Python'.center(10)'  Python  '>>>'Python'.center(10,'-')'--Python--'>>>'Python'.center(4)'Python'

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

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

Ifsub is empty, returns the number of empty strings between characterswhich is the length of the string plus one. For example:

>>>'spam, spam, spam'.count('spam')3>>>'spam, spam, spam'.count('spam',5)2>>>'spam, spam, spam'.count('spam',5,10)1>>>'spam, spam, spam'.count('eggs')0>>>'spam, spam, spam'.count('')17

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

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

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

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

For performance reasons, the value oferrors is not checked for validityunless an encoding error actually occurs,Python 開発モード is enabledor adebug build is used.For example:

>>>encoded_str_to_bytes='Python'.encode()>>>type(encoded_str_to_bytes)<class 'bytes'>>>>encoded_str_to_bytesb'Python'

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

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

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

ReturnTrue if the string ends with the specifiedsuffix, otherwise returnFalse.suffix can also be a tuple of suffixes to look for. With optionalstart, test beginning at that position. With optionalend, stop comparingat that position. Usingstart andend is equivalent tostr[start:end].endswith(suffix). For example:

>>>'Python'.endswith('on')True>>>'a tuple of suffixes'.endswith(('at','in'))False>>>'a tuple of suffixes'.endswith(('at','es'))True>>>'Python is amazing'.endswith('is',0,9)True

See alsostartswith() andremovesuffix().

str.expandtabs(tabsize=8)¶

Return a copy of the string where all tab characters are replaced by one ormore spaces, depending on the current column and the given tab size. Tabpositions occur everytabsize characters (default is 8, giving tabpositions at columns 0, 8, 16 and so on). To expand the string, the currentcolumn is set to zero and the string is examined character by character. Ifthe character is a tab (\t), one or more space characters are insertedin the result until the current column is equal to the next tab position.(The tab character itself is not copied.) If the character is a newline(\n) or return (\r), it is copied and the current column is reset tozero. Any other character is copied unchanged and the current column isincremented by one regardless of how the character is represented whenprinted. For example:

>>>'01\t012\t0123\t01234'.expandtabs()'01      012     0123    01234'>>>'01\t012\t0123\t01234'.expandtabs(4)'01  012 0123    01234'>>>print('01\t012\n0123\t01234'.expandtabs(4))01  0120123    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 のサブクラスであるときに便利です:

>>>classDefault(dict):...def__missing__(self,key):...returnkey...>>>'{name} was born in{country}'.format_map(Default(name='Guido'))'Guido was born in country'

Added in version 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()¶

ReturnTrue if all characters in the string are alphabetic and there is at leastone character,False otherwise. Alphabetic characters are those characters definedin the Unicode character database as "Letter", i.e., those with general categoryproperty being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note that this is differentfrom theAlphabetic property defined in the section 4.10 'Letters, Alphabetic, andIdeographic' of the Unicode Standard.

str.isascii()¶

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

Added in version 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 を返します。

keyword.iskeyword() は、文字列s がdef やclass のような予約済みの識別子かどうかを調べるのに使うことができます。

例:

>>>fromkeywordimportiskeyword>>>'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()¶

ReturnTrue if all characters in the string are printable,False if itcontains at least one non-printable character.

Here "printable" means the character is suitable forrepr() to use inits output; "non-printable" means thatrepr() on built-in types willhex-escape the character. It has no bearing on the handling of stringswritten tosys.stdout orsys.stderr.

The printable characters are those which in the Unicode character database(seeunicodedata) have a general category in group Letter, Mark,Number, Punctuation, or Symbol (L, M, N, P, or S); plus the ASCII space 0x20.Nonprintable characters are those in group Separator or Other (Z or C),except the ASCII space.

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 isdescribed in section 3.13 'Default Case Folding' 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!'

staticstr.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'

Added in version 3.9.

str.removesuffix(suffix,/)¶

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

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

Added in version 3.9.

str.replace(old,new,count=-1)¶

文字列中にあらわれる部分文字列old を全てnew に置き換えた、文字列のコピーを返します。count が与えられた場合、先頭からcount で指定された数の部分文字列だけを置き換えます。count の指定がないか、または-1 が与えられた場合、全ての部分文字列が置き換えられます。

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

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 なら、分割の回数に制限はありません (可能なだけ分割されます)。

sep が与えられた場合、連続した区切り文字はまとめられず、空の文字列を区切っていると判断されます(例えば'1,,2'.split(',') は['1','','2'] を返します)。引数sep は複数の文字を1つの区切り文字にもできます (複数の区切り文字で分割するにはre.split() を使用します)。区切り文字を指定して空の文字列を分割すると、[''] を返します。

例えば:

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

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

Ifsep is not specified or isNone andmaxsplit is0, onlyleading runs of consecutive whitespace are considered.

例えば:

>>>"".split(None,0)[]>>>"   ".split(None,0)[]>>>"   foo   ".split(maxsplit=0)['foo   ']

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() 関数は単語をスペースでのみ分割するため、この問題はありません。

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

>>>importre>>>deftitlecase(s):...returnre.sub(r"[A-Za-z]+('[A-Za-z]+)?",...lambdamo: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 isdescribed in section 3.13 'Default Case Folding' of the Unicode Standard.

str.zfill(width)¶

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

例えば:

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

Formatted String Literals (f-strings)¶

Anf-string (formally aformatted string literal) isa string literal that is prefixed withf orF.This type of string literal allows embedding arbitrary Python expressionswithinreplacement fields, which are delimited by curly brackets ({}).These expressions are evaluated at runtime, similarly tostr.format(),and are converted into regularstr objects.For example:

>>>who='nobody'>>>nationality='Spanish'>>>f'{who.title()} expects the{nationality} Inquisition!''Nobody expects the Spanish Inquisition!'

It is also possible to use a multi line f-string:

>>>f'''This is a string...on two lines''''This is a string\non two lines'

A single opening curly bracket,'{', marks areplacement field thatcan contain any Python expression:

>>>nationality='Spanish'>>>f'The{nationality} Inquisition!''The Spanish Inquisition!'

To include a literal{ or}, use a double bracket:

>>>x=42>>>f'{{x}} is{x}''{x} is 42'

Functions can also be used, andformat specifiers:

>>>frommathimportsqrt>>>f'√2\N{ALMOST EQUAL TO}{sqrt(2):.5f}''√2 ≈ 1.41421'

Any non-string expression is converted usingstr(), by default:

>>>fromfractionsimportFraction>>>f'{Fraction(1,3)}''1/3'

To use an explicit conversion, use the! (exclamation mark) operator,followed by any of the valid formats, which are:

例えば:

>>>fromfractionsimportFraction>>>f'{Fraction(1,3)!s}''1/3'>>>f'{Fraction(1,3)!r}''Fraction(1, 3)'>>>question='¿Dónde está el Presidente?'>>>print(f'{question!a}')'\xbfD\xf3nde est\xe1 el Presidente?'

While debugging it may be helpful to see both the expression and its value,by using the equals sign (=) after the expression.This preserves spaces within the brackets, and can be used with a converter.By default, the debugging operator uses therepr() (!r) conversion.For example:

>>>fromfractionsimportFraction>>>calculation=Fraction(1,3)>>>f'{calculation=}''calculation=Fraction(1, 3)'>>>f'{calculation= }''calculation = Fraction(1, 3)'>>>f'{calculation= !s}''calculation = 1/3'

Once the output has been evaluated, it can be formatted using aformat specifier following a colon (':').After the expression has been evaluated, and possibly converted to a string,the__format__() method of the result is called with the format specifier,or the empty string if no format specifier is given.The formatted result is then used as the final value for the replacement field.For example:

>>>fromfractionsimportFraction>>>f'{Fraction(1,7):.6f}''0.142857'>>>f'{Fraction(1,7):_^+10}''___+1/7___'

printf 形式の文字列書式化¶

文字列オブジェクトには独特の組み込み演算子:% 演算子 (モジュロ) があります。これは 文字列の書式化 あるいは補間 演算子としても知られています。format%values (format は文字列とします) が与えられると、format の中の% による変換の指定は0こ以上のvalues の要素で置き換えられます。この動作は C 言語におけるsprintf() 関数の利用方法に似ています。使用例:

>>>print('%s has%d quote types.'%('Python',2))Python has 2 quote types.

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.

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

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

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

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

注釈:

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

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

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

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

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

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

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

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

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

バイトオブジェクト¶

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

classbytes([source[,encoding[,errors]]])¶

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

• シングルクォート:b'stillallowsembedded"double"quotes'

• ダブルクォート:b"stillallowsembedded'single'quotes".

• 3重クォート:b'''3singlequotes''',b"""3doublequotes"""

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 型にはその形式でデータを読み取るための追加のクラスメソッドがあります。

classmethodfromhex(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'

Added in version 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 オブジェクトの可変なバージョンです。

classbytearray([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 型にはその形式でデータを読み取るための追加のクラスメソッドがあります。

classmethodfromhex(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'

Added in version 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 を自由に混ぜてもエラーを起こすことなく扱うことができます。ただし、操作の結果のオブジェクトはその操作の順序に依存することになります。

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

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

いくつかの bytes と bytearray の操作は 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 のこのメソッドはインプレースでは動作しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

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

Added in version 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'inb'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 オブジェクトとなります。

staticbytes.maketrans(from,to)¶

staticbytearray.maketrans(from,to)¶

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

Added in version 3.1.