ابزارهای کاربردی¶

توابع و کلاس‌های ارائه‌شده:

class contextlib.AbstractContextManager¶

یک کلاس پایه انتزاعی برای کلاس‌هایی که __enter__() و __exit__() را پیاده‌سازی می‌کنند. یک پیاده‌سازی پیش‌فرض برای __enter__() ارائه شده است که self را برمی‌گرداند، در حالی که __exit__() یک متد انتزاعی است که به‌طور پیش‌فرض None را برمی‌گرداند. همچنین تعریف انواع مدیر زمینه را نیز ببینید.

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

class contextlib.AbstractAsyncContextManager¶

یک کلاس پایه انتزاعی برای کلاس‌هایی که __aenter__() و __aexit__() را پیاده‌سازی می‌کنند. پیاده‌سازی پیش‌فرضی برای __aenter__() فراهم شده است که self را برمی‌گرداند، در حالی که __aexit__() یک متد انتزاعی است که به‌طور پیش‌فرض None را برمی‌گرداند. همچنین تعریف مدیرهای زمینه ناهمگام را ببینید.

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

@contextlib.contextmanager¶

این تابع یک دکوراتور است که می‌توان از آن برای تعریف یک تابع کارخانه‌ای برای مدیران زمینه‌ی دستور with استفاده کرد، بدون نیاز به ایجاد یک کلاس یا متدهای جداگانه‌ی __enter__() و __exit__().

در حالی که بسیاری از شیء‌ها به‌صورت ذاتی از استفاده در دستورهای with پشتیبانی می‌کنند، گاهی نیاز است منبعی مدیریت شود که به‌خودی‌خود مدیر زمینه نیست و متد close() را برای استفاده با contextlib.closing پیاده‌سازی نمی‌کند.

برای اطمینان از مدیریت صحیح منابع، یک مثال انتزاعی به‌صورت زیر خواهد بود:

from contextlib import contextmanager

@contextmanager
def managed_resource(*args, **kwds):
    # Code to acquire resource, e.g.:
    resource = acquire_resource(*args, **kwds)
    try:
        yield resource
    finally:
        # Code to release resource, e.g.:
        release_resource(resource)

سپس می‌توان از تابع به این صورت استفاده کرد:

>>> with managed_resource(timeout=3600) as resource:
...     # Resource is released at the end of this block,
...     # even if code in the block raises an exception

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

در نقطه‌ای که تولیدگر yield می‌کند، بلوک نهفته در دستور with اجرا می‌شود. سپس پس از خروج از بلوک، تولیدگر از سر گرفته می‌شود. اگر یک استثنای مدیریت‌نشده در بلوک رخ دهد، در نقطه‌ای که yield رخ داده است، درون تولیدگر دوباره پرتاب می‌شود. بنابراین، می‌توانید از یک دستور try...except...finally برای رهگیری خطا (در صورت وجود) یا اطمینان از انجام برخی پاک‌سازی‌ها استفاده کنید. اگر یک استثنا صرفاً برای ثبت آن یا انجام عملی (نه برای سرکوب کامل آن) گرفته شود، تولیدگر باید آن استثنا را دوباره پرتاب کند. در غیر این صورت، مدیر زمینه‌ی تولیدگر به دستور with اطلاع می‌دهد که استثنا مدیریت شده است، و اجرا با دستور بلافاصله پس از دستور with از سر گرفته می‌شود.

@contextmanager از ContextDecorator استفاده می‌کند، بنابراین مدیرهای زمینه‌ای که ایجاد می‌کند می‌توانند هم به‌عنوان دکوراتور و هم در دستورهای with استفاده شوند. هنگام استفاده به‌عنوان دکوراتور، در هر فراخوانی تابع، یک نمونه‌ی جدید از تولیدگر به‌طور ضمنی ایجاد می‌شود (این امر به مدیرهای زمینه‌ای که توسط @contextmanager ایجاد می‌شوند و در غیر این صورت «یک‌بارمصرف» هستند، اجازه می‌دهد الزام پشتیبانی از چندین فراخوانی برای استفاده به‌عنوان دکوراتور را برآورده کنند).

