`io` --- ابزارهای اصلی برای کار با جریان‌ها¶

کد منبع: Lib/io.py

نمای کلی¶

ماژول io امکانات اصلی پایتون را برای کار با انواع مختلف ورودی/خروجی (I/O) فراهم می‌کند. سه نوع اصلی ورودی/خروجی وجود دارد: ورودی/خروجی متنی، ورودی/خروجی دودویی و ورودی/خروجی خام. این‌ها دسته‌بندی‌های کلی هستند و می‌توان برای هر یک از آن‌ها از ذخیره‌سازهای پشتیبان (backing stores) مختلفی استفاده کرد. به هر شیء عینی که به یکی از این دسته‌ها تعلق داشته باشد، شیء پرونده گفته می‌شود. سایر اصطلاحات رایج عبارت‌اند از جریان و شیء شبه‌پرونده (file-like object).

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

همه‌ی جریان‌ها نسبت به نوع داده‌ای که به آن‌ها می‌دهید حساس هستند. برای مثال، دادن یک شیء str به متد write() یک جریان دودویی باعث پرتاب یک TypeError می‌شود. همچنین دادن یک شیء bytes به متد write() یک جریان متنی نیز همین‌طور است.

تغییر یافته در نسخه‌ی 3.3: عملیات‌هایی که پیش‌تر IOError را پرتاب می‌کردند، اکنون OSError را پرتاب می‌کنند، زیرا IOError اکنون نام مستعاری از OSError است.

ورودی/خروجی متنی¶

ورودی/خروجی متنی، اشیای str را انتظار دارد و تولید می‌کند. این بدان معناست که هرگاه ذخیره‌گاه پشتیبان به‌طور ذاتی از بایت‌ها تشکیل شده باشد (مانند یک پرونده)، کدگذاری و کدگشایی داده‌ها به‌صورت شفاف انجام می‌شود و تبدیل اختیاری نویسه‌های خط جدید خاص هر پلتفرم نیز صورت می‌گیرد.

ساده‌ترین راه برای ایجاد یک جریان متنی، استفاده از open() است، با تعیین اختیاری یک کدگذاری:

f = open("myfile.txt", "r", encoding="utf-8")

جریان‌های متنی درون‌حافظه‌ای نیز به‌عنوان اشیای StringIO در دسترس هستند:

f = io.StringIO("some initial text data")

توجه

هنگام کار با یک جریان غیرمسدود، توجه داشته باشید که اگر جریان نتواند عملیات را بلافاصله انجام دهد، عملیات‌های خواندن روی اشیای ورودی/خروجی متنی ممکن است یک BlockingIOError را پرتاب کنند.

API جریان متن به‌تفصیل در مستندات TextIOBase توضیح داده شده است.

ورودی/خروجی دودویی¶

ورودی/خروجی دودویی (که به آن ورودی/خروجی بافرشده نیز گفته می‌شود) اشیاء شبه‌بایت را می‌پذیرد و اشیای bytes را تولید می‌کند. هیچ‌گونه کدگذاری، کدگشایی یا تبدیل نویسه‌های خط جدید انجام نمی‌شود. می‌توان از این دسته از جریان‌ها برای تمام انواع داده‌های غیرمتنی استفاده کرد، و همچنین زمانی که کنترل دستی بر مدیریت داده‌های متنی مورد نظر باشد.

ساده‌ترین راه برای ایجاد یک جریان دودویی، استفاده از open() با 'b' در رشته‌ی حالت است:

f = open("myfile.jpg", "rb")

جریان‌های دودویی درون‌حافظه نیز به‌عنوان اشیای BytesIO در دسترس هستند:

f = io.BytesIO(b"some initial binary data: \x00\x01")

API جریان دودویی به‌تفصیل در مستندات BufferedIOBase شرح داده شده است.

سایر ماژول‌های کتابخانه‌ای ممکن است روش‌های بیشتری برای ایجاد جریان‌های متنی یا دودویی فراهم کنند. برای مثال socket.socket.makefile() را ببینید.

ورودی/خروجی خام¶

ورودی/خروجی خام (که به آن ورودی/خروجی بدون بافر نیز گفته می‌شود) معمولاً به‌عنوان یک جزء سازنده‌ی سطح پایین برای جریان‌های دودویی و متنی استفاده می‌شود؛ به‌ندرت دستکاری مستقیم یک جریان خام از طریق کد کاربر مفید است. با این حال، می‌توانید با باز کردن یک پرونده در حالت دودویی در حالی که بافر غیرفعال است، یک جریان خام ایجاد کنید:

f = open("myfile.jpg", "rb", buffering=0)

API جریان خام به‌طور کامل در مستندات RawIOBase شرح داده شده است.

هشدار

I/O خام یک رابط سطح پایین است و متدها معمولاً باید مقادیر بازگشتی‌شان بررسی شوند و به‌صراحت دوباره فراخوانی شوند تا از تکمیل یک عملیات اطمینان حاصل شود. برای مثال، write() تعداد بایت‌های نوشته‌شده را برمی‌گرداند که ممکن است کمتر از تعداد بایت‌های ارائه‌شده باشد (یک نوشتن جزئی). اشیاء I/O سطح بالا مانند ورودی/خروجی دودویی و ورودی/خروجی متنی رفتار تلاش مجدد را پیاده‌سازی می‌کنند.

کدگذاری متن¶

کدگذاری پیش‌فرض TextIOWrapper و open() وابسته به locale است (locale.getencoding()).

با این حال، بسیاری از توسعه‌دهندگان فراموش می‌کنند هنگام باز کردن پرونده‌های متنی کدگذاری‌شده با UTF-8 (مانند JSON، TOML، Markdown و غیره...) کدگذاری را مشخص کنند، زیرا بیش‌تر پلتفرم‌های یونیکسی به‌طور پیش‌فرض از تنظیمات locale با کدگذاری UTF-8 استفاده می‌کنند. این موضوع باعث ایجاد باگ می‌شود، زیرا کدگذاری تنظیمات locale برای بیش‌تر کاربران ویندوز UTF-8 نیست. برای مثال:

# May not work on Windows when non-ASCII characters in the file.
with open("README.md") as f:
    long_description = f.read()

بنابراین، به‌شدت توصیه می‌شود که هنگام باز کردن پرونده‌های متنی، کدگذاری را به‌صراحت مشخص کنید. اگر می‌خواهید از UTF-8 استفاده کنید، encoding="utf-8" را ارسال کنید. برای استفاده از کدگذاری locale جاری، encoding="locale" از پایتون 3.10 به بعد پشتیبانی می‌شود.

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

حالت UTF-8 پایتون: می‌توان از حالت UTF-8 پایتون برای تغییر کدگذاری پیش‌فرض از کدگذاری وابسته به locale به UTF-8 استفاده کرد.
PEP 686: پایتون 3.15، حالت UTF-8 پایتون را پیش‌فرض خواهد کرد.

فعال‌سازی اختیاری هشدار کدگذاری (EncodingWarning)¶

اضافه شده در نسخه‌ی 3.10: برای جزئیات بیشتر، PEP 597 را ببینید.

برای یافتن این‌که کدگذاری پیش‌فرض locale کجا استفاده می‌شود، می‌توانید گزینه‌ی خط فرمان -X warn_default_encoding را فعال کنید یا متغیر محیطی PYTHONWARNDEFAULTENCODING را تنظیم کنید، که هنگام استفاده از کدگذاری پیش‌فرض، یک EncodingWarning نشان می‌دهد.

