Python collections Modülü: Counter, defaultdict, deque, namedtuple, OrderedDict ve ChainMap

Hangi yapı ne işe yarar?

Counter: saymanın kısa yolu

Counter, hash edilebilir nesneleri saymak için tasarlanmış bir dict alt sınıfıdır: elemanlar anahtar, sayıları değer olarak tutulur. Belgeler onu diğer dillerdeki "bag" ya da "multiset" yapılarına benzetir. Bir yinelenebilirden, bir eşlemeden ya da anahtar kelime argümanlarından oluşturulabilir. Normal sözlükten en önemli farkı, olmayan bir eleman istendiğinde KeyError yerine 0 döndürmesidir. most_common(n) en sık geçen n elemanı sayılarıyla birlikte büyükten küçüğe verir; sayısı eşit olanlar ilk görülme sırasıyla gelir. Python 3.10'da eklenen total() tüm sayıların toplamını döndürür.

from collections import Counter

renkler = ['kırmızı', 'mavi', 'kırmızı', 'yeşil', 'mavi', 'mavi']
sayac = Counter(renkler)
print(sayac)                      # çıktı: Counter({'mavi': 3, 'kırmızı': 2, 'yeşil': 1})
print(sayac['mavi'], sayac['mor']) # çıktı: 3 0
print(sayac.most_common(2))       # çıktı: [('mavi', 3), ('kırmızı', 2)]
print(sayac.total())              # çıktı: 6

print(Counter('abracadabra').most_common(3))   # çıktı: [('a', 5), ('b', 2), ('r', 2)]
print(Counter(kedi=4, kopek=8))   # çıktı: Counter({'kopek': 8, 'kedi': 4})

Bir sayıyı sıfıra çekmek elemanı silmez; tamamen kaldırmak için del gerekir. elements(), her elemanı sayısı kadar tekrarlayan bir yineleyici döndürür ve sayısı birden küçük olanları atlar. update() normal sözlükteki gibi değerin üzerine yazmaz, sayıları ekler; ayrıca argüman olarak çift listesi değil eleman dizisi bekler. subtract() sayıları çıkarır ve sonuçta sıfır ya da negatif değerlere izin verir. Tekli + işleci sıfır ve negatif sayıları temizlemenin kısa yoludur.

from collections import Counter

c = Counter(a=4, b=2, c=0, d=-2)
print(sorted(c.elements()))   # çıktı: ['a', 'a', 'a', 'a', 'b', 'b']

c['e'] = 0
print('e' in c)               # çıktı: True
del c['e']
print('e' in c)               # çıktı: False

stok = Counter(elma=3)
stok.update(['elma', 'armut'])
stok.update({'armut': 5})
print(stok)                   # çıktı: Counter({'armut': 6, 'elma': 4})
stok.subtract(elma=10)
print(stok)                   # çıktı: Counter({'armut': 6, 'elma': -6})
print(+stok)                  # çıktı: Counter({'armut': 6})

try:
    Counter.fromkeys('ab')
except NotImplementedError as hata:
    print(hata)               # çıktı: Counter.fromkeys() is undefined.  Use Counter(iterable) instead.

Counter aritmetiği ve 3.15'te gelen ^ işleci

İki Counter birbiriyle toplanabilir, çıkarılabilir; kesişim (&) her eleman için küçük sayıyı, birleşim (|) büyük sayıyı alır. Python 3.15 bu listeye simetrik farkı (^) ekledi: sonuç her eleman için büyük sayı ile küçük sayının farkıdır. Belgelere göre bu çoklu küme işlemleri girişte negatif ya da sıfır sayıları kabul eder ama sonuçta yalnızca pozitif sayıları tutar. Karşılaştırma işleçleri (==, <=, >= vb.) Python 3.10'dan beri vardır ve eksik elemanları sıfır sayılmış gibi değerlendirir.

from collections import Counter

c = Counter(a=3, b=1)
d = Counter(a=1, b=2)
print(c + d)     # çıktı: Counter({'a': 4, 'b': 3})
print(c - d)     # çıktı: Counter({'a': 2})
print(c & d)     # çıktı: Counter({'a': 1, 'b': 1})
print(c | d)     # çıktı: Counter({'a': 3, 'b': 2})
print(c ^ d)     # çıktı: Counter({'a': 2, 'b': 1})
print(c == d, c <= d)                        # çıktı: False False
print(Counter(a=1) == Counter(a=1, b=0))     # çıktı: True

