Python collectionsのメンバー一覧とUserListの使い方|listを継承した場合との違い・UserString

collections.UserListは、中身を普通のlistとしてdata属性に持つ「リストのように振る舞うクラス」で、リストを拡張した自作クラスを作るときの土台に使います。listを直接継承した場合と違い、スライスや+の結果も自作クラスのまま返るのが一番の違いです。

この記事では、まずcollectionsモジュールのメンバー(クラスと関数)を一覧で確認し、そのあとでUserListの使い方、listを継承した場合との違い、作るときの注意点、UserString・UserDictとの関係を、Python 3.12で実行した結果つきで解説します。仕様はPython公式ドキュメント(collections)に沿っています(2026年10月18日確認)。

collectionsのメンバー一覧

import collections

names = [n for n in dir(collections) if not n.startswith("_")]
print(names)
print(len(names))

実行結果(Python 3.12):

['ChainMap', 'Counter', 'OrderedDict', 'UserDict', 'UserList', 'UserString', 'defaultdict', 'deque', 'namedtuple']
9

公開されているメンバーは9個で、collections.__all__の中身とも一致します。サブモジュールのcollections.abcは、import collections.abcを実行したあとでdir()にabcとして現れます。

メンバー 種類 用途 詳しい解説
Counter クラス 要素の出現回数を数える Counterの使い方
defaultdict クラス キーがないときに初期値を作る辞書 defaultdictとは?
OrderedDict クラス 順序の入れ替え(move_to_end())や順序込みの比較ができる辞書 —
deque クラス 両端の追加・取り出しが速いキュー deque.popleft()
ChainMap クラス 複数の辞書を重ねて優先順に引く ChainMapの使い方
UserDict クラス 辞書のように振る舞う自作クラスの土台 UserDictとは?
UserList クラス リストのように振る舞う自作クラスの土台 この記事
UserString クラス 文字列のように振る舞う自作クラスの土台 この記事
namedtuple() 関数 名前でアクセスできるタプルの型を作る namedtupleとは?
abc サブモジュール Iterable・Mappingなどの抽象基底クラス import collectionsの書き方

例外クラスや定数はありません。Counter・defaultdict・dequeなどを実行例つきで比べたい場合は「Python collections クラス一覧」をご覧ください。この記事では、ほかの記事であまり扱っていないUserListとUserStringを中心に解説します。

UserListとは

from collections import UserList

UserList([list])
項目 内容
引数 リストやタプルなどのイテラブル(省略すると空)。中身はコピーされる
中身の置き場所 data属性(普通のlist)
使えるメソッド append()・extend()・sort()・スライスなど、リストの操作はひととおり使える
型の判定 isinstance(x, list)はFalse、collections.abc.MutableSequenceにはTrue

公式ドキュメントでは、listを直接継承できるようになったためUserListの必要性は一部薄れたものの、中身が属性として見えるぶん扱いやすい場合がある、と説明されています。

listを継承した場合とUserListの違い

同じtotal()メソッドを持つクラスを、listの継承とUserListの継承でそれぞれ作って比べます。

from collections import UserList

class MyList(list):
    def total(self):
        return sum(self)

class MyUserList(UserList):
    def total(self):
        return sum(self.data)

a = MyList([1, 2, 3, 4])
b = MyUserList([1, 2, 3, 4])

print(type(a[:2]).__name__, type(b[:2]).__name__)
print(type(a + a).__name__, type(b + b).__name__)
print(type(a.copy()).__name__, type(b.copy()).__name__)
print(b[:2].total())
try:
    print(a[:2].total())
except AttributeError as e:
    print("AttributeError:", e)

実行結果:

list MyUserList
list MyUserList
list MyUserList
3
AttributeError: 'list' object has no attribute 'total'

listを継承したクラスは、スライス・+・copy()の結果がただのlistに戻るため、自作したtotal()が消えてしまいます。UserListなら結果も自作クラスのまま返るので、続けてtotal()を呼べます。