اگر یک API ارائه می‌دهید که از open() یا TextIOWrapper استفاده می‌کند و encoding=None را به‌عنوان یک پارامتر ارسال می‌کند، می‌توانید از text_encoding() استفاده کنید تا فراخوانندگان آن API در صورتی که encoding را ارسال نکنند، یک EncodingWarning نشان می‌دهند. با این حال، لطفاً برای APIهای جدید استفاده از UTF-8 به‌صورت پیش‌فرض (یعنی encoding="utf-8") را در نظر بگیرید.

رابط سطح‌بالای ماژول¶

io.DEFAULT_BUFFER_SIZE¶: یک عدد صحیح شامل اندازه‌ی بافر پیش‌فرضی که کلاس‌های I/O بافرشده‌ی ماژول از آن استفاده می‌کنند. open() در صورت امکان از blksize پرونده (که توسط os.stat() به دست می‌آید) استفاده می‌کند.

io.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)¶

این نام مستعاری برای تابع توکار open() است.

این تابع یک رویداد حسابرسی open را با آرگومان‌های path، mode و flags پرتاب می‌کند. ممکن است آرگومان‌های mode و flags تغییر کرده یا از فراخوانی اصلی استنتاج شده باشند.

io.open_code(path)¶

پرونده ارائه‌شده را با حالت 'rb' باز می‌کند. این تابع باید زمانی استفاده شود که هدف، رفتار با محتویات به‌عنوان کد قابل اجرا باشد.

path باید از نوع str و یک مسیر مطلق باشد.

ممکن است رفتار این تابع با فراخوانی پیشین PyFile_SetOpenCodeHook() بازنویسی شود. با این حال، با فرض اینکه path یک str و یک مسیر مطلق باشد، open_code(path) باید همیشه مانند open(path, 'rb') رفتار کند. بازنویسی رفتار برای اعتبارسنجی بیشتر یا پیش‌پردازش پرونده در نظر گرفته شده است.

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

io.text_encoding(encoding, stacklevel=2, /)¶

این یک تابع کمکی برای فراخوانی‌پذیرهایی است که از open() یا TextIOWrapper استفاده می‌کنند و یک پارامتر encoding=None دارند.

این تابع، encoding را در صورتی که None نباشد، برمی‌گرداند. در غیر این صورت، بسته به حالت UTF-8، "locale" یا "utf-8" را برمی‌گرداند.

این تابع در صورتی یک EncodingWarning را نشان می‌دهد که sys.flags.warn_default_encoding برابر true باشد و encoding برابر None باشد. stacklevel مشخص می‌کند که هشدار از کجا نشان داده می‌شود. برای مثال:

def read_text(path, encoding=None):
    encoding = io.text_encoding(encoding)  # stacklevel=2
    with open(path, encoding) as f:
        return f.read()

در این مثال، یک EncodingWarning برای فراخواننده‌ی read_text() نشان داده می‌شود.

برای اطلاعات بیشتر کدگذاری متن را ببینید.

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

تغییر یافته در نسخه‌ی 3.11: text_encoding() هنگامی که حالت UTF-8 فعال باشد و encoding برابر None باشد، مقدار "utf-8" را برمی‌گرداند.

exception io.BlockingIOError¶: این یک نام مستعار سازگاری برای استثنای توکار BlockingIOError است.

exception io.UnsupportedOperation¶: استثنایی که از OSError و ValueError ارث‌بری می‌کند و هنگامی پرتاب می‌شود که عملیات پشتیبانی‌نشده‌ای روی یک جریان فراخوانی شود.

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

sys: شامل جریان‌های استاندارد IO است: sys.stdin، sys.stdout و sys.stderr.

سلسله‌مراتب کلاس¶

پیاده‌سازی جریان‌های ورودی/خروجی به‌صورت سلسله‌مراتبی از کلاس‌ها سازمان‌دهی شده است. ابتدا کلاس‌های پایه انتزاعی (ABCها)، که برای تعیین دسته‌بندی‌های مختلف جریان‌ها استفاده می‌شوند، سپس کلاس‌های عینی که پیاده‌سازی‌های استاندارد جریان را ارائه می‌کنند.

توجه

کلاس‌های پایه انتزاعی همچنین به منظور کمک به پیاده‌سازی کلاس‌های جریان عینی، پیاده‌سازی‌های پیش‌فرضی برای برخی متدها ارائه می‌دهند. برای مثال، BufferedIOBase پیاده‌سازی‌های بهینه‌نشده‌ای برای readinto() و readline() ارائه می‌دهد.

در بالاترین سطح سلسله‌مراتب I/O، کلاس پایه انتزاعی IOBase قرار دارد. این کلاس رابط پایه برای یک جریانرا تعریف می‌کند. با این حال توجه داشته باشید که هیچ جدایی میان خواندن و نوشتن در جریان‌ها وجود ندارد؛ پیاده‌سازی‌ها مجاز هستند اگر از یک عملیات مشخص پشتیبانی نمی‌کنند، UnsupportedOperation را پرتاب کنند.

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

کلاس پایه انتزاعی (ABC) BufferedIOBase، IOBase را گسترش می‌دهد. این کلاس به بافرینگ (buffering) روی یک جریان دودویی خام (RawIOBase) می‌پردازد. زیرکلاس‌های آن، BufferedWriter، BufferedReader و BufferedRWPair، به ترتیب جریان‌های دودویی خام قابل نوشتن، قابل خواندن، و هم قابل خواندن و هم قابل نوشتن را بافر می‌کنند. BufferedRandom یک رابط بافرینگ‌شده (buffered) برای جریان‌های قابل مکان‌یابی فراهم می‌کند. زیرکلاس دیگری از BufferedIOBase، BytesIO، جریانی از بایت‌های درون حافظه است.

ABC TextIOBase، IOBase را گسترش می‌دهد. این کلاس با جریان‌هایی سروکار دارد که بایت‌های آن‌ها متن را نشان می‌دهند، و کدگذاری و کدگشایی از رشته‌ها و به رشته‌ها را مدیریت می‌کند. TextIOWrapper، که TextIOBase را گسترش می‌دهد، یک رابط متنی بافرشده برای یک جریان خام بافرشده (BufferedIOBase) است. در نهایت، StringIO یک جریان درون‌حافظه‌ای برای متن است.

نام آرگومان‌ها بخشی از مشخصات نیستند و تنها آرگومان‌های open() برای استفاده به‌عنوان آرگومان‌های کلیدواژه‌ای در نظر گرفته شده‌اند.

جدول زیر کلاس‌های پایه انتزاعی (ABC) ارائه‌شده توسط ماژول io را خلاصه می‌کند:

ABC	به ارث می‌برد	متدهای Stub	متدها و ویژگی‌های Mixin
`IOBase`		`fileno`، `seek` و `truncate`	`close`، `closed`، `__enter__`، `__exit__`، `flush`، `isatty`، `__iter__`، `__next__`، `readable`، `readline`، `readlines`، `seekable`، `tell`، `writable` و `writelines`
`RawIOBase`	`IOBase`	`readinto` و `write`	متدهای موروثی `IOBase`، `read` و `readall`
`BufferedIOBase`	`IOBase`	`detach`، `read`، `read1` و `write`	متدهای موروثی `IOBase`، `readinto` و `readinto1`
`TextIOBase`	`IOBase`	`detach`، `read`، `readline` و `write`	متدهای به‌ارث‌برده‌شده از `IOBase`، `encoding`، `errors` و `newlines`

کلاس‌های پایه‌ی I/O¶

class io.IOBase¶

کلاس پایه انتزاعی برای تمام کلاس‌های I/O.