^ işleci Python 3.15'ten önceki sürümlerde Counter için tanımlı değildir; aynı sonucu eski sürümlerde (c | d) - (c & d) ile elde edebilirsiniz. Sürümün diğer yenilikleri Python 3.15 yenilikleri yazısında.

defaultdict: eksik anahtara otomatik değer

defaultdict bir dict alt sınıfıdır ve ilk argüman olarak bir default_factory alır: argümansız çağrılabilen bir fonksiyon ya da sınıf. Olmayan bir anahtar d[k] ile istendiğinde bu fabrika çağrılır, dönen değer o anahtarla sözlüğe eklenir ve döndürülür. list verirseniz gruplama, int verirseniz sayma, set verirseniz tekrarsız gruplama için hazır bir sözlüğünüz olur. Belgeler bu tekniğin dict.setdefault() ile yazılan karşılığından daha basit ve daha hızlı olduğunu belirtir.

from collections import defaultdict

s = [('sarı', 1), ('mavi', 2), ('sarı', 3), ('mavi', 4), ('kırmızı', 1)]
gruplar = defaultdict(list)
for renk, sayi in s:
    gruplar[renk].append(sayi)
print(sorted(gruplar.items()))   # çıktı: [('kırmızı', [1]), ('mavi', [2, 4]), ('sarı', [1, 3])]

sayim = defaultdict(int)
for harf in 'mississippi':
    sayim[harf] += 1
print(sorted(sayim.items()))     # çıktı: [('i', 4), ('m', 1), ('p', 2), ('s', 4)]

etiketler = defaultdict(set)
for yazi, etiket in [('a', 'python'), ('a', 'linux'), ('a', 'python')]:
    etiketler[yazi].add(etiket)
print(sorted(etiketler['a']))    # çıktı: ['linux', 'python']

defaultdict'in iki davranışı sürpriz yaratabilir. Birincisi, belgelere göre fabrika yalnızca __getitem__(), yani d[k] sırasında devreye girer; get() normal sözlükteki gibi None döndürür, in de kayıt oluşturmaz. İkincisi, yalnızca okumak için d[k] yazmak bile o anahtarı sözlüğe ekler; bu, sonradan sözlüğü dolaşırken beklemediğiniz boş kayıtlar görmenize yol açabilir. default_factory değiştirilebilir bir özelliktir; None yaparsanız sözlük normal dict gibi KeyError vermeye başlar. Sabit bir varsayılan için lambda kullanılabilir.

from collections import defaultdict

d = defaultdict(list)
print(d.get('x'))          # çıktı: None
print('x' in d)            # çıktı: False
d['x']                     # yalnızca okuma, ama kayıt oluşur
print(dict(d))             # çıktı: {'x': []}
print(d.default_factory)   # çıktı: <class 'list'>

d.default_factory = None
try:
    d['y']
except KeyError as hata:
    print(repr(hata))      # çıktı: KeyError('y')

sabit = defaultdict(lambda: 'bilinmiyor')
sabit.update(ad='Ece')
print(sabit['ad'], sabit['sehir'])   # çıktı: Ece bilinmiyor

agac = defaultdict(lambda: defaultdict(int))
agac['2026']['kasım'] += 5
print({yil: dict(aylar) for yil, aylar in agac.items()})   # çıktı: {'2026': {'kasım': 5}}

deque: iki uçlu hızlı kuyruk

deque ("deck" diye okunur, "double-ended queue" kısaltması) yığın ve kuyruğun genelleştirilmiş halidir. Belgelere göre her iki uçtan ekleme ve çıkarma, hangi yönde olursa olsun yaklaşık O(1) maliyetle, iş parçacığı güvenli ve bellek açısından verimli şekilde yapılır. Listeler ise sabit uzunluklu işlemler için optimize edilmiştir; pop(0) ve insert(0, v) listede O(n) bellek kaydırması gerektirir. Buna karşılık deque'da indeksle erişim uçlarda hızlı, ortada ise O(n)'dir; rastgele erişim ağırlıklı işler için liste daha uygundur.

