~dkuhlman/python-training-materials/Materials

<h1>26.1. <a class="reference internal" href="#module-typing" title="typing: Support for type hints (see PEP 484)."><code class="xref py py-mod docutils literal">typing</code></a> — Support for type hints<a class="headerlink" href="#module-typing" title="Permalink to this headline">¶</a></h1>

New in version 3.5.

</div>

Source code: <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/typing.py">Lib/typing.py</a>

100

101

This module supports type hints as specified by <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0484">PEP 484</a>. The most

102

fundamental support consists of the types <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a>, <a class="reference internal" href="#typing.Union" title="typing.Union"><code class="xref py py-data docutils literal">Union</code></a>,

103

<a class="reference internal" href="#typing.Tuple" title="typing.Tuple"><code class="xref py py-data docutils literal">Tuple</code></a>, <a class="reference internal" href="#typing.Callable" title="typing.Callable"><code class="xref py py-data docutils literal">Callable</code></a>, <a class="reference internal" href="#typing.TypeVar" title="typing.TypeVar"><code class="xref py py-class docutils literal">TypeVar</code></a>, and

104

<a class="reference internal" href="#typing.Generic" title="typing.Generic"><code class="xref py py-class docutils literal">Generic</code></a>. For full specification please see <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0484">PEP 484</a>. For

105

a simplified introduction to type hints see <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0483">PEP 483</a>.

106

The function below takes and returns a string and is annotated as follows:

107

<div class="highlight-python3"><div class="highlight"><pre>def greeting(name: str) -> str:

108

return 'Hello ' + name

109

</pre></div>

110

</div>

111

In the function <code class="docutils literal">greeting</code>, the argument <code class="docutils literal">name</code> is expected to be of type

112

<a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal">str</code></a> and the return type <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal">str</code></a>. Subtypes are accepted as

113

arguments.

114

115

<h2>26.1.1. Type aliases<a class="headerlink" href="#type-aliases" title="Permalink to this headline">¶</a></h2>

116

A type alias is defined by assigning the type to the alias. In this example,

117

<code class="docutils literal">Vector</code> and <code class="docutils literal">List[float]</code> will be treated as interchangeable synonyms:

118

<div class="highlight-python3"><div class="highlight"><pre>from typing import List

119

Vector = List[float]

120

121

def scale(scalar: float, vector: Vector) -> Vector:

122

return [scalar * num for num in vector]

123

124

# typechecks; a list of floats qualifies as a Vector.

125

new_vector = scale(2.0, [1.0, -4.2, 5.4])

126

</pre></div>

127

</div>

128

Type aliases are useful for simplifying complex type signatures. For example:

129

<div class="highlight-python3"><div class="highlight"><pre>from typing import Dict, Tuple, List

130

131

ConnectionOptions = Dict[str, str]

132

Address = Tuple[str, int]

133

Server = Tuple[Address, ConnectionOptions]

134

135

def broadcast_message(message: str, servers: List[Server]) -> None:

136

...

137

138

# The static type checker will treat the previous type signature as

139

# being exactly equivalent to this one.

140

def broadcast_message(

141

message: str,

142

servers: List[Tuple[Tuple[str, int], Dict[str, str]]]) -> None:

143

...

144

</pre></div>

145

</div>

146

Note that <code class="docutils literal">None</code> as a type hint is a special case and is replaced by

147

<code class="docutils literal">type(None)</code>.

148

</div>

149

150

<h2>26.1.2. NewType<a class="headerlink" href="#newtype" title="Permalink to this headline">¶</a></h2>

151

Use the <a class="reference internal" href="#typing.NewType" title="typing.NewType"><code class="xref py py-func docutils literal">NewType()</code></a> helper function to create distinct types:

152

<div class="highlight-python3"><div class="highlight"><pre>from typing import NewType

153

154

UserId = NewType('UserId', int)

155

some_id = UserId(524313)

156

</pre></div>

157

</div>

158

The static type checker will treat the new type as if it were a subclass

159

of the original type. This is useful in helping catch logical errors:

160

<div class="highlight-python3"><div class="highlight"><pre>def get_user_name(user_id: UserId) -> str:

161

...

162

163

# typechecks

164

user_a = get_user_name(UserId(42351))

165

166

# does not typecheck; an int is not a UserId

167

user_b = get_user_name(-1)

168

</pre></div>

169

</div>

170

You may still perform all <code class="docutils literal">int</code> operations on a variable of type <code class="docutils literal">UserId</code>,

171

but the result will always be of type <code class="docutils literal">int</code>. This lets you pass in a

172

<code class="docutils literal">UserId</code> wherever an <code class="docutils literal">int</code> might be expected, but will prevent you from

173

accidentally creating a <code class="docutils literal">UserId</code> in an invalid way:

174

<div class="highlight-python3"><div class="highlight"><pre># 'output' is of type 'int', not 'UserId'

175

output = UserId(23413) + UserId(54341)

176

</pre></div>

177

</div>

178

Note that these checks are enforced only by the static type checker. At runtime

179

the statement <code class="docutils literal">Derived = NewType('Derived', Base)</code> will make <code class="docutils literal">Derived</code> a

180

function that immediately returns whatever parameter you pass it. That means

181

the expression <code class="docutils literal">Derived(some_value)</code> does not create a new class or introduce

182

any overhead beyond that of a regular function call.

183

More precisely, the expression <code class="docutils literal">some_value is Derived(some_value)</code> is always

184

true at runtime.

185

This also means that it is not possible to create a subtype of <code class="docutils literal">Derived</code>

186

since it is an identity function at runtime, not an actual type. Similarly, it

187

is not possible to create another <a class="reference internal" href="#typing.NewType" title="typing.NewType"><code class="xref py py-func docutils literal">NewType()</code></a> based on a <code class="docutils literal">Derived</code> type:

188

<div class="highlight-python3"><div class="highlight"><pre>from typing import NewType

189

190

191

192

# Fails at runtime and does not typecheck

193

class AdminUserId(UserId): pass

194

195

# Also does not typecheck

196

ProUserId = NewType('ProUserId', UserId)

197

</pre></div>

198

</div>

199

See <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0484">PEP 484</a> for more details.

200

201

Note

202

Recall that the use of a type alias declares two types to be equivalent to

203

one another. Doing <code class="docutils literal">Alias = Original</code> will make the static type checker

204

treat <code class="docutils literal">Alias</code> as being exactly equivalent to <code class="docutils literal">Original</code> in all cases.

205

This is useful when you want to simplify complex type signatures.

206

In contrast, <code class="docutils literal">NewType</code> declares one type to be a subtype of another.

207

Doing <code class="docutils literal">Derived = NewType('Derived', Original)</code> will make the static type

208

checker treat <code class="docutils literal">Derived</code> as a subclass of <code class="docutils literal">Original</code>, which means a

209

value of type <code class="docutils literal">Original</code> cannot be used in places where a value of type

210

<code class="docutils literal">Derived</code> is expected. This is useful when you want to prevent logic

211

errors with minimal runtime cost.

212

</div>

213

</div>

214

215

<h2>26.1.3. Callable<a class="headerlink" href="#callable" title="Permalink to this headline">¶</a></h2>

216