این کلاس، پیاده‌سازی‌های انتزاعی خالی برای بسیاری از متدها فراهم می‌کند که کلاس‌های مشتق‌شده می‌توانند آن‌ها را به‌صورت انتخابی بازنویسی کنند؛ پیاده‌سازی‌های پیش‌فرض نشان‌دهنده پرونده‌ای هستند که نمی‌توان آن را خواند، نوشت یا مکان‌یابی (seek) کرد.

با وجود اینکه IOBase متدهای read() و write() را تعریف نمی‌کند، زیرا امضاهای آن‌ها متفاوت خواهد بود، پیاده‌سازی‌ها و کلاینت‌ها باید آن متدها را بخشی از رابط بدانند. همچنین، پیاده‌سازی‌ها ممکن است هنگام فراخوانی عملیاتی که پشتیبانی نمی‌شوند، یک ValueError (یا UnsupportedOperation) پرتاب کنند.

نوع پایه‌ای که برای داده‌های دودوییِ خوانده‌شده از پرونده یا نوشته‌شده در پرونده به کار می‌رود، bytes است. سایر اشیاء شبه‌بایت نیز به‌عنوان آرگومان‌های متد پذیرفته می‌شوند. کلاس‌های ورودی/خروجی متنی با داده‌های str کار می‌کنند.

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

IOBase (و زیرکلاس‌های آن) از پروتکل پیمایش‌گر پشتیبانی می‌کند، به این معنا که می‌توان بر روی یک شیء IOBase تکرار کرد و سطرهای یک جریان را به دست آورد. سطرهای بسته به اینکه جریان یک جریان دودویی باشد (که بایت‌ها را به دست می‌دهد) یا یک جریان متنی (که رشته‌های نویسه‌ای را به دست می‌دهد)، کمی متفاوت تعریف می‌شوند. readline() را در زیر ببینید.

IOBase همچنین یک مدیر زمینه است و بنابراین از دستور with پشتیبانی می‌کند. در این مثال، file پس از پایان یافتن بدنه‌ی دستور with بسته می‌شود—حتی اگر استثنایی رخ دهد:

with open('spam.txt', 'w') as file:
    file.write('Spam and eggs!')

IOBase این ویژگی‌های داده و متدها را ارائه می‌دهد:

close()¶

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

برای سهولت، فراخوانی این متد بیش از یک بار مجاز است؛ با این حال، تنها اولین فراخوانی اثر خواهد داشت.

closed¶: True اگر جریان بسته باشد.

fileno()¶: توصیف‌گر پرونده (یک عدد صحیح) زیربنایی جریان را در صورت وجود برمی‌گرداند. اگر شیء IO از توصیف‌گر پرونده استفاده نکند، یک OSError پرتاب می‌شود.

flush()¶: در صورت امکان، بافرهای نوشتن جریان را تخلیه می‌کند. این کار برای جریان‌های فقط‌خواندنی و غیرمسدودکننده هیچ کاری انجام نمی‌دهد.

isatty()¶: اگر جریان تعاملی باشد (یعنی به یک پایانه/دستگاه tty متصل باشد)، True را برمی‌گرداند.

readable()¶: اگر بتوان از جریان خواند، True برمی‌گرداند. اگر False باشد، read() OSError را پرتاب می‌کند.

readline(size=-1, /)¶

یک خط را از جریان می‌خواند و برمی‌گرداند. اگر size مشخص شده باشد، حداکثر size بایت خوانده خواهد شد.

پایان‌دهنده خط برای پرونده‌های دودویی همیشه b'\n' است؛ برای پرونده‌های متنی، می‌توان از آرگومان newline در open() برای انتخاب پایان‌دهنده(های) خط شناسایی‌شده استفاده کرد.

readlines(hint=-1, /)¶

سطرها را از جریان می‌خواند و فهرستی از سطرها را برمی‌گرداند. می‌توان hint را برای کنترل تعداد سطرهای خوانده‌شده مشخص کرد: اگر اندازه‌ی کل تمام سطرهای تاکنون (بر حسب بایت/نویسه) از hint بیشتر شود، سطرهای بیشتری خوانده نخواهد شد.

مقادیر hint که 0 یا کمتر باشند، و همچنین None، به‌عنوان بدون راهنما در نظر گرفته می‌شوند.

توجه داشته باشید که از قبل می‌توان با استفاده از for line in file: ... روی اشیای پرونده پیمایش کرد، بدون فراخوانی file.readlines().

seek(offset, whence=os.SEEK_SET, /)¶

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

os.SEEK_SET یا 0 -- شروع جریان (پیش‌فرض)؛ offset باید صفر یا مثبت باشد
os.SEEK_CUR یا 1 -- موقعیت جاری جریان؛ offset می‌تواند منفی باشد
os.SEEK_END یا 2 -- پایان جریان؛ offset معمولاً منفی است

اضافه شده در نسخه‌ی 3.1: ثابت‌های SEEK_*.

اضافه شده در نسخه‌ی 3.3: برخی سیستم‌عامل‌ها ممکن است از مقادیر اضافی، مانند os.SEEK_HOLE یا os.SEEK_DATA پشتیبانی کنند. مقادیر معتبر برای یک پرونده ممکن است به این بستگی داشته باشد که پرونده در حالت متنی باز شده باشد یا دودویی.

seekable()¶: اگر جریان از دسترسی تصادفی پشتیبانی کند، True برمی‌گرداند. اگر False باشد، seek()، tell() و truncate() استثنای OSError را پرتاب خواهند کرد.

tell()¶: موقعیت فعلی جریان را برمی‌گرداند.

truncate(size=None, /)¶: جریان را به size داده‌شده بر حسب بایت تغییر اندازه دهید (یا اگر size مشخص نشده باشد، به موقعیت فعلی). موقعیت فعلی جریان تغییر نمی‌کند. این تغییر اندازه می‌تواند اندازه فعلی پرونده را افزایش یا کاهش دهد. در صورت افزایش، محتوای بخش جدید پرونده به پلتفرم بستگی دارد (در بیشتر سیستم‌ها، بایت‌های اضافی با صفر پر می‌شوند). اندازه جدید پرونده برگردانده می‌شود.

تغییر یافته در نسخه‌ی 3.5: اکنون ویندوز هنگام افزایش اندازه‌ی پرونده‌ها، آن‌ها را با صفر پر می‌کند.

writable()¶: اگر جریان از نوشتن پشتیبانی کند، True را برمی‌گرداند. اگر False باشد، write() و truncate() استثنای OSError را پرتاب می‌کنند.

writelines(lines, /)¶: فهرستی از سطرها را در جریان بنویسید. جداکننده‌های خط اضافه نمی‌شوند، بنابراین معمول است که هر یک از سطرهای ارائه‌شده، در انتهای خود یک جداکننده‌ی خط داشته باشد.

__del__()¶: آماده‌سازی برای نابودی شیء. IOBase پیاده‌سازی پیش‌فرضی برای این متد ارائه می‌دهد که متد close() نمونه را فراخوانی می‌کند.

class io.RawIOBase¶

کلاس پایه برای جریان‌های دودویی خام. این کلاس از IOBase ارث می‌برد.

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

RawIOBase این متدها را علاوه بر متدهای IOBase فراهم می‌کند:

read(size=-1, /)¶

حداکثر size بایت از شیء بخوانید و آن‌ها را برگردانید. برای سهولت، اگر size مشخص‌نشده باشد یا -1 باشد، تمام بایت‌ها تا EOF برگردانده می‌شوند.

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

اگر ۰ بایت بازگردانده شود و size برابر ۰ نباشد، این پایان پرونده را نشان می‌دهد. اگر شیء در حالت غیرمسدودکننده باشد و هیچ بایتی در دسترس نباشد، None بازگردانده می‌شود.

