array --- آرایه‌های کارآمد از مقادیر عددی

این ماژول یک نوع شیء را تعریف می‌کند که می‌تواند آرایه‌ای از مقادیر پایه را به‌صورت فشرده بازنمایی کند: نویسه‌ها، اعداد صحیح و اعداد ممیز شناور. آرایه‌ها انواعی از دنباله تغییرپذیر هستند و بسیار شبیه فهرست‌ها رفتار می‌کنند، با این تفاوت که نوع اشیاء ذخیره‌شده در آن‌ها محدود است. این نوع در زمان ایجاد شیء با استفاده از یک کد نوع <type code> مشخص می‌شود که یک نویسه واحد است. کدهای نوع زیر تعریف شده‌اند:

کد نوع

نوع C

نوع پایتون

حداقل اندازه به بایت

یادداشت‌ها

'b'

signed char

int

1

'B'

unsigned char

int

1

'u'

wchar_t

نویسه‌ی یونیکد

2

(1)

'w'

Py_UCS4

نویسه‌ی یونیکد

4

(2)

'h'

signed short

int

2

'H'

short بدون علامت (unsigned short)

int

2

'i'

signed int

int

2

'I'

عدد صحیح بدون علامت (unsigned int)

int

2

'l'

signed long

int

4

'L'

unsigned long

int

4

'q'

long long علامت‌دار (signed long long)

int

۸

'Q'

unsigned long long

int

۸

'f'

float

float

4

'd'

double

float

۸

یادداشت‌ها:

  1. بسته به پلتفرم، می‌تواند ۱۶ بیت یا ۳۲ بیت باشد.

    تغییر یافته در نسخه‌ی 3.9: array('u') اکنون از wchar_t به‌عنوان نوع C به‌جای Py_UNICODE منسوخ‌شده استفاده می‌کند. این تغییر بر رفتار آن تأثیری نمی‌گذارد، زیرا Py_UNICODE از پایتون 3.3 نام مستعاری از wchar_t است.

    منسوخ شده از نسخه‌ی 3.3, در نسخه‌ی 3.16 حذف خواهد شد: لطفاً به کد نوع (typecode) 'w' مهاجرت کنید.

  2. اضافه شده در نسخه‌ی 3.13.

همچنین ملاحظه نمائید

ماژول‌های ctypes و struct، و همچنین ماژول‌های شخص ثالث مانند numpy، از کدهای نوع مشابه -- اما کمی متفاوت -- استفاده می‌کنند.

نمایش واقعی مقادیر توسط معماری ماشین تعیین می‌شود (به‌طور دقیق‌تر، توسط پیاده‌سازی C). اندازه واقعی از طریق ویژگی array.itemsize قابل دسترسی است.

این ماژول آیتم زیر را تعریف می‌کند:

array.typecodes

رشته‌ای حاوی همه‌ی کدهای نوع موجود.

این ماژول نوع زیر را تعریف می‌کند:

class array.array(typecode[, initializer])

آرایه‌ای جدید با آیتم‌های محدودشده با typecode که از مقدار اختیاری initializer مقداردهی اولیه می‌شود؛ این مقدار باید یک شیء bytes یا bytearray، یک رشته یونیکد، یا پیمایش‌پذیری روی عناصری از نوع مناسب باشد.

اگر یک شیء bytes یا bytearray داده شود، مقدارده اولیه به متد frombytes() آرایه‌ی جدید ارسال می‌شود؛ اگر یک رشته یونیکد داده شود، مقدارده اولیه به متد fromunicode() ارسال می‌شود؛ در غیر این صورت، پیمایش‌گر مقدارده اولیه به متد extend() ارسال می‌شود تا آیتم‌های اولیه به آرایه افزوده شوند.

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

آرایه‌ها نسبت به نوع محتوای خود عام هستند.

یک رویداد حسابرسی array.__new__ را با آرگومان‌های typecode و initializer پرتاب می‌کند.

typecode

نویسه‌ی کد نوع (typecode) که برای ایجاد آرایه به کار رفته است.

itemsize

طول یک آیتم آرایه در نمایش داخلی، بر حسب بایت.

append(value, /)

یک آیتم جدید با مقدار مشخص‌شده را به انتهای آرایه اضافه می‌کند.

buffer_info()

یک تاپل (address, length) برمی‌گرداند که نشانی حافظه فعلی و طول بر حسب عناصر بافری را که برای نگهداری محتوای آرایه استفاده می‌شود، مشخص می‌کند. اندازه‌ی بافر حافظه بر حسب بایت را می‌توان به‌صورت array.buffer_info()[1] * array.itemsize محاسبه کرد. این موضوع گاهی هنگام کار با رابط‌های سطح پایین I/O (و ذاتاً ناامن) که به نشانی‌های حافظه نیاز دارند، مفید است، مانند برخی از عملیات‌های ioctl(). اعداد برگردانده‌شده تا زمانی که آرایه وجود دارد و هیچ عملیات تغییر طولی بر آن اعمال نشود، معتبر هستند.

توجه

هنگام استفاده از اشیای آرایه از کدی که به زبان C یا C++ نوشته‌شده است (تنها راه برای استفاده مؤثر از این اطلاعات)، منطقی‌تر است از رابط بافر (buffer interface) که توسط اشیای آرایه پشتیبانی می‌شود استفاده کنید. این متد برای سازگاری با عقب‌گرد نگهداری می‌شود و باید در کد جدید از آن اجتناب شود. رابط بافر در پروتکل بافر مستند شده است.