Frameworks expecting callback functions of specific signatures might be

217

type hinted using <code class="docutils literal">Callable[[Arg1Type, Arg2Type], ReturnType]</code>.

218

For example:

219

<div class="highlight-python3"><div class="highlight"><pre>from typing import Callable

220

221

def feeder(get_next_item: Callable[[], str]) -> None:

222

# Body

223

224

def async_query(on_success: Callable[[int], None],

225

on_error: Callable[[int, Exception], None]) -> None:

226

# Body

227

</pre></div>

228

</div>

229

It is possible to declare the return type of a callable without specifying

230

the call signature by substituting a literal ellipsis

231

for the list of arguments in the type hint: <code class="docutils literal">Callable[..., ReturnType]</code>.

232

</div>

233

234

<h2>26.1.4. Generics<a class="headerlink" href="#generics" title="Permalink to this headline">¶</a></h2>

235

Since type information about objects kept in containers cannot be statically

236

inferred in a generic way, abstract base classes have been extended to support

237

subscription to denote expected types for container elements.

238

<div class="highlight-python3"><div class="highlight"><pre>from typing import Mapping, Sequence

239

240

def notify_by_email(employees: Sequence[Employee],

241

overrides: Mapping[str, str]) -> None: ...

242

</pre></div>

243

</div>

244

Generics can be parametrized by using a new factory available in typing

245

called <a class="reference internal" href="#typing.TypeVar" title="typing.TypeVar"><code class="xref py py-class docutils literal">TypeVar</code></a>.

246

<div class="highlight-python3"><div class="highlight"><pre>from typing import Sequence, TypeVar

247

248

T = TypeVar('T') # Declare type variable

249

250

def first(l: Sequence[T]) -> T: # Generic function

251

return l[0]

252

</pre></div>

253

</div>

254

</div>

255

256

<h2>26.1.5. User-defined generic types<a class="headerlink" href="#user-defined-generic-types" title="Permalink to this headline">¶</a></h2>

257

A user-defined class can be defined as a generic class.

258

259

from logging import Logger

260

261

T = TypeVar('T')

262

263

class LoggedVar(Generic[T]):

264

def __init__(self, value: T, name: str, logger: Logger) -> None:

265

self.name = name

266

self.logger = logger

267

self.value = value

268

269

def set(self, new: T) -> None:

270

self.log('Set ' + repr(self.value))

271

self.value = new

272

273

def get(self) -> T:

274

self.log('Get ' + repr(self.value))

275

return self.value

276

277

def log(self, message: str) -> None:

278

self.logger.info('%s: %s', self.name, message)

279

</pre></div>

280

</div>

281

<code class="docutils literal">Generic[T]</code> as a base class defines that the class <code class="docutils literal">LoggedVar</code> takes a

282

single type parameter <code class="docutils literal">T</code> . This also makes <code class="docutils literal">T</code> valid as a type within the

283

class body.

284

The <a class="reference internal" href="#typing.Generic" title="typing.Generic"><code class="xref py py-class docutils literal">Generic</code></a> base class uses a metaclass that defines

285

<a class="reference internal" href="../reference/datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal">__getitem__()</code></a> so that <code class="docutils literal">LoggedVar[t]</code> is valid as a type:

286

<div class="highlight-python3"><div class="highlight"><pre>from typing import Iterable

287

288

def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:

289

for var in vars:

290

var.set(0)

291

</pre></div>

292

</div>

293

A generic type can have any number of type variables, and type variables may

294

be constrained:

295

296

...

297

298

T = TypeVar('T')

299

S = TypeVar('S', int, str)

300

301

class StrangePair(Generic[T, S]):

302

...

303

</pre></div>

304

</div>

305

Each type variable argument to <a class="reference internal" href="#typing.Generic" title="typing.Generic"><code class="xref py py-class docutils literal">Generic</code></a> must be distinct.

306

This is thus invalid:

307

308

...

309

310

T = TypeVar('T')

311

312

class Pair(Generic[T, T]): # INVALID

313

...

314

</pre></div>

315

</div>

316

You can use multiple inheritance with <a class="reference internal" href="#typing.Generic" title="typing.Generic"><code class="xref py py-class docutils literal">Generic</code></a>:

317

<div class="highlight-python3"><div class="highlight"><pre>from typing import TypeVar, Generic, Sized

318

319

T = TypeVar('T')

320

321

class LinkedList(Sized, Generic[T]):

322

...

323

</pre></div>

324

</div>

325

When inheriting from generic classes, some type variables could be fixed:

326

327

328

T = TypeVar('T')

329

330

class MyDict(Mapping[str, T]):

331

...

332

</pre></div>

333

</div>

334

In this case <code class="docutils literal">MyDict</code> has a single parameter, <code class="docutils literal">T</code>.

335

Using a generic class without specifying type parameters assumes

336

<a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a> for each position. In the following example, <code class="docutils literal">MyIterable</code> is

337

not generic but implicitly inherits from <code class="docutils literal">Iterable[Any]</code>:

338

<div class="highlight-python3"><div class="highlight"><pre>from typing import Iterable

339

340

class MyIterable(Iterable): # Same as Iterable[Any]

341

</pre></div>

342

</div>

343

User defined generic type aliases are also supported. Examples:

344

<div class="highlight-python3"><div class="highlight"><pre>from typing import TypeVar, Iterable, Tuple, Union

345

S = TypeVar('S')

346

Response = Union[Iterable[S], int]

347

348

# Return type here is same as Union[Iterable[str], int]

349

def response(query: str) -> Response[str]:

350

...

351

352

T = TypeVar('T', int, float, complex)

353

Vec = Iterable[Tuple[T, T]]

354

355

def inproduct(v: Vec[T]) -> T: # Same as Iterable[Tuple[T, T]]

356

return sum(x*y for x, y in v)

357

</pre></div>

358

</div>

359

The metaclass used by <a class="reference internal" href="#typing.Generic" title="typing.Generic"><code class="xref py py-class docutils literal">Generic</code></a> is a subclass of <a class="reference internal" href="abc.html#abc.ABCMeta" title="abc.ABCMeta"><code class="xref py py-class docutils literal">abc.ABCMeta</code></a>.

360

A generic class can be an ABC by including abstract methods or properties,

361

and generic classes can also have ABCs as base classes without a metaclass

362

conflict. Generic metaclasses are not supported. The outcome of parameterizing

363

generics is cached, and most types in the typing module are hashable and

364

comparable for equality.

365

</div>

366

367

368

A special kind of type is <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a>. A static type checker will treat

369

every type as being compatible with <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a> and <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a> as being

370

compatible with every type.

371

This means that it is possible to perform any operation or method call on a

372

value of type on <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a> and assign it to any variable:

373

<div class="highlight-python3"><div class="highlight"><pre>from typing import Any

374

375

a = None # type: Any

376

a = [] # OK

377

a = 2 # OK

378

379

s = '' # type: str

380

s = a # OK

381

382

def foo(item: Any) -> int:

383

# Typechecks; 'item' could be any type,

384

# and that type might have a 'bar' method

385

item.bar()

386

...

387

</pre></div>

388

</div>

389

Notice that no typechecking is performed when assigning a value of type

390

<a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a> to a more precise type. For example, the static type checker did

391

not report an error when assigning <code class="docutils literal">a</code> to <code class="docutils literal">s</code> even though <code class="docutils literal">s</code> was

392

declared to be of type <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal">str</code></a> and receives an <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal">int</code></a> value at

393

runtime!

394

Furthermore, all functions without a return type or parameter types will

395

implicitly default to using <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a>:

396

<div class="highlight-python3"><div class="highlight"><pre>def legacy_parser(text):

397

...

398

return data

399

400

# A static type checker will treat the above

401

# as having the same signature as:

402

def legacy_parser(text: Any) -> Any:

403

...

404

return data

405

</pre></div>

406

</div>

407

This behavior allows <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a> to be used as an escape hatch when you

408

need to mix dynamically and statically typed code.

409

Contrast the behavior of <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a> with the behavior of <a class="reference internal" href="functions.html#object" title="object"><code class="xref py py-class docutils literal">object</code></a>.

410

Similar to <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a>, every type is a subtype of <a class="reference internal" href="functions.html#object" title="object"><code class="xref py py-class docutils literal">object</code></a>. However,

411

unlike <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a>, the reverse is not true: <a class="reference internal" href="functions.html#object" title="object"><code class="xref py py-class docutils literal">object</code></a> is not a

412

subtype of every other type.

413

That means when the type of a value is <a class="reference internal" href="functions.html#object" title="object"><code class="xref py py-class docutils literal">object</code></a>, a type checker will

414

reject almost all operations on it, and assigning it to a variable (or using

415

it as a return value) of a more specialized type is a type error. For example:

416

<div class="highlight-python3"><div class="highlight"><pre>def hash_a(item: object) -> int:

417

# Fails; an object does not have a 'magic' method.

418

item.magic()

419

...

420

421

def hash_b(item: Any) -> int:

422

# Typechecks

423

item.magic()

424

...

425

426

# Typechecks, since ints and strs are subclasses of object

427

hash_a(42)

428

hash_a("foo")

429

430

# Typechecks, since Any is compatible with all types

431

hash_b(42)

432

hash_b("foo")

433

</pre></div>

434

</div>

435

Use <a class="reference internal" href="functions.html#object" title="object"><code class="xref py py-class docutils literal">object</code></a> to indicate that a value could be any type in a typesafe

436

manner. Use <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a> to indicate that a value is dynamically typed.

437

</div>

438

439

<h2>26.1.7. Classes, functions, and decorators<a class="headerlink" href="#classes-functions-and-decorators" title="Permalink to this headline">¶</a></h2>

440

The module defines the following classes, functions and decorators:

441

442

443

class <code class="descclassname">typing.</code><code class="descname">TypeVar</code><a class="headerlink" href="#typing.TypeVar" title="Permalink to this definition">¶</a></dt>

444

<dd>Type variable.

445

Usage:

446

<div class="highlight-python3"><div class="highlight"><pre>T = TypeVar('T') # Can be anything

447

A = TypeVar('A', str, bytes) # Must be str or bytes

448

</pre></div>

449

</div>

450

Type variables exist primarily for the benefit of static type

451

checkers. They serve as the parameters for generic types as well

452

as for generic function definitions. See class Generic for more

453

information on generic types. Generic functions work as follows:

454

<div class="highlight-python3"><div class="highlight"><pre>def repeat(x: T, n: int) -> Sequence[T]:

455

"""Return a list containing n references to x."""

456

return [x]*n

457

458

def longest(x: A, y: A) -> A:

459

"""Return the longest of two strings."""

460

return x if len(x) >= len(y) else y

461

</pre></div>

462

</div>

463

The latter example’s signature is essentially the overloading

464

of <code class="docutils literal">(str, str) -> str</code> and <code class="docutils literal">(bytes, bytes) -> bytes</code>. Also note

465

that if the arguments are instances of some subclass of <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal">str</code></a>,

466

the return type is still plain <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal">str</code></a>.

467

At runtime, <code class="docutils literal">isinstance(x, T)</code> will raise <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a>. In general,

468

<a class="reference internal" href="functions.html#isinstance" title="isinstance"><code class="xref py py-func docutils literal">isinstance()</code></a> and <a class="reference internal" href="functions.html#issubclass" title="issubclass"><code class="xref py py-func docutils literal">issubclass()</code></a> should not be used with types.

469

Type variables may be marked covariant or contravariant by passing

470

<code class="docutils literal">covariant=True</code> or <code class="docutils literal">contravariant=True</code>. See <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0484">PEP 484</a> for more

471

details. By default type variables are invariant. Alternatively,

472

a type variable may specify an upper bound using <code class="docutils literal">bound=<type></code>.

473

This means that an actual type substituted (explicitly or implicitly)

474

for the type variable must be a subclass of the boundary type,

475

see <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0484">PEP 484</a>.

476

</dd></dl>

477

478

479

480

class <code class="descclassname">typing.</code><code class="descname">Generic</code><a class="headerlink" href="#typing.Generic" title="Permalink to this definition">¶</a></dt>

481

<dd>Abstract base class for generic types.

482

A generic type is typically declared by inheriting from an

483

instantiation of this class with one or more type variables.

484

For example, a generic mapping type might be defined as:

485

<div class="highlight-python3"><div class="highlight"><pre>class Mapping(Generic[KT, VT]):

486

def __getitem__(self, key: KT) -> VT:

487

...

488

# Etc.

489

</pre></div>

490

</div>

491

This class can then be used as follows:

492

<div class="highlight-python3"><div class="highlight"><pre>X = TypeVar('X')

493

Y = TypeVar('Y')

494

495

def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y:

496

try:

497

return mapping[key]

498

except KeyError:

499

return default

500

</pre></div>

501

</div>

502

</dd></dl>

503

504

505

506

class <code class="descclassname">typing.</code><code class="descname">Type</code>(Generic[CT_co])<a class="headerlink" href="#typing.Type" title="Permalink to this definition">¶</a></dt>

507

<dd>A variable annotated with <code class="docutils literal">C</code> may accept a value of type <code class="docutils literal">C</code>. In

508

contrast, a variable annotated with <code class="docutils literal">Type[C]</code> may accept values that are

509

classes themselves – specifically, it will accept the class object of

510

<code class="docutils literal">C</code>. For example:

511

<div class="highlight-python3"><div class="highlight"><pre>a = 3 # Has type 'int'

512

b = int # Has type 'Type[int]'

513

c = type(a) # Also has type 'Type[int]'

514

</pre></div>

515

</div>

516

Note that <code class="docutils literal">Type[C]</code> is covariant:

517

<div class="highlight-python3"><div class="highlight"><pre>class User: ...

518

class BasicUser(User): ...

519

class ProUser(User): ...

520

class TeamUser(User): ...

521

522

# Accepts User, BasicUser, ProUser, TeamUser, ...

523

def make_new_user(user_class: Type[User]) -> User:

524

# ...

525

return user_class()

526

</pre></div>

527

</div>

528

The fact that <code class="docutils literal">Type[C]</code> is covariant implies that all subclasses of

529

<code class="docutils literal">C</code> should implement the same constructor signature and class method

530

signatures as <code class="docutils literal">C</code>. The type checker should flag violations of this,