from collections import deque

d = deque('ghi')
d.append('j')
d.appendleft('f')
print(d)                 # çıktı: deque(['f', 'g', 'h', 'i', 'j'])
print(d.pop(), d.popleft())   # çıktı: j f
print(d[0], d[-1])       # çıktı: g i

d.extend('jkl')
d.rotate(1)
print(d)                 # çıktı: deque(['l', 'g', 'h', 'i', 'j', 'k'])
d.rotate(-1)
print(d)                 # çıktı: deque(['g', 'h', 'i', 'j', 'k', 'l'])

ters = deque()
ters.extendleft('abc')   # soldan tek tek eklendiği için sıra ters döner
print(ters)              # çıktı: deque(['c', 'b', 'a'])

bos = deque()
try:
    bos.pop()
except IndexError as hata:
    print(hata)          # çıktı: pop from an empty deque

rotate(n) kuyruğu n adım sağa döndürür, negatif n sola döndürür. Belgelere göre bir adım sağa döndürmek d.appendleft(d.pop()), bir adım sola döndürmek d.append(d.popleft()) ile aynıdır. Sıra tabanlı (round-robin) görev dağıtımı gibi işler için kullanışlıdır.

maxlen ile son N kaydı tutmak

deque'ya maxlen verirseniz uzunluğu sınırlanır. Kuyruk dolduktan sonra bir uçtan eleman eklendiğinde, belgelerin tarifiyle, karşı uçtan aynı sayıda eleman atılır. Bu davranış Unix'teki tail komutuna benzer ve "son 100 log satırı" ya da "son 5 işlem" gibi yalnızca en yeni verinin önemli olduğu durumlar için idealdir. Dolu bir sınırlı kuyruğa insert() ile eleman eklemeye çalışmak ise IndexError verir.

import io
from collections import deque

son_loglar = deque(maxlen=3)
for satir in ['a', 'b', 'c', 'd', 'e']:
    son_loglar.append(satir)
print(son_loglar)          # çıktı: deque(['c', 'd', 'e'], maxlen=3)
print(son_loglar.maxlen)   # çıktı: 3
son_loglar.appendleft('z')
print(son_loglar)          # çıktı: deque(['z', 'c', 'd'], maxlen=3)

try:
    son_loglar.insert(1, 'x')
except IndexError as hata:
    print(hata)            # çıktı: deque already at its maximum size

# Belgelerdeki tail tarifi: bir dosyanın son n satırı
dosya = io.StringIO('1\n2\n3\n4\n5\n')
print(list(deque(dosya, 2)))   # çıktı: ['4\n', '5\n']

Son örnekte gerçek bir dosya yerine bellekteki bir metni dosya gibi kullanan io.StringIO kullandık; gerçek dosyalarla çalışmak için dosya okuma ve yazma yazısına bakabilirsiniz.

namedtuple(): alanlarına isimle erişilen tuple

namedtuple() bir sınıf değil, yeni bir tuple alt sınıfı üreten bir fabrika fonksiyonudur. İlk argüman tipin adı, ikincisi alan adlarıdır; alan adları bir liste ya da boşluk veya virgülle ayrılmış tek bir string olabilir. Ortaya çıkan nesneler normal tuple gibi indekslenir, açılır ve hash edilir; ek olarak alanlara p.x gibi isimle erişilir ve Nokta(x=11, y=22) biçiminde okunaklı yazdırılır. Belgelere göre örnek başına sözlük tutmadıkları için normal tuple'dan fazla bellek kullanmazlar. Alan adlarıyla çakışmayı önlemek için ek metotlar alt çizgiyle başlar: _make(), _asdict(), _replace(), _fields ve _field_defaults.

from collections import namedtuple

Nokta = namedtuple('Nokta', ['x', 'y'])
p = Nokta(11, y=22)
print(p[0] + p[1], p.x + p.y)   # çıktı: 33 33
print(p)                        # çıktı: Nokta(x=11, y=22)
print(p._asdict())              # çıktı: {'x': 11, 'y': 22}
print(p._replace(x=33))         # çıktı: Nokta(x=33, y=22)
print(Nokta._make([1, 2]))      # çıktı: Nokta(x=1, y=2)
print(Nokta._fields)            # çıktı: ('x', 'y')
print(Nokta(**{'x': 5, 'y': 6})) # çıktı: Nokta(x=5, y=6)

