| =================== |
| PEP 484: Type Hints |
| =================== |
| |
| .. image:: https://badges.gitter.im/python/typing.svg |
| :alt: Chat at https://gitter.im/python/typing |
| :target: https://gitter.im/python/typing?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge |
| |
| This GitHub repo is used for development of the ``typing`` module |
| defined by PEP 484. The module is available in Python since version |
| 3.5.0 on a provisional basis until Python 3.7.0. |
| |
| Authors |
| ------- |
| |
| * Guido van Rossum |
| |
| * Jukka Lehtosalo |
| |
| * Łukasz Langa |
| |
| BDFL-Delegate |
| ------------- |
| |
| The BDFL-Delegate is Mark Shannon. He was the final reviewer of PEP 484 |
| and ultimately accepted it on May 22, 2014. |
| |
| Important dates |
| --------------- |
| |
| * May 24, 2015: Python 3.5.0 beta 1 -- PEP 484 accepted, ``typing`` |
| checked into the CPython repo |
| |
| * September 13, 2015: Python 3.5.0 final release; ``typing`` is |
| available on a provisional basis |
| |
| * December 23, 2016: Python 3.6.0 final release; ``typing`` stays |
| provisional for the course of the 3.6 releases |
| |
| * January 29, 2018: Python 3.7.0 beta 1, feature freeze for the release, |
| including the ``typing`` module |
| |
| * June 15, 2018: Python 3.7.0 final release, the ``typing`` module is no |
| longer provisional |
| |
| The dates for Python 3.7 are based on PEP 537 and may still change. |
| |
| Important URLs |
| -------------- |
| |
| The python.org rendering of PEP 484 lives at |
| https://www.python.org/dev/peps/pep-0484/. |
| |
| Two related informational PEPs exist: |
| |
| * An explanation of the theory behind type hints can be found in |
| https://www.python.org/dev/peps/pep-0483/. |
| |
| * A literature review is at https://www.python.org/dev/peps/pep-0482/. |
| |
| The python.org site automatically updates (with a slight delay, |
| typically in the order of 5-60 minutes) whenever the python/peps repo is |
| updated. |
| |
| Workflow |
| -------- |
| |
| * The typing.py module and its unittests are edited in the src |
| subdirectory of this repo. The python2 subdirectory contains the |
| Python 2 backport. |
| |
| * The PEPs 484, 483, and 482 are edited in the GitHub python/peps repo. |
| |
| * Use the GitHub issue tracker for this repo to collect concerns and |
| TO DO items for PEPs 484, 483, and 482 as well as for typing.py. |
| |
| * Accumulate changes in the GitHub repo, closing issues as they are |
| either decided and described in PEP 484, or implemented in |
| typing.py, or both, as befits the issue. (Some issues will be |
| closed as "won't fix" after a decision is reached not to take |
| action.) |
| |
| * Make frequent small commits with clear descriptions. Preferably use |
| a separate commit for each functional change, so the edit history is |
| clear, merge conflicts are unlikely, and it's easy to roll back a |
| change when further discussion reverts an earlier tentative decision |
| that was already written up and/or implemented. |
| |
| * Push to GitHub frequently. |
| |
| * Pull from GitHub frequently, rebasing conflicts carefully (or |
| merging, if a conflicting change was already pushed). |
| |
| * At reasonable checkpoints: post current versions of PEPs |
| to python-dev, making sure to update the |
| Post-History header in python/peps repo. This is typically done by Guido. |
| |
| Tracker labels |
| -------------- |
| |
| * bug: Needs to be fixed in typing.py. |
| |
| * to do: Editing task for PEP 484 or for this repo. |
| |
| * enhancement: Proposed new feature. |
| |
| * postponed: Idea up for discussion. |
| |
| * out of scope: Somebody else's problem. |
| |
| Workflow for mypy changes |
| ------------------------- |
| |
| * Use the GitHub issue tracker for the mypy repo (python/mypy). The mypy |
| core developers accept pull requests at their discretion. |
| |
| * mypy uses ``typing.py`` from the available standard library when ran |
| on Python 3.5+ and uses the `PyPI version |
| <https://pypi.python.org/pypi/typing>`_ for older Python versions |
| |
| * The full list of mypy issues marked as PEP 484 compatibility issues is |
| here: https://github.com/python/mypy/labels/topic-pep-484 |
| |
| Workflow for CPython changes |
| ---------------------------- |
| |
| * At Guido's discretion, he will from time to time copy typing.py and |
| test_typing.py from the python/typing GitHub repo to the cpython repo. |
| |
| * This process includes merging changes made directly in the cpython |
| repo by other core developers. |
| |
| * The changes are merged in three branches (3.5, 3.6, default) due to |
| the module's provisional status. |
| |
| Workflow for PyPI releases |
| -------------------------- |
| |
| * Run tests under all supported versions. As of May 2019 this includes |
| 2.7, 3.4, 3.5, 3.6, 3.7. |
| |
| * On macOS, you can use `pyenv <https://github.com/pyenv/pyenv>`_ to |
| manage multiple Python installations. Long story short: |
| |
| * ``xcode-select --install`` |
| * ``brew install pyenv`` |
| * ``echo 'eval "$(pyenv init -)"' >> ~/.bash_profile`` |
| * Open a new shell |
| * ``pyenv install 3.5.3`` |
| * ``pyenv install 3.4.6`` |
| * (assuming you already have 2.7.13 and 3.6.1 from Homebrew) |
| * ``pyenv global system 3.5.3 3.4.6`` |
| |
| * You can use ``tox`` to automate running tests. |
| |
| * Update the version number in ``setup.py``. |
| |
| * Build the source and wheel distributions: |
| |
| * ``pip3 install -U setuptools wheel`` |
| * ``pip2 install -U setuptools wheel`` |
| * ``rm -rf dist/ build/`` |
| * ``python3 setup.py sdist bdist_wheel`` |
| * ``rm -rf build/`` (Works around `a Wheel bug <https://bitbucket.org/pypa/wheel/issues/147/bdist_wheel-should-start-by-cleaning-up>`_) |
| * ``python2 setup.py bdist_wheel`` |
| |
| * Install the built distributions locally and test (if you |
| were using ``tox``, you already tested the source distribution). |
| |
| * Make sure twine is up to date, then run ``twine upload dist/*``. |