531

but should also allow constructor calls in subclasses that match the

532

constructor calls in the indicated base class. How the type checker is

533

required to handle this particular case may change in future revisions of

534

<a class="pep reference external" href="https://www.python.org/dev/peps/pep-0484">PEP 484</a>.

535

The only legal parameters for <a class="reference internal" href="#typing.Type" title="typing.Type"><code class="xref py py-class docutils literal">Type</code></a> are classes, unions of classes, and

536

<a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a>. For example:

537

<div class="highlight-python3"><div class="highlight"><pre>def new_non_team_user(user_class: Type[Union[BaseUser, ProUser]]): ...

538

</pre></div>

539

</div>

540

<code class="docutils literal">Type[Any]</code> is equivalent to <code class="docutils literal">Type</code> which in turn is equivalent

541

to <code class="docutils literal">type</code>, which is the root of Python’s metaclass hierarchy.

542

</dd></dl>

543

544

545

546

class <code class="descclassname">typing.</code><code class="descname">Iterable</code>(Generic[T_co])<a class="headerlink" href="#typing.Iterable" title="Permalink to this definition">¶</a></dt>

547

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.Iterable" title="collections.abc.Iterable"><code class="xref py py-class docutils literal">collections.abc.Iterable</code></a>.

548

</dd></dl>

549

550

551

552

class <code class="descclassname">typing.</code><code class="descname">Iterator</code>(Iterable[T_co])<a class="headerlink" href="#typing.Iterator" title="Permalink to this definition">¶</a></dt>

553

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.Iterator" title="collections.abc.Iterator"><code class="xref py py-class docutils literal">collections.abc.Iterator</code></a>.

554

</dd></dl>

555

556

557

558

class <code class="descclassname">typing.</code><code class="descname">Reversible</code>(Iterable[T_co])<a class="headerlink" href="#typing.Reversible" title="Permalink to this definition">¶</a></dt>

559

<dd>A generic version of <code class="xref py py-class docutils literal">collections.abc.Reversible</code>.

560

</dd></dl>

561

562

563

564

class <code class="descclassname">typing.</code><code class="descname">SupportsInt</code><a class="headerlink" href="#typing.SupportsInt" title="Permalink to this definition">¶</a></dt>

565

<dd>An ABC with one abstract method <code class="docutils literal">__int__</code>.

566

</dd></dl>

567

568

569

570

class <code class="descclassname">typing.</code><code class="descname">SupportsFloat</code><a class="headerlink" href="#typing.SupportsFloat" title="Permalink to this definition">¶</a></dt>

571

<dd>An ABC with one abstract method <code class="docutils literal">__float__</code>.

572

</dd></dl>

573

574

575

576

class <code class="descclassname">typing.</code><code class="descname">SupportsAbs</code><a class="headerlink" href="#typing.SupportsAbs" title="Permalink to this definition">¶</a></dt>

577

<dd>An ABC with one abstract method <code class="docutils literal">__abs__</code> that is covariant

578

in its return type.

579

</dd></dl>

580

581

582

583

class <code class="descclassname">typing.</code><code class="descname">SupportsRound</code><a class="headerlink" href="#typing.SupportsRound" title="Permalink to this definition">¶</a></dt>

584

<dd>An ABC with one abstract method <code class="docutils literal">__round__</code>

585

that is covariant in its return type.

586

</dd></dl>

587

588

589

590

class <code class="descclassname">typing.</code><code class="descname">Container</code>(Generic[T_co])<a class="headerlink" href="#typing.Container" title="Permalink to this definition">¶</a></dt>

591

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.Container" title="collections.abc.Container"><code class="xref py py-class docutils literal">collections.abc.Container</code></a>.

592

</dd></dl>

593

594

595

596

class <code class="descclassname">typing.</code><code class="descname">Hashable</code><a class="headerlink" href="#typing.Hashable" title="Permalink to this definition">¶</a></dt>

597

<dd>An alias to <a class="reference internal" href="collections.abc.html#collections.abc.Hashable" title="collections.abc.Hashable"><code class="xref py py-class docutils literal">collections.abc.Hashable</code></a>

598

</dd></dl>

599

600

601

602

class <code class="descclassname">typing.</code><code class="descname">Sized</code><a class="headerlink" href="#typing.Sized" title="Permalink to this definition">¶</a></dt>

603

<dd>An alias to <a class="reference internal" href="collections.abc.html#collections.abc.Sized" title="collections.abc.Sized"><code class="xref py py-class docutils literal">collections.abc.Sized</code></a>

604

</dd></dl>

605

606

607

608

class <code class="descclassname">typing.</code><code class="descname">AbstractSet</code>(Sized, Iterable[T_co], Container[T_co])<a class="headerlink" href="#typing.AbstractSet" title="Permalink to this definition">¶</a></dt>

609

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.Set" title="collections.abc.Set"><code class="xref py py-class docutils literal">collections.abc.Set</code></a>.

610

</dd></dl>

611

612

613

614

class <code class="descclassname">typing.</code><code class="descname">MutableSet</code>(AbstractSet[T])<a class="headerlink" href="#typing.MutableSet" title="Permalink to this definition">¶</a></dt>

615

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.MutableSet" title="collections.abc.MutableSet"><code class="xref py py-class docutils literal">collections.abc.MutableSet</code></a>.

616

</dd></dl>

617

618

619

620

class <code class="descclassname">typing.</code><code class="descname">Mapping</code>(Sized, Iterable[KT], Container[KT], Generic[VT_co])<a class="headerlink" href="#typing.Mapping" title="Permalink to this definition">¶</a></dt>

621

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.Mapping" title="collections.abc.Mapping"><code class="xref py py-class docutils literal">collections.abc.Mapping</code></a>.

622

</dd></dl>

623

624

625

626

class <code class="descclassname">typing.</code><code class="descname">MutableMapping</code>(Mapping[KT, VT])<a class="headerlink" href="#typing.MutableMapping" title="Permalink to this definition">¶</a></dt>

627

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.MutableMapping" title="collections.abc.MutableMapping"><code class="xref py py-class docutils literal">collections.abc.MutableMapping</code></a>.

628

</dd></dl>

629

630

631

632

class <code class="descclassname">typing.</code><code class="descname">Sequence</code>(Sized, Iterable[T_co], Container[T_co])<a class="headerlink" href="#typing.Sequence" title="Permalink to this definition">¶</a></dt>

633

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.Sequence" title="collections.abc.Sequence"><code class="xref py py-class docutils literal">collections.abc.Sequence</code></a>.

634

</dd></dl>

635

636

637

638

class <code class="descclassname">typing.</code><code class="descname">MutableSequence</code>(Sequence[T])<a class="headerlink" href="#typing.MutableSequence" title="Permalink to this definition">¶</a></dt>

639

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.MutableSequence" title="collections.abc.MutableSequence"><code class="xref py py-class docutils literal">collections.abc.MutableSequence</code></a>.

640

</dd></dl>

641

642

643

644

class <code class="descclassname">typing.</code><code class="descname">ByteString</code>(Sequence[int])<a class="headerlink" href="#typing.ByteString" title="Permalink to this definition">¶</a></dt>

