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

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

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

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

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


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

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

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

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

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

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

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


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

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

+---------------+-----------------------------------+---------+
| 演算          | 結果                              | 注釈    |
|===============|===================================|=========|
| "x or y"      | *x* が偽なら *y*, そうでなければ  | (1)     |
|               | *x*                               |         |
+---------------+-----------------------------------+---------+
| "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" 例外を送出します。

Non-identical instances of a class normally compare as non-equal
unless the class defines the "__eq__()" method.

Instances of a class cannot be ordered with respect to other instances
of the same class, or other types of object, unless the class defines
enough of the methods "__lt__()", "__le__()", "__gt__()", and
"__ge__()" (in general, "__lt__()" and "__eq__()" are sufficient, if
you want the conventional meanings of the comparison operators).

"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'" をつけると虚数 (実部がゼ
ロの複素数) を与え、それに整数や浮動小数点数を加えて実部と虚部を持つ複
素数を得られます。

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

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

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

+-----------------------+-----------------------------------+-----------+----------------------+
| 演算                  | 結果                              | 注釈      | 完全なドキュメント   |
|=======================|===================================|===========|======================|
| "x + y"               | *x* と *y* の和                   |           |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "x - y"               | *x* と *y* の差                   |           |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "x * y"               | *x* と *y* の積                   |           |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "x / y"               | *x* と *y* の商                   |           |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "x // y"              | *x* と *y* の商を切り下げたもの   | (1)       |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "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. 整数の除算とも呼ばれます。結果の型は整数型とは限りませんが、結果の
   値は整数です。結果は常に負の無限大の方向に丸められます: "1//2" は
   "0" 、 "(-1)//2" は "-1" 、 "1//(-2)" は "-1" 、そして "(-1)//(-2)"
   は "0" です。

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

3. 浮動小数点数から整数への変換はC言語と同様の方法で丸め、または切り捨
   てられます; より明確に定義された変換を行う場合は、 "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" プロパティを持つコードポイントの完全なリストは https://www.un
   icode.org/Public/13.0.0/ucd/extracted/DerivedNumericType.txt をご覧
   ください。

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

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

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


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

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

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

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

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

注釈:

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

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

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

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


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

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

int.bit_length()

   整数を、符号と先頭の 0 は除いて二進法で表すために必要なビットの数を
   返します:

      >>> n = -37
      >>> bin(n)
      '-0b100101'
      >>> n.bit_length()
      6

   正確には、 "x" が非 0 なら、 "x.bit_length()" は "2**(k-1) <=
   abs(x) < 2**k" を満たす唯一の正の整数 "k" です。同様に、 "abs(x)"
   が十分小さくて対数を適切に丸められるとき、 "k = 1 + int(log(abs(x),
   2))" です。 "x" が 0 なら、 "x.bit_length()" は "0" を返します。

   次と等価です:

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

   バージョン 3.1 で追加.

int.to_bytes(length, byteorder, *, 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* バイトで表されます。整数が与えられた数のバイトで表
   せなければ、 "OverflowError" が送出されます。

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

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

   バージョン 3.2 で追加.

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

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

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

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

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

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

   バージョン 3.2 で追加.

int.as_integer_ratio()

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

   バージョン 3.8 で追加.


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

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

float.as_integer_ratio()

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

float.is_integer()

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

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

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

float.hex()

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

classmethod float.fromhex(s)

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

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

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

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

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

なお、指数部は 16 進数ではなく 10 進数で書かれ、係数に掛けられる 2 の
累乗を与えます。例えば、16 進文字列 "0x3.a7p10" は浮動小数点数 "(3 +
10./16 + 7./16**2) * 2.0**10" すなわち "3740.0" を表します:

   >>> float.fromhex('0x3.a7p10')
   3740.0

逆変換を "3740.0" に適用すると、同じ数を表す異なる 16 進文字列表現を返
します:

   >>> float.hex(3740.0)
   '0x1.d380000000000p+11'


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

For numbers "x" and "y", possibly of different types, it's a
requirement that "hash(x) == hash(y)" whenever "x == y" (see the
"__hash__()" method documentation for more details).  For ease of
implementation and efficiency across a variety of numeric types
(including "int", "float", "decimal.Decimal" and "fractions.Fraction")
Python's hash for numeric types is based on a single mathematical
function that's defined for any rational number, and hence applies to
all instances of "int" and "fractions.Fraction", and all finite
instances of "float" and "decimal.Decimal".  Essentially, this
function is given by reduction modulo "P" for a fixed prime "P".  The
value of "P" is made available to Python as the "modulus" attribute of
"sys.hash_info".

