Python En İyi Pratikler, İpuçları ve Tasarım Desenleri — Kapsamlı Rehber

# Kötü: iç içe geçmiş koşullar
def process(order):
    if order is not None:
        if order.is_valid():
            if order.total > 0:
                return charge(order)
            else:
                return None
        else:
            return None
    else:
        return None

# İyi: guard clause'lar (düz, açık, okunabilir)
def process(order):
    if order is None:
        return None
    if not order.is_valid():
        return None
    if order.total <= 0:
        return None
    return charge(order)

# Import sırası örneği
import os
import sys
from collections import defaultdict

import numpy as np
import requests

from myapp.core import settings
from myapp.utils import helpers

name = "Ada"
# İyi
greeting = f"Hello, {name}!"
# Kaçının
greeting = "Hello, {}!".format(name)
greeting = "Hello, %s!" % name

from __future__ import annotations
from typing import Optional, Union, Callable, Iterable

def find_user(user_id: int, *, cache: dict[int, "User"] | None = None) -> "User" | None:
    ...

def apply(fn: Callable[[int, int], int], values: Iterable[tuple[int, int]]) -> list[int]:
    return [fn(a, b) for a, b in values]

from typing import Protocol

class SupportsClose(Protocol):
    def close(self) -> None: ...

def cleanup(resource: SupportsClose) -> None:
    resource.close()

from typing import TypedDict

class UserPayload(TypedDict):
    id: int
    name: str
    email: str

from typing import Literal

def set_mode(mode: Literal["r", "w", "a"]) -> None: ...

from typing import TypeVar, Generic

T = TypeVar("T")

