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