**CPython implementation detail:** 現在使われている素数は、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" 、
  "sys.hash_info.nan" は、正の無限大、負の無限大、nan を (それぞれ) 表
  すのに使われます。(すべてのハッシュ可能な nan は同じハッシュ値を持ち
  ます。)

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

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

   import sys, math

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

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

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

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

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

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

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

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


イテレータ型
============

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

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

container.__iter__()

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

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

iterator.__iter__()

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

iterator.__next__()

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

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

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


ジェネレータ型
--------------

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


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

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


共通のシーケンス演算
--------------------

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

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

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

+----------------------------+----------------------------------+------------+
| 演算                       | 結果                             | 注釈       |
|============================|==================================|============|
| "x in s"                   | *s* のある要素が *x* と等しけれ  | (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)        |
|                            | 素                               |            |
+----------------------------+----------------------------------+------------+
| "s[i:j]"                   | *s* の *i* から *j* までのスライ | (3)(4)     |
|                            | ス                               |            |
+----------------------------+----------------------------------+------------+
| "s[i:j:k]"                 | *s* の *i* から *j* まで、 *k*   | (3)(5)     |
|                            | 毎のスライス                     |            |
+----------------------------+----------------------------------+------------+
| "len(s)"                   | *s* の長さ                       |            |
+----------------------------+----------------------------------+------------+
| "min(s)"                   | *s* の最小の要素                 |            |
+----------------------------+----------------------------------+------------+
| "max(s)"                   | *s* の最大の要素                 |            |
+----------------------------+----------------------------------+------------+
| "s.index(x[, i[, j]])"     | *s* 中で *x* が最初に出現するイ  | (8)        |
|                            | ンデックス (インデックス *i* 以  |            |
|                            | 降からイ ンデックス *j* までの範 |            |
|                            | 囲)                              |            |
+----------------------------+----------------------------------+------------+
| "s.count(x)"               | *s* 中に *x* が出現する回数      |            |
+----------------------------+----------------------------------+------------+

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

注釈:

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

      >>> "gg" in "eggs"
      True

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

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

   ここで、"[[]]" が空リストを含む 1 要素のリストなので、"[[]] * 3" の
   3 要素はこの一つの空リスト (への参照) です。"lists" のいずれかの要
   素を変更すると、その一つのリストが変更されます。別々のリストのリス
   トを作るにはこうします:

      >>> lists = [[] for i in range(3)]
      >>> lists[0].append(3)
      >>> lists[1].append(5)
      >>> lists[2].append(7)
      >>> lists
      [[3], [5], [7]]

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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


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

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

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

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

注釈:

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

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

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

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

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

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

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


リスト型 (list)
---------------

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

class list([iterable])

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


タプル型 (tuple)
----------------

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

class tuple([iterable])

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

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

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

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

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

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

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

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

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


range
-----

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

class range(stop)
class range(start, stop[, step])

   The arguments to the range constructor must be integers (either
   built-in "int" or any object that implements the "__index__()"
   special method).  If the *step* argument is omitted, it defaults to
   "1". If the *start* argument is omitted, it defaults to "0". If
   *step* is zero, "ValueError" is raised.

   *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 オブジェクトをそれらが定義する値のシーケンスに基づいて比較する
ように '==' と '!=' を定義しました。

バージョン 3.3 で追加: 属性 "start", "stop" および "step"。

参考:

  * linspace レシピ には、遅延評価される浮動小数点版の range の実装方
    法が載っています。


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

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

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

* Double quotes: ""allows embedded 'single' quotes""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


文字列メソッド
--------------

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

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

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

str.capitalize()

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

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

str.casefold()

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

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

   casefold のアルゴリズムは Unicode Standard のセクション 3.13 に記述
   されています。

   バージョン 3.3 で追加.

str.center(width[, fillchar])

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

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

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

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

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

   By default, the *errors* argument is not checked for best
   performances, but only used at the first encoding error. Enable the
   Python Development Mode, or use a debug build to check *errors*.

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

   バージョン 3.9 で変更: The *errors* is now checked in development
   mode and in debug mode.

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

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

str.expandtabs(tabsize=8)

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

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

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

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

   注釈:

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

        >>> 'Py' in 'Python'
        True

str.format(*args, **kwargs)

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

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

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

   注釈:

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

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

str.format_map(mapping)

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

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

   バージョン 3.2 で追加.

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

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

str.isalnum()

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

