تورفتگی¶

برای هر پله تورفتگی از ۴ فاصله استفاده کنید.

خطوط ادامه‌دار بهتر است عناصر خود را به صورت عمودی هم‌تراز کنند، این کار می‌تواند با چیدن عناصر زیر یکدیگر درون پرانتزها، کروشه‌ها و براکت‌ها، و یا استفاده از تورفتگی‌های هم‌اندازه در خطوط اضافی انجام شود [1]. هنگام استفاده از تورفتگی در خطوط ادامه‌دار به این نکته توجه داشته باشید که شکل ظاهری کدها باید به گونه‌ای باشد که خوانندهٔ کد به سادگی متوجه شود این تورفتگی‌ها مربوط به شکسته شدن یک خط بلند و ادامه‌دار است.

# Correct:

# Aligned with opening delimiter.
foo = long_function_name(var_one, var_two,
                         var_three, var_four)

# Add 4 spaces (an extra level of indentation) to distinguish arguments from the rest.
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

# Hanging indents should add a level.
foo = long_function_name(
    var_one, var_two,
    var_three, var_four)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

رعایت قانون ۴-فاصله برای خطوط ادامه‌دار الزامی نیست.

اختیاری:

# Hanging indents *may* be indented to other than 4 spaces.
foo = long_function_name(
  var_one, var_two,
  var_three, var_four)

زمانی که بخش شرطی یک دستور if ترکیبی طولانی باشد، به گونه‌ای که مجبور باشیم آن را در چند خط بنویسیم، با توجه به اینکه خود دستور if از دو حرف تشکیل شده و پس از آن نیز یک فاصله و پرانتز قرار می‌گیرد، می‌توانیم خطوط اضافی شرط را با رعایت ۴ فاصله زیر خط اصلی بنویسیم. گرچه این امر سبب بوجود آمدن یک تداخل بینایی می‌شود که در نتیجه آن شرط‌های دستور if از دستورات بلوک زیر آن به سختی قابل تفکیک خواهند بود، زیرا دستورات داخل بلوک شرطی هم باید ۴ فاصله تورفتگی داشته باشند. این شیوه‌نامه توصیه خاصی برای ایجاد تمایز بین شرط‌های اصلی و دستورات درون بلوک شرطی ندارد. برخی گزینه‌های قابل قبول به شرح زیر هستند:

# No extra indentation.
if (this_is_one_thing and
    that_is_another_thing):
    do_something()

# Add a comment, which will provide some distinction in editors
# supporting syntax highlighting.
if (this_is_one_thing and
    that_is_another_thing):
    # Since both conditions are true, we can frobnicate.
    do_something()

# Add some extra indentation on the conditional continuation line.
if (this_is_one_thing
        and that_is_another_thing):
    do_something()

(همچنین مباحث مربوط به نحوه شکستن خطوط، قبل و بعد از عملگرهای ریاضی را هم پایین‌تر ببینید.)

پرانتز/کروشه/براکت انتهایی در متغیرهای چندخطی می‌تواند زیر اولین حرف از آخرین خط نوشته شود، همانند:

my_list = [
    1, 2, 3,
    4, 5, 6,
    ]
result = some_function_that_takes_arguments(
    'a', 'b', 'c',
    'd', 'e', 'f',
    )

یا هم‌تراز با نام متغیر اصلی نوشته شود، همانند:

my_list = [
    1, 2, 3,
    4, 5, 6,
]
result = some_function_that_takes_arguments(
    'a', 'b', 'c',
    'd', 'e', 'f',
)

تب یا فاصله؟¶

برای ایجاد تورفتگی بهتر است از فاصله استفاده شود.

استفاده از تب تنها زمانی ارجحیت دارد که بخواهیم با کدهای از پیش موجود هماهنگ شویم، یعنی کدهای قدیمی که در آن‌ها از تب برای ایجاد تورفتگی استفاده شده است.

پایتون ترکیب تب و فاصله برای تورفتگی را مجاز نمی‌داند.

بیشترین طول خط¶

بیشترین اندازه یک خط باید نهایتاً ۷۹ حرف باشد.

برای بلوک‌های طولانی متن که محدودیت‌های ساختاری ندارند (مثل کامنت‌ها یا مستندات درون کد)، طول هر خط نباید از ۷۲ حرف بیشتر شود.

رعایت طول مناسب خطوط این امکان را پدید می‌آورد که بتوان چند فایل را به صورت همزمان در کنار یکدیگر باز کرد، همانند زمانی که از ابزارهای بررسی کد برای مقایسه تغییرات یک فایل استفاده می‌کنیم.

