eight


Nameeight JSON
Version 1.0.1 PyPI version JSON
download
home_pagehttps://github.com/kislyuk/eight
SummaryPython 2 to the power of 3. A lightweight porting helper library.
upload_time2021-03-16 00:12:21
maintainer
docs_urlNone
authorAndrey Kislyuk
requires_python
licenseApache Software License
keywords
VCS
bugtrack_url
requirements future
Travis-CI No Travis.
coveralls test coverage No coveralls.
            eight: Python 2 to the power of 3
=================================
Eight is a Python module that provides a minimalist compatibility layer between Python 3 and 2. Eight lets you write
code for Python 3.3+ while providing limited compatibility with Python 2.7 with no code changes.  Eight is inspired by
`six <https://pythonhosted.org/six/>`_, `nine <https://github.com/nandoflorestan/nine>`_, and `python-future
<https://github.com/PythonCharmers/python-future>`_, but provides better internationalization (i18n) support, is more
lightweight, easier to use, and unambiguously biased toward Python 3 code: if you remove eight from your code, it will
continue to function exactly as it did with eight on Python 3.

To write code for Python 3 that is portable to Python 2, you may also want to read Armin Ronacher's excellent `Python 3
porting guide <http://lucumr.pocoo.org/2013/5/21/porting-to-python-3-redux/>`_, as well as the official
`porting guide <http://docs.python.org/3/howto/pyporting.html>`_.

Writing ``from eight import *`` in your code is a no-op in Python 3. In Python 2, it binds a bunch of Python 3 names to
their Python 2 equivalents. Also, if you need to import a module or module member that was renamed in Python 3, writing
``from eight import <module>`` will do the right thing (equivalent to ``import <module>`` on Python 3 and ``import
<old_name> as <module>`` on Python 2). Finally, eight can optionally wrap your standard streams and environment variable
I/O to use text, not bytes (see below).

Installation
------------
::

    pip install eight

Synopsis
--------

.. code-block:: python

    from eight import *
    from eight import queue
    from eight.collections import UserList, deque

If you use ``print``, division, non-ASCII literals, or relative imports, you should also add this `future import
<http://docs.python.org/3/library/__future__.html>`_ at the top of each source file:

.. code-block:: python

    from __future__ import (print_function, division, unicode_literals, absolute_import)

Wrapping stdio
--------------
Eight provides wrappers for ``sys.stdin``, ``sys.stdout``, and ``sys.stderr`` to make them (and methods that use them)
behave like they do on Python 3. Specifically, in Python 3 these streams accept text data, and their ``.buffer`` attributes
refer to the underlying streams that accept bytes. Eight uses the `io <http://docs.python.org/2/library/io.html>`_ module
to do the same for you, but subclasses the TextIOWrapper class for ``sys.stdout`` and ``sys.stderr`` to coerce non-unicode
input to unicode on Python 2 (otherwise, because of the Python 2 semantics, things like exception printing cease to work).

To enable stdio wrapping, use the following:

.. code-block:: python

    import eight
    eight.wrap_stdio()

To revert the effects of this on any of the streams, use the detach method, e.g. ``sys.stdin = sys.stdin.detach()`` (but
remember to condition this on ``eight.USING_PYTHON2``). See the `io module documentation
<http://docs.python.org/2/library/io.html>`_ for more information.

Decoding command-line arguments
-------------------------------
Eight provides a utility function to decode the contents of ``sys.argv`` on Python 2 (as Python 3 does). It uses
``sys.stdin.encoding`` as the encoding to do so:

.. code-block:: python

    import eight
    eight.decode_command_line_args()

The call to ``decode_command_line_args()`` replaces ``sys.argv`` with its decoded contents and returns the new contents.
On Python 3, the call is a no-op (it returns ``sys.argv`` and leaves it intact).

Wrapping environment variable getters and setters
-------------------------------------------------
Eight provides utility wrappers to help bring Python 2 environment variable access and assignment in line with Python
3: encode the input to ``os.putenv`` (which is used for statements like ``os.environ[x] = y``) and decode the output of
``os.getenv`` (used for ``x = os.environ[y]``). Use ``wrap_os_environ_io()`` to monkey-patch these wrappers into the
``os`` module:

