Python'da UUID v4 Oluşturma — uuid.uuid4()

Bir veritabanı satırı, API izi veya oturum belirteci için çakışmaya dirençli bir tanımlayıcıya her ihtiyaç duyduğumda yanıt aynı oluyor: Python'da UUID v4 oluştur — tek satır, sıfır bağımlılık: uuid.uuid4(). Python'ın yerleşik uuid modülü kriptografik olarak güvenli rastgelelik için os.urandom() kullanır. Kod yazmadan hızlıca UUID almak için çevrimiçi UUID v4 üreteci anında çalışır. Bu kılavuz UUID nesnesinin niteliklerini, toplu oluşturmayı, JSON serileştirmeyi, veritabanı depolamayı, doğrulamayı, uuid-utils (~10× daha hızlı Rust destekli alternatif) ve en yaygın dört hatayı — tümünü Python 3.8+ ile — kapsamaktadır.

UUID v4 Nedir?

UUID (Evrensel Benzersiz Tanımlayıcı), 32 onaltılık basamağın tirelerle beş gruba ayrıldığı 128 bitlik bir etikettir: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Sürüm 4, en yaygın kullanılan varyanttır: 128 bitin 122'si rastgele üretilir, kalan 6 bit ise sürümü (4) ve varyantı (RFC 4122) kodlar. Zaman damgası veya ana makine tanımlayıcısı bulunmaz — tanımlayıcı tamamen belirsiz ve gizlilik açısından güvenlidir. Bağımsız olarak üretilen iki v4 UUID'nin çakışma olasılığı, saniyede milyonlarca kimlik üreten dağıtık sistemlerde bile pratikte sıfıra eşdeğerdir.

event_id = "evt-" + str(random.randint(100000, 999999))  # fragile, not unique

event_id = str(uuid.uuid4())  # 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e

uuid.uuid4() — Python'da UUID v4 Oluşturmanın Standart Yolu

uuid modülü Python'ın standart kütüphanesinin bir parçasıdır. uuid.uuid4() çağrısı, farklı gösterimler için tam bir nitelik kümesine sahip bir uuid.UUID nesnesi döndürür. str() ile dizeye dönüştürmek, API'lerin, veritabanlarının ve HTTP başlıklarının beklediği standart tireli biçimi üretir.

import uuid

# UUID v4 oluştur
request_id = uuid.uuid4()

print(request_id)           # 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(type(request_id))     # <class 'uuid.UUID'>
print(request_id.version)   # 4

# JSON / HTTP başlıkları için dizeye dönüştür
print(str(request_id))      # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
print(request_id.hex)       # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e" (tiresiz)
print(request_id.bytes)     # b';...' (16 ham bayt)

Gerçek dünyada yaygın bir örüntü, günlükleri servisler arasında ilişkilendirebilmek için her giden API isteğine bir UUID eklemektir. İşte her çağrıya yeni bir UUID enjekte eden minimal bir requests oturum sarmalayıcısı:

import uuid
import requests

def call_api(endpoint: str, payload: dict) -> dict:
    trace_id = str(uuid.uuid4())
    headers = {
        "X-Request-ID": trace_id,
        "Content-Type": "application/json",
    }
    response = requests.post(endpoint, json=payload, headers=headers, timeout=10)
    response.raise_for_status()
    return {"trace_id": trace_id, "data": response.json()}

# result["trace_id"], tüm servis günlüklerinde tam isteği grep'lemenizi sağlar
result = call_api("https://api.example.com/v1/orders", {"product_id": "prod_7x2k", "qty": 3})
print(result["trace_id"])  # örn. "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"

UUID'leri toplu oluştururken — örneğin bir veritabanı satırı grubunu önceden doldurmak için — liste kavrayışı deyimsel ve okunabilirdir:

import uuid

# 1000 telemetri olayı için kimlik önceden oluştur
event_ids = [str(uuid.uuid4()) for _ in range(1000)]
print(f"Generated {len(event_ids)} unique IDs")
print(event_ids[0])   # örn. "a1c2e3f4-..."
print(event_ids[-1])  # her seferinde farklı değer

Kod çalıştırmadan hızlıca bir UUID'ye mi ihtiyacınız var? Çevrimiçi UUID v4 üretecini kullanarak tek tıkla yeni bir değer kopyalayın veya aynı anda yüzlerce UUID oluşturun — test veritabanlarını başlatmak veya fikstür dosyalarını doldurmak için kullanışlıdır.

UUID Nesne Nitelikleri ve Gösterimleri