پیاده‌سازی پیش‌فرض به readall() و readinto() ارجاع می‌دهد.

readall()¶

تمام بایت‌ها را از جریانتا EOF بخوانید و برگردانید، در صورت لزوم با استفاده از چندین فراخوانی جریان.

اگر 0 بایت برگردانده شود، این نشان‌دهنده پایان پرونده است. اگر شیء در حالت غیرمسدودکننده (non-blocking) باشد و read() زیربنایی None را برگرداند که نشان می‌دهد هیچ بایتی در دسترس نیست، None برگردانده می‌شود.

readinto(b, /)¶

بایت‌ها را در یک bytes-like object از پیش تخصیص‌یافته و قابل‌نوشتن b می‌خواند و تعداد بایت‌های خوانده‌شده را برمی‌گرداند. برای مثال، b ممکن است یک bytearray باشد.

اگر 0 بازگردانده شود و len(b) برابر 0 نباشد، این نشان‌دهنده پایان پرونده است. اگر شیء در حالت غیرمسدودکننده باشد و هیچ بایتی در دسترس نباشد، None بازگردانده می‌شود.

write(b, /)¶: bytes-like object داده‌شده، b، را در جریان خام زیرین می‌نویسد و تعداد بایت‌های نوشته‌شده را برمی‌گرداند. این مقدار، بسته به جزئیات جریان خام زیرین و به‌ویژه اگر در حالت غیرمسدودکننده باشد، می‌تواند کمتر از طول b بر حسب بایت باشد. اگر جریان خام به‌گونه‌ای تنظیم شده باشد که مسدود نکند و هیچ بایتی به‌راحتی قابل نوشتن در آن نباشد، None برگردانده می‌شود. فراخواننده ممکن است پس از بازگشت این متد، b را آزاد کند یا تغییر دهد، بنابراین پیاده‌سازی باید تنها در حین فراخوانی متد به b دسترسی داشته باشد.

هشدار

این تابع تضمین نمی‌کند که همه‌ی بایت‌ها نوشته شوند یا استثنایی پرتاب شود. فراخوانندگان می‌توانند آن رفتار را با بررسی مقدار بازگشتی پیاده‌سازی کنند و اگر این مقدار کمتر از طول b باشد، با حلقه‌ای از فراخوانی‌های write بیشتر، همه‌ی بایت‌های نوشته‌نشده را بنویسند. اشیای سطح بالای I/O مانند ورودی/خروجی دودویی و ورودی/خروجی متنی رفتار تلاش مجدد را پیاده‌سازی می‌کنند.

class io.BufferedIOBase¶

کلاس پایه برای جریان‌های دودویی که از نوعی بافرینگ (buffering) پشتیبانی می‌کنند. این کلاس از IOBase ارث می‌برد.

تفاوت اصلی با RawIOBase این است که متدهای read()، readinto() و write() تلاش خواهند کرد (به‌ترتیب) تا ورودی را به اندازه‌ی درخواست‌شده بخوانند یا تمام داده‌های ارائه‌شده را خارج کنند.

علاوه بر این، اگر جریان خام زیربنایی در حالت غیرمسدودکننده باشد، هرگاه سیستم وضعیت would block را برگرداند، write() استثنا BlockingIOError را با BlockingIOError.characters_written پرتاب می‌کند و read() داده‌های خوانده‌شده تاکنون را برمی‌گرداند، یا اگر داده‌ای در دسترس نباشد None برمی‌گرداند.

علاوه بر این، متد read() پیاده‌سازی پیش‌فرضی که به readinto() ارجاع دهد، ندارد.

یک پیاده‌سازی معمول BufferedIOBase نباید از یک پیاده‌سازی RawIOBase ارث ببرد، بلکه باید آن را بپوشاند، همان‌طور که BufferedWriter و BufferedReader این کار را انجام می‌دهند.

BufferedIOBase این ویژگی‌های داده و متدها را علاوه بر موارد موجود در IOBase، ارائه می‌کند یا بازنویسی می‌کند:

raw¶: جریان خام زیربنایی (یک نمونه از RawIOBase) که BufferedIOBase با آن سروکار دارد. این بخشی از API BufferedIOBase نیست و ممکن است در برخی پیاده‌سازی‌ها وجود نداشته باشد.

detach()¶

جریان خام زیربنایی را از بافر جدا می‌کند و آن را برمی‌گرداند.

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

برخی بافرها، مانند BytesIO، مفهوم یک جریان خام واحد برای بازگرداندن از این متد را ندارند. آن‌ها UnsupportedOperation را پرتاب می‌کنند.

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

read(size=-1, /)¶

حداکثر size بایت را می‌خواند و برمی‌گرداند. اگر آرگومان حذف‌شده باشد، None باشد یا منفی باشد، تا حد ممکن می‌خواند.

ممکن است بایت‌های کمتری نسبت به تعداد درخواست‌شده بازگردانده شود. اگر جریان از قبل در EOF باشد، یک شیء bytes خالی بازگردانده می‌شود. ممکن است بیش از یک خواندن انجام شود و در صورت مواجهه با خطاهای خاص، فراخوانی‌ها بازآزمایی شوند؛ برای جزئیات بیشتر os.read() و PEP 475 را ببینید. بازگردانده شدن کمتر از size بایت، به این معنا نیست که EOF قریب‌الوقوع است.

هنگام خواندن تا حد امکان، پیاده‌سازی پیش‌فرض در صورت در دسترس بودن از raw.readall استفاده می‌کند (که باید RawIOBase.readall() را پیاده‌سازی کند)، در غیر این صورت در یک حلقه می‌خواند تا زمانی که read None، یک bytes خالی، یا یک خطای غیرقابل‌تلاش مجدد را برگرداند. برای بیشتر جریان‌ها، این فرآیند تا EOF ادامه دارد، اما برای جریان‌های غیرمسدودکننده ممکن است داده‌های بیشتری در دسترس قرار بگیرند.

توجه

هنگامی که جریان خام زیربنایی غیرمسدودکننده باشد، پیاده‌سازی‌ها ممکن است در صورت در دسترس نبودن داده، BlockingIOError را پرتاب کنند یا None را برگردانند. پیاده‌سازی‌های io مقدار None را برمی‌گردانند.

read1(size=-1, /)¶: حداکثر تا size بایت را با فراخوانی readinto() می‌خواند و برمی‌گرداند؛ این متد ممکن است در صورت مواجهه با EINTR مطابق PEP 475 دوباره تلاش کند. اگر size برابر -1 باشد یا ارائه نشده باشد، پیاده‌سازی مقدار دلخواهی برای size انتخاب خواهد کرد.

توجه

هنگامی که جریان خام زیربنایی غیرمسدودکننده باشد، پیاده‌سازی‌ها ممکن است در صورت در دسترس نبودن داده، BlockingIOError را پرتاب کنند یا None را برگردانند. پیاده‌سازی‌های io مقدار None را برمی‌گردانند.

readinto(b, /)¶

بایت‌ها را در یک شیء شبه‌بایت (bytes-like object) از پیش تخصیص‌داده‌شده و قابل‌نوشتن b می‌خواند و تعداد بایت‌های خوانده‌شده را برمی‌گرداند. برای مثال، b ممکن است یک bytearray باشد.

مانند read()، ممکن است چندین عملیات خواندن به جریان خام زیرین صادر شود، مگر اینکه این جریان تعاملی باشد.

اگر جریان خام زیربنایی در حالت غیرمسدودکننده باشد و در حال حاضر داده‌ای در دسترس نداشته باشد، یک BlockingIOError پرتاب می‌شود.

readinto1(b, /)¶