str.isalpha()

   文字列中の全ての文字が英字で、かつ 1 文字以上あるなら "True" を、そ
   うでなければ "False" を返します。英字は、Unicode 文字データベースで
   "Letter" として定義されているもので、すなわち、一般カテゴリプロパテ
   ィ "Lm"、 "Lt"、 "Lu"、 "Ll"、 "Lo" のいずれかをもつものです。なお
   、これは Unicode 標準で定義されている "Alphabetic" プロパティとは異
   なるものです。

str.isascii()

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

   バージョン 3.7 で追加.

str.isdecimal()

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

str.isdigit()

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

str.isidentifier()

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

   文字列 "s" が "def" や "class" のような予約済みの識別子か判定するに
   は "keyword.iskeyword()" を呼び出してください。

   例:

      >>> from keyword import iskeyword

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

str.islower()

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

str.isnumeric()

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

str.isprintable()

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

str.isspace()

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

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

str.istitle()

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

str.isupper()

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

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

str.join(iterable)

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

str.ljust(width[, fillchar])

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

str.lower()

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

   使われる小文字化のアルゴリズムは Unicode Standard のセクション 3.13
   に記述されています。

str.lstrip([chars])

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

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

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

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

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

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

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

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

str.partition(sep)

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

str.removeprefix(prefix, /)

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

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

   バージョン 3.9 で追加.

str.removesuffix(suffix, /)

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

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

   バージョン 3.9 で追加.

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

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

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

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

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

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

str.rjust(width[, fillchar])

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

str.rpartition(sep)

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

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

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

str.rstrip([chars])

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

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

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

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

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

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

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

   例えば:

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

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

   例えば:

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

str.splitlines(keepends=False)

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

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

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

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

   例えば:

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

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

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

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

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

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

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

str.strip([chars])

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

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

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

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

str.swapcase()

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

str.title()

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

   例えば:

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

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

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

   The "string.capwords()" function does not have this problem, as it
   splits words on spaces only.

   Alternatively, a workaround for apostrophes can be constructed
   using regular expressions:

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

str.translate(table)

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

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

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

str.upper()

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

   使われる大文字化のアルゴリズムは Unicode Standard のセクション 3.13
   に記述されています。

str.zfill(width)

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

   例えば:

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


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

注釈:

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

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

*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)     |
|              | 。                                                    |         |
+--------------+-------------------------------------------------------+---------+
| "'%'"        | 引数を変換せず、返される文字列中では文字 "'%'" になり |         |
|              | ます。                                                |         |
+--------------+-------------------------------------------------------+---------+

注釈:

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

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

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

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

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

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

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

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

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

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


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

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

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


バイトオブジェクト
------------------

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

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

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

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

   * Double quotes: "b"still allows embedded 'single' quotes""

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

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

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

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

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

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

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

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

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

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

   classmethod fromhex(string)

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

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

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

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

   hex([sep[, bytes_per_sep]])

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

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

      If you want to make the hex string easier to read, you can
      specify a single character separator *sep* parameter to include
      in the output. By default between each byte.  A second optional
      *bytes_per_sep* parameter controls the spacing.  Positive values
      calculate the separator position from the right, negative values
      from the left.

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

      バージョン 3.5 で追加.

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

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

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


bytearray オブジェクト
----------------------

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

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

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

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

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

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

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

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

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

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

   classmethod fromhex(string)

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

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

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

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

   hex([sep[, bytes_per_sep]])

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

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

      バージョン 3.5 で追加.

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

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

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


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

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

注釈:

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

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

  および:

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

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

注釈:

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

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

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

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

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

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

bytes.removeprefix(prefix, /)
bytearray.removeprefix(prefix, /)

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

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

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

   注釈:

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

   バージョン 3.9 で追加.

bytes.removesuffix(suffix, /)
bytearray.removesuffix(suffix, /)

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

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

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

   注釈:

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

   バージョン 3.9 で追加.

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

   与えられたバイト列からデコードされた文字列を返します。デフォルトの
   エンコーディングは "'utf-8'" です。 *errors* を与えて異なるエラー処
   理法を設定できます。 *errors* のデフォルトは "'strict'" で、エンコ
   ーディングエラーが "UnicodeError" を送出します。設定できる他の値は
   、 "'ignore'" 、 "'replace'" 、その他の "codecs.register_error()"
   を通して登録された名前で、節 エラーハンドラ を参照してください。可
   能なエンコーディングのリストは、 標準エンコーディング を参照してく
   ださい。

   By default, the *errors* argument is not checked for best
   performances, but only used at the first decoding error. Enable the
   Python Development Mode, or use a debug build to check *errors*.

   注釈:

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

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

   バージョン 3.9 で変更: The *errors* is now checked in development
   mode and in debug mode.

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

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

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

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

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

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

   注釈:

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

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

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

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

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

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

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