uuid.UUID nesnesi, aynı 128 bitlik değerin birden fazla gösterimini sunar. Depolama katmanınız için doğru olanı seçmek, sessiz veri bozulmalarını ve boşa harcanan baytları önler.

import uuid

u = uuid.uuid4()

print(str(u))         # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"  (36 karakter)
print(u.hex)          # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e"      (32 karakter, tiresiz)
print(u.bytes)        # b';Š...'                       (16 bayt, büyük-endian)
print(u.bytes_le)     # b'Š...'                       (16 bayt, küçük-endian)
print(u.int)          # 78823... (128 bitlik tam sayı)
print(u.version)      # 4
print(u.variant)      # 'specified in RFC 4122'

# Gidiş-dönüş: dizeden yeniden oluştur
reconstructed = uuid.UUID("3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e")
print(reconstructed == u)  # True (u bu değerse)

psycopg2 veya asyncpg kullanan PostgreSQL için UUID nesnesini doğrudan aktarın — sürücü bunu yerel uuid sütun türüyle eşleştirir. SQLite için str(u) (TEXT) veya u.bytes (BLOB, dizeye göre 16 bayt) kullanın. Ölçekte depolama verimliliği için .bytes standart dizeye göre %55 daha küçüktür.

Python'da UUID v4 Dizelerini Doğrulama ve Ayrıştırma

Kullanıcı girdisinden, URL yolu parametresinden veya yukarı akış bir API'den gelen bir UUID'yi, veritabanı anahtarı olarak kullanmadan önce doğrulamanız gerekir. Deyimsel yaklaşım, uuid.UUID() ile oluşturmayı denemek ve ValueError'ı yakalamaktır. Gelen değerin özellikle sürüm 4 olduğunu da .version kontrolüyle zorunlu kılabilirsiniz.

import uuid

def parse_uuid4(raw: str) -> uuid.UUID:
    """
    Bir UUID v4 dizesini ayrıştırır ve doğrular.
    Geçersiz biçim veya yanlış sürüm için ValueError fırlatır.
    """
    try:
        u = uuid.UUID(raw)
    except ValueError as exc:
        raise ValueError(f"Invalid UUID format: {raw!r}") from exc

    if u.version != 4:
        raise ValueError(f"Expected UUID v4, got v{u.version}: {raw!r}")

    return u

# FastAPI / Flask rota işleyicisinde kullanım
def get_order(order_id: str):
    try:
        uid = parse_uuid4(order_id)
    except ValueError as exc:
        return {"error": str(exc)}, 400

    # uid artık DB sorgusunda güvenle kullanılabilir
    return {"order_id": str(uid), "status": "processing"}

JSON Yüklerinde ve API Yanıtlarında UUID v4

JSON standardında UUID türü yoktur — JSON'daki bir UUID her zaman bir dizedir. Bu, json.dumps()'a aktarmadan önce uuid.UUID nesnesini bir dizeye dönüştürmeniz gerektiği anlamına gelir. En temiz yaklaşım, özel bir JSONEncoder alt sınıfıdır; böylece kod tabanınıza str() çağrıları dağıtmak zorunda kalmazsınız.

import json
import uuid
from datetime import datetime

class ApiEncoder(json.JSONEncoder):
    """JSON yanıtlarında UUID ve datetime nesnelerini serileştirir."""
    def default(self, obj):
        if isinstance(obj, uuid.UUID):
            return str(obj)
        if isinstance(obj, datetime):
            return obj.isoformat()
        return super().default(obj)

# İç içe UUID'ler içeren gerçekçi API yanıtı
api_response = {
    "request_id": uuid.uuid4(),
    "created_at": datetime(2026, 3, 14, 9, 41, 0),
    "order": {
        "id": uuid.uuid4(),
        "customer_id": uuid.uuid4(),
        "items": [
            {"product_id": uuid.uuid4(), "sku": "NVX-9000", "qty": 2},
        ],
    },
}

print(json.dumps(api_response, indent=2, cls=ApiEncoder))
# {
#   "request_id": "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e",
#   "created_at": "2026-03-14T09:41:00",
#   "order": {
#     "id": "a1c2e3f4-...",
#     ...
#   }
# }

Tek seferlik bir serileştirme çağrısı için alt sınıf oluşturmaktan daha basit olan default= kancası yeterlidir:

import json, uuid

event_id = uuid.uuid4()
payload = {"event_id": event_id, "action": "checkout"}

# Çağrılabilir bir nesne geçirin; yalnızca json'ın işleyemediği türler için çağrılır
json_str = json.dumps(payload, default=str)
print(json_str)  # {"event_id": "3b1f8a9d-...", "action": "checkout"}