تغییر یافته در نسخه‌ی 3.2: استفاده از ContextDecorator.

@contextlib.asynccontextmanager¶

مشابه @contextmanager، اما یک مدیر زمینه ناهمگام ایجاد می‌کند.

این تابع یک دکوراتور است که می‌توان از آن برای تعریف یک تابع کارخانه‌ای برای مدیران زمینه ناهمگام دستور async with استفاده کرد، بدون نیاز به ایجاد یک کلاس یا متدهای جداگانه‌ی __aenter__() و __aexit__(). این دکوراتور باید به یک تابع تولیدگر ناهمگام اعمال شود.

یک مثال ساده:

from contextlib import asynccontextmanager

@asynccontextmanager
async def get_connection():
    conn = await acquire_db_connection()
    try:
        yield conn
    finally:
        await release_db_connection(conn)

async def get_all_users():
    async with get_connection() as conn:
        return conn.query('SELECT ...')

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

مدیران زمینه تعریف‌شده با @asynccontextmanager را می‌توان هم به‌عنوان دکوراتور و هم با دستورهای async with استفاده کرد:

import time
from contextlib import asynccontextmanager

@asynccontextmanager
async def timeit():
    now = time.monotonic()
    try:
        yield
    finally:
        print(f'it took {time.monotonic() - now}s to run')

@timeit()
async def main():
    # ... async code ...

هنگام استفاده به‌عنوان دکوراتور، در هر فراخوانی تابع، یک نمونه تولیدگر جدید به‌طور ضمنی ایجاد می‌شود. این امر به مدیرهای زمینه ایجادشده توسط @asynccontextmanager، که در غیر این صورت «یک‌بارمصرف» هستند، اجازه می‌دهد الزامی را برآورده کنند که طبق آن مدیرهای زمینه باید برای استفاده به‌عنوان دکوراتور از فراخوانی‌های متعدد پشتیبانی کنند.

تغییر یافته در نسخه‌ی 3.10: مدیرهای زمینه ناهمگام ایجادشده با @asynccontextmanager را می‌توان به‌عنوان دکوراتور استفاده کرد.

contextlib.closing(thing)¶

یک مدیر زمینه برمی‌گرداند که thing را پس از تکمیل بلوک می‌بندد. این اساساً معادل است با:

from contextlib import contextmanager

@contextmanager
def closing(thing):
    try:
        yield thing
    finally:
        thing.close()

و به شما امکان می‌دهد کدی مانند این بنویسید:

from contextlib import closing
from urllib.request import urlopen

with closing(urlopen('https://www.python.org')) as page:
    for line in page:
        print(line)

بدون نیاز به بستن page به‌صراحت. حتی اگر خطایی رخ دهد، هنگام خروج از بلوک with، page.close() فراخوانی خواهد شد.

نکته

بیشتر انواعی که منابع را مدیریت می‌کنند، از پروتکل مدیر زمینه پشتیبانی می‌کنند، که شیء را در هنگام خروج از دستور with می‌بندد. از این رو، closing() برای انواع شخص ثالثی که از مدیران زمینه پشتیبانی نمی‌کنند، بیشترین کاربرد را دارد. این مثال صرفاً برای اهداف نمایشی است، زیرا urlopen() به‌طور معمول در یک مدیر زمینه استفاده می‌شود.

contextlib.aclosing(thing)¶

یک مدیر زمینه ناهمگام برمی‌گرداند که پس از تکمیل بلوک، متد aclose() متعلق به thing را فراخوانی می‌کند. این اساساً معادل است با:

from contextlib import asynccontextmanager

@asynccontextmanager
async def aclosing(thing):
    try:
        yield thing
    finally:
        await thing.aclose()

به‌طور قابل‌توجهی، aclosing() از پاک‌سازی قطعی تولیدگرهای ناهمگام در صورتی که به‌واسطه‌ی break یا یک استثنا زودتر خارج شوند، پشتیبانی می‌کند. برای مثال:

from contextlib import aclosing

async with aclosing(my_generator()) as values:
    async for value in values:
        if value == 42:
            break

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

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

contextlib.nullcontext(enter_result=None)¶

