1""" 2Wrappers to make file-like objects cooperative. 3 4.. class:: FileObject(fobj, mode='r', buffering=-1, closefd=True, encoding=None, errors=None, newline=None) 5 6 The main entry point to the file-like gevent-compatible behaviour. It 7 will be defined to be the best available implementation. 8 9 All the parameters are as for :func:`io.open`. 10 11 :param fobj: Usually a file descriptor of a socket. Can also be 12 another object with a ``fileno()`` method, or an object that can 13 be passed to ``io.open()`` (e.g., a file system path). If the object 14 is not a socket, the results will vary based on the platform and the 15 type of object being opened. 16 17 All supported versions of Python allow :class:`os.PathLike` objects. 18 19 .. versionchanged:: 1.5 20 Accept str and ``PathLike`` objects for *fobj* on all versions of Python. 21 .. versionchanged:: 1.5 22 Add *encoding*, *errors* and *newline* arguments. 23 .. versionchanged:: 1.5 24 Accept *closefd* and *buffering* instead of *close* and *bufsize* arguments. 25 The latter remain for backwards compatibility. 26 27There are two main implementations of ``FileObject``. On all systems, 28there is :class:`FileObjectThread` which uses the built-in native 29threadpool to avoid blocking the entire interpreter. On UNIX systems 30(those that support the :mod:`fcntl` module), there is also 31:class:`FileObjectPosix` which uses native non-blocking semantics. 32 33A third class, :class:`FileObjectBlock`, is simply a wrapper that 34executes everything synchronously (and so is not gevent-compatible). 35It is provided for testing and debugging purposes. 36 37All classes have the same signature; some may accept extra keyword arguments. 38 39Configuration 40============= 41 42You may change the default value for ``FileObject`` using the 43``GEVENT_FILE`` environment variable. Set it to ``posix``, ``thread``, 44or ``block`` to choose from :class:`FileObjectPosix`, 45:class:`FileObjectThread` and :class:`FileObjectBlock`, respectively. 46You may also set it to the fully qualified class name of another 47object that implements the file interface to use one of your own 48objects. 49 50.. note:: 51 52 The environment variable must be set at the time this module 53 is first imported. 54 55Classes 56======= 57""" 58from __future__ import absolute_import 59 60from gevent._config import config 61 62__all__ = [ 63 'FileObjectPosix', 64 'FileObjectThread', 65 'FileObjectBlock', 66 'FileObject', 67] 68 69try: 70 from fcntl import fcntl 71except ImportError: 72 __all__.remove("FileObjectPosix") 73else: 74 del fcntl 75 from gevent._fileobjectposix import FileObjectPosix 76 77from gevent._fileobjectcommon import FileObjectThread 78from gevent._fileobjectcommon import FileObjectBlock 79 80 81# None of the possible objects can live in this module because 82# we would get an import cycle and the config couldn't be set from code. 83# TODO: zope.hookable would be great for allowing this to be imported 84# without requiring configuration but still being very fast. 85FileObject = config.fileobject 86