class Stack(Generic[T]):
    def __init__(self) -> None:
        self._items: list[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        return self._items.pop()

from collections import Counter, defaultdict, deque

# Sayma
word_counts = Counter("the quick brown fox jumps over the lazy dog".split())
print(word_counts.most_common(2))

# Gruplama
groups: defaultdict[str, list[int]] = defaultdict(list)
for n in range(10):
    groups["even" if n % 2 == 0 else "odd"].append(n)

# Kayan pencere / kuyruk
window = deque(maxlen=3)
for x in range(10):
    window.append(x)

# Kötü: O(n) üyelik kontrolü
valid_ids = [1, 2, 3, 4, 5]
if user_id in valid_ids:
    ...

# İyi: ortalama O(1)
valid_ids = {1, 2, 3, 4, 5}
if user_id in valid_ids:
    ...

first, *rest = [1, 2, 3, 4]
*init, last = [1, 2, 3, 4]
a, (b, c) = 1, (2, 3)

# Geçici değişken olmadan takas
a, b = b, a

value = data.get("key", "default")
data.setdefault("key", []).append(item)

# Walrus operatörü (3.8+) çift hesaplamayı önler
if (n := len(data)) > 10:
    print(f"Too many items: {n}")

# Kötü — liste çağrılar arasında paylaşılır!
def append_item(item, items=[]):
    items.append(item)
    return items

# İyi
def append_item(item, items: list | None = None):
    if items is None:
        items = []
    items.append(item)
    return items

def create_user(*, name: str, email: str, is_admin: bool = False) -> "User":
    ...

create_user(name="Ada", email="[email protected]", is_admin=True)

def add(a: int, b: int, /) -> int:
    return a + b

def calculate_discount(price: float, percentage: float) -> float:
    """Calculate the discounted price.

    Args:
        price: The original price.
        percentage: Discount percentage (0-100).

    Returns:
        The price after discount is applied.

    Raises:
        ValueError: If percentage is not between 0 and 100.
    """
    if not 0 <= percentage <= 100:
        raise ValueError("percentage must be between 0 and 100")
    return price * (1 - percentage / 100)

# List comprehension
squares = [x**2 for x in range(10)]

# Set comprehension
unique_lengths = {len(word) for word in ["a", "bb", "ccc", "dd"]}

# Dict comprehension
name_to_len = {name: len(name) for name in ["Ada", "Grace", "Alan"]}

# İç içe comprehension (matrisi düzleştirme)
matrix = [[1, 2], [3, 4]]
flat = [x for row in matrix for x in row]

# Koşullu comprehension
evens = [x for x in range(20) if x % 2 == 0]

# Generator ifadesi — tembel (lazy), bellek dostu
total = sum(x**2 for x in range(1_000_000))

# Fazla akıllıca — okunması zor
result = [y for x in data if x > 0 for y in transform(x) if y is not None]

# Daha iyi
def transform_positive(data):
    for x in data:
        if x <= 0:
            continue
        for y in transform(x):
            if y is not None:
                yield y

def fibonacci():
    a, b = 0, 1
    while True:
        yield a
        a, b = b, a + b

fib = fibonacci()
first_ten = [next(fib) for _ in range(10)]

def flatten(nested):
    for item in nested:
        if isinstance(item, list):
            yield from flatten(item)
        else:
            yield item

list(flatten([1, [2, 3, [4, 5]], 6]))  # [1, 2, 3, 4, 5, 6]

class Range:
    def __init__(self, start: int, stop: int) -> None:
        self.current = start
        self.stop = stop

    def __iter__(self) -> "Range":
        return self

    def __next__(self) -> int:
        if self.current >= self.stop:
            raise StopIteration
        value = self.current
        self.current += 1
        return value

with open("data.txt") as f:
    content = f.read()

# Birden fazla context manager
with open("in.txt") as fin, open("out.txt", "w") as fout:
    fout.write(fin.read())

class Timer:
    def __enter__(self):
        import time
        self.start = time.perf_counter()
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        import time
        self.elapsed = time.perf_counter() - self.start
        return False  # exception'ları yaymaya devam et

from contextlib import contextmanager

@contextmanager
def timer():
    import time
    start = time.perf_counter()
    try:
        yield
    finally:
        print(f"Elapsed: {time.perf_counter() - start:.4f}s")

with timer():
    do_expensive_work()

from contextlib import suppress

with suppress(FileNotFoundError):
    os.remove("maybe_missing.txt")

from contextlib import ExitStack

with ExitStack() as stack:
    files = [stack.enter_context(open(fname)) for fname in filenames]
    # tüm dosyalar exception olsa bile çıkışta otomatik kapanır

import functools
import time

def timed(func):
    @functools.wraps(func)  # __name__, __doc__ vb. korur
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        print(f"{func.__name__} took {time.perf_counter() - start:.4f}s")
        return result
    return wrapper

@timed
def slow_function():
    time.sleep(1)

def retry(times: int = 3, exceptions: tuple = (Exception,)):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            last_exc = None
            for attempt in range(times):
                try:
                    return func(*args, **kwargs)
                except exceptions as e:
                    last_exc = e
            raise last_exc
        return wrapper
    return decorator

@retry(times=5, exceptions=(ConnectionError,))
def fetch_data():
    ...

from functools import lru_cache, cache

@lru_cache(maxsize=128)
def fib(n: int) -> int:
    return n if n < 2 else fib(n - 1) + fib(n - 2)

@cache  # sınırsız önbellek, Python 3.9+
def expensive_lookup(key: str) -> str:
    ...

class Point:
    __slots__ = ("x", "y")

    def __init__(self, x: float, y: float) -> None:
        self.x = x
        self.y = y

class Point:
    def __init__(self, x: float, y: float) -> None:
        self.x = x
        self.y = y

    def __repr__(self) -> str:
        return f"Point(x={self.x!r}, y={self.y!r})"

    def __eq__(self, other: object) -> bool:
        if not isinstance(other, Point):
            return NotImplemented
        return (self.x, self.y) == (other.x, other.y)

    def __hash__(self) -> int:
        return hash((self.x, self.y))

class Temperature:
    def __init__(self, celsius: float) -> None:
        self._celsius = celsius

    @property
    def celsius(self) -> float:
        return self._celsius

    @celsius.setter
    def celsius(self, value: float) -> None:
        if value < -273.15:
            raise ValueError("Below absolute zero")
        self._celsius = value

    @property
    def fahrenheit(self) -> float:
        return self._celsius * 9 / 5 + 32

class User:
    def __init__(self, name: str, email: str) -> None:
        self.name = name
        self.email = email

    @classmethod
    def from_dict(cls, data: dict) -> "User":
        return cls(name=data["name"], email=data["email"])

    @staticmethod
    def is_valid_email(email: str) -> bool:
        return "@" in email

from abc import ABC, abstractmethod

class PaymentProcessor(ABC):
    @abstractmethod
    def charge(self, amount: float) -> bool: ...

class StripeProcessor(PaymentProcessor):
    def charge(self, amount: float) -> bool:
        ...

from dataclasses import dataclass, field

@dataclass(frozen=True, slots=True)
class Point:
    x: float
    y: float

@dataclass
class Order:
    items: list[str] = field(default_factory=list)
    total: float = 0.0

    def add_item(self, item: str, price: float) -> None:
        self.items.append(item)
        self.total += price

from typing import NamedTuple

class Point(NamedTuple):
    x: float
    y: float

p = Point(1.0, 2.0)
x, y = p  # tuple unpacking çalışır

# Kötü
try:
    risky()
except:
    pass

# İyi
try:
    risky()
except (ConnectionError, TimeoutError) as e:
    logger.warning("Network issue: %s", e)
    raise

class AppError(Exception):
    """Base exception for this application."""

class ValidationError(AppError):
    """Raised when input validation fails."""

class NotFoundError(AppError):
    """Raised when a resource is not found."""

try:
    parse(data)
except ValueError as e:
    raise ValidationError("Invalid input") from e

try:
    conn = connect()
except ConnectionError:
    logger.error("Could not connect")
else:
    # yalnızca exception fırlatılmadıysa çalışır
    process(conn)
finally:
    # her zaman çalışır — temizlik
    conn.close()

# Pythonic (EAFP)
try:
    value = my_dict["key"]
except KeyError:
    value = default

# Daha az Pythonic (LBYL) — eşzamanlı kodda race condition'a yatkın
if "key" in my_dict:
    value = my_dict["key"]
else:
    value = default

# mypackage/models/user.py içinde
from ..utils.helpers import normalize_email   # göreli, paket içinde
from mypackage.core import Settings           # mutlak, yine de sorun değil

import asyncio
import aiohttp

async def fetch(session: aiohttp.ClientSession, url: str) -> str:
    async with session.get(url) as resp:
        return await resp.text()

async def main(urls: list[str]) -> list[str]:
    async with aiohttp.ClientSession() as session:
        tasks = [fetch(session, url) for url in urls]
        return await asyncio.gather(*tasks)

asyncio.run(main(["https://example.com"] * 10))

async def main():
    async with asyncio.TaskGroup() as tg:
        task1 = tg.create_task(fetch(url1))
        task2 = tg.create_task(fetch(url2))
    # burada her iki task de garanti olarak tamamlanmıştır; exception'lar ExceptionGroup olarak yayılır

from concurrent.futures import ProcessPoolExecutor

def heavy_computation(n: int) -> int:
    return sum(i * i for i in range(n))

with ProcessPoolExecutor() as executor:
    results = list(executor.map(heavy_computation, [10_000_000] * 4))

# Yavaş: tekrarlanan string kopyalarından dolayı O(n^2)
result = ""
for s in strings:
    result += s

# Hızlı: O(n)
result = "".join(strings)

import timeit
timeit.timeit("'-'.join(str(n) for n in range(100))", number=10000)

def test_calculate_discount():
    assert calculate_discount(100, 10) == 90

def test_calculate_discount_invalid_percentage():
    import pytest
    with pytest.raises(ValueError):
        calculate_discount(100, 150)

import pytest

@pytest.fixture
def sample_user():
    return User(name="Ada", email="[email protected]")

def test_user_email(sample_user):
    assert sample_user.email == "[email protected]"

@pytest.mark.parametrize("price,pct,expected", [
    (100, 0, 100),
    (100, 50, 50),
    (200, 25, 150),
])
def test_discounts(price, pct, expected):
    assert calculate_discount(price, pct) == expected

from unittest.mock import patch

@patch("myapp.services.requests.get")
def test_fetch_user(mock_get):
    mock_get.return_value.json.return_value = {"id": 1, "name": "Ada"}
    result = fetch_user(1)
    assert result["name"] == "Ada"

import logging

logger = logging.getLogger(__name__)

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
)