Hesap = namedtuple('Hesap', 'tur bakiye', defaults=[0])
print(Hesap('premium'))         # çıktı: Hesap(tur='premium', bakiye=0)
print(Hesap._field_defaults)    # çıktı: {'bakiye': 0}

defaults verilen değerler en sağdaki alanlara uygulanır, çünkü varsayılanı olan alanlar varsayılanı olmayanlardan sonra gelmek zorundadır. Alan adları geçerli Python tanımlayıcısı olmalı, alt çizgiyle başlamamalı ve class gibi bir anahtar kelime olmamalıdır. rename=True verirseniz geçersiz ve tekrarlanan adlar otomatik olarak _1, _2 gibi konumsal adlarla değiştirilir. İsimli tuple bir tuple olduğu için alanlarına atama yapılamaz. Python 3.13'ten beri _replace() geçersiz bir alan adı aldığında ValueError yerine TypeError fırlatıyor ve aynı sürümde gelen genel copy.replace() fonksiyonu isimli tuple'larla da çalışıyor.

import copy
from collections import namedtuple

Nokta = namedtuple('Nokta', 'x y')
p = Nokta(1, 2)
try:
    p.x = 5
except AttributeError as hata:
    print(hata)    # çıktı: can't set attribute

try:
    p._replace(z=3)
except TypeError as hata:
    print(hata)    # çıktı: Got unexpected field names: ['z']

print(copy.replace(p, x=9))   # çıktı: Nokta(x=9, y=2)

try:
    namedtuple('Kayit', 'ad class')
except ValueError as hata:
    print(hata)    # çıktı: Type names and field names cannot be a keyword: 'class'
print(namedtuple('Kayit', ['ad', 'def', 'ad'], rename=True)._fields)   # çıktı: ('ad', '_1', '_2')

Tip notlarıyla aynı yapıyı sınıf söz dizimiyle tanımlamak için typing.NamedTuple kullanılır (type hints ve typing). Alanları sonradan değiştirilebilen kayıtlar için ise belgeler dataclasses modülünü önerir (dataclasses). Tuple'ların genel kuralları tuple ve unpacking yazısında.

OrderedDict: sıra hâlâ önemliyse

Python 3.7'den beri normal sözlük ekleme sırasını garanti ettiği için OrderedDict'in önemi azaldı. Belgeler yine de bazı farkların sürdüğünü listeler: normal dict eşleme işlemlerinde iyi olacak şekilde, OrderedDict ise yeniden sıralama işlemlerinde iyi olacak şekilde tasarlanmıştır. OrderedDict'in eşitlik testi sırayı dikkate alır (ama normal bir sözlükle karşılaştırıldığında almaz); popitem(last=False) ile baştan eleman çıkarabilir; move_to_end(k, last=False) ile bir anahtarı en başa taşıyabilir. Belgelere göre normal dict'te bu son işlemin verimli bir karşılığı yoktur.

from collections import OrderedDict

d = OrderedDict.fromkeys('abcde')
d.move_to_end('b')
print(''.join(d))          # çıktı: acdeb
d.move_to_end('b', last=False)
print(''.join(d))          # çıktı: bacde
print(d.popitem(last=False))   # çıktı: ('b', None)

print(OrderedDict(a=1, b=2) == OrderedDict(b=2, a=1))   # çıktı: False
print(OrderedDict(a=1, b=2) == {'b': 2, 'a': 1})        # çıktı: True

Bu iki işlem OrderedDict'i en son kullanılanı sona taşıyan, kapasite aşılınca en eski kaydı baştan atan bir LRU (least recently used) önbellek için uygun kılar; belgelerde bu fikri işleyen tarifler yer alır. Fonksiyon sonuçlarını önbelleğe almak için hazır bir çözüm arıyorsanız functools.lru_cache daha kısa bir yoldur; o da itertools ve functools yazısında.

from collections import OrderedDict