یک مدیر زمینه برمی‌گرداند که enter_result را از __enter__() برمی‌گرداند، اما در غیر این صورت هیچ کاری انجام نمی‌دهد. این برای استفاده به‌عنوان جایگزینی برای یک مدیر زمینه اختیاری در نظر گرفته شده است، برای مثال:

def myfunction(arg, ignore_exceptions=False):
    if ignore_exceptions:
        # Use suppress to ignore all exceptions.
        cm = contextlib.suppress(Exception)
    else:
        # Do not ignore any exceptions, cm has no effect.
        cm = contextlib.nullcontext()
    with cm:
        # Do something

مثالی با استفاده از enter_result:

def process_file(file_or_path):
    if isinstance(file_or_path, str):
        # If string, open file
        cm = open(file_or_path)
    else:
        # Caller is responsible for closing file
        cm = nullcontext(file_or_path)

    with cm as file:
        # Perform processing on the file

همچنین می‌تواند به‌عنوان جایگزینی برای مدیران زمینه ناهمگام استفاده شود:

async def send_http(session=None):
    if not session:
        # If no http session, create it with aiohttp
        cm = aiohttp.ClientSession()
    else:
        # Caller is responsible for closing the session
        cm = nullcontext(session)

    async with cm as session:
        # Send http requests with session

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

تغییر یافته در نسخه‌ی 3.10: پشتیبانی از asynchronous context manager افزوده شد.

contextlib.suppress(*exceptions)¶

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

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

برای مثال:

from contextlib import suppress

with suppress(FileNotFoundError):
    os.remove('somefile.tmp')

with suppress(FileNotFoundError):
    os.remove('someotherfile.tmp')

این کد معادل است با:

try:
    os.remove('somefile.tmp')
except FileNotFoundError:
    pass

try:
    os.remove('someotherfile.tmp')
except FileNotFoundError:
    pass

این مدیر زمینه بازورودپذیر است.

اگر کد درون بلوک with یک BaseExceptionGroup را پرتاب کند، استثناهای مهارشده از گروه حذف می‌شوند. هر یک از استثناهای گروه که مهارنشده باشند، در گروه جدیدی که با استفاده از متد derive() گروه اصلی ایجاد شده است، دوباره پرتاب می‌شوند.

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

تغییر یافته در نسخه‌ی 3.12: suppress اکنون از مهار استثناهایی که به‌عنوان بخشی از یک BaseExceptionGroup پرتاب می‌شوند، پشتیبانی می‌کند.

contextlib.redirect_stdout(new_target)¶

مدیر زمینه برای هدایت موقت sys.stdout به یک شیء پرونده دیگر.

این ابزار انعطاف‌پذیری را به توابع یا کلاس‌های موجودی اضافه می‌کند که خروجی آن‌ها به sys.stdout وصل شده است.

برای مثال، خروجی help() به‌طور معمول به sys.stdout فرستاده می‌شود. شما می‌توانید با هدایت خروجی به یک شیء io.StringIO، آن خروجی را در یک رشته ذخیره کنید. جریان جایگزین از متد __enter__() بازگردانده می‌شود و بنابراین به‌عنوان هدف دستور with در دسترس است:

with redirect_stdout(io.StringIO()) as f:
    help(pow)
s = f.getvalue()

برای ارسال خروجی help() به یک پرونده روی دیسک، خروجی را به یک پرونده معمولی تغییر مسیر دهید:

with open('help.txt', 'w') as f:
    with redirect_stdout(f):
        help(pow)

برای ارسال خروجی help() به sys.stderr:

with redirect_stdout(sys.stderr):
    help(pow)

توجه داشته باشید که اثر جانبی سراسری بر sys.stdout به این معناست که این مدیر زمینه برای استفاده در کد کتابخانه‌ای و بیشتر برنامه‌های نخی مناسب نیست. همچنین بر خروجی زیرفرایندها اثری ندارد. با این حال، هنوز هم رویکردی مفید برای بسیاری از اسکریپت‌های کاربردی است.

این مدیر زمینه بازورودپذیر است.

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

contextlib.redirect_stderr(new_target)¶

مشابه redirect_stdout() اما با هدایت sys.stderr سراسری به یک شیء پرونده دیگر.