شکستن خطوط به صورت خودکار در بسیاری از نرم‌افزارهای کدنویسی باعث برهم خوردن ساختار کدها و فهم سخت‌تر کد می‌شود. این محدودیت‌ها برای این انتخاب شده‌اند که در نرم‌افزارهایی که عرض پنجره آن‌ها حداقل ۸۰ کاراکتر است، از شکستن خودکار خطوط جلوگیری شود. هرچند برخی نرم‌افزارهای کدنویسی به صورت کلی شکستن خطوط را اعمال نمی‌کنند.

برخی تیم‌ها ممکن است اندازه خطوط طولانی‌تر را ترجیح دهند. در صورت توافق اعضای تیم، برای کدهایی که فقط توسط خود تیم خوانده و نگهداری می‌شوند، طول هر خط می‌تواند تا ۹۹ حرف هم در نظر گرفته شود. اما در این حالت هم تعداد حروف کامنت‌ها و مستندات نباید از ۷۲ حرف بیشتر شود.

کتابخانه استاندارد پایتون بسیار محافظه‌کار است و لازم است که تمام خطوط آن کمتر از ۷۹ حرف باشند. همچنین کامنت‌ها و مستندات باید کمتر از ۷۲ حرف باشند.

روش ترجیحی برای شکستن خطوط طولانی، استفاده از خط ادامه‌دار ضمنی پایتون داخل پرانتزها، کروشه‌ها و آکولادهاست. با شکستن عبارات داخل پرانتزها، می توان خطوط طولانی را به چندین خط تقسیم کرد. این روش برای شکستن خطوط بلند، به جای استفاده از بک‌اسلش، اولویت دارد.

گاهی اوقات بک‌اسلش‌ها می‌توانند کارآمد باشند. برای مثال پیش از پایتون ۳٫۱۰، برخی از دستورات with که ممکن است طولانی و چندگانه باشند را می‌توان با کمک بک‌اسلش ساده‌تر و خواناتر نوشت.

with open('/path/to/some/file/you/want/to/read') as file_1, \
     open('/path/to/some/file/being/written', 'w') as file_2:
    file_2.write(file_1.read())

(درباره عبارت with چندخطی، می‌توانید مباحث پیشین در ارتباط با دستورات شرطی چندخطی multiline if-statements مطالعه کنید.)

مورد دیگر با دستور assert است.

مطمئن شوید که تورفتگی خطوط ادامه‌دار را رعایت کنید.

خطوط باید بعد از عملگرهای ریاضی شکسته شوند یا قبل از آن‌ها؟¶

برای سال‌ها، روش پیشنهادی این بود که خطوط بعد از عملگرهای ریاضی شکسته شوند؛ اما این کار به دو دلیل باعث پایین آمدن خوانایی کدها می‌شود: عملگرها در ستون‌های مختلفِ کد پراکنده می‌شوند، و هر عملگر از دستورات مربوط به خود دور شده و در خط قبل قرار می‌گیرد. برای نمونه در کد زیر، چشم انسان مجبور است کار بیشتری انجام دهد تا متوجه شویم کدام عبارت قرار است اضافه شود و کدام یک کم شود:

# Wrong:
# operators sit far away from their operands
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

برای حل مشکل خوانایی کدها، جامعه ریاضیدان‌ها روش متفاوتی برگزیدند. دانلد نات در مجموعه کتاب‌های کامپیوترها و حروف‌چینی روش سنتی را این‌گونه شرح می‌دهد: ‌‌"گرچه فرمول‌های درون هر پاراگراف بعد از عملگر ریاضی شکسته می‌شوند، اما هنگام نمایش مناسب، این فرمول‌ها باید قبل از عملگرها شکسته شوند" [3].

پیروی از سبک نگارش قدیمی ریاضیات معمولا باعث نتیجه بهتری در نمایش کدها می‌شود:

# Correct:
# easy to match operators with operands
income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)

در کدنویسی پایتون مادامی که یکدست بودن کدها رعایت شود و همیشه از یک قاعده پیروی شود، هر دو روش فوق، مجاز و قابل استفاده هستند. هر چند برای کدهایی که تازه نوشته می‌شوند، پیشنهاد می‌شوند از روش دانلد نات (شکستن خطوط قبل از عملگر) استفاده شود.

خطوط خالی¶

