86 lines
2.9 KiB
Python
86 lines
2.9 KiB
Python
"""
|
|
Wrappers to make file-like objects cooperative.
|
|
|
|
.. class:: FileObject(fobj, mode='r', buffering=-1, closefd=True, encoding=None, errors=None, newline=None)
|
|
|
|
The main entry point to the file-like gevent-compatible behaviour. It
|
|
will be defined to be the best available implementation.
|
|
|
|
All the parameters are as for :func:`io.open`.
|
|
|
|
:param fobj: Usually a file descriptor of a socket. Can also be
|
|
another object with a ``fileno()`` method, or an object that can
|
|
be passed to ``io.open()`` (e.g., a file system path). If the object
|
|
is not a socket, the results will vary based on the platform and the
|
|
type of object being opened.
|
|
|
|
All supported versions of Python allow :class:`os.PathLike` objects.
|
|
|
|
.. versionchanged:: 1.5
|
|
Accept str and ``PathLike`` objects for *fobj* on all versions of Python.
|
|
.. versionchanged:: 1.5
|
|
Add *encoding*, *errors* and *newline* arguments.
|
|
.. versionchanged:: 1.5
|
|
Accept *closefd* and *buffering* instead of *close* and *bufsize* arguments.
|
|
The latter remain for backwards compatibility.
|
|
|
|
There are two main implementations of ``FileObject``. On all systems,
|
|
there is :class:`FileObjectThread` which uses the built-in native
|
|
threadpool to avoid blocking the entire interpreter. On UNIX systems
|
|
(those that support the :mod:`fcntl` module), there is also
|
|
:class:`FileObjectPosix` which uses native non-blocking semantics.
|
|
|
|
A third class, :class:`FileObjectBlock`, is simply a wrapper that
|
|
executes everything synchronously (and so is not gevent-compatible).
|
|
It is provided for testing and debugging purposes.
|
|
|
|
All classes have the same signature; some may accept extra keyword arguments.
|
|
|
|
Configuration
|
|
=============
|
|
|
|
You may change the default value for ``FileObject`` using the
|
|
``GEVENT_FILE`` environment variable. Set it to ``posix``, ``thread``,
|
|
or ``block`` to choose from :class:`FileObjectPosix`,
|
|
:class:`FileObjectThread` and :class:`FileObjectBlock`, respectively.
|
|
You may also set it to the fully qualified class name of another
|
|
object that implements the file interface to use one of your own
|
|
objects.
|
|
|
|
.. note::
|
|
|
|
The environment variable must be set at the time this module
|
|
is first imported.
|
|
|
|
Classes
|
|
=======
|
|
"""
|
|
from __future__ import absolute_import
|
|
|
|
from gevent._config import config
|
|
|
|
__all__ = [
|
|
'FileObjectPosix',
|
|
'FileObjectThread',
|
|
'FileObjectBlock',
|
|
'FileObject',
|
|
]
|
|
|
|
try:
|
|
from fcntl import fcntl
|
|
except ImportError:
|
|
__all__.remove("FileObjectPosix")
|
|
else:
|
|
del fcntl
|
|
from gevent._fileobjectposix import FileObjectPosix
|
|
|
|
from gevent._fileobjectcommon import FileObjectThread
|
|
from gevent._fileobjectcommon import FileObjectBlock
|
|
|
|
|
|
# None of the possible objects can live in this module because
|
|
# we would get an import cycle and the config couldn't be set from code.
|
|
# TODO: zope.hookable would be great for allowing this to be imported
|
|
# without requiring configuration but still being very fast.
|
|
FileObject = config.fileobject
|