این مدیر زمینه بازورودپذیر است.

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

contextlib.chdir(path)¶

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

این پوششی ساده بر روی chdir() است که هنگام ورود، پوشه کاری جاری را تغییر می‌دهد و هنگام خروج، پوشه پیشین را بازمی‌گرداند.

این مدیر زمینه بازورودپذیر است.

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

class contextlib.ContextDecorator¶

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

مدیران زمینه‌ای که از ContextDecorator ارث‌بری می‌کنند باید __enter__() و __exit__() را به‌صورت عادی پیاده‌سازی کنند. __exit__ مدیریت اختیاری استثنا را حتی هنگام استفاده به‌عنوان دکوراتور حفظ می‌کند.

@contextmanager از ContextDecorator استفاده می‌کند، بنابراین این قابلیت به‌صورت خودکار در دسترس شما قرار می‌گیرد.

مثالی از ContextDecorator:

from contextlib import ContextDecorator

class mycontext(ContextDecorator):
    def __enter__(self):
        print('Starting')
        return self

    def __exit__(self, *exc):
        print('Finishing')
        return False

سپس می‌توان از کلاس به این صورت استفاده کرد:

>>> @mycontext()
... def function():
...     print('The bit in the middle')
...
>>> function()
Starting
The bit in the middle
Finishing

>>> with mycontext():
...     print('The bit in the middle')
...
Starting
The bit in the middle
Finishing

این تغییر صرفاً قند نحوی برای هر ساختاری با شکل زیر است:

def f():
    with cm():
        # Do stuff

ContextDecorator به شما اجازه می‌دهد در عوض بنویسید:

@cm()
def f():
    # Do stuff

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

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

from contextlib import ContextDecorator

class mycontext(ContextBaseClass, ContextDecorator):
    def __enter__(self):
        return self

    def __exit__(self, *exc):
        return False

نکته

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

هنگامی که شیء فراخوانی‌پذیرِ تزئین‌شده یک تابع تولیدگر، تابع هم‌روال یا تابع تولیدگر ناهمگام باشد، پوششِ بازگردانده‌شده از همان نوع است و مدیر زمینه را برای طول عمر پیمایش یا await باز نگه می‌دارد، نه فقط برای فراخوانی‌ای که شیء تولیدگر یا هم‌روال را ایجاد می‌کند. تولیدگرهای پوشش‌داده‌شده و تولیدگرهای ناهمگام، هنگامی که پیمایش به پایان می‌رسد، به‌طور صریح بسته می‌شوند، درست مانند زمانی که توسط closing() یا aclosing() بسته می‌شوند.

نکته

برای تولیدگرهای ناهمگام، پوشش هر مقدار را با async for دوباره تولید (yield) می‌کند؛ مقادیر ارسال‌شده با asend() و استثناهای پرتاب‌شده با athrow() به تولیدگر پوشش‌داده‌شده فوروارد نمی‌شوند.

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

تغییر یافته در نسخه‌ی 3.15: تزئین کردن یک تابع تولیدگر، تابع هم‌روال یا تابع تولیدگر ناهمگام اکنون باعث می‌شود مدیر زمینه در طول پیمایش یا await باز بماند. پیش‌تر، مدیر زمینه به‌محض ایجاد شدن شیء تولیدگر یا هم‌روال خارج می‌شد.

class contextlib.AsyncContextDecorator¶

مشابه ContextDecorator، اما ورود و خروج از مدیر زمینه با async with انجام می‌شود. توابع هم‌روال و توابع تولیدگر ناهمگام را با این کلاس تزئین کنید؛ پوششِ بازگردانده‌شده از همان نوع است.

نکته

توابع همگام و تولیدگرها پذیرفته می‌شوند، اما پوشش همیشه ناهمگام است، بنابراین شیء فراخوانی‌پذیرِ تزئین‌شده باید با async for منتظر بماند (await شود) یا پیمایش شود. اگر آن تغییر در قرارداد فراخوانی مورد نظر نیست، به جای آن از ContextDecorator استفاده کنید.

مثالی از AsyncContextDecorator:

from asyncio import run
from contextlib import AsyncContextDecorator