.. code-block:: python

    import eight
    eight.wrap_os_environ_io()

On Python 3, the call is a no-op.

Selecting from the buffet
-------------------------
You can see what ``from eight import *`` will do by running `IPython <https://github.com/ipython/ipython>`_ and typing
``import eight``, then ``eight.<TAB>``. Here is a full list of what's available:

* ``ascii``
* ``bytes``
* ``chr``
* ``filter``
* ``hex``
* ``input``
* ``int``
* ``map``
* ``oct``
* ``open``
* ``range``
* ``round``
* ``str``
* ``super``
* ``zip``

You can import these symbols by listing them explicitly. If for any reason you see an issue with importing them all (which
is recommended), you can of course import a subset.

In addition to names imported by ``from eight import *``, the following modules are available and should be imported by
name using ``from eight import <name>`` when needed:

* ``queue`` (old name: ``Queue``)
* ``builtins`` (old name: ``__builtin__``)
* ``copyreg`` (old name: ``copy_reg``)
* ``configparser`` (old name: ``ConfigParser``)
* ``reprlib`` (old name: ``repr``)
* ``winreg`` (old name: ``_winreg``)
* ``_thread`` (old name: ``thread``)
* ``_dummy_thread`` (old name: ``dummy_thread``)

The following modules have attributes which resided elsewhere in Python 2: TODO

Acknowledgments
---------------
`Python-future <https://github.com/PythonCharmers/python-future>`_ for doing a bunch of heavy lifting on backports of
Python 3 features.

Links
-----
* `Project home page (GitHub) <https://github.com/kislyuk/eight>`_
* `Documentation (Read the Docs) <https://eight.readthedocs.io/en/latest/>`_
* `Package distribution (PyPI) <https://pypi.python.org/pypi/eight>`_

Bugs
~~~~
Please report bugs, issues, feature requests, etc. on `GitHub <https://github.com/kislyuk/eight/issues>`_.