بایت‌ها را با استفاده از حداکثر یک فراخوانی متد read() (یا readinto()) جریان خام زیربنایی، در یک شیء شبه‌بایت b از پیش تخصیص‌یافته و قابل نوشتن بخوانید. تعداد بایت‌های خوانده‌شده را برگردانید.

اگر جریان خام زیربنایی در حالت غیرمسدودکننده باشد و در حال حاضر داده‌ای در دسترس نداشته باشد، یک BlockingIOError پرتاب می‌شود.

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

write(b, /)¶

bytes-like object داده‌شده، b، را می‌نویسد و تعداد بایت‌های نوشته‌شده را برمی‌گرداند (همیشه برابر با طول b بر حسب بایت است، زیرا اگر نوشتن ناموفق باشد، یک OSError پرتاب می‌شود). بسته به پیاده‌سازی واقعی، این بایت‌ها ممکن است به‌راحتی در جریان زیرین نوشته شوند، یا به دلایل کارایی و تأخیر در یک بافر نگهداری شوند.

در حالت غیرمسدودکننده، اگر داده‌ای نیاز باشد در جریان خام نوشته شود اما جریان خام نتواند همه‌ی داده‌ها را بدون مسدودسازی بپذیرد، استثنای BlockingIOError پرتاب می‌شود.

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

ورودی/خروجی خام پرونده¶

class io.FileIO(name, mode='r', closefd=True, opener=None)¶

یک جریان دودویی خام که نشان‌دهنده‌ی پرونده‌ای در سطح سیستم‌عامل حاوی داده‌های بایتی است. این جریان از RawIOBase ارث می‌برد و طراحی دسترسی سطح پایین آن را پیاده‌سازی می‌کند. این بدان معناست که write() تضمین نمی‌کند که همه‌ی بایت‌ها نوشته شوند و read() ممکن است بایت‌های کمتری نسبت به تعداد درخواست‌شده بخواند، حتی اگر بایت‌های بیشتری در پرونده زیرین موجود باشد. برای داشتن رفتار «نوشتن همه» و «حداقل خواندن»، از ورودی/خروجی دودویی استفاده کنید.

name می‌تواند یکی از دو مورد باشد:

یک رشته نویسه‌ای یا شیء bytes که مسیر پرونده‌ای را که باز خواهد شد نشان می‌دهد. در این حالت closefd باید True باشد (پیش‌فرض)؛ در غیر این صورت یک خطا پرتاب خواهد شد.
عدد صحیحی که شماره‌ی یک توصیف‌گر پرونده موجود در سطح سیستم‌عامل را نشان می‌دهد و شیء FileIO حاصل، دسترسی به آن را فراهم خواهد کرد. هنگامی که شیء FileIO بسته شود، این توصیف‌گر پرونده نیز بسته خواهد شد، مگر آنکه closefd روی False تنظیم شده باشد.

mode می‌تواند 'r'، 'w'، 'x' یا 'a' برای خواندن (پیش‌فرض)، نوشتن، ایجاد انحصاری یا الحاق باشد. اگر پرونده در زمان باز شدن برای نوشتن یا الحاق وجود نداشته باشد، ایجاد می‌شود؛ این پرونده در زمان باز شدن برای نوشتن کوتاه می‌شود. اگر پرونده در زمان باز شدن برای ایجاد از قبل وجود داشته باشد، FileExistsError پرتاب می‌شود. باز کردن پرونده برای ایجاد، مستلزم نوشتن است، بنابراین این حالت رفتاری مشابه 'w' دارد. برای امکان‌پذیر شدن خواندن و نوشتن همزمان، '+' را به حالت اضافه کنید.

می‌توانید با گذراندن یک شیء فراخوانی‌پذیر به‌عنوان opener از یک بازکننده سفارشی استفاده کنید. سپس توصیف‌گر پرونده زیربنایی برای شیء پرونده با فراخوانی opener با (name, flags) به دست می‌آید. opener باید یک توصیف‌گر پرونده باز را برگرداند (گذراندن os.open به‌عنوان opener منجر به عملکردی مشابه گذراندن None می‌شود).

پرونده تازه ایجادشده غیرقابل ارث‌بردن است.

برای مثال‌هایی درباره‌ی استفاده از پارامتر opener، تابع توکار open() را ببینید.

هشدار

FileIO یک شیء ورودی/خروجی سطح پایین است و برای اعضایی مانند read() و write()، باید مقادیر بازگشتی آن‌ها به‌صورت صریح در یک حلقه‌ی تلاش مجدد بررسی شوند تا رفتار «نوشتن همه» و «حداقل خواندن» پیاده‌سازی شود. اشیاء ورودی/خروجی سطح بالا ورودی/خروجی دودویی و ورودی/خروجی متنی رفتار تلاش مجدد را پیاده‌سازی می‌کنند.

تغییر یافته در نسخه‌ی 3.3: پارامتر opener افزوده شد. حالت 'x' افزوده شد.

تغییر یافته در نسخه‌ی 3.4: این پرونده اکنون غیرقابل ارث‌بردن است.

FileIO این ویژگی‌های داده‌ای را علاوه بر ویژگی‌های RawIOBase و IOBase ارائه می‌دهد:

mode¶: حالت، همان‌طور که در سازنده داده شده است.

name¶: نام پرونده. هنگامی که در سازنده نامی داده نشده باشد، این مقدار توصیف‌گر پرونده است.

جریان‌های بافرشده¶

جریان‌های ورودی/خروجی بافرشده، نسبت به ورودی/خروجی خام، رابط سطح بالاتری را برای یک دستگاه ورودی/خروجی فراهم می‌کنند.

class io.BytesIO(initial_bytes=b'')¶

یک جریان دودویی که از یک بافر بایت در حافظه استفاده می‌کند. این کلاس از BufferedIOBase ارث می‌برد. هنگامی که متد close() فراخوانی شود، بافر دور انداخته می‌شود.

آرگومان اختیاری initial_bytes یک bytes-like object است که حاوی داده‌های اولیه است.

BytesIO این متدها را علاوه بر متدهای BufferedIOBase و IOBase ارائه می‌دهد یا بازنویسی می‌کند:

getbuffer()¶

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

>>> b = io.BytesIO(b"abcdef")
>>> view = b.getbuffer()
>>> view[2:4] = b"56"
>>> b.getvalue()
b'ab56ef'

توجه

تا زمانی که نما وجود دارد، نمی‌توان اندازه‌ی شیء BytesIO را تغییر داد یا آن را بست.

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

getvalue()¶: bytes حاوی کل محتوای بافر را برمی‌گرداند.

read1(size=-1, /)¶: در BytesIO، این همان read() است.

تغییر یافته در نسخه‌ی 3.7: آرگومان size اکنون اختیاری است.

readinto1(b, /)¶: در BytesIO، این همان readinto() است.

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

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)¶

یک جریان دودویی بافرشده که دسترسی سطح بالاتری به یک جریان دودویی خام RawIOBase خواندنی و غیرقابل مکان‌یابی فراهم می‌کند. این جریان از BufferedIOBase ارث می‌برد.

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

سازنده، یک BufferedReader را برای جریان raw قابل‌خواندن و buffer_size داده‌شده ایجاد می‌کند. اگر buffer_size ذکر نشود، از DEFAULT_BUFFER_SIZE استفاده می‌شود.

BufferedReader علاوه بر متدهای BufferedIOBase و IOBase، این متدها را فراهم می‌کند یا بازنویسی می‌نماید:

peek(size=0, /)¶: بایت‌هایی از جریان را بدون پیش بردن موقعیت برمی‌گرداند. تعداد بایت‌های برگردانده‌شده ممکن است کمتر یا بیشتر از تعداد درخواست‌شده باشد. اگر جریان خام زیربنایی غیرمسدودکننده باشد و عملیات منجر به انسداد شود، بایت‌های خالی برمی‌گرداند.

read(size=-1, /)¶: در BufferedReader، این همان io.BufferedIOBase.read() است

read1(size=-1, /)¶: در BufferedReader، این همان io.BufferedIOBase.read1() است

تغییر یافته در نسخه‌ی 3.7: آرگومان size اکنون اختیاری است.

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)¶

یک جریان دودویی بافردار که دسترسی سطح بالاتری را به یک جریان دودویی خام قابل نوشتن و غیرقابل جستجو از نوع RawIOBase فراهم می‌کند. این کلاس از BufferedIOBase ارث‌بری می‌کند.

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

هنگامی که بافر برای همه‌ی داده‌های در انتظار بیش از حد کوچک شود؛
هنگامی که flush() فراخوانی می‌شود؛
هنگامی که یک seek() درخواست شود (برای اشیای BufferedRandom);
هنگامی که شیء BufferedWriter بسته یا نابود می‌شود.

سازنده یک BufferedWriter برای جریان raw قابل‌نوشتن داده‌شده ایجاد می‌کند. اگر buffer_size داده نشود، مقدار پیش‌فرض آن DEFAULT_BUFFER_SIZE خواهد بود.

BufferedWriter این متدها را علاوه بر متدهای BufferedIOBase و IOBase فراهم می‌کند یا بازنویسی می‌کند:

flush()¶: بایت‌های نگه‌داشته‌شده در بافر را به جریان خام وارد کنید. اگر جریان خام مسدود شود، باید یک BlockingIOError پرتاب شود.

write(b, /)¶: شیء شبه‌بایت، b را می‌نویسد و تعداد بایت‌های نوشته‌شده را برمی‌گرداند. در حالت غیرمسدودکننده، اگر نیاز باشد بافر نوشته شود اما جریان خام مسدود شود، استثنای BlockingIOError که BlockingIOError.characters_written آن تنظیم شده است، پرتاب می‌شود.

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)¶

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

سازنده یک خواننده و نویسنده برای جریان خام قابل مکان‌یابی داده‌شده در اولین آرگومان ایجاد می‌کند. اگر buffer_size حذف شود، به‌طور پیش‌فرض برابر با DEFAULT_BUFFER_SIZE خواهد بود.

BufferedRandom قادر است هر کاری را که BufferedReader یا BufferedWriter می‌توانند انجام دهند، انجام دهد. علاوه بر این، پیاده‌سازی seek() و tell() تضمین شده است.

class io.BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE, /)¶

یک جریان دودویی بافرشده که دسترسی سطح بالاتری به دو جریان دودویی خام غیرقابل جستجو (non-seekable) از RawIOBase فراهم می‌کند — یکی قابل خواندن و دیگری قابل نوشتن. این کلاس از BufferedIOBase ارث می‌برد.

reader و writer اشیاء RawIOBase هستند که به‌ترتیب قابل خواندن و قابل نوشتن می‌باشند. اگر buffer_size ذکر نشود، مقدار پیش‌فرض آن DEFAULT_BUFFER_SIZE خواهد بود.

BufferedRWPair همه متدهای BufferedIOBase را پیاده‌سازی می‌کند، به‌جز detach() که UnsupportedOperation را پرتاب می‌کند.

هشدار

BufferedRWPair تلاش نمی‌کند دسترسی‌ها به جریان‌های خام زیربنایی خود را همگام‌سازی کند. نباید یک شیء یکسان را به‌عنوان خواننده و نویسنده به آن بدهید؛ در عوض از BufferedRandom استفاده کنید.

ورودی/خروجی متنی¶

class io.TextIOBase¶

کلاس پایه برای جریان‌های متنی. این کلاس یک رابط مبتنی بر نویسه و خط برای ورودی/خروجی جریان فراهم می‌کند. این کلاس از IOBase ارث می‌برد.

TextIOBase این ویژگی‌های داده و متدها را علاوه بر موارد موجود در IOBase ارائه می‌دهد یا بازنویسی می‌کند:

encoding¶: نام کدگذاری‌ای که برای کدگشایی بایت‌های جریان به رشته‌ها و کدگذاری رشته‌ها به بایت‌ها استفاده می‌شود.

errors¶: تنظیم خطای کدگشا یا کدگذار.

newlines¶: یک رشته، یک تاپل از رشته‌ها، یا None، که نشان‌دهنده‌ی سطرهای جدیدی است که تاکنون ترجمه شده‌اند. بسته به پیاده‌سازی و پرچم‌های اولیه‌ی سازنده، ممکن است این در دسترس نباشد.

buffer¶: بافر دودویی زیربنایی (یک نمونه از BufferedIOBase یا RawIOBase) که TextIOBase با آن سروکار دارد. این بخشی از API TextIOBase نیست و ممکن است در برخی پیاده‌سازی‌ها وجود نداشته باشد.

detach()¶

بافر دودویی زیربنایی را از TextIOBase جدا می‌کند و آن را برمی‌گرداند.

پس از جدا شدن بافر زیرین، TextIOBase در وضعیت غیرقابل‌استفاده قرار می‌گیرد.

برخی از پیاده‌سازی‌های TextIOBase، مانند StringIO، ممکن است مفهوم یک بافرزیرین را نداشته باشند و فراخوانی این متد موجب پرتاب UnsupportedOperation می‌شود.

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

read(size=-1, /)¶: حداکثر size نویسه را از جریان به‌صورت یک str واحد می‌خواند و برمی‌گرداند. اگر size منفی یا None باشد، تا EOF می‌خواند.

readline(size=-1, /)¶

تا خط جدید یا EOF می‌خواند و یک str واحد برمی‌گرداند. اگر جریان از قبل در EOF باشد، یک رشته خالی برگردانده می‌شود.

اگر size تعیین شده باشد، حداکثر size نویسه خوانده خواهد شد.

seek(offset, whence=SEEK_SET, /)¶

موقعیت جریان را به offset داده‌شده تغییر می‌دهد. رفتار به پارامتر whence بستگی دارد. مقدار پیش‌فرض برای whence، SEEK_SET است.

SEEK_SET یا 0: جابه‌جایی از ابتدای جریان (پیش‌فرض)؛ offset باید یا عددی باشد که توسط TextIOBase.tell() برگردانده شده است، یا صفر. هر مقدار دیگری برای offset رفتار تعریف‌نشده‌ای ایجاد می‌کند.
SEEK_CUR یا 1: «جستجو» (seek) به موقعیت جاری؛ offset باید صفر باشد، که یک عملیات بدون اثر است (تمام مقادیر دیگر پشتیبانی نمی‌شوند).
SEEK_END یا 2: به انتهای جریان بروید؛ offset باید صفر باشد (تمام مقادیر دیگر پشتیبانی نمی‌شوند).

موقعیت مطلق جدید را به‌عنوان یک عدد غیرشفاف برمی‌گرداند.

اضافه شده در نسخه‌ی 3.1: ثابت‌های SEEK_*.

tell()¶: موقعیت جاری جریان را به‌عنوان یک عدد غیرشفاف برمی‌گرداند. این عدد معمولاً نشان‌دهنده‌ی تعدادی بایت در فضای ذخیره‌سازی دودویی زیرین نیست.

write(s, /)¶: رشته‌ی s را در جریان می‌نویسد و تعداد نویسه‌های نوشته‌شده را برمی‌گرداند.

class io.TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False, write_through=False)¶