قبل از تعریف توابع سطح بالا و کلاس‌ها از دو خط خالی استفاده کنید.

قبل از تعریف متدها درون کلاس، از یک خط خالی استفاده کنید.

در مواردی معدود می‌توان برای گروه‌بندی توابع مرتبط با هم، و جداسازی این گروه‌ها از یکدیگر، از خطوط خالی اضافه استفاده کرد. خطوط خالی را می‌توان از بین دستورات یک‌خطی مرتبط با هم حذف کرد (برای مثال در پیاده‌سازی تست‌های ساختگی).

در توابع بهتر است صرفاً برای جدا کردن بخش‌های منطقی، از خطوط خالی استفاده کنید.

پایتون از کاراکتر کنترلی control-L (یا L^) برای ایجاد فضای خالی استفاده می‌کند؛ بسیاری از ابزارها این کاراکترها را تفکیک کننده صفحه تلقی می‌کنند، که می‌توانید از آنها برای تفکیک کردن صفحات بخش‌های مرتبط با هم در فایل خود استفاده کنید. توجه کنید که بعضی از ویرایشگرها و نمایشگرهای کد مبتنی بر وب ممکن است control-L را به عنوان کاراتر کنترلی تفکیک کننده صفحه تشخیص ندهند و به جای آن یک عملکرد دیگر از خود نشان دهند.

کدبندی فایل¶

کدهای هستهٔ پایتون همیشه باید از UTF-8 استفاده کنند، و نباید خط اعلام رمزگذاری داشته باشند.

در کتابخانه استاندارد، رمزگذاری‌های غیر UTF-8 فقط باید برای اهداف آزمایشی استفاده شوند. از کاراکترهای غیر ASCII کمتر استفاده کنید، ترجیحاً فقط برای نشان دادن نام مکان‌ها و انسان‌ها. اگر از کاراکترهای غیر ASCII به عنوان داده استفاده می‌کنید، از کاراکترهای یونیکد شلوغ مانند z̯̯͡a̧͎̺l̡͓̫g̹̲o̡̼̘ و علامت‌های ترتیب بایت خودداری کنید.

تمام شناسه‌ها (نام یک متغیر، تابع، ماژول و ...) در کتابخانه استاندارد پایتون باید فقط از نوع ASCII باشند و باید تا آنجا که امکان دارد از کلمات انگلیسی استفاده کنند (در بسیاری از موارد، از برخی اختصارات و اصطلاحات فنی استفاده می‌شود که انگلیسی نیستند).

پیشنهاد می‌شود پروژه‌های بازمتنی که مخاطب جهانی دارند هم از سیاست مشابهی استفاده کنند.

ایمپورت¶

• ایمپورت‌ها بهتر است در خطوط جداگانه باشند:

  # Correct:
  import os
  import sys
  

  # Wrong:
  import sys, os
  

  مشکلی ندارد اگر بگوییم:

  # Correct:
  from subprocess import Popen, PIPE
  

• ایمپورت‌ها همیشه در ابتدای فایل نوشته می‌شوند، درست پس از کامنت‌ها، مستندات ماژول و قبل از تعریف متغیرها و ثابت‌ها.

  ایمپورت‌ها باید به ترتیب زیر گروه‌بندی شوند:

  1. ایمپورت‌های کتابخانه استاندارد.

  2. ایمپورت کتابخانه‌های شخص ثالث.

  3. ایمپورت کتابخانه‌ها و کدهای محلی (local).

  شما باید بین هر گروه از ایمپورت‌ها یک خط خالی قرار دهید.

• پیشنهاد می شود ایمپورت‌ها به صورت مطلق انجام شوند، زیرا معمولا خواناتر هستند و در صورت پیکربندی نادرست سیستم ایمپورت (مانند زمانی که یک دایرکتوری داخل یک بسته به sys.path ختم می شود) رفتار مناسب از خود نشان می دهند ( یا حداقل پیغام های خطای بهتری نمایش می دهند):

  import mypkg.sibling
  from mypkg import sibling
  from mypkg.sibling import example
  

  با این حال، ایمپورت‌های نسبی صریح، جایگزین قابل قبولی برای ایمپورت‌های مطلق هستند، بخصوص زمانی که با ترتیب پیچیده بسته‌ها سروکار داریم که استفاده از ایمپورت‌های مطلق، غیرضروری، شلوغ و ناخوانا خواهد بود:

  from . import sibling
  from .sibling import example
  

  کدهای کتابخانه استاندارد باید از ایمپورت کردن به صورت لایه‌های پیچیده اجتناب کنند و همیشه از ایمپورت‌های مطلق استفاده کنند.