byteswap()

«جابه‌جایی بایت‌ها» (Byteswap) برای تمام آیتم‌های آرایه انجام می‌شود. این عمل فقط برای مقادیری با اندازه‌ی ۱، ۲، ۴ یا ۸ بایت پشتیبانی می‌شود؛ برای سایر انواع مقادیر، RuntimeError پرتاب می‌شود. این عمل هنگام خواندن داده‌ها از پرونده‌ای که روی ماشینی با ترتیب بایت متفاوت نوشته شده است، مفید است.

count(value, /)

تعداد تکرارهای value را در آرایه برمی‌گرداند.

extend(iterable, /)

آیتم‌هایی از iterable را به انتهای آرایه اضافه می‌کند. اگر iterable آرایه دیگری باشد، باید کد نوع دقیقاً یکسانی داشته باشد؛ در غیر این صورت، TypeError پرتاب می‌شود. اگر iterable یک آرایه نباشد، باید پیمایش‌پذیر باشد و عناصر آن باید نوع مناسب برای اضافه شدن به آرایه را داشته باشند.

frombytes(buffer, /)

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

اضافه شده در نسخه‌ی 3.2: fromstring() برای وضوح بیشتر به frombytes() تغییر نام پیدا کرده است.

fromfile(f, n, /)

n آیتم را (به‌صورت مقادیر ماشینی) از file object f بخوانید و آن‌ها را به انتهای آرایه اضافه کنید. اگر کمتر از n آیتم در دسترس باشد، EOFError پرتاب می‌شود، اما آیتم‌هایی که در دسترس بودند همچنان در آرایه درج می‌شوند.

fromlist(list, /)

آیتم‌های فهرست را اضافه می‌کند. این معادل for x in list: a.append(x) است، با این تفاوت که اگر خطای نوع رخ دهد، آرایه بدون تغییر باقی می‌ماند.

fromunicode(ustr, /)

این آرایه را با داده‌های رشته یونیکد داده‌شده گسترش می‌دهد. آرایه باید کد نوع 'u' یا 'w' داشته باشد؛ در غیر این صورت یک ValueError پرتاب می‌شود. برای افزودن داده‌های یونیکد به آرایه‌ای از نوعی دیگر، از array.frombytes(unicodestring.encode(enc)) استفاده کنید.

index(value[, start[, stop]])

کوچک‌ترین i را برمی‌گرداند، به‌طوری که i اندیس نخستین رخداد value در آرایه باشد. می‌توان آرگومان‌های اختیاری start و stop را برای جست‌وجوی value در زیربخشی از آرایه مشخص کرد. اگر value یافت نشد، ValueError را پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.10: پارامترهای اختیاری start و stop افزوده شدند.

insert(index, value, /)

یک آیتم جدید با مقدار value را پیش از موقعیت index در آرایه درج کنید. مقادیر منفی نسبت به انتهای آرایه در نظر گرفته می‌شوند.

pop(index=-1, /)

آیتم با اندیس i را از آرایه حذف می‌کند و آن را برمی‌گرداند. آرگومان اختیاری به‌طور پیش‌فرض -1 است، بنابراین به‌طور پیش‌فرض آخرین آیتم حذف و برگردانده می‌شود.

remove(value, /)

اولین رخداد value را از آرایه حذف می‌کند.

clear()

حذف تمام عناصر از آرایه.

اضافه شده در نسخه‌ی 3.13.

reverse()

ترتیب آیتم‌های آرایه را معکوس می‌کند.

tobytes()

آرایه را به آرایه‌ای از مقادیر ماشین تبدیل می‌کند و بازنمایی بایتی را برمی‌گرداند (همان دنباله‌ای از بایت‌ها که توسط متد tofile() در یک پرونده نوشته می‌شود.)

اضافه شده در نسخه‌ی 3.2: tostring() برای وضوح به tobytes() تغییر نام داده شده است.

tofile(f, /)

تمام آیتم‌ها (به‌صورت مقادیر ماشینی) را در شیء پرونده f می‌نویسد.

tolist()

آرایه را به یک فهرست معمولی با همان آیتم‌ها تبدیل می‌کند.

tounicode()

آرایه را به یک رشته‌ی یونیکد تبدیل کنید. آرایه باید نوع 'u' یا 'w' داشته باشد؛ در غیر این صورت ValueError پرتاب می‌شود. برای به دست آوردن یک رشته‌ی یونیکد از آرایه‌ای با نوع دیگر، از array.tobytes().decode(enc) استفاده کنید.

نمایش رشته‌ای اشیای آرایه به شکل array(typecode, initializer) است. اگر آرایه خالی باشد، initializer حذف می‌شود؛ در غیر این صورت، اگر typecode برابر 'u' یا 'w' باشد، یک رشته یونیکد است و در غیر این صورت فهرستی از اعداد است. تضمین می‌شود که نمایش رشته‌ای را بتوان با استفاده از eval() به آرایه‌ای با همان نوع و مقدار تبدیل کرد، مشروط بر اینکه کلاس array با استفاده از from array import array ایمپورت شده باشد. اگر شامل مقادیر ممیز شناور متناظر باشد، متغیرهای inf و nan نیز باید تعریف شده باشند. نمونه‌ها:

array('l')
array('w', 'hello \u2641')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14, -inf, nan])

همچنین ملاحظه نمائید

ماژول struct

بسته‌بندی و واگشایی داده‌های دودویی ناهمگن.

NumPy

بسته NumPy نوع آرایه دیگری را تعریف می‌کند.