bytes.join(iterable)
bytearray.join(iterable)

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

static bytes.maketrans(from, to)
static bytearray.maketrans(from, to)

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

   バージョン 3.1 で追加.

bytes.partition(sep)
bytearray.partition(sep)

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

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

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

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

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

   注釈:

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

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

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

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

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

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

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

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

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

bytes.rpartition(sep)
bytearray.rpartition(sep)

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

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

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

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

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

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

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

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

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

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

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

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

bytes.center(width[, fillbyte])
bytearray.center(width[, fillbyte])

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

   注釈:

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

bytes.ljust(width[, fillbyte])
bytearray.ljust(width[, fillbyte])

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

   注釈:

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

bytes.lstrip([chars])
bytearray.lstrip([chars])

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

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

   The binary sequence of byte values to remove may be any *bytes-like
   object*. See "removeprefix()" for a method that will remove a
   single prefix string rather than all of a set of characters.  For
   example:

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

   注釈:

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

bytes.rjust(width[, fillbyte])
bytearray.rjust(width[, fillbyte])

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

   注釈:

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

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

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

bytes.rstrip([chars])
bytearray.rstrip([chars])

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

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

   The binary sequence of byte values to remove may be any *bytes-like
   object*. See "removesuffix()" for a method that will remove a
   single suffix string rather than all of a set of characters.  For
   example:

      >>> 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'1<>2<>3'.split(b'<>')" は "[b'1', b'2', b'3']" を返します)。空の
   シーケンスを分割すると、分割するオブジェクトの型によって "[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'']

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

   例えば:

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

bytes.strip([chars])
bytearray.strip([chars])

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

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

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

   注釈:

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

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

bytes.capitalize()
bytearray.capitalize()

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

   注釈:

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

bytes.expandtabs(tabsize=8)
bytearray.expandtabs(tabsize=8)

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

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

   注釈:

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

bytes.isalnum()
bytearray.isalnum()

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

   例えば:

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

bytes.isalpha()
bytearray.isalpha()

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

   例えば:

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

bytes.isascii()
bytearray.isascii()

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

   バージョン 3.7 で追加.

bytes.isdigit()
bytearray.isdigit()

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

   例えば:

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

bytes.islower()
bytearray.islower()

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

   例えば:

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

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

bytes.isspace()
bytearray.isspace()

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

bytes.istitle()
bytearray.istitle()

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

   例えば:

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

bytes.isupper()
bytearray.isupper()

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

   例えば:

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

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

bytes.lower()
bytearray.lower()

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

   例えば:

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

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

   注釈:

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

bytes.splitlines(keepends=False)
bytearray.splitlines(keepends=False)

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

   例えば:

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

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

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

bytes.swapcase()
bytearray.swapcase()

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

   例えば:

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

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

   "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'-'") だった場合、 "b'0'"
   は符号の前ではなく *後* に挿入されます。 "bytes" オブジェクトの場合
   、 *width* が "len(seq)" 以下であれば元のシーケンスが返ります。

   例えば:

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

   注釈:

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


"printf" 形式での bytes の書式化
--------------------------------

注釈:

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

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

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

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

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

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

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

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

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

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

7. 変換型。

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

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

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

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

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

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

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