• هنگام ایمپورت یک کلاس از ماژولی که شامل کلاس‌های مختلف است، می‌توانیم از الگوی زیر استفاده کنیم:

  from myclass import MyClass
  from foo.bar.yourclass import YourClass
  

  اگر کلاس‌ها یا توابعی که در یک فایل ایمپورت می‌کنید با نام‌های موجود در آن فایل تداخل دارند، بهتر است آن‌ها را صریحاً به صورت زیر بنویسید:

  import myclass
  import foo.bar.yourclass
  

  و از "myclass.MyClass" و "foo.bar.yourclass.YourClass" استفاده کنید.

• از ایمپورت‌های عمومی (استفاده از سمبل‌های جمع مانند ”*” در from <module> import *) باید اجتناب شود، زیرا آن‌ها باعث می‌شوند واضح نباشد که چه نام‌هایی در فضانام موجود هستند، این مسئله باعث گیج شدن خواننده و بسیاری از ابزارهای خودکار می‌شود. فقط یک دلیل قابل دفاع در استفاده از ایمپورت‌های عمومی وجود دارد: بازنشر یک رابط داخلی به عنوان بخشی از یک API عمومی ( برای نمونه، بازنویسی یک پیاده‌سازی پایتون خالص از یک رابط با تعاریفی اختیاری از یک ماژول شتابدهنده و اینکه دقیقا از قبل مشخص نشده است کدام تعاریف بازنویسی می‌شوند).

  هنگام بازنشر نام‌ها به این روش ، دستورالعمل‌های زیر در مورد رابط‌های عمومی و داخلی همچنان اعمال می‌شوند.

داندرهای سطح ماژول¶

داندرها، متغیر/متدهایی هستند که نام آن‌ها با دو زیرخط آغاز شده و با دو زیرخط خاتمه می‌یابد، مانند __all__، __author__، __version__. داندرهای در سطح ماژول باید پس از مستندات ماژول، و قبل از ایمپورت‌ها نوشته شوند، به استثنای ایمپورت‌های from __future__. پایتون ما را ملزم می‌کند که ایمپورت‌های from __future__ را در ابتدای ماژول، قبل از هر کد دیگری قرار دهیم.

"""This is the example module.

This module does stuff.
"""

from __future__ import barry_as_FLUFL

__all__ = ['a', 'b', 'c']
__version__ = '0.1'
__author__ = 'Cardinal Biggles'

import os
import sys

موارد روی اعصاب¶

از گذاشتن فضای خالی (فاصله) در موقعیت‌های زیر خودداری کنید:

• بعد از باز کردن پرانتز، کروشه و براکت؛ همچنین قبل از بستن آن‌ها:

  # Correct:
  spam(ham[1], {eggs: 2})
  

  # Wrong:
  spam( ham[ 1 ], { eggs: 2 } )
  

• بعد از ویرگول انتهایی و قبل از بستن پرانتز:

  # Correct:
  foo = (0,)
  

  # Wrong:
  bar = (0, )
  

• قبل از ویرگول، نقطه‌ویرگول یا دونقطه:

  # Correct:
  if x == 4: print(x, y); x, y = y, x
  

  # Wrong:
  if x == 4 : print(x , y) ; x , y = y , x
  

• با این حال در برش لیست با یک عملگر دونقطه، دونقطه مانند یک عملگر باینری عمل می‌کند و باید در هر طرف آن به یک اندازه فضا وجود داشته باشد (آن را عملگری با کمترین اولویت در نظر بگیرید). در برش لیست با دو عملگر دونقطه، هر دو عملگر باید فاصله یکسانی داشته باشند. استثنا: وقتی یک پارامتر در برش لیست حذف می‌شود، فاصله بین آن و عملگر دونقطه هم حذف می‌شود:

  # Correct:
  ham[1:9], ham[1:9:3], ham[:9:3], ham[1::3], ham[1:9:]
  ham[lower:upper], ham[lower:upper:], ham[lower::step]
  ham[lower+offset : upper+offset]
  ham[: upper_fn(x) : step_fn(x)], ham[:: step_fn(x)]
  ham[lower + offset : upper + offset]
  

  # Wrong:
  ham[lower + offset:upper + offset]
  ham[1: 9], ham[1 :9], ham[1:9 :3]
  ham[lower : : upper]
  ham[ : upper]
  

