← Blog · 15 kwietnia 2026 · Zespół ConvertCaseHQ · 6 min czytania

Nazewnictwo w Pythonie (PEP 8): snake_case dla zmiennych i funkcji

PEP 8 mówi, że nazwy funkcji i zmiennych powinny być pisane małymi literami, a wyrazy rozdzielane podkreślnikami tam, gdzie poprawia to czytelność. To właśnie snake_case: total_price, send_invoice(). Klasy używają CapWords (InvoiceSender), stałe pisze się wielkimi literami z podkreślnikami (MAX_RETRIES), a moduły dostają krótkie nazwy zapisane samymi małymi literami. To obejmuje większość Pythona, który napiszesz.

Resztę sekcji o nazewnictwie w PEP 8 wypełniają przydatne szczegóły: co oznaczają podkreślniki na początku i na końcu nazwy, jak traktować skróty, których pojedynczych liter unikać i kiedy złamanie reguł jest dobrym wyborem. Wszystko poniżej sprawdziliśmy w samym PEP 8, a to, co stoi w cudzysłowie, to oryginalne brzmienie PEP 8 (z naszym tłumaczeniem w nawiasie).

Konwencje nazewnictwa PEP 8 w skrócie

Oto większość tej tabeli w jednym małym module:

# billing.py
MAX_RETRIES = 3
_rate_cache = {}


class PaymentDeclinedError(Exception):
    pass


class InvoiceSender:
    def __init__(self, smtp_host):
        self.smtp_host = smtp_host
        self._attempts = 0

    def send_invoice(self, invoice_id):
        self._attempts += 1
        ...

    @classmethod
    def from_settings(cls, settings):
        return cls(settings["smtp_host"])

Warto znać dwa rzadsze wiersze. Zmienne typów mogą mieć przyrostek _co lub _contra, oznaczający kowariancję lub kontrawariancję, jak w VT_co = TypeVar('VT_co', covariant=True). A zmienne globalne podlegają regułom dla funkcji; jeśli moduł ma być używany z from module import *, PEP 8 zaleca wymienić jego nazwy publiczne w __all__.

Po co w ogóle snake_case?

PEP 8 pochodzi z lipca 2001 roku, a jako autorów wymienia Guido van Rossuma, Barry'ego Warsawa i Alyssę Coghlan. Jego punkt wyjścia to obserwacja Guido: kod czyta się znacznie częściej, niż się go pisze. Reguły nazewnictwa służą temu celowi. Podkreślniki zachowują widoczne granice wyrazów nawet w długich nazwach (days_since_last_login), a podział na wartości w snake_case i klasy w CapWords mówi, czym jest dana nazwa, zanim ją sprawdzisz. PEP 8 ustala też nadrzędną zasadę dla publicznych API: nazwy powinny odzwierciedlać to, jak coś jest używane, a nie jak jest zaimplementowane.

Co oznaczają podkreślniki

Python nie ma słowa kluczowego private, więc z konwencji tę rolę pełnią podkreślniki. PEP 8 rozpoznaje cztery formy:

• _single_leading: słaby sygnał „internal use” (do użytku wewnętrznego). from module import * pomija te nazwy, ale nic poza tym nie powstrzymuje nikogo przed ich używaniem.
• single_trailing_: pozwala uniknąć konfliktu ze słowem kluczowym. class_ jest lepsze niż clss, choć PEP 8 zauważa, że jeszcze lepszy może być synonim.
• __double_leading: wewnątrz klasy uruchamia name mangling (zniekształcanie nazw). PEP 8 sugeruje to tylko po to, by uniknąć konfliktów z atrybutami w podklasach, i przyznaje, że niektórzy tego nie lubią.
• __double_leading_and_trailing__: nazwy „magic” (magiczne), takie jak __init__ i __file__. PEP 8 mówi, żeby nigdy ich nie wymyślać; używaj tylko udokumentowanych.

Name mangling zaskakuje ludzi, którzy traktują je jak ochronę prywatności. To zmiana nazwy, a nie zamek:

class Account:
    def __init__(self):
        self.__pin = "1234"

acct = Account()
acct.__pin            # AttributeError
acct._Account__pin    # "1234": the mangled name still works

Stałe to konwencja, a nie reguła

Zapisanie nazwy wielkimi literami nie powstrzyma nikogo przed jej ponownym przypisaniem; Python chętnie uruchomi MAX_RETRIES = 4. Jeśli chcesz, żeby wymuszało to narzędzie, opatrz nazwę adnotacją typing.Final:

from typing import Final

MAX_RETRIES: Final = 3
MAX_RETRIES = 4  # still runs, but mypy reports:
                 # Cannot assign to final name "MAX_RETRIES"

Składowe enuma to drugie miejsce, w którym pojawiają się wielkie litery. Przewodnik enum HOWTO z dokumentacji Pythona zdecydowanie zaleca nazwy składowych w UPPER_CASE, po części dlatego, że enumy reprezentują stałe, a po części, by uniknąć konfliktów z nazwami metod: class Color(Enum) ze składowymi RED i GREEN.