比較 class X(list) class X(UserList)
スライス・+・copy()の結果 listに戻る 自作クラスのまま
中身へのアクセス selfそのもの self.data
isinstance(x, list) True False
json.dumps() そのまま使える TypeError(x.dataを渡す)
速度 組み込み型なので速い Pythonで書かれたラッパーのぶん遅い

UserListでリストを拡張する例

正の数しか入れられないリストを作ります。append()・extend()・+=(__iadd__())・insert()・__setitem__()を上書きして、入れる前に値を確かめます。

from collections import UserList

class PositiveList(UserList):
    def _check(self, x):
        if x <= 0:
            raise ValueError(f"正の数だけ入れられます: {x}")
        return x
    def __init__(self, initlist=None):
        super().__init__()
        if initlist is not None:
            self.extend(initlist)
    def append(self, item):
        super().append(self._check(item))
    def extend(self, other):
        super().extend([self._check(x) for x in other])
    def __iadd__(self, other):
        self.extend(other)
        return self
    def insert(self, i, item):
        super().insert(i, self._check(item))
    def __setitem__(self, i, item):
        if isinstance(i, slice):
            item = [self._check(x) for x in item]
        else:
            item = self._check(item)
        super().__setitem__(i, item)

p = PositiveList([3, 1, 2])
p.append(5)
print(p, p.data, type(p.data).__name__)

try:
    p.extend([4, 0])
except ValueError as e:
    print("ValueError:", e)
try:
    p += [-2]
except ValueError as e:
    print("ValueError:", e)
try:
    p[0] = -9
except ValueError as e:
    print("ValueError:", e)

p.sort()
print(p)
print(type(p[:2]).__name__, p[:2])

実行結果:

[3, 1, 2, 5] [3, 1, 2, 5] list
ValueError: 正の数だけ入れられます: 0
ValueError: 正の数だけ入れられます: -2
ValueError: 正の数だけ入れられます: -9
[1, 2, 3, 5]
PositiveList [1, 2]

sort()やスライスは書かなくてもそのまま使え、スライスの結果もPositiveListです。extend([4, 0])では先にすべての値を確かめているので、0でエラーになったとき4も入りません(ジェネレーターで1つずつ確かめると、エラーの前の4だけ入ってしまいます)。

注意:UserListは1つのメソッドにまとまっていない

UserListのappend()・extend()・+=・insert()は、それぞれ直接self.dataを操作します。実際にappend()だけを上書きして試すと、extend()・+=・insert()では上書きしたappend()は呼ばれませんでした。値の追加を制限したいときは、追加に関わるメソッドをすべて上書きしてください。UserDictでは、代入・update()・setdefault()・コンストラクタが__setitem__()を通るので、1か所の上書きでほぼ足ります(ただし|=は通りませんでした)。UserDictの例は「Python UserDictとは?」で解説しています。

__init__の引数を増やすとスライスでエラーになる

公式ドキュメントには、UserListの子クラスは「引数なし」または「引数1つ(元になるシーケンス)」で呼べるコンストラクタを用意するように、と書かれています。スライスや+の結果を作るときに、そのクラスを引数1つで呼び出すからです。

from collections import UserList

class Weird(UserList):
    def __init__(self, items, label):
        super().__init__(items)
        self.label = label

w = Weird([1, 2, 3], "x")
w[:2]

実行結果:

TypeError: Weird.__init__() missing 1 required positional argument: 'label'

追加の引数はlabel=Noneのように省略できる形にするか、属性はあとから設定するようにします。

UserListでよくあるつまずき

from collections import UserList
import collections.abc as abc
import json

u = UserList([1, 2])
print(isinstance(u, list), isinstance(u, abc.MutableSequence))
print(u == [1, 2])
try:
    print(json.dumps(u))
except TypeError as e:
    print("TypeError:", e)
print(json.dumps(u.data))

実行結果:

False True
True
TypeError: Object of type UserList is not JSON serializable
[1, 2]
  • isinstance(x, list)で判定しているライブラリには渡せない。型の判定にはcollections.abc.MutableSequenceやSequenceを使う
  • json.dumps()にはu.dataかlist(u)を渡す
  • ==は中身で比べるので、普通のリストとも比較できる

UserStringの使い方

UserStringは文字列版です。中身はdata属性のstrで、upper()などのメソッドの結果も自作クラスで返ります。

from collections import UserString

class Tag(UserString):
    def wrap(self, name):
        return self.__class__(f"<{name}>{self.data}</{name}>")

t = Tag("hello")
print(t.upper(), type(t.upper()).__name__)
print(t.wrap("b"))
print(isinstance(t, str))

実行結果:

HELLO Tag
<b>hello</b>
False

isinstance(t, str)はFalseなので、文字列であることを厳密に確かめる関数にはstr(t)で渡します。

UserList・UserString・UserDictとlist・str・dictの継承の選び方

こんなとき 選ぶもの
メソッドを1〜2個足すだけで、スライス結果の型は気にしない list・str・dictを直接継承
スライスや+の結果も自作クラスのままにしたい UserList・UserString
辞書への追加をすべて1か所で制御したい UserDict(__setitem__()を上書き)
isinstance(x, list)で判定する外部ライブラリに渡す listを直接継承
大量のデータを速く処理したい 組み込み型をそのまま使う

クラスの継承そのものの書き方は「クラスの継承とは?」で解説しています。

よくある質問

Q. collectionsモジュールには何が入っていますか?

ChainMap・Counter・OrderedDict・UserDict・UserList・UserString・defaultdict・dequeの8つのクラスと、namedtuple()関数の9個です。ほかにサブモジュールのcollections.abcがあります。

Q. UserListとlistの継承はどちらを使えばよいですか?

スライスや+の結果も自作クラスのまま返してほしいならUserList、メソッドを少し足すだけで速度やisinstance(x, list)の判定を優先するならlistの継承が向いています。

Q. UserListの中身を普通のリストとして取り出すには?

data属性が普通のlistです。コピーがほしい場合はlist(u)を使います。json.dumps()に渡すときもどちらかに変換します。

Q. UserListを継承したクラスでスライスするとTypeErrorになります。

__init__に必須の引数を増やしたことが原因です。UserListはスライスの結果を作るときにクラスを引数1つで呼ぶため、追加の引数は省略できる形にします。

まとめ

  • collectionsの公開メンバーは8クラス+namedtuple()の9個と、サブモジュールabc
  • UserListは中身をdata属性のlistに持つ、リスト風クラスの土台
  • listの継承と違い、スライス・+・copy()の結果も自作クラスで返る
  • 追加を制限するならappend()・extend()・+=・insert()・__setitem__()をすべて上書きする
  • __init__は引数1つで呼べる形に。isinstance(x, list)やjson.dumps()にはdataを渡す

あわせて読みたい


Python標準ライブラリの関連記事

collectionsは標準ライブラリに含まれるモジュールのひとつです。標準ライブラリ全体の構成や、ほかにどんなモジュールがあるのかは次の記事でまとめています。

対面・無料|東京・永田町で毎週土曜日13時

この記事のようなコードを、講師に聞きながら動かしてみる

ゼロからはじめるPython入門講座

8年間・累計600回開催/これまで全国で2万人以上が参加

「やはり対面で聞けるのはとても気づきがあり、価値があると思います」

参加者の声

  • 本当に初心者からの講座です。プログラミングに触ったことがなくて大丈夫です
  • 対面だから、その場で聞けます。つまずいた所を持ち帰らずに解決できます
  • 講座は1時間。そのあとも残って学習を続けられ、講師にも質問できます
  • 独学で挫折した方も。糸口が見つかって、講座のあと会員になる方が多くいます

無料で参加する|開催日程を見る

参加費は無料です