diff --git a/README.md b/README.md index 25203a09c..f1eca90d6 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ Each Python module is represented by a `.pyi` "stub". This is a normal Python file (i.e., it can be interpreted by Python 3), except all the methods are empty. Python function annotations ([PEP 3107](https://www.python.org/dev/peps/pep-3107/)) are used to describe the types the function has. + See [PEP 484](http://www.python.org/dev/peps/pep-0484/) for the exact syntax of the stub files. @@ -20,7 +21,7 @@ of the stub files. The below is an excerpt from the types for the `datetime` module. -``` +```python MAXYEAR = ... # type: int MINYEAR = ... # type: int @@ -52,13 +53,13 @@ versions of Python, `third_party` has version subdirectories, just like `stdlib`. We're welcoming contributions (pull requests) for type definitions of -third party packages. +third-party packages. NOTE: When you're contributing a new stub for a package that you did not develop, please obtain consent of the package owner (this is specified in [PEP 484](https://www.python.org/dev/peps/pep-0484/#the-typeshed-repo)). -The best way to obtain consent is to file an issue in the third party +The best way to obtain consent is to file an issue in the third-party package's tracker and include the link to a positive response in your PR for typeshed. @@ -77,7 +78,7 @@ Note that the only supported version of Python 2 is 2.7. According to PEP 484, type checkers are expected to understand simple version and platform checks. So the following syntax is legal in a `pyi`: -``` +```python if sys.version_info >= (3,): # Python 3 specific definitions else: @@ -90,7 +91,7 @@ can make more sense to have seperate files in 2.x/ and 3.x/. ## Running the tests -The tests are automatically run by Travis-CI on every PR and push to +The tests are automatically run by Travis CI on every PR and push to the repo. There are two separate sets of tests: `tests/mypy_test.py` runs tests against [mypy](https://github.com/python/mypy/), while `tests/pytype_tests.py` runs tests against @@ -110,11 +111,11 @@ Python 2.7 and install pytype from its repo. For mypy, if you are in the typeshed repo that is submodule of the mypy repo (so `..` refers to the mypy repo), there's a shortcut to run the mypy tests that avoids installing mypy: -``` +```bash $ PYTHONPATH=.. python3 tests/mypy_tests.py ``` This runs five sets of tests: -``` +```bash running mypy --python-version 3.5 --strict-optional # with 342 files running mypy --python-version 3.4 --strict-optional # with 342 files running mypy --python-version 3.3 --strict-optional # with 327 files @@ -122,7 +123,7 @@ running mypy --python-version 3.2 --strict-optional # with 326 files running mypy --python-version 2.7 --strict-optional # with 380 files ``` You can limit it to a single test by passing `-p2` or `-p3.5` e.g. -``` +```bash $ PYTHONPATH=.. python3 tests/mypy_tests.py -p3.5 running mypy --python-version 3.5 --strict-optional # with 342 files ```