Skróty, pojedyncze litery i inne przypadki brzegowe

Skróty w nazwach klas

PEP 8 mówi, by w CapWords pisać wielkimi literami każdą literę skrótu, więc HTTPServerError jest lepsze niż HttpServerError. Biblioteka standardowa stosuje to w takich miejscach jak http.server.HTTPServer i json.JSONDecodeError. W snake_case skróty po prostu idą małymi literami: parse_json, http_status.

Ma to znaczenie, jeśli zmieniasz nazwy narzędziem. Nasz konwerter wielkości liter zamienia processOrder na process_order, a HTTPServerError na http_server_error, co jest dokładnie tym, czego wymaga snake_case. Ale jego wynik w PascalCase zapisuje skróty jak zwykłe wyrazy, więc HTTP server error wychodzi jako HttpServerError i wielkie litery trzeba poprawić ręcznie, żeby zgadzały się z PEP 8.

Litery, których należy unikać

Nigdy nie używaj l (małe L), O (wielkie o) ani I (wielkie i) jako nazw jednoznakowych. W niektórych krojach pisma nie da się ich odróżnić od 1 i 0.

mixedCase

Nazwy funkcji w camelCase są dozwolone tylko tam, gdzie jest to już dominujący styl, ze względu na zgodność wsteczną. Własny przykład PEP 8 to moduł threading.

Dlaczego biblioteka standardowa łamie własne reguły

PEP 8 przyznaje, że nazewnictwo w bibliotece Pythona to „a bit of a mess” (trochę bałagan). Spotkasz logging.getLogger() i assertEqual() z unittest w mixedCase oraz klasy pisane małymi literami, takie jak datetime.datetime. Typy wbudowane, jak list i dict, są pisane małymi literami celowo: PEP 8 opisuje odrębną konwencję dla elementów wbudowanych, w której CapWords służy tylko do nazw wyjątków i stałych wbudowanych.

Dwie reguły z PEP 8 wyjaśniają, dlaczego te nazwy w większości zostają, jakie są. Po pierwsze, gdy istniejąca biblioteka ma inny styl, preferowana jest spójność wewnętrzna. Po drugie, sekcja zatytułowana „A Foolish Consistency is the Hobgoblin of Little Minds” (Głupia konsekwencja to straszak małych umysłów): spójność z PEP 8 jest ważna, spójność w projekcie ważniejsza, a spójność w module lub funkcji najważniejsza. Nie łam zgodności wstecznej tylko po to, żeby się dostosować. Dlatego klasa testowa unittest nadal definiuje setUp(): framework wywołuje dokładnie tę nazwę.

Sprawdzaj nazwy automatycznie za pomocą Ruffa lub pep8-naming

Nie musisz przeglądać nazw na oko. Wtyczka flake8 pep8-naming je sprawdza, a Ruff implementuje te same kontrole jako reguły N. Dla takiego pliku:

maxRetries = 3


class order_processor:
    def processOrder(self, orderId):
        totalPrice = 0
        return totalPrice


class InvalidOrder(Exception):
    pass

Ruff oznacza w nim każdą nazwę:

$ ruff check --select N --output-format concise orders.py
orders.py:1:1: N816 Variable `maxRetries` in global scope should not be mixedCase
orders.py:4:7: N801 Class name `order_processor` should use CapWords convention
orders.py:5:9: N802 Function name `processOrder` should be lowercase
orders.py:5:28: N803 Argument name `orderId` should be lowercase
orders.py:6:9: N806 Variable `totalPrice` in function should be lowercase
orders.py:10:7: N818 Exception name `InvalidOrder` should be named with an Error suffix
Found 6 errors.

Aby włączyć te reguły w całym projekcie, dodaj je do pyproject.toml:

[tool.ruff.lint]
extend-select = ["N"]

Gdy zmieniasz nazwę jednego identyfikatora w wklejonym pliku, nasze narzędzie Znajdź i zamień pokazuje, ile dopasowań zmieniło, co jest szybkim sprawdzianem, zanim wkleisz wynik z powrotem. W całej bazie kodu użyj zamiast tego refaktoryzacji zmiany nazwy w edytorze, żeby odwołania w innych plikach poszły za zmianą.

Lista kontrolna nazewnictwa PEP 8

• snake_case dla funkcji, metod, zmiennych i argumentów.
• CapWords dla klas, ze skrótami pisanymi wielkimi literami i końcówką Error w wyjątkach.
• Wielkie litery z podkreślnikami dla stałych na poziomie modułu, plus Final, jeśli chcesz, by sprawdzało to narzędzie.
• Krótkie nazwy modułów małymi literami; unikaj podkreślników w nazwach pakietów.
• Jeden podkreślnik na początku dla nazw wewnętrznych; podwójne tylko po to, by uniknąć konfliktów w podklasach.
• Gdy istniejąca biblioteka używa innego stylu, dopasuj się do biblioteki.

Przechodzisz między językami? Nasza ściągawka dla programistów zestawia reguły Pythona z JavaScriptem, Javą, Go, Rustem i innymi językami.