☰ Menu Python

☰ Menu

collections.abc — 컨테이너의 추상 베이스 클래스

Added in version 3.3: 이전에는, 이 모듈이 collections 모듈의 일부였습니다.

소스 코드: Lib/_collections_abc.py

---

이 모듈은 클래스가 특정 인터페이스를 제공하는지를 검사하는 데 사용할 수 있는 추상 베이스 클래스를 제공합니다; 예를 들어, 해시 가능인지 또는 매핑인지입니다.

인터페이스에 대한 issubclass() 또는 isinstance() 테스트는 세 가지 방식 중 하나로 작동합니다.

1. 새로 작성된 클래스는 추상 베이스 클래스 중 하나로부터 직접 상속받을 수 있습니다. 클래스는 필요한 추상 메서드를 제공해야 합니다. 나머지 믹스인(mixin) 메서드는 상속을 통해 제공되며 필요에 따라 재정의할 수 있습니다. 다른 메서드들은 필요에 따라 추가될 수 있습니다:

   class C(Sequence):                      # 직접 상속
       def __init__(self): ...             # ABC 가 요구하지 않는 추가 메서드
       def __getitem__(self, index):  ...  # 필수 추상 메서드
       def __len__(self):  ...             # 필수 추상 메서드
       def count(self, value): ...         # 선택적으로 믹스인 메서드를 재정의합니다
   

   >>> issubclass(C, Sequence)
   True
   >>> isinstance(C(), Sequence)
   True
   

2. 기존 클래스와 내장 클래스를 ABC의 “가상 서브클래스”로 등록할 수 있습니다. 이러한 클래스들은 모든 추상 메서드와 모든 믹스인 메서드를 포함하는 전체 API를 정의해야 합니다. 이를 통해 사용자는 issubclass() 또는 isinstance() 테스트에 의존하여 전체 인터페이스가 지원되는지 판단할 수 있습니다. 이 규칙의 예외는 나머지 API에서 자동으로 추론되는 메서드들입니다:

   class D:                                 # 상속 없음
       def __init__(self): ...              # ABC 가 요구하지 않는 추가 메서드
       def __getitem__(self, index):  ...   # 추상 메서드
       def __len__(self):  ...              # 추상 메서드
       def count(self, value): ...          # 믹스인 메서드
       def index(self, value): ...          # 믹스인 메서드
   
   Sequence.register(D)                     # 상속하는 대신 등록합니다
   

   >>> issubclass(D, Sequence)
   True
   >>> isinstance(D(), Sequence)
   True
   

   이 예제에서 클래스 D 는 __contains__, __iter__, __reversed__ 를 정의할 필요가 없습니다. in 연산자, 반복 로직, 그리고 reversed() 함수가 자동으로 __getitem__ 및 __len__ 을 사용하여 대체되기 때문입니다.

3. 일부 간단한 인터페이스는 필요한 메서드가 존재하면 바로 인식됩니다(해당 메서드가 None 으로 설정되지 않은 경우에 한함):

   class E:
       def __iter__(self): ...
       def __next__(self): ...
   

   >>> issubclass(E, Iterable)
   True
   >>> isinstance(E(), Iterable)
   True
   

   복잡한 인터페이스는 마지막 기술을 지원하지 않는데, 이는 인터페이스가 단순히 메서드 이름의 존재 이상의 의미를 갖기 때문입니다. 인터페이스는 특정 메서드 이름의 존재만으로는 추론할 수 없는 메서드 간의 의미와 관계를 정의합니다. 예를 들어, 클래스가 __getitem__, __len__, __iter__ 를 제공한다는 사실만으로는 Sequence 와 Mapping 을 구분하기에 충분하지 않습니다.

Added in version 3.9: 이 추상 클래스들은 이제 [] 를 지원합니다. 제네릭 에일리어스 형 및 PEP 585 를 참조하십시오.

Collections 추상 베이스 클래스

collections 모듈은 다음과 같은 ABC를 제공합니다:

ABC	상속	추상 메서드	믹스인 메서드
Container [1]		__contains__
Hashable [1]		__hash__
Iterable [1] [2]		__iter__
Iterator [1]	Iterable	__next__	__iter__
Reversible [1]	Iterable	__reversed__
Generator [1]	Iterator	send, throw	close, __iter__, __next__
Sized [1]		__len__
Callable [1]		__call__
Collection [1]	Sized, Iterable, Container	__contains__, __iter__, __len__
Sequence	Reversible, Collection	__getitem__, __len__	__contains__, __iter__, __reversed__, index 및 count
MutableSequence	Sequence	__getitem__, __setitem__, __delitem__, __len__, insert	상속된 Sequence 메서드와 append, clear, reverse, extend, pop, remove 및 __iadd__
ByteString	Sequence	__getitem__, __len__	상속된 Sequence 메서드
Set	Collection	__contains__, __iter__, __len__	__le__, __lt__, __eq__, __ne__, __gt__, __ge__, __and__, __or__, __sub__, __rsub__, __xor__, __rxor__ 및 isdisjoint
MutableSet	Set	__contains__, __iter__, __len__, add, discard	상속된 Set 메서드와 clear, pop, remove, __ior__, __iand__, __ixor__ 및 __isub__
Mapping	Collection	__getitem__, __iter__, __len__	__contains__, keys, items, values, get, __eq__ 및 __ne__
MutableMapping	Mapping	__getitem__, __setitem__, __delitem__, __iter__, __len__	상속된 Mapping 메서드와 pop, popitem, clear, update 및 setdefault
MappingView	Sized		__init__, __len__ 및 __repr__
ItemsView	MappingView, Set		__contains__, __iter__
KeysView	MappingView, Set		__contains__, __iter__
ValuesView	MappingView, Collection		__contains__, __iter__
Awaitable [1]		__await__
Coroutine [1]	Awaitable	send, throw	close
AsyncIterable [1]		__aiter__
AsyncIterator [1]	AsyncIterable	__anext__	__aiter__
AsyncGenerator [1]	AsyncIterator	asend, athrow	aclose, __aiter__, __anext__
Buffer [1]		__buffer__

각주

[1] (1,2,3,4,5,6,7,8,9,10,11,12,13,14,15)

이 ABC들은 필수 메서드가 존재하고 None 으로 설정되지 않았는지 확인하여 인터페이스를 테스트할 수 있도록 __subclasshook__() 을 재정의합니다. 이는 간단한 인터페이스에만 적용됩니다. 더 복잡한 인터페이스는 등록 또는 직접적인 서브클래싱이 필요합니다.

[2]

isinstance(obj, Iterable)를 검사하면 Iterable로 등록되었거나 __iter__() 메서드가 있는 클래스를 감지하지만, __getitem__() 메서드로 이터레이트 하는 클래스는 감지하지 않습니다. 객체가 이터러블인지를 확인하는 유일하게 신뢰성 있는 방법은 iter(obj)를 호출하는 것입니다.

Collections 추상 베이스 클래스 – 상세한 설명

class collections.abc.Container

__contains__() 메서드를 제공하는 클래스의 ABC.

class collections.abc.Hashable

__hash__() 메서드를 제공하는 클래스의 ABC.

class collections.abc.Sized

__len__() 메서드를 제공하는 클래스의 ABC.

class collections.abc.Callable

__call__() 메서드를 제공하는 클래스의 ABC.

타입 주석에서 Callable 을 사용하는 방법에 대한 자세한 내용은 콜러블 객체에 주석 달기 를 참조하십시오.

class collections.abc.Iterable

__iter__() 메서드를 제공하는 클래스의 ABC.

isinstance(obj, Iterable)를 검사하면 Iterable로 등록되었거나 __iter__() 메서드가 있는 클래스를 감지하지만, __getitem__() 메서드로 이터레이트 하는 클래스는 감지하지 않습니다. 객체가 이터러블인지를 확인하는 유일하게 신뢰성 있는 방법은 iter(obj)를 호출하는 것입니다.

class collections.abc.Collection

길이가 있는 이터러블 컨테이너 클래스의 ABC.

Added in version 3.6.

class collections.abc.Iterator

__iter__() 와 __next__() 메서드를 제공하는 클래스의 ABC. 이터레이터의 정의도 참조하십시오.

class collections.abc.Reversible

__reversed__() 메서드도 제공하는 이터러블 클래스의 ABC.

Added in version 3.6.

class collections.abc.Generator