License
-------
Licensed under the terms of the `Apache License, Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_.

.. image:: https://img.shields.io/travis/kislyuk/eight.svg
        :target: https://travis-ci.org/kislyuk/eight
.. image:: https://codecov.io/github/kislyuk/eight/coverage.svg?branch=master
        :target: https://codecov.io/github/kislyuk/eight?branch=master
.. image:: https://img.shields.io/pypi/v/eight.svg
        :target: https://pypi.python.org/pypi/eight
.. image:: https://img.shields.io/pypi/l/eight.svg
        :target: https://pypi.python.org/pypi/eight
.. image:: https://readthedocs.org/projects/eight/badge/?version=latest
        :target: https://eight.readthedocs.io/



            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/kislyuk/eight",
    "name": "eight",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "",
    "author": "Andrey Kislyuk",
    "author_email": "kislyuk@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/fb/17/16e936433e7eb99ae62080846e6a47b3cbfea645ae59e25db2d6560570c0/eight-1.0.1.tar.gz",
    "platform": "MacOS X",
    "description": "eight: Python 2 to the power of 3\n=================================\nEight is a Python module that provides a minimalist compatibility layer between Python 3 and 2. Eight lets you write\ncode for Python 3.3+ while providing limited compatibility with Python 2.7 with no code changes.  Eight is inspired by\n`six <https://pythonhosted.org/six/>`_, `nine <https://github.com/nandoflorestan/nine>`_, and `python-future\n<https://github.com/PythonCharmers/python-future>`_, but provides better internationalization (i18n) support, is more\nlightweight, easier to use, and unambiguously biased toward Python 3 code: if you remove eight from your code, it will\ncontinue to function exactly as it did with eight on Python 3.\n\nTo write code for Python 3 that is portable to Python 2, you may also want to read Armin Ronacher's excellent `Python 3\nporting guide <http://lucumr.pocoo.org/2013/5/21/porting-to-python-3-redux/>`_, as well as the official\n`porting guide <http://docs.python.org/3/howto/pyporting.html>`_.\n\nWriting ``from eight import *`` in your code is a no-op in Python 3. In Python 2, it binds a bunch of Python 3 names to\ntheir Python 2 equivalents. Also, if you need to import a module or module member that was renamed in Python 3, writing\n``from eight import <module>`` will do the right thing (equivalent to ``import <module>`` on Python 3 and ``import\n<old_name> as <module>`` on Python 2). Finally, eight can optionally wrap your standard streams and environment variable\nI/O to use text, not bytes (see below).\n\nInstallation\n------------\n::\n\n    pip install eight\n\nSynopsis\n--------\n\n.. code-block:: python\n\n    from eight import *\n    from eight import queue\n    from eight.collections import UserList, deque\n\nIf you use ``print``, division, non-ASCII literals, or relative imports, you should also add this `future import\n<http://docs.python.org/3/library/__future__.html>`_ at the top of each source file:\n\n.. code-block:: python\n\n    from __future__ import (print_function, division, unicode_literals, absolute_import)\n\nWrapping stdio\n--------------\nEight provides wrappers for ``sys.stdin``, ``sys.stdout``, and ``sys.stderr`` to make them (and methods that use them)\nbehave like they do on Python 3. Specifically, in Python 3 these streams accept text data, and their ``.buffer`` attributes\nrefer to the underlying streams that accept bytes. Eight uses the `io <http://docs.python.org/2/library/io.html>`_ module\nto do the same for you, but subclasses the TextIOWrapper class for ``sys.stdout`` and ``sys.stderr`` to coerce non-unicode\ninput to unicode on Python 2 (otherwise, because of the Python 2 semantics, things like exception printing cease to work).\n\nTo enable stdio wrapping, use the following:\n\n.. code-block:: python\n\n    import eight\n    eight.wrap_stdio()\n\nTo revert the effects of this on any of the streams, use the detach method, e.g. ``sys.stdin = sys.stdin.detach()`` (but\nremember to condition this on ``eight.USING_PYTHON2``). See the `io module documentation\n<http://docs.python.org/2/library/io.html>`_ for more information.\n\nDecoding command-line arguments\n-------------------------------\nEight provides a utility function to decode the contents of ``sys.argv`` on Python 2 (as Python 3 does). It uses\n``sys.stdin.encoding`` as the encoding to do so:\n\n.. code-block:: python\n\n    import eight\n    eight.decode_command_line_args()\n\nThe call to ``decode_command_line_args()`` replaces ``sys.argv`` with its decoded contents and returns the new contents.\nOn Python 3, the call is a no-op (it returns ``sys.argv`` and leaves it intact).\n\nWrapping environment variable getters and setters\n-------------------------------------------------\nEight provides utility wrappers to help bring Python 2 environment variable access and assignment in line with Python\n3: encode the input to ``os.putenv`` (which is used for statements like ``os.environ[x] = y``) and decode the output of\n``os.getenv`` (used for ``x = os.environ[y]``). Use ``wrap_os_environ_io()`` to monkey-patch these wrappers into the\n``os`` module:\n\n.. code-block:: python\n\n    import eight\n    eight.wrap_os_environ_io()\n\nOn Python 3, the call is a no-op.\n\nSelecting from the buffet\n-------------------------\nYou can see what ``from eight import *`` will do by running `IPython <https://github.com/ipython/ipython>`_ and typing\n``import eight``, then ``eight.<TAB>``. Here is a full list of what's available:\n\n* ``ascii``\n* ``bytes``\n* ``chr``\n* ``filter``\n* ``hex``\n* ``input``\n* ``int``\n* ``map``\n* ``oct``\n* ``open``\n* ``range``\n* ``round``\n* ``str``\n* ``super``\n* ``zip``\n\nYou can import these symbols by listing them explicitly. If for any reason you see an issue with importing them all (which\nis recommended), you can of course import a subset.\n\nIn addition to names imported by ``from eight import *``, the following modules are available and should be imported by\nname using ``from eight import <name>`` when needed:\n\n* ``queue`` (old name: ``Queue``)\n* ``builtins`` (old name: ``__builtin__``)\n* ``copyreg`` (old name: ``copy_reg``)\n* ``configparser`` (old name: ``ConfigParser``)\n* ``reprlib`` (old name: ``repr``)\n* ``winreg`` (old name: ``_winreg``)\n* ``_thread`` (old name: ``thread``)\n* ``_dummy_thread`` (old name: ``dummy_thread``)\n\nThe following modules have attributes which resided elsewhere in Python 2: TODO\n\nAcknowledgments\n---------------\n`Python-future <https://github.com/PythonCharmers/python-future>`_ for doing a bunch of heavy lifting on backports of\nPython 3 features.\n\nLinks\n-----\n* `Project home page (GitHub) <https://github.com/kislyuk/eight>`_\n* `Documentation (Read the Docs) <https://eight.readthedocs.io/en/latest/>`_\n* `Package distribution (PyPI) <https://pypi.python.org/pypi/eight>`_\n\nBugs\n~~~~\nPlease report bugs, issues, feature requests, etc. on `GitHub <https://github.com/kislyuk/eight/issues>`_.\n\nLicense\n-------\nLicensed under the terms of the `Apache License, Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_.\n\n.. image:: https://img.shields.io/travis/kislyuk/eight.svg\n        :target: https://travis-ci.org/kislyuk/eight\n.. image:: https://codecov.io/github/kislyuk/eight/coverage.svg?branch=master\n        :target: https://codecov.io/github/kislyuk/eight?branch=master\n.. image:: https://img.shields.io/pypi/v/eight.svg\n        :target: https://pypi.python.org/pypi/eight\n.. image:: https://img.shields.io/pypi/l/eight.svg\n        :target: https://pypi.python.org/pypi/eight\n.. image:: https://readthedocs.org/projects/eight/badge/?version=latest\n        :target: https://eight.readthedocs.io/\n\n\n",
    "bugtrack_url": null,
    "license": "Apache Software License",
    "summary": "Python 2 to the power of 3. A lightweight porting helper library.",
    "version": "1.0.1",
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "7d04a7a2826cc3caae60b578dfcd0bcd",
                "sha256": "bd6967ec7cf9e61ab18b55751236ed89a8363cfcb69127aace336869615245d5"
            },
            "downloads": -1,
            "filename": "eight-1.0.1-py2.py3-none-any.whl",
            "has_sig": true,
            "md5_digest": "7d04a7a2826cc3caae60b578dfcd0bcd",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": null,
            "size": 10432,
            "upload_time": "2021-03-16T00:12:20",
            "upload_time_iso_8601": "2021-03-16T00:12:20.604719Z",
            "url": "https://files.pythonhosted.org/packages/d9/17/0bc3026bbd6ee63dcff9a276a3db4ab11d845ba748aab8cdf20fa4d241f8/eight-1.0.1-py2.py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "c140d3904ff8522988bf555596a45958",
                "sha256": "6465970d3c12a1d759151690629b10b50ffb124c9b62e912999ee9233378a562"
            },
            "downloads": -1,
            "filename": "eight-1.0.1.tar.gz",
            "has_sig": true,
            "md5_digest": "c140d3904ff8522988bf555596a45958",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 11021,
            "upload_time": "2021-03-16T00:12:21",
            "upload_time_iso_8601": "2021-03-16T00:12:21.942838Z",
            "url": "https://files.pythonhosted.org/packages/fb/17/16e936433e7eb99ae62080846e6a47b3cbfea645ae59e25db2d6560570c0/eight-1.0.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2021-03-16 00:12:21",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": "kislyuk",
    "github_project": "eight",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "future",
            "specs": [
                [
                    ">=",
                    "0.16"
                ],
                [
                    "<",
                    "0.19"
                ]
            ]
        }
    ],
    "tox": true,
    "lcname": "eight"
}
        
Elapsed time: 0.01982s