PEP

Moja ściąga z PEP 8 – część 3

Zalecenia programistyczne:

  • Kod powinien być pisany w sposób, który nie powoduje problemów w innych implementacjach Pythona (PyPy, Jython, IronPython, Pyrex, Psyco i innych)

    Dla przykładu nie należy polegać na implementacji łączenia ciągów “w miejscu” (in-place) w formie a+=b lub a=a+b. Takie deklaracje wykonują się dużo wolniej w Jython. W częściach biblioteki gdzie wydajność jest szczególnie ważna w zamian powinna być użyta konstrukcja ”.join(). Taka konstrukcja daje pewność, że połączenie zdarzy się liniowo w czasie pośród różnych implementacji.

  • Porównania do singletonów takich jak None zawsze powinno być robione przy pomocy is lub is not, nigdy operatorów porównania.

    Wystrzegać należy się pisania if x kiedy ma się na myśli if x is not None — np. kiedy testuje się czy danej zmiennej czy argumentowi, który domyślnie przyjmuje wartość None została przypisana inna wartość. Inne wartości mogą mieć taki typ (tak jak kontener), że jest on fałszywy w kontekście booleanowskim (?).

  • Używać klas wyjątków w Pythonie (class-based exceptions)

    Wyjątki typu string w nowym kodzie są zabronione, ponieważ ta właściwość języka zostanie usunięta w Pythonie 2.6.

    Moduły i pakiety (packages) powinny definiować własne specyficzne dla siebie klasy wyjątków (exception class), które powinny dziedziczyć z wbudowanej (built-in) klasy wyjątków. Zawsze należy zawierać docstringa klasy.

    Mają tutaj również zastosowanie konwencje nazewnictwa klas, chociaż powinno dodawać się sufiks Error do nazwy klasy wyjątku, jeśli wyjątek jest błędem. Wyjątki “nie-błędy” nie potrzebuję specjalnego sufiksu.

          class MessageError(Exception):
          """Base class for errors in the email package."""
  • Kiedy podnosi się wyjątek należy używać raise ValueError(’message’) zamiast starszej formy raise ValueError, ‘message’.

    Forma z nawiasami jest preferowana, ponieważ kiedy argumenty wyjątku są długie lub zawierają formatowanie ciągów nie zachodzi potrzeba używania znaku kontynuacji linii dzięki otoczeniu nawiasami. Starsza forma będzie niedostępna w Pythonie 3000.

  • Podczas przechwytywania wyjątków, należy podać jaki wyjątek się przechwytuje kiedykolwiek to jest możliwe, zamiast używać “czystej” klauzuli except.

    Na przykład:

          try:
          import platform_specific_module
      except ImportError:
          platform_specific_module = None

    Samotna klauzula except przechwyci także wyjątki SystemExit i KeyboardInterrupt, co uczyni trudniejszym przerwanie działania programu przy pomocy i przesłoni inne, nieprzewidziane problemy. W przypadku potrzeby łapania wszystkich wyjątków, które sygnalizują błędy w programie należy używać except Exception

    Dobrą zasadą jest ograniczyć użycie czystego except do dwóch przypadków:

    • Jeśli uchwyt (?) wyjątku będzie drukował log ze śledzenia błędu (traceback), przynajmniej użytkownik będzie świadom, że wystąpił błąd.

    • Jeśli kod wymaga wyczyszczenia, lecz wtedy pozwala wyjątkowi propagować się w górę z raise (?). W takim wypadku try…finally jest lepszym sposobem aby obsłużyć wyjątek.

  • Dodatkowo, dla wszystkich klauzuli try/except należy ograniczać ilość kodu pod klauzulą try do niezbędnego minimum. Również to pomoże unikać błędów.

    Tak:

          try:
          value = collection[key]
      except KeyError:
          return key_not_found(key)
      else:
          return handle_value(value)

    Nie:

          try:
          # Too broad!
          return handle_value(collection[key])
      except KeyError:
          # Will also catch KeyError raised by handle_value()
          return key_not_found(key)
  • Używać metod stringów, a nie modułu string

    Metody stringów są zawsze dużo szybsze i współdzielą to samo API ze stringami unikod.

  • Należy używać ”.startswith() i ”.endswith() zamiast krojenia stringów (string slicing).

    startswith() i endswith() są czystsze i powodują mniej błędów. Na przykład:

    Tak:

          if foo.startswith('bar'):

    Nie:

          if foo[:3] == 'bar':
  • Porównania typów obiektowych powinny zawsze używać konstrukcji isinstance() zamiast porównywać typy bezpośrednio.

    Tak:

          if isinstance(obj, int):

    Nie:

          if type(obj) is type(1):

    Podczas sprawdzania czy obiekt jest stringiem, należy mieć na uwadze, że to również może być string unikodowy! W Pythonie 2.3 string i unikod mają wspólną klasę bazową, basestring, tak więc można zrobić:

          if isinstance(obj, basestring):
  • Dla typów sekwencyjnych, (stringów, list, krotek/tuples/), należy korzystać z faktu, że puste sekwencje są fałszywe.

    Tak:

          if not seq:
      if seq:

    Nie:

          if len(seq)
      if not len(seq)
  • Nie należy pisać stringów, które zawierają znaczący niedrukowalny znak (spacja, tabulator), Niektóre takie znaki nie dają się od siebie odróżnić i niektóre edytory (lub ostatnio, reindent.py) obetną je.
  • Nie wolno porównywać booleanowskich wartości do True lub False używając ==.

    Tak:

          if greeting:

    Nie:

          if greeting == True:

    Jeszcze gorzej:

          if greeting is True:

    Napisane na podstawie PEP 8 . Nie jestem profesjonalistą, ale staram się. Tekst jest pomocą przede wszystkim dla mnie. Jeśli komuś jeszcze będzie on pomocny ucieszę się. Jeszcze bardziej będę zadowolony jeśli ktoś doświadczony tu zajrzy i zechce skomentować to, i tamto.

