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

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

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

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

いくつかの演算は、複数のオブジェクト型でサポートされています。 特に、
ほぼすべてのオブジェクトでは、等価性の比較、真理値の判定、文字列への変
換ができます (文字列への変換には "repr()" 関数や、それとは少し異なる
"str()" 関数を使います)。 "print()" 関数でオブジェクトを出力する際には
、後者の関数が暗黙的に使われます。


真理値判定
==========

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

通常、オブジェクトは真とみなされます。 ただし、そのオブジェクトを渡し
て呼び出したときに "False" を返す "__bool__()" メソッドか、ゼロを返す
"__len__()" メソッドがクラスに定義されている場合は偽とみなされます。
[1] いずれかのメソッドの呼び出しで例外が送出されると、その例外が伝播し
、オブジェクトは真理値を持ちません (例えば "NotImplemented")。 偽とみ
なされる主な組み込みオブジェクトは次のとおりです:

* 偽であると定義されている定数: "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*, そうでなければ  | (1)     |
|               | *y*                               |         |
+---------------+-----------------------------------+---------+
| "x and y"     | *x* が偽なら *x*, そうでなければ  | (2)     |
|               | *y*                               |         |
+---------------+-----------------------------------+---------+
| "not x"       | *x* が偽なら "True", そうでなけれ | (3)     |
|               | ば "False"                        |         |
+---------------+-----------------------------------+---------+

注釈:

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"
================================

数値型には 3 種類あります: *整数* 、 *浮動小数点数* 、 *複素数* です。
さらに、ブール型は整数のサブタイプです。整数には精度の制限がありません
。浮動小数点型はたいていは C の double を使って実装されています; あな
たのプログラムが動作するマシンでの浮動小数点型の精度と内部表現は、
"sys.float_info" から入手可能です。複素数は実部と虚部を持ち、それぞれ
が浮動小数点数です。複素数 *z* から実部および虚部を取り出すには、
"z.real" および "z.imag" を使ってください。 (標準ライブラリには、さら
に分数のための数値型 "fractions.Fraction" や、ユーザによる精度の定義が
可能な浮動小数点数のための "decimal.Decimal" があります。)

数値は、数値リテラルによって、あるいは組み込み関数や演算子の戻り値とし
て生成されます。 (十六進、八進、二進数を含む) 修飾のない整数リテラルは
、整数を生成します。小数点または指数表記を含む数値リテラルは浮動小数点
数を生成します。数値リテラルに "'j'" または "'J'" をつけると純虚数 (実
部がゼロの複素数) を生成し、それに整数や浮動小数点数を加えることにより
実部と虚部を持つ複素数を得ることができます。

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

Python は異なる型を混在させた算術演算を完全にサポートしています。 二項
算術演算子のオペランドが異なる組み込み数値型の場合、「狭い」型のオペラ
ンドがもう一方の型に拡張されます:

* 両方の引数が複素数の場合、変換は行われません。

* それ以外で、一方の引数が複素数または浮動小数点数の場合、もう一方は浮
  動小数点数に変換されます。

* それ以外場合は、両方の引数は整数でなければならず、変換の必要はありま
  せん。

複素数と実数をオペランドとする演算は、通常の数学の式で定義されます。
例えば、次のようになります。

   x + complex(u, v) = complex(x + u, v)
   x * complex(u, v) = complex(x * u, x * v)

異なる型の数値を比較すると、それぞれの数値の正確な値を比較した場合と同
じ結果になります。[2]

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

+-----------------------+-----------------------------------+-----------+----------------------+
| 演算                  | 結果                              | 注釈      | 完全なドキュメント   |
|=======================|===================================|===========|======================|
| "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* の複素数。   | (6)       | "complex()"          |
|                       | *im* の既定値はゼロ。             |           |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "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" プロパティを持つコードポイント) を含みます。

   "Nd" プロパティを持つコードポイントの完全なリストは Unicode 標準 を
   ご覧ください。

全ての "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" モジュールをご覧ください。


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

ビット単位演算は、整数についてのみ意味を持ちます。 その結果は、符号ビ
ットを無限個持つ2の補数表現で演算した場合と同じになるよう計算されます
。

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

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

