(نسخه‌ی یونیکس) length بایت از پرونده مشخص‌شده با توصیف‌گر پرونده fileno را نگاشت می‌کند و یک شیء mmap برمی‌گرداند. اگر length برابر 0 باشد، حداکثر طول نگاشت برابر اندازه‌ی فعلی پرونده در هنگام فراخوانی mmap خواهد بود.
flags ماهیت نگاشت را مشخص می‌کند. MAP_PRIVATE یک نگاشت خصوصی با کپی-در-نوشتن (copy-on-write) ایجاد می‌کند، بنابراین تغییرات در محتوای شیء mmap برای این فرایند خصوصی خواهد بود و MAP_SHARED نگاشتی ایجاد می‌کند که با تمام فرایندهای دیگری که ناحیه‌های یکسانی از پرونده را نگاشت می‌کنند، به اشتراک گذاشته می‌شود. مقدار پیش‌فرض MAP_SHARED است. برخی سیستم‌ها پرچم‌های ممکن بیشتری دارند که فهرست کامل آن‌ها در MAP_* constants مشخص شده است.
prot، اگر مشخص شده باشد، حفاظت مطلوب حافظه را ارائه می‌دهد؛ دو مقداری که بیشترین کاربرد را دارند PROT_READ و PROT_WRITE هستند، تا مشخص کنند که صفحات می‌توانند خوانده یا نوشته شوند. مقدار پیش‌فرض prot برابر با PROT_READ | PROT_WRITE است.
می‌توان access را به‌جای flags و prot به‌عنوان یک پارامتر کلیدواژه‌ای اختیاری مشخص کرد. مشخص کردن همزمان flags، prot و access خطا است. برای آگاهی از چگونگی استفاده از این پارامتر، توضیح access در بالا را ببینید.
می‌توان offset را به‌صورت یک آفست عدد صحیح غیرمنفی مشخص کرد. ارجاع‌های mmap نسبت به آفست از ابتدای پرونده خواهند بود. مقدار پیش‌فرض offset برابر ۰ است. offset باید مضربی از ALLOCATIONGRANULARITY باشد که در سیستم‌های یونیکس برابر PAGESIZE است.
اگر trackfd برابر False باشد، توصیف‌گر پرونده مشخص‌شده توسط fileno تکثیر نخواهد شد و شیء mmap حاصل با پرونده زیربنایی نگاشت مرتبط نخواهد بود. این بدان معناست که متدهای size() و resize() ناموفق خواهند بود. این حالت برای محدود کردن تعداد توصیف‌گرهای پرونده باز مفید است.
برای اطمینان از اعتبار نگاشت حافظه‌ی ایجادشده، پرونده مشخص‌شده با توصیف‌گر fileno، به‌صورت داخلی و به‌طور خودکار با ذخیره‌گاه پشتیبان فیزیکی در macOS همگام‌سازی می‌شود.
تغییر یافته در نسخه‌ی 3.13: پارامتر trackfd افزوده شد.
این مثال روش ساده‌ای برای استفاده از mmap نشان می‌دهد:
import mmap
# write a simple example file
with open("hello.txt", "wb") as f:
f.write(b"Hello Python!\n")
with open("hello.txt", "r+b") as f:
# memory-map the file, size 0 means whole file
mm = mmap.mmap(f.fileno(), 0)
# read content via standard file methods
print(mm.readline()) # prints b"Hello Python!\n"
# read content via slice notation
print(mm[:5]) # prints b"Hello"
# update content using slice notation;
# note that new content must have same size
mm[6:] = b" world!\n"
# ... and read again using standard file methods
mm.seek(0)
print(mm.readline()) # prints b"Hello world!\n"
# close the map
mm.close()
همچنین می‌توان از mmap به‌عنوان یک مدیر زمینه در دستور with استفاده کرد:
import mmap
with mmap.mmap(-1, 13) as mm:
mm.write(b"Hello world!")
اضافه شده در نسخه‌ی 3.2: پشتیبانی از مدیر زمینه.
مثال بعدی نحوه ایجاد یک نگاشت ناشناس (anonymous map) و مبادله داده‌ها بین فرایندهای والد و فرزند را نشان می‌دهد:
import mmap
import os
mm = mmap.mmap(-1, 13)
mm.write(b"Hello world!")
pid = os.fork()
if pid == 0: # In a child process
mm.seek(0)
print(mm.readline())
mm.close()
یک رویداد حسابرسی mmap.__new__ را با آرگومان‌های fileno، length، access، offset پرتاب می‌کند.
اشیای پرونده نگاشت‌شده به حافظه از متدهای زیر پشتیبانی می‌کنند:
-
close()¶
mmap را می‌بندد. فراخوانی‌های بعدی به سایر متدهای شیء، منجر به پرتاب استثنای ValueError خواهند شد. این کار پرونده باز را نمی‌بندد.
-
closed¶
True اگر پرونده بسته باشد.
-
find(sub[, start[, end]])¶
کمترین اندیسی در شیء را برمی‌گرداند که زیردنباله‌ی sub در آن پیدا می‌شود، به‌گونه‌ای که sub در بازه‌ی [start، end] قرار داشته باشد. آرگومان‌های اختیاری start و end همانند نمادگذاری اسلایس تفسیر می‌شوند. در صورت شکست، -1 را برمی‌گرداند.
-
flush([offset, [size, ]]*, flags=MS_SYNC)¶
تغییرات اعمال‌شده بر نسخه‌ی درون‌حافظه‌ای یک پرونده را به دیسک می‌نویسد. بدون استفاده از این فراخوانی، هیچ تضمینی وجود ندارد که تغییرات پیش از از بین رفتن شیء به دیسک نوشته شوند. اگر offset و size مشخص شده باشند، فقط تغییرات در محدوده‌ی مشخص‌شده از بایت‌ها به دیسک نوشته می‌شوند؛ در غیر این صورت، کل محدوده‌ی نگاشت به دیسک نوشته می‌شود. offset باید مضربی از PAGESIZE یا ALLOCATIONGRANULARITY باشد.
پارامتر flags رفتار همگام‌سازی را مشخص می‌کند. flags باید یکی از ثابت‌های MS_* constants موجود در سیستم باشد.
در ویندوز، پارامتر flags نادیده گرفته می‌شود.
None برای نشان دادن موفقیت برگردانده می‌شود. در صورت شکست فراخوانی، یک استثنا پرتاب می‌شود.
تغییر یافته در نسخه‌ی 3.8: پیش‌تر، در صورت موفقیت یک مقدار غیرصفر بازگردانده می‌شد؛ در ویندوز، در صورت خطا صفر بازگردانده می‌شد. در یونیکس، در صورت موفقیت یک مقدار صفر بازگردانده می‌شد؛ در صورت خطا یک استثنا پرتاب می‌شد.
تغییر یافته در نسخه‌ی 3.15: امکان مشخص کردن offset بدون size را فراهم می‌کند. پیش از این، هر دو پارامتر offset و size با هم الزامی بودند. اکنون offset را می‌توان به تنهایی مشخص کرد و عملیات تخلیه (flush) از offset تا انتهای mmap گسترش خواهد یافت.
تغییر یافته در نسخه‌ی 3.15: پارامتر flags برای کنترل رفتار همگام‌سازی اضافه شد.
-
madvise(option[, start[, length]])¶
توصیه‌ی option را درباره‌ی ناحیه‌ی حافظه‌ای که از start شروع می‌شود و به طول length بایت ادامه دارد، به هسته ارسال کنید. option باید یکی از ثابت‌های MADV_* موجود در سیستم باشد. اگر start و length حذف شوند، کل نگاشت پوشش داده می‌شود. در برخی سیستم‌ها (از جمله لینوکس)، start باید مضربی از PAGESIZE باشد.
دسترس‌پذیری: سیستم‌های دارای فراخوان سیستمی madvise().
-
move(dest, src, count)¶
count بایت را که از آفست src شروع می‌شوند، به اندیس مقصد dest کپی می‌کند. اگر mmap با ACCESS_READ ایجاد شده باشد، فراخوانی‌های move یک استثنای TypeError پرتاب خواهند کرد.
-
read([n])¶
یک bytes حاوی حداکثر n بایت را برمی‌گرداند که از موقعیت فعلی پرونده شروع می‌شود. اگر آرگومان حذف شده باشد، None باشد یا منفی باشد، همه بایت‌ها را از موقعیت فعلی پرونده تا انتهای نگاشت برمی‌گرداند. موقعیت پرونده به‌روزرسانی می‌شود تا به بعد از بایت‌های برگردانده‌شده اشاره کند.
تغییر یافته در نسخه‌ی 3.3: آرگومان می‌تواند حذف شود یا None باشد.
-
read_byte()¶
یک بایت در موقعیت فعلی پرونده را به‌عنوان یک عدد صحیح برمی‌گرداند و موقعیت پرونده را ۱ واحد جلو می‌برد.
-
readline()¶
یک خط واحد را برمی‌گرداند که از موقعیت فعلی پرونده شروع می‌شود و تا خط جدید بعدی ادامه دارد. موقعیت پرونده به‌روزرسانی می‌شود تا به بعد از بایت‌های برگردانده‌شده اشاره کند.
-
resize(newsize)¶
اندازه‌ی نگاشت و پرونده زیربنایی را، در صورت وجود، تغییر می‌دهد.
تغییر اندازه‌ی نگاشتی که با access برابر با ACCESS_READ یا ACCESS_COPY ایجادشده است، باعث پرتاب یک استثنای TypeError می‌شود. تغییر اندازه‌ی نگاشتی که با تنظیم trackfd روی False ایجادشده است، باعث پرتاب یک استثنای ValueError می‌شود.
در ویندوز: تغییر اندازه‌ی نگاشت (map) در صورتی که نگاشت‌های دیگری بر روی همان پرونده نام‌دار وجود داشته باشند، باعث پرتاب یک OSError می‌شود. تغییر اندازه‌ی یک نگاشت ناشناس (یعنی بر روی پرونده صفحه‌بندی (pagefile)) بدون هیچ پیامی یک نگاشت جدید با داده‌های اصلی کپی‌شده تا طول اندازه‌ی جدید ایجاد می‌کند.
دسترس‌پذیری: ویندوز و سیستم‌های دارای فراخوانی سیستمی mremap().
تغییر یافته در نسخه‌ی 3.11: در صورت تلاش برای تغییر اندازه زمانی که نگاشت دیگری در اختیار گرفته شده است، به‌درستی شکست می‌خورد. امکان تغییر اندازه‌ی نگاشت ناشناس در ویندوز را فراهم می‌کند
-
rfind(sub[, start[, end]])¶
بالاترین اندیسی در شیء را برمی‌گرداند که زیردنباله sub در آن یافت می‌شود، به‌طوری که sub در بازه [start، end] قرار داشته باشد. آرگومان‌های اختیاری start و end مانند نمادگذاری اسلایس تفسیر می‌شوند. در صورت شکست، -1 را برمی‌گرداند.
-
seek(pos[, whence])¶
موقعیت فعلی پرونده را تنظیم می‌کند. آرگومان whence اختیاری است و پیش‌فرض آن os.SEEK_SET یا 0 (موقعیت‌دهی مطلق پرونده) است؛ مقادیر دیگر os.SEEK_CUR یا 1 (جابه‌جایی نسبت به موقعیت فعلی) و os.SEEK_END یا 2 (جابه‌جایی نسبت به پایان پرونده) هستند.
تغییر یافته در نسخه‌ی 3.13: موقعیت مطلق جدید به‌جای None برگردانده می‌شود.
-
seekable()¶
برمی‌گرداند که آیا پرونده از مکان‌یابی (seeking) پشتیبانی می‌کند، و مقدار بازگشتی همیشه True است.
اضافه شده در نسخه‌ی 3.13.
-
set_name(name, /)¶
اگر هسته از این ویژگی پشتیبانی کند و -X dev به پایتون پاس داده شود یا پایتون در حالت اشکالات‌زدایی ساخته شده باشد، نگاشت حافظه را با name داده‌شده حاشیه‌نویسی کنید تا شناسایی آن در /proc/<pid>/maps آسان‌تر شود. طول name نباید از ۶۷ بایت شامل نویسنده‌ی پایان‌بخش '\0' بیشتر باشد.
دسترس‌پذیری: Linux >= 5.17 (kernel built with CONFIG_ANON_VMA_NAME option)
اضافه شده در نسخه‌ی 3.15.
-
size()¶
طول پرونده را برمی‌گرداند که می‌تواند بزرگ‌تر از اندازه‌ی ناحیه‌ی نگاشت‌شده در حافظه باشد. برای یک نگاشت ناشناس، اندازه‌ی آن را برمی‌گرداند.
تغییر یافته در نسخه‌ی 3.15: نگاشت‌های بی‌نام اکنون روی یونیکس پشتیبانی می‌شوند.
-
tell()¶
موقعیت فعلی اشاره‌گر پرونده را برمی‌گرداند.
-
write(bytes)¶
بایت‌های موجود در bytes را در حافظه، در موقعیت فعلی اشاره‌گر پرونده می‌نویسد و تعداد بایت‌های نوشته‌شده را برمی‌گرداند (هرگز کمتر از len(bytes) نیست، زیرا اگر نوشتن ناموفق باشد، استثنای ValueError پرتاب خواهد شد). موقعیت پرونده به‌روزرسانی می‌شود تا به بعد از بایت‌های نوشته‌شده اشاره کند. اگر mmap با ACCESS_READ ایجاد شده باشد، نوشتن در آن استثنای TypeError را پرتاب خواهد کرد.
تغییر یافته در نسخه‌ی 3.6: تعداد بایت‌های نوشته‌شده اکنون برگردانده می‌شود.
-
write_byte(byte)¶
عدد صحیح byte را در حافظه، در موقعیت فعلی اشاره‌گر پرونده می‌نویسد؛ موقعیت پرونده به اندازه 1 پیش می‌رود. اگر mmap با ACCESS_READ ایجاد شده باشد، نوشتن در آن باعث پرتاب استثنای TypeError می‌شود.