### ナビゲーション

- 索引
- モジュール |
- 次へ |
- 前へ |
- Python 2.7ja1 documentation »
- Python 標準ライブラリ »
- 7. 文字列処理 »

# 7.1. `string` — 一般的な文字列操作

`string` モジュールには便利な定数やクラスが数多く入っています。また、現在は文字列のメソッドとして利用できる、すでに撤廃された古い関数も入っています。さらに、 Python の組み込み文字列クラスは シーケンス型 — str, unicode, list, tuple, bytearray, buffer, xrange 節に記載のシーケンス型のメソッドと、 文字列メソッド 節に記載の文字列メソッドもサポートします。出力の書式指定には、テンプレート文字列、または、 文字列フォーマット操作 に記載の `%` 演算子を使用して下さい。正規表現に関する文字列操作の関数は `re` を参照してください。

参考

最新のバージョンの string モジュール Python ソースコード

## 7.1.1. 文字列定数

このモジュールでは以下の定数を定義しています。

`string.``ascii_letters`

  後述の `ascii_lowercase` と `ascii_uppercase` を合わせたもの。この値はロケールに依存しません。

`string.``ascii_lowercase`

  小文字 `'abcdefghijklmnopqrstuvwxyz'` 。この値はロケールに依存せず、固定です。

`string.``ascii_uppercase`

  大文字 `'ABCDEFGHIJKLMNOPQRSTUVWXYZ'` 。この値はロケールに依存せず、固定です。

`string.``digits`

  文字列 `'0123456789'` です。

`string.``hexdigits`

  文字列 `'0123456789abcdefABCDEF'` です。

`string.``letters`

  後述の `lowercase` と `uppercase` を合わせた文字列です。具体的な値はロケールに依存しており、 `locale.setlocale()` が呼ばれたときに更新されます。

`string.``lowercase`

  小文字として扱われる文字全てを含む文字列です。ほとんどのシステムでは文字列 `'abcdefghijklmnopqrstuvwxyz'` です。具体的な値はロケールに依存しており、 `locale.setlocale()` が呼ばれたときに更新されます。

`string.``octdigits`

  文字列 `'01234567'` です。

`string.``punctuation`

  `C` ロケールにおいて、句読点として扱われる ASCII 文字の文字列です。

`string.``printable`

  印刷可能な文字で構成される文字列です。 `digits`, `letters`, `punctuation` および `whitespace` を組み合わせたものです。

`string.``uppercase`

  大文字として扱われる文字全てを含む文字列です。ほとんどのシステムでは `'ABCDEFGHIJKLMNOPQRSTUVWXYZ'` です。具体的な値はロケールに依存しており、 `locale.setlocale()` が呼ばれたときに更新されます。

`string.``whitespace`

  空白 (whitespace) として扱われる文字全てを含む文字列です。ほとんどのシステムでは、これはスペース (space)、タブ (tab)、改行 (linefeed)、復帰 (return)、改頁 (formfeed)、垂直タブ (vertical tab) です。

## 7.1.2. 文字列の書式指定

バージョン 2.6 で追加.

組み込みの str 、および、 unicode クラスは、 PEP 3101 に記載される `str.format()` メソッドによる、複雑な変数置換と値の書式指定を提供します。 `string` モジュールの `Formatter` クラスは組み込みの `format()` メソッドと同じ実装で、文字列の書式指定の作成とカスタマイズを可能にします。

class `string.``Formatter`

  `Formatter` クラスは、以下のメソッドを持ちます。 :

  `format`(format_string, *args, **kwargs)

    `format()` は主たる API メソッドです。引数は、書式指定テンプレート文字列、および、任意のポジション、キーワード引数をとります。 `format()` は、 `vformat()` を呼び出すだけのラッパーです。

  `vformat`(format_string, args, kwargs)

    この関数は、書式指定の操作を行います。 `*args` や `**kwds` を使った書式で辞書をアンパックやリパックするのではなく、予め定義された辞書を引数として与えたいときなどでは、独立した関数として露出されます。 `vformat()` は書式テンプレート文字列を、文字データや置換フィールドに展開します。この関数は、以下の様々なメソッドを呼び出します。

  付け加えると、 `Formatter` はサブクラスで置き換えるためのいくつかのメソッドを定義します。 :

  `parse`(format_string)

    format_stringを探査し、タプル、 (literal_text, field_name, format_spec, conversion) のイテラブルを返します。これは `vformat()` が文字列を文字としての文字データや置換フィールドに展開するために使用されます。

    タプルの値は、概念的に文字としての文字データと、それに続く単一の置換フィールドを表現します。文字としての文字データが無い場合は (ふたつの置換フィールドが連続した場合などに起き得ます) 、 literal_text は長さが 0 の文字列となります。置換フィールドが無い場合は、 field_name, format_spec および conversion が `None` となります。

  `get_field`(field_name, args, kwargs)

    引数として与えた `parse()` (上記参照) により返される field_name を書式指定対象オブジェクトに変換します。返り値はタプル、 (obj, used_key) です。デフォルトでは PEP 3101 に規定される “0[name]” や “label.title” のような形式の文字列を引数としてとります。 args と kwargs は `vformat()` に渡されます。返り値 used_key は、 `get_value()` の key 引数と同じ意味を持ちます。

  `get_value`(key, args, kwargs)

    与えられたフィールドの値を取り出します。 key 引数は整数でも文字列でも構いません。整数の場合は、ポジション引数 args のインデックス番号を示します。文字列の場合は、名前付きの引数 kwargs を意味します。

    args 引数は、 `vformat()` へのポジション引数のリストに設定され、 kwargs 引数は、キーワード引数の辞書に設定されます。

    複合したフィールド名に対しては、これらの関数はフィールド名の最初の要素に対してのみ呼び出されます ; あとに続く要素は通常の属性、および、インデックス処理へと渡されます。

    つまり、例えば、フィールドが ‘0.name’ と表現されるとき、 `get_value()` は、 key 引数が 0 として呼び出されます。属性 `name` は、組み込みの `getattr()` 関数が呼び出され、 `get_value()` が返されたのちに検索されます。

    もし、インデックス、もしくは、キーワードが存在しないアイテムを参照したら、 `IndexError` 、もしくは、 `KeyError` が送出されます。

  `check_unused_args`(used_args, args, kwargs)

    希望に応じ、未使用の引数がないか確認する機能を実装します。この関数への引数は、書式指定文字列で参照される全てのキー引数の set 、 (ポジション引数への整数、名前付き引数への文字列) 、そして vformat に渡される args と kwargs への参照です。使用されない引数の set は、それらのパラメータから計算されます。 `check_unused_args()` は、確認の結果が偽であると、例外を送出するものとみなされます。

  `format_field`(value, format_spec)

    `format_field()` は単純に組み込みのグローバル関数 `format()` を呼び出します。このメソッドは、サブクラスをオーバーライドするために提供されます。

  `convert_field`(value, conversion)

    (`get_field()` が返す) 値を、与えられた conversion 型に (`parse()` がタプルを返すように) 変換します。デフォルトでは ‘r’(repr) と ‘s’(str) 変換型を解釈できます。

## 7.1.3. 書式指定文字列の文法

`str.format()` メソッドと、 `Formatter` クラスは、文字列の書式指定に同じ文法を共有します (しかしながら、 `Formatter` サブクラスの場合、それ自身の書式指定文法を定義することが可能です) 。

書式指定文字列は波括弧 `{}` に囲まれた “置換フィールド” を含みます。波括弧に囲まれた部分以外は全て単純な文字として扱われ、変更を加えることなく出力へコピーされます。波括弧を文字として扱う必要がある場合は、二重にすることでエスケープすることができます: `{{` および `}}`

置換フィールドの文法は以下です:

>     replacement_field ::=  "{" [field_name] ["!" conversion] [":" format_spec] "}"
>     field_name        ::=  arg_name ("." attribute_name | "[" element_index "]")*
>     arg_name          ::=  [identifier | integer]
>     attribute_name    ::=  identifier
>     element_index     ::=  integer | index_string
>     index_string      ::=  <any source character except "]"> +
>     conversion        ::=  "r" | "s"
>     format_spec       ::=  <described in the next section>

もっと簡単にいうと、置換フィールドは field_name で始められます。これによって指定したオブジェクトの値が、置換フィールドの代わりに書式化され出力に挿入されます。その後に、感嘆符 `'!'` を挟んで conversion フィールドを続けることができます。最後にコロン `':'` を挟んで、 format_spec を書くことができます。これは、置換される値の非デフォルトの書式を指定します。

書式指定ミニ言語仕様 (Format Specification Mini-Language) 節も参照して下さい。

field_name 自体は、数字かキーワードである arg_name で始まります。数字である場合、ポジション引数を参照します。キーワードである場合、指名されたキーワード引数を参照します。書式指定文字列中の数の arg_name が 0, 1, 2, ... と並んでいるなら、これらは (一部ではなく) すべて省略でき、数 0, 1, 2, ... がその順に自動的に挿入されます。 arg_name の後に数字インデックスや属性式を続けることができます。 `'.name'` 形式の式の場合、 `getattr()` 使って指名された属性が選択され、 `'[index]'` 形式の式の場合、 `__getitem__()` を使ってインデックス検索されます。

バージョン 2.7 で変更: ポジション引数指定子は省略できるようになりました。 `'{} {}'` は `'{0} {1}'` と等価です。