+--------------+-------------------------------------------------------+---------+
| 変換         | 意味                                                  | 注釈    |
|==============|=======================================================|=========|
| "'d'"        | 符号付き 10 進整数。                                  |         |
+--------------+-------------------------------------------------------+---------+
| "'i'"        | 符号付き 10 進整数。                                  |         |
+--------------+-------------------------------------------------------+---------+
| "'o'"        | 符号付き 8 進数。                                     | (1)     |
+--------------+-------------------------------------------------------+---------+
| "'u'"        | 旧式の型 -- "'d'" と同じです。                        | (8)     |
+--------------+-------------------------------------------------------+---------+
| "'x'"        | 符号付き 16 進数 (小文字)。                           | (2)     |
+--------------+-------------------------------------------------------+---------+
| "'X'"        | 符号付き 16 進数 (大文字)。                           | (2)     |
+--------------+-------------------------------------------------------+---------+
| "'e'"        | 指数表記の浮動小数点数 (小文字)。                     | (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'"        | Bytes (converts any Python object using               | (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 への % 書式化の追加

バージョン 3.5 で追加.


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

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

class memoryview(object)

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

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

   メモリビューの長さ "len(view)" は、 "tolist" で得られるリストの長さ
   となります。"view.ndim = 0" なら、長さは 1 です。"view.ndim = 1" な
   ら、長さはビューの要素数と等しいです。より高次元では、長さはビュー
   のネストされたリスト表現の長さと等しいです。要素一つあたりのバイト
   数は "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" にはいくつかのメソッドがあります:

   __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=None)

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

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

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

      バージョン 3.8 で追加: *order* can be {'C', 'F', 'A'}.  When
      *order* is 'C' or 'F', the data of the original array is
      converted to C or Fortran order. For contiguous views, 'A'
      returns an exact copy of the physical memory. In particular, in-
      memory Fortran order is preserved. For non-contiguous views, the
      data is converted to C first. *order=None* is the same as
      *order='C'*.

   hex([sep[, bytes_per_sep]])

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

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

      バージョン 3.5 で追加.

      バージョン 3.8 で変更: Similar to "bytes.hex()",
      "memoryview.hex()" now supports optional *sep* and
      *bytes_per_sep* parameters to insert separators between bytes in
      the hex output.

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

      Return a readonly version of the memoryview object.  The
      original memoryview object is unchanged.

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

      バージョン 3.8 で追加.

   release()

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

      このメソッドが呼ばれた後、このビュー上のそれ以上の演算は
      "ValueError" を送出します (複数回呼ばれえる "release()" 自身は除
      きます):

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

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

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

      バージョン 3.2 で追加.

   cast(format[, shape])

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

      キャスト後のフォーマットは "struct" 文法の単一要素ネイティブフォ
      ーマットに制限されます。フォーマットのうちの一つはバイトフォーマ
      ット ('B', 'b', 'c') でなければなりません。結果のバイト長はオリ
      ジナルの長さと同じでなければなりません。

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

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

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

         >>> b = bytearray(b'zyz')
         >>> x = memoryview(b)
         >>> x[0] = b'a'
         Traceback (most recent call last):
           File "<stdin>", line 1, in <module>
         ValueError: memoryview: invalid value for format "B"
         >>> y = x.cast('c')
         >>> y[0] = b'a'
         >>> b
         bytearray(b'ayz')

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

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

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

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

      バージョン 3.3 で追加.

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

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

   obj

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

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

      バージョン 3.3 で追加.

   nbytes

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

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

      多次元配列:

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

      バージョン 3.3 で追加.

   readonly

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

   format

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

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

   itemsize

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

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

   ndim

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

   shape

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

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

   strides

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

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

   suboffsets

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

   c_contiguous

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

      バージョン 3.3 で追加.

   f_contiguous

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

      バージョン 3.3 で追加.

   contiguous

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

      バージョン 3.3 で追加.


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

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

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

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

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

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

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

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

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

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

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

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

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

   len(s)

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

   x in s

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

   x not in s

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

   isdisjoint(other)

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

   issubset(other)
   set <= other

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

   set < other

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

   issuperset(other)
   set >= other

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

   set > other

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

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

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

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

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

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

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

   symmetric_difference(other)
   set ^ other

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

   copy()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   symmetric_difference_update(other)
   set ^= other

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

   add(elem)

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

   remove(elem)

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

   discard(elem)

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

   pop()

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

   clear()

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

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

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


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

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

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

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

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

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

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

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

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

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

   list(d)

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

   len(d)

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

   d[key]

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

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

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

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

   d[key] = value

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

   del d[key]

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

   key in d

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

   key not in d

      "not key in d" と等価です。

   iter(d)

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

   clear()

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

   copy()

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

   classmethod fromkeys(iterable[, value])

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

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

   get(key[, default])

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

   items()

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

   keys()

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

   pop(key[, default])

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

   popitem()

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

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

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

   reversed(d)

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

      バージョン 3.8 で追加.

   setdefault(key[, default])

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

   update([other])

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

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

   values()

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

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

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

   d | other

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

      バージョン 3.9 で追加.

   d |= other

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

      バージョン 3.9 で追加.

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

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

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

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

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

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

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

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


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

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

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

len(dictview)

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

iter(dictview)

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

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

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

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

x in dictview

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

reversed(dictview)

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

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