def process_order(order_id: int) -> None:
    logger.info("Processing order %s", order_id)
    try:
        ...
    except Exception:
        logger.exception("Failed to process order %s", order_id)
        raise

import secrets
token = secrets.token_urlsafe(32)

# Kötü — SQL injection riski
cursor.execute(f"SELECT * FROM users WHERE name = '{name}'")

# İyi — parametreli
cursor.execute("SELECT * FROM users WHERE name = ?", (name,))

class Singleton:
    _instance = None

    def __new__(cls, *args, **kwargs):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

from abc import ABC, abstractmethod

class Notifier(ABC):
    @abstractmethod
    def send(self, message: str) -> None: ...

class EmailNotifier(Notifier):
    def send(self, message: str) -> None:
        print(f"Email: {message}")

class SmsNotifier(Notifier):
    def send(self, message: str) -> None:
        print(f"SMS: {message}")

def notifier_factory(kind: str) -> Notifier:
    return {"email": EmailNotifier, "sms": SmsNotifier}[kind]()

class GUIFactory(ABC):
    @abstractmethod
    def create_button(self) -> "Button": ...
    @abstractmethod
    def create_checkbox(self) -> "Checkbox": ...

class WindowsFactory(GUIFactory):
    def create_button(self): return WindowsButton()
    def create_checkbox(self): return WindowsCheckbox()