• قبل از باز کردن پرانتز در فراخوانی تابع:

  # Correct:
  spam(1)
  

  # Wrong:
  spam (1)
  

• قبل از باز کردن براکت مربوط به ایندکس لیست و دیکشنری:

  # Correct:
  dct['key'] = lst[index]
  

  # Wrong:
  dct ['key'] = lst [index]
  

• بیش از یک فاصله اطراف عملگر تخصیص = برای تراز کردن کلمات با دیگر خطوط:

  # Correct:
  x = 1
  y = 2
  long_variable = 3
  

  # Wrong:
  x             = 1
  y             = 2
  long_variable = 3
  

دیگر پیشنهادها¶

• از گذاشتن فاصله در انتهای خطوط خودداری کنید. زیرا در بیشتر زمان‌ها این فاصله نامرئی است و می‌تواند باعث پیچیدگی شود: برای نمونه یک فاصله بعد از بک‌اسلش در انتهای خط، به عنوان علامت یک خط ادامه‌دار شناسایی نمی‌شود. برخی ویرایشگرهای کد از این کار پیشگیری می‌کنند و بسیاری از پروژه‌ها (مانند خود CPython) به صورت خودکار کاراکتر فاصله در انتهای خطوط را شناسایی و رد می‌کند.

• همیشه قبل و بعد از این عملگرها یک فاصله قرار دهید: مساوی/تخصیص (=)، تخصیص غنی‌شده (مانند +=، -= و غیره)، مقایسه‌ها (==, <, >, !=, <>, <=, >=, in, not in, is, is not)، عملگرهای بولی منطقی (and, or, not).

• در صورتی که در یک خط از عملگرهایی با اولویت‌های مختلف استفاده می‌کنید، در چپ و راست عملگر با اولویت کمتر فاصله قرار دهید. به هیچ وجه از بیش از یک فاصله استفاده نکنید و همیشه به همان اندازه در هر دو طرف یک عملگر باینری فضای خالی داشته باشید:

  # Correct:
  i = i + 1
  submitted += 1
  x = x*2 - 1
  hypot2 = x*x + y*y
  c = (a+b) * (a-b)
  

  # Wrong:
  i=i+1
  submitted +=1
  x = x * 2 - 1
  hypot2 = x * x + y * y
  c = (a + b) * (a - b)
  

• انوتیشن‌های توابع باید از قوانین عادی برای دونقطه استفاده کنند و در صورت وجود نشانه پیکان -> همیشه فضای خالی اطراف آن باشد. (برای اطلاعات بیشتر به انوتیشن‌های توابع مراجعه کنید.):

  # Correct:
  def munge(input: AnyStr): ...
  def munge() -> PosInt: ...
  

  # Wrong:
  def munge(input:AnyStr): ...
  def munge()->PosInt: ...
  

• به هنگام نشان دادن یک آرگومان، یا نشان دادن مقدار پیش‌فرض پارامتر یک تابع unannotated از فضای خالی اطراف علامت = استفاده نکنید:

  # Correct:
  def complex(real, imag=0.0):
      return magic(r=real, i=imag)
  

  # Wrong:
  def complex(real, imag = 0.0):
      return magic(r = real, i = imag)
  

  با این حال، هنگام تخصیص مقدار پیش‌فرض به یک انوتیشن، از فضای خالی اطراف علامت = استفاده کنید:

  # Correct:
  def munge(sep: AnyStr = None): ...
  def munge(input: AnyStr, sep: AnyStr = None, limit=1000): ...
  

  # Wrong:
  def munge(input: AnyStr=None): ...
  def munge(input: AnyStr, limit = 1000): ...
  

• نباید از چندین عبارت دستوری در یک خط استفاده کرد:

  # Correct:
  if foo == 'blah':
      do_blah_thing()
  do_one()
  do_two()
  do_three()
  

  نامناسب:

  # Wrong:
  if foo == 'blah': do_blah_thing()
  do_one(); do_two(); do_three()
  

• هرچند گاهی اوقات قرار دادن دستورات تکی if یا for یا while در یک خط مجاز است، اما هیچگاه این کار را برای دستورات چند جمله‌ای انجام ندهید. همچنین از تا کردن این خطوط طولانی نیز خودداری کنید!

  نامناسب:

  # Wrong:
  if foo == 'blah': do_blah_thing()
  for x in lst: total += x
  while t < 10: t = delay()
  

  قطعاً نه:

  # Wrong:
  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()
  

