From 6b6e0b4d76958fa4af9cb974b7f9d4bb8784298c Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Sat, 28 Oct 2017 00:57:44 +0200 Subject: [PATCH 1/2] Merge style guide from README.md into CONTRIBUTING.md --- CONTRIBUTING.md | 42 ++++++++++++++++++++++++++++++++++++++++-- README.md | 48 +++--------------------------------------------- 2 files changed, 43 insertions(+), 47 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4511c4d9f7e3..8cf5f1514d7f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -140,6 +140,29 @@ that you know. ### Stub file coding style +#### Syntax example + +The below is an excerpt from the types for the `datetime` module. + +```python +MAXYEAR = ... # type: int +MINYEAR = ... # type: int + +class date(object): + def __init__(self, year: int, month: int, day: int) -> None: ... + @classmethod + def fromtimestamp(cls, timestamp: float) -> date: ... + @classmethod + def today(cls) -> date: ... + @classmethod + def fromordinal(cls, ordinal: int) -> date: ... + def replace(self, year: int = ..., month: int = ..., day: int = ...) -> date: ... + def ctime(self) -> str: ... + def weekday(self) -> int: ... +``` + +#### Conventions + Stub files are *like* Python files and you should generally expect them to look the same. Your tools should be able to successfully treat them as regular Python files. However, there are a few important differences @@ -156,8 +179,23 @@ rule is that they should be as concise as possible. Specifically: names, or methods and fields within a single class; * use a single blank line between top-level class definitions, or none if the classes are very small; -* do not use docstrings; -* for arguments with a type and a default, use spaces around the `=`. +* do not use docstrings. + +Stub files should only contain information necessary for the type +checker, and leave out unnecessary detail: +* for arguments with a default, use `...` instead of the actual + default; +* for arguments with a type and a default, use spaces around the `=`; +* for arguments that default to `None`, use `Optional[]` explicitly + (see below for details); +* use `float` instead of `Union[int, float]`. + +Some further tips for good type hints: +* avoid invariant collection types (`List`, `Dict`) in argument + positions, in favor of covariant types like `Mapping` or `Sequence`; +* avoid Union return types: https://github.com/python/mypy/issues/1693; +* in Python 2, whenever possible, use `unicode` if that's the only + possible type, and `Text` if it can be either `unicode` or `bytes`. Imports in stubs are considered private (not part of the exported API) unless: diff --git a/README.md b/README.md index 6558b0426f1e..e43c1524a98a 100644 --- a/README.md +++ b/README.md @@ -49,51 +49,9 @@ 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. - -## Syntax example - -The below is an excerpt from the types for the `datetime` module. - -```python -from typing import Union - -MAXYEAR = ... # type: int -MINYEAR = ... # type: int - -class date(object): - def __init__(self, year: int, month: int, day: int) -> None: ... - @classmethod - def fromtimestamp(cls, timestamp: float) -> date: ... - @classmethod - def today(cls) -> date: ... - @classmethod - def fromordinal(cls, ordinal: int) -> date: ... - def replace(self, year: int = ..., month: int = ..., day: int = ...) -> date: ... - def ctime(self) -> str: ... - def weekday(self) -> int: ... -``` - -## Conventions - -* At the time of this writing, `unicode` arguments, in Python 2 stubs, are - interpreted by type-checkers as `Union[bytes, unicode]` (so it means the same - as `Text`). - Even so, in Python 2, whenever possible, use `unicode` if that's the only - possible type, and `Text` if it can be either `unicode` or `bytes`. -* For arguments with default values, use `...` instead of the actual - default value. -* Most type-checkers interpret optional parameters of the form `x : Foo = None` - as `x : Optional[Foo] = ...`. (So the former is a shortcut for the latter) - In typeshed, however, we prefer the explicit latter form. -* When something is declared as taking only float, it also takes `int`. See - https://www.python.org/dev/peps/pep-0484/#the-numeric-tower. So write `float` - instead of `Union[int, float]`. -* Avoid Union return types: https://github.com/python/mypy/issues/1693 -* Avoid invariant collection types (List, Dict) in argument positions, in favor - of covariant types like Mapping or Sequence. - +See [PEP 484](http://www.python.org/dev/peps/pep-0484/) for the exact +syntax of the stub files and [CONTRIBUTING.md](CONTRIBUTING.md) for the +coding style used in typeshed. ## Directory structure From 9a8a373a46b635216c0202db1df0c0fe7d7388f1 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Sun, 29 Oct 2017 21:29:05 +0100 Subject: [PATCH 2/2] Group coding style items together --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8cf5f1514d7f..c23ee2deb198 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -179,13 +179,13 @@ rule is that they should be as concise as possible. Specifically: names, or methods and fields within a single class; * use a single blank line between top-level class definitions, or none if the classes are very small; -* do not use docstrings. +* do not use docstrings; +* for arguments with a type and a default, use spaces around the `=`. Stub files should only contain information necessary for the type checker, and leave out unnecessary detail: * for arguments with a default, use `...` instead of the actual default; -* for arguments with a type and a default, use spaces around the `=`; * for arguments that default to `None`, use `Optional[]` explicitly (see below for details); * use `float` instead of `Union[int, float]`.