Harici bir API'den yanıt alırken, kodunuzun tam nitelik kümesine ve tür güvenliğine kavuşabilmesi için UUID dizelerini yeniden nesneye dönüştürün:

import json
import uuid
import requests

def fetch_shipment(shipment_id: str) -> dict:
    """Bir sevkiyatı getirir ve UUID alanlarını tiplenmiş olarak döndürür."""
    response = requests.get(
        f"https://api.logistics.example.com/v2/shipments/{shipment_id}",
        headers={"Accept": "application/json"},
        timeout=10,
    )
    response.raise_for_status()
    data = response.json()

    # UUID alanlarını uuid.UUID nesnelerine geri dönüştür
    try:
        data["id"] = uuid.UUID(data["id"])
        data["carrier_id"] = uuid.UUID(data["carrier_id"])
    except (KeyError, ValueError) as exc:
        raise RuntimeError(f"Malformed shipment response: {exc}") from exc

    return data

Diskteki bir JSON dosyasındaki UUID alanlarını güncellemek için — örneğin bir yapılandırma veya başlangıç dosyasındaki bağıntı kimliğini döndürmek — atomik olarak okuyun, değiştirin ve geri yazın:

import json, uuid

def rotate_correlation_id(path: str) -> str:
    """Bir JSON dosyasındaki 'correlation_id'yi değiştirir veya ekler. Yeni UUID'yi döndürür."""
    try:
        with open(path) as f:
            data = json.load(f)
    except FileNotFoundError:
        data = {}
    except json.JSONDecodeError as exc:
        raise ValueError(f"Invalid JSON in {path!r}: {exc}") from exc

    new_id = str(uuid.uuid4())
    data["correlation_id"] = new_id

    with open(path, "w") as f:
        json.dump(data, f, indent=2)

    return new_id

Bir API yanıtından gelen UUID'yi incelemek için her seferinde betik çalıştırmak istemiyorsanız, doğrudan UUID Decoder'a yapıştırın — sürümü, varyantı ve tüm alanları kod yazmadan gösterir.

Python ile Komut Satırından UUID v4 Oluşturma

Python'ın uuid modülü, python -m json.tool gibi bağımsız bir CLI alt komutu sunmaz; ancak tek satırlık komutlar aynı ihtiyacı karşılar. Bunlar kabuk betiklerinde, CI boru hatlarında ve REPL açmadan tek kullanımlık bir tanımlayıcıya ihtiyaç duyduğunuzda kullanışlıdır.

# Tek UUID v4
python3 -c "import uuid; print(uuid.uuid4())"
# 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e

# Tiresiz (hex) biçim — dosya adları ve ortam değişkenleri için kullanışlı
python3 -c "import uuid; print(uuid.uuid4().hex)"
# 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e

# Toplu başlangıç betiği için 5 UUID oluştur
python3 -c "import uuid; [print(uuid.uuid4()) for _ in range(5)]"

# Kabuk değişkeninde kullan
DEPLOY_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
echo "Deploying with ID: $DEPLOY_ID"

uuid-utils ile Yüksek Performanslı UUID v4

Standart kütüphanenin uuid.uuid4() fonksiyonu çoğu uygulama için yeterince hızlıdır — çağrı başına birkaç mikrosaniyeyle saniyede binlerce kimlik rahatlıkla üretir. UUID'leri yüksek verimli bir servisin kritik yolunda (toplu eklemeler, ölçekte olay başına telemetri veya yoğun yük altında istek kimliği oluşturma) oluşturuyorsanız, uuid-utils standart kütüphanenin yaklaşık 10 katı hızda kıyaslama yapan Rust destekli doğrudan bir alternatiftir.

pip install uuid-utils

# uuid_utils, stdlib uuid modülünün doğrudan yerine geçebilir
import uuid_utils as uuid

# Stdlib ile aynı API
request_id = uuid.uuid4()
print(request_id)           # 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(request_id))      # standart dize
print(request_id.hex)       # tiresiz hex
print(request_id.version)   # 4

# v7'yi de destekler (zamana göre sıralı, DB birincil anahtarları için harika)
time_ordered_id = uuid.uuid7()
print(time_ordered_id)      # geçerli zaman damgası önekiyle başlar

Veri Sınıflarında ve Pydantic Modellerinde UUID v4

Python veri sınıfları ve Pydantic modelleri UUID alanlarını yerel olarak destekler. UUID'yi otomatik oluşturulan bir varsayılan olarak kullanırken temel örüntü, çağrı sonucunu değil işlev referansınıaktarmaktır — aksi takdirde her örnek aynı UUID'yi paylaşır.

from dataclasses import dataclass, field
import uuid