کامنت‌های بلوکی¶

کامنت‌های بلوکی معمولا به کدهایی که بعد از آن‌ها نوشته می‌شود اشاره دارند. تورفتگی این کامنت‌ها باید به اندازه تورفتگی کدهای مربوطه باشد. هر خط از کامنت‌های بلوکی باید با علامت # و یک فاصله پس از آن آغاز شود (به جز در مواردی که درون بلوک کامنت‌ها هم نیاز به تورفتگی وجود داشته باشد).

پاراگراف‌های درون یک بلوک کامنت، توسط خطی که با یک علامت # شروع می‌شود از هم جدا می‌شوند.

کامنت‌های درون‌خطی¶

تا حد امکان از کامنت‌های درون‌خطی استفاده نکنید.

کامنت درون‌خطی در واقع کامنتی است که در همان خط کد نوشته می‌شود. کامنت‌های درون‌خطی باید حداقل با دو فاصله از کد نوشته شوند. آن‌ها باید با یک علامت # و یک فاصله بعد از آن آغاز شوند.

کامنت‌های درون‌خطی در صورتی که توضیح واضحات باشند، کاملا غیرضروری و مزاحم هستند. این کار را انجام ندهید:

x = x + 1                 # Increment x

اما گاهی وقت‌ها می‌تواند مفید باشد:

x = x + 1                 # Compensate for border

رشته‌های مستندات¶

اصول کامل برای نوشتن مستندات خوب در پپ ۲۵۷ شرح داده شده‌اند.

• برای تمام ماژول‌ها، توابع، کلاس‌ها و متدهای خود که به صورت عمومی تعریف کرده‌اید مستندات مربوط به آن‌ها را بنویسید. نوشتن این مستندات برای سایر متدهایی که به صورت عمومی تعریف نشده‌اند الزامی نیست؛ اما باید برای این متدها نیز یک کامنت بنویسید تا عمکلرد آن را شرح دهد. این کامنت باید در پایین خط def (اولین خط درون متد شما) نوشته شود.

• پپ ۲۵۷ اصول مستندنویسی را به خوبی توضیح می‌دهد. نکته مهم این است که عبارت \"\"\" که برای پایان دادن به مستندات استفاده می‌شود باید در یک خط جداگانه قرار گیرد.

  """Return a foobang
  
  Optional plotz says to frobnicate the bizbaz first.
  """
  