簡単な書式指定文字列の例を挙げます:

    "First, thou shalt count to {0}" # 最初のポジション引数を参照します
    "Bring me a {}"                  # 暗示的に第一ポジション引数を参照します
    "From {} to {}"                  # "From {0} to {1}" と同じです
    "My quest is {name}"             # キーワード引数 'name' を参照します
    "Weight in tons {0.weight}"      # 最初のポジション引数の属性 'weight' を参照します
    "Units destroyed: {players[0]}"  # キーワード引数 'players' の最初の要素を参照します

置換 (conversion) フィールドにより書式変換前に型の強制変換が実施されます。通常、値の書式変換は `__format__()` によって実施されます。しかしながら、場合によっては、文字列として変換することを強制したり、書式指定の定義をオーバーライドしたくなることもあります。 `__format__()` の呼び出し前に値を文字列に変換すると、通常の書式変換の処理は飛ばされます。

現時点では、二種類の変換フラグがサポートされています: 値に対して `str()` を呼び出す `'!s'` と、 `repr()` を呼び出す `'!r'` です。

例:

    "Harold's a clever {0!s}"        # 引数に対して、最初に str() を呼び出します
    "Bring out the holy {name!r}"    # 引数に対して、最初に repr() を呼び出します

format_spec フィールドは、フィールド幅、文字揃え、埋め方、精度などの、値を表現する仕様を含みます。それぞれの値の型は、 “formatting mini-language” 、または、 format_spec の実装で定義されます。

ほとんどの組み込み型は、共通の次のセクションに記載の formatting mini-language をサポートします。

format_spec フィールドは入れ子になった置換フィールドを含むこともできます。入れ子になった置換フィールドはフィールド名だけを含むことができます; 変換フラグや書式指定は不可です。 format_spec 中の置換フィールドは format_spec 文字列が解釈される前に置き換えられます。これにより、値の書式動的に指定することが可能になります。

書式指定例 のいくつかの例も参照して下さい。

### 7.1.3.1. 書式指定ミニ言語仕様 (Format Specification Mini-Language)

書式指定 (“Format specifications”) は書式指定文字列の個々の値を表現する方法を指定するための、置換フィールドで使用されます (書式指定文字列の文法 を参照下さい) 。それらは、組み込み関数の `format()` 関数に直接渡されます。それぞれの書式指定可能な型について、書式指定がどのように解釈されるかが規定されます。

多くの組み込み型は、書式指定に関して以下のオプションを実装します。しかしながら、いくつかの書式指定オプションは数値型でのみサポートされます。

一般的な取り決めとして、空の書式指定文字列 (`""`) は、値に対して `str()` を呼び出したときと同じ結果を与えます。通常、空でない書式指定文字列はその結果を変更します。

