From b817bbdd936cfd78a98d5fdf9b43dcc8cc907bb2 Mon Sep 17 00:00:00 2001 From: hauntsaninja <> Date: Sat, 30 Oct 2021 17:31:52 -0700 Subject: [PATCH 1/2] Refresh README.md, CONTRIBUTING.md This was prompted by #11403 Changes include: - General streamlining of markdown - Remove outdated references, e.g. to Python 2 / how to install Python 3 - Mention the "type school" discussions repo, typing-sig mailing list - Remove roadmap, since there isn't really a mypy core team anymore - More concretely link to "good first issue" page, etc. Hopefully this is a better experience than the somewhat common case of gitter posts like "I know Python, please help me contribute" that don't really go anywhere - Consolidate contributing information in CONTRIBUTING.md - Remove issue tracker conventions, since the template does a pretty good job and the rest is either common sense or never looked at --- CONTRIBUTING.md | 174 +++++++++++++-------------------- CREDITS | 6 +- README.md | 252 ++++++++++++++---------------------------------- ROADMAP.md | 38 -------- 4 files changed, 140 insertions(+), 330 deletions(-) delete mode 100644 ROADMAP.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 13aeab4d01f5..d4b58035674b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,74 +1,89 @@ -Contributing to Mypy -==================== +# Contributing to Mypy Welcome! Mypy is a community project that aims to work for a wide -range of Python users and Python codebases. If you're trying Mypy on +range of Python users and Python codebases. If you're trying mypy on your Python code, your experience and what you can contribute are important to the project's success. +## Code of Conduct -Getting started, building, and testing --------------------------------------- +Everyone participating in the Mypy community, and in particular in our +issue tracker, pull requests, and chat, is expected to treat +other people with respect and more generally to follow the guidelines +articulated in the [Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/). -If you haven't already, take a look at the project's -[README.md file](README.md) -and the [Mypy documentation](https://mypy.readthedocs.io/en/latest/), -and try adding type annotations to your file and type-checking it with Mypy. +## Getting started with development -Discussion ----------- +### Setup -If you've run into behavior in Mypy you don't understand, or you're -having trouble working out a good way to apply it to your code, or -you've found a bug or would like a feature it doesn't have, we want to -hear from you! +Run the following: +``` +# Clone the mypy repository +git clone https://github.com/python/mypy.git -Our main forum for discussion is the project's [GitHub issue -tracker](https://github.com/python/mypy/issues). This is the right -place to start a discussion of any of the above or most any other -topic concerning the project. +# Enter the repository +cd mypy -For less formal discussion we have a chat room on -[gitter.im](https://gitter.im/python/typing). Some Mypy core developers -are almost always present; feel free to find us there and we're happy -to chat. Substantive technical discussion will be directed to the -issue tracker. +# Create then activate a virtual environment +python3 -m venv venv +source venv/bin/actiate -(We also have an IRC channel, `#python-mypy` on irc.freenode.net. -This is lightly used, we have mostly switched to the gitter room -mentioned above.) +# Install the test requirements and the project +python3 -m pip install -r test-requirements.txt +python3 -m pip install -e . +hash -r +``` -#### Code of Conduct +### Running tests -Everyone participating in the Mypy community, and in particular in our -issue tracker, pull requests, and IRC channel, is expected to treat -other people with respect and more generally to follow the guidelines -articulated in the [Python Community Code of -Conduct](https://www.python.org/psf/codeofconduct/). +Once setup, you should be able to run tests: +``` +python3 runtests.py +``` + +To use mypy to check mypy's own code, run: +``` +python3 runtests.py self +# or equivalently: +python3 -m mypy --config-file mypy_self_check.ini -p mypy +``` + +You can also use `tox` to run tests, for instance: +``` +tox -e py +``` + +## First time contributors + +If you're looking for things to help with, browse our [issue tracker](https://github.com/python/mypy/issues)! -First Time Contributors ------------------------ +In particular, look for: +- [good first issues](https://github.com/python/mypy/labels/good-first-issue) +- [good second issues](https://github.com/python/mypy/labels/good-second-issue) +- [documentation issues](https://github.com/python/mypy/labels/documentation) -Mypy appreciates your contribution! If you are interested in helping improve -mypy, there are several ways to get started: +It's also extremely easy to get started contributing to our sister project +[typeshed](https://github.com/python/typeshed/issues) that provides type stubs +for libraries. This is a great way to become familiar with type syntax. -* Contributing to [typeshed](https://github.com/python/typeshed/issues) is a great way to -become familiar with Python's type syntax. -* Work on [documentation issues](https://github.com/python/mypy/labels/documentation). -* Ask on [the chat](https://gitter.im/python/typing) or on -[the issue tracker](https://github.com/python/mypy/issues) about good beginner issues. +If you need help getting started, don't hesitate to ask on +[gitter](https://gitter.im/python/typing). -Submitting Changes ------------------- +To get help fixing a specific issue, it's often best to comment on the issue +itself. The more details you provide about what you've tried and where you've +looked, the easier it will be for you to get help. + +Interactive debuggers like `pdb` and `ipdb` are really useful for getting +started with the mypy codebase. This is a +[useful tutorial](https://realpython.com/python-debugging-pdb/). + +## Submitting changes Even more excellent than a good bug report is a fix for a bug, or the -implementation of a much-needed new feature. (*) We'd love to have +implementation of a much-needed new feature. We'd love to have your contributions. -(*) If your new feature will be a lot of work, we recommend talking to - us early -- see below. - We use the usual GitHub pull-request flow, which may be familiar to you if you've contributed to other projects on GitHub. For the mechanics, see [our git and GitHub workflow help page](https://github.com/python/mypy/wiki/Using-Git-And-GitHub), @@ -76,17 +91,8 @@ or [GitHub's own documentation](https://help.github.com/articles/using-pull-requ Anyone interested in Mypy may review your code. One of the Mypy core developers will merge your pull request when they think it's ready. -For every pull request, we aim to promptly either merge it or say why -it's not yet ready; if you go a few days without a reply, please feel -free to ping the thread by adding a new comment. - -For a list of mypy core developers, see the file [CREDITS](CREDITS). - -Preparing Changes ------------------ - -Before you begin: if your change will be a significant amount of work +If your change will be a significant amount of work to write, we highly recommend starting by opening an issue laying out what you want to do. That lets a conversation happen early in case other contributors disagree with what you'd like to do or have ideas @@ -113,8 +119,7 @@ You may also find other pages in the helpful in developing your change. -Core developer guidelines -------------------------- +## Core developer guidelines Core developers should follow these rules when processing pull requests: @@ -138,52 +143,3 @@ Core developers should follow these rules when processing pull requests: * If the PR fixes an issue, make sure something like "Fixes #xxx." occurs in the body of the message (not in the subject). * Use Markdown for formatting. - - -Issue-tracker conventions -------------------------- - -We aim to reply to all new issues promptly. We'll assign a milestone -to help us track which issues we intend to get to when, and may apply -labels to carry some other information. Here's what our milestones -and labels mean. - -### Task priority and sizing - -We use GitHub "labels" ([see our -list](https://github.com/python/mypy/labels)) to roughly order what we -want to do soon and less soon. There's two dimensions taken into -account: **priority** (does it matter to our users) and **size** (how -long will it take to complete). - -Bugs that aren't a huge deal but do matter to users and don't seem -like a lot of work to fix generally will be dealt with sooner; things -that will take longer may go further out. - -We are trying to keep the backlog at a manageable size, an issue that is -unlikely to be acted upon in foreseeable future is going to be -respectfully closed. This doesn't mean the issue is not important, but -rather reflects the limits of the team. - -The **question** label is for issue threads where a user is asking a -question but it isn't yet clear that it represents something to actually -change. We use the issue tracker as the preferred venue for such -questions, even when they aren't literally issues, to keep down the -number of distinct discussion venues anyone needs to track. These might -evolve into a bug or feature request. - -Issues **without a priority or size** haven't been triaged. We aim to -triage all new issues promptly, but there are some issues from previous -years that we haven't yet re-reviewed since adopting these conventions. - -### Other labels - -* **needs discussion**: This issue needs agreement on some kind of - design before it makes sense to implement it, and it either doesn't - yet have a design or doesn't yet have agreement on one. -* **feature**, **bug**, **crash**, **refactoring**, **documentation**: - These classify the user-facing impact of the change. Specifically - "refactoring" means there should be no user-facing effect. -* **topic-** labels group issues touching a similar aspect of the - project, for example PEP 484 compatibility, a specific command-line - option or dependency. diff --git a/CREDITS b/CREDITS index 508616cf2516..52564ba2ef41 100644 --- a/CREDITS +++ b/CREDITS @@ -10,14 +10,16 @@ the release blog posts at https://mypy-lang.blogspot.com/. Dropbox core team: Jukka Lehtosalo - Guido van Rossum Ivan Levkivskyi - Michael J. Sullivan Non-Dropbox core team members: Ethan Smith + Guido van Rossum Jelle Zijlstra + Michael J. Sullivan + Shantanu Jain + Xuanda Yuang Past Dropbox core team members: diff --git a/README.md b/README.md index 37e67ccaa893..457d53be90aa 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ mypy logo -Mypy: Optional Static Typing for Python +Mypy: Static Typing for Python ======================================= [![Build Status](https://api.travis-ci.com/python/mypy.svg?branch=master)](https://travis-ci.com/python/mypy) @@ -9,72 +9,68 @@ Mypy: Optional Static Typing for Python [![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/) -Got a question? Join us on Gitter! ----------------------------------- +Got a question? +--------------- -We don't have a mailing list; but we are always happy to answer -questions on [gitter chat](https://gitter.im/python/typing). If you are -sure you've found a bug please search our issue trackers for a -duplicate before filing a new issue: +We are always happy to answer questions! Here are some good places to ask them: -- [mypy tracker](https://github.com/python/mypy/issues) - for mypy issues -- [typeshed tracker](https://github.com/python/typeshed/issues) - for issues with specific modules -- [typing tracker](https://github.com/python/typing/issues) - for discussion of new type system features (PEP 484 changes) and - runtime bugs in the typing module +- for anything you're curious about, try [gitter chat](https://gitter.im/python/typing) +- for general questions about Python typing, try [typing discussions](https://github.com/python/typing/discussions) -What is mypy? -------------- +If you're just getting started, +[the documentation](https://mypy.readthedocs.io/en/stable/introduction.html) +and [type hints cheat sheet](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html) +can also help answer questions. -Mypy is an optional static type checker for Python. You can add type -hints ([PEP 484](https://www.python.org/dev/peps/pep-0484/)) to your -Python programs, and use mypy to type check them statically. -Find bugs in your programs without even running them! +If you think you've found a bug: -You can mix dynamic and static typing in your programs. You can always -fall back to dynamic typing when static typing is not convenient, such -as for legacy code. +- check our [common issues page](https://mypy.readthedocs.io/en/stable/common_issues.html) +- search our [issue tracker](https://github.com/python/mypy/issues) to see if + it's already been reported +- consider asking on [gitter chat](https://gitter.im/python/typing) -Here is a small example to whet your appetite (Python 3): +To report a bug or request an enhancement: -```python -from typing import Iterator +- report at [our issue tracker](https://github.com/python/mypy/issues) +- if the issue is with a specific library or function, consider reporting it at + [typeshed tracker](https://github.com/python/typeshed/issues) or the issue + tracker for that library -def fib(n: int) -> Iterator[int]: - a, b = 0, 1 - while a < n: - yield a - a, b = b, a + b -``` -See [the documentation](https://mypy.readthedocs.io/en/stable/introduction.html) for more examples. +To discuss a new type system feature: +- discuss at [typing-sig mailing list](https://mail.python.org/archives/list/typing-sig@python.org/) +- there is also some historical discussion [here](https://github.com/python/typing/issues) -For Python 2.7, the standard annotations are written as comments: -```python -def is_palindrome(s): - # type: (str) -> bool - return s == s[::-1] -``` -See [the documentation for Python 2 support](https://mypy.readthedocs.io/en/latest/python2.html). +What is mypy? +------------- -Mypy is in development; some features are missing and there are bugs. -See 'Development status' below. +Mypy is a static type checker for Python. -Requirements ------------- +Type checkers help ensure that you're using variables and functions in your code +correctly. With mypy, add type hints ([PEP 484](https://www.python.org/dev/peps/pep-0484/)) +to your Python programs, and mypy will warn you when you use those types +incorrectly. -You need Python 3.5 or later to run mypy. You can have multiple Python -versions (2.x and 3.x) installed on the same system without problems. +Python is a dynamic language, so usually you'll only see errors in your code +when you attempt to run it. Mypy is a *static* checker, so it finds bugs +in your programs without even running them! -In Ubuntu, Mint and Debian you can install Python 3 like this: +Mypy is designed with gradual typing in mind. This means you can add type +hints to your code base slowly and that you can always fall back to dynamic +typing when static typing is not convenient. - $ sudo apt-get install python3 python3-pip +Here is a small example to whet your appetite: -For other Linux flavors, macOS and Windows, packages are available at +```python +number = input("What is your favourite number?") +print("Well, my favourite number is: ", number + 1) # error: Unsupported operand types for + ("str" and "int") +``` + +See [the documentation](https://mypy.readthedocs.io/en/stable/introduction.html) for more examples. - https://www.python.org/getit/ +In particular, see: +- [type hints cheat sheet](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html) +- [getting started](https://mypy.readthedocs.io/en/stable/getting_started.html) Quick start @@ -89,14 +85,12 @@ If you want to run the latest version of the code, you can install from git: $ python3 -m pip install -U git+git://github.com/python/mypy.git -Now, if Python on your system is configured properly (else see -"Troubleshooting" below), you can type-check the [statically typed parts] of a -program like this: +Now you can type-check the [statically typed parts] of a program like this: $ mypy PROGRAM -You can always use a Python interpreter to run your statically typed -programs, even if they have type errors: +You can always use the Python interpreter to run your statically typed +programs, even if mypy reports type errors: $ python3 PROGRAM @@ -106,8 +100,8 @@ Yusuke Miyazaki). [statically typed parts]: https://mypy.readthedocs.io/en/latest/getting_started.html#function-signatures-and-dynamic-vs-static-typing -IDE, Linter Integrations, and Pre-commit ----------------------------------------- +Integrations +------------ Mypy can be integrated into popular IDEs: @@ -122,99 +116,34 @@ Mypy can be integrated into popular IDEs: * PyCharm: [mypy plugin](https://github.com/dropbox/mypy-PyCharm-plugin) (PyCharm integrates [its own implementation of PEP 484](https://www.jetbrains.com/help/pycharm/type-hinting-in-product.html)) * VS Code: provides [basic integration](https://code.visualstudio.com/docs/python/linting#_mypy) with mypy. - -Mypy can also be set up as a pre-commit hook using [pre-commit mirrors-mypy]. - -[pre-commit mirrors-mypy]: https://github.com/pre-commit/mirrors-mypy +* pre-commit: use [pre-commit mirrors-mypy](https://github.com/pre-commit/mirrors-mypy). Web site and documentation -------------------------- -Documentation and additional information is available at the web site: +Additional information is available at the web site: http://www.mypy-lang.org/ -Or you can jump straight to the documentation: +Jump straight to the documentation: https://mypy.readthedocs.io/ +Follow along our changelog at: -Troubleshooting ---------------- - -Depending on your configuration, you may have to run `pip` like -this: - - $ python3 -m pip install -U mypy - -This should automatically install the appropriate version of -mypy's parser, typed-ast. If for some reason it does not, you -can install it manually: - - $ python3 -m pip install -U typed-ast - -If the `mypy` command isn't found after installation: After -`python3 -m pip install`, the `mypy` script and -dependencies, including the `typing` module, will be installed to -system-dependent locations. Sometimes the script directory will not -be in `PATH`, and you have to add the target directory to `PATH` -manually or create a symbolic link to the script. In particular, on -macOS, the script may be installed under `/Library/Frameworks`: - - /Library/Frameworks/Python.framework/Versions//bin - -In Windows, the script is generally installed in -`\PythonNN\Scripts`. So, type check a program like this (replace -`\Python34` with your Python installation path): - - C:\>\Python34\python \Python34\Scripts\mypy PROGRAM - -### Working with `virtualenv` - -If you are using [`virtualenv`](https://virtualenv.pypa.io/en/stable/), -make sure you are running a python3 environment. Installing via `pip3` -in a v2 environment will not configure the environment to run installed -modules from the command line. - - $ python3 -m pip install -U virtualenv - $ python3 -m virtualenv env + https://mypy-lang.blogspot.com/ -Quick start for contributing to mypy ------------------------------------- - -If you want to contribute, first clone the mypy git repository: - - $ git clone https://github.com/python/mypy.git - -From the mypy directory, use pip to install mypy: - - $ cd mypy - $ python3 -m pip install -U . - -Replace `python3` with your Python 3 interpreter. You may have to do -the above as root. For example, in Ubuntu: - - $ sudo python3 -m pip install -U . - -Now you can use the `mypy` program just as above. In case of trouble -see "Troubleshooting" above. - -> NOTE: Installing with sudo can be a security risk. Please try with the `--user` flag first. - $ python3 -m pip install --user -U . - - -Tests ------ +Contributing +------------ -The basic way to run tests: +Help in testing, development, documentation and other tasks is +highly appreciated and useful to the project. There are tasks for +contributors of all experience levels. - $ pip3 install -r test-requirements.txt - $ python2 -m pip install -U typing - $ ./runtests.py +To get started with developing mypy, see [CONTRIBUTING.md](CONTRIBUTING.md). -For more on the tests, such as how to write tests and how to control -which tests to run, see [Test README.md](test-data/unit/README.md). +If you need help getting started, don't hesitate to ask on [gitter](https://gitter.im/python/typing). Development status @@ -224,58 +153,19 @@ Mypy is beta software, but it has already been used in production for several years at Dropbox and in many other organizations, and it has an extensive test suite. -See [the roadmap](ROADMAP.md) if you are interested in plans for the -future. - - -Changelog ---------- - -Follow mypy's updates on the blog: https://mypy-lang.blogspot.com/ - - -Issue tracker -------------- - -Please report any bugs and enhancement ideas using the mypy issue -tracker: https://github.com/python/mypy/issues - -If you have any questions about using mypy or types, please ask -in the typing gitter instead: https://gitter.im/python/typing - - -Compiled version of mypy ------------------------- +mypyc and compiled version of mypy +---------------------------------- -We have built a compiled version of mypy using the [mypyc -compiler](https://github.com/python/mypy/tree/master/mypyc) for -mypy-annotated Python code. It is approximately 4 times faster than -interpreted mypy and is available (and the default) for 64-bit -Windows, macOS, and Linux. +[Mypyc](https://github.com/mypyc/mypyc) uses Python type hints to compile Python +modules to faster C extensions. Mypy is itself compiled using mypyc: this makes +mypy approximately 4 times faster than if interpreted! To install an interpreted mypy instead, use: $ python3 -m pip install --no-binary mypy -U mypy -If you wish to test out the compiled version of a development -version of mypy, you can directly install a binary from +To use a compiled version of a development +version of mypy, directly install a binary from https://github.com/mypyc/mypy_mypyc-wheels/releases/latest. - -Help wanted ------------ - -Any help in testing, development, documentation and other tasks is -highly appreciated and useful to the project. There are tasks for -contributors of all experience levels. If you're just getting started, -ask on the [gitter chat](https://gitter.im/python/typing) for ideas of good -beginner issues. - -For more details, see the file [CONTRIBUTING.md](CONTRIBUTING.md). - - -License -------- - -Mypy is licensed under the terms of the MIT License (see the file -LICENSE). +To contribute to the mypyc project, check out https://github.com/mypyc/mypyc diff --git a/ROADMAP.md b/ROADMAP.md deleted file mode 100644 index b881799be8f1..000000000000 --- a/ROADMAP.md +++ /dev/null @@ -1,38 +0,0 @@ -# Mypy Roadmap - -The goal of the roadmap is to document areas the mypy core team is -planning to work on in the future or is currently working on. PRs -targeting these areas are very welcome, but please check first with a -core team member that nobody else is working on the same thing. - -**Note:** This doesn’t include everything that the core team will work -on, and everything is subject to change. - -- Continue making error messages more useful and informative. - ([issues](https://github.com/python/mypy/labels/topic-usability)) - -- Refactor and simplify specific tricky parts of mypy internals, such - as the [conditional type binder](https://github.com/python/mypy/issues/3457) - and the [semantic analyzer](https://github.com/python/mypy/issues/6204). - -- Use the redesigned semantic analyzer to support general recursive types - ([issue](https://github.com/python/mypy/issues/731)). - -- Infer signature of a single function using static analysis and integrate this - functionality in mypy daemon. - -- Support user defined variadic generics (focus on the use cases needed for precise - typing of decorators, see [issue](https://github.com/python/mypy/issues/3157)). - -- Dedicated support for NumPy and Python numeric stack (including - integer generics/shape types, and a NumPy plugin, see - [issue](https://github.com/python/mypy/issues/3540)). - -- Gradual improvements to [mypyc compiler](https://github.com/mypyc/mypyc). - -- Invest some effort into systematically filling in missing - stubs in typeshed, with focus on libraries heavily used at Dropbox. - Help with [typeshed transformation](https://github.com/python/typeshed/issues/2491) - if needed. - -- Support selected IDE features and deeper editor integrations. From e7d68cccdf13aef68c2c23eee3d4c2b0a7a33814 Mon Sep 17 00:00:00 2001 From: Shantanu <12621235+hauntsaninja@users.noreply.github.com> Date: Sat, 30 Oct 2021 21:33:29 -0700 Subject: [PATCH 2/2] Update CREDITS Co-authored-by: Xuanda Yang --- CREDITS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CREDITS b/CREDITS index 52564ba2ef41..d0e53de5ee01 100644 --- a/CREDITS +++ b/CREDITS @@ -19,7 +19,7 @@ Non-Dropbox core team members: Jelle Zijlstra Michael J. Sullivan Shantanu Jain - Xuanda Yuang + Xuanda Yang Past Dropbox core team members: