# Copyright (C) 2001-2018, Python Software Foundation # For licence information, see README file. # msgid "" msgstr "" "Project-Id-Version: Python 3.6\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2018-06-28 15:29+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: FRENCH \n" "Language: fr\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: ../Doc/library/contextlib.rst:2 msgid "" ":mod:`contextlib` --- Utilities for :keyword:`with`\\ -statement contexts" msgstr "" #: ../Doc/library/contextlib.rst:7 msgid "**Source code:** :source:`Lib/contextlib.py`" msgstr "**Code source :** :source:`Lib/contextlib.py`" #: ../Doc/library/contextlib.rst:11 msgid "" "This module provides utilities for common tasks involving the :keyword:" "`with` statement. For more information see also :ref:`typecontextmanager` " "and :ref:`context-managers`." msgstr "" #: ../Doc/library/contextlib.rst:17 msgid "Utilities" msgstr "Utilitaires" #: ../Doc/library/contextlib.rst:19 msgid "Functions and classes provided:" msgstr "" #: ../Doc/library/contextlib.rst:23 msgid "" "An :term:`abstract base class` for classes that implement :meth:`object." "__enter__` and :meth:`object.__exit__`. A default implementation for :meth:" "`object.__enter__` is provided which returns ``self`` while :meth:`object." "__exit__` is an abstract method which by default returns ``None``. See also " "the definition of :ref:`typecontextmanager`." msgstr "" #: ../Doc/library/contextlib.rst:34 msgid "" "An :term:`abstract base class` for classes that implement :meth:`object." "__aenter__` and :meth:`object.__aexit__`. A default implementation for :meth:" "`object.__aenter__` is provided which returns ``self`` while :meth:`object." "__aexit__` is an abstract method which by default returns ``None``. See also " "the definition of :ref:`async-context-managers`." msgstr "" #: ../Doc/library/contextlib.rst:46 msgid "" "This function is a :term:`decorator` that can be used to define a factory " "function for :keyword:`with` statement context managers, without needing to " "create a class or separate :meth:`__enter__` and :meth:`__exit__` methods." msgstr "" #: ../Doc/library/contextlib.rst:50 msgid "" "A simple example (this is not recommended as a real way of generating " "HTML!)::" msgstr "" #: ../Doc/library/contextlib.rst:67 msgid "" "The function being decorated must return a :term:`generator`-iterator when " "called. This iterator must yield exactly one value, which will be bound to " "the targets in the :keyword:`with` statement's :keyword:`as` clause, if any." msgstr "" #: ../Doc/library/contextlib.rst:71 msgid "" "At the point where the generator yields, the block nested in the :keyword:" "`with` statement is executed. The generator is then resumed after the block " "is exited. If an unhandled exception occurs in the block, it is reraised " "inside the generator at the point where the yield occurred. Thus, you can " "use a :keyword:`try`...\\ :keyword:`except`...\\ :keyword:`finally` " "statement to trap the error (if any), or ensure that some cleanup takes " "place. If an exception is trapped merely in order to log it or to perform " "some action (rather than to suppress it entirely), the generator must " "reraise that exception. Otherwise the generator context manager will " "indicate to the :keyword:`with` statement that the exception has been " "handled, and execution will resume with the statement immediately following " "the :keyword:`with` statement." msgstr "" #: ../Doc/library/contextlib.rst:83 msgid "" ":func:`contextmanager` uses :class:`ContextDecorator` so the context " "managers it creates can be used as decorators as well as in :keyword:`with` " "statements. When used as a decorator, a new generator instance is implicitly " "created on each function call (this allows the otherwise \"one-shot\" " "context managers created by :func:`contextmanager` to meet the requirement " "that context managers support multiple invocations in order to be used as " "decorators)." msgstr "" #: ../Doc/library/contextlib.rst:90 msgid "Use of :class:`ContextDecorator`." msgstr "" #: ../Doc/library/contextlib.rst:96 msgid "" "Similar to :func:`~contextlib.contextmanager`, but creates an :ref:" "`asynchronous context manager `." msgstr "" #: ../Doc/library/contextlib.rst:99 msgid "" "This function is a :term:`decorator` that can be used to define a factory " "function for :keyword:`async with` statement asynchronous context managers, " "without needing to create a class or separate :meth:`__aenter__` and :meth:" "`__aexit__` methods. It must be applied to an :term:`asynchronous generator` " "function." msgstr "" #: ../Doc/library/contextlib.rst:105 #, fuzzy msgid "A simple example::" msgstr "Par exemple ::" #: ../Doc/library/contextlib.rst:126 msgid "" "Return a context manager that closes *thing* upon completion of the block. " "This is basically equivalent to::" msgstr "" #: ../Doc/library/contextlib.rst:138 msgid "And lets you write code like this::" msgstr "" #: ../Doc/library/contextlib.rst:147 msgid "" "without needing to explicitly close ``page``. Even if an error occurs, " "``page.close()`` will be called when the :keyword:`with` block is exited." msgstr "" #: ../Doc/library/contextlib.rst:155 msgid "" "Return a context manager that returns enter_result from ``__enter__``, but " "otherwise does nothing. It is intended to be used as a stand-in for an " "optional context manager, for example::" msgstr "" #: ../Doc/library/contextlib.rst:175 msgid "" "Return a context manager that suppresses any of the specified exceptions if " "they occur in the body of a with statement and then resumes execution with " "the first statement following the end of the with statement." msgstr "" #: ../Doc/library/contextlib.rst:179 msgid "" "As with any other mechanism that completely suppresses exceptions, this " "context manager should be used only to cover very specific errors where " "silently continuing with program execution is known to be the right thing to " "do." msgstr "" #: ../Doc/library/contextlib.rst:184 msgid "For example::" msgstr "Par exemple ::" #: ../Doc/library/contextlib.rst:194 msgid "This code is equivalent to::" msgstr "Ce code est équivalent à ::" #: ../Doc/library/contextlib.rst:206 ../Doc/library/contextlib.rst:245 #: ../Doc/library/contextlib.rst:255 msgid "This context manager is :ref:`reentrant `." msgstr "" #: ../Doc/library/contextlib.rst:213 msgid "" "Context manager for temporarily redirecting :data:`sys.stdout` to another " "file or file-like object." msgstr "" #: ../Doc/library/contextlib.rst:216 msgid "" "This tool adds flexibility to existing functions or classes whose output is " "hardwired to stdout." msgstr "" #: ../Doc/library/contextlib.rst:219 msgid "" "For example, the output of :func:`help` normally is sent to *sys.stdout*. " "You can capture that output in a string by redirecting the output to an :" "class:`io.StringIO` object::" msgstr "" #: ../Doc/library/contextlib.rst:228 msgid "" "To send the output of :func:`help` to a file on disk, redirect the output to " "a regular file::" msgstr "" #: ../Doc/library/contextlib.rst:235 msgid "To send the output of :func:`help` to *sys.stderr*::" msgstr "" #: ../Doc/library/contextlib.rst:240 msgid "" "Note that the global side effect on :data:`sys.stdout` means that this " "context manager is not suitable for use in library code and most threaded " "applications. It also has no effect on the output of subprocesses. However, " "it is still a useful approach for many utility scripts." msgstr "" #: ../Doc/library/contextlib.rst:252 msgid "" "Similar to :func:`~contextlib.redirect_stdout` but redirecting :data:`sys." "stderr` to another file or file-like object." msgstr "" #: ../Doc/library/contextlib.rst:262 msgid "" "A base class that enables a context manager to also be used as a decorator." msgstr "" #: ../Doc/library/contextlib.rst:264 msgid "" "Context managers inheriting from ``ContextDecorator`` have to implement " "``__enter__`` and ``__exit__`` as normal. ``__exit__`` retains its optional " "exception handling even when used as a decorator." msgstr "" #: ../Doc/library/contextlib.rst:268 msgid "" "``ContextDecorator`` is used by :func:`contextmanager`, so you get this " "functionality automatically." msgstr "" #: ../Doc/library/contextlib.rst:271 msgid "Example of ``ContextDecorator``::" msgstr "" #: ../Doc/library/contextlib.rst:300 msgid "" "This change is just syntactic sugar for any construct of the following form::" msgstr "" #: ../Doc/library/contextlib.rst:306 msgid "``ContextDecorator`` lets you instead write::" msgstr "" #: ../Doc/library/contextlib.rst:312 msgid "" "It makes it clear that the ``cm`` applies to the whole function, rather than " "just a piece of it (and saving an indentation level is nice, too)." msgstr "" #: ../Doc/library/contextlib.rst:315 msgid "" "Existing context managers that already have a base class can be extended by " "using ``ContextDecorator`` as a mixin class::" msgstr "" #: ../Doc/library/contextlib.rst:328 msgid "" "As the decorated function must be able to be called multiple times, the " "underlying context manager must support use in multiple :keyword:`with` " "statements. If this is not the case, then the original construct with the " "explicit :keyword:`with` statement inside the function should be used." msgstr "" #: ../Doc/library/contextlib.rst:338 msgid "" "A context manager that is designed to make it easy to programmatically " "combine other context managers and cleanup functions, especially those that " "are optional or otherwise driven by input data." msgstr "" #: ../Doc/library/contextlib.rst:342 msgid "" "For example, a set of files may easily be handled in a single with statement " "as follows::" msgstr "" #: ../Doc/library/contextlib.rst:351 msgid "" "Each instance maintains a stack of registered callbacks that are called in " "reverse order when the instance is closed (either explicitly or implicitly " "at the end of a :keyword:`with` statement). Note that callbacks are *not* " "invoked implicitly when the context stack instance is garbage collected." msgstr "" #: ../Doc/library/contextlib.rst:356 msgid "" "This stack model is used so that context managers that acquire their " "resources in their ``__init__`` method (such as file objects) can be handled " "correctly." msgstr "" #: ../Doc/library/contextlib.rst:360 msgid "" "Since registered callbacks are invoked in the reverse order of registration, " "this ends up behaving as if multiple nested :keyword:`with` statements had " "been used with the registered set of callbacks. This even extends to " "exception handling - if an inner callback suppresses or replaces an " "exception, then outer callbacks will be passed arguments based on that " "updated state." msgstr "" #: ../Doc/library/contextlib.rst:367 msgid "" "This is a relatively low level API that takes care of the details of " "correctly unwinding the stack of exit callbacks. It provides a suitable " "foundation for higher level context managers that manipulate the exit stack " "in application specific ways." msgstr "" #: ../Doc/library/contextlib.rst:376 msgid "" "Enters a new context manager and adds its :meth:`__exit__` method to the " "callback stack. The return value is the result of the context manager's own :" "meth:`__enter__` method." msgstr "" #: ../Doc/library/contextlib.rst:380 msgid "" "These context managers may suppress exceptions just as they normally would " "if used directly as part of a :keyword:`with` statement." msgstr "" #: ../Doc/library/contextlib.rst:385 msgid "Adds a context manager's :meth:`__exit__` method to the callback stack." msgstr "" #: ../Doc/library/contextlib.rst:387 msgid "" "As ``__enter__`` is *not* invoked, this method can be used to cover part of " "an :meth:`__enter__` implementation with a context manager's own :meth:" "`__exit__` method." msgstr "" #: ../Doc/library/contextlib.rst:391 msgid "" "If passed an object that is not a context manager, this method assumes it is " "a callback with the same signature as a context manager's :meth:`__exit__` " "method and adds it directly to the callback stack." msgstr "" #: ../Doc/library/contextlib.rst:395 msgid "" "By returning true values, these callbacks can suppress exceptions the same " "way context manager :meth:`__exit__` methods can." msgstr "" #: ../Doc/library/contextlib.rst:398 msgid "" "The passed in object is returned from the function, allowing this method to " "be used as a function decorator." msgstr "" #: ../Doc/library/contextlib.rst:403 msgid "" "Accepts an arbitrary callback function and arguments and adds it to the " "callback stack." msgstr "" #: ../Doc/library/contextlib.rst:406 msgid "" "Unlike the other methods, callbacks added this way cannot suppress " "exceptions (as they are never passed the exception details)." msgstr "" #: ../Doc/library/contextlib.rst:409 msgid "" "The passed in callback is returned from the function, allowing this method " "to be used as a function decorator." msgstr "" #: ../Doc/library/contextlib.rst:414 msgid "" "Transfers the callback stack to a fresh :class:`ExitStack` instance and " "returns it. No callbacks are invoked by this operation - instead, they will " "now be invoked when the new stack is closed (either explicitly or implicitly " "at the end of a :keyword:`with` statement)." msgstr "" #: ../Doc/library/contextlib.rst:419 msgid "" "For example, a group of files can be opened as an \"all or nothing\" " "operation as follows::" msgstr "" #: ../Doc/library/contextlib.rst:433 msgid "" "Immediately unwinds the callback stack, invoking callbacks in the reverse " "order of registration. For any context managers and exit callbacks " "registered, the arguments passed in will indicate that no exception occurred." msgstr "" #: ../Doc/library/contextlib.rst:440 msgid "" "An :ref:`asynchronous context manager `, similar to :" "class:`ExitStack`, that supports combining both synchronous and asynchronous " "context managers, as well as having coroutines for cleanup logic." msgstr "" #: ../Doc/library/contextlib.rst:445 msgid "" "The :meth:`close` method is not implemented, :meth:`aclose` must be used " "instead." msgstr "" #: ../Doc/library/contextlib.rst:450 msgid "" "Similar to :meth:`enter_context` but expects an asynchronous context manager." msgstr "" #: ../Doc/library/contextlib.rst:455 msgid "" "Similar to :meth:`push` but expects either an asynchronous context manager " "or a coroutine." msgstr "" #: ../Doc/library/contextlib.rst:460 msgid "Similar to :meth:`callback` but expects a coroutine." msgstr "" #: ../Doc/library/contextlib.rst:464 msgid "Similar to :meth:`close` but properly handles awaitables." msgstr "" #: ../Doc/library/contextlib.rst:466 msgid "Continuing the example for :func:`asynccontextmanager`::" msgstr "" #: ../Doc/library/contextlib.rst:478 msgid "Examples and Recipes" msgstr "" #: ../Doc/library/contextlib.rst:480 msgid "" "This section describes some examples and recipes for making effective use of " "the tools provided by :mod:`contextlib`." msgstr "" #: ../Doc/library/contextlib.rst:485 msgid "Supporting a variable number of context managers" msgstr "" #: ../Doc/library/contextlib.rst:487 msgid "" "The primary use case for :class:`ExitStack` is the one given in the class " "documentation: supporting a variable number of context managers and other " "cleanup operations in a single :keyword:`with` statement. The variability " "may come from the number of context managers needed being driven by user " "input (such as opening a user specified collection of files), or from some " "of the context managers being optional::" msgstr "" #: ../Doc/library/contextlib.rst:502 msgid "" "As shown, :class:`ExitStack` also makes it quite easy to use :keyword:`with` " "statements to manage arbitrary resources that don't natively support the " "context management protocol." msgstr "" #: ../Doc/library/contextlib.rst:508 msgid "Catching exceptions from ``__enter__`` methods" msgstr "" #: ../Doc/library/contextlib.rst:510 msgid "" "It is occasionally desirable to catch exceptions from an ``__enter__`` " "method implementation, *without* inadvertently catching exceptions from the :" "keyword:`with` statement body or the context manager's ``__exit__`` method. " "By using :class:`ExitStack` the steps in the context management protocol can " "be separated slightly in order to allow this::" msgstr "" #: ../Doc/library/contextlib.rst:525 msgid "" "Actually needing to do this is likely to indicate that the underlying API " "should be providing a direct resource management interface for use with :" "keyword:`try`/:keyword:`except`/:keyword:`finally` statements, but not all " "APIs are well designed in that regard. When a context manager is the only " "resource management API provided, then :class:`ExitStack` can make it easier " "to handle various situations that can't be handled directly in a :keyword:" "`with` statement." msgstr "" #: ../Doc/library/contextlib.rst:535 msgid "Cleaning up in an ``__enter__`` implementation" msgstr "" #: ../Doc/library/contextlib.rst:537 msgid "" "As noted in the documentation of :meth:`ExitStack.push`, this method can be " "useful in cleaning up an already allocated resource if later steps in the :" "meth:`__enter__` implementation fail." msgstr "" #: ../Doc/library/contextlib.rst:541 msgid "" "Here's an example of doing this for a context manager that accepts resource " "acquisition and release functions, along with an optional validation " "function, and maps them to the context management protocol::" msgstr "" #: ../Doc/library/contextlib.rst:581 msgid "Replacing any use of ``try-finally`` and flag variables" msgstr "" #: ../Doc/library/contextlib.rst:583 msgid "" "A pattern you will sometimes see is a ``try-finally`` statement with a flag " "variable to indicate whether or not the body of the ``finally`` clause " "should be executed. In its simplest form (that can't already be handled just " "by using an ``except`` clause instead), it looks something like this::" msgstr "" #: ../Doc/library/contextlib.rst:597 msgid "" "As with any ``try`` statement based code, this can cause problems for " "development and review, because the setup code and the cleanup code can end " "up being separated by arbitrarily long sections of code." msgstr "" #: ../Doc/library/contextlib.rst:601 msgid "" ":class:`ExitStack` makes it possible to instead register a callback for " "execution at the end of a ``with`` statement, and then later decide to skip " "executing that callback::" msgstr "" #: ../Doc/library/contextlib.rst:613 msgid "" "This allows the intended cleanup up behaviour to be made explicit up front, " "rather than requiring a separate flag variable." msgstr "" #: ../Doc/library/contextlib.rst:616 msgid "" "If a particular application uses this pattern a lot, it can be simplified " "even further by means of a small helper class::" msgstr "" #: ../Doc/library/contextlib.rst:634 msgid "" "If the resource cleanup isn't already neatly bundled into a standalone " "function, then it is still possible to use the decorator form of :meth:" "`ExitStack.callback` to declare the resource cleanup in advance::" msgstr "" #: ../Doc/library/contextlib.rst:649 msgid "" "Due to the way the decorator protocol works, a callback function declared " "this way cannot take any parameters. Instead, any resources to be released " "must be accessed as closure variables." msgstr "" #: ../Doc/library/contextlib.rst:655 msgid "Using a context manager as a function decorator" msgstr "" #: ../Doc/library/contextlib.rst:657 msgid "" ":class:`ContextDecorator` makes it possible to use a context manager in both " "an ordinary ``with`` statement and also as a function decorator." msgstr "" #: ../Doc/library/contextlib.rst:660 msgid "" "For example, it is sometimes useful to wrap functions or groups of " "statements with a logger that can track the time of entry and time of exit. " "Rather than writing both a function decorator and a context manager for the " "task, inheriting from :class:`ContextDecorator` provides both capabilities " "in a single definition::" msgstr "" #: ../Doc/library/contextlib.rst:681 msgid "Instances of this class can be used as both a context manager::" msgstr "" #: ../Doc/library/contextlib.rst:687 msgid "And also as a function decorator::" msgstr "" #: ../Doc/library/contextlib.rst:694 msgid "" "Note that there is one additional limitation when using context managers as " "function decorators: there's no way to access the return value of :meth:" "`__enter__`. If that value is needed, then it is still necessary to use an " "explicit ``with`` statement." msgstr "" #: ../Doc/library/contextlib.rst:702 msgid ":pep:`343` - The \"with\" statement" msgstr ":pep:`343` - The \"with\" statement" #: ../Doc/library/contextlib.rst:702 msgid "" "The specification, background, and examples for the Python :keyword:`with` " "statement." msgstr "" "La spécification, les motivations et des exemples de l'instruction :keyword:" "`with` en Python." #: ../Doc/library/contextlib.rst:708 msgid "Single use, reusable and reentrant context managers" msgstr "" #: ../Doc/library/contextlib.rst:710 msgid "" "Most context managers are written in a way that means they can only be used " "effectively in a :keyword:`with` statement once. These single use context " "managers must be created afresh each time they're used - attempting to use " "them a second time will trigger an exception or otherwise not work correctly." msgstr "" #: ../Doc/library/contextlib.rst:716 msgid "" "This common limitation means that it is generally advisable to create " "context managers directly in the header of the :keyword:`with` statement " "where they are used (as shown in all of the usage examples above)." msgstr "" #: ../Doc/library/contextlib.rst:720 msgid "" "Files are an example of effectively single use context managers, since the " "first :keyword:`with` statement will close the file, preventing any further " "IO operations using that file object." msgstr "" #: ../Doc/library/contextlib.rst:724 msgid "" "Context managers created using :func:`contextmanager` are also single use " "context managers, and will complain about the underlying generator failing " "to yield if an attempt is made to use them a second time::" msgstr "" #: ../Doc/library/contextlib.rst:752 msgid "Reentrant context managers" msgstr "" #: ../Doc/library/contextlib.rst:754 msgid "" "More sophisticated context managers may be \"reentrant\". These context " "managers can not only be used in multiple :keyword:`with` statements, but " "may also be used *inside* a :keyword:`with` statement that is already using " "the same context manager." msgstr "" #: ../Doc/library/contextlib.rst:759 msgid "" ":class:`threading.RLock` is an example of a reentrant context manager, as " "are :func:`suppress` and :func:`redirect_stdout`. Here's a very simple " "example of reentrant use::" msgstr "" #: ../Doc/library/contextlib.rst:778 msgid "" "Real world examples of reentrancy are more likely to involve multiple " "functions calling each other and hence be far more complicated than this " "example." msgstr "" #: ../Doc/library/contextlib.rst:782 msgid "" "Note also that being reentrant is *not* the same thing as being thread " "safe. :func:`redirect_stdout`, for example, is definitely not thread safe, " "as it makes a global modification to the system state by binding :data:`sys." "stdout` to a different stream." msgstr "" #: ../Doc/library/contextlib.rst:791 msgid "Reusable context managers" msgstr "" #: ../Doc/library/contextlib.rst:793 msgid "" "Distinct from both single use and reentrant context managers are \"reusable" "\" context managers (or, to be completely explicit, \"reusable, but not " "reentrant\" context managers, since reentrant context managers are also " "reusable). These context managers support being used multiple times, but " "will fail (or otherwise not work correctly) if the specific context manager " "instance has already been used in a containing with statement." msgstr "" #: ../Doc/library/contextlib.rst:800 msgid "" ":class:`threading.Lock` is an example of a reusable, but not reentrant, " "context manager (for a reentrant lock, it is necessary to use :class:" "`threading.RLock` instead)." msgstr "" #: ../Doc/library/contextlib.rst:804 msgid "" "Another example of a reusable, but not reentrant, context manager is :class:" "`ExitStack`, as it invokes *all* currently registered callbacks when leaving " "any with statement, regardless of where those callbacks were added::" msgstr "" #: ../Doc/library/contextlib.rst:835 msgid "" "As the output from the example shows, reusing a single stack object across " "multiple with statements works correctly, but attempting to nest them will " "cause the stack to be cleared at the end of the innermost with statement, " "which is unlikely to be desirable behaviour." msgstr "" #: ../Doc/library/contextlib.rst:840 msgid "" "Using separate :class:`ExitStack` instances instead of reusing a single " "instance avoids that problem::" msgstr ""