一般的な書式指定子 (standard format specifier) の書式は以下です:

    format_spec   ::=  [[fill]align][sign][#][0][width][,][.precision][type]
    fill(詰め方)     ::=  <'}'以外の文字>
    align(整列)     ::=  "<" | ">" | "=" | "^"
    sign(符号)      ::=  "+" | "-" | " "
    width(幅)      ::=  整数
    precision(精度) ::=  整数
    type          ::=  "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"

fill 文字は、’{‘ と ‘}’ 以外のどんな文字でもかまいません。 fill 文字があることは、 align オプションが続くことで示されます。もし、 format_spec の二つめの文字が align オプションで無い場合は、 fill と align の両方のオプションが無いものと解釈されます。

様々な align オプションの意味は以下のとおりです :

> オプション | 意味
> --- | ---
> `'<'` | 利用可能なスペースにおいて、左詰めを強制します。 (ほとんどのオブジェクトにおいてのデフォルト)
> `'>'` | 利用可能なスペースにおいて、右詰めを強制します。 (いくつかのオブジェクトにおいてのデフォルト)
> `'='` | 符号 (があれば) の後ろを埋めます。 ‘+000000120’ のような形で表示されます。このオプションは数値型に対してのみ有効です。
> `'^'` | 資料可能なスペースにおいて、中央寄せを強制します。

最小のフィールド幅が定義されない限り、フィールド幅はデータを表示するために必要な幅と同じになることに注意して下さい。そのため、その場合には、 align オプションは意味を持ちません。

sign オプションは数値型に対してのみ有効ですであり、以下のうちのひとつとなります :

> オプション | 意味
> --- | ---
> `'+'` | 符号の使用を、正数、負数の両方に対して指定します。
> `'-'` | 符号の使用を、負数に対してのみ指定します。 (デフォルトの挙動です)
> 空白 | 空白を正数の前に付け、負号を負数の前に使用することを指定します。

`'#'` オプションは、整数、かつ、2進数、8進数、16進数の出力に対してのみ有効です。指定されれば、出力は、 `'0b'`, `'0o'`, もしくは `'0x'`, のプリフィックスが付与されます。

`','` オプションは、千の位のセパレータにカンマを使うことを合図します。ロケール依存のセパレータには、代わりに `'n'` の整数表現形式を使ってください。

バージョン 2.7 で変更: `','` オプションを追加しました (PEP 378 も参照してください)。

width は10進数の整数で、最小のフィールド幅を規程します。もし指定されなければ、フィールド幅は内容により規程されます。

もし width フィールドがゼロ (`'0'`) で始まる場合、ゼロ埋めとなります。これは、 alignment 型が `'='` で、 fill 文字が `'0'` であることと等価です。

precision は10進数で、 `'f'` および `'F'` 、あるいは、 `'g'` および `'G'` で指定される浮動小数点数の、小数点以下に続く桁数を指定します。非数型に対しては、最大フィールド幅を規程します。言い換えると、フィールドの内容から、何文字使用するかを規程します。 precision は整数型に対しては、許されません。

最後に、 type は、データがどのように表現されるかを規程します。

利用可能な文字列の表現型は以下です：

> 型 | 意味
> --- | ---
> `'s'` | 文字列。デフォルトの値で多くの場合省略されます
> 空白 | `'s'` と同じです。

利用可能な整数の表現型は以下です :

> 型 | 意味
> --- | ---
> `'b'` | 2進数。出力される数値は2を基数とします。
> `'c'` | 文字。数値を対応するユニコード文字に変換します。
> `'d'` | 10進数。出力される数値は10を基数とします。
> `'o'` | 8進数。出力される数値は8を基数とします。
> `'x'` | 16進数。出力される数値は16を基数とします。 10進で9を越える数字には小文字が使われます。
> `'X'` | 16進数。出力される数値は16を基数とします。 10進で9を越える数字には大文字が使われます。
> `'n'` | 数値。現在のロケールに従い、区切り文字を挿入することを除けば、 `'d'` と同じです。
> 空白 | `'d'` と同じです。

これらの表現型に加えて、整数は (`'n'` と空白を除く) 以下の浮動小数点型の表現型で書式指定できます。そうすることで整数は書式変換される前に `float()` を使って浮動小数点数に変換されます。

利用可能な浮動小数点数と10進数の表現型は以下です :

> 型 | 意味
> --- | ---
> `'e'` | 指数指定です。指数を示す ‘e’ を使って数値を表示します。
> `'E'` | 指数指定です。大文字の ‘E’ を使うことを除いては、 `'e'` と同じです。
> `'f'` | 固定小数点数です。数値を固定小数点数として表示します。
> `'F'` | 固定小数点数です。 `'f'` と同じです。
> `'g'` | 標準フォーマットです。精度を `p >= 1` の数値で与えた場合、数値を有効桁 `p` で丸め、桁に応じて固定小数点か指数指定で表示します。 精度のルールは以下のように決まっています: 書式指定の結果が `'e'` 型で `p-1` の精度の場合、指数は `exp` になると仮定します。そうすると、 `-4 <= exp < p` のとき数値は表現型 `'f'` で精度 `p-1-exp` に書式変換されます。それ以外の場合、数値は `'e'` 型で精度 `p-1` に書式指定されます。この両方の場合で重要でない、連続した 0 は取り除かれます, そして残った桁が無い場合小数点は取り除かれます。 正と負の無限大と 0 および NaN は精度に関係なくそれぞれ `inf`, `-inf`, `0`, `-0` および `nan` となります。 `0` の精度は `1` の精度と同等に扱われます。
> `'G'` | 標準フォーマットです。数値が大きくなったとき、 `'E'` に切り替わることを除き、 `'g'` と同じです。無限大と NaN の表示も大文字になります。
> `'n'` | 数値です。現在のロケールに合わせて、数値分割文字が挿入されることを除き、 `'g'` と同じです。
> `'%'` | パーセンテージです。数値は 100 倍され、固定小数点数フォーマット (`'f'`) でパーセント記号付きで表示されます。
> None | `'g'` と同じです。

### 7.1.3.2. 書式指定例

この節には新しい書式指定構文と古い `%`-書式の比較例が載っています。

多くの場合、 `%` の代わりに `{}` を加えることで新構文は古い `%`-書式に類似した書式になります。例えば、 `'%03.2f'` は `'{:03.2f}'` に翻訳できます。

以下の例で示すように、新構文はさらに新たに様々なオプションもサポートしています、

ポジション引数を使ったアクセス:

    >>> '{0}, {1}, {2}'.format('a', 'b', 'c')
    'a, b, c'
    >>> '{}, {}, {}'.format('a', 'b', 'c')  # 2.7+ 専用
    'a, b, c'
    >>> '{2}, {1}, {0}'.format('a', 'b', 'c')
    'c, b, a'
    >>> '{2}, {1}, {0}'.format(*'abc')      # 引数シークエンスをアンパック
    'c, b, a'
    >>> '{0}{1}{0}'.format('abra', 'cad')   # 引数のインデクスは繰り返すことができます
    'abracadabra'

名前を使ったアクセス:

    >>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
    'Coordinates: 37.24N, -115.81W'
    >>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
    >>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
    'Coordinates: 37.24N, -115.81W'

引数の属性へのアクセス:

    >>> c = 3-5j
    >>> ('The complex number {0} is formed from the real part {0.real} '
    ...  'and the imaginary part {0.imag}.').format(c)
    'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
    >>> class Point(object):
    ...     def __init__(self, x, y):
    ...         self.x, self.y = x, y
    ...     def __str__(self):
    ...         return 'Point({self.x}, {self.y})'.format(self=self)
    ...
    >>> str(Point(4, 2))
    'Point(4, 2)'

引数の要素へのアクセス:

    >>> coord = (3, 5)
    >>> 'X: {0[0]};  Y: {0[1]}'.format(coord)
    'X: 3;  Y: 5'

`%s` と `%r` の置換:

    >>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
    "repr() shows quotes: 'test1'; str() doesn't: test2"

テキストの幅を指定した整列:

    >>> '{:<30}'.format('left aligned')
    'left aligned                  '
    >>> '{:>30}'.format('right aligned')
    '                 right aligned'
    >>> '{:^30}'.format('centered')
    '           centered           '
    >>> '{:*^30}'.format('centered')  # 詰め文字に '*' を使う
    '***********centered***********'

`%+f` と `%-f`, `% f` の置換、そして符号の指定:

    >>> '{:+f}; {:+f}'.format(3.14, -3.14)  # 常に表示する
    '+3.140000; -3.140000'
    >>> '{: f}; {: f}'.format(3.14, -3.14)  # 正の数にはスペースを表示
    ' 3.140000; -3.140000'
    >>> '{:-f}; {:-f}'.format(3.14, -3.14)  # マイナスだけを表示 -- '{:f}; {:f}' と同じ
    '3.140000; -3.140000'

`%x` と `%o` の置換、そして値に対する異なる底の変換:

    >>> # format also supports binary numbers
    >>> "int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}".format(42)
    'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
    >>> # with 0x, 0o, or 0b as prefix:
    >>> "int: {0:d};  hex: {0:#x};  oct: {0:#o};  bin: {0:#b}".format(42)
    'int: 42;  hex: 0x2a;  oct: 0o52;  bin: 0b101010'

千の位のセパレータにカンマを使用する:

    >>> '{:,}'.format(1234567890)
    '1,234,567,890'

パーセントを表示する:

    >>> points = 19.5
    >>> total = 22
    >>> 'Correct answers: {:.2%}.'.format(points/total)
    'Correct answers: 88.64%'

型特有の書式指定を使う:

    >>> import datetime
    >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
    >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
    '2010-07-04 12:15:58'

引数をネストする、さらに複雑な例:

    >>> for align, text in zip('<^>', ['left', 'center', 'right']):
    ...     '{:{align}{fill}16}'.format(text, fill=align, align=align)
    ...
    'left<<<<<<<<<<<<'
    '^^^^^center^^^^^'
    '>>>>>>>>>>>right'
    >>>
    >>> octets = [192, 168, 0, 1]
    >>> '{:0X}{:02X}{:02X}{:02X}'.format(*octets)
    'C0A80001'
    >>> int(_, 16)
    3232235521
    >>>
    >>> width = 5
    >>> for num in range(5,12):
    ...     for base in 'dXob':
    ...         print '{0:{width}{base}}'.format(num, base=base, width=width),
    ...     print
    ...
        5     5     5   101
        6     6     6   110
        7     7     7   111
        8     8    10  1000
        9     9    11  1001
       10     A    12  1010
       11     B    13  1011

## 7.1.4. テンプレート文字列

バージョン 2.4 で追加.

テンプレート (template) を使うと、 PEP 292 で解説されているようにより簡潔に文字列置換 (string substitution) を行えるようになります。通常の `%` ベースの置換に代わって、テンプレートでは以下のような規則に従った `$` ベースの置換をサポートしています:

- `$$` はエスケープ文字です; `$` 一つに置換されます。
- `$identifier` は置換プレースホルダの指定で、 `"identifier"` というキーへの対応付けに相当します。デフォルトは、 `"identifier"` の部分には Python の識別子が書かれていなければなりません。 `$` の後に識別子に使えない文字が出現すると、そこでプレースホルダ名の指定が終わります。
- `${identifier}` は `$identifier` と同じです。プレースホルダ名の後ろに識別子として使える文字列が続いていて、それをプレースホルダ名の一部として扱いたくない場合、例えば `"${noun}ification"` のような場合に必要な書き方です。

上記以外の書き方で文字列中に `$` を使うと `ValueError` を送出します。

`string` モジュールでは、上記のような規則を実装した `Template` クラスを提供しています。 `Template` のメソッドを以下に示します:

class `string.``Template`(template)

  コンストラクタはテンプレート文字列になる引数を一つだけ取ります。

  `substitute`(mapping[, **kws])

    テンプレート置換を行い、新たな文字列を生成して返します。 mapping はテンプレート中のプレースホルダに対応するキーを持つような任意の辞書類似オブジェクトです。辞書を指定する代わりに、キーワード引数も指定でき、その場合にはキーワードをプレースホルダ名に対応させます。 mapping と kws の両方が指定され、内容が重複した場合には、 kws に指定したプレースホルダを優先します。

  `safe_substitute`(mapping[, **kws])

    `substitute()` と同じですが、プレースホルダに対応するものを mapping や kws から見つけられなかった場合に、 `KeyError` 例外を送出する代わりにもとのプレースホルダがそのまま入ります。また、 `substitute()` とは違い、規則外の書き方で `$` を使った場合でも、 `ValueError` を送出せず単に `$` を返します。

    その他の例外も発生し得る一方で、このメソッドが「安全 (safe) 」と呼ばれているのは、置換操作が常に例外を送出する代わりに利用可能な文字列を返そうとするからです。別の見方をすれば、 `safe_substitute()` は区切り間違いによるぶら下がり (dangling delimiter) や波括弧の非対応、 Python の識別子として無効なプレースホルダ名を含むような不正なテンプレートを何も警告せずに無視するため、安全とはいえないのです。

  `Template` のインスタンスは、次のような public な属性を提供しています:

  `template`

  コンストラクタの引数 template に渡されたオブジェクトです。通常、この値を変更すべきではありませんが、読み込み専用アクセスを強制しているわけではありません。

Templateの使い方の例を以下に示します:

    >>> from string import Template
    >>> s = Template('$who likes $what')
    >>> s.substitute(who='tim', what='kung pao')
    'tim likes kung pao'
    >>> d = dict(who='tim')
    >>> Template('Give $who $100').substitute(d)
    Traceback (most recent call last):
    [...]
    ValueError: Invalid placeholder in string: line 1, col 10
    >>> Template('$who likes $what').substitute(d)
    Traceback (most recent call last):
    [...]
    KeyError: 'what'
    >>> Template('$who likes $what').safe_substitute(d)
    'tim likes $what'

さらに進んだ使い方: `Template` のサブクラスを派生して、プレースホルダの書式、区切り文字、テンプレート文字列の解釈に使われている正規表現全体をカスタマイズできます。こうした作業には、以下のクラス属性をオーバライドします:

- delimiter – プレースホルダの開始を示すリテラル文字列です。デフォルトの値は `$` です。実装系はこの文字列に対して必要に応じて `re.escape()` を呼び出すので、正規表現を表すような文字列にしては なりません 。
- idpattern – 波括弧でくくらない形式のプレースホルダの表記パターンを示す正規表現です (波括弧は自動的に適切な場所に追加されます)　。デフォルトの値は `[_a-z][_a-z0-9]*` という正規表現です。

他にも、クラス属性 pattern をオーバライドして、正規表現パターン全体を指定できます。オーバライドを行う場合、 pattern の値は 4 つの名前つきキャプチャグループ (capturing group) を持った正規表現オブジェクトでなければなりません。これらのキャプチャグループは、上で説明した規則と、無効なプレースホルダに対する規則に対応しています:

- escaped – このグループはエスケープシーケンス、すなわちデフォルトパターンにおける `$$` に対応します。
- named – このグループは波括弧でくくらないプレースホルダ名に対応します; キャプチャグループに区切り文字を含めてはなりません。
- braced – このグループは波括弧でくくったプレースホルダ名に対応します; キャプチャグループに区切り文字を含めてはなりません。
- invalid – このグループはそのほかの区切り文字のパターン (通常は区切り文字一つ) に対応し、正規表現の末尾に出現せねばなりません。

## 7.1.5. 文字列操作関数

以下の関数は文字列または Unicode オブジェクトを操作できます。これらの関数は文字列型のメソッドにはありません。

`string.``capwords`(s[, sep])

  `split()` を使って引数を単語に分割し、 `capitalize()` を使ってそれぞれの単語の先頭の文字を大文字に変換し、 `join()` を使ってつなぎ合わせます。オプションの第2引数 sep が与えられないか `None` の場合、この置換処理は文字列中の連続する空白文字をスペース一つに置き換え、先頭と末尾の空白を削除します、それ以外の場合には sep は split と join に使われます。

`string.``maketrans`(from, to)

  `translate()` に渡すのに適した変換テーブルを返します。このテーブルは、 from 内の各文字を to の同じ位置にある文字に対応付けます; from と to は同じ長さでなければなりません。

  ノート

  `lowercase` と `uppercase` から取り出した文字列を引数に使ってはなりません; ロケールによっては、これらは同じ長さになりません。大文字小文字の変換には、常に `str.lower()` または `str.upper()` を使ってください。

## 7.1.6. 撤廃された文字列関数

以下の一連の関数は、文字列型や Unicode 型のオブジェクトのメソッドとしても定義されています; 詳しくは、それらの 文字列メソッド の項を参照してください。ここに挙げた関数は Python 3.0 で削除されることはないはずですが、撤廃された関数とみなして下さい。このモジュールで定義されている関数は以下の通りです:

`string.``atof`(s)

  バージョン 2.0 で撤廃: 組み込み関数 `float()` を使ってください。

  文字列を浮動小数点型の数値に変換します。文字列は Python における標準的なの浮動小数点リテラルの文法に従っていなければなりません。先頭に符号 (`+` または `-`)が付くのは構いません。この関数に文字列を渡した場合は、組み込み関数 `float()` と同じように振舞います。

  ノート

  文字列を渡した場合、根底にある C ライブラリによって NaN や Infinity を返す場合があります。こうした値を返させるのがどんな文字列の集合であるかは、全て C ライブラリに依存しており、ライブラリによって異なると知られています。

`string.``atoi`(s[, base])

  バージョン 2.0 で撤廃: 組み込み関数 `int()` を使ってください。

  文字列 s を、 base を基数とする整数に変換します。文字列は 1 桁またはそれ以上の数字からなっていなければなりません。先頭に符号 (`+` または `-`) が付くのは構いません。 base のデフォルト値は 10 です。 base が 0 の場合、 (符号を剥ぎ取った後の) 文字列の先頭にある文字列に従ってデフォルトの基数を決定します。 `0x` か `0X` なら 16 、 `0` なら 8 、その他の場合は 10 が基数になります。 base が 16 の場合、先頭の `0x` や `0X` が付いていても受け付けますが、必須ではありません。文字列を渡す場合、この関数は組み込み関数 `int()` と同じように振舞います。 (数値リテラルをより柔軟に解釈したい場合には、組み込み関数 `eval()` を使ってください。)

`string.``atol`(s[, base])

  バージョン 2.0 で撤廃: 組み込み関数 `long()` を使ってください。

  文字列 s を、 base を基数とする長整数に変換します。文字列は 1 桁またはそれ以上の数字からなっていなければなりません。先頭に符号 (`+` または `-`) が付くのは構いません。 base は `atoi()` と同じ意味です。基数が 0 の場合を除き、文字列末尾に `l` や `L` を付けてはなりません。 base を指定しないか、 10 を指定して文字列を渡した場合には、この関数は組み込み関数 `long()` と同じように振舞います。

`string.``capitalize`(word)

  先頭文字だけ大文字にした word のコピーを返します。

`string.``expandtabs`(s[, tabsize])

  現在のカラムと指定タブ幅に従って文字列中のタブを展開し、一つまたはそれ以上のスペースに置き換えます。文字列中に改行が出現するたびにカラム番号は 0 にリセットされます。この関数は、他の非表示文字やエスケープシーケンスを解釈しません。タブ幅のデフォルトは 8 です。

`string.``find`(s, sub[, start[, end]])

  `s[start:end]` の中で、部分文字列 sub が完全な形で入っている場所のうち、最初のものを s のインデクスで返します。見つからなかった場合は `-1` を返します。 start と end のデフォルト値、および、負の値を指定した場合の解釈は文字列のスライスと同じです。

`string.``rfind`(s, sub[, start[, end]])

  `find()` と同じですが、最後に見つかったもののインデックスを返します。

`string.``index`(s, sub[, start[, end]])

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

`string.``rindex`(s, sub[, start[, end]])

  `rfind()` と同じですが、部分文字列が見つからなかったときに `ValueError` 送出します。

`string.``count`(s, sub[, start[, end]])

  `s[start:end]` における、部分文字列 sub の (重複しない) 出現回数を返します。 start と end のデフォルト値、および、負の値を指定した場合の解釈は文字列のスライスと同じです。

`string.``lower`(s)

  s のコピーを大文字を小文字に変換して返します。

`string.``split`(s[, sep[, maxsplit]])

  文字列 s 内の単語からなるリストを返します。オプションの第二引数 sep を指定しないか、または `None` にした場合、空白文字 (スペース、タブ、改行、リターン、改頁) からなる任意の文字列で単語に区切ります。 sep を `None` 以外の値に指定した場合、単語の分割に使う文字列の指定になります。戻り値のリストには、文字列中に分割文字列が重複せずに出現する回数より一つ多い要素が入るはずです。オプションの第三引数 maxsplit はデフォルトで 0 です。この値がゼロでない場合、最大でも maxsplit 回の分割しか行わず、リストの最後の要素は未分割の残りの文字列になります (従って、リスト中の要素数は最大でも `maxsplit+1` です)。

  空文字列に対する分割を行った場合の挙動は sep の値に依存します。 sep を指定しないか `None` にした場合、結果は空のリストになります。 sep に文字列を指定した場合、空文字列一つの入ったリストになります。

`string.``rsplit`(s[, sep[, maxsplit]])

  s 中の単語からなるリストを s の末尾から検索して生成し返します。関数の返す語のリストは全ての点で `split()` の返すものと同じになります。ただし、オプションの第三引数 maxsplit をゼロでない値に指定した場合には必ずしも同じにはなりません。 maxsplit がゼロでない場合には、最大で maxsplit 個の分割を 右端から 行います - 未分割の残りの文字列はリストの最初の要素として返されます (従って、リスト中の要素数は最大でも `maxsplit+1` です)。

  バージョン 2.4 で追加.

`string.``splitfields`(s[, sep[, maxsplit]])

  この関数は `split()` と同じように振舞います。 (以前は `split()` は単一引数の場合にのみ使い、 `splitfields()` は引数 2 つの場合でのみ使っていました)。

`string.``join`(words[, sep])

  単語のリストやタプルを間に sep を入れて連結します。 sep のデフォルト値はスペース文字 1 つです。 `string.join(string.split(s, sep), sep)` は常に s になります。

`string.``joinfields`(words[, sep])

  この関数は `join()` と同じふるまいをします (以前は、 `join()` を使えるのは引数が 1 つの場合だけで、 `joinfields()` は引数 2 つの場合だけでした)。文字列オブジェクトには `joinfields()` メソッドがないので注意してください。代わりに `join()` メソッドを使ってください。

`string.``lstrip`(s[, chars])

  文字列の先頭から文字を取り除いたコピーを生成して返します。 chars を指定しない場合や `None` にした場合、先頭の空白を取り除きます。 chars を `None` 以外の値にする場合、 chars は文字列でなければなりません。

  バージョン 2.2.3 で変更: chars パラメタを追加しました。初期の 2.2 バージョンでは、 chars パラメータを渡せませんでした。

`string.``rstrip`(s[, chars])

  文字列の末尾から文字を取り除いたコピーを生成して返します。 chars を指定しない場合や `None` にした場合、末尾の空白を取り除きます。 chars を `None` 以外の値にする場合、 chars は文字列でなければなりません。

  バージョン 2.2.3 で変更: chars パラメタを追加しました。初期の 2.2 バージョンでは、 chars パラメータを渡せませんでした。

`string.``strip`(s[, chars])

  文字列の先頭と末尾から文字を取り除いたコピーを生成して返します。 chars を指定しない場合や `None` にした場合、先頭と末尾の空白を取り除きます。 chars を `None` 以外に指定する場合、 chars は文字列でなければなりません。

  バージョン 2.2.3 で変更: chars パラメタを追加しました。初期の 2.2 バージョンでは、 chars パラメータを渡せませんでした。

`string.``swapcase`(s)

  s の大文字と小文字を入れ替えたものを返します。

`string.``translate`(s, table[, deletechars])

  s の中から、 (もし指定されていれば) deletechars に入っている文字を削除し、 table を使って文字変換を行って返します。 table は 256 文字からなる文字列で、各文字はそのインデクスを序数とする文字に対する変換先の文字の指定になります。もし、 table が `None` であれば、文字削除のみが行われます。

`string.``upper`(s)

  s に含まれる小文字を大文字に置換して返します。

`string.``ljust`(s, width[, fillchar])
`string.``rjust`(s, width[, fillchar])
`string.``center`(s, width[, fillchar])

  文字列を指定した文字幅のフィールド中でそれぞれ左寄せ、右寄せ、中央寄せします。これらの関数は指定幅になるまで文字列 s の左側、右側、および、両側のいずれかに fillchar （デフォルトでは空白）を追加して、少なくとも width 文字からなる文字列にして返します。文字列を切り詰めることはありません。

`string.``zfill`(s, width)

  数値を表現する文字列の左側に、指定の幅になるまでゼロを付加します。符号付きの数字も正しく処理します。

`string.``replace`(str, old, new[, maxreplace])

  s 内の部分文字列 old を全て new に置換したものを返します。 maxreplace を指定した場合、最初に見つかった maxreplace 個分だけ置換します。

### ナビゲーション

- 索引
- モジュール |
- 次へ |
- 前へ |
- Python 2.7ja1 documentation »
- Python 標準ライブラリ »
- 7. 文字列処理 »