diff options
Diffstat (limited to 'Python/Dependencies/future-0.18.2/docs')
81 files changed, 12833 insertions, 0 deletions
diff --git a/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/astropy_py3compat.py b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/astropy_py3compat.py new file mode 100644 index 0000000..d264da8 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/astropy_py3compat.py @@ -0,0 +1,213 @@ +# Licensed under a 3-clause BSD style license - see PYFITS.rst + +import sys + +PY3 = sys.version_info[0] >= 3 + +if PY3: # pragma: py3 + # Stuff to do if Python 3 + import builtins + import io + + # Bring back the cmp() function + builtins.cmp = lambda a, b: (a > b) - (a < b) + + # Make the decode_ascii utility function actually work + from . import util + import numpy + + def encode_ascii(s): + if isinstance(s, str): + return s.encode('ascii') + elif isinstance(s, numpy.ndarray) and \ + issubclass(s.dtype.type, numpy.str_): + ns = numpy.char.encode(s, 'ascii').view(type(s)) + if ns.dtype.itemsize != s.dtype.itemsize / 4: + ns = ns.astype((numpy.bytes_, s.dtype.itemsize / 4)) + return ns + return s + util.encode_ascii = encode_ascii + + def decode_ascii(s): + if isinstance(s, bytes): + return s.decode('ascii') + elif (isinstance(s, numpy.ndarray) and + issubclass(s.dtype.type, numpy.bytes_)): + # np.char.encode/decode annoyingly don't preserve the type of the + # array, hence the view() call + # It also doesn't necessarily preserve widths of the strings, + # hence the astype() + ns = numpy.char.decode(s, 'ascii').view(type(s)) + if ns.dtype.itemsize / 4 != s.dtype.itemsize: + ns = ns.astype((numpy.str_, s.dtype.itemsize)) + return ns + return s + util.decode_ascii = decode_ascii + + # Replacements for b and u marks on strings + def b(s): + return s.encode('latin-1') + + def u(s): + return s + + util.b = b + util.u = u + + # See the docstring for astropy.io.fits.util.fileobj_open for why we need + # to replace this function + def fileobj_open(filename, mode): + return open(filename, mode, buffering=0) + util.fileobj_open = fileobj_open + + # Support the io.IOBase.readable/writable methods + from .util import isreadable as _isreadable + + def isreadable(f): + if hasattr(f, 'readable'): + return f.readable() + return _isreadable(f) + util.isreadable = isreadable + + from .util import iswritable as _iswritable + + def iswritable(f): + if hasattr(f, 'writable'): + return f.writable() + return _iswritable(f) + util.iswritable = iswritable + + # isfile needs to support the higher-level wrappers around FileIO + def isfile(f): + if isinstance(f, io.FileIO): + return True + elif hasattr(f, 'buffer'): + return isfile(f.buffer) + elif hasattr(f, 'raw'): + return isfile(f.raw) + return False + util.isfile = isfile + + # Here we monkey patch (yes, I know) numpy to fix a few numpy Python 3 + # bugs. The only behavior that's modified is that bugs are fixed, so that + # should be OK. + + # Fix chararrays; this is necessary in numpy 1.5.1 and below--hopefully + # should not be necessary later. See + # http://projects.scipy.org/numpy/ticket/1817 + # TODO: Maybe do a version check on numpy for this? (Note: the fix for + # this hasn't been accepted in Numpy yet, so a version number check would + # not be helpful yet...) + from . import file + + _chararray = numpy.char.chararray + + class chararray(_chararray): + def __getitem__(self, obj): + val = numpy.ndarray.__getitem__(self, obj) + if isinstance(val, numpy.character): + temp = val.rstrip() + if numpy.char._len(temp) == 0: + val = '' + else: + val = temp + return val + for m in [numpy.char, numpy.core.defchararray, numpy.core.records]: + m.chararray = chararray + + # Fix recarrays with sub-array fields. See + # http://projects.scipy.org/numpy/ticket/1766 + # TODO: Same as above, though the fix to this problem hasn't made it into + # any Numpy release yet either, so we'll have to hold off on a version + # check + def _fix_dtype(dtype): + """ + Numpy has a bug (in Python3 only) that causes a segfault when + accessing the data of arrays containing nested arrays. Specifically, + this happens if the shape of the subarray is not given as a tuple. + See http://projects.scipy.org/numpy/ticket/1766. + """ + + if not hasattr(dtype, 'fields') or dtype.fields is None: + return dtype + + formats = [] + offsets = [] + titles = [] + for name in dtype.names: + field = dtype.fields[name] + shape = field[0].shape + if not isinstance(shape, tuple): + shape = (shape,) + formats.append((field[0].base, shape)) + offsets.append(field[1]) + + # There seems to be no obvious way to extract the titles from + # a dtype, so this just searches for duplicate fields + title = None + for key, dup in dtype.fields.items(): + if key != name and dup == field: + title = key + break + titles.append(title) + + return numpy.dtype({'names': dtype.names, 'formats': formats, + 'offsets': offsets, 'titles': titles}) + + _recarray = numpy.recarray + + class recarray(_recarray): + def __new__(subtype, shape, dtype=None, buf=None, offset=0, + strides=None, formats=None, names=None, titles=None, + byteorder=None, aligned=False, order='C'): + if dtype is not None: + dtype = _fix_dtype(dtype) + + if 'order' in _recarray.__new__.__code__.co_varnames: + return _recarray.__new__( + subtype, shape, dtype, buf, offset, strides, formats, + names, titles, byteorder, aligned, order) + else: + return _recarray.__new__( + subtype, shape, dtype, buf, offset, strides, formats, + names, titles, byteorder, aligned) + numpy.recarray = numpy.core.records.recarray = recarray + + # We also need to patch astropy.io.fits.file._File which can also be + # affected by the #1766 bug + old_File = file._File + + class _File(old_File): + def readarray(self, size=None, offset=0, dtype=numpy.uint8, + shape=None): + if isinstance(dtype, numpy.dtype): + dtype = _fix_dtype(dtype) + return old_File.readarray(self, size, offset, dtype, shape) + readarray.__doc__ = old_File.readarray.__doc__ + file._File = _File + + # Replace astropy.io.fits.util.maketrans and translate with versions that + # work with Python 3 unicode strings + util.maketrans = str.maketrans + + def translate(s, table, deletechars): + if deletechars: + table = table.copy() + for c in deletechars: + table[ord(c)] = None + return s.translate(table) + util.translate = translate +else: + # Stuff to do if not Python 3 + import string + from . import util + util.maketrans = string.maketrans + + def b(s): + return s + + def u(s): + return unicode(s, 'unicode_escape') + + util.b = b + util.u = u diff --git a/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/django_utils_encoding.py b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/django_utils_encoding.py new file mode 100644 index 0000000..aa0218c --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/django_utils_encoding.py @@ -0,0 +1,228 @@ +from __future__ import unicode_literals + +import codecs +import datetime +from decimal import Decimal +import locale +try: + from urllib.parse import quote +except ImportError: # Python 2 + from urllib import quote + +from django.utils.functional import Promise +from django.utils import six + +class DjangoUnicodeDecodeError(UnicodeDecodeError): + def __init__(self, obj, *args): + self.obj = obj + UnicodeDecodeError.__init__(self, *args) + + def __str__(self): + original = UnicodeDecodeError.__str__(self) + return '%s. You passed in %r (%s)' % (original, self.obj, + type(self.obj)) + +def python_2_unicode_compatible(klass): + """ + A decorator that defines __unicode__ and __str__ methods under Python 2. + Under Python 3 it does nothing. + + To support Python 2 and 3 with a single code base, define a __str__ method + returning text and apply this decorator to the class. + """ + if not six.PY3: + klass.__unicode__ = klass.__str__ + klass.__str__ = lambda self: self.__unicode__().encode('utf-8') + return klass + +def smart_text(s, encoding='utf-8', strings_only=False, errors='strict'): + """ + Returns a text object representing 's' -- unicode on Python 2 and str on + Python 3. Treats bytestrings using the 'encoding' codec. + + If strings_only is True, don't convert (some) non-string-like objects. + """ + if isinstance(s, Promise): + # The input is the result of a gettext_lazy() call. + return s + return force_text(s, encoding, strings_only, errors) + +def is_protected_type(obj): + """Determine if the object instance is of a protected type. + + Objects of protected types are preserved as-is when passed to + force_text(strings_only=True). + """ + return isinstance(obj, six.integer_types + (type(None), float, Decimal, + datetime.datetime, datetime.date, datetime.time)) + +def force_text(s, encoding='utf-8', strings_only=False, errors='strict'): + """ + Similar to smart_text, except that lazy instances are resolved to + strings, rather than kept as lazy objects. + + If strings_only is True, don't convert (some) non-string-like objects. + """ + # Handle the common case first, saves 30-40% when s is an instance of + # six.text_type. This function gets called often in that setting. + if isinstance(s, six.text_type): + return s + if strings_only and is_protected_type(s): + return s + try: + if not isinstance(s, six.string_types): + if hasattr(s, '__unicode__'): + s = s.__unicode__() + else: + if six.PY3: + if isinstance(s, bytes): + s = six.text_type(s, encoding, errors) + else: + s = six.text_type(s) + else: + s = six.text_type(bytes(s), encoding, errors) + else: + # Note: We use .decode() here, instead of six.text_type(s, encoding, + # errors), so that if s is a SafeBytes, it ends up being a + # SafeText at the end. + s = s.decode(encoding, errors) + except UnicodeDecodeError as e: + if not isinstance(s, Exception): + raise DjangoUnicodeDecodeError(s, *e.args) + else: + # If we get to here, the caller has passed in an Exception + # subclass populated with non-ASCII bytestring data without a + # working unicode method. Try to handle this without raising a + # further exception by individually forcing the exception args + # to unicode. + s = ' '.join([force_text(arg, encoding, strings_only, + errors) for arg in s]) + return s + +def smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict'): + """ + Returns a bytestring version of 's', encoded as specified in 'encoding'. + + If strings_only is True, don't convert (some) non-string-like objects. + """ + if isinstance(s, Promise): + # The input is the result of a gettext_lazy() call. + return s + return force_bytes(s, encoding, strings_only, errors) + + +def force_bytes(s, encoding='utf-8', strings_only=False, errors='strict'): + """ + Similar to smart_bytes, except that lazy instances are resolved to + strings, rather than kept as lazy objects. + + If strings_only is True, don't convert (some) non-string-like objects. + """ + if isinstance(s, six.memoryview): + s = bytes(s) + if isinstance(s, bytes): + if encoding == 'utf-8': + return s + else: + return s.decode('utf-8', errors).encode(encoding, errors) + if strings_only and (s is None or isinstance(s, int)): + return s + if isinstance(s, Promise): + return six.text_type(s).encode(encoding, errors) + if not isinstance(s, six.string_types): + try: + if six.PY3: + return six.text_type(s).encode(encoding) + else: + return bytes(s) + except UnicodeEncodeError: + if isinstance(s, Exception): + # An Exception subclass containing non-ASCII data that doesn't + # know how to print itself properly. We shouldn't raise a + # further exception. + return b' '.join([force_bytes(arg, encoding, strings_only, + errors) for arg in s]) + return six.text_type(s).encode(encoding, errors) + else: + return s.encode(encoding, errors) + +if six.PY3: + smart_str = smart_text + force_str = force_text +else: + smart_str = smart_bytes + force_str = force_bytes + # backwards compatibility for Python 2 + smart_unicode = smart_text + force_unicode = force_text + +smart_str.__doc__ = """\ +Apply smart_text in Python 3 and smart_bytes in Python 2. + +This is suitable for writing to sys.stdout (for instance). +""" + +force_str.__doc__ = """\ +Apply force_text in Python 3 and force_bytes in Python 2. +""" + +def iri_to_uri(iri): + """ + Convert an Internationalized Resource Identifier (IRI) portion to a URI + portion that is suitable for inclusion in a URL. + + This is the algorithm from section 3.1 of RFC 3987. However, since we are + assuming input is either UTF-8 or unicode already, we can simplify things a + little from the full method. + + Returns an ASCII string containing the encoded result. + """ + # The list of safe characters here is constructed from the "reserved" and + # "unreserved" characters specified in sections 2.2 and 2.3 of RFC 3986: + # reserved = gen-delims / sub-delims + # gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@" + # sub-delims = "!" / "$" / "&" / "'" / "(" / ")" + # / "*" / "+" / "," / ";" / "=" + # unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" + # Of the unreserved characters, urllib.quote already considers all but + # the ~ safe. + # The % character is also added to the list of safe characters here, as the + # end of section 3.1 of RFC 3987 specifically mentions that % must not be + # converted. + if iri is None: + return iri + return quote(force_bytes(iri), safe=b"/#%[]=:;$&()+,!?*@'~") + +def filepath_to_uri(path): + """Convert a file system path to a URI portion that is suitable for + inclusion in a URL. + + We are assuming input is either UTF-8 or unicode already. + + This method will encode certain chars that would normally be recognized as + special chars for URIs. Note that this method does not encode the ' + character, as it is a valid character within URIs. See + encodeURIComponent() JavaScript function for more details. + + Returns an ASCII string containing the encoded result. + """ + if path is None: + return path + # I know about `os.sep` and `os.altsep` but I want to leave + # some flexibility for hardcoding separators. + return quote(force_bytes(path).replace(b"\\", b"/"), safe=b"/~!*()'") + +def get_system_encoding(): + """ + The encoding of the default system locale but falls back to the given + fallback encoding if the encoding is unsupported by python or could + not be determined. See tickets #10335 and #5846 + """ + try: + encoding = locale.getdefaultlocale()[1] or 'ascii' + codecs.lookup(encoding) + except Exception: + encoding = 'ascii' + return encoding + +DEFAULT_LOCALE_ENCODING = get_system_encoding() diff --git a/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/gevent_py3k.py b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/gevent_py3k.py new file mode 100644 index 0000000..465cb50 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/gevent_py3k.py @@ -0,0 +1,17 @@ +""" +From gevent/hub.py +""" +PY3 = sys.version_info[0] >= 3 + +if PY3: + string_types = str, + integer_types = int, +else: + string_types = basestring, + integer_types = (int, long) + + +if sys.version_info[0] <= 2: + import thread +else: + import _thread as thread diff --git a/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/ipython_py3compat.py b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/ipython_py3compat.py new file mode 100644 index 0000000..c9fbb2c --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/ipython_py3compat.py @@ -0,0 +1,178 @@ +# coding: utf-8 +"""Compatibility tricks for Python 3. Mainly to do with unicode.""" +import __builtin__ +import functools +import sys +import re +import types + +from .encoding import DEFAULT_ENCODING + +orig_open = open + +def no_code(x, encoding=None): + return x + +def decode(s, encoding=None): + encoding = encoding or DEFAULT_ENCODING + return s.decode(encoding, "replace") + +def encode(u, encoding=None): + encoding = encoding or DEFAULT_ENCODING + return u.encode(encoding, "replace") + + +def cast_unicode(s, encoding=None): + if isinstance(s, bytes): + return decode(s, encoding) + return s + +def cast_bytes(s, encoding=None): + if not isinstance(s, bytes): + return encode(s, encoding) + return s + +def _modify_str_or_docstring(str_change_func): + @functools.wraps(str_change_func) + def wrapper(func_or_str): + if isinstance(func_or_str, basestring): + func = None + doc = func_or_str + else: + func = func_or_str + doc = func.__doc__ + + doc = str_change_func(doc) + + if func: + func.__doc__ = doc + return func + return doc + return wrapper + +if sys.version_info[0] >= 3: + PY3 = True + + input = input + builtin_mod_name = "builtins" + + str_to_unicode = no_code + unicode_to_str = no_code + str_to_bytes = encode + bytes_to_str = decode + cast_bytes_py2 = no_code + + def isidentifier(s, dotted=False): + if dotted: + return all(isidentifier(a) for a in s.split(".")) + return s.isidentifier() + + open = orig_open + + MethodType = types.MethodType + + def execfile(fname, glob, loc=None): + loc = loc if (loc is not None) else glob + exec compile(open(fname, 'rb').read(), fname, 'exec') in glob, loc + + # Refactor print statements in doctests. + _print_statement_re = re.compile(r"\bprint (?P<expr>.*)$", re.MULTILINE) + def _print_statement_sub(match): + expr = match.groups('expr') + return "print(%s)" % expr + + @_modify_str_or_docstring + def doctest_refactor_print(doc): + """Refactor 'print x' statements in a doctest to print(x) style. 2to3 + unfortunately doesn't pick up on our doctests. + + Can accept a string or a function, so it can be used as a decorator.""" + return _print_statement_re.sub(_print_statement_sub, doc) + + # Abstract u'abc' syntax: + @_modify_str_or_docstring + def u_format(s): + """"{u}'abc'" --> "'abc'" (Python 3) + + Accepts a string or a function, so it can be used as a decorator.""" + return s.format(u='') + +else: + PY3 = False + + input = raw_input + builtin_mod_name = "__builtin__" + + str_to_unicode = decode + unicode_to_str = encode + str_to_bytes = no_code + bytes_to_str = no_code + cast_bytes_py2 = cast_bytes + + import re + _name_re = re.compile(r"[a-zA-Z_][a-zA-Z0-9_]*$") + def isidentifier(s, dotted=False): + if dotted: + return all(isidentifier(a) for a in s.split(".")) + return bool(_name_re.match(s)) + + class open(object): + """Wrapper providing key part of Python 3 open() interface.""" + def __init__(self, fname, mode="r", encoding="utf-8"): + self.f = orig_open(fname, mode) + self.enc = encoding + + def write(self, s): + return self.f.write(s.encode(self.enc)) + + def read(self, size=-1): + return self.f.read(size).decode(self.enc) + + def close(self): + return self.f.close() + + def __enter__(self): + return self + + def __exit__(self, etype, value, traceback): + self.f.close() + + def MethodType(func, instance): + return types.MethodType(func, instance, type(instance)) + + # don't override system execfile on 2.x: + execfile = execfile + + def doctest_refactor_print(func_or_str): + return func_or_str + + + # Abstract u'abc' syntax: + @_modify_str_or_docstring + def u_format(s): + """"{u}'abc'" --> "u'abc'" (Python 2) + + Accepts a string or a function, so it can be used as a decorator.""" + return s.format(u='u') + + if sys.platform == 'win32': + def execfile(fname, glob=None, loc=None): + loc = loc if (loc is not None) else glob + # The rstrip() is necessary b/c trailing whitespace in files will + # cause an IndentationError in Python 2.6 (this was fixed in 2.7, + # but we still support 2.6). See issue 1027. + scripttext = __builtin__.open(fname).read().rstrip() + '\n' + # compile converts unicode filename to str assuming + # ascii. Let's do the conversion before calling compile + if isinstance(fname, unicode): + filename = unicode_to_str(fname) + else: + filename = fname + exec compile(scripttext, filename, 'exec') in glob, loc + else: + def execfile(fname, *where): + if isinstance(fname, unicode): + filename = fname.encode(sys.getfilesystemencoding()) + else: + filename = fname + __builtin__.execfile(filename, *where) diff --git a/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/jinja2_compat.py b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/jinja2_compat.py new file mode 100644 index 0000000..1326cbc --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/jinja2_compat.py @@ -0,0 +1,109 @@ +# -*- coding: utf-8 -*- +""" + jinja2._compat + ~~~~~~~~~~~~~~ + + Some py2/py3 compatibility support based on a stripped down + version of six so we don't have to depend on a specific version + of it. + + :copyright: Copyright 2013 by the Jinja team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" +import sys + +PY2 = sys.version_info[0] == 2 +PYPY = hasattr(sys, 'pypy_translation_info') +_identity = lambda x: x + + +if not PY2: + unichr = chr + range_type = range + text_type = str + string_types = (str,) + + iterkeys = lambda d: iter(d.keys()) + itervalues = lambda d: iter(d.values()) + iteritems = lambda d: iter(d.items()) + + import pickle + from io import BytesIO, StringIO + NativeStringIO = StringIO + + def reraise(tp, value, tb=None): + if value.__traceback__ is not tb: + raise value.with_traceback(tb) + raise value + + ifilter = filter + imap = map + izip = zip + intern = sys.intern + + implements_iterator = _identity + implements_to_string = _identity + encode_filename = _identity + get_next = lambda x: x.__next__ + +else: + unichr = unichr + text_type = unicode + range_type = xrange + string_types = (str, unicode) + + iterkeys = lambda d: d.iterkeys() + itervalues = lambda d: d.itervalues() + iteritems = lambda d: d.iteritems() + + import cPickle as pickle + from cStringIO import StringIO as BytesIO, StringIO + NativeStringIO = BytesIO + + exec('def reraise(tp, value, tb=None):\n raise tp, value, tb') + + from itertools import imap, izip, ifilter + intern = intern + + def implements_iterator(cls): + cls.next = cls.__next__ + del cls.__next__ + return cls + + def implements_to_string(cls): + cls.__unicode__ = cls.__str__ + cls.__str__ = lambda x: x.__unicode__().encode('utf-8') + return cls + + get_next = lambda x: x.next + + def encode_filename(filename): + if isinstance(filename, unicode): + return filename.encode('utf-8') + return filename + + +def with_metaclass(meta, *bases): + # This requires a bit of explanation: the basic idea is to make a + # dummy metaclass for one level of class instanciation that replaces + # itself with the actual metaclass. Because of internal type checks + # we also need to make sure that we downgrade the custom metaclass + # for one level to something closer to type (that's why __call__ and + # __init__ comes back from type etc.). + # + # This has the advantage over six.with_metaclass in that it does not + # introduce dummy classes into the final MRO. + class metaclass(meta): + __call__ = type.__call__ + __init__ = type.__init__ + def __new__(cls, name, this_bases, d): + if this_bases is None: + return type.__new__(cls, name, (), d) + return meta(name, bases, d) + return metaclass('temporary_class', None, {}) + + +try: + from urllib.parse import quote_from_bytes as url_quote +except ImportError: + from urllib import quote as url_quote diff --git a/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/numpy_py3k.py b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/numpy_py3k.py new file mode 100644 index 0000000..0a03929 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/numpy_py3k.py @@ -0,0 +1,71 @@ +""" +Python 3 compatibility tools. + +""" + +__all__ = ['bytes', 'asbytes', 'isfileobj', 'getexception', 'strchar', + 'unicode', 'asunicode', 'asbytes_nested', 'asunicode_nested', + 'asstr', 'open_latin1'] + +import sys + +if sys.version_info[0] >= 3: + import io + bytes = bytes + unicode = str + + def asunicode(s): + if isinstance(s, bytes): + return s.decode('latin1') + return str(s) + + def asbytes(s): + if isinstance(s, bytes): + return s + return str(s).encode('latin1') + + def asstr(s): + if isinstance(s, bytes): + return s.decode('latin1') + return str(s) + + def isfileobj(f): + return isinstance(f, (io.FileIO, io.BufferedReader)) + + def open_latin1(filename, mode='r'): + return open(filename, mode=mode, encoding='iso-8859-1') + + strchar = 'U' + +else: + bytes = str + unicode = unicode + asbytes = str + asstr = str + strchar = 'S' + + def isfileobj(f): + return isinstance(f, file) + + def asunicode(s): + if isinstance(s, unicode): + return s + return str(s).decode('ascii') + + def open_latin1(filename, mode='r'): + return open(filename, mode=mode) + +def getexception(): + return sys.exc_info()[1] + +def asbytes_nested(x): + if hasattr(x, '__iter__') and not isinstance(x, (bytes, unicode)): + return [asbytes_nested(y) for y in x] + else: + return asbytes(x) + +def asunicode_nested(x): + if hasattr(x, '__iter__') and not isinstance(x, (bytes, unicode)): + return [asunicode_nested(y) for y in x] + else: + return asunicode(x) diff --git a/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/pandas_py3k.py b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/pandas_py3k.py new file mode 100644 index 0000000..2a8eb5a --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/pandas_py3k.py @@ -0,0 +1,702 @@ +""" +compat +====== + +Cross-compatible functions for Python 2 and 3. + +Key items to import for 2/3 compatible code: +* iterators: range(), map(), zip(), filter(), reduce() +* lists: lrange(), lmap(), lzip(), lfilter() +* unicode: u() [u"" is a syntax error in Python 3.0-3.2] +* longs: long (int in Python 3) +* callable +* iterable method compatibility: iteritems, iterkeys, itervalues + * Uses the original method if available, otherwise uses items, keys, values. +* types: + * text_type: unicode in Python 2, str in Python 3 + * binary_type: str in Python 2, bytes in Python 3 + * string_types: basestring in Python 2, str in Python 3 +* bind_method: binds functions to classes + +Python 2.6 compatibility: +* OrderedDict +* Counter + +Other items: +* OrderedDefaultDict +""" +# pylint disable=W0611 +import functools +import itertools +from distutils.version import LooseVersion +from itertools import product +import sys +import types + +PY3 = (sys.version_info[0] >= 3) +# import iterator versions of these functions + +try: + import __builtin__ as builtins + # not writeable when instantiated with string, doesn't handle unicode well + from cStringIO import StringIO as cStringIO + # always writeable + from StringIO import StringIO + BytesIO = StringIO + import cPickle +except ImportError: + import builtins + from io import StringIO, BytesIO + cStringIO = StringIO + import pickle as cPickle + + +if PY3: + def isidentifier(s): + return s.isidentifier() + + def str_to_bytes(s, encoding='ascii'): + return s.encode(encoding) + + def bytes_to_str(b, encoding='utf-8'): + return b.decode(encoding) + + # have to explicitly put builtins into the namespace + range = range + map = map + zip = zip + filter = filter + reduce = functools.reduce + long = int + unichr = chr + + # list-producing versions of the major Python iterating functions + def lrange(*args, **kwargs): + return list(range(*args, **kwargs)) + + def lzip(*args, **kwargs): + return list(zip(*args, **kwargs)) + + def lmap(*args, **kwargs): + return list(map(*args, **kwargs)) + + def lfilter(*args, **kwargs): + return list(filter(*args, **kwargs)) +else: + # Python 2 + import re + _name_re = re.compile(r"[a-zA-Z_][a-zA-Z0-9_]*$") + + def isidentifier(s, dotted=False): + return bool(_name_re.match(s)) + + def str_to_bytes(s, encoding='ascii'): + return s + + def bytes_to_str(b, encoding='ascii'): + return b + + range = xrange + zip = itertools.izip + filter = itertools.ifilter + map = itertools.imap + reduce = reduce + long = long + unichr = unichr + + # Python 2-builtin ranges produce lists + lrange = builtins.range + lzip = builtins.zip + lmap = builtins.map + lfilter = builtins.filter + + +def iteritems(obj, **kwargs): + """replacement for six's iteritems for Python2/3 compat + uses 'iteritems' if available and otherwise uses 'items'. + + Passes kwargs to method.""" + func = getattr(obj, "iteritems", None) + if not func: + func = obj.items + return func(**kwargs) + + +def iterkeys(obj, **kwargs): + func = getattr(obj, "iterkeys", None) + if not func: + func = obj.keys + return func(**kwargs) + + +def itervalues(obj, **kwargs): + func = getattr(obj, "itervalues", None) + if not func: + func = obj.values + return func(**kwargs) + + +def bind_method(cls, name, func): + """Bind a method to class, python 2 and python 3 compatible. + + Parameters + ---------- + + cls : type + class to receive bound method + name : basestring + name of method on class instance + func : function + function to be bound as method + + + Returns + ------- + None + """ + # only python 2 has bound/unbound method issue + if not PY3: + setattr(cls, name, types.MethodType(func, None, cls)) + else: + setattr(cls, name, func) +# ---------------------------------------------------------------------------- +# functions largely based / taken from the six module + +# Much of the code in this module comes from Benjamin Peterson's six library. +# The license for this library can be found in LICENSES/SIX and the code can be +# found at https://bitbucket.org/gutworth/six + +if PY3: + string_types = str, + integer_types = int, + class_types = type, + text_type = str + binary_type = bytes + + def u(s): + return s +else: + string_types = basestring, + integer_types = (int, long) + class_types = (type, types.ClassType) + text_type = unicode + binary_type = str + + def u(s): + return unicode(s, "unicode_escape") + + +string_and_binary_types = string_types + (binary_type,) + + +try: + # callable reintroduced in later versions of Python + callable = callable +except NameError: + def callable(obj): + return any("__call__" in klass.__dict__ for klass in type(obj).__mro__) + +# ---------------------------------------------------------------------------- +# Python 2.6 compatibility shims +# + +# OrderedDict Shim from Raymond Hettinger, python core dev +# http://code.activestate.com/recipes/576693-ordered-dictionary-for-py24/ +# here to support versions before 2.6 +if not PY3: + # don't need this except in 2.6 + try: + from thread import get_ident as _get_ident + except ImportError: + from dummy_thread import get_ident as _get_ident + +try: + from _abcoll import KeysView, ValuesView, ItemsView +except ImportError: + pass + + +class _OrderedDict(dict): + + 'Dictionary that remembers insertion order' + # An inherited dict maps keys to values. + # The inherited dict provides __getitem__, __len__, __contains__, and get. + # The remaining methods are order-aware. + # Big-O running times for all methods are the same as for regular + # dictionaries. + + # The internal self.__map dictionary maps keys to links in a doubly linked + # list. The circular doubly linked list starts and ends with a sentinel + # element. The sentinel element never gets deleted (this simplifies the + # algorithm). Each link is stored as a list of length three: [PREV, NEXT, + # KEY]. + + def __init__(self, *args, **kwds): + '''Initialize an ordered dictionary. Signature is the same as for + regular dictionaries, but keyword arguments are not recommended + because their insertion order is arbitrary. + + ''' + if len(args) > 1: + raise TypeError('expected at most 1 arguments, got %d' % len(args)) + try: + self.__root + except AttributeError: + self.__root = root = [] # sentinel node + root[:] = [root, root, None] + self.__map = {} + self.__update(*args, **kwds) + + def __setitem__(self, key, value, dict_setitem=dict.__setitem__): + 'od.__setitem__(i, y) <==> od[i]=y' + # Setting a new item creates a new link which goes at the end of the + # linked list, and the inherited dictionary is updated with the new + # key/value pair. + if key not in self: + root = self.__root + last = root[0] + last[1] = root[0] = self.__map[key] = [last, root, key] + dict_setitem(self, key, value) + + def __delitem__(self, key, dict_delitem=dict.__delitem__): + 'od.__delitem__(y) <==> del od[y]' + # Deleting an existing item uses self.__map to find the link which is + # then removed by updating the links in the predecessor and successor + # nodes. + dict_delitem(self, key) + link_prev, link_next, key = self.__map.pop(key) + link_prev[1] = link_next + link_next[0] = link_prev + + def __iter__(self): + 'od.__iter__() <==> iter(od)' + root = self.__root + curr = root[1] + while curr is not root: + yield curr[2] + curr = curr[1] + + def __reversed__(self): + 'od.__reversed__() <==> reversed(od)' + root = self.__root + curr = root[0] + while curr is not root: + yield curr[2] + curr = curr[0] + + def clear(self): + 'od.clear() -> None. Remove all items from od.' + try: + for node in itervalues(self.__map): + del node[:] + root = self.__root + root[:] = [root, root, None] + self.__map.clear() + except AttributeError: + pass + dict.clear(self) + + def popitem(self, last=True): + '''od.popitem() -> (k, v), return and remove a (key, value) pair. + Pairs are returned in LIFO order if last is true or FIFO order if + false. + ''' + if not self: + raise KeyError('dictionary is empty') + root = self.__root + if last: + link = root[0] + link_prev = link[0] + link_prev[1] = root + root[0] = link_prev + else: + link = root[1] + link_next = link[1] + root[1] = link_next + link_next[0] = root + key = link[2] + del self.__map[key] + value = dict.pop(self, key) + return key, value + + # -- the following methods do not depend on the internal structure -- + + def keys(self): + 'od.keys() -> list of keys in od' + return list(self) + + def values(self): + 'od.values() -> list of values in od' + return [self[key] for key in self] + + def items(self): + 'od.items() -> list of (key, value) pairs in od' + return [(key, self[key]) for key in self] + + def iterkeys(self): + 'od.iterkeys() -> an iterator over the keys in od' + return iter(self) + + def itervalues(self): + 'od.itervalues -> an iterator over the values in od' + for k in self: + yield self[k] + + def iteritems(self): + 'od.iteritems -> an iterator over the (key, value) items in od' + for k in self: + yield (k, self[k]) + + def update(*args, **kwds): + '''od.update(E, **F) -> None. Update od from dict/iterable E and F. + + If E is a dict instance, does: for k in E: od[k] = E[k] + If E has a .keys() method, does: for k in E.keys(): od[k] = E[k] + Or if E is an iterable of items, does:for k, v in E: od[k] = v + In either case, this is followed by: for k, v in F.items(): od[k] = v + ''' + if len(args) > 2: + raise TypeError('update() takes at most 2 positional ' + 'arguments (%d given)' % (len(args),)) + elif not args: + raise TypeError('update() takes at least 1 argument (0 given)') + self = args[0] + # Make progressively weaker assumptions about "other" + other = () + if len(args) == 2: + other = args[1] + if isinstance(other, dict): + for key in other: + self[key] = other[key] + elif hasattr(other, 'keys'): + for key in other.keys(): + self[key] = other[key] + else: + for key, value in other: + self[key] = value + for key, value in kwds.items(): + self[key] = value + # let subclasses override update without breaking __init__ + __update = update + + __marker = object() + + def pop(self, key, default=__marker): + '''od.pop(k[,d]) -> v, remove specified key and return the\ + corresponding value. If key is not found, d is returned if given, + otherwise KeyError is raised. + ''' + if key in self: + result = self[key] + del self[key] + return result + if default is self.__marker: + raise KeyError(key) + return default + + def setdefault(self, key, default=None): + 'od.setdefault(k[,d]) -> od.get(k,d), also set od[k]=d if k not in od' + if key in self: + return self[key] + self[key] = default + return default + + def __repr__(self, _repr_running={}): + 'od.__repr__() <==> repr(od)' + call_key = id(self), _get_ident() + if call_key in _repr_running: + return '...' + _repr_running[call_key] = 1 + try: + if not self: + return '%s()' % (self.__class__.__name__,) + return '%s(%r)' % (self.__class__.__name__, list(self.items())) + finally: + del _repr_running[call_key] + + def __reduce__(self): + 'Return state information for pickling' + items = [[k, self[k]] for k in self] + inst_dict = vars(self).copy() + for k in vars(OrderedDict()): + inst_dict.pop(k, None) + if inst_dict: + return (self.__class__, (items,), inst_dict) + return self.__class__, (items,) + + def copy(self): + 'od.copy() -> a shallow copy of od' + return self.__class__(self) + + @classmethod + def fromkeys(cls, iterable, value=None): + '''OD.fromkeys(S[, v]) -> New ordered dictionary with keys from S and + values equal to v (which defaults to None). + ''' + d = cls() + for key in iterable: + d[key] = value + return d + + def __eq__(self, other): + '''od.__eq__(y) <==> od==y. Comparison to another OD is + order-sensitive while comparison to a regular mapping is + order-insensitive. + ''' + if isinstance(other, OrderedDict): + return (len(self) == len(other) and + list(self.items()) == list(other.items())) + return dict.__eq__(self, other) + + def __ne__(self, other): + return not self == other + + # -- the following methods are only used in Python 2.7 -- + + def viewkeys(self): + "od.viewkeys() -> a set-like object providing a view on od's keys" + return KeysView(self) + + def viewvalues(self): + "od.viewvalues() -> an object providing a view on od's values" + return ValuesView(self) + + def viewitems(self): + "od.viewitems() -> a set-like object providing a view on od's items" + return ItemsView(self) + + +# {{{ http://code.activestate.com/recipes/576611/ (r11) + +try: + from operator import itemgetter + from heapq import nlargest +except ImportError: + pass + + +class _Counter(dict): + + '''Dict subclass for counting hashable objects. Sometimes called a bag + or multiset. Elements are stored as dictionary keys and their counts + are stored as dictionary values. + + >>> Counter('zyzygy') + Counter({'y': 3, 'z': 2, 'g': 1}) + + ''' + + def __init__(self, iterable=None, **kwds): + '''Create a new, empty Counter object. And if given, count elements + from an input iterable. Or, initialize the count from another mapping + of elements to their counts. + + >>> c = Counter() # a new, empty counter + >>> c = Counter('gallahad') # a new counter from an iterable + >>> c = Counter({'a': 4, 'b': 2}) # a new counter from a mapping + >>> c = Counter(a=4, b=2) # a new counter from keyword args + + ''' + self.update(iterable, **kwds) + + def __missing__(self, key): + return 0 + + def most_common(self, n=None): + '''List the n most common elements and their counts from the most + common to the least. If n is None, then list all element counts. + + >>> Counter('abracadabra').most_common(3) + [('a', 5), ('r', 2), ('b', 2)] + + ''' + if n is None: + return sorted(iteritems(self), key=itemgetter(1), reverse=True) + return nlargest(n, iteritems(self), key=itemgetter(1)) + + def elements(self): + '''Iterator over elements repeating each as many times as its count. + + >>> c = Counter('ABCABC') + >>> sorted(c.elements()) + ['A', 'A', 'B', 'B', 'C', 'C'] + + If an element's count has been set to zero or is a negative number, + elements() will ignore it. + + ''' + for elem, count in iteritems(self): + for _ in range(count): + yield elem + + # Override dict methods where the meaning changes for Counter objects. + + @classmethod + def fromkeys(cls, iterable, v=None): + raise NotImplementedError( + 'Counter.fromkeys() is undefined. Use Counter(iterable) instead.') + + def update(self, iterable=None, **kwds): + '''Like dict.update() but add counts instead of replacing them. + + Source can be an iterable, a dictionary, or another Counter instance. + + >>> c = Counter('which') + >>> c.update('witch') # add elements from another iterable + >>> d = Counter('watch') + >>> c.update(d) # add elements from another counter + >>> c['h'] # four 'h' in which, witch, and watch + 4 + + ''' + if iterable is not None: + if hasattr(iterable, 'iteritems'): + if self: + self_get = self.get + for elem, count in iteritems(iterable): + self[elem] = self_get(elem, 0) + count + else: + dict.update( + self, iterable) # fast path when counter is empty + else: + self_get = self.get + for elem in iterable: + self[elem] = self_get(elem, 0) + 1 + if kwds: + self.update(kwds) + + def copy(self): + 'Like dict.copy() but returns a Counter instance instead of a dict.' + return Counter(self) + + def __delitem__(self, elem): + '''Like dict.__delitem__() but does not raise KeyError for missing + values.''' + if elem in self: + dict.__delitem__(self, elem) + + def __repr__(self): + if not self: + return '%s()' % self.__class__.__name__ + items = ', '.join(map('%r: %r'.__mod__, self.most_common())) + return '%s({%s})' % (self.__class__.__name__, items) + + # Multiset-style mathematical operations discussed in: + # Knuth TAOCP Volume II section 4.6.3 exercise 19 + # and at http://en.wikipedia.org/wiki/Multiset + # + # Outputs guaranteed to only include positive counts. + # + # To strip negative and zero counts, add-in an empty counter: + # c += Counter() + + def __add__(self, other): + '''Add counts from two counters. + + >>> Counter('abbb') + Counter('bcc') + Counter({'b': 4, 'c': 2, 'a': 1}) + + + ''' + if not isinstance(other, Counter): + return NotImplemented + result = Counter() + for elem in set(self) | set(other): + newcount = self[elem] + other[elem] + if newcount > 0: + result[elem] = newcount + return result + + def __sub__(self, other): + ''' Subtract count, but keep only results with positive counts. + + >>> Counter('abbbc') - Counter('bccd') + Counter({'b': 2, 'a': 1}) + + ''' + if not isinstance(other, Counter): + return NotImplemented + result = Counter() + for elem in set(self) | set(other): + newcount = self[elem] - other[elem] + if newcount > 0: + result[elem] = newcount + return result + + def __or__(self, other): + '''Union is the maximum of value in either of the input counters. + + >>> Counter('abbb') | Counter('bcc') + Counter({'b': 3, 'c': 2, 'a': 1}) + + ''' + if not isinstance(other, Counter): + return NotImplemented + _max = max + result = Counter() + for elem in set(self) | set(other): + newcount = _max(self[elem], other[elem]) + if newcount > 0: + result[elem] = newcount + return result + + def __and__(self, other): + ''' Intersection is the minimum of corresponding counts. + + >>> Counter('abbb') & Counter('bcc') + Counter({'b': 1}) + + ''' + if not isinstance(other, Counter): + return NotImplemented + _min = min + result = Counter() + if len(self) < len(other): + self, other = other, self + for elem in filter(self.__contains__, other): + newcount = _min(self[elem], other[elem]) + if newcount > 0: + result[elem] = newcount + return result + +if sys.version_info[:2] < (2, 7): + OrderedDict = _OrderedDict + Counter = _Counter +else: + from collections import OrderedDict, Counter + +# http://stackoverflow.com/questions/4126348 +# Thanks to @martineau at SO + +from dateutil import parser as _date_parser +import dateutil +if LooseVersion(dateutil.__version__) < '2.0': + @functools.wraps(_date_parser.parse) + def parse_date(timestr, *args, **kwargs): + timestr = bytes(timestr) + return _date_parser.parse(timestr, *args, **kwargs) +else: + parse_date = _date_parser.parse + +class OrderedDefaultdict(OrderedDict): + + def __init__(self, *args, **kwargs): + newdefault = None + newargs = () + if args: + newdefault = args[0] + if not (newdefault is None or callable(newdefault)): + raise TypeError('first argument must be callable or None') + newargs = args[1:] + self.default_factory = newdefault + super(self.__class__, self).__init__(*newargs, **kwargs) + + def __missing__(self, key): + if self.default_factory is None: + raise KeyError(key) + self[key] = value = self.default_factory() + return value + + def __reduce__(self): # optional, for pickle support + args = self.default_factory if self.default_factory else tuple() + return type(self), args, None, None, list(self.items()) diff --git a/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/pycrypto_py3compat.py b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/pycrypto_py3compat.py new file mode 100644 index 0000000..34e5224 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/pycrypto_py3compat.py @@ -0,0 +1,107 @@ +# -*- coding: utf-8 -*- +# +# Util/py3compat.py : Compatibility code for handling Py3k / Python 2.x +# +# Written in 2010 by Thorsten Behrens +# +# =================================================================== +# The contents of this file are dedicated to the public domain. To +# the extent that dedication to the public domain is not available, +# everyone is granted a worldwide, perpetual, royalty-free, +# non-exclusive license to exercise all rights associated with the +# contents of this file for any purpose whatsoever. +# No rights are reserved. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS +# BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN +# ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. +# =================================================================== + +"""Compatibility code for handling string/bytes changes from Python 2.x to Py3k + +In Python 2.x, strings (of type ''str'') contain binary data, including encoded +Unicode text (e.g. UTF-8). The separate type ''unicode'' holds Unicode text. +Unicode literals are specified via the u'...' prefix. Indexing or slicing +either type always produces a string of the same type as the original. +Data read from a file is always of '''str'' type. + +In Python 3.x, strings (type ''str'') may only contain Unicode text. The u'...' +prefix and the ''unicode'' type are now redundant. A new type (called +''bytes'') has to be used for binary data (including any particular +''encoding'' of a string). The b'...' prefix allows one to specify a binary +literal. Indexing or slicing a string produces another string. Slicing a byte +string produces another byte string, but the indexing operation produces an +integer. Data read from a file is of '''str'' type if the file was opened in +text mode, or of ''bytes'' type otherwise. + +Since PyCrypto aims at supporting both Python 2.x and 3.x, the following helper +functions are used to keep the rest of the library as independent as possible +from the actual Python version. + +In general, the code should always deal with binary strings, and use integers +instead of 1-byte character strings. + +b(s) + Take a text string literal (with no prefix or with u'...' prefix) and + make a byte string. +bchr(c) + Take an integer and make a 1-character byte string. +bord(c) + Take the result of indexing on a byte string and make an integer. +tobytes(s) + Take a text string, a byte string, or a sequence of character taken from + a byte string and make a byte string. +""" + +__revision__ = "$Id$" + +import sys + +if sys.version_info[0] == 2: + def b(s): + return s + def bchr(s): + return chr(s) + def bstr(s): + return str(s) + def bord(s): + return ord(s) + if sys.version_info[1] == 1: + def tobytes(s): + try: + return s.encode('latin-1') + except: + return ''.join(s) + else: + def tobytes(s): + if isinstance(s, unicode): + return s.encode("latin-1") + else: + return ''.join(s) +else: + def b(s): + return s.encode("latin-1") # utf-8 would cause some side-effects we don't want + def bchr(s): + return bytes([s]) + def bstr(s): + if isinstance(s,str): + return bytes(s,"latin-1") + else: + return bytes(s) + def bord(s): + return s + def tobytes(s): + if isinstance(s,bytes): + return s + else: + if isinstance(s,str): + return s.encode("latin-1") + else: + return bytes(s) + +# vim:set ts=4 sw=4 sts=4 expandtab: diff --git a/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/statsmodels_py3k.py b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/statsmodels_py3k.py new file mode 100644 index 0000000..aab8807 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/3rd-party-py3k-compat-code/statsmodels_py3k.py @@ -0,0 +1,69 @@ +""" +Python 3 compatibility tools. + +""" + +__all__ = ['bytes', 'asbytes', 'isfileobj', 'getexception', 'strchar', + 'unicode', 'asunicode', 'asbytes_nested', 'asunicode_nested', + 'asstr', 'open_latin1'] + +import sys + +if sys.version_info[0] >= 3: + import io + bytes = bytes + unicode = str + asunicode = str + def asbytes(s): + if isinstance(s, bytes): + return s + return s.encode('latin1') + def asstr(s): + if isinstance(s, str): + return s + return s.decode('latin1') + def asstr2(s): #added JP, not in numpy version + if isinstance(s, str): + return s + elif isinstance(s, bytes): + return s.decode('latin1') + else: + return str(s) + def isfileobj(f): + return isinstance(f, io.FileIO) + def open_latin1(filename, mode='r'): + return open(filename, mode=mode, encoding='iso-8859-1') + strchar = 'U' + from io import BytesIO, StringIO #statsmodels +else: + bytes = str + unicode = unicode + asbytes = str + asstr = str + asstr2 = str + strchar = 'S' + def isfileobj(f): + return isinstance(f, file) + def asunicode(s): + if isinstance(s, unicode): + return s + return s.decode('ascii') + def open_latin1(filename, mode='r'): + return open(filename, mode=mode) + from StringIO import StringIO + BytesIO = StringIO + +def getexception(): + return sys.exc_info()[1] + +def asbytes_nested(x): + if hasattr(x, '__iter__') and not isinstance(x, (bytes, unicode)): + return [asbytes_nested(y) for y in x] + else: + return asbytes(x) + +def asunicode_nested(x): + if hasattr(x, '__iter__') and not isinstance(x, (bytes, unicode)): + return [asunicode_nested(y) for y in x] + else: + return asunicode(x) diff --git a/Python/Dependencies/future-0.18.2/docs/Makefile b/Python/Dependencies/future-0.18.2/docs/Makefile new file mode 100644 index 0000000..3607cbd --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/Makefile @@ -0,0 +1,153 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Python-Future.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Python-Future.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Python-Future" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Python-Future" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/Python/Dependencies/future-0.18.2/docs/_static/python-future-icon-32.ico b/Python/Dependencies/future-0.18.2/docs/_static/python-future-icon-32.ico Binary files differnew file mode 100644 index 0000000..e3f2cf7 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_static/python-future-icon-32.ico diff --git a/Python/Dependencies/future-0.18.2/docs/_static/python-future-icon-white-32.ico b/Python/Dependencies/future-0.18.2/docs/_static/python-future-icon-white-32.ico Binary files differnew file mode 100644 index 0000000..3fa3dab --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_static/python-future-icon-white-32.ico diff --git a/Python/Dependencies/future-0.18.2/docs/_static/python-future-logo-textless-transparent.png b/Python/Dependencies/future-0.18.2/docs/_static/python-future-logo-textless-transparent.png Binary files differnew file mode 100644 index 0000000..95ba682 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_static/python-future-logo-textless-transparent.png diff --git a/Python/Dependencies/future-0.18.2/docs/_static/python-future-logo.png b/Python/Dependencies/future-0.18.2/docs/_static/python-future-logo.png Binary files differnew file mode 100644 index 0000000..c1f92a5 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_static/python-future-logo.png diff --git a/Python/Dependencies/future-0.18.2/docs/_static/python-future-logo.tiff b/Python/Dependencies/future-0.18.2/docs/_static/python-future-logo.tiff Binary files differnew file mode 100644 index 0000000..dcfba15 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_static/python-future-logo.tiff diff --git a/Python/Dependencies/future-0.18.2/docs/_templates/layout.html b/Python/Dependencies/future-0.18.2/docs/_templates/layout.html new file mode 100644 index 0000000..c979ab2 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_templates/layout.html @@ -0,0 +1,33 @@ +{# Import the theme's layout. #} +{% extends "!layout.html" %} + +{% block extrahead %} +{{ super() }} +<script type="text/javascript"> + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'UA-19344199-2']); + _gaq.push(['_trackPageview']); +</script> +{% endblock %} + +{% block footer %} +{{ super() }} +<div class="footer"> +<script type="text/javascript"> + (function() { + var ga = document.createElement('script'); + ga.src = ('https:' == document.location.protocol ? + 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + ga.setAttribute('async', 'true'); + document.documentElement.firstChild.appendChild(ga); + })(); +</script> +</div> +{% endblock %} + + +{# Import the theme's layout. #} + + +{# Include our new CSS file into existing ones. #} +{% set css_files = css_files + ['_static/my-styles.css'] %} diff --git a/Python/Dependencies/future-0.18.2/docs/_templates/navbar.html b/Python/Dependencies/future-0.18.2/docs/_templates/navbar.html new file mode 100644 index 0000000..b77fb76 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_templates/navbar.html @@ -0,0 +1,57 @@ +<a href="https://github.com/PythonCharmers/python-future"><img style="position: absolute; top: 45px; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" alt="Fork me on GitHub"></a> +<div id="navbar" class="{{ theme_navbar_class }} navbar-default {% if theme_navbar_fixed_top == 'true' -%} navbar-fixed-top{%- endif -%}"> + + <div class="container"> + + <div class="navbar-header"> + + <!-- .btn-navbar is used as the toggle for collapsed navbar content --> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse"> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + + <a class="logo"> <img height="32" width="32" src="_static/python-future-logo-textless-transparent.png" /></a> + <a class="navbar-brand" href="{{ pathto(master_doc) }}">{% if theme_navbar_title -%}{{ theme_navbar_title|e }}{%- else -%}{{ project|e }}{%- endif -%}</a> + <span class="navbar-text navbar-version pull-left"><b>{{ version|e }}</b></span> + </div> + <div class="collapse navbar-collapse nav-collapse"> + <ul class="nav navbar-nav"> + <li class="divider-vertical"></li> + {% if theme_navbar_links %} + {%- for link in theme_navbar_links %} + <li><a href="{{ pathto(*link[1:]) }}">{{ link[0] }}</a></li> + {%- endfor %} + {% endif %} + {% block navbartoc %} + {% include "globaltoc.html" %} + {% if theme_navbar_pagenav %} + {% include "navbartoc.html" %} + {% endif %} + {% endblock %} + {% if theme_navbar_sidebarrel %} + {% block sidebarrel %} + {% include "relations.html" %} + {% endblock %} + {% endif %} + {% block navbarextra %} + {% endblock %} + {% if theme_source_link_position == "nav" %} + + <li>{%- if show_source and has_source and sourcename %} + <a href="{{ pathto('_sources/' + sourcename, true)|e }}" + rel="nofollow">{{ _('Source') }}</a> + {%- endif %} + </li> + + {% endif %} + </ul> + + {% block navbarsearch %} + {% include "navbarsearchbox.html" %} + {% endblock %} + + </div> + </div> + </div> diff --git a/Python/Dependencies/future-0.18.2/docs/_templates/sidebarintro.html b/Python/Dependencies/future-0.18.2/docs/_templates/sidebarintro.html new file mode 100644 index 0000000..e443322 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_templates/sidebarintro.html @@ -0,0 +1,21 @@ +<!--<h3>Python-Future</h3> +<p>--> + <h4>Easy, clean, reliable Python 2/3 compatibility</h4> + <a href="http://python-future.org">Table of Contents</a> +<!-- +</p> +<h3>Other Formats</h3> +<p> + You can download the documentation in other formats as well: +</p> +<ul> + <li><a href="http://jinja.pocoo.org/docs/jinja-docs.pdf">as PDF</a> + <li><a href="http://jinja.pocoo.org/docs/jinja-docs.zip">as zipped HTML</a> +</ul> +--> +<!--<h3>Useful Links</h3> +<ul> + <li><a href="https://pypi.org/project/future/">on PyPI</a></li> + <li><a href="https://github.com/PythonCharmers/python-future">on GitHub</a></li> +</ul> +--> diff --git a/Python/Dependencies/future-0.18.2/docs/_templates/sidebarlogo.html b/Python/Dependencies/future-0.18.2/docs/_templates/sidebarlogo.html new file mode 100644 index 0000000..cf875c3 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_templates/sidebarlogo.html @@ -0,0 +1,3 @@ +<p class="logo"><a href="{{ pathto(master_doc) }}"> + <img class="logo" src="{{ pathto('_static/python-future-logo.png', 1) }}" width="150" alt="Logo"/> +</a></p> diff --git a/Python/Dependencies/future-0.18.2/docs/_templates/sidebartoc.html b/Python/Dependencies/future-0.18.2/docs/_templates/sidebartoc.html new file mode 100644 index 0000000..0d119af --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_templates/sidebartoc.html @@ -0,0 +1 @@ +{{ toctree(maxdepth=theme_globaltoc_depth|toint, collapse=True, includehidden=theme_globaltoc_includehidden|tobool) }} diff --git a/Python/Dependencies/future-0.18.2/docs/_themes/LICENSE b/Python/Dependencies/future-0.18.2/docs/_themes/LICENSE new file mode 100644 index 0000000..8daab7e --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_themes/LICENSE @@ -0,0 +1,37 @@ +Copyright (c) 2010 by Armin Ronacher. + +Some rights reserved. + +Redistribution and use in source and binary forms of the theme, with or +without modification, are permitted provided that the following conditions +are met: + +* Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + +* The names of the contributors may not be used to endorse or + promote products derived from this software without specific + prior written permission. + +We kindly ask you to only use these themes in an unmodified manner just +for Flask and Flask-related products, not for unrelated projects. If you +like the visual style and want to use it for your own projects, please +consider making some larger changes to the themes (such as changing +font faces, sizes, colors or margins). + +THIS THEME IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS THEME, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. diff --git a/Python/Dependencies/future-0.18.2/docs/_themes/README b/Python/Dependencies/future-0.18.2/docs/_themes/README new file mode 100644 index 0000000..b3292bd --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_themes/README @@ -0,0 +1,31 @@ +Flask Sphinx Styles +=================== + +This repository contains sphinx styles for Flask and Flask related +projects. To use this style in your Sphinx documentation, follow +this guide: + +1. put this folder as _themes into your docs folder. Alternatively + you can also use git submodules to check out the contents there. +2. add this to your conf.py: + + sys.path.append(os.path.abspath('_themes')) + html_theme_path = ['_themes'] + html_theme = 'flask' + +The following themes exist: + +- 'flask' - the standard flask documentation theme for large + projects +- 'flask_small' - small one-page theme. Intended to be used by + very small addon libraries for flask. + +The following options exist for the flask_small theme: + + [options] + index_logo = '' filename of a picture in _static + to be used as replacement for the + h1 in the index.rst file. + index_logo_height = 120px height of the index logo + github_fork = '' repository name on github for the + "fork me" badge diff --git a/Python/Dependencies/future-0.18.2/docs/_themes/future/layout.html b/Python/Dependencies/future-0.18.2/docs/_themes/future/layout.html new file mode 100644 index 0000000..b5b16d7 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_themes/future/layout.html @@ -0,0 +1,8 @@ +{%- extends "basic/layout.html" %} +{%- block relbar2 %}{% endblock %} +{%- block footer %} + <div class="footer"> + © Copyright {{ copyright }}. + Docs created using <a href="http://sphinx.pocoo.org/">Sphinx</a>. + </div> +{%- endblock %} diff --git a/Python/Dependencies/future-0.18.2/docs/_themes/future/relations.html b/Python/Dependencies/future-0.18.2/docs/_themes/future/relations.html new file mode 100644 index 0000000..3bbcde8 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_themes/future/relations.html @@ -0,0 +1,19 @@ +<h3>Related Topics</h3> +<ul> + <li><a href="{{ pathto(master_doc) }}">Documentation overview</a><ul> + {%- for parent in parents %} + <li><a href="{{ parent.link|e }}">{{ parent.title }}</a><ul> + {%- endfor %} + {%- if prev %} + <li>Previous: <a href="{{ prev.link|e }}" title="{{ _('previous chapter') + }}">{{ prev.title }}</a></li> + {%- endif %} + {%- if next %} + <li>Next: <a href="{{ next.link|e }}" title="{{ _('next chapter') + }}">{{ next.title }}</a></li> + {%- endif %} + {%- for parent in parents %} + </ul></li> + {%- endfor %} + </ul></li> +</ul> diff --git a/Python/Dependencies/future-0.18.2/docs/_themes/future/static/future.css_t b/Python/Dependencies/future-0.18.2/docs/_themes/future/static/future.css_t new file mode 100644 index 0000000..593da46 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_themes/future/static/future.css_t @@ -0,0 +1,398 @@ +/* + * future.css_t + * ~~~~~~~~~~~ + * + * Based on jinja.css_t. + * + * :copyright: Copyright 2011 by Armin Ronacher. + * :license: Flask Design License, see LICENSE for details. + */ + +@import url(http://fonts.googleapis.com/css?family=Oxygen); + +{% set page_width = '940px' %} +{% set sidebar_width = '220px' %} +{% set font_family = 'Geneva, sans serif' %} +{% set header_font_family = 'Oxygen, ' ~ font_family %} + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: {{ font_family }}; + font-size: 17px; + background-color: white; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + width: {{ page_width }}; + margin: 30px auto 0 auto; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 {{ sidebar_width }}; +} + +div.sphinxsidebar { + width: {{ sidebar_width }}; +} + +hr { + border: 1px solid #B1B4B6; +} + +div.body { + background-color: #ffffff; + color: #3E4349; + padding: 0 30px 0 30px; +} + +img.floatingflask { + padding: 0 0 10px 10px; + float: right; +} + +div.footer { + width: {{ page_width }}; + margin: 20px auto 30px auto; + font-size: 14px; + color: #888; + text-align: right; +} + +div.footer a { + color: #888; +} + +div.related { + display: none; +} + +div.sphinxsidebar a { + color: #444; + text-decoration: none; + border-bottom: 1px dotted #999; +} + +div.sphinxsidebar a:hover { + border-bottom: 1px solid #999; +} + +div.sphinxsidebar { + font-size: 15px; + line-height: 1.5; +} + +div.sphinxsidebarwrapper { + padding: 18px 10px; +} + +div.sphinxsidebarwrapper p.logo { + padding: 0 0 20px 0; + margin: 0; + text-align: center; +} + +div.sphinxsidebar h3, +div.sphinxsidebar h4 { + font-family: {{ font_family }}; + color: #444; + font-size: 24px; + font-weight: normal; + margin: 0 0 5px 0; + padding: 0; +} + +div.sphinxsidebar h4 { + font-size: 20px; +} + +div.sphinxsidebar h3 a { + color: #444; +} + +div.sphinxsidebar p.logo a, +div.sphinxsidebar h3 a, +div.sphinxsidebar p.logo a:hover, +div.sphinxsidebar h3 a:hover { + border: none; +} + +div.sphinxsidebar p { + color: #555; + margin: 10px 0; +} + +div.sphinxsidebar ul { + margin: 10px 0; + padding: 0; + color: #000; +} + +div.sphinxsidebar input { + border: 1px solid #ccc; + font-family: {{ font_family }}; + font-size: 14px; +} + +div.sphinxsidebar form.search input[name="q"] { + width: 130px; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: #aa0000; + text-decoration: underline; +} + +a:hover { + color: #dd0000; + text-decoration: underline; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: {{ header_font_family }}; + font-weight: normal; + margin: 30px 0px 10px 0px; + padding: 0; + color: black; +} + +div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; } +div.body h2 { font-size: 180%; } +div.body h3 { font-size: 150%; } +div.body h4 { font-size: 130%; } +div.body h5 { font-size: 100%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #ddd; + padding: 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + color: #444; + background: #eaeaea; +} + +div.body p, div.body dd, div.body li { + line-height: 1.4em; +} + +div.admonition { + background: #fafafa; + margin: 20px -30px; + padding: 10px 30px; + border-top: 1px solid #ccc; + border-bottom: 1px solid #ccc; +} + +div.admonition tt.xref, div.admonition a tt { + border-bottom: 1px solid #fafafa; +} + +dd div.admonition { + margin-left: -60px; + padding-left: 60px; +} + +div.admonition p.admonition-title { + font-family: {{ font_family }}; + font-weight: normal; + font-size: 24px; + margin: 0 0 10px 0; + padding: 0; + line-height: 1; +} + +div.admonition p.last { + margin-bottom: 0; +} + +div.highlight { + background-color: white; +} + +dt:target, .highlight { + background: #FAF3E8; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre, tt { + font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; + font-size: 0.85em; +} + +img.screenshot { +} + +tt.descname, tt.descclassname { + font-size: 0.95em; +} + +tt.descname { + padding-right: 0.08em; +} + +img.screenshot { + -moz-box-shadow: 2px 2px 4px #eee; + -webkit-box-shadow: 2px 2px 4px #eee; + box-shadow: 2px 2px 4px #eee; +} + +table.docutils { + border: 1px solid #888; + -moz-box-shadow: 2px 2px 4px #eee; + -webkit-box-shadow: 2px 2px 4px #eee; + box-shadow: 2px 2px 4px #eee; +} + +table.docutils td, table.docutils th { + border: 1px solid #888; + padding: 0.25em 0.7em; +} + +table.field-list, table.footnote { + border: none; + -moz-box-shadow: none; + -webkit-box-shadow: none; + box-shadow: none; +} + +table.footnote { + margin: 15px 0; + width: 100%; + border: 1px solid #eee; + background: #fdfdfd; + font-size: 0.9em; +} + +table.footnote + table.footnote { + margin-top: -15px; + border-top: none; +} + +table.field-list th { + padding: 0 0.8em 0 0; +} + +table.field-list td { + padding: 0; +} + +table.footnote td.label { + width: 0px; + padding: 0.3em 0 0.3em 0.5em; +} + +table.footnote td { + padding: 0.3em 0.5em; +} + +dl { + margin: 0; + padding: 0; +} + +dl dd { + margin-left: 30px; +} + +blockquote { + margin: 0 0 0 30px; + padding: 0; +} + +ul, ol { + margin: 10px 0 10px 30px; + padding: 0; +} + +pre { + background: #eee; + padding: 7px 30px; + margin: 15px -30px; + line-height: 1.3em; +} + +dl pre, blockquote pre, li pre { + margin-left: -60px; + padding-left: 60px; +} + +dl dl pre { + margin-left: -90px; + padding-left: 90px; +} + +tt { + background-color: #E8EFF0; + color: #222; + /* padding: 1px 2px; */ +} + +tt.xref, a tt { + background-color: #E8EFF0; + border-bottom: 1px solid white; +} + +a.reference { + text-decoration: none; + border-bottom: 1px dotted #bb0000; +} + +a.reference:hover { + border-bottom: 1px solid #dd0000; +} + +a.footnote-reference { + text-decoration: none; + font-size: 0.7em; + vertical-align: top; + border-bottom: 1px dotted #bb0000; +} + +a.footnote-reference:hover { + border-bottom: 1px solid #dd0000; +} + +a:hover tt { + background: #EEE; +} diff --git a/Python/Dependencies/future-0.18.2/docs/_themes/future/theme.conf b/Python/Dependencies/future-0.18.2/docs/_themes/future/theme.conf new file mode 100644 index 0000000..7a4d324 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/_themes/future/theme.conf @@ -0,0 +1,3 @@ +[theme] +inherit = basic +stylesheet = future.css diff --git a/Python/Dependencies/future-0.18.2/docs/automatic_conversion.rst b/Python/Dependencies/future-0.18.2/docs/automatic_conversion.rst new file mode 100644 index 0000000..5c718da --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/automatic_conversion.rst @@ -0,0 +1,29 @@ +.. _automatic-conversion: + +Automatic conversion to Py2/3 +============================= + +The ``future`` source tree includes scripts called ``futurize`` and +``pasteurize`` to aid in making Python 2 code or Python 3 code compatible with +both platforms (Py2/3) using the :mod:`future` module. These are based on +``lib2to3`` and use fixers from ``2to3``, ``3to2``, and ``python-modernize``. + +``futurize`` passes Python 2 code through all the appropriate fixers to turn it +into valid Python 3 code, and then adds ``__future__`` and ``future`` package +imports. + +For conversions from Python 3 code to Py2/3, use the ``pasteurize`` script +instead. This converts Py3-only constructs (e.g. new metaclass syntax) and adds +``__future__`` and ``future`` imports to the top of each module. + +In both cases, the result should be relatively clean Py3-style code that runs +mostly unchanged on both Python 2 and Python 3. + + +.. include:: futurize.rst + +.. include:: futurize_cheatsheet.rst + +.. include:: pasteurize.rst + +.. include:: conversion_limitations.rst diff --git a/Python/Dependencies/future-0.18.2/docs/bind_method.rst b/Python/Dependencies/future-0.18.2/docs/bind_method.rst new file mode 100644 index 0000000..d737384 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/bind_method.rst @@ -0,0 +1,29 @@ +.. _bind-method: + +Binding a method to a class +--------------------------- + +Python 2 draws a distinction between bound and unbound methods, whereas +in Python 3 this distinction is gone: unbound methods have been removed +from the language. To bind a method to a class compatibly across Python +3 and Python 2, you can use the :func:`bind_method` helper function:: + + from future.utils import bind_method + + class Greeter(object): + pass + + def greet(self, message): + print(message) + + bind_method(Greeter, 'greet', greet) + + g = Greeter() + g.greet('Hi!') + + +On Python 3, calling ``bind_method(cls, name, func)`` is equivalent to +calling ``setattr(cls, name, func)``. On Python 2 it is equivalent to:: + + import types + setattr(cls, name, types.MethodType(func, None, cls)) diff --git a/Python/Dependencies/future-0.18.2/docs/bytes_object.rst b/Python/Dependencies/future-0.18.2/docs/bytes_object.rst new file mode 100644 index 0000000..110280a --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/bytes_object.rst @@ -0,0 +1,80 @@ +.. _bytes-object: + +bytes +----- + +Handling ``bytes`` consistently and correctly has traditionally been one +of the most difficult tasks in writing a Py2/3 compatible codebase. This +is because the Python 2 :class:`bytes` object is simply an alias for +Python 2's :class:`str`, rather than a true implementation of the Python +3 :class:`bytes` object, which is substantially different. + +:mod:`future` contains a backport of the :mod:`bytes` object from Python 3 +which passes most of the Python 3 tests for :mod:`bytes`. (See +``tests/test_future/test_bytes.py`` in the source tree.) You can use it as +follows:: + + >>> from builtins import bytes + >>> b = bytes(b'ABCD') + +On Py3, this is simply the builtin :class:`bytes` object. On Py2, this +object is a subclass of Python 2's :class:`str` that enforces the same +strict separation of unicode strings and byte strings as Python 3's +:class:`bytes` object:: + + >>> b + u'EFGH' # TypeError + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + TypeError: argument can't be unicode string + + >>> bytes(b',').join([u'Fred', u'Bill']) + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + TypeError: sequence item 0: expected bytes, found unicode string + + >>> b == u'ABCD' + False + + >>> b < u'abc' + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + TypeError: unorderable types: bytes() and <type 'unicode'> + + +In most other ways, these :class:`bytes` objects have identical +behaviours to Python 3's :class:`bytes`:: + + b = bytes(b'ABCD') + assert list(b) == [65, 66, 67, 68] + assert repr(b) == "b'ABCD'" + assert b.split(b'B') == [b'A', b'CD'] + +Currently the easiest way to ensure identical behaviour of byte-strings +in a Py2/3 codebase is to wrap all byte-string literals ``b'...'`` in a +:func:`~bytes` call as follows:: + + from builtins import bytes + + # ... + + b = bytes(b'This is my bytestring') + + # ... + +This is not perfect, but it is superior to manually debugging and fixing +code incompatibilities caused by the many differences between Py3 bytes +and Py2 strings. + + +The :class:`bytes` type from :mod:`builtins` also provides support for the +``surrogateescape`` error handler on Python 2.x. Here is an example that works +identically on Python 2.x and 3.x:: + + >>> from builtins import bytes + >>> b = bytes(b'\xff') + >>> b.decode('utf-8', 'surrogateescape') + '\udcc3' + +This feature is in alpha. Please leave feedback `here +<https://github.com/PythonCharmers/python-future/issues>`_ about whether this +works for you. diff --git a/Python/Dependencies/future-0.18.2/docs/changelog.rst b/Python/Dependencies/future-0.18.2/docs/changelog.rst new file mode 100644 index 0000000..059ad4f --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/changelog.rst @@ -0,0 +1,1124 @@ +.. _whats-old: + +Changes in previous versions +**************************** + +Changes in the most recent major version are here: :ref:`whats-new`. + +.. _whats-new-0.14.x: + +Changes in version 0.14.3 (2014-12-15) +====================================== + +This is a bug-fix release: + +- Expose contents of ``thread`` (not ``dummy_thread``) as ``_thread`` on Py2 (Issue #124) +- Add signed support for ``newint.to_bytes()`` (Issue #128) +- Fix ``OrderedDict.clear()`` on Py2.6 (Issue #125) +- Improve ``newrange``: equality and slicing, start/stop/step properties, refactoring (Issues #129, #130) +- Minor doc updates + +Changes in version 0.14.2 (2014-11-21) +====================================== + +This is a bug-fix release: + +- Speed up importing of ``past.translation`` (Issue #117) +- ``html.escape()``: replace function with the more robust one from Py3.4 +- ``futurize``: avoid displacing encoding comments by ``__future__`` imports (Issues #97, #10, #121) +- ``futurize``: don't swallow exit code (Issue #119) +- Packaging: don't forcibly remove the old build dir in ``setup.py`` (Issue #108) +- Docs: update further docs and tests to refer to ``install_aliases()`` instead of + ``install_hooks()`` +- Docs: fix ``iteritems`` import error in cheat sheet (Issue #120) +- Tests: don't rely on presence of ``test.test_support`` on Py2 or ``test.support`` on Py3 (Issue #109) +- Tests: don't override existing ``PYTHONPATH`` for tests (PR #111) + +Changes in version 0.14.1 (2014-10-02) +====================================== + +This is a minor bug-fix release: + +- Docs: add a missing template file for building docs (Issue #108) +- Tests: fix a bug in error handling while reporting failed script runs (Issue #109) +- ``install_aliases()``: don't assume that the ``test.test_support`` module always + exists on Py2 (Issue #109) + + +Changes in version 0.14.0 (2014-10-02) +====================================== + +This is a major new release that offers a cleaner interface for most imports in +Python 2/3 compatible code. + +Instead of this interface:: + + >>> from future.builtins import str, open, range, dict + + >>> from future.standard_library import hooks + >>> with hooks(): + ... import queue + ... import configparser + ... import tkinter.dialog + ... # etc. + +You can now use the following interface for much Python 2/3 compatible code:: + + >>> # Alias for future.builtins on Py2: + >>> from builtins import str, open, range, dict + + >>> # Alias for future.moves.* on Py2: + >>> import queue + >>> import configparser + >>> import tkinter.dialog + >>> etc. + +Notice that the above code will run on Python 3 even without the presence of the +``future`` package. Of the 44 standard library modules that were refactored with +PEP 3108, 30 are supported with direct imports in this manner. (These are listed +here: :ref:`direct-imports`.) + +The other 14 standard library modules that kept the same top-level names in +Py3.x are not supported with this direct import interface on Py2. These include +the 5 modules in the Py3 ``urllib`` package. These modules are accessible through +the following interface (as well as the interfaces offered in previous versions +of ``python-future``):: + + from future.standard_library import install_aliases + install_aliases() + + from collections import UserDict, UserList, UserString + import dbm.gnu + from itertools import filterfalse, zip_longest + from subprocess import getoutput, getstatusoutput + from sys import intern + import test.support + from urllib.request import urlopen + from urllib.parse import urlparse + # etc. + from collections import Counter, OrderedDict # backported to Py2.6 + +The complete list of packages supported with this interface is here: +:ref:`list-standard-library-refactored`. + +For more information on these and other interfaces to the standard library, see +:ref:`standard-library-imports`. + +Bug fixes +--------- + +- This release expands the ``future.moves`` package to include most of the remaining + modules that were moved in the standard library reorganization (PEP 3108). + (Issue #104) + +- This release also removes the broken ``--doctests_only`` option from the ``futurize`` + and ``pasteurize`` scripts for now. (Issue #103) + +Internal cleanups +----------------- + +The project folder structure has changed. Top-level packages are now in a +``src`` folder and the tests have been moved into a project-level ``tests`` +folder. + +The following deprecated internal modules have been removed (Issue #80): + +- ``future.utils.encoding`` and ``future.utils.six``. + +Deprecations +------------ + +The following internal functions have been deprecated and will be removed in a future release: + +- ``future.standard_library.scrub_py2_sys_modules`` +- ``future.standard_library.scrub_future_sys_modules`` + + +.. _whats-new-0.13.x: + +Changes in version 0.13.1 (2014-09-23) +====================================== + +This is a bug-fix release: + +- Fix (multiple) inheritance of ``future.builtins.object`` with metaclasses (Issues #91, #96) +- Fix ``futurize``'s refactoring of ``urllib`` imports (Issue #94) +- Fix ``futurize --all-imports`` (Issue #101) +- Fix ``futurize --output-dir`` logging (Issue #102) +- Doc formatting fix (Issues #98, #100) + + +Changes in version 0.13.0 (2014-08-13) +====================================== + +This is mostly a clean-up release. It adds some small new compatibility features +and fixes several bugs. + +Deprecations +------------ + +The following unused internal modules are now deprecated. They will be removed in a +future release: + +- ``future.utils.encoding`` and ``future.utils.six``. + +(Issue #80). See `here <http://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries>`_ +for the rationale for unbundling them. + + +New features +------------ + +- Docs: Add :ref:`compatible-idioms` from Ed Schofield's PyConAU 2014 talk. +- Add ``newint.to_bytes()`` and ``newint.from_bytes()``. (Issue #85) +- Add ``future.utils.raise_from`` as an equivalent to Py3's ``raise ... from + ...`` syntax. (Issue #86) +- Add ``past.builtins.oct()`` function. +- Add backports for Python 2.6 of ``subprocess.check_output()``, + ``itertools.combinations_with_replacement()``, and ``functools.cmp_to_key()``. + +Bug fixes +--------- + +- Use a private logger instead of the global logger in + ``future.standard_library`` (Issue #82). This restores compatibility of the + standard library hooks with ``flask``. (Issue #79) +- Stage 1 of ``futurize`` no longer renames ``next`` methods to ``__next__`` + (Issue #81). It still converts ``obj.next()`` method calls to + ``next(obj)`` correctly. +- Prevent introduction of a second set of parentheses in ``print()`` calls in + some further cases. +- Fix ``isinstance`` checks for subclasses of future types. (Issue #89) +- Be explicit about encoding file contents as UTF-8 in unit tests. (Issue #63) + Useful for building RPMs and in other environments where ``LANG=C``. +- Fix for 3-argument ``pow(x, y, z)`` with ``newint`` arguments. (Thanks to @str4d.) + (Issue #87) + + +.. _whats-new-0.12.4: + +Changes in version 0.12.4 (2014-07-18) +====================================== + +- Fix upcasting behaviour of ``newint``. (Issue #76) + + +.. _whats-new-0.12.3: + +Changes in version 0.12.3 (2014-06-19) +====================================== + +- Add "official Python 3.4 support": Py3.4 is now listed among the PyPI Trove + classifiers and the tests now run successfully on Py3.4. (Issue #67) + +- Add backports of ``collections.OrderedDict`` and + ``collections.Counter`` for Python 2.6. (Issue #52) + +- Add ``--version`` option for ``futurize`` and ``pasteurize`` scripts. + (Issue #57) + +- Fix ``future.utils.ensure_new_type`` with ``long`` input. (Issue #65) + +- Remove some false alarms on checks for ambiguous fixer names with + ``futurize -f ...``. + +- Testing fixes: + - Don't hard-code Python interpreter command in tests. (Issue #62) + - Fix deprecated ``unittest`` usage in Py3. (Issue #62) + - Be explicit about encoding temporary file contents as UTF-8 for + when ``LANG=C`` (e.g., when building an RPM). (Issue #63) + - All undecorated tests are now passing again on Python 2.6, 2.7, 3.3, + and 3.4 (thanks to Elliott Sales de Andrade). + +- Docs: + - Add list of fixers used by ``futurize``. (Issue #58) + - Add list of contributors to the Credits page. + +.. _whats-new-0.12.2: + +Changes in version 0.12.2 (2014-05-25) +====================================== + +- Add ``bytes.maketrans()`` method. (Issue #51) +- Add support for Python versions between 2.7.0 and 2.7.3 (inclusive). + (Issue #53) +- Bug fix for ``newlist(newlist([1, 2, 3]))``. (Issue #50) + + +.. _whats-new-0.12.1: + +Changes in version 0.12.1 (2014-05-14) +====================================== + +- Python 2.6 support: ``future.standard_library`` now isolates the ``importlib`` + dependency to one function (``import_``) so the ``importlib`` backport may + not be needed. + +- Doc updates + + +.. _whats-new-0.12: + +Changes in version 0.12.0 (2014-05-06) +====================================== + +The major new feature in this version is improvements in the support for the +reorganized standard library (PEP 3108) and compatibility of the import +mechanism with 3rd-party modules. + +More robust standard-library import hooks +----------------------------------------- + +**Note: backwards-incompatible change:** As previously announced (see +:ref:`deprecated-auto-import-hooks`), the import hooks must now be enabled +explicitly, as follows:: + + from future import standard_library + with standard_library.hooks(): + import html.parser + import http.client + ... + +This now causes these modules to be imported from ``future.moves``, a new +package that provides wrappers over the native Python 2 standard library with +the new Python 3 organization. As a consequence, the import hooks provided in +``future.standard_library`` are now fully compatible with the `Requests library +<http://python-requests.org>`_. + +The functional interface with ``install_hooks()`` is still supported for +backwards compatibility:: + + from future import standard_library + standard_library.install_hooks(): + + import html.parser + import http.client + ... + standard_library.remove_hooks() + +Explicit installation of import hooks allows finer-grained control +over whether they are enabled for other imported modules that provide their own +Python 2/3 compatibility layer. This also improves compatibility of ``future`` +with tools like ``py2exe``. + + +``newobject`` base object defines fallback Py2-compatible special methods +------------------------------------------------------------------------- + +There is a new ``future.types.newobject`` base class (available as +``future.builtins.object``) that can streamline Py2/3 compatible code by +providing fallback Py2-compatible special methods for its subclasses. It +currently provides ``next()`` and ``__nonzero__()`` as fallback methods on Py2 +when its subclasses define the corresponding Py3-style ``__next__()`` and +``__bool__()`` methods. + +This obviates the need to add certain compatibility hacks or decorators to the +code such as the ``@implements_iterator`` decorator for classes that define a +Py3-style ``__next__`` method. + +In this example, the code defines a Py3-style iterator with a ``__next__`` +method. The ``object`` class defines a ``next`` method for Python 2 that maps +to ``__next__``:: + + from future.builtins import object + + class Upper(object): + def __init__(self, iterable): + self._iter = iter(iterable) + def __next__(self): # note the Py3 interface + return next(self._iter).upper() + def __iter__(self): + return self + + assert list(Upper('hello')) == list('HELLO') + +``newobject`` defines other Py2-compatible special methods similarly: +currently these include ``__nonzero__`` (mapped to ``__bool__``) and +``__long__`` (mapped to ``__int__``). + +Inheriting from ``newobject`` on Python 2 is safe even if your class defines +its own Python 2-style ``__nonzero__`` and ``next`` and ``__long__`` methods. +Your custom methods will simply override those on the base class. + +On Python 3, as usual, ``future.builtins.object`` simply refers to ``builtins.object``. + + +``past.builtins`` module improved +--------------------------------- + +The ``past.builtins`` module is much more compatible with the corresponding +builtins on Python 2; many more of the Py2 unit tests pass on Py3. For example, +functions like ``map()`` and ``filter()`` now behave as they do on Py2 with with +``None`` as the first argument. + +The ``past.builtins`` module has also been extended to add Py3 support for +additional Py2 constructs that are not adequately handled by ``lib2to3`` (see +Issue #37). This includes new ``execfile()`` and ``cmp()`` functions. +``futurize`` now invokes imports of these functions from ``past.builtins``. + + +``surrogateescape`` error handler +--------------------------------- + +The ``newstr`` type (``future.builtins.str``) now supports a backport of the +Py3.x ``'surrogateescape'`` error handler for preserving high-bit +characters when encoding and decoding strings with unknown encodings. + + +``newlist`` type +---------------- + +There is a new ``list`` type in ``future.builtins`` that offers ``.copy()`` and +``.clear()`` methods like the ``list`` type in Python 3. + + +``listvalues`` and ``listitems`` +-------------------------------- + +``future.utils`` now contains helper functions ``listvalues`` and +``listitems``, which provide Python 2-style list snapshotting semantics for +dictionaries in both Python 2 and Python 3. + +These came out of the discussion around Nick Coghlan's now-withdrawn PEP 469. + +There is no corresponding ``listkeys(d)`` function; use ``list(d)`` instead. + + +Tests +----- + +The number of unit tests has increased from 600 to over 800. Most of the new +tests come from Python 3.3's test suite. + + +Refactoring of ``future.standard_library.*`` -> ``future.backports`` +-------------------------------------------------------------------- + +The backported standard library modules have been moved to ``future.backports`` +to make the distinction clearer between these and the new ``future.moves`` +package. + + +Backported ``http.server`` and ``urllib`` modules +------------------------------------------------- + +Alpha versions of backports of the ``http.server`` and ``urllib`` module from +Python 3.3's standard library are now provided in ``future.backports``. + +Use them like this:: + + from future.backports.urllib.request import Request # etc. + from future.backports.http import server as http_server + +Or with this new interface:: + + from future.standard_library import import_, from_import + + Request = from_import('urllib.request', 'Request', backport=True) + http = import_('http.server', backport=True) + +.. from future.standard_library.email import message_from_bytes # etc. +.. from future.standard_library.xmlrpc import client, server + + +Internal refactoring +-------------------- + +The ``future.builtins.types`` module has been moved to ``future.types``. +Likewise, ``past.builtins.types`` has been moved to ``past.types``. The only +user-visible effect of this is to change ``repr(type(obj))`` for instances +of these types. For example:: + + >>> from future.builtins import bytes + >>> bytes(b'abc') + >>> type(b) + future.types.newbytes.newbytes + +Instead of:: + + >>> type(b) # prior to v0.12 + future.builtins.types.newbytes.newbytes + + +Bug fixes +--------- + +Many small improvements and fixes have been made across the project. Some highlights are: + +- Fixes and updates from Python 3.3.5 have been included in the backported + standard library modules. + +- Scrubbing of the ``sys.modules`` cache performed by ``remove_hooks()`` (also + called by the ``suspend_hooks`` and ``hooks`` context managers) is now more + conservative. + +.. Is this still true? +.. It now removes only modules with Py3 names (such as +.. ``urllib.parse``) and not the corresponding ``future.standard_library.*`` +.. modules (such as ``future.standard_library.urllib.parse``. + +- The ``fix_next`` and ``fix_reduce`` fixers have been moved to stage 1 of + ``futurize``. + +- ``futurize``: Shebang lines such as ``#!/usr/bin/env python`` and source code + file encoding declarations like ``# -*- coding=utf-8 -*-`` are no longer occasionally + displaced by ``from __future__ import ...`` statements. (Issue #10) + +- Improved compatibility with ``py2exe`` (`Issue #31 <https://github.com/PythonCharmers/python-future/issues/31>`_). + +- The ``future.utils.bytes_to_native_str`` function now returns a platform-native string + object and ``future.utils.native_str_to_bytes`` returns a ``newbytes`` object on Py2. + (`Issue #47 <https://github.com/PythonCharmers/python-future/issues/47>`_). + +- The backported ``http.client`` module and related modules use other new + backported modules such as ``email``. As a result they are more compliant + with the Python 3.3 equivalents. + + +.. _whats-new-0.11.4: + +Changes in version 0.11.4 (2014-05-25) +====================================== + +This release contains various small improvements and fixes: + +- This release restores Python 2.6 compatibility. (Issue #42) + +- The ``fix_absolute_import`` fixer now supports Cython ``.pyx`` modules. (Issue + #35) + +- Right-division with ``newint`` objects is fixed. (Issue #38) + +- The ``fix_dict`` fixer has been moved to stage2 of ``futurize``. + +- Calls to ``bytes(string, encoding[, errors])`` now work with ``encoding`` and + ``errors`` passed as positional arguments. Previously this only worked if + ``encoding`` and ``errors`` were passed as keyword arguments. + + +- The 0-argument ``super()`` function now works from inside static methods such + as ``__new__``. (Issue #36) + +- ``future.utils.native(d)`` calls now work for ``future.builtins.dict`` objects. + + +.. _whats-new-0.11.3: + +Changes in version 0.11.3 (2014-02-27) +====================================== + +This release has improvements in the standard library import hooks mechanism and +its compatibility with 3rd-party modules: + + +Improved compatibility with ``requests`` +---------------------------------------- + +The ``__exit__`` function of the ``hooks`` context manager and the +``remove_hooks`` function both now remove submodules of +``future.standard_library`` from the ``sys.modules`` cache. Therefore this code +is now possible on Python 2 and 3:: + + from future import standard_library + standard_library.install_hooks() + import http.client + standard_library.remove_hooks() + import requests + + data = requests.get('http://www.google.com') + + +Previously, this required manually removing ``http`` and ``http.client`` from +``sys.modules`` before importing ``requests`` on Python 2.x. (Issue #19) + +This change should also improve the compatibility of the standard library hooks +with any other module that provides its own Python 2/3 compatibility code. + +Note that the situation will improve further in version 0.12; import hooks will +require an explicit function call or the ``hooks`` context manager. + + +Conversion scripts explicitly install import hooks +-------------------------------------------------- + +The ``futurize`` and ``pasteurize`` scripts now add an explicit call to +``install_hooks()`` to install the standard library import hooks. These scripts +now add these two lines:: + + from future import standard_library + standard_library.install_hooks() + +instead of just the first one. The next major version of ``future`` (0.12) will +require the explicit call or use of the ``hooks`` context manager. This will +allow finer-grained control over whether import hooks are enabled for other +imported modules, such as ``requests``, which provide their own Python 2/3 +compatibility code. + + +``futurize`` script no longer adds ``unicode_literals`` by default +------------------------------------------------------------------ + +There is a new ``--unicode-literals`` flag to ``futurize`` that adds the +import:: + + from __future__ import unicode_literals + +to the top of each converted module. Without this flag, ``futurize`` now no +longer adds this import. (Issue #22) + +The ``pasteurize`` script for converting from Py3 to Py2/3 still adds +``unicode_literals``. (See the comments in Issue #22 for an explanation.) + + +.. _whats-new-0.11: + +Changes in version 0.11 (2014-01-28) +==================================== + +There are several major new features in version 0.11. + + +``past`` package +---------------- + +The python-future project now provides a ``past`` package in addition to the +``future`` package. Whereas ``future`` provides improved compatibility with +Python 3 code to Python 2, ``past`` provides support for using and interacting +with Python 2 code from Python 3. The structure reflects that of ``future``, +with ``past.builtins`` and ``past.utils``. There is also a new +``past.translation`` package that provides transparent translation of Python 2 +code to Python 3. (See below.) + +One purpose of ``past`` is to ease module-by-module upgrades to +codebases from Python 2. Another is to help with enabling Python 2 libraries to +support Python 3 without breaking the API they currently provide. (For example, +user code may expect these libraries to pass them Python 2's 8-bit strings, +rather than Python 3's ``bytes`` object.) A third purpose is to help migrate +projects to Python 3 even if one or more dependencies are still on Python 2. + +Currently ``past.builtins`` provides forward-ports of Python 2's ``str`` and +``dict`` objects, ``basestring``, and list-producing iterator functions. In +later releases, ``past.builtins`` will be used internally by the +``past.translation`` package to help with importing and using old Python 2 +modules in a Python 3 environment. + + +Auto-translation of Python 2 modules upon import +------------------------------------------------ + +``past`` provides an experimental ``translation`` package to help +with importing and using old Python 2 modules in a Python 3 environment. + +This is implemented using import hooks that attempt to automatically +translate Python 2 modules to Python 3 syntax and semantics upon import. Use +it like this:: + + $ pip3 install plotrique==0.2.5-7 --no-compile # to ignore SyntaxErrors + $ python3 + +Then pass in a whitelist of module name prefixes to the +``past.translation.autotranslate()`` function. Example:: + + >>> from past.translation import autotranslate + >>> autotranslate(['plotrique']) + >>> import plotrique + + +This is intended to help you migrate to Python 3 without the need for all +your code's dependencies to support Python 3 yet. It should be used as a +last resort; ideally Python 2-only dependencies should be ported +properly to a Python 2/3 compatible codebase using a tool like +``futurize`` and the changes should be pushed to the upstream project. + +For more information, see :ref:`translation`. + + +Separate ``pasteurize`` script +------------------------------ + +The functionality from ``futurize --from3`` is now in a separate script called +``pasteurize``. Use ``pasteurize`` when converting from Python 3 code to Python +2/3 compatible source. For more information, see :ref:`backwards-conversion`. + + +``pow()`` +--------- + +There is now a ``pow()`` function in ``future.builtins.misc`` that behaves like +the Python 3 ``pow()`` function when raising a negative number to a fractional +power (returning a complex number). + + +``input()`` no longer disabled globally on Py2 +---------------------------------------------- + +Previous versions of ``future`` deleted the ``input()`` function from +``__builtin__`` on Python 2 as a security measure. This was because +Python 2's ``input()`` function allows arbitrary code execution and could +present a security vulnerability on Python 2 if someone expects Python 3 +semantics but forgets to import ``input`` from ``future.builtins``. This +behaviour has been reverted, in the interests of broadening the +compatibility of ``future`` with other Python 2 modules. + +Please remember to import ``input`` from ``future.builtins`` if you use +``input()`` in a Python 2/3 compatible codebase. + + +.. _deprecated-auto-import-hooks: + +Deprecated feature: auto-installation of standard-library import hooks +---------------------------------------------------------------------- + +Previous versions of ``python-future`` installed import hooks automatically upon +importing the ``standard_library`` module from ``future``. This has been +deprecated in order to improve robustness and compatibility with modules like +``requests`` that already perform their own single-source Python 2/3 +compatibility. + +As of v0.12, importing ``future.standard_library`` +will no longer install import hooks by default. Instead, please install the +import hooks explicitly as follows:: + + from future import standard_library + standard_library.install_hooks() + +And uninstall them after your import statements using:: + + standard_library.remove_hooks() + +*Note*: This is a backward-incompatible change. + + + +Internal changes +---------------- + +The internal ``future.builtins.backports`` module has been renamed to +``future.builtins.types``. This will change the ``repr`` of ``future`` +types but not their use. + + +.. _whats-new-0.10.2: + +Changes in version 0.10.2 (2014-01-11) +====================================== + +New context-manager interface to ``standard_library.hooks`` +----------------------------------------------------------- + +There is a new context manager ``future.standard_library.hooks``. Use it like +this:: + + from future import standard_library + with standard_library.hooks(): + import queue + import configserver + from http.client import HTTPConnection + # etc. + +If not using this context manager, it is now encouraged to add an explicit call to +``standard_library.install_hooks()`` as follows:: + + from future import standard_library + standard_library.install_hooks() + + import queue + import html + import http.client + # etc. + +And to remove the hooks afterwards with:: + + standard_library.remove_hooks() + +The functions ``install_hooks()`` and ``remove_hooks()`` were previously +called ``enable_hooks()`` and ``disable_hooks()``. The old names are +deprecated (but are still available as aliases). + +As usual, this feature has no effect on Python 3. + + +.. _whats-new-0.10: + +Changes in version 0.10.0 (2013-12-02) +====================================== + +Backported ``dict`` type +------------------------ + +``future.builtins`` now provides a Python 2 ``dict`` subclass whose +:func:`keys`, :func:`values`, and :func:`items` methods produce +memory-efficient iterators. On Python 2.7, these also have the same set-like +view behaviour as on Python 3. This can streamline code needing to iterate +over large dictionaries. For example:: + + from __future__ import print_function + from future.builtins import dict, range + + squares = dict({i: i**2 for i in range(10**7)}) + + assert not isinstance(d.items(), list) + # Because items() is memory-efficient, so is this: + square_roots = dict((i_squared, i) for (i, i_squared) in squares.items()) + +For more information, see :ref:`dict-object`. + + +Utility functions ``raise_`` and ``exec_`` +------------------------------------------ + +The functions ``raise_with_traceback()`` and ``raise_()`` were +added to ``future.utils`` to offer either the Python 3.x or Python 2.x +behaviour for raising exceptions. Thanks to Joel Tratner for the +contribution of these. ``future.utils.reraise()`` is now deprecated. + +A portable ``exec_()`` function has been added to ``future.utils`` from +``six``. + + +Bugfixes +-------- +- Fixed ``newint.__divmod__`` +- Improved robustness of installing and removing import hooks in :mod:`future.standard_library` +- v0.10.1: Fixed broken ``pip install future`` on Py3 + + +.. _whats-new-0.9: + +Changes in version 0.9 (2013-11-06) +=================================== + + +``isinstance`` checks are supported natively with backported types +------------------------------------------------------------------ + +The ``isinstance`` function is no longer redefined in ``future.builtins`` +to operate with the backported ``int``, ``bytes`` and ``str``. +``isinstance`` checks with the backported types now work correctly by +default; we achieve this through overriding the ``__instancecheck__`` +method of metaclasses of the backported types. + +For more information, see :ref:`isinstance-calls`. + + +``futurize``: minimal imports by default +---------------------------------------- + +By default, the ``futurize`` script now only adds the minimal set of +imports deemed necessary. + +There is now an ``--all-imports`` option to the ``futurize`` script which +gives the previous behaviour, which is to add all ``__future__`` imports +and ``from future.builtins import *`` imports to every module. (This even +applies to an empty ``__init__.py`` file.) + + +Looser type-checking for the backported ``str`` object +------------------------------------------------------ + +Now the ``future.builtins.str`` object behaves more like the Python 2 +``unicode`` object with regard to type-checking. This is to work around some +bugs / sloppiness in the Python 2 standard library involving mixing of +byte-strings and unicode strings, such as ``os.path.join`` in ``posixpath.py``. + +``future.builtins.str`` still raises the expected ``TypeError`` exceptions from +Python 3 when attempting to mix it with ``future.builtins.bytes``. + + +``suspend_hooks()`` context manager added to ``future.standard_library`` +------------------------------------------------------------------------ + +Pychecker (as of v0.6.1)'s ``checker.py`` attempts to import the ``builtins`` +module as a way of determining whether Python 3 is running. Since this +succeeds when ``from future import standard_library`` is in effect, this +check does not work and pychecker sets the wrong value for its internal ``PY2`` +flag is set. + +To work around this, ``future`` now provides a context manager called +``suspend_hooks`` that can be used as follows:: + + from future import standard_library + ... + with standard_library.suspend_hooks(): + from pychecker.checker import Checker + + +.. _whats-new-0.8: + +Changes in version 0.8 (2013-10-28) +=================================== + +Python 2.6 support +------------------ + +``future`` now includes support for Python 2.6. + +To run the ``future`` test suite on Python 2.6, this additional package is needed:: + + pip install unittest2 + +``http.server`` also requires the ``argparse`` package:: + + pip install argparse + + +Unused modules removed +---------------------- + +The ``future.six`` module has been removed. ``future`` doesn't require ``six`` +(and hasn't since version 0.3). If you need support for Python versions before +2.6, ``six`` is the best option. ``future`` and ``six`` can be installed +alongside each other easily if needed. + +The unused ``hacks`` module has also been removed from the source tree. + + +``isinstance()`` added to :mod:`future.builtins` (v0.8.2) +--------------------------------------------------------- + +It is now possible to use ``isinstance()`` calls normally after importing ``isinstance`` from +``future.builtins``. On Python 2, this is specially defined to be compatible with +``future``'s backported ``int``, ``str``, and ``bytes`` types, as well as +handling Python 2's ``int``/``long`` distinction. + +The result is that code that uses ``isinstance`` to perform type-checking of +ints, strings, and bytes should now work identically on Python 2 as on Python 3. + +The utility functions ``isint``, ``istext``, and ``isbytes`` provided before for +compatible type-checking across Python 2 and 3 in :mod:`future.utils` are now +deprecated. + + +.. _changelog: + +Summary of all changes +====================== + +v0.15.0: + * Full backports of ``urllib.parse`` and other ``urllib`` submodules are exposed by ``install_aliases()``. + * ``tkinter.ttk`` support + * Initial ``surrogateescape`` support + * Additional backports: ``collections``, ``http`` constants, etc. + * Bug fixes + +v0.14.3: + * Bug fixes + +v0.14.2: + * Bug fixes + +v0.14.1: + * Bug fixes + +v0.14.0: + * New top-level ``builtins`` package on Py2 for cleaner imports. Equivalent to + ``future.builtins`` + * New top-level packages on Py2 with the same names as Py3 standard modules: + ``configparser``, ``copyreg``, ``html``, ``http``, ``xmlrpc``, ``winreg`` + +v0.13.1: + * Bug fixes + +v0.13.0: + * Cheat sheet for writing Python 2/3 compatible code + * ``to_int`` and ``from_int`` methods for ``newbytes`` + * Bug fixes + +v0.12.0: + * Add ``newobject`` and ``newlist`` types + * Improve compatibility of import hooks with ``Requests``, ``py2exe`` + * No more auto-installation of import hooks by ``future.standard_library`` + * New ``future.moves`` package + * ``past.builtins`` improved + * ``newstr.encode(..., errors='surrogateescape')`` supported + * Refactoring: ``future.standard_library`` submodules -> ``future.backports`` + * Refactoring: ``future.builtins.types`` -> ``future.types`` + * Refactoring: ``past.builtins.types`` -> ``past.types`` + * New ``listvalues`` and ``listitems`` functions in ``future.utils`` + * Many bug fixes to ``futurize``, ``future.builtins``, etc. + +v0.11.4: + * Restore Py2.6 compatibility + +v0.11.3: + * The ``futurize`` and ``pasteurize`` scripts add an explicit call to + ``future.standard_library.install_hooks()`` whenever modules affected by + PEP 3108 are imported. + + * The ``future.builtins.bytes`` constructor now accepts ``frozenset`` + objects as on Py3. + +v0.11.2: + * The ``past.translation.autotranslate`` feature now finds modules to import + more robustly and works with Python eggs. + +v0.11.1: + * Update to ``requirements_py26.txt`` for Python 2.6. Small updates to + docs and tests. + +v0.11: + * New ``past`` package with ``past.builtins`` and ``past.translation`` + modules. + +v0.10.2: + * Improvements to stdlib hooks. New context manager: + ``future.standard_library.hooks()``. + + * New ``raise_`` and ``raise_with_traceback`` functions in ``future.utils``. + +v0.10: + * New backported ``dict`` object with set-like ``keys``, ``values``, ``items`` + +v0.9: + * :func:`isinstance` hack removed in favour of ``__instancecheck__`` on the + metaclasses of the backported types + * ``futurize`` now only adds necessary imports by default + * Looser type-checking by ``future.builtins.str`` when combining with Py2 + native byte-strings. + +v0.8.3: + * New ``--all-imports`` option to ``futurize`` + * Fix bug with ``str.encode()`` with encoding as a non-keyword arg + +v0.8.2: + * New ``isinstance`` function in :mod:`future.builtins`. This obviates + and deprecates the utility functions for type-checking in :mod:`future.utils`. + +v0.8.1: + * Backported ``socketserver.py``. Fixes sporadic test failures with + ``http.server`` (related to threading and old-style classes used in Py2.7's + ``SocketServer.py``). + + * Move a few more safe ``futurize`` fixes from stage2 to stage1 + + * Bug fixes to :mod:`future.utils` + +v0.8: + * Added Python 2.6 support + + * Removed unused modules: :mod:`future.six` and :mod:`future.hacks` + + * Removed undocumented functions from :mod:`future.utils` + +v0.7: + * Added a backported Py3-like ``int`` object (inherits from ``long``). + + * Added utility functions for type-checking and docs about + ``isinstance`` uses/alternatives. + + * Fixes and stricter type-checking for ``bytes`` and ``str`` objects + + * Added many more tests for the ``futurize`` script + + * We no longer disable obsolete Py2 builtins by default with ``from + future.builtins import *``. Use ``from future.builtins.disabled + import *`` instead. + +v0.6: + * Added a backported Py3-like ``str`` object (inherits from Py2's ``unicode``) + + * Removed support for the form ``from future import *``; use ``from future.builtins import *`` instead + +v0.5.3: + * Doc improvements + +v0.5.2: + * Add lots of docs and a Sphinx project + +v0.5.1: + * Upgraded included ``six`` module (included as ``future.utils.six``) to v1.4.1 + + * :mod:`http.server` module backported + + * ``bytes.split()`` and ``.rsplit()`` bugfixes + +v0.5.0: + * Added backported Py3-like ``bytes`` object + +v0.4.2: + * Various fixes + +v0.4.1: + * Added :func:`open` (from :mod:`io` module on Py2) + * Improved docs + +v0.4.0: + * Added various useful compatibility functions to :mod:`future.utils` + + * Reorganized package: moved all builtins to :mod:`future.builtins`; moved + all stdlib things to ``future.standard_library`` + + * Renamed ``python-futurize`` console script to ``futurize`` + + * Moved ``future.six`` to ``future.utils.six`` and pulled the most relevant + definitions to :mod:`future.utils`. + + * More improvements to "Py3 to both" conversion (``futurize.py --from3``) + +v0.3.5: + * Fixed broken package setup ("package directory 'libfuturize/tests' does not exist") + +v0.3.4: + * Added ``itertools.zip_longest`` + + * Updated ``2to3_backcompat`` tests to use ``futurize.py`` + + * Improved ``libfuturize`` fixers: correct order of imports; add imports only when necessary (except ``absolute_import`` currently) + +v0.3.3: + * Added ``python-futurize`` console script + + * Added ``itertools.filterfalse`` + + * Removed docs about unfinished backports (``urllib`` etc.) + + * Removed old Py2 syntax in some files that breaks py3 ``setup.py install`` + +v0.3.2: + * Added ``test.support`` module + + * Added ``UserList``, ``UserString``, ``UserDict`` classes to ``collections`` module + + * Removed ``int`` -> ``long`` mapping + + * Added backported ``_markupbase.py`` etc. with new-style classes to fix travis-ci build problems + + * Added working ``html`` and ``http.client`` backported modules +v0.3.0: + * Generalized import hooks to allow dotted imports + + * Added backports of ``urllib``, ``html``, ``http`` modules from Py3.3 stdlib using ``future`` + + * Added ``futurize`` script for automatically turning Py2 or Py3 modules into + cross-platform Py3 modules + + * Renamed ``future.standard_library_renames`` to + ``future.standard_library``. (No longer just renames, but backports too.) + +v0.2.2.1: + * Small bug fixes to get tests passing on travis-ci.org + +v0.2.1: + * Small bug fixes + +v0.2.0: + * ``Features`` module renamed to ``modified_builtins`` + + * New functions added: :func:`round`, :func:`input` + + * No more namespace pollution as a policy:: + + from future import * + + should have no effect on Python 3. On Python 2, it only shadows the + builtins; it doesn't introduce any new names. + + * End-to-end tests with Python 2 code and ``2to3`` now work + +v0.1.0: + * first version with tests! + + * removed the inspect-module magic + +v0.0.x: + * initial releases. Use at your peril. diff --git a/Python/Dependencies/future-0.18.2/docs/compatible_idioms.rst b/Python/Dependencies/future-0.18.2/docs/compatible_idioms.rst new file mode 100644 index 0000000..b0cb05a --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/compatible_idioms.rst @@ -0,0 +1,1457 @@ +.. _compatible-idioms: + +Cheat Sheet: Writing Python 2-3 compatible code +=============================================== + +- **Copyright (c):** 2013-2019 Python Charmers Pty Ltd, Australia. +- **Author:** Ed Schofield. +- **Licence:** Creative Commons Attribution. + +A PDF version is here: http://python-future.org/compatible\_idioms.pdf + +This notebook shows you idioms for writing future-proof code that is +compatible with both versions of Python: 2 and 3. It accompanies Ed +Schofield's talk at PyCon AU 2014, "Writing 2/3 compatible code". (The +video is here: http://www.youtube.com/watch?v=KOqk8j11aAI&t=10m14s.) + +Minimum versions: + +- Python 2: 2.7+ +- Python 3: 3.4+ + +Setup +----- + +The imports below refer to these ``pip``-installable packages on PyPI: + +:: + + import future # pip install future + import builtins # pip install future + import past # pip install future + import six # pip install six + +The following scripts are also ``pip``-installable: + +:: + + futurize # pip install future + pasteurize # pip install future + +See http://python-future.org and https://pythonhosted.org/six/ for more +information. + +Essential syntax differences +---------------------------- + +print +~~~~~ + +.. code:: python + + # Python 2 only: + print 'Hello' +.. code:: python + + # Python 2 and 3: + print('Hello') +To print multiple strings, import ``print_function`` to prevent Py2 from +interpreting it as a tuple: + +.. code:: python + + # Python 2 only: + print 'Hello', 'Guido' +.. code:: python + + # Python 2 and 3: + from __future__ import print_function # (at top of module) + + print('Hello', 'Guido') +.. code:: python + + # Python 2 only: + print >> sys.stderr, 'Hello' +.. code:: python + + # Python 2 and 3: + from __future__ import print_function + + print('Hello', file=sys.stderr) +.. code:: python + + # Python 2 only: + print 'Hello', +.. code:: python + + # Python 2 and 3: + from __future__ import print_function + + print('Hello', end='') +Raising exceptions +~~~~~~~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + raise ValueError, "dodgy value" +.. code:: python + + # Python 2 and 3: + raise ValueError("dodgy value") +Raising exceptions with a traceback: + +.. code:: python + + # Python 2 only: + traceback = sys.exc_info()[2] + raise ValueError, "dodgy value", traceback +.. code:: python + + # Python 3 only: + raise ValueError("dodgy value").with_traceback() +.. code:: python + + # Python 2 and 3: option 1 + from six import reraise as raise_ + # or + from future.utils import raise_ + + traceback = sys.exc_info()[2] + raise_(ValueError, "dodgy value", traceback) +.. code:: python + + # Python 2 and 3: option 2 + from future.utils import raise_with_traceback + + raise_with_traceback(ValueError("dodgy value")) +Exception chaining (PEP 3134): + +.. code:: python + + # Setup: + class DatabaseError(Exception): + pass +.. code:: python + + # Python 3 only + class FileDatabase: + def __init__(self, filename): + try: + self.file = open(filename) + except IOError as exc: + raise DatabaseError('failed to open') from exc +.. code:: python + + # Python 2 and 3: + from future.utils import raise_from + + class FileDatabase: + def __init__(self, filename): + try: + self.file = open(filename) + except IOError as exc: + raise_from(DatabaseError('failed to open'), exc) +.. code:: python + + # Testing the above: + try: + fd = FileDatabase('non_existent_file.txt') + except Exception as e: + assert isinstance(e.__cause__, IOError) # FileNotFoundError on Py3.3+ inherits from IOError +Catching exceptions +~~~~~~~~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + try: + ... + except ValueError, e: + ... +.. code:: python + + # Python 2 and 3: + try: + ... + except ValueError as e: + ... +Division +~~~~~~~~ + +Integer division (rounding down): + +.. code:: python + + # Python 2 only: + assert 2 / 3 == 0 +.. code:: python + + # Python 2 and 3: + assert 2 // 3 == 0 +"True division" (float division): + +.. code:: python + + # Python 3 only: + assert 3 / 2 == 1.5 +.. code:: python + + # Python 2 and 3: + from __future__ import division # (at top of module) + + assert 3 / 2 == 1.5 +"Old division" (i.e. compatible with Py2 behaviour): + +.. code:: python + + # Python 2 only: + a = b / c # with any types +.. code:: python + + # Python 2 and 3: + from past.utils import old_div + + a = old_div(b, c) # always same as / on Py2 +Long integers +~~~~~~~~~~~~~ + +Short integers are gone in Python 3 and ``long`` has become ``int`` +(without the trailing ``L`` in the ``repr``). + +.. code:: python + + # Python 2 only + k = 9223372036854775808L + + # Python 2 and 3: + k = 9223372036854775808 +.. code:: python + + # Python 2 only + bigint = 1L + + # Python 2 and 3 + from builtins import int + bigint = int(1) +To test whether a value is an integer (of any kind): + +.. code:: python + + # Python 2 only: + if isinstance(x, (int, long)): + ... + + # Python 3 only: + if isinstance(x, int): + ... + + # Python 2 and 3: option 1 + from builtins import int # subclass of long on Py2 + + if isinstance(x, int): # matches both int and long on Py2 + ... + + # Python 2 and 3: option 2 + from past.builtins import long + + if isinstance(x, (int, long)): + ... +Octal constants +~~~~~~~~~~~~~~~ + +.. code:: python + + 0644 # Python 2 only +.. code:: python + + 0o644 # Python 2 and 3 +Backtick repr +~~~~~~~~~~~~~ + +.. code:: python + + `x` # Python 2 only +.. code:: python + + repr(x) # Python 2 and 3 +Metaclasses +~~~~~~~~~~~ + +.. code:: python + + class BaseForm(object): + pass + + class FormType(type): + pass +.. code:: python + + # Python 2 only: + class Form(BaseForm): + __metaclass__ = FormType + pass +.. code:: python + + # Python 3 only: + class Form(BaseForm, metaclass=FormType): + pass +.. code:: python + + # Python 2 and 3: + from six import with_metaclass + # or + from future.utils import with_metaclass + + class Form(with_metaclass(FormType, BaseForm)): + pass +Strings and bytes +----------------- + +Unicode (text) string literals +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are upgrading an existing Python 2 codebase, it may be preferable +to mark up all string literals as unicode explicitly with ``u`` +prefixes: + +.. code:: python + + # Python 2 only + s1 = 'The Zen of Python' + s2 = u'きたないのよりきれいな方がいい\n' + + # Python 2 and 3 + s1 = u'The Zen of Python' + s2 = u'きたないのよりきれいな方がいい\n' +The ``futurize`` and ``python-modernize`` tools do not currently offer +an option to do this automatically. + +If you are writing code for a new project or new codebase, you can use +this idiom to make all string literals in a module unicode strings: + +.. code:: python + + # Python 2 and 3 + from __future__ import unicode_literals # at top of module + + s1 = 'The Zen of Python' + s2 = 'きたないのよりきれいな方がいい\n' +See http://python-future.org/unicode\_literals.html for more discussion +on which style to use. + +Byte-string literals +~~~~~~~~~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only + s = 'This must be a byte-string' + + # Python 2 and 3 + s = b'This must be a byte-string' +To loop over a byte-string with possible high-bit characters, obtaining +each character as a byte-string of length 1: + +.. code:: python + + # Python 2 only: + for bytechar in 'byte-string with high-bit chars like \xf9': + ... + + # Python 3 only: + for myint in b'byte-string with high-bit chars like \xf9': + bytechar = bytes([myint]) + + # Python 2 and 3: + from builtins import bytes + for myint in bytes(b'byte-string with high-bit chars like \xf9'): + bytechar = bytes([myint]) +As an alternative, ``chr()`` and ``.encode('latin-1')`` can be used to +convert an int into a 1-char byte string: + +.. code:: python + + # Python 3 only: + for myint in b'byte-string with high-bit chars like \xf9': + char = chr(myint) # returns a unicode string + bytechar = char.encode('latin-1') + + # Python 2 and 3: + from builtins import bytes, chr + for myint in bytes(b'byte-string with high-bit chars like \xf9'): + char = chr(myint) # returns a unicode string + bytechar = char.encode('latin-1') # forces returning a byte str +basestring +~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + a = u'abc' + b = 'def' + assert (isinstance(a, basestring) and isinstance(b, basestring)) + + # Python 2 and 3: alternative 1 + from past.builtins import basestring # pip install future + + a = u'abc' + b = b'def' + assert (isinstance(a, basestring) and isinstance(b, basestring)) +.. code:: python + + # Python 2 and 3: alternative 2: refactor the code to avoid considering + # byte-strings as strings. + + from builtins import str + a = u'abc' + b = b'def' + c = b.decode() + assert isinstance(a, str) and isinstance(c, str) + # ... +unicode +~~~~~~~ + +.. code:: python + + # Python 2 only: + templates = [u"blog/blog_post_detail_%s.html" % unicode(slug)] +.. code:: python + + # Python 2 and 3: alternative 1 + from builtins import str + templates = [u"blog/blog_post_detail_%s.html" % str(slug)] +.. code:: python + + # Python 2 and 3: alternative 2 + from builtins import str as text + templates = [u"blog/blog_post_detail_%s.html" % text(slug)] +StringIO +~~~~~~~~ + +.. code:: python + + # Python 2 only: + from StringIO import StringIO + # or: + from cStringIO import StringIO + + # Python 2 and 3: + from io import BytesIO # for handling byte strings + from io import StringIO # for handling unicode strings +Imports relative to a package +----------------------------- + +Suppose the package is: + +:: + + mypackage/ + __init__.py + submodule1.py + submodule2.py + + +and the code below is in ``submodule1.py``: + +.. code:: python + + # Python 2 only: + import submodule2 +.. code:: python + + # Python 2 and 3: + from . import submodule2 +.. code:: python + + # Python 2 and 3: + # To make Py2 code safer (more like Py3) by preventing + # implicit relative imports, you can also add this to the top: + from __future__ import absolute_import +Dictionaries +------------ + +.. code:: python + + heights = {'Fred': 175, 'Anne': 166, 'Joe': 192} +Iterating through ``dict`` keys/values/items +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Iterable dict keys: + +.. code:: python + + # Python 2 only: + for key in heights.iterkeys(): + ... +.. code:: python + + # Python 2 and 3: + for key in heights: + ... +Iterable dict values: + +.. code:: python + + # Python 2 only: + for value in heights.itervalues(): + ... +.. code:: python + + # Idiomatic Python 3 + for value in heights.values(): # extra memory overhead on Py2 + ... +.. code:: python + + # Python 2 and 3: option 1 + from builtins import dict + + heights = dict(Fred=175, Anne=166, Joe=192) + for key in heights.values(): # efficient on Py2 and Py3 + ... +.. code:: python + + # Python 2 and 3: option 2 + from future.utils import itervalues + # or + from six import itervalues + + for key in itervalues(heights): + ... +Iterable dict items: + +.. code:: python + + # Python 2 only: + for (key, value) in heights.iteritems(): + ... +.. code:: python + + # Python 2 and 3: option 1 + for (key, value) in heights.items(): # inefficient on Py2 + ... +.. code:: python + + # Python 2 and 3: option 2 + from future.utils import viewitems + + for (key, value) in viewitems(heights): # also behaves like a set + ... +.. code:: python + + # Python 2 and 3: option 3 + from future.utils import iteritems + # or + from six import iteritems + + for (key, value) in iteritems(heights): + ... +dict keys/values/items as a list +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +dict keys as a list: + +.. code:: python + + # Python 2 only: + keylist = heights.keys() + assert isinstance(keylist, list) +.. code:: python + + # Python 2 and 3: + keylist = list(heights) + assert isinstance(keylist, list) +dict values as a list: + +.. code:: python + + # Python 2 only: + heights = {'Fred': 175, 'Anne': 166, 'Joe': 192} + valuelist = heights.values() + assert isinstance(valuelist, list) +.. code:: python + + # Python 2 and 3: option 1 + valuelist = list(heights.values()) # inefficient on Py2 +.. code:: python + + # Python 2 and 3: option 2 + from builtins import dict + + heights = dict(Fred=175, Anne=166, Joe=192) + valuelist = list(heights.values()) +.. code:: python + + # Python 2 and 3: option 3 + from future.utils import listvalues + + valuelist = listvalues(heights) +.. code:: python + + # Python 2 and 3: option 4 + from future.utils import itervalues + # or + from six import itervalues + + valuelist = list(itervalues(heights)) +dict items as a list: + +.. code:: python + + # Python 2 and 3: option 1 + itemlist = list(heights.items()) # inefficient on Py2 +.. code:: python + + # Python 2 and 3: option 2 + from future.utils import listitems + + itemlist = listitems(heights) +.. code:: python + + # Python 2 and 3: option 3 + from future.utils import iteritems + # or + from six import iteritems + + itemlist = list(iteritems(heights)) +Custom class behaviour +---------------------- + +Custom iterators +~~~~~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only + class Upper(object): + def __init__(self, iterable): + self._iter = iter(iterable) + def next(self): # Py2-style + return self._iter.next().upper() + def __iter__(self): + return self + + itr = Upper('hello') + assert itr.next() == 'H' # Py2-style + assert list(itr) == list('ELLO') +.. code:: python + + # Python 2 and 3: option 1 + from builtins import object + + class Upper(object): + def __init__(self, iterable): + self._iter = iter(iterable) + def __next__(self): # Py3-style iterator interface + return next(self._iter).upper() # builtin next() function calls + def __iter__(self): + return self + + itr = Upper('hello') + assert next(itr) == 'H' # compatible style + assert list(itr) == list('ELLO') +.. code:: python + + # Python 2 and 3: option 2 + from future.utils import implements_iterator + + @implements_iterator + class Upper(object): + def __init__(self, iterable): + self._iter = iter(iterable) + def __next__(self): # Py3-style iterator interface + return next(self._iter).upper() # builtin next() function calls + def __iter__(self): + return self + + itr = Upper('hello') + assert next(itr) == 'H' + assert list(itr) == list('ELLO') +Custom ``__str__`` methods +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + class MyClass(object): + def __unicode__(self): + return 'Unicode string: \u5b54\u5b50' + def __str__(self): + return unicode(self).encode('utf-8') + + a = MyClass() + print(a) # prints encoded string +.. code:: python + + # Python 2 and 3: + from future.utils import python_2_unicode_compatible + + @python_2_unicode_compatible + class MyClass(object): + def __str__(self): + return u'Unicode string: \u5b54\u5b50' + + a = MyClass() + print(a) # prints string encoded as utf-8 on Py2 + +.. parsed-literal:: + + Unicode string: 孔子 + + +Custom ``__nonzero__`` vs ``__bool__`` method: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + class AllOrNothing(object): + def __init__(self, l): + self.l = l + def __nonzero__(self): + return all(self.l) + + container = AllOrNothing([0, 100, 200]) + assert not bool(container) +.. code:: python + + # Python 2 and 3: + from builtins import object + + class AllOrNothing(object): + def __init__(self, l): + self.l = l + def __bool__(self): + return all(self.l) + + container = AllOrNothing([0, 100, 200]) + assert not bool(container) +Lists versus iterators +---------------------- + +xrange +~~~~~~ + +.. code:: python + + # Python 2 only: + for i in xrange(10**8): + ... +.. code:: python + + # Python 2 and 3: forward-compatible + from builtins import range + for i in range(10**8): + ... +.. code:: python + + # Python 2 and 3: backward-compatible + from past.builtins import xrange + for i in xrange(10**8): + ... +range +~~~~~ + +.. code:: python + + # Python 2 only + mylist = range(5) + assert mylist == [0, 1, 2, 3, 4] +.. code:: python + + # Python 2 and 3: forward-compatible: option 1 + mylist = list(range(5)) # copies memory on Py2 + assert mylist == [0, 1, 2, 3, 4] +.. code:: python + + # Python 2 and 3: forward-compatible: option 2 + from builtins import range + + mylist = list(range(5)) + assert mylist == [0, 1, 2, 3, 4] +.. code:: python + + # Python 2 and 3: option 3 + from future.utils import lrange + + mylist = lrange(5) + assert mylist == [0, 1, 2, 3, 4] +.. code:: python + + # Python 2 and 3: backward compatible + from past.builtins import range + + mylist = range(5) + assert mylist == [0, 1, 2, 3, 4] +map +~~~ + +.. code:: python + + # Python 2 only: + mynewlist = map(f, myoldlist) + assert mynewlist == [f(x) for x in myoldlist] +.. code:: python + + # Python 2 and 3: option 1 + # Idiomatic Py3, but inefficient on Py2 + mynewlist = list(map(f, myoldlist)) + assert mynewlist == [f(x) for x in myoldlist] +.. code:: python + + # Python 2 and 3: option 2 + from builtins import map + + mynewlist = list(map(f, myoldlist)) + assert mynewlist == [f(x) for x in myoldlist] +.. code:: python + + # Python 2 and 3: option 3 + try: + import itertools.imap as map + except ImportError: + pass + + mynewlist = list(map(f, myoldlist)) # inefficient on Py2 + assert mynewlist == [f(x) for x in myoldlist] +.. code:: python + + # Python 2 and 3: option 4 + from future.utils import lmap + + mynewlist = lmap(f, myoldlist) + assert mynewlist == [f(x) for x in myoldlist] +.. code:: python + + # Python 2 and 3: option 5 + from past.builtins import map + + mynewlist = map(f, myoldlist) + assert mynewlist == [f(x) for x in myoldlist] +imap +~~~~ + +.. code:: python + + # Python 2 only: + from itertools import imap + + myiter = imap(func, myoldlist) + assert isinstance(myiter, iter) +.. code:: python + + # Python 3 only: + myiter = map(func, myoldlist) + assert isinstance(myiter, iter) +.. code:: python + + # Python 2 and 3: option 1 + from builtins import map + + myiter = map(func, myoldlist) + assert isinstance(myiter, iter) +.. code:: python + + # Python 2 and 3: option 2 + try: + import itertools.imap as map + except ImportError: + pass + + myiter = map(func, myoldlist) + assert isinstance(myiter, iter) +.. code:: python + + # Python 2 and 3: option 3 + from six.moves import map + + myiter = map(func, myoldlist) + assert isinstance(myiter, iter) + +zip, izip +~~~~~~~~~ + +As above with ``zip`` and ``itertools.izip``. + +filter, ifilter +~~~~~~~~~~~~~~~ + +As above with ``filter`` and ``itertools.ifilter`` too. + +Other builtins +-------------- + +File IO with open() +~~~~~~~~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only + f = open('myfile.txt') + data = f.read() # as a byte string + text = data.decode('utf-8') + + # Python 2 and 3: alternative 1 + from io import open + f = open('myfile.txt', 'rb') + data = f.read() # as bytes + text = data.decode('utf-8') # unicode, not bytes + + # Python 2 and 3: alternative 2 + from io import open + f = open('myfile.txt', encoding='utf-8') + text = f.read() # unicode, not bytes +reduce() +~~~~~~~~ + +.. code:: python + + # Python 2 only: + assert reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) == 1+2+3+4+5 +.. code:: python + + # Python 2 and 3: + from functools import reduce + + assert reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) == 1+2+3+4+5 +raw\_input() +~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + name = raw_input('What is your name? ') + assert isinstance(name, str) # native str +.. code:: python + + # Python 2 and 3: + from builtins import input + + name = input('What is your name? ') + assert isinstance(name, str) # native str on Py2 and Py3 +input() +~~~~~~~ + +.. code:: python + + # Python 2 only: + input("Type something safe please: ") +.. code:: python + + # Python 2 and 3 + from builtins import input + eval(input("Type something safe please: ")) +Warning: using either of these is **unsafe** with untrusted input. + +file() +~~~~~~ + +.. code:: python + + # Python 2 only: + f = file(pathname) +.. code:: python + + # Python 2 and 3: + f = open(pathname) + + # But preferably, use this: + from io import open + f = open(pathname, 'rb') # if f.read() should return bytes + # or + f = open(pathname, 'rt') # if f.read() should return unicode text +exec +~~~~ + +.. code:: python + + # Python 2 only: + exec 'x = 10' + + # Python 2 and 3: + exec('x = 10') +.. code:: python + + # Python 2 only: + g = globals() + exec 'x = 10' in g + + # Python 2 and 3: + g = globals() + exec('x = 10', g) +.. code:: python + + # Python 2 only: + l = locals() + exec 'x = 10' in g, l + + # Python 2 and 3: + exec('x = 10', g, l) +execfile() +~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + execfile('myfile.py') +.. code:: python + + # Python 2 and 3: alternative 1 + from past.builtins import execfile + + execfile('myfile.py') +.. code:: python + + # Python 2 and 3: alternative 2 + exec(compile(open('myfile.py').read())) + + # This can sometimes cause this: + # SyntaxError: function ... uses import * and bare exec ... + # See https://github.com/PythonCharmers/python-future/issues/37 +unichr() +~~~~~~~~ + +.. code:: python + + # Python 2 only: + assert unichr(8364) == '€' +.. code:: python + + # Python 3 only: + assert chr(8364) == '€' +.. code:: python + + # Python 2 and 3: + from builtins import chr + assert chr(8364) == '€' +intern() +~~~~~~~~ + +.. code:: python + + # Python 2 only: + intern('mystring') +.. code:: python + + # Python 3 only: + from sys import intern + intern('mystring') +.. code:: python + + # Python 2 and 3: alternative 1 + from past.builtins import intern + intern('mystring') +.. code:: python + + # Python 2 and 3: alternative 2 + from six.moves import intern + intern('mystring') +.. code:: python + + # Python 2 and 3: alternative 3 + from future.standard_library import install_aliases + install_aliases() + from sys import intern + intern('mystring') +.. code:: python + + # Python 2 and 3: alternative 2 + try: + from sys import intern + except ImportError: + pass + intern('mystring') +apply() +~~~~~~~ + +.. code:: python + + args = ('a', 'b') + kwargs = {'kwarg1': True} +.. code:: python + + # Python 2 only: + apply(f, args, kwargs) +.. code:: python + + # Python 2 and 3: alternative 1 + f(*args, **kwargs) +.. code:: python + + # Python 2 and 3: alternative 2 + from past.builtins import apply + apply(f, args, kwargs) +chr() +~~~~~ + +.. code:: python + + # Python 2 only: + assert chr(64) == b'@' + assert chr(200) == b'\xc8' +.. code:: python + + # Python 3 only: option 1 + assert chr(64).encode('latin-1') == b'@' + assert chr(0xc8).encode('latin-1') == b'\xc8' +.. code:: python + + # Python 2 and 3: option 1 + from builtins import chr + + assert chr(64).encode('latin-1') == b'@' + assert chr(0xc8).encode('latin-1') == b'\xc8' +.. code:: python + + # Python 3 only: option 2 + assert bytes([64]) == b'@' + assert bytes([0xc8]) == b'\xc8' +.. code:: python + + # Python 2 and 3: option 2 + from builtins import bytes + + assert bytes([64]) == b'@' + assert bytes([0xc8]) == b'\xc8' +cmp() +~~~~~ + +.. code:: python + + # Python 2 only: + assert cmp('a', 'b') < 0 and cmp('b', 'a') > 0 and cmp('c', 'c') == 0 +.. code:: python + + # Python 2 and 3: alternative 1 + from past.builtins import cmp + assert cmp('a', 'b') < 0 and cmp('b', 'a') > 0 and cmp('c', 'c') == 0 +.. code:: python + + # Python 2 and 3: alternative 2 + cmp = lambda(x, y): (x > y) - (x < y) + assert cmp('a', 'b') < 0 and cmp('b', 'a') > 0 and cmp('c', 'c') == 0 +reload() +~~~~~~~~ + +.. code:: python + + # Python 2 only: + reload(mymodule) +.. code:: python + + # Python 2 and 3 + from imp import reload + reload(mymodule) +Standard library +---------------- + +dbm modules +~~~~~~~~~~~ + +.. code:: python + + # Python 2 only + import anydbm + import whichdb + import dbm + import dumbdbm + import gdbm + + # Python 2 and 3: alternative 1 + from future import standard_library + standard_library.install_aliases() + + import dbm + import dbm.ndbm + import dbm.dumb + import dbm.gnu + + # Python 2 and 3: alternative 2 + from future.moves import dbm + from future.moves.dbm import dumb + from future.moves.dbm import ndbm + from future.moves.dbm import gnu + + # Python 2 and 3: alternative 3 + from six.moves import dbm_gnu + # (others not supported) +commands / subprocess modules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only + from commands import getoutput, getstatusoutput + + # Python 2 and 3 + from future import standard_library + standard_library.install_aliases() + + from subprocess import getoutput, getstatusoutput +StringIO module +~~~~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only + from StringIO import StringIO + from cStringIO import StringIO +.. code:: python + + # Python 2 and 3 + from io import BytesIO + # and refactor StringIO() calls to BytesIO() if passing byte-strings +http module +~~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + import httplib + import Cookie + import cookielib + import BaseHTTPServer + import SimpleHTTPServer + import CGIHttpServer + + # Python 2 and 3 (after ``pip install future``): + import http.client + import http.cookies + import http.cookiejar + import http.server +xmlrpc module +~~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + import DocXMLRPCServer + import SimpleXMLRPCServer + + # Python 2 and 3 (after ``pip install future``): + import xmlrpc.server +.. code:: python + + # Python 2 only: + import xmlrpclib + + # Python 2 and 3 (after ``pip install future``): + import xmlrpc.client +html escaping and entities +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: python + + # Python 2 and 3: + from cgi import escape + + # Safer (Python 2 and 3, after ``pip install future``): + from html import escape + + # Python 2 only: + from htmlentitydefs import codepoint2name, entitydefs, name2codepoint + + # Python 2 and 3 (after ``pip install future``): + from html.entities import codepoint2name, entitydefs, name2codepoint +html parsing +~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + from HTMLParser import HTMLParser + + # Python 2 and 3 (after ``pip install future``) + from html.parser import HTMLParser + + # Python 2 and 3 (alternative 2): + from future.moves.html.parser import HTMLParser +urllib module +~~~~~~~~~~~~~ + +``urllib`` is the hardest module to use from Python 2/3 compatible code. +You might want to switch to Requests (http://python-requests.org) instead. + +.. code:: python + + # Python 2 only: + from urlparse import urlparse + from urllib import urlencode + from urllib2 import urlopen, Request, HTTPError +.. code:: python + + # Python 3 only: + from urllib.parse import urlparse, urlencode + from urllib.request import urlopen, Request + from urllib.error import HTTPError +.. code:: python + + # Python 2 and 3: easiest option + from future.standard_library import install_aliases + install_aliases() + + from urllib.parse import urlparse, urlencode + from urllib.request import urlopen, Request + from urllib.error import HTTPError +.. code:: python + + # Python 2 and 3: alternative 2 + from future.standard_library import hooks + + with hooks(): + from urllib.parse import urlparse, urlencode + from urllib.request import urlopen, Request + from urllib.error import HTTPError +.. code:: python + + # Python 2 and 3: alternative 3 + from future.moves.urllib.parse import urlparse, urlencode + from future.moves.urllib.request import urlopen, Request + from future.moves.urllib.error import HTTPError + # or + from six.moves.urllib.parse import urlparse, urlencode + from six.moves.urllib.request import urlopen + from six.moves.urllib.error import HTTPError +.. code:: python + + # Python 2 and 3: alternative 4 + try: + from urllib.parse import urlparse, urlencode + from urllib.request import urlopen, Request + from urllib.error import HTTPError + except ImportError: + from urlparse import urlparse + from urllib import urlencode + from urllib2 import urlopen, Request, HTTPError +Tkinter +~~~~~~~ + +.. code:: python + + # Python 2 only: + import Tkinter + import Dialog + import FileDialog + import ScrolledText + import SimpleDialog + import Tix + import Tkconstants + import Tkdnd + import tkColorChooser + import tkCommonDialog + import tkFileDialog + import tkFont + import tkMessageBox + import tkSimpleDialog + import ttk + + # Python 2 and 3 (after ``pip install future``): + import tkinter + import tkinter.dialog + import tkinter.filedialog + import tkinter.scrolledtext + import tkinter.simpledialog + import tkinter.tix + import tkinter.constants + import tkinter.dnd + import tkinter.colorchooser + import tkinter.commondialog + import tkinter.filedialog + import tkinter.font + import tkinter.messagebox + import tkinter.simpledialog + import tkinter.ttk +socketserver +~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + import SocketServer + + # Python 2 and 3 (after ``pip install future``): + import socketserver +copy\_reg, copyreg +~~~~~~~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + import copy_reg + + # Python 2 and 3 (after ``pip install future``): + import copyreg +configparser +~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + from ConfigParser import ConfigParser + + # Python 2 and 3 (after ``pip install configparser``): + from configparser import ConfigParser +queue +~~~~~ + +.. code:: python + + # Python 2 only: + from Queue import Queue, heapq, deque + + # Python 2 and 3 (after ``pip install future``): + from queue import Queue, heapq, deque +repr, reprlib +~~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + from repr import aRepr, repr + + # Python 2 and 3 (after ``pip install future``): + from reprlib import aRepr, repr +UserDict, UserList, UserString +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + from UserDict import UserDict + from UserList import UserList + from UserString import UserString + + # Python 3 only: + from collections import UserDict, UserList, UserString + + # Python 2 and 3: alternative 1 + from future.moves.collections import UserDict, UserList, UserString + + # Python 2 and 3: alternative 2 + from six.moves import UserDict, UserList, UserString + + # Python 2 and 3: alternative 3 + from future.standard_library import install_aliases + install_aliases() + from collections import UserDict, UserList, UserString +itertools: filterfalse, zip\_longest +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: python + + # Python 2 only: + from itertools import ifilterfalse, izip_longest + + # Python 3 only: + from itertools import filterfalse, zip_longest + + # Python 2 and 3: alternative 1 + from future.moves.itertools import filterfalse, zip_longest + + # Python 2 and 3: alternative 2 + from six.moves import filterfalse, zip_longest + + # Python 2 and 3: alternative 3 + from future.standard_library import install_aliases + install_aliases() + from itertools import filterfalse, zip_longest diff --git a/Python/Dependencies/future-0.18.2/docs/conf.py b/Python/Dependencies/future-0.18.2/docs/conf.py new file mode 100644 index 0000000..fd106fa --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/conf.py @@ -0,0 +1,332 @@ +# -*- coding: utf-8 -*- +# +# Python-Future documentation build configuration file, created by +# sphinx-quickstart on Sun Sep 22 07:02:03 2013. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +from __future__ import absolute_import, print_function +import sys, os +from future import __version__ +import sphinx_bootstrap_theme + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) +# Was: sys.path.append(os.path.dirname(os.path.abspath(__file__))) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', + # 'sphinxcontrib.napoleon' # see https://sphinxcontrib-napoleon.readthedocs.io/ + # 'sphinx.ext.napoleon' # use this in Sphinx 1.3+ + ] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Python-Future' +copyright = u'2013-2019, Python Charmers Pty Ltd, Australia' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# if 'dev' in release: +# release = release.split('dev')[0] + 'dev' +# release = '0.12.5-dev' +# version = release # was: '.'.join(release.split('.')[:2]) + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' # 'futureext.FutureStyle' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'bootstrap' +html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_theme_options = { + # Navigation bar title. (Default: ``project`` value) + #'navbar_title': "Python-Future", + + # Tab name for entire site. (Default: "Site") + 'navbar_site_name': "Contents", + + # A list of tuples containing pages or urls to link to. + # Valid tuples should be in the following forms: + # (name, page) # a link to a page + # (name, "/aa/bb", 1) # a link to an arbitrary relative url + # (name, "http://example.com", True) # arbitrary absolute url + # Note the "1" or "True" value above as the third argument to indicate + # an arbitrary url. + 'navbar_links': [ + ("Overview", "overview"), + ("Cheat Sheet", "compatible_idioms.html", True), + ("FAQ", "faq.html", True), + # ("Link", "http://example.com", True), + ], + + # Render the next and previous page links in navbar. (Default: true) + 'navbar_sidebarrel': False, + + # Render the current pages TOC in the navbar. (Default: true) + 'navbar_pagenav': True, + + # Global TOC depth for "site" navbar tab. (Default: 1) + # Switching to -1 shows all levels. + 'globaltoc_depth': 3, + + # Include hidden TOCs in Site navbar? + # + # Note: If this is "false", you cannot have mixed ``:hidden:`` and + # non-hidden ``toctree`` directives in the same page, or else the build + # will break. + # + # Values: "true" (default) or "false" + 'globaltoc_includehidden': "true", + + # HTML navbar class (Default: "navbar") to attach to <div> element. + # For black navbar, do "navbar navbar-inverse" + 'navbar_class': "navbar navbar-inverse", + + # Fix navigation bar to top of page? + # Values: "true" (default) or "false" + 'navbar_fixed_top': "true", + + # Location of link to source. + # Options are "nav" (default), "footer" or anything else to exclude. + 'source_link_position': "none", + + # Bootswatch (http://bootswatch.com/) theme. + # + # Options are nothing with "" (default) or the name of a valid theme + # such as "amelia" or "cosmo" or "united". + 'bootswatch_theme': "cerulean", + + # Choose Bootstrap version. + # Values: "3" (default) or "2" (in quotes) + 'bootstrap_version': "3", +} + + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = '_static/python-future-logo-textless-transparent.png' + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +html_favicon = "_static/python-future-icon-32.ico" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +html_sidebars = { + '**': ['sidebarintro.html', + 'sidebartoc.html', + # 'sourcelink.html', + #'searchbox.html', + ] + # '**': ['sidebarlogo.html', 'localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] +} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +html_show_sphinx = False + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Futuredoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +'papersize': 'a4paper', + +# The font size ('10pt', '11pt' or '12pt'). +'pointsize': '12pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': r''' +#\usepackage{futurestyle} +#''', + +# 'fontpkg': r'\usepackage{mathpazo}', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'Python-Future.tex', u'Python-Future Documentation', + u'Python Charmers', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +latex_use_parts = True + +# latex_additional_files = ['futurestyle.sty', 'logo.pdf'] + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'python-future', u'Python-Future Documentation', + [u'Python Charmers'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'Python-Future', u'Python-Future Documentation', + u'Python Charmers', 'Python-Future', 'Easy compatibility for Python 2 and 3', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/Python/Dependencies/future-0.18.2/docs/contents.rst.inc b/Python/Dependencies/future-0.18.2/docs/contents.rst.inc new file mode 100644 index 0000000..7c9bbf2 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/contents.rst.inc @@ -0,0 +1,26 @@ +Contents: +--------- + +.. toctree:: + :maxdepth: 2 + + whatsnew + overview + quickstart + compatible_idioms + imports + what_else + automatic_conversion + faq + stdlib_incompatibilities + older_interfaces + changelog + credits + reference + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/Python/Dependencies/future-0.18.2/docs/conversion_limitations.rst b/Python/Dependencies/future-0.18.2/docs/conversion_limitations.rst new file mode 100644 index 0000000..c2b1530 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/conversion_limitations.rst @@ -0,0 +1,27 @@ +.. _futurize-limitations: + +Known limitations +----------------- + +``futurize`` and ``pasteurize`` are useful to automate much of the +work of porting, particularly the boring repetitive text substitutions. They also +help to flag which parts of the code require attention. + +Nevertheless, ``futurize`` and ``pasteurize`` are still incomplete and make +some mistakes, like 2to3, on which they are based. Please report bugs on +`GitHub <https://github.com/PythonCharmers/python-future/>`_. Contributions to +the ``lib2to3``-based fixers for ``futurize`` and ``pasteurize`` are +particularly welcome! Please see :ref:`contributing`. + +``futurize`` doesn't currently make the following change automatically: + +1. Strings containing ``\U`` produce a ``SyntaxError`` on Python 3. An example is:: + + s = 'C:\Users'. + + Python 2 expands this to ``s = 'C:\\Users'``, but Python 3 requires a raw + prefix (``r'...'``). This also applies to multi-line strings (including + multi-line docstrings). + +Also see the tests in ``future/tests/test_futurize.py`` marked +``@expectedFailure`` or ``@skip`` for known limitations. diff --git a/Python/Dependencies/future-0.18.2/docs/credits.rst b/Python/Dependencies/future-0.18.2/docs/credits.rst new file mode 100644 index 0000000..275e148 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/credits.rst @@ -0,0 +1,151 @@ +Licensing and credits +===================== + +.. _licence: + +Licence +------- +The software is distributed under an MIT licence. The text is as follows +(from ``LICENSE.txt``):: + + Copyright (c) 2013-2019 Python Charmers Pty Ltd, Australia + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. + +.. _sponsor: + +Sponsors +-------- +Python Charmers Pty Ltd, Australia, and Python Charmers Pte Ltd, Singapore. +http://pythoncharmers.com + +Pinterest https://opensource.pinterest.com/ + +.. _authors: + +Maintainer +---------- +Python-Future is currently maintained by Jordan M. Adler <jordan.m.adler@gmail.com>. + +Authors +------- +Python-Future is largely written by Ed Schofield <ed@pythoncharmers.com> with the help of various contributors: + +- Jordan Adler +- Jeroen Akkerman +- Kyle Altendorf +- Grant Bakker +- Jacob Beck +- Fumihiro (Ben) Bessho +- Shiva Bhusal +- Nate Bogdanowicz +- Tomer Chachamu +- Christian Clauss +- Denis Cornehl +- Nicolas Delaby +- Chad Dombrova +- Jon Dufresne +- Corey Farwell +- Eric Firing +- Joe Gordon +- Maximilian Hils +- Miro Hrončok +- Mark Huang +- Martijn Jacobs +- Michael Joseph +- Waldemar Kornewald +- Alexey Kotlyarov +- Steve Kowalik +- Lion Krischer +- Marcin Kuzminski +- Joshua Landau +- German Larrain +- Chris Lasher +- ghanshyam lele +- Calum Lind +- Tobias Megies +- Anika Mukherji +- Jon Parise +- Matthew Parnell +- Tom Picton +- Miga Purg +- Éloi Rivard +- Sesh Sadasivam +- Elliott Sales de Andrade +- Aiden Scandella +- Yury Selivanov +- Tim Shaffer +- Sameera Somisetty +- Louis Sautier +- Gregory P. Smith +- Chase Sterling +- Daniel Szoska +- Flaviu Tamas +- Jeff Tratner +- Tim Tröndle +- Brad Walker +- Andrew Wason +- Jeff Widman +- Dan Yeaw +- Hackalog (GitHub user) +- lsm (GiHub user) +- Mystic-Mirage (GitHub user) +- str4d (GitHub user) +- ucodery (GitHub user) +- urain39 (GitHub user) +- 9seconds (GitHub user) +- Varriount (GitHub user) + +Suggestions and Feedback +~~~~~~~~~~~~~~~~~~~~~~~~ + +- Chris Adams +- Martijn Faassen +- Joe Gordon +- Lion Krischer +- Danielle Madeley +- Val Markovic +- wluebbe (GitHub user) + + +Other Credits +------------- + +- The backported ``super()`` and ``range()`` functions are derived from Ryan + Kelly's ``magicsuper`` module and Dan Crosta's ``xrange`` module. + +- The ``futurize`` and ``pasteurize`` scripts use ``lib2to3``, ``lib3to2``, and + parts of Armin Ronacher's ``python-modernize`` code. + +- The ``python_2_unicode_compatible`` decorator is from Django. The + ``implements_iterator`` and ``with_metaclass`` decorators are from Jinja2. + +- The ``exec_`` function and some others in ``future.utils`` are from the + ``six`` module by Benjamin Peterson. + +- The ``raise_`` and ``raise_with_traceback`` functions were contributed by + Jeff Tratner. + +- A working version of ``raise_from`` was contributed by Varriount (GitHub). + +- Documentation is generated with `Sphinx <http://sphinx.pocoo.org>`_ using the + ``sphinx-bootstrap`` theme. + +- ``past.translation`` is inspired by and borrows some code from Sanjay Vinip's + ``uprefix`` module. diff --git a/Python/Dependencies/future-0.18.2/docs/custom_iterators.rst b/Python/Dependencies/future-0.18.2/docs/custom_iterators.rst new file mode 100644 index 0000000..6ff389a --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/custom_iterators.rst @@ -0,0 +1,94 @@ +.. _custom-iterators: + +Custom iterators +---------------- + +If you define your own iterators, there is an incompatibility in the method name +to retrieve the next item across Py3 and Py2. On Python 3 it is ``__next__``, +whereas on Python 2 it is ``next``. + +The most elegant solution to this is to derive your custom iterator class from +``builtins.object`` and define a ``__next__`` method as you normally +would on Python 3. On Python 2, ``object`` then refers to the +``future.types.newobject`` base class, which provides a fallback ``next`` +method that calls your ``__next__``. Use it as follows:: + + from builtins import object + + class Upper(object): + def __init__(self, iterable): + self._iter = iter(iterable) + def __next__(self): # Py3-style iterator interface + return next(self._iter).upper() + def __iter__(self): + return self + + itr = Upper('hello') + assert next(itr) == 'H' + assert next(itr) == 'E' + assert list(itr) == list('LLO') + + +You can use this approach unless you are defining a custom iterator as a +subclass of a base class defined elsewhere that does not derive from +``newobject``. In that case, you can provide compatibility across +Python 2 and Python 3 using the ``next`` function from ``future.builtins``:: + + from builtins import next + + from some_module import some_base_class + + class Upper2(some_base_class): + def __init__(self, iterable): + self._iter = iter(iterable) + def __next__(self): # Py3-style iterator interface + return next(self._iter).upper() + def __iter__(self): + return self + + itr2 = Upper2('hello') + assert next(itr2) == 'H' + assert next(itr2) == 'E' + +``next()`` also works with regular Python 2 iterators with a ``.next`` method:: + + itr3 = iter(['one', 'three', 'five']) + assert 'next' in dir(itr3) + assert next(itr3) == 'one' + +This approach is feasible whenever your code calls the ``next()`` function +explicitly. If you consume the iterator implicitly in a ``for`` loop or +``list()`` call or by some other means, the ``future.builtins.next`` function +will not help; the third assertion below would fail on Python 2:: + + itr2 = Upper2('hello') + + assert next(itr2) == 'H' + assert next(itr2) == 'E' + assert list(itr2) == list('LLO') # fails because Py2 implicitly looks + # for a ``next`` method. + +Instead, you can use a decorator called ``implements_iterator`` from +``future.utils`` to allow Py3-style iterators to work identically on Py2, even +if they don't inherit from ``future.builtins.object``. Use it as follows:: + + from future.utils import implements_iterator + + Upper2 = implements_iterator(Upper2) + + print(list(Upper2('hello'))) + # prints ['H', 'E', 'L', 'L', 'O'] + +This can of course also be used with the ``@`` decorator syntax when defining +the iterator as follows:: + + @implements_iterator + class Upper2(some_base_class): + def __init__(self, iterable): + self._iter = iter(iterable) + def __next__(self): # note the Py3 interface + return next(self._iter).upper() + def __iter__(self): + return self + +On Python 3, as usual, this decorator does nothing. diff --git a/Python/Dependencies/future-0.18.2/docs/custom_str_methods.rst b/Python/Dependencies/future-0.18.2/docs/custom_str_methods.rst new file mode 100644 index 0000000..12c3c6b --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/custom_str_methods.rst @@ -0,0 +1,27 @@ +.. _custom-str-methods: + +Custom __str__ methods +---------------------- + +If you define a custom ``__str__`` method for any of your classes, +functions like ``print()`` expect ``__str__`` on Py2 to return a byte +string, whereas on Py3 they expect a (unicode) string. + +Use the following decorator to map the ``__str__`` to ``__unicode__`` on +Py2 and define ``__str__`` to encode it as utf-8:: + + from future.utils import python_2_unicode_compatible + + @python_2_unicode_compatible + class MyClass(object): + def __str__(self): + return u'Unicode string: \u5b54\u5b50' + a = MyClass() + + # This then prints the name of a Chinese philosopher: + print(a) + +This decorator is identical to the decorator of the same name in +:mod:`django.utils.encoding`. + +This decorator is a no-op on Python 3. diff --git a/Python/Dependencies/future-0.18.2/docs/dev_notes.rst b/Python/Dependencies/future-0.18.2/docs/dev_notes.rst new file mode 100644 index 0000000..6985bca --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/dev_notes.rst @@ -0,0 +1,16 @@ +Notes +----- +This module only supports Python 2.7, and Python 3.4+. + +The following renames are already supported on Python 2.7 without any +additional work from us:: + + reload() -> imp.reload() + reduce() -> functools.reduce() + StringIO.StringIO -> io.StringIO + Bytes.BytesIO -> io.BytesIO + +Old things that can one day be fixed automatically by futurize.py:: + + string.uppercase -> string.ascii_uppercase # works on either Py2.7 or Py3+ + sys.maxint -> sys.maxsize # but this isn't identical diff --git a/Python/Dependencies/future-0.18.2/docs/development.rst b/Python/Dependencies/future-0.18.2/docs/development.rst new file mode 100644 index 0000000..a12f2ca --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/development.rst @@ -0,0 +1,19 @@ +.. developer-docs + +Developer docs +============== + +The easiest way to start developing ``python-future`` is as follows: + +1. Install Anaconda Python distribution + +2. Run:: + + conda install -n future2 python=2.7 pip + conda install -n future3 python=3.4 pip + + git clone https://github.com/PythonCharmers/python-future + +3. If you are using Anaconda Python distribution, this comes without a ``test`` +module on Python 2.x. Copy ``Python-2.7.6/Lib/test`` from the Python source tree +to ``~/anaconda/envs/yourenvname/lib/python2.7/site-packages/`. diff --git a/Python/Dependencies/future-0.18.2/docs/dict_object.rst b/Python/Dependencies/future-0.18.2/docs/dict_object.rst new file mode 100644 index 0000000..165cf76 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/dict_object.rst @@ -0,0 +1,92 @@ +.. _dict-object: + +dict +---- + +Python 3 dictionaries have ``.keys()``, ``.values()``, and ``.items()`` +methods which return memory-efficient set-like iterator objects, not lists. +(See `PEP 3106 <http://www.python.org/dev/peps/pep-3106/>`_.) + +If your dictionaries are small, performance is not critical, and you don't need +the set-like behaviour of iterator objects from Python 3, you can of course +stick with standard Python 3 code in your Py2/3 compatible codebase:: + + # Assuming d is a native dict ... + + for key in d: + # code here + + for item in d.items(): + # code here + + for value in d.values(): + # code here + +In this case there will be memory overhead of list creation on Py2 for each +call to ``items``, ``values`` or ``keys``. + +For improved efficiency, ``future.builtins`` (aliased to ``builtins``) provides +a Python 2 ``dict`` subclass whose :func:`keys`, :func:`values`, and +:func:`items` methods return iterators on all versions of Python >= 2.7. On +Python 2.7, these iterators also have the same set-like view behaviour as +dictionaries in Python 3. This can streamline code that iterates over large +dictionaries. For example:: + + from __future__ import print_function + from builtins import dict, range + + # Memory-efficient construction: + d = dict((i, i**2) for i in range(10**7)) + + assert not isinstance(d.items(), list) + + # Because items() is memory-efficient, so is this: + d2 = dict((v, k) for (k, v) in d.items()) + +As usual, on Python 3 ``dict`` imported from either ``builtins`` or +``future.builtins`` is just the built-in ``dict`` class. + + +Memory-efficiency and alternatives +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you already have large native dictionaries, the downside to wrapping them in +a ``dict`` call is that memory is copied (on both Py3 and on Py2). For +example:: + + # This allocates and then frees a large amount of temporary memory: + d = dict({i: i**2 for i in range(10**7)}) + +If dictionary methods like ``values`` and ``items`` are called only once, this +obviously negates the memory benefits offered by the overridden methods through +not creating temporary lists. + +The memory-efficient (and CPU-efficient) alternatives are: + +- to construct a dictionary from an iterator. The above line could use a + generator like this:: + + d = dict((i, i**2) for i in range(10**7)) + +- to construct an empty dictionary with a ``dict()`` call using + ``builtins.dict`` (rather than ``{}``) and then update it; + +- to use the ``viewitems`` etc. functions from :mod:`future.utils`, passing in + regular dictionaries:: + + from future.utils import viewkeys, viewvalues, viewitems + + for (key, value) in viewitems(hugedictionary): + # some code here + + # Set intersection: + d = {i**2: i for i in range(1000)} + both = viewkeys(d) & set(range(0, 1000, 7)) + + # Set union: + both = viewvalues(d1) | viewvalues(d2) + +For compatibility, the functions ``iteritems`` etc. are also available in +:mod:`future.utils`. These are equivalent to the functions of the same names in +``six``, which is equivalent to calling the ``iteritems`` etc. methods on +Python 2, or to calling ``items`` etc. on Python 3. diff --git a/Python/Dependencies/future-0.18.2/docs/faq.rst b/Python/Dependencies/future-0.18.2/docs/faq.rst new file mode 100644 index 0000000..9b1eab0 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/faq.rst @@ -0,0 +1,310 @@ +Frequently Asked Questions (FAQ) +******************************** + +Who is this for? +================ + +1. People with existing or new Python 3 codebases who wish to provide +ongoing Python 2.7 support easily and with little maintenance burden. + +2. People who wish to ease and accelerate migration of their Python 2 codebases +to Python 3.4+, module by module, without giving up Python 2 compatibility. + + +Why upgrade to Python 3? +======================== + +.. epigraph:: + + "Python 2 is the next COBOL." + + -- Alex Gaynor, at PyCon AU 2013 + +Python 2.7 is the end of the Python 2 line. (See `PEP 404 +<http://www.python.org/peps/pep-0404/>`_.) The language and standard +libraries are improving only in Python 3.x. + +Python 3.x is a better language and better set of standard libraries than +Python 2.x in many ways. Python 3.x is cleaner, less warty, and easier to +learn than Python 2. It has better memory efficiency, easier Unicode handling, +and powerful new features like the `asyncio +<https://docs.python.org/3/library/asyncio.html>`_ module. + +.. Unicode handling is also much easier. For example, see `this page +.. <http://pythonhosted.org/kitchen/unicode-frustrations.html>`_ +.. describing some of the problems with handling Unicode on Python 2 that +.. Python 3 mostly solves. + + +Porting philosophy +================== + +Why write Python 3-style code? +------------------------------ + +Here are some quotes: + +- "Django's developers have found that attempting to write Python 3 code + that's compatible with Python 2 is much more rewarding than the + opposite." from the `Django docs + <https://docs.djangoproject.com/en/dev/topics/python3/>`_. + +- "Thanks to Python 3 being more strict about things than Python 2 (e.g., + bytes vs. strings), the source translation [from Python 3 to 2] can be + easier and more straightforward than from Python 2 to 3. Plus it gives + you more direct experience developing in Python 3 which, since it is + the future of Python, is a good thing long-term." from the official + guide `"Porting Python 2 Code to Python 3" + <http://docs.python.org/2/howto/pyporting.html>`_ by Brett Cannon. + +- "Developer energy should be reserved for addressing real technical + difficulties associated with the Python 3 transition (like + distinguishing their 8-bit text strings from their binary data). They + shouldn't be punished with additional code changes ..." from `PEP 414 + <http://www.python.org/dev/peps/pep-0414/>`_ by Armin Ronacher and Nick + Coghlan. + + +Can't I just roll my own Py2/3 compatibility layer? +--------------------------------------------------- + +Yes, but using ``python-future`` will probably be easier and lead to cleaner +code with fewer bugs. + +Consider this quote: + +.. epigraph:: + + "Duplication of effort is wasteful, and replacing the various + home-grown approaches with a standard feature usually ends up making + things more readable, and interoperable as well." + + -- Guido van Rossum (`blog post <http://www.artima.com/weblogs/viewpost.jsp?thread=86641>`_) + + +``future`` also includes various Py2/3 compatibility tools in +:mod:`future.utils` picked from large projects (including IPython, +Django, Jinja2, Pandas), which should reduce the burden on every project to +roll its own py3k compatibility wrapper module. + + +What inspired this project? +--------------------------- + +In our Python training courses, we at `Python Charmers +<http://pythoncharmers.com>`_ faced a dilemma: teach people Python 3, which was +future-proof but not as useful to them today because of weaker 3rd-party +package support, or teach people Python 2, which was more useful today but +would require them to change their code and unlearn various habits soon. We +searched for ways to avoid polluting the world with more deprecated code, but +didn't find a good way. + +Also, in attempting to help with porting packages such as `scikit-learn +<http://scikit-learn.org>`_ to Python 3, I (Ed) was dissatisfied with how much +code cruft was necessary to introduce to support Python 2 and 3 from a single +codebase (the preferred porting option). Since backward-compatibility with +Python 2 may be necessary for at least the next 5 years, one of the promised +benefits of Python 3 -- cleaner code with fewer of Python 2's warts -- was +difficult to realize before in practice in a single codebase that supported +both platforms. + +The goal is to accelerate the uptake of Python 3 and help the strong Python +community to remain united around a single version of the language. + + +Maturity +======== + +How well has it been tested? +---------------------------- + +``future`` is used by several major projects, including `mezzanine +<http://mezzanine.jupo.org>`_ and `ObsPy <http://www.obspy.org>`_. It is also +currently being used to help with porting 800,000 lines of Python 2 code in +`Sage <http://sagemath.org>`_ to Python 2/3. + +Currently ``python-future`` has over 1000 unit tests. Many of these are straight +from the Python 3.3 and 3.4 test suites. + +In general, the ``future`` package itself is in good shape, whereas the +``futurize`` script for automatic porting is imperfect; chances are it will +require some manual cleanup afterwards. The ``past`` package also needs to be +expanded. + + +Is the API stable? +------------------ + +Not yet; ``future`` is still in beta. Where possible, we will try not to break +anything which was documented and used to work. After version 1.0 is released, +the API will not change in backward-incompatible ways until a hypothetical +version 2.0. + +.. + Are there any example of Python 2 packages ported to Python 3 using ``future`` and ``futurize``? + ------------------------------------------------------------------------------------------------ + + Yes, an example is the port of ``xlwt``, available `here + <https://github.com/python-excel/xlwt/pull/32>`_. + + The code also contains backports for several Py3 standard library + modules under ``future/standard_library/``. + + +Relationship between python-future and other compatibility tools +================================================================ + +How does this relate to ``2to3``? +--------------------------------- + +``2to3`` is a powerful and flexible tool that can produce different +styles of Python 3 code. It is, however, primarily designed for one-way +porting efforts, for projects that can leave behind Python 2 support. + +The example at the top of the `2to3 docs +<http://docs.python.org/2/library/2to3.html>`_ demonstrates this. After +transformation by ``2to3``, ``example.py`` looks like this:: + + def greet(name): + print("Hello, {0}!".format(name)) + print("What's your name?") + name = input() + greet(name) + +This is Python 3 code that, although syntactically valid on Python 2, +is semantically incorrect. On Python 2, it raises an exception for +most inputs; worse, it allows arbitrary code execution by the user +for specially crafted inputs because of the ``eval()`` executed by Python +2's ``input()`` function. + +This is not an isolated example; almost every output of ``2to3`` will need +modification to provide backward compatibility with Python 2. As an +alternative, the ``python-future`` project provides a script called +``futurize`` that is based on ``lib2to3`` but will produce code that is +compatible with both platforms (Py2 and Py3). + + +Can I maintain a Python 2 codebase and use 2to3 to automatically convert to Python 3 in the setup script? +--------------------------------------------------------------------------------------------------------- + +This was originally the approach recommended by Python's core developers, +but it has some large drawbacks: + +1. First, your actual working codebase will be stuck with Python 2's +warts and smaller feature set for as long as you need to retain Python 2 +compatibility. This may be at least 5 years for many projects, possibly +much longer. + +2. Second, this approach carries the significant disadvantage that you +cannot apply patches submitted by Python 3 users against the +auto-generated Python 3 code. (See `this talk +<http://www.youtube.com/watch?v=xNZ4OVO2Z_E>`_ by Jacob Kaplan-Moss.) + + +What is the relationship between ``future`` and ``six``? +-------------------------------------------------------- + +``python-future`` is a higher-level compatibility layer than ``six`` that +includes more backported functionality from Python 3, more forward-ported +functionality from Python 2, and supports cleaner code, but requires more +modern Python versions to run. + +``python-future`` and ``six`` share the same goal of making it possible to write +a single-source codebase that works on both Python 2 and Python 3. +``python-future`` has the further goal of allowing standard Py3 code to run with +almost no modification on both Py3 and Py2. ``future`` provides a more +complete set of support for Python 3's features, including backports of +Python 3 builtins such as the ``bytes`` object (which is very different +to Python 2's ``str`` object) and several standard library modules. + +``python-future`` supports only Python 2.7+ and Python 3.4+, whereas ``six`` +supports all versions of Python from 2.4 onwards. (See +:ref:`supported-versions`.) If you must support older Python versions, +``six`` will be essential for you. However, beware that maintaining +single-source compatibility with older Python versions is ugly and `not +fun <http://lucumr.pocoo.org/2013/5/21/porting-to-python-3-redux/>`_. + +If you can drop support for older Python versions, ``python-future`` leverages +some important features introduced into Python 2.7, such as +import hooks, and a comprehensive and well-tested set of backported +functionality, to allow you to write more idiomatic, maintainable code with +fewer compatibility hacks. + + +What is the relationship between ``python-future`` and ``python-modernize``? +---------------------------------------------------------------------------- + +``python-future`` contains, in addition to the ``future`` compatibility +package, a ``futurize`` script that is similar to ``python-modernize.py`` +in intent and design. Both are based heavily on ``2to3``. + +Whereas ``python-modernize`` converts Py2 code into a common subset of +Python 2 and 3, with ``six`` as a run-time dependency, ``futurize`` +converts either Py2 or Py3 code into (almost) standard Python 3 code, +with ``future`` as a run-time dependency. + +Because ``future`` provides more backported Py3 behaviours from ``six``, +the code resulting from ``futurize`` is more likely to work +identically on both Py3 and Py2 with less additional manual porting +effort. + + +Platform and version support +============================ + +.. _supported-versions: + +Which versions of Python does ``python-future`` support? +-------------------------------------------------------- + +Python 2.7, and 3.4+ only. + +Python 2.7 introduced many important forward-compatibility +features (such as import hooks, ``b'...'`` literals and ``__future__`` +definitions) that greatly reduce the maintenance burden for single-source +Py2/3 compatible code. ``future`` leverages these features and aims to +close the remaining gap between Python 3 and 2.7. + + +Do you support Pypy? +~~~~~~~~~~~~~~~~~~~~ + +Yes, except for the standard library import hooks (currently). Feedback +and pull requests are welcome! + + +Do you support IronPython and/or Jython? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Not sure. This would be nice... + + +.. _support: + +Support +======= + +Is there a mailing list? +------------------------ + +Yes, please ask any questions on the `python-porting +<https://mail.python.org/mailman/listinfo/python-porting>`_ mailing list. + + +.. _contributing: + +Contributing +============ + +Can I help? +----------- + +Yes please :) We welcome bug reports, additional tests, pull requests, +and stories of either success or failure with using it. Help with the fixers +for the ``futurize`` script is particularly welcome. + + +Where is the repo? +------------------ + +`<https://github.com/PythonCharmers/python-future>`_. diff --git a/Python/Dependencies/future-0.18.2/docs/func_annotations.rst b/Python/Dependencies/future-0.18.2/docs/func_annotations.rst new file mode 100644 index 0000000..a298f2c --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/func_annotations.rst @@ -0,0 +1,37 @@ +.. _func_annotations: + +Function annotations +==================== + +Function annotations are a piece of syntax introduced in Python 3.0 that was +not backported to Python 2.x. (See PEP 3107: +http://www.python.org/dev/peps/pep-3107/). They cause Python 2 to raise a +SyntaxError. + +To rewrite Python 3 code with function annotations to be compatible with both +Python 3 and Python 2, you can replace the annotation syntax with a dictionary +called ``__annotations__`` as an attribute on your functions. For example, code +such as this:: + + def _parse(self, filename: str, dir='.') -> list: + pass + +can be re-expressed like this:: + + def _parse(self, filename, dir='.'): + pass + _parse.__annotations__ = {'filename': str, 'return': list} + +As described in PEP 3107, the annotation for a function's return value +corresponds to the ``'return'`` key in the dictionary. + +(Note that PEP 3107 describes annotations as belonging to a +``func_annotations`` attribute. This attribute was renamed in Python 3.2 to +``__annotations__``.) + +Be aware that some libraries that consume function annotations, such as +`Reticulated <https://github.com/mvitousek/reticulated>`_, have their own +semantics for supporting earlier Python versions, such as decorators. If you +are using such a library, please use its own mechanism for providing +compatibility with earlier Python versions, rather than the generic equivalent +above. diff --git a/Python/Dependencies/future-0.18.2/docs/future-builtins.rst b/Python/Dependencies/future-0.18.2/docs/future-builtins.rst new file mode 100644 index 0000000..df8ff79 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/future-builtins.rst @@ -0,0 +1,17 @@ +.. _future-builtins: + +``future.builtins`` +=================== + +The ``future.builtins`` module is also accessible as ``builtins`` on Py2. + +- ``pow()`` supports fractional exponents of negative numbers like in Py3:: + + >>> from builtins import pow + >>> pow(-1, 0.5) + (6.123233995736766e-17+1j) + +- ``round()`` uses Banker's Rounding as in Py3 to the nearest even last digit:: + + >>> from builtins import round + >>> assert round(0.1250, 2) == 0.12 diff --git a/Python/Dependencies/future-0.18.2/docs/futureext.py b/Python/Dependencies/future-0.18.2/docs/futureext.py new file mode 100644 index 0000000..23471a1 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/futureext.py @@ -0,0 +1,83 @@ +# -*- coding: utf-8 -*- +""" + Python-Future Documentation Extensions + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Support for automatically documenting filters and tests. + + Based on the Jinja2 documentation extensions. + + :copyright: Copyright 2008 by Armin Ronacher. + :license: BSD. +""" +import collections +import os +import re +import inspect +from itertools import islice +from types import BuiltinFunctionType +from docutils import nodes +from docutils.statemachine import ViewList +from sphinx.ext.autodoc import prepare_docstring +from sphinx.application import TemplateBridge +from pygments.style import Style +from pygments.token import Keyword, Name, Comment, String, Error, \ + Number, Operator, Generic + + +def parse_rst(state, content_offset, doc): + node = nodes.section() + # hack around title style bookkeeping + surrounding_title_styles = state.memo.title_styles + surrounding_section_level = state.memo.section_level + state.memo.title_styles = [] + state.memo.section_level = 0 + state.nested_parse(doc, content_offset, node, match_titles=1) + state.memo.title_styles = surrounding_title_styles + state.memo.section_level = surrounding_section_level + return node.children + + +class FutureStyle(Style): + title = 'Future Style' + default_style = "" + styles = { + Comment: 'italic #0B6A94', # was: #0066ff', + Comment.Preproc: 'noitalic #B11414', + Comment.Special: 'italic #505050', + + Keyword: 'bold #D15E27', + Keyword.Type: '#D15E27', + + Operator.Word: 'bold #B80000', + + Name.Builtin: '#333333', + Name.Function: '#333333', + Name.Class: 'bold #333333', + Name.Namespace: 'bold #333333', + Name.Entity: 'bold #363636', + Name.Attribute: '#686868', + Name.Tag: 'bold #686868', + Name.Decorator: '#686868', + + String: '#AA891C', + Number: '#444444', + + Generic.Heading: 'bold #000080', + Generic.Subheading: 'bold #800080', + Generic.Deleted: '#aa0000', + Generic.Inserted: '#00aa00', + Generic.Error: '#aa0000', + Generic.Emph: 'italic', + Generic.Strong: 'bold', + Generic.Prompt: '#555555', + Generic.Output: '#888888', + Generic.Traceback: '#aa0000', + + Error: '#F00 bg:#FAA' + } + +def setup(app): + pass + # uncomment for inline toc. links are broken unfortunately + ##app.connect('doctree-resolved', inject_toc) diff --git a/Python/Dependencies/future-0.18.2/docs/futurize.rst b/Python/Dependencies/future-0.18.2/docs/futurize.rst new file mode 100644 index 0000000..11520a6 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/futurize.rst @@ -0,0 +1,314 @@ +.. _forwards-conversion: + +``futurize``: Py2 to Py2/3 +-------------------------- + +.. include:: futurize_overview.rst + + +.. _forwards-conversion-stage1: + +Stage 1: "safe" fixes +~~~~~~~~~~~~~~~~~~~~~ + +Run the first stage of the conversion process with:: + + futurize --stage1 mypackage/*.py + +or, if you are using zsh, recursively:: + + futurize --stage1 mypackage/**/*.py + +This applies fixes that modernize Python 2 code without changing the effect of +the code. With luck, this will not introduce any bugs into the code, or will at +least be trivial to fix. The changes are those that bring the Python code +up-to-date without breaking Py2 compatibility. The resulting code will be +modern Python 2.7-compatible code plus ``__future__`` imports from the +following set: + +.. code-block:: python + + from __future__ import absolute_import + from __future__ import division + from __future__ import print_function + +Only those ``__future__`` imports deemed necessary will be added unless +the ``--all-imports`` command-line option is passed to ``futurize``, in +which case they are all added. + +The ``from __future__ import unicode_literals`` declaration is not added +unless the ``--unicode-literals`` flag is passed to ``futurize``. + +The changes include:: + + - except MyException, e: + + except MyException as e: + + - print >>stderr, "Blah" + + from __future__ import print_function + + print("Blah", stderr) + + - class MyClass: + + class MyClass(object): + + - def next(self): + + def __next__(self): + + - if d.has_key(key): + + if key in d: + +Implicit relative imports fixed, e.g.:: + + - import mymodule + + from __future__ import absolute_import + + from . import mymodule + +.. and all unprefixed string literals '...' gain a b prefix to be b'...'. + +.. (This last step can be prevented using --no-bytes-literals if you already have b'...' markup in your code, whose meaning would otherwise be lost.) + +Stage 1 does not add any imports from the ``future`` package. The output of +stage 1 will probably not (yet) run on Python 3. + +The goal for this stage is to create most of the ``diff`` for the entire +porting process, but without introducing any bugs. It should be uncontroversial +and safe to apply to every Python 2 package. The subsequent patches introducing +Python 3 compatibility should then be shorter and easier to review. + +The complete set of fixers applied by ``futurize --stage1`` is: + +.. code-block:: python + + lib2to3.fixes.fix_apply + lib2to3.fixes.fix_except + lib2to3.fixes.fix_exec + lib2to3.fixes.fix_exitfunc + lib2to3.fixes.fix_funcattrs + lib2to3.fixes.fix_has_key + lib2to3.fixes.fix_idioms + lib2to3.fixes.fix_intern + lib2to3.fixes.fix_isinstance + lib2to3.fixes.fix_methodattrs + lib2to3.fixes.fix_ne + lib2to3.fixes.fix_numliterals + lib2to3.fixes.fix_paren + lib2to3.fixes.fix_reduce + lib2to3.fixes.fix_renames + lib2to3.fixes.fix_repr + lib2to3.fixes.fix_standarderror + lib2to3.fixes.fix_sys_exc + lib2to3.fixes.fix_throw + lib2to3.fixes.fix_tuple_params + lib2to3.fixes.fix_types + lib2to3.fixes.fix_ws_comma + lib2to3.fixes.fix_xreadlines + libfuturize.fixes.fix_absolute_import + libfuturize.fixes.fix_next_call + libfuturize.fixes.fix_print_with_import + libfuturize.fixes.fix_raise + +The following fixers from ``lib2to3`` are not applied: + +.. code-block:: python + + lib2to3.fixes.fix_import + +The ``fix_absolute_import`` fixer in ``libfuturize.fixes`` is applied instead of +``lib2to3.fixes.fix_import``. The new fixer both makes implicit relative +imports explicit and adds the declaration ``from __future__ import +absolute_import`` at the top of each relevant module. + +.. code-block:: python + + lib2to3.fixes.fix_next + +The ``fix_next_call`` fixer in ``libfuturize.fixes`` is applied instead of +``fix_next`` in stage 1. The new fixer changes any ``obj.next()`` calls to +``next(obj)``, which is Py2/3 compatible, but doesn't change any ``next`` method +names to ``__next__``, which would break Py2 compatibility. + +``fix_next`` is applied in stage 2. + +.. code-block:: python + + lib2to3.fixes.fix_print + +The ``fix_print_with_import`` fixer in ``libfuturize.fixes`` changes the code to +use print as a function and also adds ``from __future__ import +print_function`` to the top of modules using ``print()``. + +In addition, it avoids adding an extra set of parentheses if these already +exist. So ``print(x)`` does not become ``print((x))``. + +.. code-block:: python + + lib2to3.fixes.fix_raise + +This fixer translates code to use the Python 3-only ``with_traceback()`` +method on exceptions. + +.. code-block:: python + + lib2to3.fixes.fix_set_literal + +This converts ``set([1, 2, 3]``) to ``{1, 2, 3}``. + +.. code-block:: python + + lib2to3.fixes.fix_ws_comma + +This performs cosmetic changes. This is not applied by default because it +does not serve to improve Python 2/3 compatibility. (In some cases it may +also reduce readability: see issue #58.) + + + +.. _forwards-conversion-stage2: + +Stage 2: Py3-style code with wrappers for Py2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run stage 2 of the conversion process with:: + + futurize --stage2 myfolder/*.py + +This stage adds a dependency on the ``future`` package. The goal for stage 2 is +to make further mostly safe changes to the Python 2 code to use Python 3-style +code that then still runs on Python 2 with the help of the appropriate builtins +and utilities in ``future``. + +For example:: + + name = raw_input('What is your name?\n') + + for k, v in d.iteritems(): + assert isinstance(v, basestring) + + class MyClass(object): + def __unicode__(self): + return u'My object' + def __str__(self): + return unicode(self).encode('utf-8') + +would be converted by Stage 2 to this code:: + + from builtins import input + from builtins import str + from future.utils import iteritems, python_2_unicode_compatible + + name = input('What is your name?\n') + + for k, v in iteritems(d): + assert isinstance(v, (str, bytes)) + + @python_2_unicode_compatible + class MyClass(object): + def __str__(self): + return u'My object' + +Stage 2 also renames standard-library imports to their Py3 names and adds these +two lines:: + + from future import standard_library + standard_library.install_aliases() + +For example:: + + import ConfigParser + +becomes:: + + from future import standard_library + standard_library.install_aliases() + import configparser + +The complete list of fixers applied in Stage 2 is:: + + lib2to3.fixes.fix_dict + lib2to3.fixes.fix_filter + lib2to3.fixes.fix_getcwdu + lib2to3.fixes.fix_input + lib2to3.fixes.fix_itertools + lib2to3.fixes.fix_itertools_imports + lib2to3.fixes.fix_long + lib2to3.fixes.fix_map + lib2to3.fixes.fix_next + lib2to3.fixes.fix_nonzero + lib2to3.fixes.fix_operator + lib2to3.fixes.fix_raw_input + lib2to3.fixes.fix_zip + + libfuturize.fixes.fix_basestring + libfuturize.fixes.fix_cmp + libfuturize.fixes.fix_division_safe + libfuturize.fixes.fix_execfile + libfuturize.fixes.fix_future_builtins + libfuturize.fixes.fix_future_standard_library + libfuturize.fixes.fix_future_standard_library_urllib + libfuturize.fixes.fix_metaclass + libpasteurize.fixes.fix_newstyle + libfuturize.fixes.fix_object + libfuturize.fixes.fix_unicode_keep_u + libfuturize.fixes.fix_xrange_with_import + + +Not applied:: + + lib2to3.fixes.fix_buffer # Perhaps not safe. Test this. + lib2to3.fixes.fix_callable # Not needed in Py3.2+ + lib2to3.fixes.fix_execfile # Some problems: see issue #37. + # We use the custom libfuturize.fixes.fix_execfile instead. + lib2to3.fixes.fix_future # Removing __future__ imports is bad for Py2 compatibility! + lib2to3.fixes.fix_imports # Called by libfuturize.fixes.fix_future_standard_library + lib2to3.fixes.fix_imports2 # We don't handle this yet (dbm) + lib2to3.fixes.fix_metaclass # Causes SyntaxError in Py2! Use the one from ``six`` instead + lib2to3.fixes.fix_unicode # Strips off the u'' prefix, which removes a potentially + # helpful source of information for disambiguating + # unicode/byte strings. + lib2to3.fixes.fix_urllib # Included in libfuturize.fix_future_standard_library_urllib + lib2to3.fixes.fix_xrange # Custom one because of a bug with Py3.3's lib2to3 + + + +.. Ideally the output of this stage should not be a ``SyntaxError`` on either +.. Python 3 or Python 2. + +.. _forwards-conversion-text: + +Separating text from bytes +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After applying stage 2, the recommended step is to decide which of your Python +2 strings represent text and which represent binary data and to prefix all +string literals with either ``b`` or ``u`` accordingly. Furthermore, to ensure +that these types behave similarly on Python 2 as on Python 3, also wrap +byte-strings or text in the ``bytes`` and ``str`` types from ``future``. For +example:: + + from builtins import bytes, str + b = bytes(b'\x00ABCD') + s = str(u'This is normal text') + +Any unadorned string literals will then represent native platform strings +(byte-strings on Py2, unicode strings on Py3). + +An alternative is to pass the ``--unicode-literals`` flag:: + + $ futurize --unicode-literals mypython2script.py + +After running this, all string literals that were not explicitly marked up as +``b''`` will mean text (Python 3 ``str`` or Python 2 ``unicode``). + + + +.. _forwards-conversion-stage3: + +Post-conversion +~~~~~~~~~~~~~~~ + +After running ``futurize``, we recommend first running your tests on Python 3 and making further code changes until they pass on Python 3. + +The next step would be manually tweaking the code to re-enable Python 2 +compatibility with the help of the ``future`` package. For example, you can add +the ``@python_2_unicode_compatible`` decorator to any classes that define custom +``__str__`` methods. See :ref:`what-else` for more info. diff --git a/Python/Dependencies/future-0.18.2/docs/futurize_cheatsheet.rst b/Python/Dependencies/future-0.18.2/docs/futurize_cheatsheet.rst new file mode 100644 index 0000000..82f211c --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/futurize_cheatsheet.rst @@ -0,0 +1,124 @@ +.. _futurize_cheatsheet: + +``futurize`` quick-start guide +------------------------------ + +How to convert Py2 code to Py2/3 code using ``futurize``: + +.. _porting-setup: + +Step 0: setup +~~~~~~~~~~~~~ + +Step 0 goal: set up and see the tests passing on Python 2 and failing on Python 3. + +a. Clone the package from github/bitbucket. Optionally rename your repo to ``package-future``. Examples: ``reportlab-future``, ``paramiko-future``, ``mezzanine-future``. +b. Create and activate a Python 2 conda environment or virtualenv. Install the package with ``python setup.py install`` and run its test suite on Py2.7 (e.g. ``python setup.py test`` or ``py.test``) +c. Optionally: if there is a ``.travis.yml`` file, add Python version 3.6 and remove any versions < 2.6. +d. Install Python 3 with e.g. ``sudo apt-get install python3``. On other platforms, an easy way is to use `Miniconda <http://repo.continuum.io/miniconda/index.html>`_. Then e.g.:: + + conda create -n py36 python=3.6 pip + +.. _porting-step1: + +Step 1: modern Py2 code +~~~~~~~~~~~~~~~~~~~~~~~ + +The goal for this step is to modernize the Python 2 code without introducing any dependencies (on ``future`` or e.g. ``six``) at this stage. + +**1a**. Install ``future`` into the virtualenv using:: + + pip install future + +**1b**. Run ``futurize --stage1 -w *.py subdir1/*.py subdir2/*.py``. Note that with +recursive globbing in ``bash`` or ``zsh``, you can apply stage 1 to all source files +recursively with:: + + futurize --stage1 -w . + +**1c**. Commit all changes + +**1d**. Re-run the test suite on Py2 and fix any errors. + +See :ref:`forwards-conversion-stage1` for more info. + + +Example error +************* + +One relatively common error after conversion is:: + + Traceback (most recent call last): + ... + File "/home/user/Install/BleedingEdge/reportlab/tests/test_encrypt.py", line 19, in <module> + from .test_pdfencryption import parsedoc + ValueError: Attempted relative import in non-package + +If you get this error, try adding an empty ``__init__.py`` file in the package +directory. (In this example, in the tests/ directory.) If this doesn’t help, +and if this message appears for all tests, they must be invoked differently +(from the cmd line or e.g. ``setup.py``). The way to run a module inside a +package on Python 3, or on Python 2 with ``absolute_import`` in effect, is:: + + python -m tests.test_platypus_xref + +(For more info, see `PEP 328 <http://www.python.org/dev/peps/pep-0328/>`_ and +the `PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_ section on absolute +imports.) + + +.. _porting-step2: + +Step 2: working Py3 code that still supports Py2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The goal for this step is to get the tests passing first on Py3 and then on Py2 +again with the help of the ``future`` package. + +**2a**. Run:: + + futurize --stage2 myfolder1/*.py myfolder2/*.py + +You can view the stage 2 changes to all Python source files recursively with:: + + futurize --stage2 . + +To apply the changes, add the ``-w`` argument. + +This stage makes further conversions needed to support both Python 2 and 3. +These will likely require imports from ``future`` on Py2 (and sometimes on Py3), +such as:: + + from future import standard_library + standard_library.install_aliases() + # ... + from builtins import bytes + from builtins import open + from future.utils import with_metaclass + +Optionally, you can use the ``--unicode-literals`` flag to add this import to +the top of each module:: + + from __future__ import unicode_literals + +All strings in the module would then be unicode on Py2 (as on Py3) unless +explicitly marked with a ``b''`` prefix. + +If you would like ``futurize`` to import all the changed builtins to have their +Python 3 semantics on Python 2, invoke it like this:: + + futurize --stage2 --all-imports myfolder/*.py + + +**2b**. Re-run your tests on Py3 now. Make changes until your tests pass on Python 3. + +**2c**. Commit your changes! :) + +**2d**. Now run your tests on Python 2 and notice the errors. Add wrappers from +``future`` to re-enable Python 2 compatibility. See the +:ref:`compatible-idioms` cheat sheet and :ref:`what-else` for more info. + +After each change, re-run the tests on Py3 and Py2 to ensure they pass on both. + +**2e**. You're done! Celebrate! Push your code and announce to the world! Hashtags +#python3 #python-future. diff --git a/Python/Dependencies/future-0.18.2/docs/futurize_overview.rst b/Python/Dependencies/future-0.18.2/docs/futurize_overview.rst new file mode 100644 index 0000000..769b65c --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/futurize_overview.rst @@ -0,0 +1,55 @@ +The ``futurize`` script passes Python 2 code through all the appropriate fixers +to turn it into valid Python 3 code, and then adds ``__future__`` and +``future`` package imports to re-enable compatibility with Python 2. + +For example, running ``futurize`` turns this Python 2 code: + +.. code-block:: python + + import ConfigParser # Py2 module name + + class Upper(object): + def __init__(self, iterable): + self._iter = iter(iterable) + def next(self): # Py2-style iterator interface + return next(self._iter).upper() + def __iter__(self): + return self + + itr = Upper('hello') + print next(itr), + for letter in itr: + print letter, # Py2-style print statement + +into this code which runs on both Py2 and Py3: + +.. code-block:: python + + from __future__ import print_function + from future import standard_library + standard_library.install_aliases() + from future.builtins import next + from future.builtins import object + import configparser # Py3-style import + + class Upper(object): + def __init__(self, iterable): + self._iter = iter(iterable) + def __next__(self): # Py3-style iterator interface + return next(self._iter).upper() + def __iter__(self): + return self + + itr = Upper('hello') + print(next(itr), end=' ') # Py3-style print function + for letter in itr: + print(letter, end=' ') + + +To write out all the changes to your Python files that ``futurize`` suggests, +use the ``-w`` flag. + +For complex projects, it is probably best to divide the porting into two stages. +Stage 1 is for "safe" changes that modernize the code but do not break Python +2.7 compatibility or introduce a dependency on the ``future`` package. Stage 2 +is to complete the process. diff --git a/Python/Dependencies/future-0.18.2/docs/hindsight.rst b/Python/Dependencies/future-0.18.2/docs/hindsight.rst new file mode 100644 index 0000000..b4654c6 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/hindsight.rst @@ -0,0 +1,3 @@ +In a perfect world, the new metaclass syntax should ideally be available in +Python 2 as a `__future__`` import like ``from __future__ import +new_metaclass_syntax``. diff --git a/Python/Dependencies/future-0.18.2/docs/imports.rst b/Python/Dependencies/future-0.18.2/docs/imports.rst new file mode 100644 index 0000000..f7dcd9f --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/imports.rst @@ -0,0 +1,126 @@ +.. _imports: + +Imports +======= + +.. _-__future__-imports: + +__future__ imports +------------------ + +To write a Python 2/3 compatible codebase, the first step is to add this line +to the top of each module:: + + from __future__ import absolute_import, division, print_function + +For guidelines about whether to import ``unicode_literals`` too, see below +(:ref:`unicode-literals`). + +For more information about the ``__future__`` imports, which are a +standard feature of Python, see the following docs: + +- absolute_import: `PEP 328: Imports: Multi-Line and Absolute/Relative <http://www.python.org/dev/peps/pep-0328>`_ +- division: `PEP 238: Changing the Division Operator <http://www.python.org/dev/peps/pep-0238>`_ +- print_function: `PEP 3105: Make print a function <http://www.python.org/dev/peps/pep-3105>`_ +- unicode_literals: `PEP 3112: Bytes literals in Python 3000 <http://www.python.org/dev/peps/pep-3112>`_ + +These are all available in Python 2.7 and up, and enabled by default in Python 3.x. + + +.. _builtins-imports: + +Imports of builtins +------------------- + +.. _star-imports: + +Implicit imports +~~~~~~~~~~~~~~~~ + +If you don't mind namespace pollution, the easiest way to provide Py2/3 +compatibility for new code using ``future`` is to include the following imports +at the top of every module:: + + from builtins import * + +On Python 3, this has no effect. (It shadows builtins with globals of the same +names.) + +On Python 2, this import line shadows 18 builtins (listed below) to +provide their Python 3 semantics. + + +.. _explicit-imports: + +Explicit imports +~~~~~~~~~~~~~~~~ + +Explicit forms of the imports are often preferred and are necessary for using +certain automated code-analysis tools. + +The complete set of imports of builtins from ``future`` is:: + + from builtins import (ascii, bytes, chr, dict, filter, hex, input, + int, map, next, oct, open, pow, range, round, + str, super, zip) + +These are also available under the ``future.builtins`` namespace for backward compatibility. + +Importing only some of the builtins is cleaner but increases the risk of +introducing Py2/3 portability bugs as your code evolves over time. For example, +be aware of forgetting to import ``input``, which could expose a security +vulnerability on Python 2 if Python 3's semantics are expected. + +.. One further technical distinction is that unlike the ``import *`` form above, +.. these explicit imports do actually modify ``locals()`` on Py3; this is +.. equivalent to typing ``bytes = bytes; int = int`` etc. for each builtin. + +The internal API is currently as follows:: + + from future.types import bytes, dict, int, range, str + from future.builtins.misc import (ascii, chr, hex, input, next, + oct, open, pow, round, super) + from future.builtins.iterators import filter, map, zip + +Please note that this internal API is evolving and may not be stable between +different versions of ``future``. To understand the details of the backported +builtins on Python 2, see the docs for these modules. + +For more information on what the backported types provide, see :ref:`what-else`. + +.. < Section about past.translation is included here > + + +.. _obsolete-builtins: + +Obsolete Python 2 builtins +__________________________ + +Twelve Python 2 builtins have been removed from Python 3. To aid with +porting code to Python 3 module by module, you can use the following +import to cause a ``NameError`` exception to be raised on Python 2 when any +of the obsolete builtins is used, just as would occur on Python 3:: + + from future.builtins.disabled import * + +This is equivalent to:: + + from future.builtins.disabled import (apply, cmp, coerce, execfile, + file, long, raw_input, reduce, reload, + unicode, xrange, StandardError) + +Running ``futurize`` over code that uses these Python 2 builtins does not +import the disabled versions; instead, it replaces them with their +equivalent Python 3 forms and then adds ``future`` imports to resurrect +Python 2 support, as described in :ref:`forwards-conversion-stage2`. + + +.. include:: standard_library_imports.rst + +.. include:: translation.rst + +.. include:: unicode_literals.rst + +Next steps +---------- +See :ref:`what-else`. diff --git a/Python/Dependencies/future-0.18.2/docs/index.rst b/Python/Dependencies/future-0.18.2/docs/index.rst new file mode 100644 index 0000000..cc84c9b --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/index.rst @@ -0,0 +1,9 @@ +Easy, clean, reliable Python 2/3 compatibility +============================================== + +``python-future`` is the missing compatibility layer between Python 2 and +Python 3. It allows you to use a single, clean Python 3.x-compatible +codebase to support both Python 2 and Python 3 with minimal overhead. + + +.. include:: contents.rst.inc diff --git a/Python/Dependencies/future-0.18.2/docs/int_object.rst b/Python/Dependencies/future-0.18.2/docs/int_object.rst new file mode 100644 index 0000000..f774784 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/int_object.rst @@ -0,0 +1,68 @@ +.. _int-object: + +int +--- + +Python 3's ``int`` type is very similar to Python 2's ``long``, except +for the representation (which omits the ``L`` suffix in Python 2). Python +2's usual (short) integers have been removed from Python 3, as has the +``long`` builtin name. + +Python 3:: + + >>> 2**64 + 18446744073709551616 + +Python 2:: + + >>> 2**64 + 18446744073709551616L + +``future`` includes a backport of Python 3's ``int`` that +is a subclass of Python 2's ``long`` with the same representation +behaviour as Python 3's ``int``. To ensure an integer is long compatibly with +both Py3 and Py2, cast it like this:: + + >>> from builtins import int + >>> must_be_a_long_integer = int(1234) + +The backported ``int`` object helps with writing doctests and simplifies code +that deals with ``long`` and ``int`` as special cases on Py2. An example is the +following code from ``xlwt-future`` (called by the ``xlwt.antlr.BitSet`` class) +for writing out Excel ``.xls`` spreadsheets. With ``future``, the code is:: + + from builtins import int + + def longify(data): + """ + Turns data (an int or long, or a list of ints or longs) into a + list of longs. + """ + if not data: + return [int(0)] + if not isinstance(data, list): + return [int(data)] + return list(map(int, data)) + + +Without ``future`` (or with ``future`` < 0.7), this might be:: + + def longify(data): + """ + Turns data (an int or long, or a list of ints or longs) into a + list of longs. + """ + if not data: + if PY3: + return [0] + else: + return [long(0)] + if not isinstance(data,list): + if PY3: + return [int(data)] + else: + return [long(data)] + if PY3: + return list(map(int, data)) # same as returning data, but with up-front typechecking + else: + return list(map(long, data)) diff --git a/Python/Dependencies/future-0.18.2/docs/isinstance.rst b/Python/Dependencies/future-0.18.2/docs/isinstance.rst new file mode 100644 index 0000000..2bb5084 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/isinstance.rst @@ -0,0 +1,117 @@ +.. _isinstance-calls: + +isinstance +---------- + +The following tests all pass on Python 3:: + + >>> assert isinstance(2**62, int) + >>> assert isinstance(2**63, int) + >>> assert isinstance(b'my byte-string', bytes) + >>> assert isinstance(u'unicode string 1', str) + >>> assert isinstance('unicode string 2', str) + + +However, two of these normally fail on Python 2:: + + >>> assert isinstance(2**63, int) + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + AssertionError + + >>> assert isinstance(u'my unicode string', str) + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + AssertionError + +And if this import is in effect on Python 2:: + + >>> from __future__ import unicode_literals + +then the fifth test fails too:: + + >>> assert isinstance('unicode string 2', str) + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + AssertionError + + +After importing the builtins from ``future``, all these tests pass on +Python 2 as on Python 3:: + + >>> from builtins import bytes, int, str + + >>> assert isinstance(10, int) + >>> assert isinstance(10**100, int) + >>> assert isinstance(b'my byte-string', bytes) + >>> assert isinstance(u'unicode string 1', str) + +However, note that the last test requires that ``unicode_literals`` be imported to succeed.:: + + >>> from __future__ import unicode_literals + >>> assert isinstance('unicode string 2', str) + +This works because the backported types ``int``, ``bytes`` and ``str`` +(and others) have metaclasses that override ``__instancecheck__``. See `PEP 3119 +<http://www.python.org/dev/peps/pep-3119/#overloading-isinstance-and-issubclass>`_ +for details. + + +Passing data to/from Python 2 libraries +--------------------------------------- + +If you are passing any of the backported types (``bytes``, ``int``, ``dict, +``str``) into brittle library code that performs type-checks using ``type()``, +rather than ``isinstance()``, or requires that you pass Python 2's native types +(rather than subclasses) for some other reason, it may be necessary to upcast +the types from ``future`` to their native superclasses on Py2. + +The ``native`` function in ``future.utils`` is provided for this. Here is how +to use it. (The output showing is from Py2):: + + >>> from builtins import int, bytes, str + >>> from future.utils import native + + >>> a = int(10**20) # Py3-like long int + >>> a + 100000000000000000000 + >>> type(a) + future.types.newint.newint + >>> native(a) + 100000000000000000000L + >>> type(native(a)) + long + + >>> b = bytes(b'ABC') + >>> type(b) + future.types.newbytes.newbytes + >>> native(b) + 'ABC' + >>> type(native(b)) + str + + >>> s = str(u'ABC') + >>> type(s) + future.types.newstr.newstr + >>> native(s) + u'ABC' + >>> type(native(s)) + unicode + +On Py3, the :func:`native` function is a no-op. + + +Native string type +------------------ + +Some library code, include standard library code like the ``array.array()`` +constructor, require native strings on Python 2 and Python 3. This means that +there is no simple way to pass the appropriate string type when the +``unicode_literals`` import from ``__future__`` is in effect. + +The objects ``native_str`` and ``native_bytes`` are available in +``future.utils`` for this case. These are equivalent to the ``str`` and +``bytes`` objects in ``__builtin__`` on Python 2 or in ``builtins`` on Python 3. + +The functions ``native_str_to_bytes`` and ``bytes_to_native_str`` are also +available for more explicit conversions. diff --git a/Python/Dependencies/future-0.18.2/docs/limitations.rst b/Python/Dependencies/future-0.18.2/docs/limitations.rst new file mode 100644 index 0000000..0d13805 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/limitations.rst @@ -0,0 +1,52 @@ +limitations of the ``future`` module and differences between Py2 and Py3 that are not (yet) handled +=================================================================================================== + +The following attributes on functions in Python 3 are not provided in Python +2.7: + +__func__: see six.get_method_function() +__self__: see six.get_method_self() +__self__.__class__ + + +Limitations of the ``futurize`` script +-------------------------------------- +The ``futurize`` script is not yet mature; like ``2to3``, on which it is based, +it makes mistakes. Nevertheless, it should be useful for automatically +performing a lot of the repetitive code-substitution tasks when porting from +Py2 to Py2/3. + +Some new Python 3.3 features that cause SyntaxErrors on earlier versions +are not currently handled by the ``futurize`` script. This includes: + +- ``yield ... from`` syntax for generators in Py3.3 + +- ``raise ... from`` syntax for exceptions. (This is simple to fix + manually by creating a temporary variable.) + +Also: + +- Usage of ``file('myfile', 'w')`` as a synonym for ``open`` doesn't seem + to be converted currently. + +- ``isinstance(var, basestring)`` should sometimes be converted to + ``isinstance(var, str) or isinstance(var, bytes)``, or sometimes simply + ``isinstance(var, str)``, depending on the context. Currently it is always + converted to ``isinstance(var, str)``. + +- Caveats with bytes indexing!:: + + b'\x00'[0] != 0 + b'\x01'[0] != 1 + + ``futurize`` does not yet wrap all byte-string literals in a ``bytes()`` + call. This is on the to-do list. See :ref:`bytes-object` for more information. + + +Notes +----- +- Ensure you are using new-style classes on Py2. Py3 doesn't require + inheritance from ``object`` for this, but Py2 does. ``pasteurize`` + adds this back in automatically, but ensure you do this too + when writing your classes, otherwise weird breakage when e.g. calling + ``super()`` may occur. diff --git a/Python/Dependencies/future-0.18.2/docs/metaclasses.rst b/Python/Dependencies/future-0.18.2/docs/metaclasses.rst new file mode 100644 index 0000000..d40c5a4 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/metaclasses.rst @@ -0,0 +1,18 @@ +Metaclasses +----------- + +Python 3 and Python 2 syntax for metaclasses are incompatible. +``future`` provides a function (from ``jinja2/_compat.py``) called +:func:`with_metaclass` that can assist with specifying metaclasses +portably across Py3 and Py2. Use it like this:: + + from future.utils import with_metaclass + + class BaseForm(object): + pass + + class FormType(type): + pass + + class Form(with_metaclass(FormType, BaseForm)): + pass diff --git a/Python/Dependencies/future-0.18.2/docs/notebooks/Writing Python 2-3 compatible code.ipynb b/Python/Dependencies/future-0.18.2/docs/notebooks/Writing Python 2-3 compatible code.ipynb new file mode 100644 index 0000000..0f585d2 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/notebooks/Writing Python 2-3 compatible code.ipynb @@ -0,0 +1,3167 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Cheat Sheet: Writing Python 2-3 compatible code" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "- **Copyright (c):** 2013-2019 Python Charmers Pty Ltd, Australia.\n", + "- **Author:** Ed Schofield.\n", + "- **Licence:** Creative Commons Attribution.\n", + "\n", + "A PDF version is here: http://python-future.org/compatible_idioms.pdf\n", + "\n", + "This notebook shows you idioms for writing future-proof code that is compatible with both versions of Python: 2 and 3. It accompanies Ed Schofield's talk at PyCon AU 2014, \"Writing 2/3 compatible code\". (The video is here: <http://www.youtube.com/watch?v=KOqk8j11aAI&t=10m14s>.)\n", + "\n", + "Minimum versions:\n", + "\n", + " - Python 2: 2.6+\n", + " - Python 3: 3.3+" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Setup" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The imports below refer to these ``pip``-installable packages on PyPI:\n", + "\n", + " import future # pip install future\n", + " import builtins # pip install future\n", + " import past # pip install future\n", + " import six # pip install six\n", + "\n", + "The following scripts are also ``pip``-installable:\n", + "\n", + " futurize # pip install future\n", + " pasteurize # pip install future\n", + "\n", + "See http://python-future.org and https://pythonhosted.org/six/ for more information." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Essential syntax differences" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### print" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "print 'Hello'" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "print('Hello')" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To print multiple strings, import ``print_function`` to prevent Py2 from interpreting it as a tuple:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "print 'Hello', 'Guido'" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "from __future__ import print_function # (at top of module)\n", + "\n", + "print('Hello', 'Guido')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "print >> sys.stderr, 'Hello'" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "from __future__ import print_function\n", + "\n", + "print('Hello', file=sys.stderr)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "print 'Hello'," + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "from __future__ import print_function\n", + "\n", + "print('Hello', end='')" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Raising exceptions" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "raise ValueError, \"dodgy value\"" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "raise ValueError(\"dodgy value\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Raising exceptions with a traceback:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "traceback = sys.exc_info()[2]\n", + "raise ValueError, \"dodgy value\", traceback" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 3 only:\n", + "raise ValueError(\"dodgy value\").with_traceback()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 1\n", + "from six import reraise as raise_\n", + "# or\n", + "from future.utils import raise_\n", + "\n", + "traceback = sys.exc_info()[2]\n", + "raise_(ValueError, \"dodgy value\", traceback)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 2\n", + "from future.utils import raise_with_traceback\n", + "\n", + "raise_with_traceback(ValueError(\"dodgy value\"))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Exception chaining (PEP 3134):" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Setup:\n", + "class DatabaseError(Exception):\n", + " pass" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 3 only\n", + "class FileDatabase:\n", + " def __init__(self, filename):\n", + " try:\n", + " self.file = open(filename)\n", + " except IOError as exc:\n", + " raise DatabaseError('failed to open') from exc" + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "from future.utils import raise_from\n", + "\n", + "class FileDatabase:\n", + " def __init__(self, filename):\n", + " try:\n", + " self.file = open(filename)\n", + " except IOError as exc:\n", + " raise_from(DatabaseError('failed to open'), exc)" + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Testing the above:\n", + "try:\n", + " fd = FileDatabase('non_existent_file.txt')\n", + "except Exception as e:\n", + " assert isinstance(e.__cause__, IOError) # FileNotFoundError on Py3.3+ inherits from IOError" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Catching exceptions" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "try:\n", + " ...\n", + "except ValueError, e:\n", + " ..." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "try:\n", + " ...\n", + "except ValueError as e:\n", + " ..." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Division" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Integer division (rounding down):" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "assert 2 / 3 == 0" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "assert 2 // 3 == 0" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\"True division\" (float division):" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 3 only:\n", + "assert 3 / 2 == 1.5" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "from __future__ import division # (at top of module)\n", + "\n", + "assert 3 / 2 == 1.5" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\"Old division\" (i.e. compatible with Py2 behaviour):" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "a = b / c # with any types" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "from past.utils import old_div\n", + "\n", + "a = old_div(b, c) # always same as / on Py2" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Long integers" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Short integers are gone in Python 3 and ``long`` has become ``int`` (without the trailing ``L`` in the ``repr``)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only\n", + "k = 9223372036854775808L\n", + "\n", + "# Python 2 and 3:\n", + "k = 9223372036854775808" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only\n", + "bigint = 1L\n", + "\n", + "# Python 2 and 3\n", + "from builtins import int\n", + "bigint = int(1)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To test whether a value is an integer (of any kind):" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "if isinstance(x, (int, long)):\n", + " ...\n", + "\n", + "# Python 3 only:\n", + "if isinstance(x, int):\n", + " ...\n", + "\n", + "# Python 2 and 3: option 1\n", + "from builtins import int # subclass of long on Py2\n", + "\n", + "if isinstance(x, int): # matches both int and long on Py2\n", + " ...\n", + "\n", + "# Python 2 and 3: option 2\n", + "from past.builtins import long\n", + "\n", + "if isinstance(x, (int, long)):\n", + " ..." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Octal constants" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "0644 # Python 2 only" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "0o644 # Python 2 and 3" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Backtick repr" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "`x` # Python 2 only" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "repr(x) # Python 2 and 3" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Metaclasses" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "class BaseForm(object):\n", + " pass\n", + "\n", + "class FormType(type):\n", + " pass" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "class Form(BaseForm):\n", + " __metaclass__ = FormType\n", + " pass" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 3 only:\n", + "class Form(BaseForm, metaclass=FormType):\n", + " pass" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "from six import with_metaclass\n", + "# or\n", + "from future.utils import with_metaclass\n", + "\n", + "class Form(with_metaclass(FormType, BaseForm)):\n", + " pass" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Strings and bytes" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Unicode (text) string literals" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If you are upgrading an existing Python 2 codebase, it may be preferable to mark up all string literals as unicode explicitly with ``u`` prefixes:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only\n", + "s1 = 'The Zen of Python'\n", + "s2 = u'きたないのよりきれいな方がいい\\n'\n", + "\n", + "# Python 2 and 3\n", + "s1 = u'The Zen of Python'\n", + "s2 = u'きたないのよりきれいな方がいい\\n'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The ``futurize`` and ``python-modernize`` tools do not currently offer an option to do this automatically." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If you are writing code for a new project or new codebase, you can use this idiom to make all string literals in a module unicode strings:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3\n", + "from __future__ import unicode_literals # at top of module\n", + "\n", + "s1 = 'The Zen of Python'\n", + "s2 = 'きたないのよりきれいな方がいい\\n'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "See http://python-future.org/unicode_literals.html for more discussion on which style to use." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Byte-string literals" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only\n", + "s = 'This must be a byte-string'\n", + "\n", + "# Python 2 and 3\n", + "s = b'This must be a byte-string'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To loop over a byte-string with possible high-bit characters, obtaining each character as a byte-string of length 1:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "for bytechar in 'byte-string with high-bit chars like \\xf9':\n", + " ...\n", + "\n", + "# Python 3 only:\n", + "for myint in b'byte-string with high-bit chars like \\xf9':\n", + " bytechar = bytes([myint])\n", + "\n", + "# Python 2 and 3:\n", + "from builtins import bytes\n", + "for myint in bytes(b'byte-string with high-bit chars like \\xf9'):\n", + " bytechar = bytes([myint])" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "As an alternative, ``chr()`` and ``.encode('latin-1')`` can be used to convert an int into a 1-char byte string:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 3 only:\n", + "for myint in b'byte-string with high-bit chars like \\xf9':\n", + " char = chr(myint) # returns a unicode string\n", + " bytechar = char.encode('latin-1')\n", + "\n", + "# Python 2 and 3:\n", + "from builtins import bytes, chr\n", + "for myint in bytes(b'byte-string with high-bit chars like \\xf9'):\n", + " char = chr(myint) # returns a unicode string\n", + " bytechar = char.encode('latin-1') # forces returning a byte str" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### basestring" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "a = u'abc'\n", + "b = 'def'\n", + "assert (isinstance(a, basestring) and isinstance(b, basestring))\n", + "\n", + "# Python 2 and 3: alternative 1\n", + "from past.builtins import basestring # pip install future\n", + "\n", + "a = u'abc'\n", + "b = b'def'\n", + "assert (isinstance(a, basestring) and isinstance(b, basestring))" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 2: refactor the code to avoid considering\n", + "# byte-strings as strings.\n", + "\n", + "from builtins import str\n", + "a = u'abc'\n", + "b = b'def'\n", + "c = b.decode()\n", + "assert isinstance(a, str) and isinstance(c, str)\n", + "# ..." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### unicode" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "templates = [u\"blog/blog_post_detail_%s.html\" % unicode(slug)]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 1\n", + "from builtins import str\n", + "templates = [u\"blog/blog_post_detail_%s.html\" % str(slug)]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 2\n", + "from builtins import str as text\n", + "templates = [u\"blog/blog_post_detail_%s.html\" % text(slug)]" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### StringIO" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "from StringIO import StringIO\n", + "# or:\n", + "from cStringIO import StringIO\n", + "\n", + "# Python 2 and 3:\n", + "from io import BytesIO # for handling byte strings\n", + "from io import StringIO # for handling unicode strings" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Imports relative to a package" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Suppose the package is:\n", + "\n", + " mypackage/\n", + " __init__.py\n", + " submodule1.py\n", + " submodule2.py\n", + " \n", + "and the code below is in ``submodule1.py``:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only: \n", + "import submodule2" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "from . import submodule2" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "# To make Py2 code safer (more like Py3) by preventing\n", + "# implicit relative imports, you can also add this to the top:\n", + "from __future__ import absolute_import" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Dictionaries" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "heights = {'Fred': 175, 'Anne': 166, 'Joe': 192}" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Iterating through ``dict`` keys/values/items" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Iterable dict keys:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "for key in heights.iterkeys():\n", + " ..." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "for key in heights:\n", + " ..." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Iterable dict values:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "for value in heights.itervalues():\n", + " ..." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Idiomatic Python 3\n", + "for value in heights.values(): # extra memory overhead on Py2\n", + " ..." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 1\n", + "from builtins import dict\n", + "\n", + "heights = dict(Fred=175, Anne=166, Joe=192)\n", + "for key in heights.values(): # efficient on Py2 and Py3\n", + " ..." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 2\n", + "from future.utils import itervalues\n", + "# or\n", + "from six import itervalues\n", + "\n", + "for key in itervalues(heights):\n", + " ..." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Iterable dict items:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "for (key, value) in heights.iteritems():\n", + " ..." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 1\n", + "for (key, value) in heights.items(): # inefficient on Py2 \n", + " ..." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 2\n", + "from future.utils import viewitems\n", + "\n", + "for (key, value) in viewitems(heights): # also behaves like a set\n", + " ..." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 3\n", + "from future.utils import iteritems\n", + "# or\n", + "from six import iteritems\n", + "\n", + "for (key, value) in iteritems(heights):\n", + " ..." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### dict keys/values/items as a list" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "dict keys as a list:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "keylist = heights.keys()\n", + "assert isinstance(keylist, list)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "keylist = list(heights)\n", + "assert isinstance(keylist, list)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "dict values as a list:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "heights = {'Fred': 175, 'Anne': 166, 'Joe': 192}\n", + "valuelist = heights.values()\n", + "assert isinstance(valuelist, list)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 1\n", + "valuelist = list(heights.values()) # inefficient on Py2" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 2\n", + "from builtins import dict\n", + "\n", + "heights = dict(Fred=175, Anne=166, Joe=192)\n", + "valuelist = list(heights.values())" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 3\n", + "from future.utils import listvalues\n", + "\n", + "valuelist = listvalues(heights)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 4\n", + "from future.utils import itervalues\n", + "# or\n", + "from six import itervalues\n", + "\n", + "valuelist = list(itervalues(heights))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "dict items as a list:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 1\n", + "itemlist = list(heights.items()) # inefficient on Py2" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 2\n", + "from future.utils import listitems\n", + "\n", + "itemlist = listitems(heights)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 3\n", + "from future.utils import iteritems\n", + "# or\n", + "from six import iteritems\n", + "\n", + "itemlist = list(iteritems(heights))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Custom class behaviour" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Custom iterators" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only\n", + "class Upper(object):\n", + " def __init__(self, iterable):\n", + " self._iter = iter(iterable)\n", + " def next(self): # Py2-style\n", + " return self._iter.next().upper()\n", + " def __iter__(self):\n", + " return self\n", + "\n", + "itr = Upper('hello')\n", + "assert itr.next() == 'H' # Py2-style\n", + "assert list(itr) == list('ELLO')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 1\n", + "from builtins import object\n", + "\n", + "class Upper(object):\n", + " def __init__(self, iterable):\n", + " self._iter = iter(iterable)\n", + " def __next__(self): # Py3-style iterator interface\n", + " return next(self._iter).upper() # builtin next() function calls\n", + " def __iter__(self):\n", + " return self\n", + "\n", + "itr = Upper('hello')\n", + "assert next(itr) == 'H' # compatible style\n", + "assert list(itr) == list('ELLO')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 2\n", + "from future.utils import implements_iterator\n", + "\n", + "@implements_iterator\n", + "class Upper(object):\n", + " def __init__(self, iterable):\n", + " self._iter = iter(iterable)\n", + " def __next__(self): # Py3-style iterator interface\n", + " return next(self._iter).upper() # builtin next() function calls\n", + " def __iter__(self):\n", + " return self\n", + "\n", + "itr = Upper('hello')\n", + "assert next(itr) == 'H'\n", + "assert list(itr) == list('ELLO')" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Custom ``__str__`` methods" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "class MyClass(object):\n", + " def __unicode__(self):\n", + " return 'Unicode string: \\u5b54\\u5b50'\n", + " def __str__(self):\n", + " return unicode(self).encode('utf-8')\n", + "\n", + "a = MyClass()\n", + "print(a) # prints encoded string" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": { + "collapsed": false + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Unicode string: 孔子\n" + ] + } + ], + "source": [ + "# Python 2 and 3:\n", + "from future.utils import python_2_unicode_compatible\n", + "\n", + "@python_2_unicode_compatible\n", + "class MyClass(object):\n", + " def __str__(self):\n", + " return u'Unicode string: \\u5b54\\u5b50'\n", + "\n", + "a = MyClass()\n", + "print(a) # prints string encoded as utf-8 on Py2" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Custom ``__nonzero__`` vs ``__bool__`` method:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "class AllOrNothing(object):\n", + " def __init__(self, l):\n", + " self.l = l\n", + " def __nonzero__(self):\n", + " return all(self.l)\n", + "\n", + "container = AllOrNothing([0, 100, 200])\n", + "assert not bool(container)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "from builtins import object\n", + "\n", + "class AllOrNothing(object):\n", + " def __init__(self, l):\n", + " self.l = l\n", + " def __bool__(self):\n", + " return all(self.l)\n", + "\n", + "container = AllOrNothing([0, 100, 200])\n", + "assert not bool(container)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Lists versus iterators" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### xrange" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "for i in xrange(10**8):\n", + " ..." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: forward-compatible\n", + "from builtins import range\n", + "for i in range(10**8):\n", + " ..." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: backward-compatible\n", + "from past.builtins import xrange\n", + "for i in xrange(10**8):\n", + " ..." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### range" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only\n", + "mylist = range(5)\n", + "assert mylist == [0, 1, 2, 3, 4]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: forward-compatible: option 1\n", + "mylist = list(range(5)) # copies memory on Py2\n", + "assert mylist == [0, 1, 2, 3, 4]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: forward-compatible: option 2\n", + "from builtins import range\n", + "\n", + "mylist = list(range(5))\n", + "assert mylist == [0, 1, 2, 3, 4]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 3\n", + "from future.utils import lrange\n", + "\n", + "mylist = lrange(5)\n", + "assert mylist == [0, 1, 2, 3, 4]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: backward compatible\n", + "from past.builtins import range\n", + "\n", + "mylist = range(5)\n", + "assert mylist == [0, 1, 2, 3, 4]" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### map" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "mynewlist = map(f, myoldlist)\n", + "assert mynewlist == [f(x) for x in myoldlist]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 1\n", + "# Idiomatic Py3, but inefficient on Py2\n", + "mynewlist = list(map(f, myoldlist))\n", + "assert mynewlist == [f(x) for x in myoldlist]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 2\n", + "from builtins import map\n", + "\n", + "mynewlist = list(map(f, myoldlist))\n", + "assert mynewlist == [f(x) for x in myoldlist]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 3\n", + "try:\n", + " from itertools import imap as map\n", + "except ImportError:\n", + " pass\n", + "\n", + "mynewlist = list(map(f, myoldlist)) # inefficient on Py2\n", + "assert mynewlist == [f(x) for x in myoldlist]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 4\n", + "from future.utils import lmap\n", + "\n", + "mynewlist = lmap(f, myoldlist)\n", + "assert mynewlist == [f(x) for x in myoldlist]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 5\n", + "from past.builtins import map\n", + "\n", + "mynewlist = map(f, myoldlist)\n", + "assert mynewlist == [f(x) for x in myoldlist]" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### imap" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "from itertools import imap\n", + "\n", + "myiter = imap(func, myoldlist)\n", + "assert isinstance(myiter, iter)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 3 only:\n", + "myiter = map(func, myoldlist)\n", + "assert isinstance(myiter, iter)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 1\n", + "from builtins import map\n", + "\n", + "myiter = map(func, myoldlist)\n", + "assert isinstance(myiter, iter)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 2\n", + "try:\n", + " from itertools import imap as map\n", + "except ImportError:\n", + " pass\n", + "\n", + "myiter = map(func, myoldlist)\n", + "assert isinstance(myiter, iter)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### zip, izip" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "As above with ``zip`` and ``itertools.izip``." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### filter, ifilter" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "As above with ``filter`` and ``itertools.ifilter`` too." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Other builtins" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### File IO with open()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": true + }, + "outputs": [], + "source": [ + "# Python 2 only\n", + "f = open('myfile.txt')\n", + "data = f.read() # as a byte string\n", + "text = data.decode('utf-8')\n", + "\n", + "# Python 2 and 3: alternative 1\n", + "from io import open\n", + "f = open('myfile.txt', 'rb')\n", + "data = f.read() # as bytes\n", + "text = data.decode('utf-8') # unicode, not bytes\n", + "\n", + "# Python 2 and 3: alternative 2\n", + "from io import open\n", + "f = open('myfile.txt', encoding='utf-8')\n", + "text = f.read() # unicode, not bytes" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### reduce()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "assert reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) == 1+2+3+4+5" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "from functools import reduce\n", + "\n", + "assert reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) == 1+2+3+4+5" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### raw_input()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "name = raw_input('What is your name? ')\n", + "assert isinstance(name, str) # native str" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "from builtins import input\n", + "\n", + "name = input('What is your name? ')\n", + "assert isinstance(name, str) # native str on Py2 and Py3" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### input()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "input(\"Type something safe please: \")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3\n", + "from builtins import input\n", + "eval(input(\"Type something safe please: \"))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Warning: using either of these is **unsafe** with untrusted input." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### file()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "f = file(pathname)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "f = open(pathname)\n", + "\n", + "# But preferably, use this:\n", + "from io import open\n", + "f = open(pathname, 'rb') # if f.read() should return bytes\n", + "# or\n", + "f = open(pathname, 'rt') # if f.read() should return unicode text" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### exec" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": true + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "exec 'x = 10'\n", + "\n", + "# Python 2 and 3:\n", + "exec('x = 10')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": true + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "g = globals()\n", + "exec 'x = 10' in g\n", + "\n", + "# Python 2 and 3:\n", + "g = globals()\n", + "exec('x = 10', g)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": true + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "l = locals()\n", + "exec 'x = 10' in g, l\n", + "\n", + "# Python 2 and 3:\n", + "exec('x = 10', g, l)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "But note that Py3's `exec()` is less powerful (and less dangerous) than Py2's `exec` statement." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### execfile()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "execfile('myfile.py')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 1\n", + "from past.builtins import execfile\n", + "\n", + "execfile('myfile.py')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 2\n", + "exec(compile(open('myfile.py').read()))\n", + "\n", + "# This can sometimes cause this:\n", + "# SyntaxError: function ... uses import * and bare exec ...\n", + "# See https://github.com/PythonCharmers/python-future/issues/37" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### unichr()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "assert unichr(8364) == '€'" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 3 only:\n", + "assert chr(8364) == '€'" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "from builtins import chr\n", + "assert chr(8364) == '€'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### intern()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "intern('mystring')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 3 only:\n", + "from sys import intern\n", + "intern('mystring')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 1\n", + "from past.builtins import intern\n", + "intern('mystring')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 2\n", + "from six.moves import intern\n", + "intern('mystring')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 3\n", + "from future.standard_library import install_aliases\n", + "install_aliases()\n", + "from sys import intern\n", + "intern('mystring')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 2\n", + "try:\n", + " from sys import intern\n", + "except ImportError:\n", + " pass\n", + "intern('mystring')" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### apply()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "args = ('a', 'b')\n", + "kwargs = {'kwarg1': True}" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "apply(f, args, kwargs)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 1\n", + "f(*args, **kwargs)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 2\n", + "from past.builtins import apply\n", + "apply(f, args, kwargs)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### chr()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "assert chr(64) == b'@'\n", + "assert chr(200) == b'\\xc8'" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 3 only: option 1\n", + "assert chr(64).encode('latin-1') == b'@'\n", + "assert chr(0xc8).encode('latin-1') == b'\\xc8'" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 1\n", + "from builtins import chr\n", + "\n", + "assert chr(64).encode('latin-1') == b'@'\n", + "assert chr(0xc8).encode('latin-1') == b'\\xc8'" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 3 only: option 2\n", + "assert bytes([64]) == b'@'\n", + "assert bytes([0xc8]) == b'\\xc8'" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: option 2\n", + "from builtins import bytes\n", + "\n", + "assert bytes([64]) == b'@'\n", + "assert bytes([0xc8]) == b'\\xc8'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### cmp()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "assert cmp('a', 'b') < 0 and cmp('b', 'a') > 0 and cmp('c', 'c') == 0" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 1\n", + "from past.builtins import cmp\n", + "assert cmp('a', 'b') < 0 and cmp('b', 'a') > 0 and cmp('c', 'c') == 0" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 2\n", + "cmp = lambda(x, y): (x > y) - (x < y)\n", + "assert cmp('a', 'b') < 0 and cmp('b', 'a') > 0 and cmp('c', 'c') == 0" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### reload()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "reload(mymodule)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3\n", + "from imp import reload\n", + "reload(mymodule)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Standard library" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### dbm modules" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only\n", + "import anydbm\n", + "import whichdb\n", + "import dbm\n", + "import dumbdbm\n", + "import gdbm\n", + "\n", + "# Python 2 and 3: alternative 1\n", + "from future import standard_library\n", + "standard_library.install_aliases()\n", + "\n", + "import dbm\n", + "import dbm.ndbm\n", + "import dbm.dumb\n", + "import dbm.gnu\n", + "\n", + "# Python 2 and 3: alternative 2\n", + "from future.moves import dbm\n", + "from future.moves.dbm import dumb\n", + "from future.moves.dbm import ndbm\n", + "from future.moves.dbm import gnu\n", + "\n", + "# Python 2 and 3: alternative 3\n", + "from six.moves import dbm_gnu\n", + "# (others not supported)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### commands / subprocess modules" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only\n", + "from commands import getoutput, getstatusoutput\n", + "\n", + "# Python 2 and 3\n", + "from future import standard_library\n", + "standard_library.install_aliases()\n", + "\n", + "from subprocess import getoutput, getstatusoutput" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### subprocess.check_output()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2.7 and above\n", + "from subprocess import check_output\n", + "\n", + "# Python 2.6 and above: alternative 1\n", + "from future.moves.subprocess import check_output\n", + "\n", + "# Python 2.6 and above: alternative 2\n", + "from future import standard_library\n", + "standard_library.install_aliases()\n", + "\n", + "from subprocess import check_output" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### collections: Counter, OrderedDict, ChainMap" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2.7 and above\n", + "from collections import Counter, OrderedDict, ChainMap\n", + "\n", + "# Python 2.6 and above: alternative 1\n", + "from future.backports import Counter, OrderedDict, ChainMap\n", + "\n", + "# Python 2.6 and above: alternative 2\n", + "from future import standard_library\n", + "standard_library.install_aliases()\n", + "\n", + "from collections import Counter, OrderedDict, ChainMap" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### StringIO module" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only\n", + "from StringIO import StringIO\n", + "from cStringIO import StringIO" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3\n", + "from io import BytesIO\n", + "# and refactor StringIO() calls to BytesIO() if passing byte-strings" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### http module" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "import httplib\n", + "import Cookie\n", + "import cookielib\n", + "import BaseHTTPServer\n", + "import SimpleHTTPServer\n", + "import CGIHttpServer\n", + "\n", + "# Python 2 and 3 (after ``pip install future``):\n", + "import http.client\n", + "import http.cookies\n", + "import http.cookiejar\n", + "import http.server" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### xmlrpc module" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "import DocXMLRPCServer\n", + "import SimpleXMLRPCServer\n", + "\n", + "# Python 2 and 3 (after ``pip install future``):\n", + "import xmlrpc.server" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "import xmlrpclib\n", + "\n", + "# Python 2 and 3 (after ``pip install future``):\n", + "import xmlrpc.client" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### html escaping and entities" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3:\n", + "from cgi import escape\n", + "\n", + "# Safer (Python 2 and 3, after ``pip install future``):\n", + "from html import escape\n", + "\n", + "# Python 2 only:\n", + "from htmlentitydefs import codepoint2name, entitydefs, name2codepoint\n", + "\n", + "# Python 2 and 3 (after ``pip install future``):\n", + "from html.entities import codepoint2name, entitydefs, name2codepoint" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### html parsing" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "from HTMLParser import HTMLParser\n", + "\n", + "# Python 2 and 3 (after ``pip install future``)\n", + "from html.parser import HTMLParser\n", + "\n", + "# Python 2 and 3 (alternative 2):\n", + "from future.moves.html.parser import HTMLParser" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### urllib module" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "``urllib`` is the hardest module to use from Python 2/3 compatible code. You may like to use Requests (http://python-requests.org) instead." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "from urlparse import urlparse\n", + "from urllib import urlencode\n", + "from urllib2 import urlopen, Request, HTTPError" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 3 only:\n", + "from urllib.parse import urlparse, urlencode\n", + "from urllib.request import urlopen, Request\n", + "from urllib.error import HTTPError" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: easiest option\n", + "from future.standard_library import install_aliases\n", + "install_aliases()\n", + "\n", + "from urllib.parse import urlparse, urlencode\n", + "from urllib.request import urlopen, Request\n", + "from urllib.error import HTTPError" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 2\n", + "from future.standard_library import hooks\n", + "\n", + "with hooks():\n", + " from urllib.parse import urlparse, urlencode\n", + " from urllib.request import urlopen, Request\n", + " from urllib.error import HTTPError" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 3\n", + "from future.moves.urllib.parse import urlparse, urlencode\n", + "from future.moves.urllib.request import urlopen, Request\n", + "from future.moves.urllib.error import HTTPError\n", + "# or\n", + "from six.moves.urllib.parse import urlparse, urlencode\n", + "from six.moves.urllib.request import urlopen\n", + "from six.moves.urllib.error import HTTPError" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 and 3: alternative 4\n", + "try:\n", + " from urllib.parse import urlparse, urlencode\n", + " from urllib.request import urlopen, Request\n", + " from urllib.error import HTTPError\n", + "except ImportError:\n", + " from urlparse import urlparse\n", + " from urllib import urlencode\n", + " from urllib2 import urlopen, Request, HTTPError" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Tkinter" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "import Tkinter\n", + "import Dialog\n", + "import FileDialog\n", + "import ScrolledText\n", + "import SimpleDialog\n", + "import Tix \n", + "import Tkconstants\n", + "import Tkdnd \n", + "import tkColorChooser\n", + "import tkCommonDialog\n", + "import tkFileDialog\n", + "import tkFont\n", + "import tkMessageBox\n", + "import tkSimpleDialog\n", + "import ttk\n", + "\n", + "# Python 2 and 3 (after ``pip install future``):\n", + "import tkinter\n", + "import tkinter.dialog\n", + "import tkinter.filedialog\n", + "import tkinter.scrolledtext\n", + "import tkinter.simpledialog\n", + "import tkinter.tix\n", + "import tkinter.constants\n", + "import tkinter.dnd\n", + "import tkinter.colorchooser\n", + "import tkinter.commondialog\n", + "import tkinter.filedialog\n", + "import tkinter.font\n", + "import tkinter.messagebox\n", + "import tkinter.simpledialog\n", + "import tkinter.ttk" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### socketserver" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "import SocketServer\n", + "\n", + "# Python 2 and 3 (after ``pip install future``):\n", + "import socketserver" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### copy_reg, copyreg" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "import copy_reg\n", + "\n", + "# Python 2 and 3 (after ``pip install future``):\n", + "import copyreg" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### configparser" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "from ConfigParser import ConfigParser\n", + "\n", + "# Python 2 and 3 (after ``pip install future``):\n", + "from configparser import ConfigParser" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### queue" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "from Queue import Queue, heapq, deque\n", + "\n", + "# Python 2 and 3 (after ``pip install future``):\n", + "from queue import Queue, heapq, deque" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### repr, reprlib" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "from repr import aRepr, repr\n", + "\n", + "# Python 2 and 3 (after ``pip install future``):\n", + "from reprlib import aRepr, repr" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### UserDict, UserList, UserString" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "from UserDict import UserDict\n", + "from UserList import UserList\n", + "from UserString import UserString\n", + "\n", + "# Python 3 only:\n", + "from collections import UserDict, UserList, UserString\n", + "\n", + "# Python 2 and 3: alternative 1\n", + "from future.moves.collections import UserDict, UserList, UserString\n", + "\n", + "# Python 2 and 3: alternative 2\n", + "from six.moves import UserDict, UserList, UserString\n", + "\n", + "# Python 2 and 3: alternative 3\n", + "from future.standard_library import install_aliases\n", + "install_aliases()\n", + "from collections import UserDict, UserList, UserString" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### itertools: filterfalse, zip_longest" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Python 2 only:\n", + "from itertools import ifilterfalse, izip_longest\n", + "\n", + "# Python 3 only:\n", + "from itertools import filterfalse, zip_longest\n", + "\n", + "# Python 2 and 3: alternative 1\n", + "from future.moves.itertools import filterfalse, zip_longest\n", + "\n", + "# Python 2 and 3: alternative 2\n", + "from six.moves import filterfalse, zip_longest\n", + "\n", + "# Python 2 and 3: alternative 3\n", + "from future.standard_library import install_aliases\n", + "install_aliases()\n", + "from itertools import filterfalse, zip_longest" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.4.3" + } + }, + "nbformat": 4, + "nbformat_minor": 0 +} diff --git a/Python/Dependencies/future-0.18.2/docs/notebooks/bytes object.ipynb b/Python/Dependencies/future-0.18.2/docs/notebooks/bytes object.ipynb new file mode 100644 index 0000000..5792144 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/notebooks/bytes object.ipynb @@ -0,0 +1,161 @@ +{ + "metadata": { + "name": "" + }, + "nbformat": 3, + "nbformat_minor": 0, + "worksheets": [ + { + "cells": [ + { + "cell_type": "code", + "collapsed": false, + "input": [ + "import sys\n", + "sys.version" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "metadata": {}, + "output_type": "pyout", + "prompt_number": 6, + "text": [ + "'2.7.6 (default, Mar 22 2014, 22:59:56) \\n[GCC 4.8.2]'" + ] + } + ], + "prompt_number": 6 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "import future\n", + "future.__version__" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "metadata": {}, + "output_type": "pyout", + "prompt_number": 1, + "text": [ + "'0.12.0-dev'" + ] + } + ], + "prompt_number": 1 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "from builtins import bytes" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 2 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "# Backported Py3 bytes object\n", + "b = bytes(b'ABCD')" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 3 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "list(b)" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "metadata": {}, + "output_type": "pyout", + "prompt_number": 4, + "text": [ + "[65, 66, 67, 68]" + ] + } + ], + "prompt_number": 4 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "repr(b)" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "metadata": {}, + "output_type": "pyout", + "prompt_number": 5, + "text": [ + "\"b'ABCD'\"" + ] + } + ], + "prompt_number": 5 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "# These raise TypeErrors:\n", + "# b + u'EFGH'\n", + "# bytes(b',').join([u'Fred', u'Bill'])\n", + "# b < u'abcd'" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 10 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "b == u'ABCD'" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "metadata": {}, + "output_type": "pyout", + "prompt_number": 9, + "text": [ + "False" + ] + } + ], + "prompt_number": 9 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [], + "language": "python", + "metadata": {}, + "outputs": [] + } + ], + "metadata": {} + } + ] +} diff --git a/Python/Dependencies/future-0.18.2/docs/notebooks/object special methods (next, bool, ...).ipynb b/Python/Dependencies/future-0.18.2/docs/notebooks/object special methods (next, bool, ...).ipynb new file mode 100644 index 0000000..5729ddc --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/notebooks/object special methods (next, bool, ...).ipynb @@ -0,0 +1,246 @@ +{ + "metadata": { + "name": "" + }, + "nbformat": 3, + "nbformat_minor": 0, + "worksheets": [ + { + "cells": [ + { + "cell_type": "heading", + "level": 2, + "metadata": {}, + "source": [ + "``object`` special methods" + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "import sys\n", + "sys.version" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "metadata": {}, + "output_type": "pyout", + "prompt_number": 1, + "text": [ + "'2.7.6 (default, Mar 22 2014, 22:59:56) \\n[GCC 4.8.2]'" + ] + } + ], + "prompt_number": 1 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "from builtins import object" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 2 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "object??" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 2 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "# Py3-style iterators written as new-style classes (subclasses of\n", + "# future.builtins.object) are backward compatibile with Py2:\n", + "class Upper(object):\n", + " def __init__(self, iterable):\n", + " self._iter = iter(iterable)\n", + " def __next__(self): # note the Py3 interface\n", + " return next(self._iter).upper()\n", + " def __iter__(self):\n", + " return self" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 3 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "assert list(Upper('hello')) == list('HELLO')" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 5 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "class AllOrNothing(object):\n", + " def __init__(self, l):\n", + " self.l = l\n", + " def __bool__(self):\n", + " return all(self.l)" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 6 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "container = AllOrNothing([0, 100, 200])\n", + "bool(container)" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "metadata": {}, + "output_type": "pyout", + "prompt_number": 8, + "text": [ + "False" + ] + } + ], + "prompt_number": 8 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "container2 = AllOrNothing([-100, 100, 200])\n", + "bool(container2)" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "metadata": {}, + "output_type": "pyout", + "prompt_number": 9, + "text": [ + "True" + ] + } + ], + "prompt_number": 9 + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Classes derived from Python builtins don't have this behaviour:" + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "class AllOrNothingBroken(list):\n", + " def __bool__(self):\n", + " print('Called!')\n", + " return all(self)" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 13 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "container3 = AllOrNothingBroken([0, 1, 2])\n", + "bool(container3)" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "metadata": {}, + "output_type": "pyout", + "prompt_number": 14, + "text": [ + "True" + ] + } + ], + "prompt_number": 14 + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "But subclasses of ``future`` types do:" + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "from builtins import list\n", + "\n", + "class AllOrNothingFixed(list):\n", + " def __bool__(self):\n", + " print('Called!')\n", + " return all(self)" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 15 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "container4 = AllOrNothingFixed([0, 1, 2])\n", + "bool(container4)" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "metadata": {}, + "output_type": "pyout", + "prompt_number": 17, + "text": [ + "True" + ] + } + ], + "prompt_number": 17 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [], + "language": "python", + "metadata": {}, + "outputs": [] + } + ], + "metadata": {} + } + ] +} diff --git a/Python/Dependencies/future-0.18.2/docs/older_interfaces.rst b/Python/Dependencies/future-0.18.2/docs/older_interfaces.rst new file mode 100644 index 0000000..546f92b --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/older_interfaces.rst @@ -0,0 +1,141 @@ +.. _older-standard-library-interfaces: + +Older interfaces +~~~~~~~~~~~~~~~~ + +In addition to the direct and ``install_aliases()`` interfaces (described in +:ref:`standard-library-imports`), ``future`` supports four other interfaces to +the reorganized standard library. This is largely for historical reasons (for +versions prior to 0.14). + + +``future.moves`` interface +__________________________ + +The ``future.moves`` interface avoids import hooks. It may therefore be more +robust, at the cost of less idiomatic code. Use it as follows:: + + from future.moves import queue + from future.moves import socketserver + from future.moves.http.client import HTTPConnection + # etc. + +If you wish to achieve the effect of a two-level import such as this:: + + import http.client + +portably on both Python 2 and Python 3, note that Python currently does not +support syntax like this:: + + from future.moves import http.client + +One workaround is to replace the dot with an underscore:: + + import future.moves.http.client as http_client + + +Comparing future.moves and six.moves +++++++++++++++++++++++++++++++++++++ + +``future.moves`` and ``six.moves`` provide a similar Python 3-style +interface to the native standard library module definitions. + +The major difference is that the ``future.moves`` package is a real Python package +(``future/moves/__init__.py``) with real modules provided as ``.py`` files, whereas +``six.moves`` constructs fake ``_LazyModule`` module objects within the Python +code and injects them into the ``sys.modules`` cache. + +The advantage of ``six.moves`` is that the code fits in a single module that can be +copied into a project that seeks to eliminate external dependencies. + +The advantage of ``future.moves`` is that it is likely to be more robust in the +face of magic like Django's auto-reloader and tools like ``py2exe`` and +``cx_freeze``. See issues #51, #53, #56, and #63 in the ``six`` project for +more detail of bugs related to the ``six.moves`` approach. + + +``import_`` and ``from_import`` functions +_________________________________________ + +The functional interface is to use the ``import_`` and ``from_import`` +functions from ``future.standard_library`` as follows:: + + from future.standard_library import import_, from_import + + http = import_('http.client') + urllib = import_('urllib.request') + + urlopen, urlsplit = from_import('urllib.request', 'urlopen', 'urlsplit') + +This interface also works with two-level imports. + + +Context-manager for import hooks +________________________________ + +The context-manager interface is via a context-manager called ``hooks``:: + + from future.standard_library import hooks + with hooks(): + import socketserver + import queue + import configparser + import test.support + import html.parser + from collections import UserList + from itertools import filterfalse, zip_longest + from http.client import HttpConnection + import urllib.request + # and other moved modules and definitions + +This interface is straightforward and effective, using PEP 302 import +hooks. However, there are reports that this sometimes leads to problems +(see issue #238). Until this is resolved, it is probably safer to use direct +imports or one of the other import mechanisms listed above. + + +install_hooks() call (deprecated) +_________________________________ + +The last interface to the reorganized standard library is via a call to +``install_hooks()``:: + + from future import standard_library + standard_library.install_hooks() + + import urllib + f = urllib.request.urlopen('http://www.python.org/') + + standard_library.remove_hooks() + +If you use this interface, it is recommended to disable the import hooks again +after use by calling ``remove_hooks()``, in order to prevent the futurized +modules from being invoked inadvertently by other modules. (Python does not +automatically disable import hooks at the end of a module, but keeps them +active for the life of a process unless removed.) + +.. The call to ``scrub_future_sys_modules()`` removes any modules from the +.. ``sys.modules`` cache (on Py2 only) that have Py3-style names, like ``http.client``. +.. This can prevent libraries that have their own Py2/3 compatibility code from +.. importing the ``future.moves`` or ``future.backports`` modules unintentionally. +.. Code such as this will then fall through to using the Py2 standard library +.. modules on Py2:: +.. +.. try: +.. from http.client import HTTPConnection +.. except ImportError: +.. from httplib import HTTPConnection +.. +.. **Requests**: The above snippet is from the `requests +.. <http://docs.python-requests.org>`_ library. As of v0.12, the +.. ``future.standard_library`` import hooks are compatible with Requests. + + +.. If you wish to avoid changing every reference of ``http.client`` to +.. ``http_client`` in your code, an alternative is this:: +.. +.. from future.standard_library import http +.. from future.standard_library.http import client as _client +.. http.client = client + +.. but it has the advantage that it can be used by automatic translation scripts such as ``futurize`` and ``pasteurize``. diff --git a/Python/Dependencies/future-0.18.2/docs/open_function.rst b/Python/Dependencies/future-0.18.2/docs/open_function.rst new file mode 100644 index 0000000..7915d8a --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/open_function.rst @@ -0,0 +1,39 @@ +.. _open-function: + +open() +------ + +The Python 3 builtin :func:`open` function for opening files returns file +contents as (unicode) strings unless the binary (``b``) flag is passed, as in:: + + open(filename, 'rb') + +in which case its methods like :func:`read` return Py3 :class:`bytes` objects. + +On Py2 with ``future`` installed, the :mod:`builtins` module provides an +``open`` function that is mostly compatible with that on Python 3 (e.g. it +offers keyword arguments like ``encoding``). This maps to the ``open`` backport +available in the standard library :mod:`io` module on Py2.7. + +One difference to be aware of between the Python 3 ``open`` and +``future.builtins.open`` on Python 2 is that the return types of methods such +as :func:`read()` from the file object that ``open`` returns are not +automatically cast from native bytes or unicode strings on Python 2 to the +corresponding ``future.builtins.bytes`` or ``future.builtins.str`` types. If you +need the returned data to behave the exactly same way on Py2 as on Py3, you can +cast it explicitly as follows:: + + from __future__ import unicode_literals + from builtins import open, bytes + + data = open('image.png', 'rb').read() + # On Py2, data is a standard 8-bit str with loose Unicode coercion. + # data + u'' would likely raise a UnicodeDecodeError + + data = bytes(data) + # Now it behaves like a Py3 bytes object... + + assert data[:4] == b'\x89PNG' + assert data[4] == 13 # integer + # Raises TypeError: + # data + u'' diff --git a/Python/Dependencies/future-0.18.2/docs/other/auto2to3.py b/Python/Dependencies/future-0.18.2/docs/other/auto2to3.py new file mode 100644 index 0000000..3abd370 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/other/auto2to3.py @@ -0,0 +1,122 @@ +#!/usr/bin/env python3 +"""Wrapper to run 2to3 automatically at import time. + +Usage: + auto2to3 -m mypackage.main_module + auto2to3 mypackage/script.py + +By default, all modules imported from a subdirectory of the current +directory will be run through `2to3`. To change this behavior, use the +`--package` or `--dir` flags to `auto2to3` to specify which packages or +directories contain Python 2 code that should be converted. + +2to3 output is cached on disk between runs for speed. + +Based on auto2to3.py by Georg Brandl: +http://dev.pocoo.org/hg/sandbox/file/tip/auto2to3.py +""" + +import argparse +import os +import sys +import imp +import runpy +from io import StringIO +from pkgutil import ImpImporter, ImpLoader +import runpy +import sys +import tempfile + +import lib2to3 +from lib2to3.refactor import RefactoringTool, get_fixers_from_package + +fixes = get_fixers_from_package('lib2to3.fixes') +rt = RefactoringTool(fixes) + +PACKAGES = [] +DIRS = [] + +def maybe_2to3(filename, modname=None): + """Returns a python3 version of filename.""" + need_2to3 = False + filename = os.path.abspath(filename) + if any(filename.startswith(d) for d in DIRS): + need_2to3 = True + elif modname is not None and any(modname.startswith(p) for p in PACKAGES): + need_2to3 = True + if not need_2to3: + return filename + outfilename = '/_auto2to3_'.join(os.path.split(filename)) + if (not os.path.exists(outfilename) or + os.stat(filename).st_mtime > os.stat(outfilename).st_mtime): + try: + with open(filename) as file: + contents = file.read() + contents = rt.refactor_docstring(contents, filename) + tree = rt.refactor_string(contents, filename) + except Exception as err: + raise ImportError("2to3 couldn't convert %r" % filename) + outfile = open(outfilename, 'wb') + outfile.write(str(tree).encode('utf8')) + outfile.close() + return outfilename + + + +class ToThreeImporter(ImpImporter): + def find_module(self, fullname, path=None): + # this duplicates most of ImpImporter.find_module + subname = fullname.split(".")[-1] + if subname != fullname and self.path is None: + return None + if self.path is None: + path = None + else: + path = [os.path.realpath(self.path)] + try: + file, filename, etc = imp.find_module(subname, path) + except ImportError: + return None + if file and etc[2] == imp.PY_SOURCE: + outfilename = maybe_2to3(filename, modname=fullname) + if outfilename != filename: + file.close() + filename = outfilename + file = open(filename, 'rb') + return ImpLoader(fullname, file, filename, etc) + + +# setup the hook +sys.path_hooks.append(ToThreeImporter) +for key in sys.path_importer_cache: + if sys.path_importer_cache[key] is None: + sys.path_importer_cache[key] = ToThreeImporter(key) + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument('--package', action='append') + parser.add_argument('--dir', action='append') + parser.add_argument('-m', action='store', metavar='MODULE') + args, rest = parser.parse_known_args() + if args.package: + PACKAGES.extend(args.package) + if args.dir: + DIRS.extend(os.path.abspath(d) for d in args.dir) + if not PACKAGES and not DIRS: + DIRS.append(os.getcwd()) + if args.m: + sys.argv[1:] = rest + runpy.run_module(args.m, run_name='__main__', alter_sys=True) + elif rest: + sys.argv = rest + converted = maybe_2to3(rest[0]) + with open(converted) as f: + new_globals = dict(__name__='__main__', + __file__=rest[0]) + exec(f.read(), new_globals) + else: + import code + code.interact() + +if __name__ == '__main__': + main() diff --git a/Python/Dependencies/future-0.18.2/docs/other/find_pattern.py b/Python/Dependencies/future-0.18.2/docs/other/find_pattern.py new file mode 100644 index 0000000..1a5da35 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/other/find_pattern.py @@ -0,0 +1,98 @@ +#!/usr/bin/env python + +"""Script that makes determining PATTERN for a new [2to3] fix much easier. + +Figuring out exactly what PATTERN I want for a given fixer class is +getting tedious. This script will step through each possible subtree +for a given string, allowing you to select which one you want. It will +then try to figure out an appropriate pattern to match that tree. This +pattern will require some editing (it will be overly restrictive) but +should provide a solid base to work with and handle the tricky parts. + +Usage: + + python find_pattern.py "g.throw(E, V, T)" + +This will step through each subtree in the parse. To reject a +candidate subtree, hit enter; to accept a candidate, hit "y" and +enter. The pattern will be spit out to stdout. + +For example, the above will yield a succession of possible snippets, +skipping all leaf-only trees. I accept + +'g.throw(E, V, T)' + +This causes find_pattern to spit out + +power< 'g' trailer< '.' 'throw' > + trailer< '(' arglist< 'E' ',' 'V' ',' 'T' > ')' > > + + +Some minor tweaks later, I'm left with + +power< any trailer< '.' 'throw' > + trailer< '(' args=arglist< exc=any ',' val=any [',' tb=any] > ')' > > + +which is exactly what I was after. + +Larger snippets can be placed in a file (as opposed to a command-line +arg) and processed with the -f option. +""" +from __future__ import print_function + +__author__ = "Collin Winter <collinw@gmail.com>" + +# Python imports +import optparse +import sys +from StringIO import StringIO + +# Local imports +from lib2to3 import pytree +from lib2to3.pgen2 import driver +from lib2to3.pygram import python_symbols, python_grammar + +driver = driver.Driver(python_grammar, convert=pytree.convert) + +def main(args): + parser = optparse.OptionParser(usage="find_pattern.py [options] [string]") + parser.add_option("-f", "--file", action="store", + help="Read a code snippet from the specified file") + + # Parse command line arguments + options, args = parser.parse_args(args) + if options.file: + tree = driver.parse_file(options.file) + elif len(args) > 1: + tree = driver.parse_stream(StringIO(args[1] + "\n")) + else: + print("You must specify an input file or an input string", file=sys.stderr) + return 1 + + examine_tree(tree) + return 0 + +def examine_tree(tree): + for node in tree.post_order(): + if isinstance(node, pytree.Leaf): + continue + print(repr(str(node))) + verdict = raw_input() + if verdict.strip(): + print(find_pattern(node)) + return + +def find_pattern(node): + if isinstance(node, pytree.Leaf): + return repr(node.value) + + return find_symbol(node.type) + \ + "< " + " ".join(find_pattern(n) for n in node.children) + " >" + +def find_symbol(sym): + for n, v in python_symbols.__dict__.items(): + if v == sym: + return n + +if __name__ == "__main__": + sys.exit(main(sys.argv)) diff --git a/Python/Dependencies/future-0.18.2/docs/other/fix_notebook_html_colour.py b/Python/Dependencies/future-0.18.2/docs/other/fix_notebook_html_colour.py new file mode 100644 index 0000000..36c2205 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/other/fix_notebook_html_colour.py @@ -0,0 +1,36 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +""" +A script to re-enable colour in .html files produced from IPython notebooks. + +Based on a script in a GitHub gist with this copyright notice: + +#---------------------------------------------------------------------------- +# Copyright (c) 2013 - Damián Avila +# +# Distributed under the terms of the Modified BSD License. +# +# A little snippet to fix @media print issue printing slides from IPython +#----------------------------------------------------------------------------- +""" + +import io +import sys + +notebook = sys.argv[1] +assert notebook.endswith('.html') +# notebook = 'jevans.ipynb' +path = notebook[:-5] + '.html' +flag = u'@media print{*{text-shadow:none !important;color:#000 !important' + +with io.open(path, 'r') as in_file: + data = in_file.readlines() + for i, line in enumerate(data): + if line[:64] == flag: + data[i] = data[i].replace('color:#000 !important;', '') + +with io.open(path, 'w') as out_file: + out_file.writelines(data) + +print("You can now print your slides") diff --git a/Python/Dependencies/future-0.18.2/docs/other/lessons.txt b/Python/Dependencies/future-0.18.2/docs/other/lessons.txt new file mode 100644 index 0000000..ede523c --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/other/lessons.txt @@ -0,0 +1,49 @@ +The escape() function in this file in Django 1.4: + + /home/user/VirtualEnvs/mezzanine/local/lib/python2.7/site-packages/django/utils/html.py + +atttempts to use the unicode replace method with byte strings. This +causes this exception when running the Mezzanine tests using the newstr +object: + + File "/home/user/VirtualEnvs/mezzanine/local/lib/python2.7/site-packages/django/utils/html.py", line 36, in escape + return mark_safe(force_unicode(html).replace('&', '&').replace('<', '<').replace('>', '>').replace('"', '"').replace("'", ''')) + File "/home/user/VirtualEnvs/mezzanine/local/lib/python2.7/site-packages/future-0.9.0_dev-py2.7.egg/future/builtins/backports/__init__.py", line 145, in wrapper + raise TypeError(errmsg.format(mytype)) + TypeError: argument can't be <type 'str'> + + +Comment to add to prevent Pylint from issuing warnings on ``from +future.builtins import *``: + + # pylint: disable=W0622,W0401 + +INCOMPATIBLE: array.array() + +Python 2: + >>> array.array(b'b') + array.array(b'b') + + >>> array.array(u'u') + TypeError: must be char, not unicode + +Python 3: + >>> array.array(b'b') + TypeError: must be a unicode character, not bytes + + >>> array.array(u'b') + array('b') + +Maybe use on Py2: + >>> array.array(u'b'.encode('ascii')) ?? + +Long int syntax (e.g. 1000000L) is incompatible with Py3. +We probably shouldn't shadow int with long on Py2 because then isinstance(1, int) is False + +Python 2's bytes object is nothing like Python 3's bytes object! +Running test_bytes.py from Py3 on Py2 (after fixing imports) gives this: + +-------------------------------------------------------------- +Ran 203 tests in 0.209s + +FAILED (failures=31, errors=55, skipped=1) diff --git a/Python/Dependencies/future-0.18.2/docs/other/todo.txt b/Python/Dependencies/future-0.18.2/docs/other/todo.txt new file mode 100644 index 0000000..def7b04 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/other/todo.txt @@ -0,0 +1 @@ +Import open() from codecs to shadow the Py2 open()? diff --git a/Python/Dependencies/future-0.18.2/docs/other/upload_future_docs.sh b/Python/Dependencies/future-0.18.2/docs/other/upload_future_docs.sh new file mode 100644 index 0000000..d5c272d --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/other/upload_future_docs.sh @@ -0,0 +1,23 @@ +# On the local machine + +git checkout v0.16.0 # or whatever +rm -Rf docs/build/ +cd docs; make html +cp cheatsheet.pdf /shared/ +cd build +touch /shared/python-future-html-docs.zip +rm /shared/python-future-html-docs.zip +zip -r /shared/python-future-html-docs.zip * + +scp /shared/python-future-html-docs.zip python-future.org: +scp /shared/cheatsheet.pdf python-future.org: +ssh python-future.org + + +# On the remote machine: + +cd /var/www/python-future.org/ +unzip -o ~/python-future-html-docs.zip +chmod a+r * html/* html/_static/* +cp ~/cheatsheet.pdf ./html/compatible_idioms.pdf +cp ~/cheatsheet.pdf ./html/cheatsheet.pdf diff --git a/Python/Dependencies/future-0.18.2/docs/other/useful_links.txt b/Python/Dependencies/future-0.18.2/docs/other/useful_links.txt new file mode 100644 index 0000000..abb9684 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/other/useful_links.txt @@ -0,0 +1,110 @@ +Official words on porting: +-------------------------- +http://docs.python.org/2/howto/pyporting.html +http://wiki.python.org/moin/Python2orPython3 + +Other docs to read about porting to Py3: +---------------------------------------- + +https://github.com/nltk/nltk/blob/2and3/web/dev/python3porting.rst (particularly about doctests) +https://ep2013.europython.eu/media/conference/slides/python-3-the-next-generation-is-here-already.pdf +http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/ +Supporting both 2 and 3 without 2to3 conversion: http://python3porting.com/noconv.html +http://python3porting.com/strategies.html +http://techspot.zzzeek.org/2011/01/24/zzzeek-s-guide-to-python-3-porting/ +http://dabeaz.blogspot.com.au/2011/01/porting-py65-and-my-superboard-to.html +http://wolfprojects.altervista.org/talks/unicode-and-python-3/ + +Porting Django apps: https://docs.djangoproject.com/en/dev/topics/python3/ +http://www.wefearchange.org/2012/01/python-3-porting-fun-redux.html + +http://lucumr.pocoo.org/2011/12/7/thoughts-on-python3/ + +http://python3porting.com/fixers.html +http://washort.twistedmatrix.com/2010/11/unicode-in-python-and-how-to-prevent-it.html +http://docs.python.org/release/3.0.1/whatsnew/3.0.html +https://pypi.org/project/unicode-nazi/ +http://www.rmi.net/~lutz/strings30.html + +"Porting your code to Python 3": Alexandre Vassalotti: peadrop.com/slides/mp5.pdf + +Migration problems: +------------------- +http://python3porting.com/problems.html +http://www.wefearchange.org/2012/01/python-3-porting-fun-redux.html + +Six module: http://pythonhosted.org/six/ + +Dive Into Python: Appendix A: Porting Code to Python 3 with 2to3: http://getpython3.com/diveintopython3/porting-code-to-python-3-with-2to3.html + +Stdlib reorganization: http://python3porting.com/stdlib.html + +python-modernize: https://github.com/mitsuhiko/python-modernize + +2to3 docs describing the different fixers: http://docs.python.org/2/library/2to3.html + +Injecting code into running Python processes (hopefully not needed): https://pypi.org/project/pyrasite/2.0/ + +Withdrawn PEP to help with the Py3k standard library transition: http://www.peps.io/364/ + +Import hooks +------------ +http://www.peps.io/302/ +"Hacking Python imports ... for fun and profit": blog post from 2012-05: http://xion.org.pl/2012/05/06/hacking-python-imports/ + +Full importlib backport to Py2: https://pypi.org/project/backport_importlib/0...1/ + +Python 2.7 importlib subset: http://docs.python.org/2/whatsnew/2.7.html#importlib-section + +Post-import hooks (rendered obsolete by importlib): http://blog.cdleary.com/2009/04/monstrous-polymorphism-and-a-python-post-import-hook-decorator/ + +'An import hook for Python 3 that removes u prefixes ' + 'from Python source code before compiling it.': https://bitbucket.org/vinay.sajip/uprefix/ + + +__future__ imports +------------------ +http://simeonvisser.com/posts/how-does-from-future-import-work-in-python.html +http://docs.python.org/2/library/__future__.html + +lib3to2 +------- +https://bitbucket.org/amentajo/lib3to2 +http://www.startcodon.com/wordpress/category/3to2/ + +Unicode and bytes +----------------- +PEPs: 358, 3112, 3137, 3138 +http://python3porting.com/noconv.html#unicode-section +Unicode literals u'...' back in Python 3.3: http://www.python.org/dev/peps/pep-0414/ +https://github.com/django/django/blob/master/django/utils/encoding.py +https://pypi.org/project/unicode-nazi/ +http://docs.python.org/3/library/stdtypes.html#bytes-methods +http://wolfprojects.altervista.org/talks/unicode-and-python-3/ +Buffer protocol (which bytes and bytes-like objects obey): http://docs.python.org/3.3/c-api/buffer.html#bufferobjects + + +Python's future +---------------- +https://ncoghlan-devs-python-notes.readthedocs.io/en/latest/python3/questions_and_answers.html + +http://www.ironfroggy.com/software/i-am-worried-about-the-future-of-python + +Backporting +----------- +http://stackoverflow.com/questions/7507492/is-backporting-python-3s-range-to-python-2-a-bad-idea + + +Other +----- +Type-checking decorators (maybe useful for implementing a Py3-like bytes +object in Py2): http://wiki.python.org/moin/PythonDecoratorLibrary#Type_Enforcement_.28accepts.2Freturns.29 +Also: typecheck module on PyPI + +To categorize +------------- + +https://pypi.org/project/awkwardduet/1.1a4/ +https://github.com/campadrenalin/persei/blob/master/persei.py +http://slideshare.net/dabeaz/mastering-python-3-io +http://rmi.net/~lutz/strings30.html diff --git a/Python/Dependencies/future-0.18.2/docs/overview.rst b/Python/Dependencies/future-0.18.2/docs/overview.rst new file mode 100644 index 0000000..72a3355 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/overview.rst @@ -0,0 +1 @@ +.. include:: ../README.rst diff --git a/Python/Dependencies/future-0.18.2/docs/pasteurize.rst b/Python/Dependencies/future-0.18.2/docs/pasteurize.rst new file mode 100644 index 0000000..070b5d1 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/pasteurize.rst @@ -0,0 +1,45 @@ +.. _backwards-conversion: + +``pasteurize``: Py3 to Py2/3 +---------------------------- + +Running ``pasteurize -w mypy3module.py`` turns this Python 3 code:: + + import configparser + import copyreg + + class Blah: + pass + print('Hello', end=None) + +into this code which runs on both Py2 and Py3:: + + from __future__ import print_function + from future import standard_library + standard_library.install_hooks() + + import configparser + import copyreg + + class Blah(object): + pass + print('Hello', end=None) + +Notice that both ``futurize`` and ``pasteurize`` create explicit new-style +classes that inherit from ``object`` on both Python versions, and both +refer to stdlib modules (as well as builtins) under their Py3 names. + +Note also that the ``configparser`` module is a special case; there is a full +backport available on PyPI (https://pypi.org/project/configparser/), so, as +of v0.16.0, ``python-future`` no longer provides a ``configparser`` package +alias. To use the resulting code on Py2, install the ``configparser`` backport +with ``pip install configparser`` or by adding it to your ``requirements.txt`` +file. + +``pasteurize`` also handles the following Python 3 features: + +- keyword-only arguments +- metaclasses (using :func:`~future.utils.with_metaclass`) +- extended tuple unpacking (PEP 3132) + +To handle function annotations (PEP 3107), see :ref:`func_annotations`. diff --git a/Python/Dependencies/future-0.18.2/docs/quickstart.rst b/Python/Dependencies/future-0.18.2/docs/quickstart.rst new file mode 100644 index 0000000..6042e05 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/quickstart.rst @@ -0,0 +1,153 @@ +.. _quickstart-guide: + +Quick-start guide +================= + +You can use ``future`` to help to port your code from Python 2 to Python 3 +today -- and still have it run on Python 2. + +If you already have Python 3 code, you can instead use ``future`` to +offer Python 2 compatibility with almost no extra work. + +Installation +------------ + +To install the latest stable version, type:: + + pip install future + +If you would prefer the latest development version, it is available `here +<https://github.com/PythonCharmers/python-future>`_. + + +If you are writing code from scratch +------------------------------------ + +The easiest way is to start each new module with these lines:: + + from __future__ import (absolute_import, division, + print_function, unicode_literals) + from builtins import * + +Then write standard Python 3 code. The :mod:`future` package will +provide support for running your code on Python 2.7, and 3.4+ mostly +unchanged. + +- For explicit import forms, see :ref:`explicit-imports`. +- For more details, see :ref:`what-else`. +- For a cheat sheet, see :ref:`compatible-idioms`. + + +To convert existing Python 3 code +--------------------------------- + +To offer backward compatibility with Python 2 from your Python 3 code, +you can use the ``pasteurize`` script. This adds these lines at the top of each +module:: + + from __future__ import absolute_import + from __future__ import division + from __future__ import print_function + from __future__ import unicode_literals + + from builtins import open + from builtins import str + # etc., as needed + + from future import standard_library + standard_library.install_aliases() + +and converts several Python 3-only constructs (like keyword-only arguments) to a +form compatible with both Py3 and Py2. Most remaining Python 3 code should +simply work on Python 2. + +See :ref:`backwards-conversion` for more details. + + +To convert existing Python 2 code +--------------------------------- + +.. include:: futurize_overview.rst + +See :ref:`forwards-conversion-stage1` and :ref:`forwards-conversion-stage2` for more details. + +.. If you already know Python 3, start with the :ref:`automatic-conversion` page. +.. If you don't know Python 3 yet, start with :ref:`python3-essentials`. + + +.. _standard-library: + +Standard library reorganization +------------------------------- + +:mod:`future` supports the standard library reorganization (PEP 3108) via +one of several mechanisms, allowing most moved standard library modules +to be accessed under their Python 3 names and locations in Python 2:: + + from future import standard_library + standard_library.install_aliases() + + # Then these Py3-style imports work on both Python 2 and Python 3: + import socketserver + import queue + from collections import UserDict, UserList, UserString + from collections import ChainMap # even on Py2.7 + from itertools import filterfalse, zip_longest + + import html + import html.entities + import html.parser + + import http + import http.client + import http.server + import http.cookies + import http.cookiejar + + import urllib.request + import urllib.parse + import urllib.response + import urllib.error + import urllib.robotparser + + import xmlrpc.client + import xmlrpc.server + +and others. For a complete list, see :ref:`direct-imports`. + +.. _py2-dependencies: + +Python 2-only dependencies +-------------------------- + +If you have dependencies that support only Python 2, you may be able to use the +``past`` module to automatically translate these Python 2 modules to Python 3 +upon import. First, install the Python 2-only package into your Python 3 +environment:: + + $ pip3 install mypackagename --no-compile # to ignore SyntaxErrors + +(or use ``pip`` if this points to your Py3 environment.) + +Then add the following code at the top of your (Py3 or Py2/3-compatible) +code:: + + from past.translation import autotranslate + autotranslate(['mypackagename']) + import mypackagename + +This feature is experimental, and we would appreciate your feedback on +how well this works or doesn't work for you. Please file an issue `here +<https://github.com/PythonCharmers/python-future>`_ or post to the +`python-porting <https://mail.python.org/mailman/listinfo/python-porting>`_ +mailing list. + +For more information on the automatic translation feature, see :ref:`translation`. + + +Next steps +---------- +For more information about writing Py2/3-compatible code, see: + +- :ref:`compatible-idioms` +- :ref:`what-else`. diff --git a/Python/Dependencies/future-0.18.2/docs/reference.rst b/Python/Dependencies/future-0.18.2/docs/reference.rst new file mode 100644 index 0000000..d9ac5e1 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/reference.rst @@ -0,0 +1,81 @@ +API Reference (in progress) +*************************** + +**NOTE: This page is still a work in progress... We need to go through our +docstrings and make them sphinx-compliant, and figure out how to improve +formatting with the sphinx-bootstrap-theme plugin. Pull requests would be +very welcome.** + + +.. contents:: + :local: + :depth: 2 + +future.builtins Interface +========================= + +.. automodule:: future.builtins + :members: + +.. Docs are also in future-builtins.rst. Extract these and put them into the +.. relevant docstrings. + + +Backported types from Python 3 +============================== + +.. automodule:: future.types + :members: + + +future.standard_library Interface +================================= + +.. automodule:: future.standard_library + :members: + + +future.utils Interface +====================== + +.. automodule:: future.utils + :members: + + +past.builtins Interface +========================= + +.. automodule:: past.builtins + :members: + +.. Docs are also in future-builtins.rst. Extract these and put them into the +.. relevant docstrings. + + +Forward-ported types from Python 2 +================================== + +.. automodule:: past.types + :members: + + + +.. bytes +.. ----- +.. .. automodule:: future.types.newbytes +.. +.. dict +.. ----- +.. .. automodule:: future.types.newdict +.. +.. int +.. --- +.. .. automodule:: future.builtins.backports.newint +.. +.. range +.. ----- +.. .. automodule:: future.types.newrange +.. +.. str +.. --- +.. .. automodule:: future.types.newstr diff --git a/Python/Dependencies/future-0.18.2/docs/roadmap.rst b/Python/Dependencies/future-0.18.2/docs/roadmap.rst new file mode 100644 index 0000000..c5020d5 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/roadmap.rst @@ -0,0 +1,46 @@ +Development roadmap +=================== + +futurize script +--------------- + +1. "Safe" mode -- from Py2 to modern Py2 or Py3 to more-compatible Py3 + + - Split the fixers into two categories: safe and bold + - Safe is highly unlikely to break existing Py2 or Py3 support. The + output of this still requires :mod:`future` imports. Examples: + + - Compatible metaclass syntax on Py3 + - Explicit inheritance from object on Py3 + + - Bold might make assumptions about which strings on Py2 should be + unicode strings and which should be bytestrings. + + - We should also build up a database of which standard library + interfaces on Py2 and Py3 accept unicode strings versus + byte-strings, which have changed, and which haven't. + +2. Windows support + +future package +-------------- + +- [Done] Add more tests for bytes ... preferably all from test_bytes.py in Py3.3. +- [Done] Add remove_hooks() and install_hooks() as functions in the + :mod:`future.standard_library` module. (See the uprefix module for how + to do this.) + +Experimental: +- Add:: + + from future import bytes_literals + from future import new_metaclass_syntax + from future import new_style_classes + +- [Done] Maybe:: + + from future.builtins import str + + should import a custom str is a Py3 str-like object which inherits from unicode and + removes the decode() method and has any other Py3-like behaviours + (possibly stricter casting?) diff --git a/Python/Dependencies/future-0.18.2/docs/standard_library_imports.rst b/Python/Dependencies/future-0.18.2/docs/standard_library_imports.rst new file mode 100644 index 0000000..6044254 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/standard_library_imports.rst @@ -0,0 +1,181 @@ +.. _standard-library-imports: + +Standard library imports +------------------------ + +:mod:`future` supports the standard library reorganization (PEP 3108) through +several mechanisms. + +.. _direct-imports: + +Direct imports +~~~~~~~~~~~~~~ + +As of version 0.14, the ``future`` package comes with top-level packages for +Python 2.x that provide access to the reorganized standard library modules +under their Python 3.x names. + +Direct imports are the preferred mechanism for accesing the renamed standard +library modules in Python 2/3 compatible code. For example, the following clean +Python 3 code runs unchanged on Python 2 after installing ``future``:: + + >>> # Alias for future.builtins on Py2: + >>> from builtins import str, open, range, dict + + >>> # Top-level packages with Py3 names provided on Py2: + >>> import queue + >>> import tkinter.dialog + >>> etc. + +Notice that this code actually runs on Python 3 without the presence of the +``future`` package. + +Of the 44 modules that were refactored with PEP 3108 (standard library +reorganization), 29 are supported with direct imports in the above manner. The +complete list is here:: + + ### Renamed modules: + + import builtins + + import copyreg + + import html + import html.entities + import html.parser + + import http.client + import http.cookies + import http.cookiejar + import http.server + + import queue + + import reprlib + + import socketserver + + from tkinter import colorchooser + from tkinter import commondialog + from tkinter import constants + from tkinter import dialog + from tkinter import dnd + from tkinter import filedialog + from tkinter import font + from tkinter import messagebox + from tkinter import scrolledtext + from tkinter import simpledialog + from tkinter import tix + from tkinter import ttk + + import winreg # Windows only + + import xmlrpc.client + import xmlrpc.server + + import _dummy_thread + import _markupbase + import _thread + +Note that, as of v0.16.0, ``python-future`` no longer includes an alias for the +``configparser`` module because a full backport exists (see https://pypi.org/project/configparser/). + +.. _list-standard-library-refactored: + +Aliased imports +~~~~~~~~~~~~~~~ + +The following 14 modules were refactored or extended from Python 2.7 to 3.x +but were neither renamed in Py3.x nor were the new APIs backported to Py2.x. +This precludes compatibility interfaces that work out-of-the-box. Instead, the +``future`` package makes the Python 3.x APIs available on Python 2.x as +follows:: + + from future.standard_library import install_aliases + install_aliases() + + from collections import UserDict, UserList, UserString + + import urllib.parse + import urllib.request + import urllib.response + import urllib.robotparser + import urllib.error + + import dbm + import dbm.dumb + import dbm.gnu # requires Python dbm support + import dbm.ndbm # requires Python dbm support + + from itertools import filterfalse, zip_longest + + from subprocess import getoutput, getstatusoutput + + from sys import intern + + import test.support + + +The newly exposed ``urllib`` submodules are backports of those from Py3.x. +This means, for example, that ``urllib.parse.unquote()`` now exists and takes +an optional ``encoding`` argument on Py2.x as it does on Py3.x. + +**Limitation:** Note that the ``http``-based backports do not currently support +HTTPS (as of 2015-09-11) because the SSL support changed considerably in Python +3.x. If you need HTTPS support, please use this idiom for now:: + + from future.moves.urllib.request import urlopen + +Backports also exist of the following features from Python 3.4: + +- ``math.ceil`` returns an int on Py3 +- ``collections.ChainMap`` (for 2.7) +- ``reprlib.recursive_repr`` (for 2.7) + +These can then be imported on Python 2.7+ as follows:: + + from future.standard_library import install_aliases + install_aliases() + + from math import ceil # now returns an int + from collections import ChainMap + from reprlib import recursive_repr + + +External standard-library backports +----------------------------------- + +Backports of the following modules from the Python 3.x standard library are +available independently of the python-future project:: + + import enum # pip install enum34 + import singledispatch # pip install singledispatch + import pathlib # pip install pathlib + +A few modules from Python 3.4 are also available in the ``backports`` +package namespace after ``pip install backports.lzma`` etc.:: + + from backports import lzma + from backports import functools_lru_cache as lru_cache + + +Included full backports +----------------------- + +Alpha-quality full backports of the following modules from Python 3.3's +standard library to Python 2.x are also available in ``future.backports``:: + + http.client + http.server + html.entities + html.parser + urllib + xmlrpc.client + xmlrpc.server + +The goal for these modules, unlike the modules in the ``future.moves`` package +or top-level namespace, is to backport new functionality introduced in Python +3.3. + +If you need the full backport of one of these packages, please open an issue `here +<https://github.com/PythonCharmers/python-future>`_. diff --git a/Python/Dependencies/future-0.18.2/docs/stdlib_incompatibilities.rst b/Python/Dependencies/future-0.18.2/docs/stdlib_incompatibilities.rst new file mode 100644 index 0000000..5f2217d --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/stdlib_incompatibilities.rst @@ -0,0 +1,106 @@ +.. _stdlib-incompatibilities: + +Standard library incompatibilities +================================== + +Some standard library interfaces have changed in ways that require +different code than normal Py3 code in order to achieve Py2/3 +compatibility. + +Here we will attempt to document these, together with known workarounds: + +.. csv-table:: Standard library incompatibilities + :header: "module", "object / feature", "section" + :widths: 10, 20, 15 + + ``array``, ``array`` constructor, :ref:`stdlib-array-constructor` + ``array``, ``array.read()`` method, :ref:`stdlib-array-read` + ``base64``, ``decodebytes()`` function, :ref:`stdlib-base64-decodebytes` + ``re``, ``ASCII`` mode, :ref:`stdlib-re-ASCII` + +To contribute to this, please email the python-porting list or send a +pull request. See :ref:`contributing`. + + +.. _stdlib-array-constructor: + +array.array() +------------- + +The first argument to ``array.array(typecode[, initializer])`` must be a native +platform string: unicode string on Python 3, byte string on Python 2. + +Python 2:: + >>> array.array(b'b') + array.array(b'b') + + >>> array.array(u'u') + TypeError: must be char, not unicode + +Python 3:: + >>> array.array(b'b') + TypeError: must be a unicode character, not bytes + + >>> array.array(u'b') + array('b') + +This means that the typecode cannot be specified portably across Python 3 and Python 2 +with a single string literal when ``from __future__ import unicode_literals`` is in effect. + +You can use the following code on both Python 3 and Python 2:: + + from __future__ import unicode_literals + from future.utils import bytes_to_native_str + import array + + # ... + + a = array.array(bytes_to_native_str(b'b')) + +This was `fixed in Python 2.7.11 +<https://hg.python.org/cpython/file/6d1b6a68f775/Misc/NEWS#l233>`_. +Since then, ``array.array()`` now also accepts unicode format typecode. + +.. _stdlib-array-read: + +array.array.read() +------------------ +This method has been removed in Py3. This crops up in e.g. porting ``http.client``. + + +.. _stdlib-base64-decodebytes: + +base64.decodebytes() and base64.encodebytes() +--------------------------------------------- +The ``base64`` module on Py2 has no ``decodebytes`` or ``encodebytes`` functions. + + +.. _stdlib-re-ASCII: + +re.ASCII +-------- +Python 3 code using regular expressions sometimes looks like this (from +:mod:`urllib.request`):: + + re.compile(r":\d+$", re.ASCII) + +This enables 'ASCII mode' for regular expressions (see the docs `here +<http://docs.python.org/3/library/re.html#re.ASCII>`_). Python 2's +:mod:`re` module has no equivalent mode. + +struct.pack() +------------- + +Before Python version 2.7.7, the :func:`struct.pack` function +required a native string as its format argument. For example:: + + >>> from __future__ import unicode_literals + >>> from struct import pack + >>> pack('<4H2I', version, rec_type, build, year, file_hist_flags, ver_can_read) + +raised ``TypeError: Struct() argument 1 must be string, not unicode``. + +This was `fixed in Python 2.7.7 +<https://hg.python.org/cpython/raw-file/f89216059edf/Misc/NEWS>`_. +Since then, ``struct.pack()`` now also accepts unicode format +strings. diff --git a/Python/Dependencies/future-0.18.2/docs/str_object.rst b/Python/Dependencies/future-0.18.2/docs/str_object.rst new file mode 100644 index 0000000..4c5257a --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/str_object.rst @@ -0,0 +1,99 @@ +.. _str-object: + +str +----- + +The :class:`str` object in Python 3 is quite similar but not identical to the +Python 2 :class:`unicode` object. + +The major difference is the stricter type-checking of Py3's ``str`` that +enforces a distinction between unicode strings and byte-strings, such as when +comparing, concatenating, joining, or replacing parts of strings. + +There are also other differences, such as the ``repr`` of unicode strings in +Py2 having a ``u'...'`` prefix, versus simply ``'...'``, and the removal of +the :func:`str.decode` method in Py3. + +:mod:`future` contains a :class:`newstr`` type that is a backport of the +:mod:`str` object from Python 3. This inherits from the Python 2 +:class:`unicode` class but has customizations to improve compatibility with +Python 3's :class:`str` object. You can use it as follows:: + + >>> from __future__ import unicode_literals + >>> from builtins import str + +On Py2, this gives us:: + + >>> str + future.types.newstr.newstr + +(On Py3, it is simply the usual builtin :class:`str` object.) + +Then, for example, the following code has the same effect on Py2 as on Py3:: + + >>> s = str(u'ABCD') + >>> assert s != b'ABCD' + >>> assert isinstance(s.encode('utf-8'), bytes) + >>> assert isinstance(b.decode('utf-8'), str) + + These raise TypeErrors: + + >>> bytes(b'B') in s + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + TypeError: 'in <string>' requires string as left operand, not <type 'str'> + + >>> s.find(bytes(b'A')) + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + TypeError: argument can't be <type 'str'> + +Various other operations that mix strings and bytes or other types are +permitted on Py2 with the :class:`newstr` class even though they +are illegal with Python 3. For example:: + + >>> s2 = b'/' + str('ABCD') + >>> s2 + '/ABCD' + >>> type(s2) + future.types.newstr.newstr + +This is allowed for compatibility with parts of the Python 2 standard +library and various third-party libraries that mix byte-strings and unicode +strings loosely. One example is ``os.path.join`` on Python 2, which +attempts to add the byte-string ``b'/'`` to its arguments, whether or not +they are unicode. (See ``posixpath.py``.) Another example is the +:func:`escape` function in Django 1.4's :mod:`django.utils.html`. + + +.. For example, this is permissible on Py2:: +.. +.. >>> u'u' > 10 +.. True +.. +.. >>> u'u' <= b'u' +.. True +.. +.. On Py3, these raise TypeErrors. + +In most other ways, these :class:`builtins.str` objects on Py2 have the +same behaviours as Python 3's :class:`str`:: + + >>> s = str('ABCD') + >>> assert repr(s) == 'ABCD' # consistent repr with Py3 (no u prefix) + >>> assert list(s) == ['A', 'B', 'C', 'D'] + >>> assert s.split('B') == ['A', 'CD'] + + +The :class:`str` type from :mod:`builtins` also provides support for the +``surrogateescape`` error handler on Python 2.x. Here is an example that works +identically on Python 2.x and 3.x:: + + >>> from builtins import str + >>> s = str(u'\udcff') + >>> s.encode('utf-8', 'surrogateescape') + b'\xff' + +This feature is in alpha. Please leave feedback `here +<https://github.com/PythonCharmers/python-future/issues>`_ about whether this +works for you. diff --git a/Python/Dependencies/future-0.18.2/docs/translation.rst b/Python/Dependencies/future-0.18.2/docs/translation.rst new file mode 100644 index 0000000..632c46b --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/translation.rst @@ -0,0 +1,112 @@ +.. _translation: + +Using Python 2-only dependencies on Python 3 +-------------------------------------------- + +The ``past`` module provides an experimental ``translation`` package to help +with importing and using old Python 2 modules in a Python 3 environment. + +This is implemented using PEP 414 import hooks together with fixers from +``lib2to3`` and ``libfuturize`` (included with ``python-future``) that +attempt to automatically translate Python 2 code to Python 3 code with equivalent +semantics upon import. + +*Note* This feature is still in alpha and needs further development to support a +full range of real-world Python 2 modules. Also be aware that the API for +this package might change considerably in later versions. + +Here is how to use it:: + + $ pip3 install plotrique==0.2.5-7 --no-compile # to ignore SyntaxErrors + $ python3 + +Then pass in a whitelist of module name prefixes to the +``past.translation.autotranslate()`` function. Example:: + + >>> from past.translation import autotranslate + >>> autotranslate(['plotrique']) + >>> import plotrique + +Here is another example:: + + >>> from past.translation import install_hooks, remove_hooks + >>> install_hooks(['mypy2module']) + >>> import mypy2module + >>> remove_hooks() + +This will translate, import and run Python 2 code such as the following:: + + ### File: mypy2module.py + + # Print statements are translated transparently to functions: + print 'Hello from a print statement' + + # xrange() is translated to Py3's range(): + total = 0 + for i in xrange(10): + total += i + print 'Total is: %d' % total + + # Dictionary methods like .keys() and .items() are supported and + # return lists as on Python 2: + d = {'a': 1, 'b': 2} + assert d.keys() == ['a', 'b'] + assert isinstance(d.items(), list) + + # Functions like range, reduce, map, filter also return lists: + assert isinstance(range(10), list) + + # The exec statement is supported: + exec 'total += 1' + print 'Total is now: %d' % total + + # Long integers are supported: + k = 1234983424324L + print 'k + 1 = %d' % k + + # Most renamed standard library modules are supported: + import ConfigParser + import HTMLParser + import urllib + + +The attributes of the module are then accessible normally from Python 3. +For example:: + + # This Python 3 code works + >>> type(mypy2module.d) + builtins.dict + +This is a standard Python 3 data type, so, when called from Python 3 code, +``keys()`` returns a view, not a list:: + + >>> type(mypy2module.d.keys()) + builtins.dict_keys + + +.. _translation-limitations: + +Known limitations of ``past.translation`` +***************************************** + +- It currently requires a newline at the end of the module or it throws a + ``ParseError``. + +- This only works with pure-Python modules. C extension modules and Cython code + are not supported. + +- The biggest hurdle to automatic translation is likely to be ambiguity + about byte-strings and text (unicode strings) in the Python 2 code. If the + ``past.autotranslate`` feature fails because of this, you could try + running ``futurize`` over the code and adding a ``b''`` or ``u''`` prefix to + the relevant string literals. To convert between byte-strings and text (unicode + strings), add an ``.encode`` or ``.decode`` method call. If this succeeds, + please push your patches upstream to the package maintainers. + +- Otherwise, the source translation feature offered by the ``past.translation`` + package has similar limitations to the ``futurize`` script (see + :ref:`futurize-limitations`). Help developing and testing this feature further + would be particularly welcome. + +Please report any bugs you find on the ``python-future`` `bug tracker +<https://github.com/PythonCharmers/python-future/>`_. diff --git a/Python/Dependencies/future-0.18.2/docs/unicode_literals.rst b/Python/Dependencies/future-0.18.2/docs/unicode_literals.rst new file mode 100644 index 0000000..7252e4d --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/unicode_literals.rst @@ -0,0 +1,197 @@ +.. _unicode-literals: + +Should I import unicode_literals? +--------------------------------- + +The ``future`` package can be used with or without ``unicode_literals`` +imports. + +In general, it is more compelling to use ``unicode_literals`` when +back-porting new or existing Python 3 code to Python 2/3 than when porting +existing Python 2 code to 2/3. In the latter case, explicitly marking up all +unicode string literals with ``u''`` prefixes would help to avoid +unintentionally changing the existing Python 2 API. However, if changing the +existing Python 2 API is not a concern, using ``unicode_literals`` may speed up +the porting process. + +This section summarizes the benefits and drawbacks of using +``unicode_literals``. To avoid confusion, we recommend using +``unicode_literals`` everywhere across a code-base or not at all, instead of +turning on for only some modules. + + + +Benefits +~~~~~~~~ + +1. String literals are unicode on Python 3. Making them unicode on Python 2 + leads to more consistency of your string types across the two + runtimes. This can make it easier to understand and debug your code. + +2. Code without ``u''`` prefixes is cleaner, one of the claimed advantages + of Python 3. Even though some unicode strings would require a function + call to invert them to native strings for some Python 2 APIs (see + :ref:`stdlib-incompatibilities`), the incidence of these function calls + would usually be much lower than the incidence of ``u''`` prefixes for text + strings in the absence of ``unicode_literals``. + +3. The diff when porting to a Python 2/3-compatible codebase may be smaller, + less noisy, and easier to review with ``unicode_literals`` than if an + explicit ``u''`` prefix is added to every unadorned string literal. + +4. If support for Python 3.2 is required (e.g. for Ubuntu 12.04 LTS or + Debian wheezy), ``u''`` prefixes are a ``SyntaxError``, making + ``unicode_literals`` the only option for a Python 2/3 compatible + codebase. [However, note that ``future`` doesn't support Python 3.0-3.2.] + + +Drawbacks +~~~~~~~~~ + +1. Adding ``unicode_literals`` to a module amounts to a "global flag day" for + that module, changing the data types of all strings in the module at once. + Cautious developers may prefer an incremental approach. (See + `here <http://lwn.net/Articles/165039/>`_ for an excellent article + describing the superiority of an incremental patch-set in the the case + of the Linux kernel.) + +.. This is a larger-scale change than adding explicit ``u''`` prefixes to +.. all strings that should be Unicode. + +2. Changing to ``unicode_literals`` will likely introduce regressions on + Python 2 that require an initial investment of time to find and fix. The + APIs may be changed in subtle ways that are not immediately obvious. + + An example on Python 2:: + + ### Module: mypaths.py + + ... + def unix_style_path(path): + return path.replace('\\', '/') + ... + + ### User code: + + >>> path1 = '\\Users\\Ed' + >>> unix_style_path(path1) + '/Users/ed' + + On Python 2, adding a ``unicode_literals`` import to ``mypaths.py`` would + change the return type of the ``unix_style_path`` function from ``str`` to + ``unicode`` in the user code, which is difficult to anticipate and probably + unintended. + + The counter-argument is that this code is broken, in a portability + sense; we see this from Python 3 raising a ``TypeError`` upon passing the + function a byte-string. The code needs to be changed to make explicit + whether the ``path`` argument is to be a byte string or a unicode string. + +3. With ``unicode_literals`` in effect, there is no way to specify a native + string literal (``str`` type on both platforms). This can be worked around as follows:: + + >>> from __future__ import unicode_literals + >>> ... + >>> from future.utils import bytes_to_native_str as n + + >>> s = n(b'ABCD') + >>> s + 'ABCD' # on both Py2 and Py3 + + although this incurs a performance penalty (a function call and, on Py3, + a ``decode`` method call.) + + This is a little awkward because various Python library APIs (standard + and non-standard) require a native string to be passed on both Py2 + and Py3. (See :ref:`stdlib-incompatibilities` for some examples. WSGI + dictionaries are another.) + +3. If a codebase already explicitly marks up all text with ``u''`` prefixes, + and if support for Python versions 3.0-3.2 can be dropped, then + removing the existing ``u''`` prefixes and replacing these with + ``unicode_literals`` imports (the porting approach Django used) would + introduce more noise into the patch and make it more difficult to review. + However, note that the ``futurize`` script takes advantage of PEP 414 and + does not remove explicit ``u''`` prefixes that already exist. + +4. Turning on ``unicode_literals`` converts even docstrings to unicode, but + Pydoc breaks with unicode docstrings containing non-ASCII characters for + Python versions < 2.7.7. (`Fix + committed <http://bugs.python.org/issue1065986#msg207403>`_ in Jan 2014.):: + + >>> def f(): + ... u"Author: Martin von Löwis" + + >>> help(f) + + /Users/schofield/Install/anaconda/python.app/Contents/lib/python2.7/pydoc.pyc in pipepager(text, cmd) + 1376 pipe = os.popen(cmd, 'w') + 1377 try: + -> 1378 pipe.write(text) + 1379 pipe.close() + 1380 except IOError: + + UnicodeEncodeError: 'ascii' codec can't encode character u'\xf6' in position 71: ordinal not in range(128) + +See `this Stack Overflow thread +<http://stackoverflow.com/questions/809796/any-gotchas-using-unicode-literals-in-python-2-6>`_ +for other gotchas. + + +Others' perspectives +~~~~~~~~~~~~~~~~~~~~ + +In favour of ``unicode_literals`` +********************************* + +Django recommends importing ``unicode_literals`` as its top `porting tip <https://docs.djangoproject.com/en/dev/topics/python3/#unicode-literals>`_ for +migrating Django extension modules to Python 3. The following `quote +<https://groups.google.com/forum/#!topic/django-developers/2ddIWdicbNY>`_ is +from Aymeric Augustin on 23 August 2012 regarding why he chose +``unicode_literals`` for the port of Django to a Python 2/3-compatible +codebase.: + + "... I'd like to explain why this PEP [PEP 414, which allows explicit + ``u''`` prefixes for unicode literals on Python 3.3+] is at odds with + the porting philosophy I've applied to Django, and why I would have + vetoed taking advantage of it. + + "I believe that aiming for a Python 2 codebase with Python 3 + compatibility hacks is a counter-productive way to port a project. You + end up with all the drawbacks of Python 2 (including the legacy `u` + prefixes) and none of the advantages Python 3 (especially the sane + string handling). + + "Working to write Python 3 code, with legacy compatibility for Python + 2, is much more rewarding. Of course it takes more effort, but the + results are much cleaner and much more maintainable. It's really about + looking towards the future or towards the past. + + "I understand the reasons why PEP 414 was proposed and why it was + accepted. It makes sense for legacy software that is minimally + maintained. I hope nobody puts Django in this category!" + + +Against ``unicode_literals`` +**************************** + + "There are so many subtle problems that ``unicode_literals`` causes. + For instance lots of people accidentally introduce unicode into + filenames and that seems to work, until they are using it on a system + where there are unicode characters in the filesystem path." + + -- Armin Ronacher + + "+1 from me for avoiding the unicode_literals future, as it can have + very strange side effects in Python 2.... This is one of the key + reasons I backed Armin's PEP 414." + + -- Nick Coghlan + + "Yeah, one of the nuisances of the WSGI spec is that the header values + IIRC are the str or StringType on both py2 and py3. With + unicode_literals this causes hard-to-spot bugs, as some WSGI servers + might be more tolerant than others, but usually using unicode in python + 2 for WSGI headers will cause the response to fail." + + -- Antti Haapala diff --git a/Python/Dependencies/future-0.18.2/docs/upgrading.rst b/Python/Dependencies/future-0.18.2/docs/upgrading.rst new file mode 100644 index 0000000..0d8afca --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/upgrading.rst @@ -0,0 +1,12 @@ +.. upgrading + +Upgrading +********* + +We strive to support compatibility between versions of ``python-future``. Part of this involves keeping around old interfaces and marking them as deprecated for a period to allow projects to transition in a straightforward manner to using the new interfaces. + + +.. upgrading-to-v0.12 + +Upgrading to v0.12 +================== diff --git a/Python/Dependencies/future-0.18.2/docs/utilities.rst b/Python/Dependencies/future-0.18.2/docs/utilities.rst new file mode 100644 index 0000000..e3f1e9c --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/utilities.rst @@ -0,0 +1,48 @@ +.. _utilities-guide: + +Utilities +--------- + +:mod:`future` also provides some useful functions and decorators to ease +backward compatibility with Py2 in the :mod:`future.utils` and +:mod:`past.utils` modules. These are a selection of the most useful functions +from ``six`` and various home-grown Py2/3 compatibility modules from popular +Python projects, such as Jinja2, Pandas, IPython, and Django. The goal is to +consolidate these in one place, tested and documented, obviating the need for +every project to repeat this work. + +Examples:: + + # Functions like print() expect __str__ on Py2 to return a byte + # string. This decorator maps the __str__ to __unicode__ on Py2 and + # defines __str__ to encode it as utf-8: + + from future.utils import python_2_unicode_compatible + + @python_2_unicode_compatible + class MyClass(object): + def __str__(self): + return u'Unicode string: \u5b54\u5b50' + a = MyClass() + + # This then prints the Chinese characters for Confucius: + print(a) + + + # Iterators on Py3 require a __next__() method, whereas on Py2 this + # is called next(). This decorator allows Py3-style iterators to work + # identically on Py2: + + @implements_iterator + class Upper(object): + def __init__(self, iterable): + self._iter = iter(iterable) + def __next__(self): # note the Py3 interface + return next(self._iter).upper() + def __iter__(self): + return self + + print(list(Upper('hello'))) + # prints ['H', 'E', 'L', 'L', 'O'] + +On Python 3 these decorators are no-ops. diff --git a/Python/Dependencies/future-0.18.2/docs/what_else.rst b/Python/Dependencies/future-0.18.2/docs/what_else.rst new file mode 100644 index 0000000..51f1986 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/what_else.rst @@ -0,0 +1,25 @@ +.. _what-else: + +What else you need to know +************************** + +The following points are important to know about when writing Python 2/3 +compatible code. + +.. _what-else-essentials: + +.. include:: bytes_object.rst +.. include:: str_object.rst +.. include:: dict_object.rst +.. include:: int_object.rst +.. include:: isinstance.rst +.. include:: open_function.rst +.. include:: custom_str_methods.rst +.. include:: custom_iterators.rst + +.. _what-else-advanced: + +.. include:: bind_method.rst +.. include:: metaclasses.rst + +.. diff --git a/Python/Dependencies/future-0.18.2/docs/whatsnew.rst b/Python/Dependencies/future-0.18.2/docs/whatsnew.rst new file mode 100644 index 0000000..e0b4603 --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/whatsnew.rst @@ -0,0 +1,174 @@ +.. _whats-new: + +What's New +********** + +What's new in version 0.18.2 (2019-10-30) +========================================= +This is a minor bug-fix release containing a number of fixes: +- Fix min/max functions with generators, and 'None' default (PR #514) +- Use BaseException in raise_() (PR #515) +- Fix builtins.round() for Decimals (Issue #501) +- Fix raise_from() to prevent failures with immutable classes (PR #518) +- Make FixInput idempotent (Issue #427) +- Fix type in newround (PR #521) +- Support mimetype guessing in urllib2 for Py3.8+ (Issue #508) + +Python 3.8 is not yet officially supported. + +What's new in version 0.18.1 (2019-10-09) +========================================= +This is a minor bug-fix release containing a fix for raise_() +when passed an exception that's not an Exception (e.g. BaseException +subclasses) + +What's new in version 0.18.0 (2019-10-09) +========================================= +This is a major bug-fix and feature release, including: + +- Fix collections.abc import for py38+ +- Remove import for isnewbytes() function, reducing CPU cost significantly +- Fix bug with importing past.translation when importing past which breaks zipped python installations +- Fix an issue with copyreg import under Py3 that results in unexposed stdlib functionality +- Export and document types in future.utils +- Update behavior of newstr.__eq__() to match str.__eq__() as per reference docs +- Fix raising and the raising fixer to handle cases where the syntax is ambigious +- Allow "default" parameter in min() and max() (Issue #334) +- Implement __hash__() in newstr (Issue #454) +- Future proof some version checks to handle the fact that Py4 won't be a major breaking release +- Fix urllib.request imports for Python 3.8 compatibility (Issue #447) +- Fix future import ordering (Issue #445) +- Fixed bug in fix_division_safe fixture (Issue #434) +- Do not globally destroy re.ASCII in PY3 +- Fix a bug in email.Message.set_boundary() (Issue #429) +- Implement format_map() in str +- Implement readinto() for socket.fp + +As well as a number of corrections to a variety of documentation, and updates to +test infrastructure. + +What's new in version 0.17.1 (2018-10-30) +========================================= +This release address a packaging error because of an erroneous declaration that +any built wheels are universal. + +What's new in version 0.17.0 (2018-10-19) +========================================= + +This is a major bug-fix release, including: + +- Fix ``from collections import ChainMap`` after install_aliases() (issue #226) +- Fix multiple import from ``__future__`` bug in futurize (issue #113) +- Add support for proper %s formatting of newbytes +- Properly implement iterator protocol for newrange object +- Fix ``past.translation`` on read-only file systems +- Fix Tkinter import bug introduced in Python 2.7.4 (issue #262) +- Correct TypeError to ValueError in a specific edge case for newrange +- Support inequality tests betwen newstrs and newbytes +- Add type check to __get__ in newsuper +- Fix fix_divsion_safe to support better conversion of complex expressions, and + skip obvious float division. + +As well as a number of corrections to a variety of documentation, and updates to +test infrastructure. + +What's new in version 0.16.0 (2016-10-27) +========================================== + +This release removes the ``configparser`` package as an alias for +``ConfigParser`` on Py2 to improve compatibility with the backported +`configparser package <https://pypi.org/project/configparser/>`. Previously +``python-future`` and the PyPI ``configparser`` backport clashed, causing +various compatibility issues. (Issues #118, #181) + +If your code previously relied on ``configparser`` being supplied by +``python-future``, the recommended upgrade path is to run ``pip install +configparser`` or add ``configparser`` to your ``requirements.txt`` file. + +Note that, if you are upgrading ``future`` with ``pip``, you may need to +uninstall the old version of future or manually remove the +``site-packages/future-0.15.2-py2.7.egg`` folder for this change to take +effect on your system. + +This releases also fixes these bugs: + +- Fix ``newbytes`` constructor bug. (Issue #171) +- Fix semantics of ``bool()`` with ``newobject``. (Issue #211) +- Fix ``standard_library.install_aliases()`` on PyPy. (Issue #205) +- Fix assertRaises for ``pow`` and ``compile``` on Python 3.5. (Issue #183) +- Fix return argument of ``future.utils.ensure_new_type`` if conversion to + new type does not exist. (Issue #185) +- Add missing ``cmp_to_key`` for Py2.6. (Issue #189) +- Allow the ``old_div`` fixer to be disabled. (Issue #190) +- Improve compatibility with Google App Engine. (Issue #231) +- Add some missing imports to the ``tkinter`` and ``tkinter.filedialog`` + package namespaces. (Issues #212 and #233) +- More complete implementation of ``raise_from`` on PY3. (Issues #141, + #213 and #235, fix provided by Varriount) + + +What's new in version 0.15.2 (2015-09-11) +========================================= + +This is a minor bug-fix release: + +- Fix ``socket.create_connection()`` backport on Py2.6 (issue #162) +- Add more tests of ``urllib.request`` etc. +- Fix ``newsuper()`` calls from the ``__init__`` method of PyQt subclassses + (issue #160, thanks to Christopher Arndt) + +What's new in version 0.15.1 (2015-09-09) +========================================= + +This is a minor bug-fix release: + +- Use 3-argument ``socket.create_connection()`` backport to restore Py2.6 + compatibility in ``urllib.request.urlopen()`` (issue #162) +- Remove breakpoint in ``future.backports.http.client`` triggered on certain + data (issue #164) +- Move ``exec`` fixer to stage 1 of ``futurize`` because the forward-compatible ``exec(a, b)`` + idiom is supported in Python 2.6 and 2.7. See + https://docs.python.org/2/reference/simple_stmts.html#exec. + + +What's new in version 0.15.0 (2015-07-25) +========================================= + +This release fixes compatibility bugs with CherryPy's Py2/3 compat layer and +the latest version of the ``urllib3`` package. It also adds some additional +backports for Py2.6 and Py2.7 from Py3.4's standard library. + +New features: + +- ``install_aliases()`` now exposes full backports of the Py3 urllib submodules + (``parse``, ``request`` etc.) from ``future.backports.urllib`` as submodules + of ``urllib`` on Py2. This implies, for example, that + ``urllib.parse.unquote`` now takes an optional encoding argument as it does + on Py3. This improves compatibility with CherryPy's Py2/3 compat layer (issue + #158). +- ``tkinter.ttk`` support (issue #151) +- Backport of ``collections.ChainMap`` (issue #150) +- Backport of ``itertools.count`` for Py2.6 (issue #152) +- Enable and document support for the ``surrogateescape`` error handler for ``newstr`` and ``newbytes`` objects on Py2.x (issue #116). This feature is currently in alpha. +- Add constants to ``http.client`` such as ``HTTP_PORT`` and ``BAD_REQUEST`` (issue #137) +- Backport of ``reprlib.recursive_repr`` to Py2 + +Bug fixes: + +- Add ``HTTPMessage`` to ``http.client``, which is missing from ``httplib.__all__`` on Python <= 2.7.10. This restores compatibility with the latest ``urllib3`` package (issue #159, thanks to Waldemar Kornewald) +- Expand newint.__divmod__ and newint.__rdivmod__ to fall back to <type 'long'> + implementations where appropriate (issue #146 - thanks to Matt Bogosian) +- Fix newrange slicing for some slice/range combos (issue #132, thanks to Brad Walker) +- Small doc fixes (thanks to Michael Joseph and Tim Tröndle) +- Improve robustness of test suite against opening .pyc files as text on Py2 +- Update backports of ``Counter`` and ``OrderedDict`` to use the newer + implementations from Py3.4. This fixes ``.copy()`` preserving subclasses etc. +- ``futurize`` no longer breaks working Py2 code by changing ``basestring`` to + ``str``. Instead it imports the ``basestring`` forward-port from + ``past.builtins`` (issues #127 and #156) +- ``future.utils``: add ``string_types`` etc. and update docs (issue #126) + +Previous versions +================= + +See :ref:`whats-old` for versions prior to v0.15. diff --git a/Python/Dependencies/future-0.18.2/docs/why_python3.rst b/Python/Dependencies/future-0.18.2/docs/why_python3.rst new file mode 100644 index 0000000..a4b535f --- /dev/null +++ b/Python/Dependencies/future-0.18.2/docs/why_python3.rst @@ -0,0 +1,66 @@ +.. _why-python3: + +Why Python 3? +============= + +- Python 2.7 is the final Python 2.x release. Python 3.x is the future. + The Python ecosystem needs to consolidate. A split or schism between + different incompatible versions is not healthy for growing the + community. +- Function annotations +- Decimal module 100x faster. As fast as floats. +- Easier to learn. (Less cruft in language and stdlib, more consistency, better docstrings, etc.) +- Much safer handling of unicode text and encodings: fewer bugs. +- More memory efficiency (shared dict keys (PEP 412) and space-efficient + Unicode representation (PEP 393)) +- Exception chaining + +Why are Unicode strings better on Python 3? +------------------------------------------- + +- it is not the default string type (you have to prefix the string + with a u to get Unicode); + +- it is missing some functionality, e.g. casefold; + +- there are two distinct implementations, narrow builds and wide builds; + +- wide builds take up to four times more memory per string as needed; + +- narrow builds take up to two times more memory per string as needed; + +- worse, narrow builds have very naive (possibly even "broken") + handling of code points in the Supplementary Multilingual Planes. + +The unicode string type in Python 3 is better because: + +- it is the default string type; + +- it includes more functionality; + +- starting in Python 3.3, it gets rid of the distinction between + narrow and wide builds; + +- which reduces the memory overhead of strings by up to a factor + of four in many cases; + +- and fixes the issue of SMP code points. + +(quote from a mailing list post by Steve D'Aprano on 2014-01-17). + + +New features +------------ + +Standard library: +~~~~~~~~~~~~~~~~~ + +- SSL contexts in http.client +- + + + +Non-arguments for Python 3 +========================== + +- |