class MacFactory(GUIFactory):
    def create_button(self): return MacButton()
    def create_checkbox(self): return MacCheckbox()

class RequestBuilder:
    def __init__(self) -> None:
        self._url = ""
        self._headers: dict[str, str] = {}
        self._method = "GET"

    def url(self, url: str) -> "RequestBuilder":
        self._url = url
        return self

    def header(self, key: str, value: str) -> "RequestBuilder":
        self._headers[key] = value
        return self

    def method(self, method: str) -> "RequestBuilder":
        self._method = method
        return self

    def build(self) -> dict:
        return {"url": self._url, "headers": self._headers, "method": self._method}

request = (
    RequestBuilder()
    .url("https://api.example.com")
    .header("Authorization", "Bearer token")
    .method("POST")
    .build()
)

import copy

class Prototype:
    def clone(self):
        return copy.deepcopy(self)

class OldPrinter:
    def print_old(self, text: str) -> None:
        print(f"[OLD] {text}")

class NewPrinterInterface(ABC):
    @abstractmethod
    def print(self, text: str) -> None: ...

class PrinterAdapter(NewPrinterInterface):
    def __init__(self, old_printer: OldPrinter) -> None:
        self._old_printer = old_printer

    def print(self, text: str) -> None:
        self._old_printer.print_old(text)

class Coffee(ABC):
    @abstractmethod
    def cost(self) -> float: ...

class SimpleCoffee(Coffee):
    def cost(self) -> float:
        return 2.0

class MilkDecorator(Coffee):
    def __init__(self, coffee: Coffee) -> None:
        self._coffee = coffee

    def cost(self) -> float:
        return self._coffee.cost() + 0.5

coffee = MilkDecorator(SimpleCoffee())
print(coffee.cost())  # 2.5

class CPU:
    def freeze(self): ...
    def jump(self, position): ...
    def execute(self): ...

class Memory:
    def load(self, position, data): ...

class ComputerFacade:
    def __init__(self):
        self.cpu = CPU()
        self.memory = Memory()

    def start(self):
        self.cpu.freeze()
        self.memory.load(0, "boot_data")
        self.cpu.jump(0)
        self.cpu.execute()

class RealImage:
    def __init__(self, filename: str) -> None:
        self.filename = filename
        self._load()

    def _load(self) -> None:
        print(f"Loading {self.filename}")

    def display(self) -> None:
        print(f"Displaying {self.filename}")

class ImageProxy:
    def __init__(self, filename: str) -> None:
        self.filename = filename
        self._real_image = None

    def display(self) -> None:
        if self._real_image is None:
            self._real_image = RealImage(self.filename)  # tembel (lazy) yükleme
        self._real_image.display()

class Component(ABC):
    @abstractmethod
    def render(self, indent: int = 0) -> str: ...

class Leaf(Component):
    def __init__(self, name: str) -> None:
        self.name = name

    def render(self, indent: int = 0) -> str:
        return "  " * indent + self.name