یک جریان متنی بافرشده که دسترسی سطح بالاتری به یک جریان دودویی بافرشده از BufferedIOBase فراهم می‌کند. این جریان از TextIOBase ارث‌بری می‌کند.

encoding نام کدگذاری‌ای را مشخص می‌کند که جریان با آن کدگشایی یا کدگذاری می‌شود. در حالت UTF-8، این مقدار به‌طور پیش‌فرض UTF-8 است. در غیر این صورت، مقدار پیش‌فرض آن locale.getencoding() است. می‌توان از encoding="locale" برای مشخص کردن صریح کدگذاری locale استفاده کرد. برای اطلاعات بیشتر کدگذاری متن را ببینید.

errors رشته‌ای اختیاری است که چگونگی مدیریت خطاهای کدگذاری و کدگشایی را مشخص می‌کند. برای پرتاب استثنای ValueError در صورت بروز خطای کدگذاری، 'strict' را ارسال کنید (مقدار پیش‌فرض None نیز همین اثر را دارد)، یا برای نادیده گرفتن خطاها، 'ignore' را ارسال کنید. (توجه داشته باشید که نادیده گرفتن خطاهای کدگذاری می‌تواند منجر به از دست رفتن داده شود.) 'replace' باعث می‌شود یک نشانگر جایگزینی (مانند '?') در جایی که داده نادرست وجود دارد درج شود. 'backslashreplace' باعث می‌شود داده نادرست با یک دنباله خنثی‌سازی حاوی بک‌اسلش جایگزین شود. هنگام نوشتن، می‌توان از 'xmlcharrefreplace' (جایگزینی با ارجاع نویسه مناسب XML) یا 'namereplace' (جایگزینی با دنباله‌های خنثی‌سازی \N{...}) استفاده کرد. هر نام مدیریت خطای دیگری که با codecs.register_error() ثبت‌شده باشد نیز معتبر است.

newline نحوه مدیریت پایان سطرها را کنترل می‌کند. این پارامتر می‌تواند None، ''، '\n'، '\r' و '\r\n' باشد. این پارامتر به‌صورت زیر عمل می‌کند:

هنگام خواندن ورودی از جریان، اگر newline برابر None باشد، حالت سطرهای جدید همگانی (universal newlines) فعال می‌شود. سطرهای موجود در ورودی می‌توانند با '\n'، '\r' یا '\r\n' به پایان برسند، و این موارد پیش از بازگشت به فراخواننده به '\n' تبدیل می‌شوند. اگر newline برابر '' باشد، حالت سطرهای جدید همگانی (universal newlines) فعال می‌شود، اما پایان سطرهای بدون تبدیل به فراخواننده بازگردانده می‌شود. اگر newline هر یک از مقادیر مجاز دیگر را داشته باشد، سطرهای ورودی فقط با رشته داده‌شده به پایان می‌رسند و پایان خط بدون تبدیل به فراخواننده بازگردانده می‌شود.
هنگام نوشتن خروجی در جریان، اگر newline برابر None باشد، همه نویسه‌های '\n' نوشته‌شده به جداکننده خط پیش‌فرض سیستم، os.linesep، تبدیل می‌شوند. اگر newline برابر '' یا '\n' باشد، هیچ تبدیلی صورت نمی‌گیرد. اگر newline هر یک از دیگر مقادیر مجاز باشد، همه نویسه‌های '\n' نوشته‌شده به رشته داده‌شده تبدیل می‌شوند.

اگر line_buffering برابر True باشد، هنگامی که یک فراخوانی write شامل یک نویسه خط جدید یا بازگشت به ابتدای سطر باشد، flush() به‌طور ضمنی فراخوانی می‌شود.

اگر write_through برابر True باشد، تضمین می‌شود که فراخوانی‌های write() در بافر نگهداری نمی‌شوند: هر داده‌ای که روی شیء TextIOWrapper نوشته شود، بلافاصله به buffer دودویی زیرین آن منتقل می‌شود.

تغییر یافته در نسخه‌ی 3.3: آرگومان write_through اضافه شده است.

تغییر یافته در نسخه‌ی 3.3: کدگذاری پیش‌فرض اکنون locale.getpreferredencoding(False) است، به‌جای locale.getpreferredencoding(). کدگذاری locale را به‌طور موقت با locale.setlocale() تغییر ندهید؛ به‌جای کدگذاری ترجیحی کاربر، از کدگذاری locale فعلی استفاده کنید.

تغییر یافته در نسخه‌ی 3.10: آرگومان encoding اکنون از نام کدگذاری ساختگی "locale" پشتیبانی می‌کند.

توجه

هنگامی که جریان خام زیربنایی غیرمسدودکننده باشد، اگر یک عملیات خواندن نتواند بلافاصله کامل شود، ممکن است یک BlockingIOError پرتاب شود.

TextIOWrapper علاوه بر مواردِ TextIOBase و IOBase، این ویژگی‌های داده‌ای و متدها را فراهم می‌کند:

line_buffering¶: اینکه بافرینگ سطری (line buffering) فعال است یا خیر.

write_through¶: اینکه آیا نوشتارها بلافاصله به بافر دودویی زیرین ارسال می‌شوند.

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

reconfigure(*, encoding=None, errors=None, newline=None, line_buffering=None, write_through=None)¶

این جریان متنی را با استفاده از تنظیمات جدید برای encoding، errors، newline، line_buffering و write_through بازپیکربندی کنید.

پارامترهای مشخص‌نشده، تنظیمات فعلی را حفظ می‌کنند، به‌جز وقتی که encoding مشخص شده باشد اما errors مشخص نشده باشد؛ در این صورت از errors='strict' استفاده می‌شود.

اگر پیش‌تر مقداری داده از جریان خوانده شده باشد، تغییر کدگذاری یا خط جدید ممکن نیست. از سوی دیگر، تغییر کدگذاری پس از نوشتن ممکن است.

این متد پیش از تنظیم پارامترهای جدید، جریان را به‌صورت ضمنی تخلیه می‌کند.

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

تغییر یافته در نسخه‌ی 3.11: این متد از گزینه‌ی encoding="locale" پشتیبانی می‌کند.

seek(cookie, whence=os.SEEK_SET, /)¶

موقعیت جریان را تنظیم می‌کند. موقعیت جدید جریان را به‌عنوان یک int برمی‌گرداند.

چهار عملیات پشتیبانی می‌شود که با ترکیب‌های آرگومان زیر مشخص می‌شوند:

seek(0, SEEK_SET): به ابتدای جریان بازمی‌گردد.
seek(cookie, SEEK_SET): بازگرداندن موقعیت قبلی؛ cookie باید عددی باشد که tell() آن را برمی‌گرداند.
seek(0, SEEK_END): پرش سریع به انتهای جریان.
seek(0, SEEK_CUR): موقعیت فعلی جریان را بدون تغییر باقی می‌گذارد.

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

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

os.SEEK_SET، os.SEEK_CUR و os.SEEK_END.

tell()¶: موقعیت جریان را به‌عنوان یک عدد غیرشفاف برمی‌گرداند. مقدار بازگشتی tell() می‌تواند به‌عنوان ورودی به seek() داده شود تا موقعیت قبلی جریان بازیابی شود.

class io.StringIO(initial_value='', newline='\n')¶

جریان متنی که از یک بافر متنی در حافظه استفاده می‌کند. این جریان از TextIOBase ارث می‌برد.

بافر متنی هنگام فراخوانی متد close() دور ریخته می‌شود.