onbellek = OrderedDict()
KAPASITE = 2

def kaydet(anahtar, deger):
    onbellek[anahtar] = deger
    onbellek.move_to_end(anahtar)
    if len(onbellek) > KAPASITE:
        onbellek.popitem(last=False)

def oku(anahtar):
    onbellek.move_to_end(anahtar)
    return onbellek[anahtar]

kaydet('a', 1)
kaydet('b', 2)
oku('a')            # 'a' yeniden en son kullanılan oldu
kaydet('c', 3)      # kapasite aşıldı, en eski olan 'b' atılır
print(list(onbellek))   # çıktı: ['a', 'c']

ChainMap: birden çok sözlüğe tek görünüm

ChainMap birkaç sözlüğü (ya da başka eşlemeyi) kopyalamadan birbirine bağlar ve tek bir güncellenebilir görünüm sunar. Belgelere göre bu, yeni bir sözlük oluşturup art arda update() çağırmaktan çoğu zaman çok daha hızlıdır. Okuma sırasında eşlemeler sırayla aranır ve anahtarın bulunduğu ilk eşlemedeki değer döner. Yazma, güncelleme ve silme ise yalnızca ilk eşleme üzerinde çalışır. Eşlemeler referansla tutulduğu için alttaki bir sözlük değişirse ChainMap değişikliği hemen yansıtır. Belgelerdeki klasik kullanım, komut satırı argümanlarının ortam değişkenlerine, ortam değişkenlerinin de varsayılan ayarlara üstün geldiği katmanlı bir yapılandırmadır.

from collections import ChainMap

varsayilan = {'renk': 'kırmızı', 'kullanici': 'misafir'}
ortam = {'kullanici': 'ece'}
komut_satiri = {'renk': 'mavi'}

ayar = ChainMap(komut_satiri, ortam, varsayilan)
print(ayar['renk'], ayar['kullanici'])   # çıktı: mavi ece
print(list(ayar))                        # çıktı: ['renk', 'kullanici']

ayar['dil'] = 'tr'                       # yazma yalnızca ilk eşlemeye
print(komut_satiri)                      # çıktı: {'renk': 'mavi', 'dil': 'tr'}

varsayilan['tema'] = 'açık'              # alttaki değişiklik görünür
print(ayar['tema'])                      # çıktı: açık

cocuk = ayar.new_child({'renk': 'yeşil'})
print(cocuk['renk'], ayar['renk'])       # çıktı: yeşil mavi
print(cocuk.parents['renk'])             # çıktı: mavi
print(len(cocuk.maps))                   # çıktı: 4

new_child() başa yeni (varsayılan olarak boş) bir eşleme ekleyen yeni bir ChainMap döndürür; üst eşlemelere dokunmadan değiştirilebilen alt bağlamlar kurmak için kullanılır. parents ise ilk eşleme hariç diğerlerini içeren bir ChainMap verir. Belgeler ChainMap'in dolaşılma sırasının eşlemelerin sondan başa taranmasıyla belirlendiğini, yani en sondaki eşlemeden başlayan bir dizi update() ile aynı sırayı verdiğini belirtir. Gerçek uygulamalarda komut satırı katmanı için argparse, ortam değişkenleri için .env dosyası yazılarına bakabilirsiniz.

UserDict, UserList ve UserString

Bu üç sınıf sırasıyla sözlük, liste ve string nesnelerini saran sarmalayıcılardır. Belgelere göre doğrudan dict veya list'ten türetebildiğimiz için bunlara olan ihtiyaç kısmen azaldı; yine de içerik data özelliğinde gerçek bir sözlük, liste ya da string olarak durduğu için kendi davranışını eklediğiniz sınıfları yazmak bazen daha kolaydır. Basit bir özelleştirme için çoğu zaman dict'ten türetip __missing__() gibi tek bir metodu yazmak yeterlidir; örneği sözlük metotları yazısında. Sınıf yazımının temelleri için class ve nesne yazısına bakabilirsiniz.

Uygulamalı mini örnek: erişim günlüğü özeti