キーのビューは、項目が一意的でハッシュ可能であるという点で、集合に似て
います。すべての値がハッシュ可能なら、 "(key, value)" 対も一意的でハッ
シュ可能なので、要素のビューも集合に似ています。(値のビューは、要素が
一般に一意的でないことから、集合に似ているとは考えられません。) 集合に
似ているビューに対して、抽象基底クラス "collections.abc.Set" で定義さ
れている全ての演算 (例えば、 "=="、"<"、"^") が利用できます。

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

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

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

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

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

   >>> # set operations
   >>> keys & {'eggs', 'bacon', 'salad'}
   {'bacon'}
   >>> keys ^ {'sausage', 'juice'}
   {'juice', 'sausage', 'bacon', 'spam'}


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

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

contextmanager.__enter__()

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

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

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

contextmanager.__exit__(exc_type, exc_val, exc_tb)

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

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

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

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

Python's *generator*s and the "contextlib.contextmanager" decorator
provide a convenient way to implement these protocols.  If a generator
function is decorated with the "contextlib.contextmanager" decorator,
it will return a context manager implementing the necessary
"__enter__()" and "__exit__()" methods, rather than the iterator
produced by an undecorated generator function.

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


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

"GenericAlias" objects are generally created by subscripting a class.
They are most often used with container classes, such as "list" or
"dict". For example, "list[int]" is a "GenericAlias" object created by
subscripting the "list" class with the argument "int". "GenericAlias"
objects are intended primarily for use with *type annotations*.

注釈:

  It is generally only possible to subscript a class if the class
  implements the special method "__class_getitem__()".

A "GenericAlias" object acts as a proxy for a *generic type*,
implementing *parameterized generics*.

For a container class, the argument(s) supplied to a subscription of
the class may indicate the type(s) of the elements an object contains.
For example, "set[bytes]" can be used in type annotations to signify a
"set" in which all the elements are of type "bytes".

For a class which defines "__class_getitem__()" but is not a
container, the argument(s) supplied to a subscription of the class
will often indicate the return type(s) of one or more methods defined
on an object. For example, "regular expressions" can be used on both
the "str" data type and the "bytes" data type:

* If "x = re.search('foo', 'foo')", "x" will be a re.Match object
  where the return values of "x.group(0)" and "x[0]" will both be of
  type "str". We can represent this kind of object in type annotations
  with the "GenericAlias" "re.Match[str]".

* If "y = re.search(b'bar', b'bar')", (note the "b" for "bytes"), "y"
  will also be an instance of "re.Match", but the return values of
  "y.group(0)" and "y[0]" will both be of type "bytes". In type
  annotations, we would represent this variety of re.Match objects
  with "re.Match[bytes]".

"GenericAlias" objects are instances of the class
"types.GenericAlias", which can also be used to create "GenericAlias"
objects directly.

T[X, Y, ...]

   Creates a "GenericAlias" representing a type "T" parameterized by
   types *X*, *Y*, and more depending on the "T" used. For example, a
   function expecting a "list" containing "float" elements:

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

   Another example for *mapping* objects, using a "dict", which is a
   generic type expecting two type parameters representing the key
   type and the value type.  In this example, the function expects a
   "dict" with keys of type "str" and values of type "int":

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

The builtin functions "isinstance()" and "issubclass()" do not accept
"GenericAlias" types for their second argument:

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

The Python runtime does not enforce *type annotations*. This extends
to generic types and their type parameters. When creating a container
object from a "GenericAlias", the elements in the container are not
checked against their type. For example, the following code is
discouraged, but will run without errors:

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

Furthermore, parameterized generics erase type parameters during
object creation:

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

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

Calling "repr()" or "str()" on a generic shows the parameterized type:

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

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

The "__getitem__()" method of generic containers will raise an
exception to disallow mistakes like "dict[str][str]":

   >>> dict[str][str]
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   TypeError: There are no type variables left in dict[str]

However, such expressions are valid when type variables are used.  The
index must have as many elements as there are type variable items in
the "GenericAlias" object's "__args__".

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


Standard Generic Classes
------------------------

The following standard library classes support parameterized generics.
This list is non-exhaustive.

* "tuple"

* "list"

* "dict"

* "set"

* "frozenset"

* "type"

* "collections.deque"

* "collections.defaultdict"

* "collections.OrderedDict"

* "collections.Counter"

* "collections.ChainMap"

* ’’"collections.abc.Awaitable"

* "collections.abc.Coroutine"

* "collections.abc.AsyncIterable"

* "collections.abc.AsyncIterator"

* "collections.abc.AsyncGenerator"

* "collections.abc.Iterable"

* "collections.abc.Iterator"

* "collections.abc.Generator"

* "collections.abc.Reversible"

* "collections.abc.Container"

* "collections.abc.Collection"

* "collections.abc.Callable"

* "collections.abc.Set"

* "collections.abc.MutableSet"

* "collections.abc.Mapping"