By grzeszy on Styczeń 27, 2009 | PEP, Python | A comment?
Tagi: ,

Moja ściąga z PEP 8 – część 2

  1. Konwencje nazewnictwa

    1. Nazwy, których należy unikać:
    2. Nazwy pakietów i modułów.
    3. Nazwy klas
    4. Nazwy funkcyj
    5. Argumenty funkcyj i metod
    6. Nazwy zmiennych globalnych
    7. Nazwy metod i zmiennych instancyj
    8. Stałe
    9. Konstrukcja ze względu na dziedziczenie

Konwencje nazewnictwa

Istnieją pewne rekomendowane konwencje nazewnictwa w Pythonie. Konwencje te powinny być stosowane do nowo pisanych modułów. Nowo pisane pakiety i moduły powinny być utrzymane w tych konwencjach. Kiedy starsza biblioteka reprezentuje inny styl to przy jej rozszerzaniu powinien być zachowany pierwotny styl w celu wewnętrznej spójności.

Nazwy, których należy unikać:

Nie używać jako nazw zmiennych liter l (L jak Leszek), O (O jak Olga) oraz I (i jak Irena). W przypadku pewnych krojów czcionek litery te są nieodróżnialne od liczby jeden oraz zero.

Nazwy pakietów i modułów.

Moduły powinny mieć krótką nazwę wyłącznie z małych liter. Podkreślenia mogą być używane w nazwach modułów jeśli poprawi to czytelność. Podobnie jest w przypadku pakietów (ang. package) jednak nie zaleca się stosować podkreśleń.

Ponieważ nazwy modułów są mapowane do nazw plików powinny one być odpowiednio krótkie. Zbyt długie nazwy mogą być problemem na starszych wersjach Mac, Windows oraz w DOS.

Kiedy rozszerzeniu napisanym w C/C++ towarzyszy moduł Pythona dodający interfejs wyższego poziomu (bardzo zorientowany obiektowo), nazwa rozszerzenia w C/C++ powinna rozpoczynać pojedynczym podkreśleniem (np. _socket)

Nazwy klas

Prawie że bez wyjątków, nazwy klas powinny mieć nazwę w konwencji CapsWords. Klasy do użytku wewnętrznego powinno poprzedzać pojedyncze podkreślenie (_CapsWord).

Nazwy funkcyj