class mycontext(AsyncContextDecorator):
    async def __aenter__(self):
        print('Starting')
        return self

    async def __aexit__(self, *exc):
        print('Finishing')
        return False

سپس می‌توان از کلاس به این صورت استفاده کرد:

>>> @mycontext()
... async def function():
...     print('The bit in the middle')
...
>>> run(function())
Starting
The bit in the middle
Finishing

>>> async def function():
...    async with mycontext():
...         print('The bit in the middle')
...
>>> run(function())
Starting
The bit in the middle
Finishing

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

تغییر یافته در نسخه‌ی 3.15: تزئین کردن یک تابع تولیدگر ناهمگام اکنون باعث می‌شود مدیر زمینه در طول پیمایش باز بماند. پیش‌تر، مدیر زمینه به‌محض ایجاد شدن شیء تولیدگر خارج می‌شد. توابع همگام و توابع تولیدگر همگام نیز اکنون پذیرفته می‌شوند و یک پوشش ناهمگام بازگردانده می‌شود.

class contextlib.ExitStack¶

یک مدیر زمینه که طراحی شده است تا ترکیب سایر مدیرهای زمینه و توابع پاک‌سازی را به‌صورت برنامه‌ای آسان کند، به‌ویژه آن‌هایی که اختیاری هستند یا به‌نحوی دیگر توسط داده‌های ورودی هدایت می‌شوند.

برای مثال، مجموعه‌ای از پرونده‌ها را می‌توان به‌راحتی در یک دستور with واحد به‌صورت زیر مدیریت کرد:

with ExitStack() as stack:
    files = [stack.enter_context(open(fname)) for fname in filenames]
    # All opened files will automatically be closed at the end of
    # the with statement, even if attempts to open files later
    # in the list raise an exception

متد __enter__() نمونه ExitStack را برمی‌گرداند و هیچ عملیات اضافی انجام نمی‌دهد.

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

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

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

این یک API نسبتاً سطح پایین است که جزئیات باز کردن صحیح پشته‌ی کال‌بک‌های خروج را مدیریت می‌کند. این API پایه‌ای مناسب برای مدیرهای زمینه سطح بالاتر فراهم می‌کند که پشته‌ی خروج را به روش‌های مختص برنامه دستکاری می‌کنند.

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

enter_context(cm)¶

وارد یک مدیر زمینه جدید می‌شود و متد __exit__() آن را به پشته‌ی کال‌بک اضافه می‌کند. مقدار بازگشتی، نتیجه‌ی متد __enter__() خود مدیر زمینه است.

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

تغییر یافته در نسخه‌ی 3.11: اگر cm یک مدیر زمینه نباشد، به‌جای AttributeError، TypeError پرتاب می‌شود.

تغییر یافته در نسخه‌ی 3.15: پشتیبانی از توصیف‌گرهای دلخواه __enter__() و __exit__() اضافه شد.

push(exit)¶

متد __exit__()مدیر زمینه را به پشته‌ی کال‌بک اضافه می‌کند.

از آنجا که __enter__ فراخوانی نمی‌شود، می‌توان از این متد برای پوشش دادن بخشی از پیاده‌سازی __enter__() با متد __exit__() خودِ مدیر زمینه استفاده کرد.

اگر شیءای که مدیریتگر زمینه نیست به این متد داده شود، این متد فرض می‌کند که آن شیء یک کال‌بک با همان امضای متد __exit__() مدیریتگر زمینه است و آن را مستقیماً به پشته کال‌بک اضافه می‌کند.

این کال‌بک‌ها می‌توانند با برگرداندن مقادیر درست، استثناها را دقیقاً مانند متدهای __exit__() مدیر زمینه مهار کنند.

شیء داده‌شده از تابع بازگردانده می‌شود و امکان استفاده از این متد به‌عنوان دکوراتور تابع را فراهم می‌کند.

تغییر یافته در نسخه‌ی 3.15: پشتیبانی از توصیف‌گرهای دلخواه __exit__() اضافه شد.

callback(callback, /, *args, **kwds)¶

یک تابع کال‌بک دلخواه و آرگومان‌ها را می‌پذیرد و آن را به پشته کال‌بک اضافه می‌کند.

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

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