@dataclass
class WorkerJob:
    job_id: uuid.UUID = field(default_factory=uuid.uuid4)
    worker_id: str = "worker-01"
    payload: dict = field(default_factory=dict)

job1 = WorkerJob(payload={"task": "resize_image", "src": "uploads/img_4932.png"})
job2 = WorkerJob(payload={"task": "send_email",   "to":  "ops@example.com"})

print(job1.job_id)  # örnek başına benzersiz
print(job2.job_id)  # job1.job_id'den farklı
print(job1.job_id == job2.job_id)  # False

from pydantic import BaseModel, Field
import uuid

class OrderEvent(BaseModel):
    event_id: uuid.UUID = Field(default_factory=uuid.uuid4)
    order_id: uuid.UUID
    status: str
    amount_cents: int

event = OrderEvent(
    order_id=uuid.UUID("a1c2e3f4-5b6d-4e7f-8c9d-0a1b2c3d4e5f"),
    status="payment_confirmed",
    amount_cents=4995,
)

print(event.model_dump_json(indent=2))
# {
#   "event_id": "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e",
#   "order_id": "a1c2e3f4-5b6d-4e7f-8c9d-0a1b2c3d4e5f",
#   "status": "payment_confirmed",
#   "amount_cents": 4995
# }
# Pydantic v2, uuid.UUID'yi otomatik olarak dize olarak serileştirir

Python'da UUID v4 Oluştururken Yapılan Yaygın Hatalar

Bu dört örüntünün tamamını kod incelemelerinde ve üretim olaylarında gördüm — hemen hata fırlatmadıkları için gözden kaçırmaları kolaydır.

@dataclass
class Session:
    # YANLIŞ: bir kez değerlendirilir, tüm örnekler bu UUID'yi paylaşır
    session_id: uuid.UUID = uuid.uuid4()

@dataclass
class Session:
    # DOĞRU: fabrika her örnek için çağrılır
    session_id: uuid.UUID = field(default_factory=uuid.uuid4)

# Değerler eşleşse bile False döndürür
if record["session_id"] == "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e":
    revoke_session(record)

target = uuid.UUID("3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e")
if record["session_id"] == target:   # ikisi de uuid.UUID
    revoke_session(record)

# Ya da sınırda her şeyi dizeye normalleştirin:
if str(record["session_id"]) == str(target):
    revoke_session(record)

# "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e" depolar — tiresiz
payload = {"correlation_id": request_id.hex}

# "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e" depolar — standart biçim
payload = {"correlation_id": str(request_id)}

import random, secrets

# UUID değil — uuid.UUID() doğrulamasında başarısız olur
request_id = secrets.token_hex(16)   # "a1b2c3d4e5f6..."
session_id = str(random.random())    # "0.8273..." — hiç de değil

import uuid

request_id = str(uuid.uuid4())  # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
# Geçerli UUID v4, kriptografik olarak güvenli

Python'da UUID Oluşturma Yöntemleri — Hızlı Karşılaştırma

Aşağıdaki tüm yöntemler 128 bitlik tanımlayıcılar üretir; ancak entropi kaynağı, gizlilik özellikleri ve üçüncü taraf kurulum gerektirip gerektirmeme bakımından farklılaşırlar.

Sıralanabilirlik gerektirmeyen web uygulamalarında, dağıtık sistemlerde ve veritabanı birincil anahtarlarında genel amaçlı benzersiz tanımlayıcılar için uuid.uuid4() kullanın. Bilinen bir ad alanı ve isimden türetilen belirleyici kimlikler için — örneğin kanonik bir URL'ye sabit kimlik oluşturmak — uuid.uuid5() (ya da v3) tercih edin. Veritabanı indeksleri için zamana göre sıralı kimliğe ihtiyaç duyduğunuzda (yüksek ekleme hızlarında B-tree indeks sayfa bölünmelerini önler) uuid_utils.uuid7()'ye geçin. Ham oluşturma verimi darboğaz olduğunda ise uuid_utils.uuid4()'e başvurun.

UUID v4 ile UUID v7 — Hangisini Kullanmalısınız?

En yaygın pratik soru, veritabanı birincil anahtarları için UUID v4 mü yoksa daha yeni UUID v7 mi kullanılması gerektiğidir. Kısa yanıt şu: varsayılan olarak UUID v4 kullanın; UUID v7'ye yalnızca indeks parçalanması ölçülen bir sorun haline geldiğinde geçin.