send(), throw() 및 close() 메서드로 이터레이터를 확장하는 PEP 342에 정의된 프로토콜을 구현하는 제너레이터 클래스의 ABC.

타입 주석에서 Generator 을 사용하는 방법에 대한 자세한 내용은 제너레이터와 코루틴 주석 처리하기 를 참조하십시오.

Added in version 3.5.

class collections.abc.Sequence

class collections.abc.MutableSequence

class collections.abc.ByteString

읽기 전용과 가변 시퀀스의 ABC.

구현 참고: __iter__(), __reversed__(), index() 와 같은 일부 믹스인 메서드는 기본이 되는 __getitem__() 메서드를 반복적으로 호출합니다. 결과적으로, __getitem__() 이 일정한 접근 속도로 구현된 경우 믹스인 메서드는 선형 성능을 가지지만, 기본 메서드가 선형적인 경우(연결 리스트와 같은 경우) 믹스인은 이차 성능을 가지며 재정의가 필요할 수 있습니다.

index(value, start=0, stop=None)

value 의 첫 번째 인덱스를 반환합니다.

값이 존재하지 않으면 ValueError 를 발생시킵니다.

start 및 stop 인자를 지원하는 것은 선택 사항이지만 권장됩니다.

버전 3.5에서 변경: index() 메서드가 stop 및 start 인자를 지원하게 되었습니다.

버전 3.12부터 사용 지원 중단(deprecated), 버전 3.17에서 제거 예정: ByteString ABC가 더 이상 사용되지 않습니다.

실행 시간에 obj 가 버퍼 프로토콜 를 구현하는지 확인하려면 isinstance(obj, collections.abc.Buffer) 를 사용하십시오. 타입 어노테이션에서 사용하는 경우, Buffer 를 사용하거나 코드가 지원하는 타입을 명시적으로 지정한 유니온(예: bytes | bytearray | memoryview)을 사용하십시오.

ByteString 은 원래 bytes 와 bytearray 모두의 상위 타입 역할을 하는 추상 클래스로 설계되었습니다. 하지만 이 ABC에 메서드가 전혀 없었기 때문에, 어떤 객체가 ByteString 의 인스턴스라는 사실이 객체에 대한 유용한 정보를 제공하지 못했습니다. 또한 memoryview 와 같은 다른 일반적인 버퍼 타입들도 런타임이나 정적 타입 검사에서 ByteString 의 하위 유형으로 인식되지 않았습니다.

자세한 내용은 PEP 688 를 참조하십시오.

class collections.abc.Set

class collections.abc.MutableSet

읽기 전용과 가변 집합의 ABC.

class collections.abc.Mapping

class collections.abc.MutableMapping

읽기 전용과 가변 매핑의 ABC.

class collections.abc.MappingView

class collections.abc.ItemsView

class collections.abc.KeysView

class collections.abc.ValuesView

매핑, 항목, 키 및 값 뷰의 ABC.

class collections.abc.Awaitable

await 표현식에서 사용할 수 있는 어웨이터블 객체의 ABC. 사용자 정의 구현은 __await__() 메서드를 제공해야 합니다.

코루틴 객체와 Coroutine ABC의 인스턴스는 모두 이 ABC의 인스턴스입니다.

참고

CPython에서 제너레이터 기반 코루틴(제너레이터 가 @types.coroutine 으로 데코레이션됨)은 __await__() 메서드가 없더라도 어웨이터블 입니다. 이들에 대해 isinstance(gencoro, Awaitable) 을 사용하면 False 를 반환합니다. 이를 감지하려면 inspect.isawaitable() 을 사용하십시오.

Added in version 3.5.

class collections.abc.Coroutine

코루틴 호환 클래스의 ABC. 코루틴 객체(Coroutine Objects)에 정의된 다음 메서드를 구현합니다: send(), throw() 및 close(). 사용자 정의 구현은 __await__()도 구현해야 합니다. 모든 Coroutine 인스턴스는 Awaitable의 인스턴스이기도 합니다.

참고

CPython에서 제너레이터 기반 코루틴(제너레이터 가 @types.coroutine 으로 데코레이션됨)은 __await__() 메서드가 없더라도 어웨이터블 입니다. 이들에 대해 isinstance(gencoro, Coroutine) 을 사용하면 False 를 반환합니다. 이를 감지하려면 inspect.isawaitable() 을 사용하십시오.

