/usr/lib/python3/dist-packages/twisted/python
Edit: /usr/lib/python3/dist-packages/twisted/python/compat.py (16931B)
# -*- test-case-name: twisted.test.test_compat -*-
#
# Copyright (c) Twisted Matrix Laboratories.
# See LICENSE for details.
"""
Compatibility module to provide backwards compatibility for useful Python
features.
This is mainly for use of internal Twisted code. We encourage you to use
the latest version of Python directly from your code, if possible.
@var unicode: The type of Unicode strings, C{unicode} on Python 2 and C{str}
on Python 3.
@var NativeStringIO: An in-memory file-like object that operates on the native
string type (bytes in Python 2, unicode in Python 3).
@var urllib_parse: a URL-parsing module (urlparse on Python 2, urllib.parse on
Python 3)
"""
import inspect
import os
import platform
import socket
import sys
import urllib.parse as urllib_parse
import warnings
from collections.abc import Sequence
from functools import reduce
from html import escape
from http import cookiejar as cookielib
from io import IOBase, StringIO as NativeStringIO, TextIOBase
from sys import intern
from types import FrameType, MethodType as _MethodType
from typing import Any, AnyStr, cast
from urllib.parse import quote as urlquote, unquote as urlunquote
from incremental import Version
from twisted.python.deprecate import deprecated, deprecatedModuleAttribute
if sys.version_info >= (3, 7, 0):
_PY37PLUS = True
else:
_PY37PLUS = False
if platform.python_implementation() == "PyPy":
_PYPY = True
else:
_PYPY = False
FileType = IOBase
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Obsolete alias for io.IOBase",
__name__,
"FileType",
)
frozenset = frozenset
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Obsolete alias for frozenset builtin type",
__name__,
"frozenset",
)
InstanceType = object
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Old-style classes don't exist in Python 3",
__name__,
"InstanceType",
)
izip = zip
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Obsolete alias for zip() builtin",
__name__,
"izip",
)
long = int
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Obsolete alias for int builtin type",
__name__,
"long",
)
range = range
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Obsolete alias for range() builtin",
__name__,
"range",
)
raw_input = input
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Obsolete alias for input() builtin",
__name__,
"raw_input",
)
set = set
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Obsolete alias for set builtin type",
__name__,
"set",
)
StringType = str
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Obsolete alias for str builtin type",
__name__,
"StringType",
)
unichr = chr
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Obsolete alias for chr() builtin",
__name__,
"unichr",
)
unicode = str
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Obsolete alias for str builtin type",
__name__,
"unicode",
)
xrange = range
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Obsolete alias for range() builtin",
__name__,
"xrange",
)
@deprecated(Version("Twisted", 21, 2, 0), replacement="d.items()")
def iteritems(d):
"""
Return an iterable of the items of C{d}.
@type d: L{dict}
@rtype: iterable
"""
return d.items()
@deprecated(Version("Twisted", 21, 2, 0), replacement="d.values()")
def itervalues(d):
"""
Return an iterable of the values of C{d}.
@type d: L{dict}
@rtype: iterable
"""
return d.values()
@deprecated(Version("Twisted", 21, 2, 0), replacement="list(d.items())")
def items(d):
"""
Return a list of the items of C{d}.
@type d: L{dict}
@rtype: L{list}
"""
return list(d.items())
def currentframe(n: int = 0) -> FrameType:
"""
In Python 3, L{inspect.currentframe} does not take a stack-level argument.
Restore that functionality from Python 2 so we don't have to re-implement
the C{f_back}-walking loop in places where it's called.
@param n: The number of stack levels above the caller to walk.
@return: a frame, n levels up the stack from the caller.
"""
f = inspect.currentframe()
for x in range(n + 1):
assert f is not None
f = f.f_back
assert f is not None
return f
def execfile(filename, globals, locals=None):
"""
Execute a Python script in the given namespaces.
Similar to the execfile builtin, but a namespace is mandatory, partly
because that's a sensible thing to require, and because otherwise we'd
have to do some frame hacking.
This is a compatibility implementation for Python 3 porting, to avoid the
use of the deprecated builtin C{execfile} function.
"""
if locals is None:
locals = globals
with open(filename, "rb") as fin:
source = fin.read()
code = compile(source, filename, "exec")
exec(code, globals, locals)
# type note: Can't find a Comparable type, despite
# https://github.com/python/typing/issues/59
def cmp(a: object, b: object) -> int:
"""
Compare two objects.
Returns a negative number if C{a < b}, zero if they are equal, and a
positive number if C{a > b}.
"""
if a < b: # type: ignore[operator]
return -1
elif a == b:
return 0
else:
return 1
def comparable(klass):
"""
Class decorator that ensures support for the special C{__cmp__} method.
C{__eq__}, C{__lt__}, etc. methods are added to the class, relying on
C{__cmp__} to implement their comparisons.
"""
def __eq__(self: Any, other: object) -> bool:
c = cast(bool, self.__cmp__(other))
if c is NotImplemented:
return c
return c == 0
def __ne__(self: Any, other: object) -> bool:
c = cast(bool, self.__cmp__(other))
if c is NotImplemented:
return c
return c != 0
def __lt__(self: Any, other: object) -> bool:
c = cast(bool, self.__cmp__(other))
if c is NotImplemented:
return c
return c < 0
def __le__(self: Any, other: object) -> bool:
c = cast(bool, self.__cmp__(other))
if c is NotImplemented:
return c
return c <= 0
def __gt__(self: Any, other: object) -> bool:
c = cast(bool, self.__cmp__(other))
if c is NotImplemented:
return c
return c > 0
def __ge__(self: Any, other: object) -> bool:
c = cast(bool, self.__cmp__(other))
if c is NotImplemented:
return c
return c >= 0
klass.__lt__ = __lt__
klass.__gt__ = __gt__
klass.__le__ = __le__
klass.__ge__ = __ge__
klass.__eq__ = __eq__
klass.__ne__ = __ne__
return klass
def ioType(fileIshObject, default=str):
"""
Determine the type which will be returned from the given file object's
read() and accepted by its write() method as an argument.
In other words, determine whether the given file is 'opened in text mode'.
@param fileIshObject: Any object, but ideally one which resembles a file.
@type fileIshObject: L{object}
@param default: A default value to return when the type of C{fileIshObject}
cannot be determined.
@type default: L{type}
@return: There are 3 possible return values:
1. L{str}, if the file is unambiguously opened in text mode.
2. L{bytes}, if the file is unambiguously opened in binary mode.
3. The C{default} parameter, if the given type is not understood.
@rtype: L{type}
"""
if isinstance(fileIshObject, TextIOBase):
# If it's for text I/O, then it's for text I/O.
return str
if isinstance(fileIshObject, IOBase):
# If it's for I/O but it's _not_ for text I/O, it's for bytes I/O.
return bytes
encoding = getattr(fileIshObject, "encoding", None)
import codecs
if isinstance(fileIshObject, (codecs.StreamReader, codecs.StreamWriter)):
# On StreamReaderWriter, the 'encoding' attribute has special meaning;
# it is unambiguously text.
if encoding:
return str
else:
return bytes
return default
def nativeString(s: AnyStr) -> str:
"""
Convert C{bytes} or C{str} to C{str} type, using ASCII encoding if
conversion is necessary.
@raise UnicodeError: The input string is not ASCII encodable/decodable.
@raise TypeError: The input is neither C{bytes} nor C{str}.
"""
if not isinstance(s, (bytes, str)):
raise TypeError("%r is neither bytes nor str" % s)
if isinstance(s, bytes):
return s.decode("ascii")
else:
# Ensure we're limited to ASCII subset:
s.encode("ascii")
return s
def _matchingString(constantString, inputString):
"""
Some functions, such as C{os.path.join}, operate on string arguments which
may be bytes or text, and wish to return a value of the same type. In
those cases you may wish to have a string constant (in the case of
C{os.path.join}, that constant would be C{os.path.sep}) involved in the
parsing or processing, that must be of a matching type in order to use
string operations on it. L{_matchingString} will take a constant string
(either L{bytes} or L{str}) and convert it to the same type as the
input string. C{constantString} should contain only characters from ASCII;
to ensure this, it will be encoded or decoded regardless.
@param constantString: A string literal used in processing.
@type constantString: L{str} or L{bytes}
@param inputString: A byte string or text string provided by the user.
@type inputString: L{str} or L{bytes}
@return: C{constantString} converted into the same type as C{inputString}
@rtype: the type of C{inputString}
"""
if isinstance(constantString, bytes):
otherType = constantString.decode("ascii")
else:
otherType = constantString.encode("ascii")
if type(constantString) == type(inputString):
return constantString
else:
return otherType
@deprecated(
Version("Twisted", 21, 2, 0),
replacement="raise exception.with_traceback(traceback)",
)
def reraise(exception, traceback):
"""
Re-raise an exception, with an optional traceback.
Re-raised exceptions will be mutated, with their C{__traceback__} attribute
being set.
@param exception: The exception instance.
@param traceback: The traceback to use, or L{None} indicating a new
traceback.
"""
raise exception.with_traceback(traceback)
def iterbytes(originalBytes):
"""
Return an iterable wrapper for a C{bytes} object that provides the behavior
of iterating over C{bytes} on Python 2.
In particular, the results of iteration are the individual bytes (rather
than integers as on Python 3).
@param originalBytes: A C{bytes} object that will be wrapped.
"""
for i in range(len(originalBytes)):
yield originalBytes[i : i + 1]
@deprecated(Version("Twisted", 21, 2, 0), replacement="b'%d'")
def intToBytes(i: int) -> bytes:
"""
Convert the given integer into C{bytes}, as ASCII-encoded Arab numeral.
@param i: The C{int} to convert to C{bytes}.
@rtype: C{bytes}
"""
return b"%d" % (i,)
def lazyByteSlice(object, offset=0, size=None):
"""
Return a copy of the given bytes-like object.
If an offset is given, the copy starts at that offset. If a size is
given, the copy will only be of that length.
@param object: C{bytes} to be copied.
@param offset: C{int}, starting index of copy.
@param size: Optional, if an C{int} is given limit the length of copy
to this size.
"""
view = memoryview(object)
if size is None:
return view[offset:]
else:
return view[offset : (offset + size)]
def networkString(s: str) -> bytes:
"""
Convert a string to L{bytes} using ASCII encoding.
This is useful for sending text-like bytes that are constructed using
string interpolation. For example::
networkString("Hello %d" % (n,))
@param s: A string to convert to bytes.
@type s: L{str}
@raise UnicodeError: The input string is not ASCII encodable.
@raise TypeError: The input is not L{str}.
@rtype: L{bytes}
"""
if not isinstance(s, str):
raise TypeError("Can only convert strings to bytes")
return s.encode("ascii")
@deprecated(Version("Twisted", 21, 2, 0), replacement="os.environb")
def bytesEnviron():
"""
Return a L{dict} of L{os.environ} where all text-strings are encoded into
L{bytes}.
This function is POSIX only; environment variables are always text strings
on Windows.
"""
encodekey = os.environ.encodekey
encodevalue = os.environ.encodevalue
return {encodekey(x): encodevalue(y) for x, y in os.environ.items()} # type: ignore[call-arg]
def _constructMethod(cls, name, self):
"""
Construct a bound method.
@param cls: The class that the method should be bound to.
@type cls: L{type}
@param name: The name of the method.
@type name: native L{str}
@param self: The object that the method is bound to.
@type self: any object
@return: a bound method
@rtype: L{_MethodType}
"""
func = cls.__dict__[name]
return _MethodType(func, self)
def _get_async_param(isAsync=None, **kwargs):
"""
Provide a backwards-compatible way to get async param value that does not
cause a syntax error under Python 3.7.
@param isAsync: isAsync param value (should default to None)
@type isAsync: L{bool}
@param kwargs: keyword arguments of the caller (only async is allowed)
@type kwargs: L{dict}
@raise TypeError: Both isAsync and async specified.
@return: Final isAsync param value
@rtype: L{bool}
"""
if "async" in kwargs:
warnings.warn(
"'async' keyword argument is deprecated, please use isAsync",
DeprecationWarning,
stacklevel=2,
)
if isAsync is None and "async" in kwargs:
isAsync = kwargs.pop("async")
if kwargs:
raise TypeError
return bool(isAsync)
def _pypy3BlockingHack():
"""
Work around U{https://foss.heptapod.net/pypy/pypy/-/issues/3051}
by replacing C{socket.fromfd} with a more conservative version.
"""
try:
from fcntl import F_GETFL, F_SETFL, fcntl
except ImportError:
return
if not _PYPY:
return
def fromFDWithoutModifyingFlags(fd, family, type, proto=None):
passproto = [proto] * (proto is not None)
flags = fcntl(fd, F_GETFL)
try:
return realFromFD(fd, family, type, *passproto)
finally:
fcntl(fd, F_SETFL, flags)
realFromFD = socket.fromfd
if realFromFD.__name__ == fromFDWithoutModifyingFlags.__name__:
return
socket.fromfd = fromFDWithoutModifyingFlags
_pypy3BlockingHack()
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Use functools.reduce() directly",
__name__,
"reduce",
)
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Use io.StringIO directly",
__name__,
"NativeStringIO",
)
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Import urllib.parse directly",
__name__,
"urllib_parse",
)
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0), "Use html.escape directly", __name__, "escape"
)
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Use urllib.parse.quote() directly",
__name__,
"urlquote",
)
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Use urllib.parse.unquote() directly",
__name__,
"urlunquote",
)
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Use http.cookiejar directly",
__name__,
"cookielib",
)
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0), "Use sys.intern() directly", __name__, "intern"
)
deprecatedModuleAttribute(
Version("Twisted", 21, 2, 0),
"Use collections.abc.Sequence directly",
__name__,
"Sequence",
)
__all__ = [
"reraise",
"execfile",
"frozenset",
"reduce",
"set",
"cmp",
"comparable",
"nativeString",
"NativeStringIO",
"networkString",
"unicode",
"iterbytes",
"intToBytes",
"lazyByteSlice",
"StringType",
"InstanceType",
"FileType",
"items",
"iteritems",
"itervalues",
"range",
"xrange",
"urllib_parse",
"bytesEnviron",
"escape",
"urlquote",
"urlunquote",
"cookielib",
"intern",
"unichr",
"raw_input",
"_get_async_param",
"Sequence",
]