645

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.ByteString" title="collections.abc.ByteString"><code class="xref py py-class docutils literal">collections.abc.ByteString</code></a>.

646

This type represents the types <a class="reference internal" href="functions.html#bytes" title="bytes"><code class="xref py py-class docutils literal">bytes</code></a>, <a class="reference internal" href="functions.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal">bytearray</code></a>,

647

and <a class="reference internal" href="stdtypes.html#memoryview" title="memoryview"><code class="xref py py-class docutils literal">memoryview</code></a>.

648

As a shorthand for this type, <a class="reference internal" href="functions.html#bytes" title="bytes"><code class="xref py py-class docutils literal">bytes</code></a> can be used to

649

annotate arguments of any of the types mentioned above.

650

</dd></dl>

651

652

653

654

class <code class="descclassname">typing.</code><code class="descname">List</code>(list, MutableSequence[T])<a class="headerlink" href="#typing.List" title="Permalink to this definition">¶</a></dt>

655

<dd>Generic version of <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal">list</code></a>.

656

Useful for annotating return types. To annotate arguments it is preferred

657

to use abstract collection types such as <a class="reference internal" href="#typing.Mapping" title="typing.Mapping"><code class="xref py py-class docutils literal">Mapping</code></a>, <a class="reference internal" href="#typing.Sequence" title="typing.Sequence"><code class="xref py py-class docutils literal">Sequence</code></a>,

658

or <a class="reference internal" href="#typing.AbstractSet" title="typing.AbstractSet"><code class="xref py py-class docutils literal">AbstractSet</code></a>.

659

This type may be used as follows:

660

661

662

def vec2(x: T, y: T) -> List[T]:

663

return [x, y]

664

665

def keep_positives(vector: Sequence[T]) -> List[T]:

666

return [item for item in vector if item > 0]

667

</pre></div>

668

</div>

669

</dd></dl>

670

671

672

673

class <code class="descclassname">typing.</code><code class="descname">Set</code>(set, MutableSet[T])<a class="headerlink" href="#typing.Set" title="Permalink to this definition">¶</a></dt>

674

<dd>A generic version of <a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-class docutils literal">builtins.set</code></a>.

675

</dd></dl>

676

677

678

679

class <code class="descclassname">typing.</code><code class="descname">FrozenSet</code>(frozenset, AbstractSet[T_co])<a class="headerlink" href="#typing.FrozenSet" title="Permalink to this definition">¶</a></dt>

680

<dd>A generic version of <a class="reference internal" href="stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal">builtins.frozenset</code></a>.

681

</dd></dl>

682

683

684

685

class <code class="descclassname">typing.</code><code class="descname">MappingView</code>(Sized, Iterable[T_co])<a class="headerlink" href="#typing.MappingView" title="Permalink to this definition">¶</a></dt>

686

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.MappingView" title="collections.abc.MappingView"><code class="xref py py-class docutils literal">collections.abc.MappingView</code></a>.

687

</dd></dl>

688

689

690

691

class <code class="descclassname">typing.</code><code class="descname">KeysView</code>(MappingView[KT_co], AbstractSet[KT_co])<a class="headerlink" href="#typing.KeysView" title="Permalink to this definition">¶</a></dt>

692

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.KeysView" title="collections.abc.KeysView"><code class="xref py py-class docutils literal">collections.abc.KeysView</code></a>.

693

</dd></dl>

694

695

696

697

class <code class="descclassname">typing.</code><code class="descname">ItemsView</code>(MappingView, Generic[KT_co, VT_co])<a class="headerlink" href="#typing.ItemsView" title="Permalink to this definition">¶</a></dt>

698

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.ItemsView" title="collections.abc.ItemsView"><code class="xref py py-class docutils literal">collections.abc.ItemsView</code></a>.

699

</dd></dl>

700

701

702

703

class <code class="descclassname">typing.</code><code class="descname">ValuesView</code>(MappingView[VT_co])<a class="headerlink" href="#typing.ValuesView" title="Permalink to this definition">¶</a></dt>

704

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.ValuesView" title="collections.abc.ValuesView"><code class="xref py py-class docutils literal">collections.abc.ValuesView</code></a>.

705

</dd></dl>

706

707

708

709

class <code class="descclassname">typing.</code><code class="descname">Awaitable</code>(Generic[T_co])<a class="headerlink" href="#typing.Awaitable" title="Permalink to this definition">¶</a></dt>

710

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.Awaitable" title="collections.abc.Awaitable"><code class="xref py py-class docutils literal">collections.abc.Awaitable</code></a>.

711

</dd></dl>

712

713

714

715

class <code class="descclassname">typing.</code><code class="descname">Coroutine</code>(Awaitable[V_co], Generic[T_co T_contra, V_co])<a class="headerlink" href="#typing.Coroutine" title="Permalink to this definition">¶</a></dt>

716

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.Coroutine" title="collections.abc.Coroutine"><code class="xref py py-class docutils literal">collections.abc.Coroutine</code></a>.

717

The variance and order of type variables

718

correspond to those of <a class="reference internal" href="#typing.Generator" title="typing.Generator"><code class="xref py py-class docutils literal">Generator</code></a>, for example:

719

720

c = None # type: Coroutine[List[str], str, int]

721

...

722

x = c.send('hi') # type: List[str]

723

async def bar() -> None:

724

x = await c # type: int

725

</pre></div>

726

</div>

727

</dd></dl>

728

729

730

731

class <code class="descclassname">typing.</code><code class="descname">AsyncIterable</code>(Generic[T_co])<a class="headerlink" href="#typing.AsyncIterable" title="Permalink to this definition">¶</a></dt>

732

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.AsyncIterable" title="collections.abc.AsyncIterable"><code class="xref py py-class docutils literal">collections.abc.AsyncIterable</code></a>.

733

</dd></dl>

734

735

736

737

class <code class="descclassname">typing.</code><code class="descname">AsyncIterator</code>(AsyncIterable[T_co])<a class="headerlink" href="#typing.AsyncIterator" title="Permalink to this definition">¶</a></dt>

738

<dd>A generic version of <a class="reference internal" href="collections.abc.html#collections.abc.AsyncIterator" title="collections.abc.AsyncIterator"><code class="xref py py-class docutils literal">collections.abc.AsyncIterator</code></a>.

739

</dd></dl>

740

741

742

743

class <code class="descclassname">typing.</code><code class="descname">Dict</code>(dict, MutableMapping[KT, VT])<a class="headerlink" href="#typing.Dict" title="Permalink to this definition">¶</a></dt>

744

<dd>A generic version of <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal">dict</code></a>.

745

The usage of this type is as follows:

746

<div class="highlight-python3"><div class="highlight"><pre>def get_position_in_index(word_list: Dict[str, int], word: str) -> int:

747

return word_list[word]

748

</pre></div>

749

</div>

750

</dd></dl>

751

752

753

754

class <code class="descclassname">typing.</code><code class="descname">DefaultDict</code>(collections.defaultdict, MutableMapping[KT, VT])<a class="headerlink" href="#typing.DefaultDict" title="Permalink to this definition">¶</a></dt>

755

<dd>A generic version of <a class="reference internal" href="collections.html#collections.defaultdict" title="collections.defaultdict"><code class="xref py py-class docutils literal">collections.defaultdict</code></a>