타입 어노테이션에서 Coroutine 을 사용하는 방법에 대한 자세한 내용은 제너레이터와 코루틴 주석 처리하기 를 참조하십시오. 타입 파라미터의 분산과 순서는 Generator 와 동일합니다.

Added in version 3.5.

class collections.abc.AsyncIterable

__aiter__ 메서드를 제공하는 클래스의 ABC. 비동기 이터러블의 정의도 참조하십시오.

Added in version 3.5.

class collections.abc.AsyncIterator

__aiter__ 와 __anext__ 메서드를 제공하는 클래스의 ABC. 비동기 이터레이터의 정의도 참조하십시오.

Added in version 3.5.

class collections.abc.AsyncGenerator

PEP 525와 PEP 492에 정의된 프로토콜을 구현하는 비동기 제너레이터 클래스의 ABC.

타입 어노테이션에서 AsyncGenerator 를 사용하는 방법에 대한 자세한 내용은 제너레이터와 코루틴 주석 처리하기 를 참조하십시오.

Added in version 3.6.

class collections.abc.Buffer

버퍼 프로토콜 을 구현하고 __buffer__() 메서드를 제공하는 클래스를 위한 ABC입니다. PEP 688 을 참조하십시오.

Added in version 3.12.

예제와 조리법

ABC들은 클래스나 인스턴스가 특정 기능을 제공하는지 묻는 것을 허용합니다, 예를 들어:

size = None
if isinstance(myvar, collections.abc.Sized):
    size = len(myvar)

ABC 중 일부는 믹스인으로도 유용하여 컨테이너 API를 지원하는 클래스를 쉽게 개발할 수 있게 합니다. 예를 들어, 전체 Set API를 지원하는 클래스를 작성하려면, __contains__(), __iter__() 및 __len__()의 세 가지 하부 추상 메서드 만 제공하면 됩니다. ABC는 __and__()와 isdisjoint()와 같은 나머지 메서드를 제공합니다:

class ListBasedSet(collections.abc.Set):
    ''' 속도보다 공간을 선호하고 집합 원소가
        해시 가능할 필요가 없는 대안 집합 구현. '''
    def __init__(self, iterable):
        self.elements = lst = []
        for value in iterable:
            if value not in lst:
                lst.append(value)

    def __iter__(self):
        return iter(self.elements)

    def __contains__(self, value):
        return value in self.elements

    def __len__(self):
        return len(self.elements)

s1 = ListBasedSet('abcdef')
s2 = ListBasedSet('defghi')
overlap = s1 & s2            # __and__() 메서드는 자동으로 지원됩니다

Set과 MutableSet을 믹스인으로 사용할 때의 주의 사항:

1. 일부 집합 연산은 새로운 집합을 만들기 때문에, 기본 믹스인 메서드는 이터러블로부터 새 인스턴스를 만드는 방법이 필요합니다. 클래스 생성자가 ClassName(iterable) 형식의 서명을 가진 것으로 가정합니다. 이 가정은 새로운 집합을 생성하기 위해 cls(iterable)를 호출하는 _from_iterable()이라는 내부 classmethod로 분리되었습니다. Set 믹스인이 다른 생성자 서명을 갖는 클래스에서 사용되고 있으면, 이터러블 인자로부터 새 인스턴스를 생성할 수 있는 클래스 메서드나 일반 메서드로 _from_iterable()을 재정의해야 합니다.

2. 비교를 재정의하려면 (의미는 고정되었으므로, 아마도 속도 때문에), __le__()와 __ge__()를 재정의하십시오, 그러면 다른 연산은 자동으로 맞춰집니다.

3. Set 믹스인은 집합의 해시 값을 계산하는 _hash() 메서드를 제공합니다. 다만 모든 집합이 해시 가능 하거나 불변은 아니므로 __hash__() 는 정의되어 있지 않습니다. 믹스인을 사용하여 집합의 해시 가능성을 추가하려면, Set 과 Hashable 을 모두 상속한 후 __hash__ = Set._hash 을 정의하십시오.

더 보기

• MutableSet으로 구축한 예제 OrderedSet 조리법.

• ABC에 대한 자세한 내용은, abc 모듈과 PEP 3119를 참조하십시오.

분실물 보관소