Nazwy funkcyj powinny być pisane małymi literami ze słowami rozdzielanymi przez podkreślenia, jeśli to konieczne aby zwiększyć czytelność (nazwa, nazwa_funkcji)

Argumenty funkcyj i metod

Zawsze należy używać self jako pierwszego argumentu do metody instancji. Zawsze należy używać cls jako pierwszego argumentu do metody klasy.

Jeśli nazwa argumentu funkcji koliduje z nazwą słowa kluczowego Pythona, zazwyczaj lepiej jest dołączyć pojedyncze podkreślenie na końcu nazwy niż tworzyć nieczytelne skróty lub celowe literówki. W związku z tym print_ jest lepsze niż prnt. Dobrze jeśli uda się uniknąć konfliktu przez użycie synonimu.

Nazwy zmiennych globalnych

Nazwy zmiennych globalnych podlegają tym samym konwencjom co nazwy funkcyj. (Zaleca się aby używać zmiennych globalnych tylko wewnątrz jednego modułu)

Moduły, które są zaprojektowane aby używać ich przez from module import * powinny zawierać mechanizm __all__ aby zapobiec eksportowaniu zmiennych globalnych lub stosować starszą konwencję dołączania przedrostka – pojedynczego podkreślenia (co można chcieć zrobić by wskazać te zmienne globalne jako “niepubliczne”).

Nazwy metod i zmiennych instancyj

Stosować zasady dotyczące nazw funkcyj.

Poprzedzające pojedyncze podkreślenie dla niepublicznych metod i zmiennych instancji.

Unikać konfliktu nazw z podklasą przez użycie podwójnego poprzedzającego podkreślenia aby wywołać mechanizm dekorowania nazw Pythona (Python’s mangling rules).

Stałe

Stałe są deklarowane na poziomie modułu i pisane wielkimi literami z pokreśleniami jako separatorami słów. Np. MAX_OVERFLOW i TOTAL.

Konstrukcja ze względu na dziedziczenie

Zawsze należy zdecydować czy metody i zmienne instancji (wspólne określenie to atrybuty) mają być publiczne czy niepubliczne. W razie wątpliwości należy uczynić atrybut niepublicznym, później łatwiej zrobić z niego atrybut publiczny niż na odwrót.

Publiczne atrybuty to te, co do których należy się spodziewać, że będą użyte przez niezwiązane klienty, ze “zobowiązaniem”, że zmiany w module/pakiecie nie będą powodowały niekompatybilności wstecz. Niepubliczne atrybuty to te, które nie są tworzone w zamierzeniu do użycia przez programy trzecie. Nie ma potrzeby zapewniać, że niepubliczne atrybuty nie zmienią się lub nawet nie będą usunięte.

Używa się terminu “niepubliczny” gdyż tak na prawdę żaden atrybut w Pythonie nie jest prywatny.

Kolejna kategoria atrybutów to te, które są częścią “podklasowego API” (”subclass API”) – nazywane w innych językach programowania – protected. Niektóre klasy są przeznaczone do dziedziczenia aby rozszerzać lub modyfikować różne aspekty zachowania klasy. Podczas projektowania takiej klasy należy podjąć wyraźne decyzje dotyczące tego jakie atrybuty mają być publiczne, a które są częścią “podklasowego API”, i które będą na prawdę używane tylko przez klasę bazową.

Biorąc pod uwagę powyższe, oto Pythonowe wskazówki.

  • Publiczne atrybuty nie powinny mieć przedniego podkreślenia.
  • Jeśli atrybut koliduje ze słowem kluczowym Pythona, należy dołączyć pojedyncze, kończące podkreślenie.