Bir web sunucusunun erişim kayıtlarından türetilmiş gibi düşündüğümüz (ip, sayfa) çiftlerini üç yapıyla özetleyelim: Counter en çok ziyaret edilen sayfaları, defaultdict(set) her IP'nin gezdiği farklı sayfaları, deque(maxlen=2) ise son iki kaydı tutuyor.

from collections import Counter, defaultdict, deque

kayitlar = [('10.0.0.1', '/'), ('10.0.0.2', '/blog'), ('10.0.0.1', '/blog'),
            ('10.0.0.3', '/'), ('10.0.0.1', '/'), ('10.0.0.2', '/fiyat')]

sayfa_sayac = Counter(sayfa for _, sayfa in kayitlar)
ip_sayfalari = defaultdict(set)
son_kayitlar = deque(maxlen=2)
for ip, sayfa in kayitlar:
    ip_sayfalari[ip].add(sayfa)
    son_kayitlar.append((ip, sayfa))

print(sayfa_sayac.most_common(2))   # çıktı: [('/', 3), ('/blog', 2)]
for ip in sorted(ip_sayfalari):
    print(ip, sorted(ip_sayfalari[ip]))
# çıktı: 10.0.0.1 ['/', '/blog']
# çıktı: 10.0.0.2 ['/blog', '/fiyat']
# çıktı: 10.0.0.3 ['/']
print(list(son_kayitlar))   # çıktı: [('10.0.0.1', '/'), ('10.0.0.2', '/fiyat')]

Sık yapılan hatalar

• Counter.update()'in değerin üzerine yazdığını sanmak: sayıları toplar.
• Counter'da sayıyı 0 yapınca elemanın silindiğini sanmak: del kullanın ya da +c ile temizleyin.
• defaultdict'te yalnızca bakmak için d[k] yazmak: anahtar oluşur; okumak için get() veya in kullanın.
• defaultdict(list()) yazmak: fabrika olarak fonksiyonun kendisini verin, çağrılmış sonucunu değil: defaultdict(list).
• Kuyruk için listeyle pop(0) kullanmak: deque.popleft() tercih edin.
• deque'nun ortasına sık indeksle erişmek: ortada erişim yavaştır, liste daha uygundur.
• extendleft()'in sırayı koruduğunu sanmak: elemanlar ters sırada eklenir.
• ChainMap'e yazınca alttaki eşlemelerin değiştiğini sanmak: yazma yalnızca ilk eşlemeye yapılır.

Sık Sorulan Sorular

Counter mı defaultdict(int) mi?

İkisi de saymak için kullanılabilir. defaultdict(int) eksik anahtara 0 ekleyen genel amaçlı bir sözlüktür. Counter ise sayma için özel metotlar (most_common(), elements(), total()) ve çoklu küme aritmetiği sunar; ayrıca eksik anahtarı okurken sözlüğe eklemez, yalnızca 0 döndürür. Sayım sonucu üzerinde işlem yapacaksanız Counter daha uygundur.

namedtuple mı dataclass mı?

Değişmez, hafif, tuple gibi açılabilen ve hash edilebilen kayıtlar için namedtuple; alanları değiştirilebilen, metot eklemeyi kolaylaştıran ve tuple olmayan sınıflar için dataclass uygundur. collections belgeleri de isimli tuple bölümünün sonunda dataclasses modülünü alternatif olarak anar.

deque iş parçacıkları arasında güvenli mi?

Belgeler deque'nun iki uçtan ekleme ve çıkarma işlemlerinin iş parçacığı güvenli (thread-safe) olduğunu belirtir. Üretici ve tüketicilerin birbirini beklemesi gereken senaryolarda ise queue modülü daha uygun araçlar sunar; eşzamanlılık için threading ve multiprocessing yazısına bakabilirsiniz.

Counter sonucunu sözlüğe veya listeye nasıl çeviririm?

Counter bir sözlük alt sınıfı olduğu için dict(c) normal sözlük, list(c) benzersiz elemanların listesi, set(c) küme, c.items() ise (eleman, sayı) çiftlerini verir. Belgelerdeki kalıplar listesinde en az geçen n eleman için c.most_common()[:-n-1:-1] dilimi de yer alır.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Python öğrenme rehberi · Sözlük metotları · Liste ve kuyruk · Tuple · dataclasses · itertools ve functools