UUID v4 değerleri tamamen rastgeledir; bu nedenle eklemeler B-tree indeksinde rastgele konumlara düşer. Orta düzey ekleme hızlarında (saniyede yüzlerden düşük binlere kadar) bu sorun değildir — indeks tampon havuzuna sığar ve rastgele yazmalar ucuzdur. Çok yüksek ekleme hızlarında ise rastgele yerleşim sık sayfa bölünmelerine ve önbellek isabetsizliklerine neden olur; bu da yazma yükünü artırır ve sorguları yavaşlatır.

UUID v7, en anlamlı bitlere milisaniye hassasiyetli bir Unix zaman damgası yerleştirir; böylece zamana yakın eklenen satırlar indekste de birbirine yakın konumlarda yer alır. Bu, B-tree indekslerine (PostgreSQL, MySQL, SQLite) otomatik artış tam sayısına benzer bir davranış kazandırır: yeni satırlar her zaman indeksin sonuna eklenir, sayfa bölünmelerini ortadan kaldırır. Takas olarak UUID v7 bir zaman damgası kodladığından, oluşturma zamanının hassas olduğu kullanıcıya dönük kimliklerden kaçının.

Python'da UUID v7, Python 3.12 itibarıyla henüz standart kütüphanede yer almamaktadır. pip install uuid-utils ile kurun ve uuid_utils.uuid7()'yi çağırın. Döndürülen nesne, uuid.UUID ile aynı nitelik kümesine sahiptir; dolayısıyla v4'ten geçiş, kimlik fabrikasında tek satırlık bir değişikliktir.

Herhangi bir Python kurulumu olmadan tek tıklık bir alternatif için UUID dizenizi UUID v4 üretici ve doğrulayıcısına yapıştırın — tarayıcıda tüm alanları oluşturur, doğrular ve çözümler.

Sıkça Sorulan Sorular

import uuid

session_id = uuid.uuid4()
print(session_id)           # örn. 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(session_id))      # aynı standart dize
print(session_id.hex)       # 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e (tiresiz)

import uuid

u = uuid.uuid4()
print(type(u))          # <class 'uuid.UUID'>
print(u.version)        # 4
print(u.hex)            # 32 karakterlik hex, tiresiz
print(u.bytes)          # 16 baytlık ikili veri
print(str(u))           # tireli 36 karakterlik standart dize

import uuid, os

# uuid4 dahili olarak os.urandom(16) çağırır
raw = os.urandom(16)
# uuid4 döndürmeden önce sürüm ve varyant bitlerini ayarlar
u = uuid.UUID(bytes=raw, version=4)
print(u)  # ham rastgele baytlardan oluşan geçerli v4 UUID

import uuid

def is_valid_uuid4(value: str) -> bool:
    try:
        u = uuid.UUID(value)
        return u.version == 4
    except ValueError:
        return False

print(is_valid_uuid4("3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"))  # True
print(is_valid_uuid4("not-a-uuid"))                              # False
print(is_valid_uuid4("3b1f8a9d-2c4e-1f6a-8b0d-5e7c9f1a3d2e"))  # False (v1, v4 değil)

import uuid
import sqlite3

conn = sqlite3.connect(":memory:")
conn.execute("CREATE TABLE events (id TEXT PRIMARY KEY, name TEXT)")

event_id = uuid.uuid4()
conn.execute("INSERT INTO events VALUES (?, ?)", (str(event_id), "user_signup"))
conn.commit()

row = conn.execute("SELECT * FROM events").fetchone()
# Saklanan diziden UUID nesnesini yeniden oluştur
retrieved_id = uuid.UUID(row[0])
print(retrieved_id.version)  # 4

import uuid

# Toplu bir istek için 5 benzersiz iz kimliği oluştur
trace_ids = [str(uuid.uuid4()) for _ in range(5)]
for tid in trace_ids:
    print(tid)
# Her satır farklı bir UUID v4'tür

İlgili Araçlar

• →UUID v4 Generator — UUID v4 değerlerini tarayıcıda anında oluşturun — Python ortamına gerek yok. Tek bir değer kopyalayın veya aynı anda yüzlerce UUID toplu olarak oluşturun.
• →UUID v7 Generator — Oluşturulma zamanına göre sıralanabilen UUID v7 değerleri üretin — dizin parçalanmasının önemli olduğu veritabanı birincil anahtarları için idealdir.
• →UUID Decoder — Herhangi bir UUID'yi inceleyin — sürüm, varyant, zaman damgası (v1/v7) ve düğüm alanları — sıfırdan bir ayrıştırıcı yazmadan.
• →JWT Decoder — JWT token'larını çözün ve inceleyin; bu token'lar genellikle oturum UUID'lerinin yanı sıra UUID konu talepleri (sub) veya jti tanımlayıcıları taşır.