Zobacz powyższe rekomendacje dla nazewnictwa metod klas.

  • Dla prostych atrybutów z danymi, najlepiej jest ujawnić po prostu nazwę atrybutu bez skomplikowanych metod typu accessor czu mutator. Należy też mieć na uwadze, że Python daje łatwą możliwość rozszerzania funkcjonalności atrybutu jeśli zajdzie taka potrzeba. W takim wypadku używa się właściwości (properties) aby ukryć funkcjonalną implementację atrybutu za prostą składnią dostępu do atrybutu.
    1. Właściwości (properties) działają tylko w nowego typu klasach
    2. ?
    3. Lepiej unikać używania właściwości do drogich obliczeniowo operacji, zapis atrybutu jest traktowany przez wywołującego (caller) jako niewymagający dużych zasobów obliczeniowych.
  • Jeśli klasa w zamierzeniu ma służyć jako przodek (subclass) lecz nie wszystkie atrybuty mają być używane przez podklasę można rozważyć nazwanie ich z podwójnym podkreśleniem na początku nazwy i bez końcowego podkreślenia. To spowoduje wywołanie mechanizmu dekorowania nazwy (mangling), gdzie nazwa klasy jest wdekorowana w nazwę atrybutu. To pomaga unikać kolizji atrybutów gdyby podklasa niezamierzenie zawierała atrybuty o takiej samej nazwie.
    1. Zauważyć należy, że tylko prosta nazwa klasy jest używana w dekorowaniu nazwy, tak więc jeśli podklasa ma zarówno taką samą nazwę klasy jak i nazwę atrybutu nadal istnieje możliwość kolizji nazw
    2. Dekorowanie nazwy czyni pewne zastosowania, jak debugowanie czy __getattr__() mniej wygodnymi. Jakkolwiek algorytm dekorowania nazw jest dobrze udokumentowany i łatwy do wykonania ręcznie.


PEP 8 to jest podręcznik z wytycznymi na temat stylu kodu w Pythonie, a powyższy tekst to moja ściąga z PEP 8, napisana na poziomie mojej wiedzy z języka Python. Ma służyć dla mnie jako pomoc w opanowaniu języka.

Do późniejszego uzupełnienia.

By grzeszy on | PEP, Python | A comment?
Tagi: ,

Moja ściąga z PEP 8 – część 1

  1. Układ kodu
  2. Importy
  3. Odstępy w wyrażeniach i deklaracjach
  4. Komentarze

Układ kodu

Wcięcia:

  • spacje na jeden poziom wcięcia

Spacje czy tabulatory:

  • nigdy nie używa się jednocześnie spacji i tabulatorów jako wcięć w kodzie

Maksymalna długość linii:

  • maksymalnie 79 znaków Preferuje się łamanie linii przez użycie implikowanej kontynuacji linii w nawiasach {}[](), w miarę potrzeby można dodać dodatkową parę nawiasów dookoła długiego wyrażenia. Należy zadbać o właściwe wcięcie kontynuowanej linii. Zaleca się łamać linię po operatorze binarnym, nie przed nim. Przykład:
      def __init__(self, width, height,
              color='black', emphasis=None, highlight=0):
          if width == 0 and height == 0 and \
                  color == 'red' and emphasis == 'strong' or \
                  highlight > 100:
                      raise ValueError("sorry, you lose")
                  if width == 0 and height == 0 and (color == 'red' or
                          emphasis is None):
                      raise ValueError("I don't think so -- values are %s, %s" %
                              (width, height))
                      Blob.__init__(self, width, height,
                              color, emphasis, highlight)

Puste linie:

  • należy oddzielać definicje funkcji i klas na najwyższym poziomie dwiema liniami
  • definicje metod w klasie są oddzielane przez jedną pustą linię
  • używaj oszczędnie pustych linii do oddzielania logicznych sekcji w funkcji

Importy

  • Importy zwykle umieszcza się w osobnych liniachDobrze: 
          import os
      import sys

    Źle:

          import sys, os

    ale poniższe jest w porządku:

          from subprocess import Popen, PIPE
  • Importy umieszcza się u góry pliku, bezpośrednio po komentarzu lub docstringu modułu i przed zmiennymi i stałymi modułuImport powinny być pogrupowane w następującej kolejności: 1. importy z biblioteki standardowej 2. zewnętrzne importy spoza aplikacji 3. import z lokalnej aplikacji/biblioteki

    Powinno się umieszczać pustą linię pomiędzy powyższymi trzema grupami importów

  • Względne importy dla wewnątrz-pakietowych importów są bardzo odradzane, zawsze należy używać pełnej ścieżki pakietu dla wszystkich importów
  • Podczas importu klas z modułu zawierającego klasy jest w porządku pisać: 
          from myclass import MyClass
      from foo.bar.yourclass import YourClass

    lecz jeśli występuje konflikt nazw z lokalnymi klasami należy użyć:

          import myclass
      import foo.bar.yourclass

    i używa się “myclass.MyClass” oraz “foo.bar.yourclass.YourClass”