* "collections.abc.MutableMapping"

* "collections.abc.Sequence"

* "collections.abc.MutableSequence"

* "collections.abc.ByteString"

* "collections.abc.MappingView"

* "collections.abc.KeysView"

* "collections.abc.ItemsView"

* "collections.abc.ValuesView"

* "contextlib.AbstractContextManager"

* "contextlib.AbstractAsyncContextManager"

* "dataclasses.Field"

* "functools.cached_property"

* "functools.partialmethod"

* "os.PathLike"

* "queue.LifoQueue"

* "queue.Queue"

* "queue.PriorityQueue"

* "queue.SimpleQueue"

* re.Pattern

* re.Match

* "shelve.BsdDbShelf"

* "shelve.DbfilenameShelf"

* "shelve.Shelf"

* "types.MappingProxyType"

* "weakref.WeakKeyDictionary"

* "weakref.WeakMethod"

* "weakref.WeakSet"

* "weakref.WeakValueDictionary"


Special Attributes of "GenericAlias" objects
--------------------------------------------

All parameterized generics implement special read-only attributes.

genericalias.__origin__

   This attribute points at the non-parameterized generic class:

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

genericalias.__args__

   This attribute is a "tuple" (possibly of length 1) of generic types
   passed to the original "__class_getitem__()" of the generic class:

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

genericalias.__parameters__

   This attribute is a lazily computed tuple (possibly empty) of
   unique type variables found in "__args__":

      >>> from typing import TypeVar

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

参考:

  **PEP 484** - Type Hints
     Introducing Python's framework for type annotations.

  **PEP 585** - Type Hinting Generics In Standard Collections
     Introducing the ability to natively parameterize standard-library
     classes, provided they implement the special class method
     "__class_getitem__()".

  ジェネリクス, user-defined generics and "typing.Generic"
     Documentation on how to implement generic classes that can be
     parameterized at runtime and understood by static type-checkers.

バージョン 3.9 で追加.


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

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

インスタンスを通してメソッド (クラスの名前空間内で定義された関数) にア
クセスすると、特殊なオブジェクトが得られます。それは束縛メソッド
(*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)" の呼び
出しと完全に等価です。

関数オブジェクトと同様に、メソッドオブジェクトは任意の属性の取得をサポ
ートしています。しかし、メソッド属性は実際には下層の関数オブジェクト
("meth.__func__") に記憶されているので、バインドされるメソッドにメソッ
ド属性を設定することは許されていません。メソッドに属性を設定しようとす
ると "AttributeError" が送出されます。メソッドの属性を設定するためには
、次のようにその下層の関数オブジェクトに明示的に設定する必要があります
:

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

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


コードオブジェクト
------------------

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

"__code__" へのアクセスは "object.__getattr__" に "obj" と
""__code__"" を渡して行いますが、 監査イベント を送出します。

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

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


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

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

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


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

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

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


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

このオブジェクトは一般にスライシングによって使われます (スライス表記
(slicing) を参照してください)。特殊な演算は何もサポートしていません。
Ellipsis オブジェクトは一つだけで、その名前は "Ellipsis" (組み込み名)
です。"type(Ellipsis)()" は単一の "Ellipsis" を作成します。

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


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

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

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


ブール値
--------

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

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


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

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


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

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

object.__dict__

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

instance.__class__

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

class.__bases__

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

definition.__name__

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

definition.__qualname__

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

   バージョン 3.3 で追加.

class.__mro__

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

class.mro()

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

class.__subclasses__()

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

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


Integer string conversion length limitation
===========================================

CPython has a global limit for converting between "int" and "str" to
mitigate denial of service attacks. This limit *only* applies to
decimal or other non-power-of-two number bases. Hexadecimal, octal,
and binary conversions are unlimited. The limit can be configured.

The "int" type in CPython is an arbitrary length number stored in
binary form (commonly known as a "bignum"). There exists no algorithm
that can convert a string to a binary integer or a binary integer to a
string in linear time, *unless* the base is a power of 2. Even the
best known algorithms for base 10 have sub-quadratic complexity.
Converting a large value such as "int('1' * 500_000)" can take over a
second on a fast CPU.

Limiting conversion size offers a practical way to avoid
CVE-2020-10735.

The limit is applied to the number of digit characters in the input or
output string when a non-linear conversion algorithm would be
involved.  Underscores and the sign are not counted towards the limit.