pop_all()¶

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

برای مثال، می‌توان گروهی از پرونده‌ها را به‌عنوان یک عملیات «همه یا هیچ» به‌صورت زیر باز کرد:

with ExitStack() as stack:
    files = [stack.enter_context(open(fname)) for fname in filenames]
    # Hold onto the close method, but don't call it yet.
    close_files = stack.pop_all().close
    # If opening any file fails, all previously opened files will be
    # closed automatically. If all files are opened successfully,
    # they will remain open even after the with statement ends.
    # close_files() can then be invoked explicitly to close them all.

close()¶

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

class contextlib.AsyncExitStack¶

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

متد close() پیاده‌سازی نشده است؛ باید به‌جای آن از aclose() استفاده شود.

async enter_async_context(cm)¶

مشابه ExitStack.enter_context() است، اما انتظار یک مدیر زمینه ناهمگام را دارد.

تغییر یافته در نسخه‌ی 3.11: اگر cm یک مدیر زمینه‌ی ناهمگام نباشد، به‌جای AttributeError، TypeError را پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.15: پشتیبانی از توصیف‌گرهای دلخواه __aenter__() و __aexit__() اضافه شد.

push_async_exit(exit)¶

مشابه ExitStack.push() است، اما انتظار دارد که یا یک مدیر زمینه ناهمگام باشد یا یک تابع هم‌روال.

تغییر یافته در نسخه‌ی 3.15: پشتیبانی از توصیف‌گرهای دلخواه __aexit__() اضافه شد.

push_async_callback(callback, /, *args, **kwds)¶

مشابه ExitStack.callback() است، اما یک تابع هم‌روال انتظار می‌رود.

async aclose()¶

مشابه ExitStack.close() است، اما awaitableها را به‌درستی مدیریت می‌کند.

در ادامه‌ی مثال برای @asynccontextmanager:

async with AsyncExitStack() as stack:
    connections = [await stack.enter_async_context(get_connection())
        for i in range(5)]
    # All opened connections will automatically be released at the end of
    # the async with statement, even if attempts to open a connection
    # later in the list raise an exception.

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

مثال‌ها و دستور پخت‌ها¶

این بخش چند مثال و راهکار را برای استفاده‌ی مؤثر از ابزارهای فراهم‌شده توسط contextlib شرح می‌دهد.

with ExitStack() as stack:
    for resource in resources:
        stack.enter_context(resource)
    if need_special_resource():
        special = acquire_special_resource()
        stack.callback(release_special_resource, special)
    # Perform operations that use the acquired resources

stack = ExitStack()
try:
    x = stack.enter_context(cm)
except Exception:
    # handle __enter__ exception
else:
    with stack:
        # Handle normal case

from contextlib import contextmanager, AbstractContextManager, ExitStack

class ResourceManager(AbstractContextManager):

    def __init__(self, acquire_resource, release_resource, check_resource_ok=None):
        self.acquire_resource = acquire_resource
        self.release_resource = release_resource
        if check_resource_ok is None:
            def check_resource_ok(resource):
                return True
        self.check_resource_ok = check_resource_ok

    @contextmanager
    def _cleanup_on_error(self):
        with ExitStack() as stack:
            stack.push(self)
            yield
            # The validation check passed and didn't raise an exception
            # Accordingly, we want to keep the resource, and pass it
            # back to our caller
            stack.pop_all()

    def __enter__(self):
        resource = self.acquire_resource()
        with self._cleanup_on_error():
            if not self.check_resource_ok(resource):
                msg = "Failed validation for {!r}"
                raise RuntimeError(msg.format(resource))
        return resource

    def __exit__(self, *exc_details):
        # We don't need to duplicate any of our resource release logic
        self.release_resource()

cleanup_needed = True
try:
    result = perform_operation()
    if result:
        cleanup_needed = False
finally:
    if cleanup_needed:
        cleanup_resources()

from contextlib import ExitStack

with ExitStack() as stack:
    stack.callback(cleanup_resources)
    result = perform_operation()
    if result:
        stack.pop_all()

from contextlib import ExitStack

