Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 9656feb

Browse files
srittauJelleZijlstra
srittau
authored and
JelleZijlstra
committed
Merge style guide from README.md into CONTRIBUTING.md (#1696)
1 parent 0a9a2b6 commit 9656feb

2 files changed

Lines changed: 41 additions & 45 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,29 @@ that you know.
140140

141141
### Stub file coding style
142142

143+
#### Syntax example
144+
145+
The below is an excerpt from the types for the `datetime` module.
146+
147+
```python
148+
MAXYEAR = ... # type: int
149+
MINYEAR = ... # type: int
150+
151+
class date(object):
152+
def __init__(self, year: int, month: int, day: int) -> None: ...
153+
@classmethod
154+
def fromtimestamp(cls, timestamp: float) -> date: ...
155+
@classmethod
156+
def today(cls) -> date: ...
157+
@classmethod
158+
def fromordinal(cls, ordinal: int) -> date: ...
159+
def replace(self, year: int = ..., month: int = ..., day: int = ...) -> date: ...
160+
def ctime(self) -> str: ...
161+
def weekday(self) -> int: ...
162+
```
163+
164+
#### Conventions
165+
143166
Stub files are *like* Python files and you should generally expect them
144167
to look the same. Your tools should be able to successfully treat them
145168
as regular Python files. However, there are a few important differences
@@ -159,6 +182,21 @@ rule is that they should be as concise as possible. Specifically:
159182
* do not use docstrings;
160183
* for arguments with a type and a default, use spaces around the `=`.
161184

185+
Stub files should only contain information necessary for the type
186+
checker, and leave out unnecessary detail:
187+
* for arguments with a default, use `...` instead of the actual
188+
default;
189+
* for arguments that default to `None`, use `Optional[]` explicitly
190+
(see below for details);
191+
* use `float` instead of `Union[int, float]`.
192+
193+
Some further tips for good type hints:
194+
* avoid invariant collection types (`List`, `Dict`) in argument
195+
positions, in favor of covariant types like `Mapping` or `Sequence`;
196+
* avoid Union return types: https://github.com/python/mypy/issues/1693;
197+
* in Python 2, whenever possible, use `unicode` if that's the only
198+
possible type, and `Text` if it can be either `unicode` or `bytes`.
199+
162200
Imports in stubs are considered private (not part of the exported API)
163201
unless:
164202
* they use the form ``from library import name as name`` (sic, using

‎README.md‎

Lines changed: 3 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -49,51 +49,9 @@ file (i.e., it can be interpreted by Python 3), except all the methods are empty
4949
Python function annotations ([PEP 3107](https://www.python.org/dev/peps/pep-3107/))
5050
are used to describe the types the function has.
5151

52-
See [PEP 484](http://www.python.org/dev/peps/pep-0484/) for the exact syntax
53-
of the stub files.
54-
55-
## Syntax example
56-
57-
The below is an excerpt from the types for the `datetime` module.
58-
59-
```python
60-
from typing import Union
61-
62-
MAXYEAR = ... # type: int
63-
MINYEAR = ... # type: int
64-
65-
class date(object):
66-
def __init__(self, year: int, month: int, day: int) -> None: ...
67-
@classmethod
68-
def fromtimestamp(cls, timestamp: float) -> date: ...
69-
@classmethod
70-
def today(cls) -> date: ...
71-
@classmethod
72-
def fromordinal(cls, ordinal: int) -> date: ...
73-
def replace(self, year: int = ..., month: int = ..., day: int = ...) -> date: ...
74-
def ctime(self) -> str: ...
75-
def weekday(self) -> int: ...
76-
```
77-
78-
## Conventions
79-
80-
* At the time of this writing, `unicode` arguments, in Python 2 stubs, are
81-
interpreted by type-checkers as `Union[bytes, unicode]` (so it means the same
82-
as `Text`).
83-
Even so, in Python 2, whenever possible, use `unicode` if that's the only
84-
possible type, and `Text` if it can be either `unicode` or `bytes`.
85-
* For arguments with default values, use `...` instead of the actual
86-
default value.
87-
* Most type-checkers interpret optional parameters of the form `x : Foo = None`
88-
as `x : Optional[Foo] = ...`. (So the former is a shortcut for the latter)
89-
In typeshed, however, we prefer the explicit latter form.
90-
* When something is declared as taking only float, it also takes `int`. See
91-
https://www.python.org/dev/peps/pep-0484/#the-numeric-tower. So write `float`
92-
instead of `Union[int, float]`.
93-
* Avoid Union return types: https://github.com/python/mypy/issues/1693
94-
* Avoid invariant collection types (List, Dict) in argument positions, in favor
95-
of covariant types like Mapping or Sequence.
96-
52+
See [PEP 484](http://www.python.org/dev/peps/pep-0484/) for the exact
53+
syntax of the stub files and [CONTRIBUTING.md](CONTRIBUTING.md) for the
54+
coding style used in typeshed.
9755

9856
## Directory structure
9957

0 commit comments

Comments
 (0)