756

</dd></dl>

757

758

759

760

class <code class="descclassname">typing.</code><code class="descname">Generator</code>(Iterator[T_co], Generic[T_co, T_contra, V_co])<a class="headerlink" href="#typing.Generator" title="Permalink to this definition">¶</a></dt>

761

<dd>A generator can be annotated by the generic type

762

<code class="docutils literal">Generator[YieldType, SendType, ReturnType]</code>. For example:

763

<div class="highlight-python3"><div class="highlight"><pre>def echo_round() -> Generator[int, float, str]:

764

sent = yield 0

765

while sent >= 0:

766

sent = yield round(sent)

767

return 'Done'

768

</pre></div>

769

</div>

770

Note that unlike many other generics in the typing module, the <code class="docutils literal">SendType</code>

771

of <a class="reference internal" href="#typing.Generator" title="typing.Generator"><code class="xref py py-class docutils literal">Generator</code></a> behaves contravariantly, not covariantly or

772

invariantly.

773

If your generator will only yield values, set the <code class="docutils literal">SendType</code> and

774

<code class="docutils literal">ReturnType</code> to <code class="docutils literal">None</code>:

775

<div class="highlight-python3"><div class="highlight"><pre>def infinite_stream(start: int) -> Generator[int, None, None]:

776

while True:

777

yield start

778

start += 1

779

</pre></div>

780

</div>

781

Alternatively, annotate your generator as having a return type of

782

either <code class="docutils literal">Iterable[YieldType]</code> or <code class="docutils literal">Iterator[YieldType]</code>:

783

<div class="highlight-python3"><div class="highlight"><pre>def infinite_stream(start: int) -> Iterator[int]:

784

while True:

785

yield start

786

start += 1

787

</pre></div>

788

</div>

789

</dd></dl>

790

791

792

793

class <code class="descclassname">typing.</code><code class="descname">Text</code><a class="headerlink" href="#typing.Text" title="Permalink to this definition">¶</a></dt>

794

<dd><code class="docutils literal">Text</code> is an alias for <code class="docutils literal">str</code>. It is provided to supply a forward

795

compatible path for Python 2 code: in Python 2, <code class="docutils literal">Text</code> is an alias for

796

<code class="docutils literal">unicode</code>.

797

Use <code class="docutils literal">Text</code> to indicate that a value must contain a unicode string in

798

a manner that is compatible with both Python 2 and Python 3:

799

<div class="highlight-python3"><div class="highlight"><pre>def add_unicode_checkmark(text: Text) -> Text:

800

return text + u' \u2713'

801

</pre></div>

802

</div>

803

</dd></dl>

804

805

806

807

class <code class="descclassname">typing.</code><code class="descname">io</code><a class="headerlink" href="#typing.io" title="Permalink to this definition">¶</a></dt>

808

<dd>Wrapper namespace for I/O stream types.

809

This defines the generic type <code class="docutils literal">IO[AnyStr]</code> and aliases <code class="docutils literal">TextIO</code>

810

and <code class="docutils literal">BinaryIO</code> for respectively <code class="docutils literal">IO[str]</code> and <code class="docutils literal">IO[bytes]</code>.

811

These representing the types of I/O streams such as returned by

812

<a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal">open()</code></a>.

813

</dd></dl>

814

815

816

817

class <code class="descclassname">typing.</code><code class="descname">re</code><a class="headerlink" href="#typing.re" title="Permalink to this definition">¶</a></dt>

818

<dd>Wrapper namespace for regular expression matching types.

819

This defines the type aliases <code class="docutils literal">Pattern</code> and <code class="docutils literal">Match</code> which

820

correspond to the return types from <a class="reference internal" href="re.html#re.compile" title="re.compile"><code class="xref py py-func docutils literal">re.compile()</code></a> and

821

<a class="reference internal" href="re.html#re.match" title="re.match"><code class="xref py py-func docutils literal">re.match()</code></a>. These types (and the corresponding functions)

822

are generic in <code class="docutils literal">AnyStr</code> and can be made specific by writing

823

<code class="docutils literal">Pattern[str]</code>, <code class="docutils literal">Pattern[bytes]</code>, <code class="docutils literal">Match[str]</code>, or

824

<code class="docutils literal">Match[bytes]</code>.

825

</dd></dl>

826

827

828

829

<code class="descclassname">typing.</code><code class="descname">NamedTuple</code>(typename, fields)<a class="headerlink" href="#typing.NamedTuple" title="Permalink to this definition">¶</a></dt>

830

<dd>Typed version of namedtuple.

831

Usage:

832

<div class="highlight-python3"><div class="highlight"><pre>Employee = typing.NamedTuple('Employee', [('name', str), ('id', int)])

833

</pre></div>

834

</div>

835

This is equivalent to:

836

<div class="highlight-python3"><div class="highlight"><pre>Employee = collections.namedtuple('Employee', ['name', 'id'])

837

</pre></div>

838

</div>

839

The resulting class has one extra attribute: _field_types,

840

giving a dict mapping field names to types. (The field names

841

are in the _fields attribute, which is part of the namedtuple

842

API.)

843

</dd></dl>

844

845

846

847

<code class="descclassname">typing.</code><code class="descname">NewType</code>(typ)<a class="headerlink" href="#typing.NewType" title="Permalink to this definition">¶</a></dt>

848

<dd>A helper function to indicate a distinct types to a typechecker,

849

see <a class="reference internal" href="#distinct">NewType</a>. At runtime it returns a function that returns

850

its argument. Usage:

851

<div class="highlight-python3"><div class="highlight"><pre>UserId = NewType('UserId', int)

852

first_user = UserId(1)

853

</pre></div>

854

</div>

855

</dd></dl>

856

857

858

859

<code class="descclassname">typing.</code><code class="descname">cast</code>(typ, val)<a class="headerlink" href="#typing.cast" title="Permalink to this definition">¶</a></dt>

860

<dd>Cast a value to a type.

861

This returns the value unchanged. To the type checker this

862

signals that the return value has the designated type, but at

863

runtime we intentionally don’t check anything (we want this

864

to be as fast as possible).

865

</dd></dl>

866

867

868

869

<code class="descclassname">typing.</code><code class="descname">get_type_hints</code>(obj[, globals[, locals]])<a class="headerlink" href="#typing.get_type_hints" title="Permalink to this definition">¶</a></dt>

870

<dd>Return a dictionary containing type hints for a function, method, module

871

or class object.

872

This is often the same as <code class="docutils literal">obj.__annotations__</code>. In addition,

873

forward references encoded as string literals are handled by evaluating

874

them in <code class="docutils literal">globals</code> and <code class="docutils literal">locals</code> namespaces. If necessary,

875

<code class="docutils literal">Optional[t]</code> is added for function and method annotations if a default

876

value equal to <code class="docutils literal">None</code> is set. For a class <code class="docutils literal">C</code>, return

877

a dictionary constructed by merging all the <code class="docutils literal">__annotations__</code> along

878

<code class="docutils literal">C.__mro__</code> in reverse order.

879

</dd></dl>

880

881

882

883

