File size: 3,645 Bytes
14ee1a9
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
# Code Contribution

* We expect Type Hints in all methods.

You don't need to type hint every variable or function. Start with critical components, or where types might be confusing.
Type hints are not enforced at runtime. They're purely for the developer and tooling.
For large projects, consider gradual typing. You can add hints incrementally.
Type hints, when used judiciously, can make your Python code more readable and maintainable, and can catch potential bugs before runtime.

* We expect Docstrings in all methods and classes.

For modules, the docstring should list the classes, exceptions, and functions (and any other objects) that are exported by the module. For classes, document its methods and instance variables.

## Type Hints

Type hints, introduced in Python 3.5 via PEP 484, provide a way to specify the expected data types for variables, function arguments, and return values. This can greatly improve the readability of your code, facilitate debugging, and enable better tooling (like type checkers and IDE assistance). Here's a guide to get you started with type hints.

### Function and Method Signatures

Type hints can be added to function arguments and return values:
```python
def greet(name: str) -> None:
    print(f"Hello, {name}!")

def add(a: int, b: int) -> int:
    return a + b
```

### Type Hinting Lists, Dictionaries, and Other Collections

For collections, you can use the `typing` module:

```python
from typing import List, Dict

def get_names() -> List[str]:
    return ["Alice", "Bob", "Charlie"]

def get_age_mapping() -> Dict[str, int]:
    return {"Alice": 30, "Bob": 25, "Charlie": 28}
```

### Optional Types

If a variable might be of a certain type or None, use `Optional`:

```python
from typing import Optional

def find_user(username: str) -> Optional[Dict[str, str]]:
    # Return user dict if found, else None
    pass
```

### Union Types

If a variable can be one of several types, use `Union`:

```python
from typing import Union

def process_data(data: Union[str, bytes]) -> None:
    pass
```

### Classes and Type Hints

You can also use type hints in class definitions:

```python
class Person:
    def __init__(self, name: str, age: int) -> None:
        self.name: str = name
        self.age: int = age
```

## Docstrings

Docstrings, or documentation strings, are an essential aspect of Python programming. They provide concise descriptions of how a module, class, method, or function works. The PEP-8 style guide suggests a specific format for these descriptions. We'll walk through the process of adding PEP-8 style docstrings to your Python code. This style is commonly associated with Google's Python style guide.

### What is PEP-8

PEP-8 is the Python Enhancement Proposal that provides coding conventions for the Python code comprising the standard library in the main Python distribution. These conventions help in making the code readable and maintainable.

### Why Docstrings

Docstrings provide a built-in system for associating blocks of documentation with modules, classes, methods, and functions. This documentation can be accessed at runtime using the `help()` function or outside the runtime using tools like Sphinx.

### PEP-8 Docstring Format

Here's the basic structure:

```python
def function_name(arg1, arg2):
    """Brief description.

    More detailed description.

    Args:
        arg1 (type): Description of arg1.
        arg2 (type): Description of arg2.

    Returns:
        type: Description of the return value.

    Raises:
        ExceptionType: Description of the circumstances under which the exception is raised.
    """
    pass

```