+--------------+----------------------------------+------------+
| 演算         | 結果                             | 注釈       |
|==============|==================================|============|
| "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. 有限ビット幅の2の補数表現に、少なくとも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)       # 2進表現:  bin(-37) --> '-0b100101'
          s = s.lstrip('-0b') # 先頭のゼロと負符号を除去する
          return len(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

   次と等価です:

      def bit_count(self):
          return bin(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" 例外を引き起こします。

   次と等価です:

      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)

   Added in version 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* か、バイト値を生成するイテラブ
   ルでなければなりません。

   *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

   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" *抽象基底クラス* を実装しています。
浮動小数点型はまた、以下の追加のメソッドを持ちます。

classmethod float.from_number(x)

   数 *x* から生成された浮動小数点数を返すクラスメソッドです。

   引数が整数または浮動小数点数の場合、(Python の浮動小数点数の精度で)
   同じ値の浮動小数点数が返されます。  引数が Python の浮動小数点数の
   範囲外なら、 "OverflowError" が送出されます。

   一般の Python オブジェクト "x" に対して、"float.from_number(x)" は
   "x.__float__()" に委譲します。 "__float__()" が定義されていない場合
   、"__index__()" へフォールバックします。

   Added in version 3.14.

float.as_integer_ratio()

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

float.is_integer()

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

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

16進文字列との相互変換をサポートするメソッドが二つあります。 Python の
浮動小数点数は内部では2進数として格納されるため、浮動小数点数と *10進
文字列* との相互変換では通常、小さな丸め誤差が生じます。 一方、16進文
字列では浮動小数点数を正確に表現したり指定したりできます。 これはデバ
ッグや数値計算に役立つことがあります。

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"
で生成された16進文字列は "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'


複素数に対する追加のメソッド
----------------------------

"complex" 型は、 "numbers.Complex" *抽象基底クラス* を実装しています。
"complex" 型はまた、以下の追加のメソッドを持ちます。

classmethod complex.from_number(x)

   数値を複素数に変換するクラスメソッドです。

   一般的な Python オブジェクト "x" に対して、
   "complex.from_number(x)" は "x.__complex__()" に処理を委譲します。
   "__complex__()" が定義されていない場合は "__float__()" にフォールバ
   ックします。 "__float__()" も定義されていない場合は "__index__()"
   にフォールバックします。

   Added in version 3.14.


数値型のハッシュ化
------------------

数 "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 で利用できます。

現在使われている素数は、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):
       """有理数 m / n のハッシュを計算する。

       m と n は整数で、n は正と仮定する。
       hash(fractions.Fraction(m, n)) と等価。

       """
       P = sys.hash_info.modulus
       # P の共通因子を除く (m と n がすでに互いに素なら不要)。
       while m % P == n % P == 0:
           m, n = m // P, n // P

       if n % P == 0:
           hash_value = sys.hash_info.inf
       else:
           # フェルマーの小定理により pow(n, P-1, P) は1なので、
           # pow(n, P-2, P) は P を法とする n の逆数を与える。
           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):
       """浮動小数点数 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):
       """複素数 z のハッシュを計算する。"""

       hash_value = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag)
       # 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


ブーリアン型 - "bool"
=====================

ブーリアン型は真理値を表現します。 "bool" 型はただ2つの定数インスタン
ス "True" と "False" を持ちます。

組み込み関数 "bool()"  は、もしその値が真理値として解釈可能ならば、任
意の値を真偽値に変換します (上記 真理値判定 節を参照してください)。

論理演算には ブーリアン演算子 "and", "or" および "not" を使ってくださ
い。2つの真偽値に対してビット演算子 "&", "|", "^" を適用した場合は、そ
れぞれ論理演算  "and", "or", "xor" に相当するブール値を返します。しか
しながら、論理演算子 "and", "or" および "!=" を使うほうが "&", "|" や
"^" を使うよりも好ましいです。

バージョン 3.12 で非推奨: ビット反転演算子 "~" の使用は非推奨となり、
Python 3.16 ではエラーが送出されるようになります。

"bool" は "int" のサブクラスです (数値型 int, float, complex を参照し
てください)。多くの数値的なコンテキストにおいて、 "False" と "True" は
それぞれ整数 0 と 1 であるかのように振る舞います。しかし、そのような振
る舞いを信頼することは推奨されません; "int()" を使って明示的に整数値に
変換してください。


反復に関連する型
================

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


イテラブル
----------

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

container.__iter__()

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


イテレータ (iterator)
---------------------

イテレータオブジェクト自体は以下の 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 の *ジェネレータ*、より正確には *ジェネレータ関数* と *ジェネレ
ータイテレータ* を使うと、イテレータプロトコルを簡単に実装できます。

yield 式 を一つ以上含む関数は *ジェネレータ関数* です。 例えば、次のよ
うになります。

   >>> def count_to_three():
   ...     yield 0
   ...     yield 1
   ...     yield 2
   ...     yield 3

ジェネレータ関数は通常の ユーザ定義関数 と同様に振る舞います (例えば、
同じ属性を持ちます)。 ただし、呼び出すと ジェネレータイテレータ を返し
ます。

   >>> count_to_three()
   <generator object count_to_three at 0x7f33a2305000>

ジェネレータイテレータを反復すると、元のジェネレータ関数のコードが実行
され、"yield" された値が順番に生成されます。

   >>> for number in count_to_three():
   ...     print(number)
   0
   1
   2
   3

   >>> list(count_to_three())
   [0, 1, 2, 3]

ジェネレータ関数は、独自のイテラブルオブジェクトの "__iter__()" メソッ
ドを実装する際によく使われます。 例えば、次のようになります。

   >>> class CardDeck:
   ...     def __iter__(self):
   ...         yield 'three of clubs'
   ...         yield 'ace of hearts'

   >>> list(CardDeck())
   ['three of clubs', 'ace of hearts']


ジェネレータイテレータ
~~~~~~~~~~~~~~~~~~~~~~

ジェネレータイテレータは イテレータプロトコル を実装しています。 反復
すると、元のジェネレータ関数の実行が進みます。

generator.__next__()

   ジェネレータ関数の実行を開始するか、現在中断している yield 式 から
   実行を再開します。 "__next__()" メソッドでジェネレータ関数を再開す
   ると、現在の yield 式は常に "None" と評価されます。 その後、次の
   yield 式まで実行が進み、そこでジェネレータは再び中断します。
   "yield" キーワードの後の式の値が "__next__()" の呼び出し元に返され
   ます。 別の値を yield することなくジェネレータが終了すると、
   "__next__()" は "StopIteration" 例外を送出し、反復の完了を知らせま
   す。

   通常、このメソッドは "for" ループや組み込みの "next()" 関数などによ
   って暗黙的に呼び出されます。

ジェネレータイテレータは一般的なイテレータに加えていくつかのメソッドを
持ち、元のジェネレータ関数の実行を制御できます:

generator.send(value)

   ジェネレータ関数に値を「送信」します。 "value" 引数が現在の yield
   式の結果になります。

   それ以外の点では、このメソッドは "__next__()" と同様に動作します。
   元の関数の実行を再開し、次に yield された値を返すか、
   "StopIteration" を送出します。

   ジェネレータを開始するために "send()" を呼び出す場合は、引数として
   "None" を渡さなければなりません。 まだ値を受け取れる yield 式がない
   ためです。

generator.throw(value)
generator.throw(type[, value[, traceback]])

   ジェネレータが現在中断している箇所で例外を送出します。

   それ以外の点では、このメソッドは "__next__()" と同様に動作します。
   元の関数の実行を再開し、次に yield された値を返すか、
   "StopIteration" を送出します。 ジェネレータ関数が渡された例外を捕捉
   しないか、別の例外を送出した場合、その例外は呼び出し元に伝播します
   。

   ジェネレータを開始するために "throw()" を呼び出すと、ジェネレータは
   直ちに終了し (以降の "__next__()" の呼び出しでは "StopIteration" が
   送出されます)、送出された例外は "throw()" の呼び出し元に伝播します
   。

   通常は "raise" キーワードと同様に、例外インスタンスを一つの引数とし
   て渡して呼び出します。

   ただし、後方互換性のため、以前のバージョンの Python の慣例に従った2
   番目のシグネチャもサポートされています。 "type" 引数には例外クラス
   を、"value" には例外インスタンスを指定してください。 "value" を指定
   しない場合は、"type" のコンストラクタを呼び出してインスタンスを取得
   します。 "traceback" を指定した場合は例外に設定されます。 指定しな
   い場合は、"value" に格納されている既存の "__traceback__" 属性がクリ
   アされることがあります。

   バージョン 3.12 で変更: 2番目のシグネチャ (type[, value[,
   traceback]]) は非推奨となり、将来のバージョンの Python で削除される
   可能性があります。

generator.close()

   ジェネレータ関数が現在中断している箇所で "GeneratorExit" 例外を送出
   します ("throw(GeneratorExit)" の呼び出しと等価です)。

   ジェネレータ関数がすでに終了している場合 (例外による終了と正常な
   return のどちらも含みます)、または例外を捕捉せず "GeneratorExit" を
   送出した場合、"close()" は "None" を返します。 ジェネレータが値を
   yield すると、"RuntimeError" が送出されます。 ジェネレータがそれ以
   外の例外を送出した場合、その例外は呼び出し元に伝播します。 クローズ
   時にジェネレータが値を return した場合、"close()" はその値を返しま
   す。

   ジェネレータイテレータが終了する前にガベージコレクションで回収され
   ると、"close()" が自動的に呼び出されます。

   バージョン 3.13 で変更: クローズ時にジェネレータが値を return した
   場合、"close()" はその値を返すようになりました。 以前は "None" を返
   していました。

ジェネレータのメソッド ("__next__()"、"send()"、"throw()"、"close()")
のいずれかを実行中に、これらのメソッドのいずれかを呼び出すと
"ValueError" 例外が送出されます。


非同期ジェネレータイテレータ
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

この節では、非同期ジェネレータ関数の実行を制御する、非同期ジェネレータ
イテレータのメソッドを説明します。

async agen.__anext__()

   実行すると非同期ジェネレータ関数の実行を開始するか、現在中断してい
   る yield 式 から実行を再開する *待ち受け可能オブジェクト* を返しま
   す。 "__anext__()" メソッドで非同期ジェネレータ関数を再開すると、返
   された待ち受け可能オブジェクト内で現在の yield 式は常に "None" と評
   価されます。 この待ち受け可能オブジェクトを実行すると、次の yield
   式まで実行が進みます。 "yield" キーワードの後の式の値は、完了するコ
   ルーチンが送出する "StopIteration" 例外の値になります。 別の値を
   yield することなく非同期ジェネレータが終了すると、待ち受け可能オブ
   ジェクトは代わりに "StopAsyncIteration" 例外を送出し、非同期反復の
   完了を知らせます。

   通常、このメソッドは "async for" ループや組み込みの "anext()" 関数
   によって暗黙的に呼び出されます。

非同期ジェネレータイテレータは一般的な非同期イテレータに加えていくつか
のメソッドを持ち、元のジェネレータ関数の実行を制御できます:

async agen.asend(value)

   実行すると元の非同期ジェネレータ関数に値を「送信」する待ち受け可能
   オブジェクトを返します。 "value" 引数が現在の yield 式の結果になり
   ます。

   それ以外の点では、このメソッドは "__anext__()" と同様に動作します。
   返された待ち受け可能オブジェクトを実行すると、元の関数の実行が再開
   され、次に yield された値を "StopIteration" 例外の値として返すか、
   "StopAsyncIteration" を送出します。

   非同期ジェネレータを開始するために "asend()" を呼び出す場合は、引数
   として "None" を渡さなければなりません。 まだ値を受け取れる yield
   式がないためです。

async agen.athrow(value)
async agen.athrow(type[, value[, traceback]])

   実行すると元の非同期ジェネレータ関数が現在中断している箇所で例外を
   送出する待ち受け可能オブジェクトを返します。

   それ以外の点では、このメソッドは "__anext__()" と同様に動作します。
   返された待ち受け可能オブジェクトを実行すると、元の関数の実行が例外
   を送出した状態で再開され、次に yield された値を "StopIteration" 例
   外の値として返すか、"StopAsyncIteration" を送出します。 元の関数が
   渡された例外を捕捉しないか、別の例外を送出した場合、待ち受け可能オ
   ブジェクトの実行時に、その例外は待ち受け可能オブジェクトの呼び出し
   元に伝播します。

   ジェネレータを開始するために "athrow()" を呼び出すと、待ち受け可能
   オブジェクトの実行時にジェネレータは終了し (以降の "__anext__()" の
   結果を実行すると "StopAsyncIteration" が送出されます)、送出された例
   外は待ち受け可能オブジェクトの呼び出し元に伝播します。

   通常は "raise" キーワードと同様に、例外インスタンスを一つの引数とし
   て渡して呼び出します。

   ただし、後方互換性のため、2番目のシグネチャもサポートされています。
   "generator.throw()" と同様に、三つの引数から例外インスタンスを作成
   します。

   バージョン 3.12 で変更: 2番目のシグネチャ (type[, value[,
   traceback]]) は非推奨となり、将来のバージョンの Python で削除される
   可能性があります。

async agen.aclose()

   実行すると元の非同期ジェネレータ関数が現在中断している箇所で
   "GeneratorExit" を送出する待ち受け可能オブジェクトを返します
   ("athrow(GeneratorExit)" の呼び出しと等価です)。

   If the asynchronous generator function then exits gracefully, is
   already closed, or raises "GeneratorExit" (by not catching the
   exception), then the returned awaitable will raise a
   "StopIteration" exception. Any further awaitables returned by
   subsequent calls to the asynchronous generator will raise a
   "StopAsyncIteration" exception.

   非同期ジェネレータが値を yield すると、待ち受け可能オブジェクトは
   "RuntimeError" を送出します。 非同期ジェネレータがそれ以外の例外を
   送出した場合、その例外は待ち受け可能オブジェクトの呼び出し元に伝播
   します。

   非同期ジェネレータが例外または正常終了によってすでに終了している場
   合、以降の "aclose()" の呼び出しは、何もしない待ち受け可能オブジェ
   クトを返します。


シーケンス型 --- "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* と等しけれ  | (1)        |
|                            | ば "True" , そうでなければ       |            |
|                            | "False"                          |            |
+----------------------------+----------------------------------+------------+
| "x not in s"               | *s* のある要素が *x* と等しけれ  | (1)        |
|                            | ば "False", そうでなければ       |            |
|                            | "True"                           |            |
+----------------------------+----------------------------------+------------+
| "s + t"                    | *s* と *t* の結合                | (6)(7)     |
+----------------------------+----------------------------------+------------+
| "s * n" または "n * s"     | *s* 自身を *n* 回足すのと同じ    | (2)(7)     |
+----------------------------+----------------------------------+------------+
| "s[i]"                     | *s* の 0 から数えて *i* 番目の要 | (3)(8)     |
|                            | 素                               |            |
+----------------------------+----------------------------------+------------+
| "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* の最大の要素                 |            |
+----------------------------+----------------------------------+------------+

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

ミュータブルなシーケンスに対する前方および逆方向イテレータはインデック
スを使って要素にアクセスします。インデックスは、仮に参照するシーケンス
が変化したとしても前方 (または後方) に進み続けます。イテレータは
"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* が省略された場合や "None" の場合は "0" を使います。

   * *j* が省略された場合や "None" の場合は "len(s)" を使います。

   * *i* または *j* が "-len(s)" 未満の場合は "0" を使います。

   * *i* または *j* が "len(s)" より大きい場合は "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. *i* がシーケンスの範囲外の場合、"IndexError" が送出されます。

-[ シーケンスのメソッド ]-

シーケンス型は以下のようなメソッドをサポートしています:

sequence.count(value, /)

   *sequence* の中に *value* が出現する回数を返します。

sequence.index(value[, start[, stop]])

   *sequence* で最初に *value* が出現する場所のインデックスを返します
   。

   *sequence* に *value* が見つからなければ "ValueError" を送出します
   。

   "start" または "stop" 引数を使うと、シーケンスの "start" から
   "stop" までの部分を効率よく検索できます。 これはおおむね "start +
   sequence[start:stop].index(value)" と等価ですが、データをコピーしま
   せん。

   注意:

     "start" および "stop" 引数の指定をサポートしていないシーケンス型
     もあります。


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

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

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

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


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

以下の表にある演算は、ミュータブルなシーケンス型で定義されています。
独自のシーケンス型でこれらの演算を正しく実装しやすくするために、
"collections.abc.MutableSequence" ABC が提供されています。

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

+--------------------------------+----------------------------------+-----------------------+
| 演算                           | 結果                             | 注釈                  |
|================================|==================================|=======================|
| "s[i] = x"                     | *s* の要素 *i* を *x* と入れ替え |                       |
|                                | ます                             |                       |
+--------------------------------+----------------------------------+-----------------------+
| "del s[i]"                     | *s* の要素 *i* を削除します      |                       |
+--------------------------------+----------------------------------+-----------------------+
| "s[i:j] = t"                   | *s* の *i* から *j* 番目までのス |                       |
|                                | ライスをイテラブル *t* の内容に  |                       |
|                                | 入れ替 えます                    |                       |
+--------------------------------+----------------------------------+-----------------------+
| "del s[i:j]"                   | リストから "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 += t"                       | *s* を *t* の内容で拡張します (  |                       |
|                                | ほとんど "s[len(s):len(s)] = t"  |                       |
|                                | と同じ)                          |                       |
+--------------------------------+----------------------------------+-----------------------+
| "s *= n"                       | *s* をその内容を *n* 回繰り返し  | (2)                   |
|                                | たもので更新                     |                       |
+--------------------------------+----------------------------------+-----------------------+

注釈:

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

2. *n* は整数または "__index__()" を実装したオブジェクトです。 *n* が
   ゼロまたは負の値の場合、シーケンスを空にします。 共通のシーケンス演
   算 の "s * n" の説明と同様に、シーケンスの要素はコピーされず、同じ
   要素が複数回参照されます。

-[ ミュータブルなシーケンスのメソッド ]-

ミュータブルなシーケンス型は以下のようなメソッドをサポートしています:

sequence.append(value, /)

   シーケンスの末尾に "value" を追加します。 これは
   "seq[len(seq):len(seq)] = [value]" と書くことと等価です。

sequence.clear()

   Added in version 3.3.

   *sequence* からすべての要素を削除します。 これは "del sequence[:]"
   と書くことと等価です。

sequence.copy()

   Added in version 3.3.

   *sequence* の浅いコピーを作成します。 これは "sequence[:]" と書くこ
   とと等価です。

   ヒント:

     "copy()" メソッドは "MutableSequence" "ABC" には含まれませんが、
     ほとんどの具体的なミュータブルシーケンス型で提供されています。

sequence.extend(iterable, /)

   *sequence* を "iterable" の内容で拡張します。 これはほとんどの場合
   、"seq[len(seq):len(seq)] = iterable" と書くことと同じです。

sequence.insert(index, value, /)

   *sequence* の指定された "index" に "value" を挿入します。 これは
   "sequence[index:index] = [value]" と書くことと等価です。

sequence.pop(index=-1, /)

   "index" の要素を取得し、*sequence* から削除します。 デフォルトでは
   、*sequence* の最後の要素を削除して返します。

sequence.remove(value, /)

   "sequence[i] == value" を満たす最初の要素を *sequence* から削除しま
   す。

   *sequence* に *value* が見つからなければ "ValueError" を送出します
   。

sequence.reverse()

   *sequence* の要素をインプレースで逆順に並べ替えます。 このメソッド
   は、大きなシーケンスを逆順にするときにもメモリ使用量を抑えます。 副
   作用によって動作することを利用者に意識させるため、"None" を返します
   。


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

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

      リストのソート中にそのリストを変更したり、内容を調べたりしようと
      した場合の動作は未定義です。 Python の C 実装では、ソート中はリ
      ストが空に見えるようにし、 ソート中にリストが変更されたことを検
      出できた場合は "ValueError" を送出します。

参考: "list" オブジェクトのスレッドセーフ性の保証については、list オブジェ
    クトのスレッドセーフ性 を参照してください。


タプル型 (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-タプルを唯一の引数とする関数の呼び出しです。

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

   タプルは内容の型について ジェネリック です。 詳しくは、タプルのアノ
   テーションに関する typing ドキュメント を参照してください。

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


range
-----

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

class range(stop, /)
class range(start, stop, step=1, /)

   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"
が追加。

参考:

  * linspace レシピ は浮動小数点数向けの遅延評価版 range を実装する方
    法を紹介しています。


テキストおよびバイナリシーケンス型のメソッド一覧
================================================

次の表は、テキストおよびバイナリシーケンス型のメソッドを分類ごとにまと
めたものです。

+----------------------------+--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
| カテゴリ                   | "str" メソッド                                                  | "bytes" または "bytearray" メソッド                                         |
|============================|====================|=========|=========|========================|======================|===========|===========|==============================|
| 書式化                     | "str.format()"                                                  |                                                                             |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.format_map()"                                              |                                                                             |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | f-strings                                                       |                                                                             |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | printf 形式の文字列書式化                                       | printf 形式での bytes の書式化                                              |
+----------------------------+--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
| 検索と置換                 | "str.find()"       | "str.rfind()"                              | "bytes.find()"       | "bytes.rfind()"                                      |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.index()"      | "str.rindex()"                             | "bytes.index()"      | "bytes.rindex()"                                     |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.startswith()"                                              | "bytes.startswith()"                                                        |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.endswith()"                                                | "bytes.endswith()"                                                          |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.count()"                                                   | "bytes.count()"                                                             |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.replace()"                                                 | "bytes.replace()"                                                           |
+----------------------------+--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
| 分割と結合                 | "str.split()"                | "str.rsplit()"                   | "bytes.split()"                  | "bytes.rsplit()"                         |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.splitlines()"                                              | "bytes.splitlines()"                                                        |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.partition()"                                               | "bytes.partition()"                                                         |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.rpartition()"                                              | "bytes.rpartition()"                                                        |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.join()"                                                    | "bytes.join()"                                                              |
+----------------------------+--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
| 文字列の分類               | "str.isalpha()"                                                 | "bytes.isalpha()"                                                           |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.isdecimal()"                                               |                                                                             |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.isdigit()"                                                 | "bytes.isdigit()"                                                           |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.isnumeric()"                                               |                                                                             |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.isalnum()"                                                 | "bytes.isalnum()"                                                           |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.isidentifier()"                                            |                                                                             |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.islower()"                                                 | "bytes.islower()"                                                           |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.isupper()"                                                 | "bytes.isupper()"                                                           |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.istitle()"                                                 | "bytes.istitle()"                                                           |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.isspace()"                                                 | "bytes.isspace()"                                                           |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.isprintable()"                                             |                                                                             |
+----------------------------+--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
| 大文字と小文字の操作       | "str.lower()"                                                   | "bytes.lower()"                                                             |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.upper()"                                                   | "bytes.upper()"                                                             |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.casefold()"                                                |                                                                             |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.capitalize()"                                              | "bytes.capitalize()"                                                        |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.title()"                                                   | "bytes.title()"                                                             |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.swapcase()"                                                | "bytes.swapcase()"                                                          |
+----------------------------+--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
| パディングと除去           | "str.ljust()"                | "str.rjust()"                    | "bytes.ljust()"                  | "bytes.rjust()"                          |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.center()"                                                  | "bytes.center()"                                                            |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.expandtabs()"                                              | "bytes.expandtabs()"                                                        |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.strip()"                                                   | "bytes.strip()"                                                             |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.lstrip()"                         | "str.rstrip()"         | "bytes.lstrip()"                             | "bytes.rstrip()"             |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.removeprefix()"                                            | "bytes.removeprefix()"                                                      |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.removesuffix()"                                            | "bytes.removesuffix()"                                                      |
+----------------------------+--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
| 変換とエンコーディング     | "str.translate()"                                               | "bytes.translate()"                                                         |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.maketrans()"                                               | "bytes.maketrans()"                                                         |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            | "str.encode()"                                                  |                                                                             |
|                            +--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+
|                            |                                                                 | "bytes.decode()"                                                            |
+----------------------------+--------------------+---------+---------+------------------------+----------------------+-----------+-----------+------------------------------+


テキストシーケンス型 --- "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(*, encoding='utf-8', errors='strict')
class str(object)
class str(object, encoding, errors='strict')
class str(object, *, errors)

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

   *encoding* も *errors* も与えられない場合、 "str(object)" は "形式
   ばらず"、 表示用にきれいに整えられた *object* の文字列表現である
   "type(object).__str__(object)" を返します。文字列オブジェクトに対し
   ては、文字列そのものです。 *object* が "__str__()" メソッドを持たな
   い場合、 "str()" は代わりに "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""
   に変換されます。 例えば、次のようになります:

      >>> 'straße'.lower()
      'straße'
      >>> 'straße'.casefold()
      'strasse'

   casefold のアルゴリズムは Unicode 標準の3.13.3節「Default Case
   Folding」 に記載されています。

   Added in version 3.3.

str.center(width, fillchar=' ', /)

   長さ "width" の文字列の中央に配置して返します。 パディングには指定
   された "fillchar" (デフォルトは ASCII スペース) を使います。
   "width" が "len(s)" 以下の場合は元の文字列を返します。 例えば、次の
   ようになります。

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

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

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

   If *sub* is empty, returns the number of empty strings between
   characters which 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()" で登録された名前です。詳しくは エラーハン
   ドラ を参照してください。

   パフォーマンス上の理由から、実際にエンコーディングエラーが発生した
   場合、Python 開発モード が有効な場合、または デバッグビルド を使っ
   ている場合にのみ、"errors" の値の妥当性を検査します。 例えば、次の
   ようになります。

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

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

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

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

   Return "True" if the string ends with the specified *suffix*,
   otherwise return "False".  *suffix* can also be a tuple of suffixes
   to look for.  With optional *start*, test beginning at that
   position.  With optional *end*, stop comparing at that position.
   Using *start* and *end* is equivalent to
   "str[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

   "startswith()" と "removesuffix()" も参照してください。

str.expandtabs(tabsize=8)

   すべてのタブ文字を、現在の列と指定されたタブサイズに応じて一つ以上
   のスペースに置き換えた文字列のコピーを返します。 タブ位置は
   "tabsize" 文字ごとにあります (デフォルトは8で、列0、8、16などがタブ
   位置になります)。 文字列を展開する際には、現在の列をゼロに設定し、
   文字列を1文字ずつ調べます。 文字がタブ ("\t") の場合、現在の列が次
   のタブ位置に達するまで、結果に一つ以上のスペース文字を挿入します (
   タブ文字自体はコピーしません)。 文字が改行 ("\n") または復帰 ("\r")
   の場合、その文字をコピーして現在の列をゼロに戻します。 それ以外の文
   字はそのままコピーし、表示したときの表現に関係なく現在の列を一つ進
   めます。 例えば、次のようになります。

      >>> '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  012
      0123    01234

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

   スライス "s[start:end]" 内で部分文字列 "sub" が見つかる、文字列内の
   最小のインデックスを返します。 省略可能な "start" と "end" 引数はス
   ライス表記と同様に解釈されます。 "sub" が見つからない場合は "-1" を
   返します。 例えば、次のようになります。

      >>> 'spam, spam, spam'.find('sp')
      0
      >>> 'spam, spam, spam'.find('sp', 5)
      6

   "rfind()" と "index()" も参照してください。

   注釈:

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

        >>> 'Py' in 'Python'
        True

str.format(*args, **kwargs)

   Perform a string formatting operation.  The string on which this
   method is called can contain literal text or replacement fields
   delimited by braces "{}".  Each replacement field contains either
   the numeric index of a positional argument, or the name of a
   keyword argument.  Returns a copy of the string where each
   replacement field is replaced with the string value of the
   corresponding argument. For example:

      >>> "The sum of 1 + 2 is {0}".format(1+2)
      'The sum of 1 + 2 is 3'
      >>> "The sum of {a} + {b} is {answer}".format(answer=1+2, a=1, b=2)
      'The sum of 1 + 2 is 3'
      >>> "{1} expects the {0} Inquisition!".format("Spanish", "Nobody")
      'Nobody expects the Spanish Inquisition!'

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

   注釈:

     数値 ("int"、"float"、"complex"、"decimal.Decimal" とそのサブクラ
     ス) を "n" 型で書式化する場合 (例: "'{:n}'.format(1234)")、
     "localeconv()" の "decimal_point" または "thousands_sep" フィール
     ドが非 ASCII 文字を含むか1バイトより長く、 かつ "LC_NUMERIC" ロケ
     ールが "LC_CTYPE" ロケールと異なるときは、 それらのフィールドをデ
     コードするために、一時的に "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'

   Added in version 3.2.

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

   "find()" と同様ですが、部分文字列が見つからない場合は "ValueError"
   を送出します。 例えば、次のようになります:

      >>> 'spam, spam, spam'.index('spam')
      0
      >>> 'spam, spam, spam'.index('eggs')
      Traceback (most recent call last):
        File "<python-input-0>", line 1, in <module>
          'spam, spam, spam'.index('eggs')
          ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
      ValueError: substring not found

   "rindex()" も参照してください。

str.isalnum()

   文字列内のすべての文字が字母または数字で、かつ1文字以上ある場合は
   "True" を、それ以外の場合は "False" を返します。 文字 "c" は、
   "c.isalpha()"、"c.isdecimal()"、"c.isdigit()"、"c.isnumeric()" のい
   ずれかが "True" を返す場合に字母または数字とみなされます。 例えば、
   次のようになります:

      >>> 'abc123'.isalnum()
      True
      >>> 'abc123!@#'.isalnum()
      False
      >>> ''.isalnum()
      False
      >>> ' '.isalnum()
      False

str.isalpha()

   文字列内のすべての文字が字母で、かつ1文字以上ある場合は "True" を、
   それ以外の場合は "False" を返します。 字母とは、Unicode 文字データ
   ベースで「Letter」と定義されている文字、すなわち一般カテゴリのプロ
   パティが "Lm"、"Lt"、"Lu"、"Ll"、"Lo" のいずれかである文字です。 こ
   れは Unicode 標準の4.10節「Letters, Alphabetic, and Ideographic」で
   定義されている Alphabetic プロパティ とは異なることに注意してくださ
   い。 例えば、次のようになります:

      >>> 'Letters and spaces'.isalpha()
      False
      >>> 'LettersOnly'.isalpha()
      True
      >>> 'µ'.isalpha()  # 非 ASCII 文字も字母とみなされる場合がある
      True

   Unicode プロパティ を参照してください。

str.isascii()

   文字列が空であるか、文字列内のすべての文字が ASCII 文字である場合は
   "True" を、それ以外の場合は "False" を返します。 ASCII 文字のコード
   ポイントは U+0000-U+007F の範囲です。 例えば、次のようになります:

      >>> 'ASCII characters'.isascii()
      True
      >>> 'µ'.isascii()
      False

   Added in version 3.7.

str.isdecimal()

   文字列内のすべての文字が10進数字で、かつ1文字以上ある場合は "True"
   を、それ以外の場合は "False" を返します。 10進数字とは、U+0660
   (ARABIC-INDIC DIGIT ZERO) のように10進数を構成するために使える文字
   です。 厳密には、Unicode の一般カテゴリが "Nd" である文字を指します
   。 例えば、次のようになります:

      >>> '0123456789'.isdecimal()
      True
      >>> '٠١٢٣٤٥٦٧٨٩'.isdecimal()  # アラビア・インド数字の0から9
      True
      >>> 'alphabetic'.isdecimal()
      False

str.isdigit()

   文字列内のすべての文字が数字で、かつ1文字以上ある場合は "True" を、
   それ以外の場合は "False" を返します。 数字には10進数字と、互換文字
   である上付き数字のように特別な扱いが必要な数字が含まれます。 これに
   は、カローシュティー数字 のように10進数の構成には使えない数字も含ま
   れます。 厳密には、プロパティ値 Numeric_Type=Digit または
   Numeric_Type=Decimal を持つ文字を指します。

   例えば:

      >>> '0123456789'.isdigit()
      True
      >>> '٠١٢٣٤٥٦٧٨٩'.isdigit()  # アラビア・インド数字の0から9
      True
      >>> '⅕'.isdigit()  # 分数の5分の1
      False
      >>> '²'.isdecimal(), '²'.isdigit(),  '²'.isnumeric()
      (False, True, True)

   "isdecimal()" と "isnumeric()" も参照してください。

str.isidentifier()

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

   "keyword.iskeyword()" は、文字列 "s" が "def" や "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" を返します。 数を表す文字には、
   数字や、U+2155 (VULGAR FRACTION ONE FIFTH) のように Unicode の数値
   プロパティを持つすべての文字が含まれます。 厳密には、プロパティ値
   Numeric_Type=Digit、Numeric_Type=Decimal、Numeric_Type=Numeric のい
   ずれかを持つ文字を指します。 例えば、次のようになります:

      >>> '0123456789'.isnumeric()
      True
      >>> '٠١٢٣٤٥٦٧٨٩'.isnumeric()  # アラビア・インド数字の0から9
      True
      >>> '⅕'.isnumeric()  # 分数の5分の1
      True
      >>> '²'.isdecimal(), '²'.isdigit(),  '²'.isnumeric()
      (False, True, True)

   "isdecimal()" と "isdigit()" も参照してください。

str.isprintable()

   文字列内のすべての文字が表示可能な場合は "True" を、表示できない文
   字が一つでも含まれる場合は "False" を返します。

   ここで「表示可能」とは、その文字を "repr()" の出力にそのまま使える
   ことを意味します。 「表示できない」とは、組み込み型に対する
   "repr()" がその文字を16進エスケープで表すことを意味します。
   "sys.stdout" や "sys.stderr" に書き出す文字列の扱いには関係ありませ
   ん。

   表示可能な文字は、Unicode 文字データベース ("unicodedata" を参照)
   で一般カテゴリが Letter、Mark、Number、Punctuation、Symbol のグルー
   プ (L、M、N、P、S) に属する文字と、ASCII スペース 0x20 です。 表示
   できない文字は、ASCII スペースを除く、Separator または Other のグル
   ープ (Z、C) に属する文字です。

   例えば:

      >>> ''.isprintable(), ' '.isprintable()
      (True, True)
      >>> '\t'.isprintable(), '\n'.isprintable()
      (False, False)

   "isspace()" も参照してください。

str.isspace()

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

   例えば:

      >>> ''.isspace()
      False
      >>> ' '.isspace()
      True
      >>> '\t\n'.isspace() # タブと改行
      True
      >>> '\u3000'.isspace() # 全角スペース
      True

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

   "isprintable()" も参照してください。

str.istitle()

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

   例えば:

      >>> 'Spam, Spam, Spam'.istitle()
      True
      >>> 'spam, spam, spam'.istitle()
      False
      >>> 'SPAM, SPAM, SPAM'.istitle()
      False

   "title()" も参照してください。

str.isupper()

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

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

str.join(iterable, /)

   "iterable" 内の文字列を結合した文字列を返します。 "iterable" に
   "bytes" オブジェクトを含む文字列以外の値が一つでもある場合は、
   "TypeError" が送出されます。 要素間の区切りには、このメソッドを呼び
   出す文字列を使います。 例えば、次のようになります:

      >>> ', '.join(['spam', 'spam', 'spam'])
      'spam, spam, spam'
      >>> '-'.join('Python')
      'P-y-t-h-o-n'

   "split()" も参照してください。

str.ljust(width, fillchar=' ', /)

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

   例えば:

      >>> 'Python'.ljust(10)
      'Python    '
      >>> 'Python'.ljust(10, '.')
      'Python....'
      >>> 'Monty Python'.ljust(10, '.')
      'Monty Python'

   "rjust()" も参照してください。

str.lower()

   大小文字の区別のある文字 [4] をすべて小文字に変換した文字列のコピー
   を返します。 例えば、次のようになります:

      >>> 'Lower Method Example'.lower()
      'lower method example'

   小文字化のアルゴリズムは Unicode 標準の3.13.2節「Default Case
   Conversion」 に記載されています。

str.lstrip(chars=None, /)

   文字列の先頭の文字を除去したコピーを返します。引数 *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(dict, /)
static str.maketrans(from, to, remove='', /)

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

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

   引数が二つの場合、どちらも同じ長さの文字列でなければなりません。 結
   果の辞書では、"from" の各文字が "to" の同じ位置の文字にマップされま
   す。 3番目の引数を指定する場合、その引数は文字列でなければならず、
   その各文字は結果で "None" にマップされます。

   バージョン 3.15 で変更: "dict" に "frozendict" を指定できるようにな
   りました。

str.partition(sep, /)

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

   例えば:

      >>> 'Monty Python'.partition(' ')
      ('Monty', ' ', 'Python')
      >>> "Monty Python's Flying Circus".partition(' ')
      ('Monty', ' ', "Python's Flying Circus")
      >>> 'Monty Python'.partition('-')
      ('Monty Python', '', '')

   "rpartition()" も参照してください。

str.removeprefix(prefix, /)

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

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

   Added in version 3.9.

   "removesuffix()" と "startswith()" も参照してください。

str.removesuffix(suffix, /)

   文字列が "suffix" で終わり、かつ "suffix" が空でない場合は
   "string[:-len(suffix)]" を返します。 それ以外の場合は、元の文字列の
   コピーを返します:

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

   Added in version 3.9.

   "removeprefix()" と "endswith()" も参照してください。

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

   部分文字列 "old" のすべての出現箇所を "new" に置き換えた文字列のコ
   ピーを返します。 "count" を指定した場合は、先頭から "count" 個の出
   現箇所だけを置き換えます。 "count" を指定しない場合や "-1" を指定し
   た場合は、すべての出現箇所を置き換えます。 例えば、次のようになりま
   す:

      >>> 'spam, spam, spam'.replace('spam', 'eggs')
      'eggs, eggs, eggs'
      >>> 'spam, spam, spam'.replace('spam', 'eggs', 1)
      'eggs, spam, spam'

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

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

   部分文字列 "sub" が "s[start:end]" に収まる位置で見つかる、文字列内
   の最大のインデックスを返します。 省略可能な "start" と "end" 引数は
   スライス表記と同様に解釈されます。 見つからない場合は "-1" を返しま
   す。 例えば、次のようになります:

      >>> 'spam, spam, spam'.rfind('sp')
      12
      >>> 'spam, spam, spam'.rfind('sp', 0, 10)
      6

   "find()" と "rindex()" も参照してください。

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

   "rfind()" と同様ですが、部分文字列 "sub" が見つからない場合は
   "ValueError" を送出します。 例えば、次のようになります:

      >>> 'spam, spam, spam'.rindex('spam')
      12
      >>> 'spam, spam, spam'.rindex('eggs')
      Traceback (most recent call last):
        File "<stdin-0>", line 1, in <module>
          'spam, spam, spam'.rindex('eggs')
          ~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
      ValueError: substring not found

   "index()" と "find()" も参照してください。

str.rjust(width, fillchar=' ', /)

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

   例えば:

      >>> 'Python'.rjust(10)
      '    Python'
      >>> 'Python'.rjust(10, '.')
      '....Python'
      >>> 'Monty Python'.rjust(10, '.')
      'Monty Python'

   "ljust()" と "zfill()" も参照してください。

str.rpartition(sep, /)

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

   例えば:

      >>> 'Monty Python'.rpartition(' ')
      ('Monty', ' ', 'Python')
      >>> "Monty Python's Flying Circus".rpartition(' ')
      ("Monty Python's Flying", ' ', 'Circus')
      >>> 'Monty Python'.rpartition('-')
      ('', '', 'Monty Python')

   "partition()" も参照してください。

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

   区切り文字列として "sep" を使い、文字列内の単語のリストを返します。
   "maxsplit" を指定した場合は、*右端から* 最大 "maxsplit" 回分割しま
   す。 "sep" を指定しない場合や "None" を指定した場合は、任意の "空白
   文字" の文字列を区切りとします。 右から分割する点を除いて、
   "rsplit()" は後で詳しく説明する "split()" と同様に動作します。

str.rstrip(chars=None, /)

   末尾の文字を除去した文字列のコピーを返します。 "chars" 引数は、除去
   する文字の集合を指定する文字列です。 "chars" 引数を省略した場合や
   "None" を指定した場合は、デフォルトで空白文字を除去します。 "chars"
   引数を接尾辞として扱うのではなく、その値を構成する文字を組み合わせ
   に関係なく除去します。 例えば、次のようになります:

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

   文字の集合に含まれる文字をすべて除去するのではなく、一つの接尾辞文
   字列を除去するメソッドについては、"removesuffix()" を参照してくださ
   い。 例えば、次のようになります。

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

   "strip()" も参照してください。

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

   "sep" を指定しないか "None" を指定し、かつ "maxsplit" が "0" の場合
   は、先頭の連続する空白文字だけを扱います。

   例えば:

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

   "join()" と "rsplit()" も参照してください。

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

   区切り文字列 *sep* を指定した "split()" とは異なり、 このメソッドは
   空文字列に対して空のリストを返し、末尾に改行があっても余分な行を追
   加しません:

      >>> "".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* があれば、その位置で比較を止めます。

   例えば:

      >>> 'Python'.startswith('Py')
      True
      >>> 'a tuple of prefixes'.startswith(('at', 'a'))
      True
      >>> 'Python is amazing'.startswith('is', 7)
      True

   "endswith()" と "removeprefix()" も参照してください。

str.strip(chars=None, /)

   先頭と末尾の文字を除去した文字列のコピーを返します。 "chars" 引数は
   、除去する文字の集合を指定する文字列です。 "chars" 引数を省略した場
   合や "None" を指定した場合は、デフォルトで空白文字を除去します。
   "chars" 引数を接頭辞や接尾辞として扱うのではなく、その値を構成する
   文字を組み合わせに関係なく除去します。

   空白文字は "str.isspace()" で定義されています。

   例えば:

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

   "rstrip()" も参照してください。

str.swapcase()

   大文字を小文字に、小文字を大文字に変換した文字列のコピーを返します
   。 例えば、次のようになります:

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

   "s.swapcase().swapcase() == s" が常に成り立つとは限らないことに注意
   してください。 例えば、次のようになります:

      >>> 'straße'.swapcase().swapcase()
      'strasse'

   "str.lower()" と "str.upper()" も参照してください。

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

   "istitle()" も参照してください。

str.translate(table, /)

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

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

   次の例では、マッピングを使って "'a'" を "'X'" に、"'b'" を "'Y'" に
   置き換え、"'c'" を削除します:

      >>> 'abc123'.translate({ord('a'): 'X', ord('b'): 'Y', ord('c'): None})
      'XY123'

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

str.upper()

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

   大文字化のアルゴリズムは Unicode 標準の3.13.2節「Default Case
   Conversion」 に記載されています。

str.zfill(width, /)

   長さが "width" になるよう、左側を ASCII "'0'" で埋めた文字列のコピ
   ーを返します。 先頭に符号接頭辞 ("'+'"/"'-'") がある場合は、符号文
   字の前ではなく *後* にパディングを挿入します。 "width" が "len(s)"
   以下の場合は元の文字列を返します。

   例えば:

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

   "rjust()" も参照してください。


フォーマット済み文字列リテラル (f-string)
-----------------------------------------

Added in version 3.6.

バージョン 3.7 で変更: f-string 内の式で "await" と "async for" を使え
るようになりました。

バージョン 3.8 で変更: デバッグ指定子 ("=") を追加しました

バージョン 3.12 で変更: f-string 内の式に対する多くの制限が取り除かれ
ました。 特に、文字列の入れ子、コメント、バックスラッシュが使えるよう
になりました。

接頭辞 "f" または "F" を付けた文字列リテラルを *f-string* (正式には *
フォーマット済み文字列リテラル*) と呼びます。 この文字列リテラルでは、
波括弧 ("{}") で区切った *置換フィールド* に、任意の Python 式の結果を
埋め込めます。 各置換フィールドには式が必要で、その後に必要に応じて次
のものを指定できます:

* *デバッグ指定子* である等号 ("=")。

* *変換指定子* である "!s"、"!r"、"!a" のいずれか。 これと次の書式指定
  子は、どちらか一方または両方を指定できます。

* コロン (":") を先頭に付けた *書式指定子*。

これらのフィールドの構文について詳しくは、字句解析の f-string に関する
節 を参照してください。


デバッグ指定子
~~~~~~~~~~~~~~

Added in version 3.8.

置換フィールドの式の後にデバッグ指定子である等号 ("=") を付けると、結
果の f-string には式のソース、等号、式の値が含まれます。 これはデバッ
グに役立つことがよくあります。

   >>> number = 14.3
   >>> f'{number=}'
   'number=14.3'

式の前後や内部の空白、および等号の後の空白には意味があり、そのまま結果
に残ります。

   >>> f'{ number  -  4  = }'
   ' number  -  4  = 10.3'


変換指定子
~~~~~~~~~~

By default, the value of a replacement field expression is converted
to a string using "str()":

   >>> from fractions import Fraction
   >>> one_third = Fraction(1, 3)
   >>> f'{one_third}'
   '1/3'

デバッグ指定子があり書式指定子がない場合、デフォルトの変換には代わりに
"repr()" を使います。

   >>> f'{one_third = }'
   'one_third = Fraction(1, 3)'

次のいずれかの指定子を使って、変換を明示的に指定できます:

* "str()" に対しては "!s"

* "repr()" に対しては "!r"

* "ascii()" に対しては "!a"

例えば:

   >>> str(one_third)
   '1/3'
   >>> repr(one_third)
   'Fraction(1, 3)'

   >>> f'{one_third!s} is {one_third!r}'
   '1/3 is Fraction(1, 3)'

   >>> string = "¡kočka 😸!"
   >>> ascii(string)
   "'\\xa1ko\\u010dka \\U0001f638!'"

   >>> f'{string = !a}'
   "string = '\\xa1ko\\u010dka \\U0001f638!'"


書式指定子
~~~~~~~~~~

式を評価し、明示的な変換指定子がある場合は変換を行った後、"format()"
関数で書式化します。 置換フィールドにコロン (":") に続く *書式指定子*
が含まれている場合、その指定子を "format()" の第2引数として渡します。
"format()" の結果を置換フィールドの最終的な値として使います。 例えば、
次のようになります。

   >>> from fractions import Fraction
   >>> one_third = Fraction(1, 3)
   >>> f'{one_third:.6f}'
   '0.333333'
   >>> f'{one_third:_^+10}'
   '___+1/3___'
   >>> f'{one_third!r:_^20}'
   '___Fraction(1, 3)___'
   >>> f'{one_third = :~>10}~'
   'one_third = ~~~~~~~1/3~'


テンプレート文字列リテラル (t-string)
-------------------------------------

接頭辞 "t" または "T" を付けた文字列リテラルを *t-string* (正式には *
テンプレート文字列リテラル*) と呼びます。

これらの文字列は、次の点を除いて フォーマット済み文字列リテラル と同じ
構文と評価規則に従います:

* テンプレート文字列リテラルを評価すると、"str" オブジェクトの代わりに
  "string.templatelib.Template" オブジェクトが得られます。

* "format()" プロトコルは使われません。 代わりに、評価した式ごとに新し
  い "Interpolation" オブジェクトが作成され、書式指定子や変換の指定が
  あれば、そのオブジェクトに渡されます。 書式指定子と変換をどのように
  扱うかは、結果の "Template" オブジェクトを処理するコードが決めます。

* 入れ子になった置換フィールドを含む書式指定子は、"Interpolation" オブ
  ジェクトに渡される前に即座に評価されます。 例えば、
  "{amount:.{precision}f}" 形式の補間では、内部の式 "{precision}" を評
  価して "format_spec" 属性の値を決めます。 "precision" が "2" なら、
  結果の書式指定子は "'.2f'" になります。

* 補間式に等号 "'='" を指定すると、その式のテキストが、対応する補間の
  直前のリテラル文字列に追加されます。 これには等号とその周囲の空白も
  含まれます。 その式に対する "Interpolation" インスタンスは通常どおり
  作成されますが、"conversion" はデフォルトで '"r"' ("repr()") に設定
  されます。 変換や書式指定子を明示的に指定した場合は、このデフォルト
  の動作が上書きされます。


"printf" 形式の文字列書式化
---------------------------

注釈:

  ここで説明する書式化演算にはさまざまな癖があり、タプルや辞書を正しく
  表示できないなど、よくある誤りの原因となります。これらの誤りは、フォ
  ーマット済み文字列リテラル、"str.format()" インターフェース、
  "string.Template" を使うことで避けられる場合があります。 それぞれの
  方法には、簡潔さ、柔軟さ、拡張性の点で利点やトレードオフがあります。

文字列オブジェクトには独特の組み込み演算子: "%" 演算子 (モジュロ) があ
ります。これは 文字列の *書式化* あるいは *補間* 演算子としても知られ
ています。 "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.

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

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

+-----------+-----------------------------------------------------------------------+
| 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'"        | 指数表記の浮動小数点数 (小文字)。                     | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'E'"        | 指数表記の浮動小数点数 (大文字)。                     | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'f'"        | 10 進浮動小数点数。                                   | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'F'"        | 10 進浮動小数点数。                                   | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'g'"        | 浮動小数点数の書式。 指数が -4 未満または指定精度以上 | (4)     |
|              | の場合は小文字の 指数表記を使い、それ以外は10進表記を |         |
|              | 使います。                                            |         |
+--------------+-------------------------------------------------------+---------+
| "'G'"        | 浮動小数点数の書式。 指数が -4 未満または指定精度以上 | (4)     |
|              | の場合は大文字の 指数表記を使い、それ以外は10進表記を |         |
|              | 使います。                                            |         |
+--------------+-------------------------------------------------------+---------+
| "'c'"        | 文字一文字 (整数または一文字からなる文字列を受理しま  |         |
|              | す)。                                                 |         |
+--------------+-------------------------------------------------------+---------+
| "'r'"        | 文字列 (Python オブジェクトを "repr()" で変換します)  | (5)     |
|              | 。                                                    |         |
+--------------+-------------------------------------------------------+---------+
| "'s'"        | 文字列 (Python オブジェクトを "str()" で変換します)。 | (5)     |
+--------------+-------------------------------------------------------+---------+
| "'a'"        | 文字列 (Python オブジェクトを "ascii()" で変換します) | (5)     |
|              | 。                                                    |         |
+--------------+-------------------------------------------------------+---------+
| "'%'"        | 引数を変換せず、返される文字列中では文字 "'%'" になり |         |
|              | ます。                                                |         |
+--------------+-------------------------------------------------------+---------+

For floating-point formats, the result should be correctly rounded to
a given precision "p" of digits after the decimal point.  The rounding
mode matches that of the "round()" builtin.

注釈:

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=b'')
class bytes(source, encoding, errors='strict')

   まず、 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 の空白文字全てをスキップするようになりました。

      バージョン 3.14 で変更: "bytes.fromhex()" が入力として ASCII の
      "bytes" および *bytes-like オブジェクト* を受け付けるようになり
      ました。

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

   hex(*, bytes_per_sep=1)
   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" オブジェクトの可変なバージョンです
。

class bytearray(source=b'')
class bytearray(source, encoding, errors='strict')

   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 オブジェクトを返します。 文字列には1バ
      イトにつき2桁の16進数字を含める必要があり、ASCII 空白文字は無視
      されます。

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

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

      バージョン 3.14 で変更: "bytearray.fromhex()" が入力として ASCII
      の "bytes" および *bytes-like オブジェクト* を受け付けるようにな
      りました。

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

   hex(*, bytes_per_sep=1)
   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* をサ
      ポートするようになりました。

   resize(size, /)

      "bytearray" のサイズを "size" バイトに変更します。 "size" は0以
      上でなければなりません。

      "bytearray" を縮小する場合は、"size" を超える部分のバイトを切り
      捨てます。

      If the "bytearray" needs to grow, all new bytes, those beyond
      *size*, will be set to null bytes.

      これは次と等価です:

      >>> def resize(ba, size):
      ...     if len(ba) > size:
      ...         del ba[size:]
      ...     else:
      ...         ba += b'\0' * (size - len(ba))

      例:

      >>> shrink = bytearray(b'abc')
      >>> shrink.resize(1)
      >>> (shrink, len(shrink))
      (bytearray(b'a'), 1)
      >>> grow = bytearray(b'abc')
      >>> grow.resize(5)
      >>> (grow, len(grow))
      (bytearray(b'abc\x00\x00'), 5)

      Added in version 3.14.

   take_bytes(n=None, /)

      bytearray の先頭から "n" バイトを削除し、イミュータブルな
      "bytes" として返します。 デフォルトでは ("n" が "None" の場合)、
      すべてのバイトを返し、bytearray を空にします。

      "n" が負の場合は末尾から数え、先頭から "len()" と "n" の和のバイ
      ト数を取り出します。 "n" が範囲外の場合は "IndexError" を送出し
      ます。

      全体の長さより少ないバイト数を取り出す場合は、"bytearray" にバイ
      トが残るため、コピーが必要です。 残りのバイトを破棄する場合は、
      "resize()" または "del" で切り詰めてから、サイズを指定せず
      "take_bytes()" を使ってください。

      すべてのバイトを取り出す操作ではコピーが行われません。

      Added in version 3.15: "bytearray.take_bytes()" によって最適化で
      きる一般的なコードパターンについては、新機能の紹介 を参照してく
      ださい。

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

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

参考:

  "bytearray" オブジェクトのスレッドセーフ性の保証については、
  bytearray オブジェクトのスレッドセーフ性 を参照してください。


bytes と bytearray の操作
-------------------------

bytes オブジェクトと bytearray オブジェクトは、どちらも 共通のシーケン
ス演算 をサポートします。 同じ型のオペランドだけでなく、任意の *bytes-
like object* とも相互に演算できます。 この柔軟性により、これらの型を演
算で自由に混在させてもエラーにはなりません。 ただし、結果の型はオペラ
ンドの順序によって異なる場合があります。

注釈:

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

   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' 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 オブジェクト* で、
   同じ長さでなければなりません。

   Added in version 3.1.

bytes.partition(sep, /)
bytearray.partition(sep, /)

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

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

bytes.replace(old, new, /, count=-1)
bytearray.replace(old, new, /, count=-1)

   部分シーケンス "old" のすべての出現箇所を "new" に置き換えたシーケ
   ンスのコピーを返します。 "count" を指定した場合は、先頭から "count"
   個の出現箇所だけを置き換えます。 "count" を指定しない場合や "-1" を
   指定した場合は、すべての出現箇所を置き換えます。

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

   注釈:

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

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

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=b' ', /)
bytearray.center(width, fillbyte=b' ', /)

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

   注釈:

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

bytes.ljust(width, fillbyte=b' ', /)
bytearray.ljust(width, fillbyte=b' ', /)

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

   注釈:

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

bytes.lstrip(bytes=None, /)
bytearray.lstrip(bytes=None, /)

   先頭から指定されたバイトを除去したシーケンスのコピーを返します。
   "bytes" 引数は、除去するバイト値の集合を指定するバイナリシーケンス
   です。 "bytes" 引数を省略した場合や "None" を指定した場合は、デフォ
   ルトで "ASCII 空白文字" を除去します。 "bytes" 引数を接頭辞として扱
   うのではなく、その値を構成するバイトを組み合わせに関係なく除去しま
   す。

      >>> 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=b' ', /)
bytearray.rjust(width, fillbyte=b' ', /)

   長さ *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(bytes=None, /)
bytearray.rstrip(bytes=None, /)

   末尾から指定されたバイトを除去したシーケンスのコピーを返します。
   "bytes" 引数は、除去するバイト値の集合を指定するバイナリシーケンス
   です。 "bytes" 引数を省略した場合や "None" を指定した場合は、デフォ
   ルトで "ASCII 空白文字" を除去します。 "bytes" 引数を接尾辞として扱
   うのではなく、その値を構成するバイトを組み合わせに関係なく除去しま
   す。

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

   *sep* を指定した場合、連続する区切りは一つにまとめられず、空の部分
   シーケンスを区切るものとみなされます (例えば "b'1,,2'.split(b',')"
   は "[b'1', b'', b'2']" を返します)。 *sep* には、複数バイトのシーケ
   ンスを一つの区切りとして指定できます。 区切りを指定して空のシーケン
   スを分割すると、分割するオブジェクトの型に応じて "[b'']" または
   "[bytearray(b'')]" が返されます。 *sep* には、任意の *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'']
      >>> b'1<>2<>3<4'.split(b'<>')
      [b'1', b'2', b'3<4']

   "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(bytes=None, /)
bytearray.strip(bytes=None, /)

   先頭と末尾から指定されたバイトを除去したシーケンスのコピーを返しま
   す。 "bytes" 引数は、除去するバイト値の集合を指定するバイナリシーケ
   ンスです。 "bytes" 引数を省略した場合や "None" を指定した場合は、デ
   フォルトで "ASCII 空白文字" を除去します。 "bytes" 引数を接頭辞や接
   尾辞として扱うのではなく、その値を構成するバイトを組み合わせに関係
   なく除去します。

      >>> 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 の範囲にあります。

   Added in version 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']

   区切り文字列 *sep* を指定した "split()" とは異なり、 このメソッドは
   空のシーケンスに対して空のリストを返し、末尾に改行があっても余分な
   行を追加しません:

      >>> 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 文字を対応する大文字に、大文字の ASCII
   文字を対応する小文字に変換したコピーを返します。

   例えば:

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

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

   "str.swapcase()" とは異なり、バイナリ版では
   "bin.swapcase().swapcase() == bin" が常に成り立ちます。 任意の
   Unicode コードポイントについては一般に成り立ちませんが、ASCII では
   大文字と小文字の変換が対称だからです。

   注釈:

     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'-'") がある場合は、
   符号文字の前ではなく *後* にパディングを挿入します。 "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* の0個
以上の要素に置き換えられます。 その効果は 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'"        | 指数表記の浮動小数点数 (小文字)。                     | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'E'"        | 指数表記の浮動小数点数 (大文字)。                     | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'f'"        | 10 進浮動小数点数。                                   | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'F'"        | 10 進浮動小数点数。                                   | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'g'"        | 浮動小数点数の書式。 指数が -4 未満または指定精度以上 | (4)     |
|              | の場合は小文字の 指数表記を使い、それ以外は10進表記を |         |
|              | 使います。                                            |         |
+--------------+-------------------------------------------------------+---------+
| "'G'"        | 浮動小数点数の書式。 指数が -4 未満または指定精度以上 | (4)     |
|              | の場合は大文字の 指数表記を使い、それ以外は10進表記を |         |
|              | 使います。                                            |         |
+--------------+-------------------------------------------------------+---------+
| "'c'"        | 1 バイト (整数または要素 1 つの "bytes"/"bytearray"   |         |
|              | オブジェクトを受理 します)                            |         |
+--------------+-------------------------------------------------------+---------+
| "'b'"        | バイナリシーケンス (buffer protocol をサポートするか  | (5)     |
|              | 、 "__bytes__()" メソッドがあるオブジェクト)          |         |
+--------------+-------------------------------------------------------+---------+
| "'s'"        | "'s'" は "'b'" の別名です。Python 2/3 の両方を対象と  | (6)     |
|              | したコードでのみ使 用すべきです。                     |         |
+--------------+-------------------------------------------------------+---------+
| "'a'"        | バイナリシーケンス (Python オブジェクトを             | (5)     |
|              | "repr(obj).encode('ascii', 'backslashreplace')" で変  |         |
|              | 換します)。                                           |         |
+--------------+-------------------------------------------------------+---------+
| "'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 への % 書式化の追加

Added in version 3.5.


メモリビュー
------------

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

class memoryview(object)

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

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

   "memoryview" は元のデータの型について ジェネリック です。

   "len(view)" は、ビューを入れ子のリストで表す "tolist()" の結果の長
   さと等しくなります。 "view.ndim == 1" の場合、これはビュー内の要素
   数と等しくなります。

   バージョン 3.12 で変更: "view.ndim == 0" の場合、"len(view)" は 1
   を返す代わりに "TypeError" を送出するようになりました。

   "itemsize" 属性は各要素のバイト数を与えます。

   "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 のインデックスを指
   定できるようになりました。

   バージョン 3.14 で変更: memoryview が *ジェネリック型* になりました
   。

   "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

      浮動小数点数の場合と同様 memoryview オブジェクトに対する "v is
      w" は "v == w" を意味 *しない* ことに注意してください。

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

   tobytes(order='C')

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

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

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

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

   hex(*, bytes_per_sep=1)
   hex(sep, bytes_per_sep=1)

      バッファ内の各バイトを2桁の16進数字で表した文字列オブジェクトを
      返します。

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

      Added in version 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]

      Added in version 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

      Added in version 3.2.

   cast(format, /)
   cast(format, shape, /)

      memoryview を新しいフォーマットまたは形状にキャストします。
      *shape* のデフォルト値は "[byte_length//new_itemsize]" で、結果
      のビューは1次元になります。 返り値は新しい memoryview ですが、バ
      ッファ自体はコピーされません。 サポートされるキャストは、1次元か
      ら C-*連続* への変換と、C-連続から1次元への変換です。

      変換先のフォーマットは、"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]]

      Added in version 3.3.

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

   count(value, /)

      "value" の出現回数を数えます。

      Added in version 3.14.

   index(value, start=0, stop=sys.maxsize, /)

      "value" が最初に出現する位置のインデックスを返します (インデック
      ス "start" 以上、"stop" 未満の範囲で検索します)。

      "value" が見つからない場合は "ValueError" を送出します。

      Added in version 3.14.

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

   obj

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

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

      Added in version 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

      Added in version 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* ）。

      Added in version 3.3.

   f_contiguous

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

      Added in version 3.3.

   contiguous

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

      Added in version 3.3.

*フリースレッドビルド* における "memoryview" オブジェクトのスレッドセ
ーフ性については、memoryview オブジェクトのスレッドセーフ性 を参照して
ください。


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

*集合 (set)* オブジェクトは、互いに異なる *ハッシュ可能* なオブジェク
トからなる順序を持たないコレクションです。 主な用途には、帰属判定、シ
ーケンスからの重複の除去、積集合・和集合・差集合・対称差といった数学的
演算の計算があります。 (その他のコンテナについては、組み込みの "dict"
、"list"、"tuple" クラス、および "collections" モジュールを参照してく
ださい。) 各種集合演算の計算量については、組み込み型の操作の時間計算量
を参照してください。

集合は他のコレクションと同様に、"x in set"、"len(set)"、"for x in set"
をサポートします。 集合は順序を持たないコレクションなので、要素の位置
や挿入順序を記録しません。 そのため、インデックス指定やスライスなど、
シーケンスのような動作はサポートしません。

現在、組み込みの集合型には "set" と "frozenset" の二つがあります。
"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* のメンバーに含まれていないことを判定します。

frozenset.isdisjoint(other, /)
set.isdisjoint(other, /)

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

frozenset.issubset(other, /)
set.issubset(other, /)

set <= other

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

set < other

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

frozenset.issuperset(other, /)
set.issuperset(other, /)

set >= other

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

set > other

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

frozenset.union(*others)
set.union(*others)

set | other | ...

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

frozenset.intersection(*others)
set.intersection(*others)

set & other & ...

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

frozenset.difference(*others)
set.difference(*others)

set - other - ...

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

frozenset.symmetric_difference(other, /)
set.symmetric_difference(other, /)

set ^ other

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

frozenset.copy()
set.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" のイミュー
タブルなインスタンスには適用されません:

set.update(*others)

set |= other | ...

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

set.intersection_update(*others)

set &= other & ...

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

set.difference_update(*others)

set -= other | ...

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

set.symmetric_difference_update(other, /)

set ^= other

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

set.add(elem, /)

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

set.remove(elem, /)

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

set.discard(elem, /)

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

set.pop()

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

set.clear()

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

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

Note, the *elem* argument to the "__contains__()", "remove()", and
"discard()" methods may be a set.  To support searching for an
equivalent frozenset, a temporary one is created from *elem*.

set と frozenset は要素の型について ジェネリック です。

参考: "set" オブジェクトのスレッドセーフ性の保証については、set オブジェク
    トのスレッドセーフ性 を参照してください。


マッピング型 --- "dict"、"frozendict"
=====================================

*マッピング* オブジェクトは、*ハッシュ可能* な値を任意のオブジェクトに
対応付けます。 現在、標準のマッピング型には *辞書 (dictionary)* と
"frozendict" の二つがあります。 (その他のコンテナについては、組み込み
の "list"、"set"、"tuple" クラス、および "collections" モジュールを参
照してください。) 各種辞書演算の計算量については、組み込み型の操作の時
間計算量 を参照してください。

辞書のキーには、*ほぼ* 任意の値を使えます。 *ハッシュ可能* でない値、
すなわちリスト、辞書、その他のミュータブルな型 (オブジェクトの同一性で
はなく値によって比較されるもの) を含む値は、キーとして使えません。 比
較すると等しい値 (例えば "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)"

   位置引数を指定しない場合は、空の辞書を作成します。 位置引数を指定し
   、そのオブジェクトに "keys()" メソッドが定義されている場合は、その
   メソッドが返す各キーを使って位置引数の "__getitem__()" を呼び出し、
   辞書を作成します。 それ以外の場合、位置引数は *イテラブル* オブジェ
   クトでなければなりません。 そのイテラブル内の各要素も、それぞれちょ
   うど二つの要素を持つイテラブルでなければなりません。 各要素の1番目
   の値が新しい辞書のキーとなり、2番目の値が対応する値となります。 同
   じキーが複数回出現した場合は、そのキーの最後の値が新しい辞書での対
   応する値となります。

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

   辞書同士は、順序に関係なく同じ "(key, value)" 対を持つ場合に限り等
   しいとみなされます。 順序比較 ('<'、'<='、'>='、'>') は "TypeError"
   を送出します。 辞書の作成と等価性を示す次の例は、すべて "{"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
   の識別子でなければなりません。それ以外の方法では、辞書のキーとして
   有効などんなキーでも使えます。

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

      >>> 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 の実装詳細でした。

   辞書は、キーと値の型をそれぞれ表す二つの型について ジェネリック で
   す。

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

   list(d)

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

   len(d)

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

   d[key]

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

      dict のサブクラスに "__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" の実装の一部を示しています。
      "collections.defaultdict" では、異なる "__missing__()" メソッド
      を使っています。

   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=None, /)

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

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

   get(key, default=None, /)

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

   items()

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

   keys()

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

   pop(key, /)
   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())" へのショートカットです。

      Added in version 3.8.

   setdefault(key, default=None, /)

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

   update(**kwargs)
   update(mapping, /, **kwargs)
   update(iterable, /, **kwargs)

      "mapping" または "iterable" と "kwargs" のキーと値の対で辞書を更
      新し、既存のキーを上書きします。 "None" を返します。

      "update()" は、"keys()" メソッドを持つ別のオブジェクトか、キーと
      値の対のイテラブル (各対はタプル、または長さ2のその他のイテラブ
      ル) を受け付けます。 前者の場合、そのメソッドが返す各キーを使っ
      て "__getitem__()" を呼び出します。 キーワード引数を指定した場合
      は、続いてそれらのキーと値の対で辞書を更新します:
      "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* は両方とも辞書でなければなりません。 *d* と *other*
      でキーが重複する場合は、*other* の値が優先されます。

      Added in version 3.9.

   d |= other

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

      Added in version 3.9.

   辞書と辞書のビューは "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 で変更: 辞書がリバース可能になりました。

   参考:

     "frozendict" and "types.MappingProxyType" can be used to create a
     read-only view of a "dict".

参考: "dict" オブジェクトのスレッドセーフ性の保証については、dict オブジェ
    クトのスレッドセーフ性 を参照してください。


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

"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" オブジェ
   クト を返します。

   Added in version 3.10.

キーのビューは要素に重複がなくハッシュ可能 (*hashable*) であるため、集
合の特性を持ちます。項目のビューも、 キーと値の対に重複がなく、かつキ
ーがハッシュ可能であるため、集合的な演算を持っています。もし項目の全て
の値がハッシュ可能ならば、項目のビューは集合と相互に演算することが可能
です。 (値のビューは一般に要素に重複があるため、集合の特性を持つとはみ
なされません。) 集合の特性を持つビューに対しては、
"collections.abc.Set" 抽象基底クラスで定義された全ての演算が利用可能で
す (たとえば "==", "<" や "^" など)。 集合演算に対しては、集合はオペラ
ンドとして集合しか取ることができないのに対して、これら集合の特性を持つ
ビューはオペランドとして任意のイテラブルを取ることができます。

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

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

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

   >>> # キーと値は同じ順序 (挿入順序) で反復される
   >>> list(keys)
   ['eggs', 'sausage', 'bacon', 'spam']
   >>> list(values)
   [2, 1, 1, 500]

   >>> # ビューオブジェクトは動的で、辞書の変更を反映する
   >>> del dishes['eggs']
   >>> del dishes['sausage']
   >>> list(keys)
   ['bacon', 'spam']

   >>> # 集合演算
   >>> keys & {'eggs', 'bacon', 'salad'}
   {'bacon'}
   >>> keys ^ {'sausage', 'juice'} == {'juice', 'sausage', 'bacon', 'spam'}
   True
   >>> keys | ['juice', 'juice', 'juice'] == {'bacon', 'spam', 'juice'}
   True

   >>> # 元の辞書の読み出し専用プロキシを取得する
   >>> values.mapping
   mappingproxy({'bacon': 1, 'spam': 500})
   >>> values.mapping['spam']
   500


凍結辞書
--------

class frozendict(**kwargs)
class frozendict(mapping, /, **kwargs)
class frozendict(iterable, /, **kwargs)

   省略可能な位置引数と、空でもよいキーワード引数の集まりから初期化し
   た、新しい凍結辞書を返します。

   "frozendict" の API は "dict" の API と似ていますが、次の点が異なり
   ます:

   * "dict" は "frozendict" より多くのメソッドを持ちます:

        * "__delitem__()"

        * "__setitem__()"

        * "clear()"

        * "pop()"

        * "popitem()"

        * "setdefault()"

        * "update()"

   * "frozendict" のすべてのキーと値がハッシュ可能であれば、
     "hash(frozendict)" でハッシュ値を計算できます。

   * "frozendict |= other" は "frozendict" をインプレースで変更せず、
     新しい凍結辞書を作成します。

   "frozendict" は "dict" のサブクラスではなく、"object" を直接継承し
   ます。

   辞書と同様に、frozendict はキーと値の型をそれぞれ表す二つの型につい
   て ジェネリック です。

   classmethod fromkeys(iterable, value=None, /)

      Similar to "dict.fromkeys()", but call again the type
      constructor with an initialized "frozendict" if the type is a
      "frozendict" subclass or if the constructor returned a
      "frozendict".

   Added in version 3.15.


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

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" ブロックで発生した例外を処理している間に別の
   例外を送出すると、新しい例外が送出され、元の例外はその
   "__context__" 属性に格納されます。

   渡された例外を明示的に再送出すべきではありません。その代わりに、こ
   のメソッドが偽の値を返すことでメソッドの正常終了と送出された例外を
   抑制しないことを伝えるべきです。このようにすればコンテキストマネー
   ジャは "__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" オブジェクトを直接作成する
こともできます。 ユーザ定義の ジェネリッククラス を特殊化したものは
"types.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'>

"GenericAlias" のインスタンスは、インスタンス化やサブクラス化ができる
などクラスのように振る舞いますが、実行時にはクラスではありません。

   >>> import inspect
   >>> inspect.isclass(list[int])
   False

これは ユーザ定義のジェネリック型 にも当てはまります。

パラメータ付きジェネリック型に "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"

* "frozendict"

* "frozenset"

* "type"

* "asyncio.Future"

* "asyncio.Task"

* "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" を参照してください)。

   Added in version 3.11.

参考:

  **PEP 484** - 型ヒント
     型アノテーションのための Python のフレームワークへの導入です。

  **PEP 585** - 標準コレクション型の型ヒントにおける総称型 (generics)
  の使用
     特殊なクラスメソッド "__class_getitem__()" を実装している場合に、
     標準ライブラリのクラスに対してネイティブにパラメータ表記を可能に
     する機能への導入です。

  ジェネリクス, ユーザー定義のジェネリック型, および  "typing.Generic"
     実行時にパラメータ設定が可能であり、かつ静的な型チェッカーが理解
     できるジェネリッククラスを実装する方法のドキュメントです。

Added in version 3.9.


Union 型
--------

ユニオンオブジェクトは、複数の 型オブジェクト に対する "|" (ビット単位
の論理和) 演算の値を保持します。 これらの型は主に *型アノテーション*
で使うことを想定しています。 ユニオン型の式を使うと、"typing.Union" の
添字表記よりも簡潔な型ヒントの構文で書けます。

X | Y | ...

   *X*、*Y* などの型を保持するユニオンオブジェクトを定義します。 "X |
   Y" は X または Y を意味し、"typing.Union[X, Y]" と等価です。 例えば
   、次の関数は "int" 型または "float" 型の引数を想定しています。

      def square(number: int | float) -> int | float:
          return number ** 2

   注釈:

     一つ以上のメンバーが前方参照であるユニオンを実行時に定義するため
     に、"|" 演算子を使うことはできません。 例えば、まだ定義されていな
     いクラスを ""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]
        type(int | str) is typing.Union

   * Optional型は "None" とのUnion型で記述できます:

        str | None == typing.Optional[str]

isinstance(obj, union_object)

issubclass(obj, union_object)

   ユニオンオブジェクトを使った "isinstance()" と "issubclass()" の呼
   び出しもサポートされています。

      >>> isinstance("", int | str)
      True

   しかし、Unionオブジェクトの中の parameterized generics はチェックで
   きません:

      >>> isinstance(1, int | list[int])  # 短絡評価
      True
      >>> isinstance([1], int | list[int])
      Traceback (most recent call last):
        ...
      TypeError: isinstance() argument 2 cannot be a parameterized generic

利用者がユニオンオブジェクトの型にアクセスするには "typing.Union" を使
います。 "isinstance()" による検査にも使えます。

   >>> import typing
   >>> isinstance(int | str, typing.Union)
   True
   >>> typing.Union()
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   TypeError: cannot create 'typing.Union' 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

Added in version 3.10.

バージョン 3.14 で変更: ユニオンオブジェクトは "typing.Union" のインス
タンスになりました。 以前は "types.UnionType" のインスタンスでしたが、
この型名は "typing.Union" のエイリアスとして残っています。


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

インタプリタは、その他いくつかの種類のオブジェクトをサポートしています
。これらのほとんどは 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()" など) と クラスのインスタンスメソッド の2種類があります
。 組み込みメソッドは、それをサポートする型の説明で扱います。

インスタンスを通してメソッド (クラスの名前空間内で定義された関数) にア
クセスすると、特殊なオブジェクトが得られます。それは束縛メソッド
(*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'  # メソッドに設定することはできない
   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__" にアクセスすると、実引数 "obj" と ""__code__"" を伴う 監査
イベント "object.__getattr__" が送出されます。

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

詳細は、 標準型の階層 を参照してください。


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

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

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


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

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

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


Ellipsis オブジェクト
---------------------

このオブジェクトは、何かが省略されていることを表すためによく使われます
。 特別な演算はサポートしていません。 省略記号オブジェクトはちょうど一
つだけ存在し、組み込み名 "Ellipsis" が付いています。
"type(Ellipsis)()" は "Ellipsis" シングルトンを生成します。

"Ellipsis" または "..." と書き表されます。

通常、"Ellipsis" オブジェクトとしての "..." は、例えば次のような箇所で
使われます:

* 呼び出し可能オブジェクトの引数 や タプルの要素 などの型アノテーショ
  ン。

* pass 文 の代わりとなる関数本体。

* NumPy のスライスとストライド などのサードパーティライブラリ。

Python では、"Ellipsis" オブジェクト以外の意味でも3個のドットを使いま
す。 例えば、次のような場合です:

* 省略された内容にマッチするパターンとしての、doctest の "ELLIPSIS"。

* 入力がまだ完了していないときの、*対話型* シェルの Python のデフォル
  トプロンプト。

最後に、Python ドキュメントでは内容の省略を意味する通常の英語の用法で
も3個のドットをよく使います。 これは、"Ellipsis" としても3個のドットを
使っているコード例にも当てはまります。


NotImplemented オブジェクト
---------------------------

このオブジェクトは、対応していない型に対して比較演算や二項演算が求めら
れたとき、それらの演算から返されます。詳細は 比較 を参照してください。
"NotImplemented" オブジェクトは一つだけです。 "type(NotImplemented)()"
はこの単一のインスタンスを作成します。

"NotImplemented" と書き表されます。


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

この情報は 標準型の階層 を参照してください。stack frame objects、
traceback objects、スライスオブジェクトについて記述されています。


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

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

definition.__name__

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

definition.__qualname__

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

   Added in version 3.3.

definition.__module__

   クラスまたは関数が定義されたモジュールの名前。

definition.__doc__

   クラスまたは関数のドキュメンテーション文字列。 未定義の場合は
   "None"。

definition.__type_params__

   ジェネリッククラスや関数、および 型エイリアス の 型パラメータ。 ジ
   ェネリックでないクラスや関数では空のタプルになります。

   Added in version 3.12.


整数と文字列の変換での長さ制限
==============================

CPythonはDoS(サービス妨害攻撃)を軽減するために "int" と "str" の間の変
換に全体的な制限を設けました。この制限は10進数や2のべき乗以外の基数に
*のみ* 適用されます。16進数、8進数と2進数は制限がありません。上限値は
設定できます。

CPython の "int" 型は、任意の長さの数を2進形式で格納します (一般に「
bignum」と呼ばれます)。 基数が2のべき乗でない限り、文字列と2進整数を線
形時間で相互変換できるアルゴリズムは存在しません。 10進数に対する既知
の最良のアルゴリズムでも、計算量は二次未満です。 "int('1' * 500_000)"
のような大きな値の変換には、高速な CPU でも1秒を超える時間が掛かる場合
があります。

変換するサイズを制限することは、 **CVE 2020-10735** を回避する実践的な
方法を提供します。

制限は、非線形な変換アルゴリズムが必要とされる場合に、入力または出力文
字列の桁数に対して適用されます。アンダースコアや正負の符号はカウントさ
れません。

演算の結果が制限を超えると、"ValueError" が送出されます:

   >>> import sys
   >>> sys.set_int_max_str_digits(4300)  # 例示用。これはデフォルト値。
   >>> _ = 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  # 16進数は制限されない。

デフォルトの上限値は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')
   ...

Added in version 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の場合は無効になります)。

Added in version 3.11.

注意:

  小さな上限値を設定すると、問題が起きる *可能性があります* 。 まれで
  すが、ソース内に最小の閾値を超える10進整数定数を含むコードが存在しま
  す。 上限値を設定すると、その上限より長い10進整数リテラルを含む
  Python ソースコードのパース時にエラーが発生します。 これは、通常は起
  動時やインポート時、場合によってはインストール時など、そのコードに対
  応する最新の ".pyc" がまだ存在しないときに起こります。 このような大
  きな定数を含むソースでは、制限のない "0x" 形式の16進数へ定数を変換す
  ることで回避できます。小さな上限値を使う場合、アプリケーションを徹底
  的にテストしてください。環境変数やフラグを使って、制限が起動時や、さ
  らにはインストールの段階で Python が ".py" ファイルを事前にコンパイ
  ルして ".pyc" ファイルを作成する際にも適用されるようにした状態で、確
  実にテストが実行されるようにしてください。


推奨設定
--------

デフォルトの "sys.int_info.default_max_str_digits" は、ほとんどのアプ
リケーションで適切な値であると期待されます。もしあなたのアプリケーショ
ンが異なる制限値を必要とする場合は、メインのエントリーポイントから、
Python バージョンに依存しないコードを使って制限値を設定してください。
こうしなければならない理由は、これらの API が 3.12 以前のセキュリテイ
パッチリリースで追加されたためです。

以下はプログラム例です:

   >>> 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] 大小文字の区別のある文字とは、一般カテゴリプロパティが "Lu"
    (Letter, uppercase (大文字))、 "Ll" (Letter, lowercase (小文字))、
    "Lt" (Letter、titlecase (先頭が大文字)) のいずれかであるものです。

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