class Composite(Component):
    def __init__(self, name: str) -> None:
        self.name = name
        self.children: list[Component] = []

    def add(self, component: Component) -> None:
        self.children.append(component)

    def render(self, indent: int = 0) -> str:
        lines = ["  " * indent + self.name]
        for child in self.children:
            lines.append(child.render(indent + 1))
        return "\n".join(lines)

class Subject:
    def __init__(self) -> None:
        self._observers: list[Callable] = []

    def subscribe(self, observer: Callable) -> None:
        self._observers.append(observer)

    def notify(self, *args, **kwargs) -> None:
        for observer in self._observers:
            observer(*args, **kwargs)

subject = Subject()
subject.subscribe(lambda event: print(f"Received: {event}"))
subject.notify("user_created")

class SortStrategy(ABC):
    @abstractmethod
    def sort(self, data: list) -> list: ...

class QuickSort(SortStrategy):
    def sort(self, data: list) -> list:
        return sorted(data)  # basitleştirilmiş

class Sorter:
    def __init__(self, strategy: SortStrategy) -> None:
        self._strategy = strategy

    def sort(self, data: list) -> list:
        return self._strategy.sort(data)

def sort_data(data: list, strategy: Callable[[list], list] = sorted) -> list:
    return strategy(data)

class Command(ABC):
    @abstractmethod
    def execute(self) -> None: ...
    @abstractmethod
    def undo(self) -> None: ...

class AddTextCommand(Command):
    def __init__(self, document: list[str], text: str) -> None:
        self.document = document
        self.text = text

    def execute(self) -> None:
        self.document.append(self.text)

    def undo(self) -> None:
        self.document.remove(self.text)

class State(ABC):
    @abstractmethod
    def handle(self, context: "TrafficLight") -> None: ...

class RedState(State):
    def handle(self, context):
        print("Red -> Green")
        context.state = GreenState()

class GreenState(State):
    def handle(self, context):
        print("Green -> Red")
        context.state = RedState()

class TrafficLight:
    def __init__(self):
        self.state: State = RedState()

    def change(self):
        self.state.handle(self)

class DataProcessor(ABC):
    def process(self) -> None:
        self.load()
        self.transform()
        self.save()

    @abstractmethod
    def load(self) -> None: ...
    @abstractmethod
    def transform(self) -> None: ...
    @abstractmethod
    def save(self) -> None: ...

class CsvProcessor(DataProcessor):
    def load(self): print("Loading CSV")
    def transform(self): print("Transforming CSV")
    def save(self): print("Saving CSV")

class Handler(ABC):
    def __init__(self) -> None:
        self._next: Handler | None = None

    def set_next(self, handler: "Handler") -> "Handler":
        self._next = handler
        return handler

    def handle(self, request) -> None:
        if self._next:
            self._next.handle(request)

class AuthHandler(Handler):
    def handle(self, request):
        if not request.get("authenticated"):
            print("Auth failed")
            return
        super().handle(request)

# Hata: tüm lambda'lar aynı `i`'yi (son değeri) yakalar
funcs = [lambda: i for i in range(5)]
print([f() for f in funcs])  # [4, 4, 4, 4, 4]

# Çözüm: varsayılan argüman tanım anındaki değeri yakalar
funcs = [lambda i=i: i for i in range(5)]
print([f() for f in funcs])  # [0, 1, 2, 3, 4]

# Hata: bazı öğeler atlanır
for item in my_list:
    if condition(item):
        my_list.remove(item)

# Çözüm: bir kopya üzerinde iterasyon yapın veya yeni bir liste oluşturun
my_list = [item for item in my_list if not condition(item)]

# Kötü
if type(obj) == list:
    ...

# İyi
if isinstance(obj, list):
    ...

# Kırılgan
if shape_type == "circle":
    ...
elif shape_type == "square":
    ...

# Daha iyi: Enum + dispatch dict veya sınıflar aracılığıyla polimorfizm
from enum import Enum, auto

class ShapeType(Enum):
    CIRCLE = auto()
    SQUARE = auto()

[project]
name = "mypackage"
version = "0.1.0"
requires-python = ">=3.11"

[tool.ruff]
line-length = 88
select = ["E", "F", "I", "UP", "B"]

[tool.mypy]
strict = true

[tool.pytest.ini_options]
testpaths = ["tests"]