<code class="descclassname">@</code><code class="descclassname">typing.</code><code class="descname">overload</code><a class="headerlink" href="#typing.overload" title="Permalink to this definition">¶</a></dt>

884

<dd>The <code class="docutils literal">@overload</code> decorator allows describing functions and methods

885

that support multiple different combinations of argument types. A series

886

of <code class="docutils literal">@overload</code>-decorated definitions must be followed by exactly one

887

non-<code class="docutils literal">@overload</code>-decorated definition (for the same function/method).

888

The <code class="docutils literal">@overload</code>-decorated definitions are for the benefit of the

889

type checker only, since they will be overwritten by the

890

non-<code class="docutils literal">@overload</code>-decorated definition, while the latter is used at

891

runtime but should be ignored by a type checker. At runtime, calling

892

a <code class="docutils literal">@overload</code>-decorated function directly will raise

893

<code class="docutils literal">NotImplementedError</code>. An example of overload that gives a more

894

precise type than can be expressed using a union or a type variable:

895

<div class="highlight-python3"><div class="highlight"><pre>@overload

896

def process(response: None) -> None:

897

...

898

@overload

899

def process(response: int) -> Tuple[int, str]:

900

...

901

@overload

902

def process(response: bytes) -> str:

903

...

904

def process(response):

905

906

</pre></div>

907

</div>

908

See <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0484">PEP 484</a> for details and comparison with other typing semantics.

909

</dd></dl>

910

911

912

913

<code class="descclassname">@</code><code class="descclassname">typing.</code><code class="descname">no_type_check</code>(arg)<a class="headerlink" href="#typing.no_type_check" title="Permalink to this definition">¶</a></dt>

914

<dd>Decorator to indicate that annotations are not type hints.

915

The argument must be a class or function; if it is a class, it

916

applies recursively to all methods defined in that class (but not

917

to methods defined in its superclasses or subclasses).

918

This mutates the function(s) in place.

919

</dd></dl>

920

921

922

923

<code class="descclassname">@</code><code class="descclassname">typing.</code><code class="descname">no_type_check_decorator</code>(decorator)<a class="headerlink" href="#typing.no_type_check_decorator" title="Permalink to this definition">¶</a></dt>

924

<dd>Decorator to give another decorator the <a class="reference internal" href="#typing.no_type_check" title="typing.no_type_check"><code class="xref py py-func docutils literal">no_type_check()</code></a> effect.

925

This wraps the decorator with something that wraps the decorated

926

function in <a class="reference internal" href="#typing.no_type_check" title="typing.no_type_check"><code class="xref py py-func docutils literal">no_type_check()</code></a>.

927

</dd></dl>

928

929

930

931

<code class="descclassname">typing.</code><code class="descname">Any</code><a class="headerlink" href="#typing.Any" title="Permalink to this definition">¶</a></dt>

932

<dd>Special type indicating an unconstrained type.

933

934

<li>Every type is compatible with <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a>.</li>

935

<li><a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal">Any</code></a> is compatible with every type.</li>

936

</ul>

937

</dd></dl>

938

939

940

941

<code class="descclassname">typing.</code><code class="descname">Union</code><a class="headerlink" href="#typing.Union" title="Permalink to this definition">¶</a></dt>

942

<dd>Union type; <code class="docutils literal">Union[X, Y]</code> means either X or Y.

943

To define a union, use e.g. <code class="docutils literal">Union[int, str]</code>. Details:

944

<ul>

945

<li>The arguments must be types and there must be at least one.

946

</li>

947

<li>Unions of unions are flattened, e.g.:

948

<div class="highlight-python3"><div class="highlight"><pre>Union[Union[int, str], float] == Union[int, str, float]

949

</pre></div>

950

</div>

951

</li>

952

<li>Unions of a single argument vanish, e.g.:

953

954

</pre></div>

955

</div>

956

</li>

957

<li>Redundant arguments are skipped, e.g.:

958

<div class="highlight-python3"><div class="highlight"><pre>Union[int, str, int] == Union[int, str]

959

</pre></div>

960

</div>

961

</li>

962

<li>When comparing unions, the argument order is ignored, e.g.:

963

<div class="highlight-python3"><div class="highlight"><pre>Union[int, str] == Union[str, int]

964

</pre></div>

965

</div>

966

</li>

967

<li>When a class and its subclass are present, the former is skipped, e.g.:

968

969

</pre></div>

970

</div>

971

</li>

972

<li>You cannot subclass or instantiate a union.

973

</li>

974

<li>You cannot write <code class="docutils literal">Union[X][Y]</code>.

975

</li>

976

<li>You can use <code class="docutils literal">Optional[X]</code> as a shorthand for <code class="docutils literal">Union[X, None]</code>.

977

</li>

978

</ul>

979

</dd></dl>

980

981

982

983

<code class="descclassname">typing.</code><code class="descname">Optional</code><a class="headerlink" href="#typing.Optional" title="Permalink to this definition">¶</a></dt>

984

<dd>Optional type.

985

<code class="docutils literal">Optional[X]</code> is equivalent to <code class="docutils literal">Union[X, None]</code>.

986

Note that this is not the same concept as an optional argument,

987

which is one that has a default. An optional argument with a

988

default needn’t use the <code class="docutils literal">Optional</code> qualifier on its type

989

annotation (although it is inferred if the default is <code class="docutils literal">None</code>).

990

A mandatory argument may still have an <code class="docutils literal">Optional</code> type if an

991

explicit value of <code class="docutils literal">None</code> is allowed.

992

</dd></dl>

993

994

995

996

<code class="descclassname">typing.</code><code class="descname">Tuple</code><a class="headerlink" href="#typing.Tuple" title="Permalink to this definition">¶</a></dt>

997

<dd>Tuple type; <code class="docutils literal">Tuple[X, Y]</code> is the type of a tuple of two items

998

with the first item of type X and the second of type Y.

999

Example: <code class="docutils literal">Tuple[T1, T2]</code> is a tuple of two elements corresponding

1000

to type variables T1 and T2. <code class="docutils literal">Tuple[int, float, str]</code> is a tuple

1001

of an int, a float and a string.

1002

To specify a variable-length tuple of homogeneous type,

1003

use literal ellipsis, e.g. <code class="docutils literal">Tuple[int, ...]</code>. A plain <a class="reference internal" href="#typing.Tuple" title="typing.Tuple"><code class="xref py py-data docutils literal">Tuple</code></a>

1004

is equivalent to <code class="docutils literal">Tuple[Any, ...]</code>, and in turn to <a class="reference internal" href="stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal">tuple</code></a>.

1005

</dd></dl>

1006

1007

1008

1009

<code class="descclassname">typing.</code><code class="descname">Callable</code><a class="headerlink" href="#typing.Callable" title="Permalink to this definition">¶</a></dt>

1010

<dd>Callable type; <code class="docutils literal">Callable[[int], str]</code> is a function of (int) -> str.

1011

The subscription syntax must always be used with exactly two

1012

values: the argument list and the return type. The argument list

1013

must be a list of types or an ellipsis; the return type must be

1014

a single type.

1015

There is no syntax to indicate optional or keyword arguments;

1016

such function types are rarely used as callback types.

1017

<code class="docutils literal">Callable[..., ReturnType]</code> (literal ellipsis) can be used to