When an operation would exceed the limit, a "ValueError" is raised:

   >>> import sys
   >>> sys.set_int_max_str_digits(4300)  # Illustrative, this is the default.
   >>> _ = int('2' * 5432)
   Traceback (most recent call last):
   ...
   ValueError: Exceeds the limit (4300) 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) for integer string conversion: value has 8599 digits; use sys.set_int_max_str_digits() to increase the limit.
   >>> len(hex(i_squared))
   7144
   >>> assert int(hex(i_squared), base=16) == i*i  # Hexadecimal is unlimited.

The default limit is 4300 digits as provided in
"sys.int_info.default_max_str_digits". The lowest limit that can be
configured is 640 digits as provided in
"sys.int_info.str_digits_check_threshold".

Verification:

   >>> import sys
   >>> assert sys.int_info.default_max_str_digits == 4300, sys.int_info
   >>> assert sys.int_info.str_digits_check_threshold == 640, sys.int_info
   >>> msg = int('578966293710682886880994035146873798396722250538762761564'
   ...           '9252925514383915483333812743580549779436104706260696366600'
   ...           '571186405732').to_bytes(53, 'big')
   ...

バージョン 3.9.14 で追加.


Affected APIs
-------------

The limitation only applies to potentially slow conversions between
"int" and "str" or "bytes":

* "int(string)" with default base 10.

* "int(string, base)" for all bases that are not a power of 2.

* "str(integer)".

* "repr(integer)".

* any other string conversion to base 10, for example "f"{integer}"",
  ""{}".format(integer)", or "b"%d" % integer".

The limitations do not apply to functions with a linear algorithm:

* "int(string, base)" with base 2, 4, 8, 16, or 32.

* "int.from_bytes()" and "int.to_bytes()".

* "hex()", "oct()", "bin()".

* 書式指定ミニ言語仕様 for hex, octal, and binary numbers.

* "str" to "float".

* "str" to "decimal.Decimal".


Configuring the limit
---------------------

Before Python starts up you can use an environment variable or an
interpreter command line flag to configure the limit:

* "PYTHONINTMAXSTRDIGITS", e.g. "PYTHONINTMAXSTRDIGITS=640 python3" to
  set the limit to 640 or "PYTHONINTMAXSTRDIGITS=0 python3" to disable
  the limitation.

* "-X int_max_str_digits", e.g. "python3 -X int_max_str_digits=640"

* "sys.flags.int_max_str_digits" contains the value of
  "PYTHONINTMAXSTRDIGITS" or "-X int_max_str_digits". If both the env
  var and the "-X" option are set, the "-X" option takes precedence. A
  value of *-1* indicates that both were unset, thus a value of
  "sys.int_info.default_max_str_digits" was used during
  initialization.

From code, you can inspect the current limit and set a new one using
these "sys" APIs:

* "sys.get_int_max_str_digits()" and "sys.set_int_max_str_digits()"
  are a getter and setter for the interpreter-wide limit.
  Subinterpreters have their own limit.

Information about the default and minimum can be found in
"sys.int_info":

* "sys.int_info.default_max_str_digits" is the compiled-in default
  limit.

* "sys.int_info.str_digits_check_threshold" is the lowest accepted
  value for the limit (other than 0 which disables it).

バージョン 3.9.14 で追加.

ご用心:

  Setting a low limit *can* lead to problems. While rare, code exists
  that contains integer constants in decimal in their source that
  exceed the minimum threshold. A consequence of setting the limit is
  that Python source code containing decimal integer literals longer
  than the limit will encounter an error during parsing, usually at
  startup time or import time or even at installation time - anytime
  an up to date ".pyc" does not already exist for the code. A
  workaround for source that contains such large constants is to
  convert them to "0x" hexadecimal form as it has no limit.Test your
  application thoroughly if you use a low limit. Ensure your tests run
  with the limit set early via the environment or flag so that it
  applies during startup and even during any installation step that
  may invoke Python to precompile ".py" sources to ".pyc" files.


Recommended configuration
-------------------------

The default "sys.int_info.default_max_str_digits" is expected to be
reasonable for most applications. If your application requires a
different limit, set it from your main entry point using Python
version agnostic code as these APIs were added in security patch
releases in versions before 3.11.

Example:

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

If you need to disable it entirely, set it to "0".

-[ 脚注 ]-

[1] これらの特殊なメソッドのさらなる情報については、 Python リファレン
    スマニュアル (基本的なカスタマイズ) を参照してください。

[2] この結果として、リスト "[1, 2]" は "[1.0, 2.0]" と等しいと見なされ
    ます。タプルの場合も同様です。

[3] パーザが演算対象の型を識別できるようにするために、このような優先順
    位でなければならないのです。

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

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