Skip to content

Commit 8ef9a43

Browse files
committed
chore: markdown references for type hinting
Signed-off-by: exploreriii <[email protected]>
1 parent f3716ee commit 8ef9a43

File tree

1 file changed

+32
-10
lines changed

1 file changed

+32
-10
lines changed

README_types.md

Lines changed: 32 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
## Introduction
2+
This is a markdown file, click Ctrl+Shift+V to view or click open preview.
23

34
This guide provides an overview of Python’s built-in types, explains how and why to use type hints, and demonstrates how to leverage the `typing` module and MyPy for static type checking. Whether you’re new to type annotations or looking to adopt a more robust workflow, you’ll find examples and best practices for writing clearer, safer, and more maintainable Python code.
45

@@ -52,10 +53,12 @@ Python code can be written using various built-in types that define their behavi
5253

5354
### Example
5455

56+
```python
5557
x: int = 3
5658
y: float = 1.0
5759
frozen: bool = True
5860
name: str = "Rupert"
61+
```
5962

6063
## What are Type Hints?
6164

@@ -72,16 +75,19 @@ Type hints let you declare the expected types of variables, function parameters,
7275

7376
### Examples
7477

75-
#### Correct
78+
#### Example 1: Correct
79+
```python
7680
name: str = ""
7781

7882
def greet(name: str) -> str:
7983
"""Return a personalized greeting."""
8084
return f"Hello, {name}!"
8185

8286
print(greet("Beatrice"))
87+
```
8388

84-
#### Incorrect
89+
#### Example 2: Incorrect
90+
```python
8591
name: str = ""
8692

8793
def greet(name: str) -> str:
@@ -97,6 +103,7 @@ def greet(name: str) -> str:
97103
return f"Hello, {name}!"
98104

99105
print(greet("Beatrice"))
106+
```
100107

101108
## Why Type Hint?
102109

@@ -113,8 +120,9 @@ Additionally, type hints unlock the use of static analysis tools (like MyPy), al
113120

114121
## Typing Using the `typing` Module
115122

116-
Most common types (e.g., `str`, `int`, `float`, `bool`, `bytes`, `list`, `dict`, `tuple`, `set`, `None`) are built-in in Python 3.10+. For more advanced or generic types, import from the `typing` module:
123+
Most common types (e.g., `str`, `int`, `float`, `bool`, `bytes`, `list`, `dict`, `tuple`, `set`, `None`) are built-in in Python 3.10. For more advanced or generic types, import from the `typing` module:
117124

125+
```python
118126
from typing import (
119127
Any, # “escape hatch” for unknown types
120128
Union, # still available, though often replaced by |
@@ -131,8 +139,10 @@ from typing import (
131139
ParamSpec, Concatenate, # for decorator/dependent signatures
132140
overload, cast, NoReturn, # various mypy helpers
133141
)
142+
```
134143

135144
### Example
145+
```python
136146
from typing import TypedDict, Literal
137147

138148
class User(TypedDict):
@@ -150,12 +160,14 @@ def find_user(uid: int) -> User | None:
150160
if uid == 1:
151161
return {"id": 1, "name": "Alice", "active": True}
152162
return None
163+
```
153164

154165
## Custom Types
155166

156167
You can use custom types whenever you’ve defined your own classes.
157168

158-
### Example
169+
### Example 1
170+
```python
159171
from dataclasses import dataclass
160172
from hiero_sdk import CryptoGetAccountBalanceQuery
161173

@@ -175,10 +187,12 @@ def query_hbar_balance(account: AccountId) -> None:
175187
if __name__ == "__main__":
176188
account = AccountId(0, 0, 200)
177189
query_hbar_balance(account)
190+
```
178191

179-
def_query_hbar_balance function takes account as an argument, which is of custom type AccountId, then the function returns type None. It returns None because there is no return statement in the function, and it instead prints.
192+
query_hbar_balance function takes account as an argument, which is of custom type AccountId, then the function returns type None. It returns None because there is no return statement in the function, and it instead prints.
180193

181194
### Example 2
195+
```python
182196
from dataclasses import dataclass
183197
from hiero_sdk import AccountId
184198
from hiero_sdk import CryptoGetAccountBalanceQuery
@@ -197,8 +211,9 @@ def build_balance_query(account: AccountId) -> CryptoGetAccountBalanceQuery:
197211

198212
if __name__ == "__main__":
199213
account = AccountId(0, 0, 200)
200-
query = build_balance_query(acct)
214+
query = build_balance_query(account)
201215
print(query)
216+
```
202217

203218
## Installing and Using MyPy
204219

@@ -210,22 +225,28 @@ This makes MyPy safe to introduce at your own pace.
210225

211226
### Install MyPy
212227

213-
bash:
228+
```bash
214229
pip install mypy
230+
```
215231

216232
Command to check type hinting with MyPy for program.py:
233+
```bash
217234
mypy path/to/program.py
235+
```
218236
E.g.
237+
```bash
219238
mypy src/hiero_sdk_python/tokens/token_info.py
239+
```
240+
241+
Read more:
220242

221-
Read about MyPy:
222243
Mypy [general](https://mypy.readthedocs.io/en/stable/).
223244

224-
Mypy cheatsheet [cheatsheet](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html#cheat-sheet-py3).
245+
Mypy [cheatsheet](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html#cheat-sheet-py3).
225246

226247
## Configuring MyPy
227248

228-
By default, MyPy is a very strict type checker. This project includes a `mypy.ini` at `/mypy.ini` to enable gradual, module-by-module checking. You can customize it to suit your needs:
249+
By default, MyPy is a fairly strict type checker. This project includes a `mypy.ini` at `/mypy.ini` to facilitate gradual, module-by-module checking. Customize mypy.ini it to suit your needs:
229250

230251
```ini
231252
# Do not error on imports that lack type stubs
@@ -236,6 +257,7 @@ implicit_optional = True
236257

237258
# Suppress errors when calling functions without type annotations
238259
allow_untyped_calls = True
260+
```
239261

240262
For a full list of flags and options, see the MyPy command-line reference:
241263
[MyPy command-line reference](https://mypy.readthedocs.io/en/stable/command_line.html#command-line)

0 commit comments

Comments
 (0)