1018

type hint a callable taking any number of arguments and returning

1019

<code class="docutils literal">ReturnType</code>. A plain <a class="reference internal" href="#typing.Callable" title="typing.Callable"><code class="xref py py-data docutils literal">Callable</code></a> is equivalent to

1020

<code class="docutils literal">Callable[..., Any]</code>, and in turn to

1021

<a class="reference internal" href="collections.abc.html#collections.abc.Callable" title="collections.abc.Callable"><code class="xref py py-class docutils literal">collections.abc.Callable</code></a>.

1022

</dd></dl>

1023

1024

1025

1026

<code class="descclassname">typing.</code><code class="descname">ClassVar</code><a class="headerlink" href="#typing.ClassVar" title="Permalink to this definition">¶</a></dt>

1027

<dd>Special type construct to mark class variables.

1028

As introduced in <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0526">PEP 526</a>, a variable annotation wrapped in ClassVar

1029

indicates that a given attribute is intended to be used as a class variable

1030

and should not be set on instances of that class. Usage:

1031

<div class="highlight-python3"><div class="highlight"><pre>class Starship:

1032

stats = {} # type: ClassVar[Dict[str, int]] # class variable

1033

damage = 10 # type: int # instance variable

1034

</pre></div>

1035

</div>

1036

<a class="reference internal" href="#typing.ClassVar" title="typing.ClassVar"><code class="xref py py-data docutils literal">ClassVar</code></a> accepts only types and cannot be further subscribed.

1037

1038

be used with <a class="reference internal" href="functions.html#isinstance" title="isinstance"><code class="xref py py-func docutils literal">isinstance()</code></a> or <a class="reference internal" href="functions.html#issubclass" title="issubclass"><code class="xref py py-func docutils literal">issubclass()</code></a>.

1039

Note that <a class="reference internal" href="#typing.ClassVar" title="typing.ClassVar"><code class="xref py py-data docutils literal">ClassVar</code></a> does not change Python runtime behavior;

1040

it can be used by 3rd party type checkers, so that the following

1041

code might flagged as an error by those:

1042

<div class="highlight-python3"><div class="highlight"><pre>enterprise_d = Starship(3000)

1043

enterprise_d.stats = {} # Error, setting class variable on instance

1044

Starship.stats = {} # This is OK

1045

</pre></div>

1046

</div>

1047

1048

New in version 3.5.3.

1049

</div>

1050

</dd></dl>

1051

1052

1053

1054

<code class="descclassname">typing.</code><code class="descname">AnyStr</code><a class="headerlink" href="#typing.AnyStr" title="Permalink to this definition">¶</a></dt>

1055

<dd><code class="docutils literal">AnyStr</code> is a type variable defined as

1056

<code class="docutils literal">AnyStr = TypeVar('AnyStr', str, bytes)</code>.

1057

It is meant to be used for functions that may accept any kind of string

1058

without allowing different kinds of strings to mix. For example:

1059

<div class="highlight-python3"><div class="highlight"><pre>def concat(a: AnyStr, b: AnyStr) -> AnyStr:

1060

return a + b

1061

1062

concat(u"foo", u"bar") # Ok, output has type 'unicode'

1063

concat(b"foo", b"bar") # Ok, output has type 'bytes'

1064

concat(u"foo", b"bar") # Error, cannot mix unicode and bytes

1065

</pre></div>

1066

</div>

1067

</dd></dl>

1068

1069

1070

1071

<code class="descclassname">typing.</code><code class="descname">TYPE_CHECKING</code><a class="headerlink" href="#typing.TYPE_CHECKING" title="Permalink to this definition">¶</a></dt>

1072

<dd>A special constant that is assumed to be <code class="docutils literal">True</code> by 3rd party static

1073

type checkers. It is <code class="docutils literal">False</code> at runtime. Usage:

1074

<div class="highlight-python3"><div class="highlight"><pre>if TYPE_CHECKING:

1075

import expensive_mod

1076

1077

def fun():

1078

local_var: expensive_mod.some_type = other_fun()

1079

</pre></div>

1080

</div>

1081

</dd></dl>

1082

1083

</div>

1084

</div>

1085

1086

1087

</div>

1088

</div>

1089

</div>

1090

1091

1092

<h3><a href="../contents.html">Table Of Contents</a></h3>

1093

<ul>

1094

<li><a class="reference internal" href="#">26.1. <code class="docutils literal">typing</code> — Support for type hints</a><ul>

1095

<li><a class="reference internal" href="#type-aliases">26.1.1. Type aliases</a></li>

1096

<li><a class="reference internal" href="#newtype">26.1.2. NewType</a></li>

1097

<li><a class="reference internal" href="#callable">26.1.3. Callable</a></li>

1098

<li><a class="reference internal" href="#generics">26.1.4. Generics</a></li>

1099

<li><a class="reference internal" href="#user-defined-generic-types">26.1.5. User-defined generic types</a></li>

1100

1101

<li><a class="reference internal" href="#classes-functions-and-decorators">26.1.7. Classes, functions, and decorators</a></li>

1102

</ul>

1103

</li>

1104

</ul>

1105

1106

<h4>Previous topic</h4>

1107

<a href="development.html"

1108

title="previous chapter">26. Development Tools</a>

1109

<h4>Next topic</h4>

1110

<a href="pydoc.html"

1111

title="next chapter">26.2. <code class="docutils literal">pydoc</code> — Documentation generator and online help system</a>

1112

1113

1114

1115

<li><a href="../bugs.html">Report a Bug</a></li>

1116

<li><a href="../_sources/library/typing.txt"

1117

rel="nofollow">Show Source</a></li>

1118

</ul>

1119

</div>

1120

</div>

1121

</div>

1122

1123

</div>

1124

1125

<h3>Navigation</h3>

1126

<ul>

1127

1128

<a href="../genindex.html" title="General Index"

1129

>index</a></li>

1130

1131

<a href="../py-modindex.html" title="Python Module Index"

1132

>modules</a> |</li>

1133

1134

<a href="pydoc.html" title="26.2. pydoc — Documentation generator and online help system"

1135

>next</a> |</li>

1136

1137

<a href="development.html" title="26. Development Tools"

1138

>previous</a> |</li>

1139

<li><img src="../_static/py.png" alt=""

1140

style="vertical-align: middle; margin-top: -1px"/></li>

1141

<li><a href="https://www.python.org/">Python</a> »</li>

1142

<li>

1143

3.5.2

1144

<a href="../index.html">Documentation </a> »

1145

</li>

1146

1147

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>

1148

<li class="nav-item nav-item-2"><a href="development.html" >26. Development Tools</a> »</li>

1149

1150

1151

1152

1153

1154

1155

1156

1157

1158

</form>

1159

</div>

1160

1161

1162

</li>

1163

1164

</ul>

1165

</div>

1166

1167

1168

1169

The Python Software Foundation is a non-profit corporation.

1170

<a href="https://www.python.org/psf/donations/">Please donate.</a>

1171

1172

Last updated on Nov 25, 2016.

1173

<a href="../bugs.html">Found a bug</a>?

1174

1175

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

1176

</div>

1177

1178

</body>

1179

</html>

b'\\ No newline at end of file'

Older »