• برای مستندات یک خطی، لطفاً """ پایانی را در همان خط قرار دهید:

  """Return an ex-parrot."""
  

اصل مهم¶

نام‌هایی که به عنوان بخشی از یک API عمومی به کاربران نمایش داده می‌شوند، بهتر است با توجه به نوع کارکرد آن بخش از API انتخاب شوند.

توصیفی: سبک‌های نام‌گذاری¶

سبک‌های نامگذاری مختلف زیادی وجود دارند و مستقل از آنچه که برای آن استفاده می‌شوند، کمک می‌کنند که بتوانیم تشخیص دهیم از چه سبک نامگذاری استفاده می‌شود.

شیوه‌های نامگذاری زیر به راحتی قابل تفکیک و تشخیص هستند:

• b (تک حرف کوچک)

• B (تک حرف بزرگ)

• lowercase

• lower_case_with_underscores

• UPPERCASE

• UPPER_CASE_WITH_UNDERSCORES

• CapitalizedWords (یا CapWords نگارش کلمات به هم چسبیده با حرف اول بزرگ ، یا CamelCase (نگارش شتری) -- که این نام گذاری به دلیل ظاهر ناهموار حروف آن است [4]). این نوع نگارش گاهی اوقات به عنوان StudlyCaps نیز شناخته میشود.

  نکته: هنگام استفاده از کلمات اختصاری در نگارش CapWords، تمام حروفِ کلمه اختصاری با حروف بزرگ نوشته می‌شود. بنابراین نوشتن HTTPServerError بهتر از HttpServerError است.

• mixedCase (تفاوت آن با نگارش CapitalizedWords این است که اولین حرف آن به صورت کوچک نوشته می شود!)

• Capitalized_Words_With_Underscores (زشت!)

همچنین سبک استفاده از یک پیشوند منحصر به فرد کوتاه برای گروه‌بندی نام‌های مرتبط باهم وجود دارد. این سبک خیلی در پایتون استفاده نمی‌شود، اما برای کامل بودن ذکر شده است. برای مثال، تابع os.stat() یک تاپل را برمی‌گرداند که آیتم‌های آن معمولاً دارای نام‌هایی مانند st_mode، st_size، st_mtime و غیره هستند. (این کار برای تأکید بر مطابقت با فیلدهای ساختار سیستم کال POSIX انجام می شود که به برنامه‌نویسانی که با آن آشنا هستند کمک می کند.)

کتابخانه X11 از یک پیشوند X برای تمام توابع عمومی خود استفاده می‌کند. در پایتون، این سبک به طور کلی غیرضروری تلقی می‌شود زیرا پیشوند نام مشخصه‌ها و متدها، نام یک شی است و پیشوند نام توابع نیز، نام یک ماژول.

علاوه بر این، فرم‌های ویژه زیر که زیرخط‌هایی در ابتدا یا انتهای خود دارند، شناخته شده هستند (این‌ فرم‌ها را معمولا می‌توان با هر کدام از شیوه‌های نامگذاری ترکیب کرد):

• _single_leading_underscore: نشانهٔ ضعیف برای «استفاده داخلی». برای نمونه عبارت from M import * اشیائی که اسم آن‌ها با یک زیرخط شروع می‌شود را ایمپورت نمی‌کند.

• single_trailing_underscore_: طبق قرارداد برای جلوگیری از مغایرت با کلمه‌های کلیدی پایتون استفاده می‌شود، برای نمونه:

  tkinter.Toplevel(master, class_='ClassName')
  

• __double_leading_underscore: هنگام نامگذاری یک مشخصه کلاس، دستکاری نام (name mangling) را فراخوانی می‌کند (در داخل کلاس FooBar، __boo تبدیل به _FooBar__boo می‌شود؛ زیر را ببینید).

• __double_leading_and_trailing_underscore__: اشیاء و مشخصه‌های «جادویی» که در فضانام‌های تحت کنترل کاربر قرار دارند. برای مثال __init__, __import__ or __file__. هرگز چنین اسم‌هایی را نسازید؛ فقط از آن‌ها طبق مستندات پایتون استفاده کنید.

تجویزی: قواعد نام‌گذاری¶

from typing import TypeVar

VT_co = TypeVar('VT_co', covariant=True)
KT_contra = TypeVar('KT_contra', contravariant=True)

رابط‌های عمومی و داخلی¶

هرگونه ضمانت سازگاری با نسخه‌های پیشین فقط برای اینترفیس‌های عمومی اعمال می‌شود. بر این اساس، مهم است که کاربران بتوانند به وضوح بین اینترفیس‌های عمومی و داخلی تمایز قائل شوند.

اینترفیس‌های مستند شده، عمومی درنظر گرفته می‌شوند، مگر اینکه اسناد به صراحت آنها را موقت یا اینترفیس‌های داخلی اعلام کند که از ضمانت‌های سازگاری با نسخه‌های پیشین معمول، مستثنی هستند. همه اینترفیس‌های غیرمستند باید داخلی فرض شوند.

برای پشتیبانی بهتر از رابط‌های داخلی، ماژول‌ها باید به صراحت نام‌ها را در API عمومی خود با استفاده از مشخصه __all__ تعریف کنند. تنظیم __all__ به یک لیست خالی نشان می‌دهد که ماژول فاقد API عمومی است.

حتی با تنظیم __all__ بصورت صحیح، واسط‌های داخلی (بسته‌ها، ماژول‌ها، کلاس‌ها، توابع، مشخصه‌ها و بقیه نام‌ها) هنوز باید همراه با یک زیرخط به صورت پیشوند باشند.

اگر فضانام (بسته، ماژول یا کلاس) دربرگیرندهٔ یک اینترفیس، داخلی در نظر گرفته شود، آن اینترفیس نیز داخلی در نظر گرفته خواهد شد.

نام‌های ایمپورت‌شده همیشه باید به عنوان جزییات پیاده‌سازی در نظر گرفته شوند. ماژول‌های دیگر نباید به دسترسی غیرمستقیم به این نام‌های ایمپورت‌شده متکی باشند، مگر اینکه بخش به صراحت مستند‌شده از API ماژول باشند، مانند os.path یا ماژول __init__ در بسته‌ها، که عملکرد زیرماژول‌ها را نشان می‌دهد.

انوتیشن‌های توابع¶

با پذیرش پپ ۴۸۴ شیوه نگارش انوتیشن توابع تغییر کرد.

• انوتیشن‌های توابع باید مطابق با شیوه‌نامه پپ ۴۸۴ باشند. (در بخش قبل، برخی اصول پیشنهادی برای انوتیشن‌ها آورده شده).

• استفاده‌های آزمایشی از انوتیشن‌ها که در نسخه‌های پیشین پپ ۸ گفته شده بود از این به بعد پیشنهاد نمی‌شود.

• با این حال اکنون، آزمایش قوانین پپ ۴۸۴ خارج از کتابخانه استاندارد نیز پیشنهاد می‌شوند. برای نمونه، علامت‌گذاری یک کتابخانه یا برنامه شخص ثالث بزرگ با سبک انوتیشن‌های پپ ۴۸۴، بررسی آسان بودن افزودن آن انوتیشن‌ها، و مشاهده اینکه آیا وجود آنها درک کد را افزایش می دهد یا خیر.

• کتابخانه استاندارد پایتون باید در پذیرش چنین انوتیشن‌هایی محافظه‌کار باشد، اما استفاده از آن‌ها برای کدهای جدید و بازسازی‌های بزرگ کدها مجاز است.

• برای کدهایی که می‌خواهند استفادهٔ دیگری از انوتیشن‌های تابع داشته باشند، پیشنهاد می‌شود از کامنت‌هایی با فرم زیر استفاده شود:

  # type: ignore
  

  در خطوط اولیهٔ فایل؛ این خط به چک‌کننده‌های تایپ‌ها پیغام می‌دهد که انوتیشن‌ها را در این فایل نادیده بگیرند. (برای دیدن روش‌های دیگر غیرفعال کردن انوتیشن‌ها به پپ ۴۸۴ مراجعه کنید).

• مانند لینترها، چک‌کننده‌های نوع داده اختیاری هستند و ابزارهایی جدا به حساب می‌آیند. مفسرهای پایتون به طور پیش‌فرض نباید هیچ پیامی را به دلیل بررسی نوع داده نشان دهند و نباید رفتار خود را بر اساس انوتیشن‌ها تغییر دهند.

• کاربرانی که نمی‌خواهند از چک‌کننده‌های نوع داده استفاده کنند، می‌توانند آن‌ها را نادیده بگیرند. با این حال، انتظار می‌رود که کاربران بسته‌های کتابخانه شخص ثالث ممکن است بخواهند بررسی‌های نوع داده را روی آن بسته‌ها انجام دهند. برای این منظور پپ ۴۸۴ استفاده از فایل‌های خرد (stub files) را توصیه می‌کند: فایل‌های .pyi که توسط چک‌کننده نوع داده در اولویت فایل‌های .py مربوطه خوانده می‌شوند. فایل‌های خرد را می‌توان با کتابخانه، یا به صورت جداگانه (با اجازه نویسنده کتابخانه) از طریق مخزن typeshed [5] توزیع کرد.

انوتیشن‌های متغیرها¶

پپ ۲۵۶ انوتیشن‌های متغیر را معرفی کرد. شیوه‌نامه پیشنهادی شامل قانون‌های مشابه با انوتیشن توابع است که بالاتر توضیح داده شد:

• انوتیشن برای متغیرهای سطح ماژول، کلاس و متغیرهای داخلی کلاس و متغیرهای محلی باید یک فاصله بعد از دونقطه داشته باشند.

• هیچ فاصله‌ای نباید پیش از دونقطه قرار بگیرد.

• هنگام تخصیص مقدار به یک متغیر، باید قبل و بعد از علامت = یک فاصله قرار بگیرد:

  # Correct:
  
  code: int
  
  class Point:
      coords: Tuple[int, int]
      label: str = '<unknown>'
  

  # Wrong:
  
  code:int  # No space after colon
  code : int  # Space before colon
  
  class Test:
      result: int=0  # No spaces around equality sign
  

• هرچند پپ ۵۲۶ برای پایتون ۳,۶ پذیرفته شده است، ساختار انوتیشن متغیرها، ساختار ترجیح داده شده برای فایل‌های stub در تمام نگارش‌های پایتون است (برای جزئیات بیشتر پپ ۴۸۴ را ببینید).

پانویس‌ها

مشارکت‌کنندگان¶

• حنیف بیرگانی

• معین باباپور

• امیر همتی

• آرش حاتمی

• رضا رضائی

• علی صادقی

مشارکت در ترجمه¶

برای مشارکت در ترجمه این متن به مخزن گیتهاب پروژه مراجعه کنید.

سایت پپ ۸ فارسی، پروژه‌ای از حنیف بیرگانی.