مقدار اولیه‌ی بافر را می‌توان با ارائه‌ی initial_value تنظیم کرد. اگر ترجمه‌ی خط جدید فعال باشد، نویسه‌های خط جدید طوری کدگذاری می‌شوند که گویی توسط write() کدگذاری شده‌اند. جریان در ابتدای بافر قرار می‌گیرد؛ این حالت، باز کردن یک پرونده موجود در حالت w+ را شبیه‌سازی می‌کند و جریان را برای نوشتن فوری از ابتدا یا برای نوشتنی که مقدار اولیه را بازنویسی می‌کند، آماده می‌سازد. برای شبیه‌سازی باز کردن یک پرونده در حالت a+ که برای افزودن آماده است، از f.seek(0, io.SEEK_END) برای تغییر موقعیت جریان به انتهای بافر استفاده کنید.

آرگومان newline مانند آرگومان newline در TextIOWrapper عمل می‌کند، با این تفاوت که هنگام نوشتن خروجی در جریان، اگر newline برابر None باشد، سطرهای جدید به‌صورت \n در همه‌ی سکوها نوشته می‌شوند.

StringIO این متد را علاوه بر متدهای TextIOBase و IOBase ارائه می‌دهد:

getvalue()¶: یک str حاوی تمام محتوای بافر را برمی‌گرداند. کدگشایی سطرهای جدید گویی با read() انجام می‌شود، هرچند موقعیت جریان تغییر نمی‌کند.

نمونه استفاده:

import io

output = io.StringIO()
output.write('First line.\n')
print('Second line.', file=output)

# Retrieve file contents -- this will be
# 'First line.\nSecond line.\n'
contents = output.getvalue()

# Close object and discard memory buffer --
# .getvalue() will now raise an exception.
output.close()

class io.IncrementalNewlineDecoder¶: یک کدک کمکی که سطرهای جدید را برای حالت سطرهای جدید جهان‌شمول (universal newlines) کدگشایی می‌کند. این کدک از codecs.IncrementalDecoder ارث می‌برد.

نوع‌دهی ایستا¶

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

class io.Reader[T]¶

پروتکل عام برای خواندن از یک پرونده یا جریان ورودی دیگر. T معمولاً str یا bytes خواهد بود، اما می‌تواند هر نوعی باشد که از جریان خوانده می‌شود.

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

read()¶
read(size, /): داده را از جریان ورودی می‌خواند و آن را برمی‌گرداند. اگر size مشخص شده باشد، باید عدد صحیح باشد و حداکثر size آیتم (بایت/نویسه) خوانده می‌شود.

برای مثال:

def read_it(reader: Reader[str]):
    data = reader.read(11)
    assert isinstance(data, str)

class io.Writer[T]¶

پروتکل عام برای نوشتن در یک پرونده یا جریان خروجی دیگر. T معمولاً str یا bytes خواهد بود، اما می‌تواند هر نوعی باشد که بتوان آن را در جریان نوشت.

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

write(data, /)¶: data را در جریان خروجی می‌نویسد و تعداد آیتم‌های نوشته‌شده (بایت‌ها/نویسه‌ها) را برمی‌گرداند.

برای مثال:

def write_binary(writer: Writer[bytes]):
    writer.write(b"Hello world!\n")

برای سایر پروتکل‌ها و کلاس‌های مرتبط با I/O که می‌توانند برای بررسی ایستای نوع استفاده شوند، ABCها و پروتکل‌ها برای کار با I/O را ببینید.

کارایی¶

این بخش به بررسی کارایی پیاده‌سازی‌های عینی ورودی/خروجی (I/O) ارائه‌شده می‌پردازد.

ورودی/خروجی دودویی¶

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

ورودی/خروجی متنی¶

ورودی/خروجی متنی روی یک فضای ذخیره‌سازی دودویی (مانند پرونده) به‌مراتب کندتر از ورودی/خروجی دودویی روی همان فضای ذخیره‌سازی است، زیرا به تبدیل بین داده‌های یونیکد و دودویی با استفاده از یک کدک نویسه‌ای نیاز دارد. این موضوع می‌تواند هنگام کار با حجم زیادی از داده‌های متنی، مانند پرونده‌های گزارش بزرگ، محسوس شود. همچنین tell() و seek() هر دو به دلیل الگوریتم بازسازی به‌کاررفته کاملاً کند هستند.

با این حال، StringIO یک ظرف یونیکد بومی درون‌حافظه‌ای است و سرعتی مشابه BytesIO خواهد داشت.

چندنخی¶

اشیای FileIO تا حدی نخ‌ایمن هستند که فراخوانی‌های سیستم‌عاملی که این اشیاء پوشش می‌دهند (مانند read(2) در یونیکس) نیز نخ‌ایمن باشند.

اشیای دودویی بافرشده (نمونه‌های BufferedReader، BufferedWriter، BufferedRandom و BufferedRWPair) ساختارهای داخلی خود را با استفاده از یک قفل محافظت می‌کنند؛ بنابراین فراخوانی آن‌ها از چندین نخ به‌صورت همزمان ایمن است.

اشیای TextIOWrapper نخ‌ایمن نیستند.

بازورودپذیری (Reentrancy)¶

اشیای بافرشده‌ی دودویی (نمونه‌هایی از BufferedReader، BufferedWriter، BufferedRandom و BufferedRWPair) بازورودپذیر نیستند. اگرچه فراخوانی‌های بازورودپذیر در شرایط عادی رخ نمی‌دهند، اما ممکن است در اثر انجام I/O در یک هندلر سیگنال از signal پیش بیایند. اگر یک نخ تلاش کند به یک شیء بافرشده که هم‌اکنون در حال دسترسی به آن است دوباره وارد شود، یک RuntimeError پرتاب می‌شود. توجه داشته باشید که این موضوع یک نخ دیگر را از ورود به شیء بافرشده باز نمی‌دارد.

مورد بالا به‌طور ضمنی به پرونده‌های متنی نیز تعمیم می‌یابد، زیرا تابع open() یک شیء بافرشده را درون یک TextIOWrapper قرار می‌دهد. این موضوع شامل جریان‌های استاندارد نیز می‌شود و بنابراین تابع توکار print() را نیز تحت تأثیر قرار می‌دهد.

`io` --- ابزارهای اصلی برای کار با جریان‌ها¶

نمای کلی¶

ورودی/خروجی متنی¶

ورودی/خروجی دودویی¶

ورودی/خروجی خام¶

کدگذاری متن¶

فعال‌سازی اختیاری هشدار کدگذاری (EncodingWarning)¶

رابط سطح‌بالای ماژول¶

سلسله‌مراتب کلاس¶

کلاس‌های پایه‌ی I/O¶

ورودی/خروجی خام پرونده¶

جریان‌های بافرشده¶

ورودی/خروجی متنی¶

نوع‌دهی ایستا¶

کارایی¶

ورودی/خروجی دودویی¶

ورودی/خروجی متنی¶

چندنخی¶

بازورودپذیری (Reentrancy)¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه

io --- ابزارهای اصلی برای کار با جریان‌ها¶

نمای کلی¶

ورودی/خروجی متنی¶

ورودی/خروجی دودویی¶

ورودی/خروجی خام¶

کدگذاری متن¶

فعال‌سازی اختیاری هشدار کدگذاری (EncodingWarning)¶

رابط سطح‌بالای ماژول¶

سلسله‌مراتب کلاس¶

کلاس‌های پایه‌ی I/O¶

ورودی/خروجی خام پرونده¶

جریان‌های بافرشده¶

ورودی/خروجی متنی¶

نوع‌دهی ایستا¶

کارایی¶

ورودی/خروجی دودویی¶

ورودی/خروجی متنی¶

چندنخی¶

بازورودپذیری (Reentrancy)¶

`io` --- ابزارهای اصلی برای کار با جریان‌ها¶