Odstępy w wyrażeniach i deklaracjach

  • Dobre przykłady: 
          spam(ham[1], {eggs: 2})
 
      if x == 4: print x, y; x, y = y, x
 
      spam(1)
 
      dict['key'] = list[index]
 
      x = 1
      y = 2
      long_variable = 3
  • Pojedyncza spacja po każdej ze stron operatorów: (=), (+=, -= itp.), (==, <, >, !=, <>, <=, >=, in, not in, is, is not) i (and, or, not)
  • Spacje dookoła operatorów arytmetycznych: 
          i = i + 1
      submitted += 1
      x = x * 2 - 1
      hypot2 = x * x + y * y
      c = (a + b) * (a - b)
  • brak spacji dookoła znaku = jeśli wskazuje on na domyślny parametr funkcji lub argument. 
          def complex(real, imag=0.0):
          return magic(r=real, i=imag)
  • wielokrotne instrukcje na tej samej linii są niewskazane: 
          if foo == 'blah':
          do_blah_thing()
      do_one()
      do_two()
      do_three()
  • raczej nie umieszczać instrukcji warunkowych na tej samej liniiRaczej nie: 
          if foo == 'blah': do_blah_thing()
      for x in lst: total += x
      wile t &lt; 10: t = delay()

    Absolutnie nie:

          if foo == 'blah': do_blah_thing()
      else: do_non_blah_thing()
 
      try: something()
      finally: cleanup()
 
      do_one(); do_two(); do_three(long, argument,
            list, like, this)
 
      if foo == 'blah': one(); two(); three()

Komentarze

  • Należy bezwzględnie utrzymywać aktualne komentarze w kodzie. Nieaktualne lub wręcz mylące komentarze są gorsze niż ich brak.
  • Komentarze powinny być pełnymi zdaniami. Komentarz który jest zdaniem lub frazą powinien mieć pierwsze słowo napisane wielkimi literami, chyba, że jest identyfikatorem rozpoczynającym się małą literą. Nie zmienia się przypadku identyfikatorów.(?)
  • Kropka na końcu krótkiego komentarza może być pominięta. Blok komentarza na ogół składa się jednego lub więcej paragrafów składających się ze zdań zakończonych kropką.
  • Należy używać dwóch spacji po kropce kończącej zdanie.
  • Komentarze zawsze należy pisać po angielsku.

Bloki komentarzy.

  • Bloki komentarzy dotyczą do części (lub całego) kodu, który po nich następuje i powinny mieć takie samo wcięcie jak ów kod. Każda linia kodu zaczyna się ze znaku # i spacji (# Komentarz do kodu.).
  • Paragrafy wewnątrz komentarzy oddzielone są są linią zawierającą tylko jeden znak #.

Komentarze w linii z kodem

  • Używać oszczędnie
  • Powinny być oddzielone od instrukcji min. dwiema spacjami.
  • Nie komentuje się instrukcji oczywistych, np.: 
          x = x + 1               # increment x by 1

Teksty dokumentacji (Docstrings)

  • Należy pisać docstringi dla publicznych modułów, funkcji, klas i metod. Docstringi nie są konieczne dla niepublicznych metod lecz powinno się pisać co dana metoda robi. Ten komentarz powinien następować po linii z def.
  • PEP 257 opisuje poprawne konwencje stosowania docstringów. Przykład: 
          """Return a foobang
 
      Optional plotz says to frobnicate the bizbaz first.
 
      """
  • Dla docstringu w jednej lini: 
          """Optional plotz says to frobnicate the bizbaz first."""

Version Bookkeeping (?)

Napisane na podstawie PEP 8 . Nie jestem profesjonalistą, ale staram się. Tekst jest pomocą przede wszystkim dla mnie. Jeśli komuś jeszcze będzie on pomocny ucieszę się. Jeszcze bardziej będę zadowolony jeśli ktoś doświadczony tu zajrzy i zechce skomentować to, i tamto.

By grzeszy on Grudzień 18, 2008 | PEP, Programowanie, Python | A comment?
Tagi: ,