class Callback(ExitStack):
    def __init__(self, callback, /, *args, **kwds):
        super().__init__()
        self.callback(callback, *args, **kwds)

    def cancel(self):
        self.pop_all()

with Callback(cleanup_resources) as cb:
    result = perform_operation()
    if result:
        cb.cancel()

from contextlib import ExitStack

with ExitStack() as stack:
    @stack.callback
    def cleanup_resources():
        ...
    result = perform_operation()
    if result:
        stack.pop_all()

from contextlib import ContextDecorator
import logging

logging.basicConfig(level=logging.INFO)

class track_entry_and_exit(ContextDecorator):
    def __init__(self, name):
        self.name = name

    def __enter__(self):
        logging.info('Entering: %s', self.name)

    def __exit__(self, exc_type, exc, exc_tb):
        logging.info('Exiting: %s', self.name)

with track_entry_and_exit('widget loader'):
    print('Some time consuming activity goes here')
    load_widget()

@track_entry_and_exit('widget loader')
def activity():
    print('Some time consuming activity goes here')
    load_widget()

مدیران زمینه‌ی یک‌بارمصرف، بازاستفاده‌پذیر و بازورودپذیر¶

بیشتر مدیرهای زمینه به‌گونه‌ای نوشته شده‌اند که فقط یک بار می‌توان به‌طور مؤثر در یک دستور with از آن‌ها استفاده کرد. این مدیرهای زمینه‌ی یک‌بارمصرف باید هر بار که استفاده می‌شوند، از نو ایجاد شوند؛ تلاش برای استفاده از آن‌ها برای بار دوم باعث پرتاب یک استثنا می‌شود یا در غیر این صورت به‌درستی کار نخواهد کرد.

این محدودیت رایج به این معناست که معمولاً توصیه می‌شود مدیرهای زمینه را مستقیماً در سرآیند دستور with در محل استفاده ایجاد کنید (همان‌طور که در تمام مثال‌های استفاده بالا نشان داده شده است).

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

مدیرهای زمینه‌ای که با استفاده از @contextmanager ایجاد می‌شوند نیز مدیرهای زمینه یک‌بارمصرف هستند و اگر تلاش شود برای بار دوم از آن‌ها استفاده شود، از yield نکردن تولیدگر زیربنایی شکایت خواهند کرد:

>>> from contextlib import contextmanager
>>> @contextmanager
... def singleuse():
...     print("Before")
...     yield
...     print("After")
...
>>> cm = singleuse()
>>> with cm:
...     pass
...
Before
After
>>> with cm:
...     pass
...
Traceback (most recent call last):
    ...
RuntimeError: generator didn't yield

>>> from contextlib import redirect_stdout
>>> from io import StringIO
>>> stream = StringIO()
>>> write_to_stream = redirect_stdout(stream)
>>> with write_to_stream:
...     print("This is written to the stream rather than stdout")
...     with write_to_stream:
...         print("This is also written to the stream")
...
>>> print("This is written directly to stdout")
This is written directly to stdout
>>> print(stream.getvalue())
This is written to the stream rather than stdout
This is also written to the stream

>>> from contextlib import ExitStack
>>> stack = ExitStack()
>>> with stack:
...     stack.callback(print, "Callback: from first context")
...     print("Leaving first context")
...
Leaving first context
Callback: from first context
>>> with stack:
...     stack.callback(print, "Callback: from second context")
...     print("Leaving second context")
...
Leaving second context
Callback: from second context
>>> with stack:
...     stack.callback(print, "Callback: from outer context")
...     with stack:
...         stack.callback(print, "Callback: from inner context")
...         print("Leaving inner context")
...     print("Leaving outer context")
...
Leaving inner context
Callback: from inner context
Callback: from outer context
Leaving outer context

>>> from contextlib import ExitStack
>>> with ExitStack() as outer_stack:
...     outer_stack.callback(print, "Callback: from outer context")
...     with ExitStack() as inner_stack:
...         inner_stack.callback(print, "Callback: from inner context")
...         print("Leaving inner context")
...     print("Leaving outer context")
...
Leaving inner context
Callback: from inner context
Leaving outer context
Callback: from outer context