Coverage for hints/__init__.py: 0%

1"""

2 Annotation Type Hints

3=====================

4

5 Define the annotation type hints, the module exposes many aliases from

6:mod:`typing` and :mod:`numpy.typing` to avoid having to handle multiple

7 imports.

8"""

9

10 from __future__ import annotations

11

12 import re

13 import typing

14 from collections.abc import Generator, Iterable, Iterator, Mapping, Sequence

15 from os import PathLike

16 from types import ModuleType

17 from typing import ( # noqa: UP035

18 Annotated,

19 Any,

20 Callable,

21 ClassVar,

22 Dict,

23 List,

24 Literal,

25 NewType,

26 NoReturn,

27 Protocol,

28 Set,

29 SupportsIndex,

30 TextIO,

31 Tuple,

32 Type,

33 TypeAlias,

34 TypedDict,

35 TypeVar,

36 cast,

37 overload,

38 runtime_checkable,

39)

40

41 import numpy as np

42 from numpy.typing import ArrayLike, NDArray

43 from typing_extensions import Self

44

45 __author__ = "Colour Developers"

46 __copyright__ = "Copyright 2013 Colour Developers"

47 __license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause"

48 __maintainer__ = "Colour Developers"

49 __email__ = "colour-developers@colour-science.org"

50 __status__ = "Production"

51

52 __all__ = [

53 "Annotated",

54 "ArrayLike",

55 "NDArray",

56 "ModuleType",

57 "Any",

58 "Callable",

59 "ClassVar",

60 "Dict",

61 "Generator",

62 "Iterable",

63 "Iterator",

64 "List",

65 "Literal",

66 "Mapping",

67 "NoReturn",

68 "NewType",

69 "Protocol",

70 "Sequence",

71 "PathLike",

72 "Set",

73 "SupportsIndex",

74 "TextIO",

75 "Tuple",

76 "Type",

77 "TypeVar",

78 "TypedDict",

79 "cast",

80 "overload",

81 "runtime_checkable",

82 "Self",

83 "RegexFlag",

84 "DTypeInt",

85 "DTypeFloat",

86 "DTypeReal",

87 "DTypeComplex",

88 "DTypeBoolean",

89 "DType",

90 "Real",

91 "Dataclass",

92 "NDArrayInt",

93 "NDArrayFloat",

94 "NDArrayReal",

95 "NDArrayComplex",

96 "NDArrayBoolean",

97 "NDArrayStr",

98 "Domain1",

99 "Domain10",

100 "Domain100",

101 "Domain360",

102 "Domain100_100_360",

103 "Range1",

104 "Range10",

105 "Range100",

106 "Range360",

107 "Range100_100_360",

108 "ProtocolInterpolator",

109 "ProtocolExtrapolator",

110 "ProtocolLUTSequenceItem",

111 "LiteralWarning",

112 "LiteralChromaticAdaptationTransform",

113 "LiteralColourspaceModel",

114 "LiteralRGBColourspace",

115 "LiteralLogEncoding",

116 "LiteralLogDecoding",

117 "LiteralOETF",

118 "LiteralOETFInverse",

119 "LiteralEOTF",

120 "LiteralEOTFInverse",

121 "LiteralCCTFEncoding",

122 "LiteralCCTFDecoding",

123 "LiteralOOTF",

124 "LiteralOOTFInverse",

125 "LiteralLUTReadMethod",

126 "LiteralLUTWriteMethod",

127 "LiteralFontScaling",

128]

129

130 RegexFlag = NewType("RegexFlag", re.RegexFlag)

131

132 DTypeInt: TypeAlias = (

133 np.int8

134 | np.int16

135 | np.int32

136 | np.int64

137 | np.uint8

138 | np.uint16

139 | np.uint32

140 | np.uint64

141)

142 DTypeFloat: TypeAlias = np.float16 | np.float32 | np.float64

143 DTypeReal: TypeAlias = DTypeInt | DTypeFloat

144 DTypeComplex: TypeAlias = np.complex64 | np.complex128

145 DTypeBoolean: TypeAlias = np.bool_

146 DType: TypeAlias = DTypeBoolean | DTypeReal | DTypeComplex

147

148 Real: TypeAlias = int | float

149

150# TODO: Revisit to use Protocol.

151 Dataclass: TypeAlias = Any

152

153 NDArrayInt: TypeAlias = NDArray[DTypeInt]

154 NDArrayFloat: TypeAlias = NDArray[DTypeFloat]

155 NDArrayReal: TypeAlias = NDArray[DTypeInt | DTypeFloat]

156 NDArrayComplex: TypeAlias = NDArray[DTypeComplex]

157 NDArrayBoolean: TypeAlias = NDArray[DTypeBoolean]

158 NDArrayStr: TypeAlias = NDArray[np.str_]

159

160# Domain-Range Scale Type Aliases

161 Domain1: TypeAlias = Annotated[ArrayLike, 1]

162 Domain10: TypeAlias = Annotated[ArrayLike, 10]

163 Domain100: TypeAlias = Annotated[ArrayLike, 100]

164 Domain360: TypeAlias = Annotated[ArrayLike, 360]

165 Domain100_100_360: TypeAlias = Annotated[ArrayLike, (100, 100, 360)]

166

167 Range1: TypeAlias = Annotated[NDArrayFloat, 1]

168 Range10: TypeAlias = Annotated[NDArrayFloat, 10]

169 Range100: TypeAlias = Annotated[NDArrayFloat, 100]

170 Range360: TypeAlias = Annotated[NDArrayFloat, 360]

171 Range100_100_360: TypeAlias = Annotated[NDArrayFloat, (100, 100, 360)]

172

173

174 class ProtocolInterpolator(Protocol): # noqa: D101 # pragma: no cover

175 @property

176 def x(self) -> NDArray: # noqa: D102

177 ...

178

179 @x.setter

180 def x(self, value: ArrayLike, /) -> None: ...

181

182 @property

183 def y(self) -> NDArray: # noqa: D102

184 ...

185

186 @y.setter

187 def y(self, value: ArrayLike, /) -> None: ...

188

189 def __init__(self, *args: Any, **kwargs: Any) -> None: ... # pragma: no cover

190

191 def __call__(self, x: NDArrayFloat) -> NDArray: # noqa: D102

192 ... # pragma: no cover

193

194

195 class ProtocolExtrapolator(Protocol): # noqa: D101 # pragma: no cover

196 @property

197 def interpolator(self) -> ProtocolInterpolator: # noqa: D102

198 ...

199

200 @interpolator.setter

201 def interpolator(self, value: ProtocolInterpolator, /) -> None: ...

202

203 def __init__(self, *args: Any, **kwargs: Any) -> None: ... # pragma: no cover

204

205 def __call__(self, x: NDArrayFloat) -> NDArray: # noqa: D102

206 ... # pragma: no cover

207

208

209@runtime_checkable

210 class ProtocolLUTSequenceItem(Protocol): # noqa: D101 # pragma: no cover

211 def apply(self, RGB: ArrayLike, **kwargs: Any) -> NDArray: # noqa: D102

212 ... # pragma: no cover

213

214

215 LiteralWarning = Literal["default", "error", "ignore", "always", "module", "once"]

216

217# NOTE: The following literals are automatically generated by the *invoke*

218# *literalise* task. Please do not edit this section manually!

219

220# LITERALISE::BEGIN

221 LiteralChromaticAdaptationTransform = Literal[

222 "Bianco 2010",

223 "Bianco PC 2010",

224 "Bradford",

225 "CAT02",

226 "CAT02 Brill 2008",

227 "CAT16",

228 "CMCCAT2000",

229 "CMCCAT97",

230 "Fairchild",

231 "Sharp",

232 "Von Kries",

233 "XYZ Scaling",

234]

235

236 LiteralColourspaceModel = Literal[

237 "CAM02LCD",

238 "CAM02SCD",

239 "CAM02UCS",

240 "CAM16LCD",

241 "CAM16SCD",

242 "CAM16UCS",

243 "CIE 1931",

244 "CIE 1960 UCS",

245 "CIE 1976 UCS",

246 "CIE Lab",

247 "CIE Luv",

248 "CIE UCS",

249 "CIE UVW",

250 "CIE XYZ",

251 "CIE xyY",

252 "DIN99",

253 "HCL",

254 "HSL",

255 "HSV",

256 "Hunter Lab",

257 "Hunter Rdab",

258 "ICaCb",

259 "ICtCp",

260 "IHLS",

261 "IPT",

262 "IPT Ragoo 2021",

263 "IgPgTg",

264 "Jzazbz",

265 "OSA UCS",

266 "Oklab",

267 "RGB",

268 "YCbCr",

269 "YCoCg",

270 "Yrg",

271 "hdr-CIELAB",

272 "hdr-IPT",

273]

274

275 LiteralRGBColourspace = Literal[

276 "ACES2065-1",

277 "ACEScc",

278 "ACEScct",

279 "ACEScg",

280 "ACESproxy",

281 "ARRI Wide Gamut 3",

282 "ARRI Wide Gamut 4",

283 "Adobe RGB (1998)",

284 "Adobe Wide Gamut RGB",

285 "Apple RGB",

286 "Best RGB",

287 "Beta RGB",

288 "Blackmagic Wide Gamut",

289 "CIE RGB",

290 "Cinema Gamut",

291 "ColorMatch RGB",

292 "DCDM XYZ",

293 "DCI-P3",

294 "DCI-P3-P",

295 "DJI D-Gamut",

296 "DRAGONcolor",

297 "DRAGONcolor2",

298 "DaVinci Wide Gamut",

299 "Display P3",

300 "Don RGB 4",

301 "EBU Tech. 3213-E",

302 "ECI RGB v2",

303 "ERIMM RGB",

304 "Ekta Space PS 5",

305 "F-Gamut",

306 "FilmLight E-Gamut",

307 "ITU-R BT.2020",

308 "ITU-R BT.470 - 525",

309 "ITU-R BT.470 - 625",

310 "ITU-R BT.709",

311 "ITU-T H.273 - 22 Unspecified",

312 "ITU-T H.273 - Generic Film",

313 "Max RGB",

314 "N-Gamut",

315 "NTSC (1953)",

316 "NTSC (1987)",

317 "P3-D65",

318 "PLASA ANSI E1.54",

319 "Pal/Secam",

320 "ProPhoto RGB",

321 "Protune Native",

322 "REDWideGamutRGB",

323 "REDcolor",

324 "REDcolor2",

325 "REDcolor3",

326 "REDcolor4",

327 "RIMM RGB",

328 "ROMM RGB",

329 "Russell RGB",

330 "S-Gamut",

331 "S-Gamut3",

332 "S-Gamut3.Cine",

333 "SMPTE 240M",

334 "SMPTE C",

335 "Sharp RGB",

336 "V-Gamut",

337 "Venice S-Gamut3",

338 "Venice S-Gamut3.Cine",

339 "Xtreme RGB",

340 "aces",

341 "adobe1998",

342 "prophoto",

343 "sRGB",

344]

345

346 LiteralLogEncoding = Literal[

347 "ACEScc",

348 "ACEScct",

349 "ACESproxy",

350 "ARRI LogC3",

351 "ARRI LogC4",

352 "Apple Log Profile",

353 "Canon Log",

354 "Canon Log 2",

355 "Canon Log 3",

356 "Cineon",

357 "D-Log",

358 "ERIMM RGB",

359 "F-Log",

360 "F-Log2",

361 "Filmic Pro 6",

362 "L-Log",

363 "Log2",

364 "Log3G10",

365 "Log3G12",

366 "Mi-Log",

367 "N-Log",

368 "PLog",

369 "Panalog",

370 "Protune",

371 "REDLog",

372 "REDLogFilm",

373 "S-Log",

374 "S-Log2",

375 "S-Log3",

376 "T-Log",

377 "V-Log",

378 "ViperLog",

379]

380

381 LiteralLogDecoding = Literal[

382 "ACEScc",

383 "ACEScct",

384 "ACESproxy",

385 "ARRI LogC3",

386 "ARRI LogC4",

387 "Apple Log Profile",

388 "Canon Log",

389 "Canon Log 2",

390 "Canon Log 3",

391 "Cineon",

392 "D-Log",

393 "ERIMM RGB",

394 "F-Log",

395 "F-Log2",

396 "Filmic Pro 6",

397 "L-Log",

398 "Log2",

399 "Log3G10",

400 "Log3G12",

401 "Mi-Log",

402 "N-Log",

403 "PLog",

404 "Panalog",

405 "Protune",

406 "REDLog",

407 "REDLogFilm",

408 "S-Log",

409 "S-Log2",

410 "S-Log3",

411 "T-Log",

412 "V-Log",

413 "ViperLog",

414]

415

416 LiteralOETF = Literal[

417 "ARIB STD-B67",

418 "Blackmagic Film Generation 5",

419 "DaVinci Intermediate",

420 "ITU-R BT.2020",

421 "ITU-R BT.2100 HLG",

422 "ITU-R BT.2100 PQ",

423 "ITU-R BT.601",

424 "ITU-R BT.709",

425 "ITU-T H.273 IEC 61966-2",

426 "ITU-T H.273 Log",

427 "ITU-T H.273 Log Sqrt",

428 "SMPTE 240M",

429]

430

431 LiteralOETFInverse = Literal[

432 "ARIB STD-B67",

433 "Blackmagic Film Generation 5",

434 "DaVinci Intermediate",

435 "ITU-R BT.2020",

436 "ITU-R BT.2100 HLG",

437 "ITU-R BT.2100 PQ",

438 "ITU-R BT.601",

439 "ITU-R BT.709",

440 "ITU-T H.273 IEC 61966-2",

441 "ITU-T H.273 Log",

442 "ITU-T H.273 Log Sqrt",

443]

444

445 LiteralEOTF = Literal[

446 "DCDM",

447 "DICOM GSDF",

448 "ITU-R BT.1886",

449 "ITU-R BT.2100 HLG",

450 "ITU-R BT.2100 PQ",

451 "ITU-T H.273 ST.428-1",

452 "SMPTE 240M",

453 "ST 2084",

454 "sRGB",

455]

456

457 LiteralEOTFInverse = Literal[

458 "DCDM",

459 "DICOM GSDF",

460 "ITU-R BT.1886",

461 "ITU-R BT.2100 HLG",

462 "ITU-R BT.2100 PQ",

463 "ITU-T H.273 ST.428-1",

464 "ST 2084",

465 "sRGB",

466]

467

468 LiteralCCTFEncoding = Literal[

469 "ACEScc",

470 "ACEScct",

471 "ACESproxy",

472 "ARIB STD-B67",

473 "ARRI LogC3",

474 "ARRI LogC4",

475 "Apple Log Profile",

476 "Blackmagic Film Generation 5",

477 "Canon Log",

478 "Canon Log 2",

479 "Canon Log 3",

480 "Cineon",

481 "D-Log",

482 "DCDM",

483 "DICOM GSDF",

484 "DaVinci Intermediate",

485 "ERIMM RGB",

486 "F-Log",

487 "F-Log2",

488 "Filmic Pro 6",

489 "Gamma 2.2",

490 "Gamma 2.4",

491 "Gamma 2.6",

492 "ITU-R BT.1886",

493 "ITU-R BT.2020",

494 "ITU-R BT.2100 HLG",

495 "ITU-R BT.2100 PQ",

496 "ITU-R BT.601",

497 "ITU-R BT.709",

498 "ITU-T H.273 IEC 61966-2",

499 "ITU-T H.273 Log",

500 "ITU-T H.273 Log Sqrt",

501 "ITU-T H.273 ST.428-1",

502 "L-Log",

503 "Log2",

504 "Log3G10",

505 "Log3G12",

506 "Mi-Log",

507 "N-Log",

508 "PLog",

509 "Panalog",

510 "ProPhoto RGB",

511 "Protune",

512 "REDLog",

513 "REDLogFilm",

514 "RIMM RGB",

515 "ROMM RGB",

516 "S-Log",

517 "S-Log2",

518 "S-Log3",

519 "SMPTE 240M",

520 "ST 2084",

521 "T-Log",

522 "V-Log",

523 "ViperLog",

524 "sRGB",

525]

526

527 LiteralCCTFDecoding = Literal[

528 "ACEScc",

529 "ACEScct",

530 "ACESproxy",

531 "ARIB STD-B67",

532 "ARRI LogC3",

533 "ARRI LogC4",

534 "Apple Log Profile",

535 "Blackmagic Film Generation 5",

536 "Canon Log",

537 "Canon Log 2",

538 "Canon Log 3",

539 "Cineon",

540 "D-Log",

541 "DCDM",

542 "DICOM GSDF",

543 "DaVinci Intermediate",

544 "ERIMM RGB",

545 "F-Log",

546 "F-Log2",

547 "Filmic Pro 6",

548 "Gamma 2.2",

549 "Gamma 2.4",

550 "Gamma 2.6",

551 "ITU-R BT.1886",

552 "ITU-R BT.2020",

553 "ITU-R BT.2100 HLG",

554 "ITU-R BT.2100 PQ",

555 "ITU-R BT.601",

556 "ITU-R BT.709",

557 "ITU-T H.273 IEC 61966-2",

558 "ITU-T H.273 Log",

559 "ITU-T H.273 Log Sqrt",

560 "ITU-T H.273 ST.428-1",

561 "L-Log",

562 "Log2",

563 "Log3G10",

564 "Log3G12",

565 "Mi-Log",

566 "N-Log",

567 "PLog",

568 "Panalog",

569 "ProPhoto RGB",

570 "Protune",

571 "REDLog",

572 "REDLogFilm",

573 "RIMM RGB",

574 "ROMM RGB",

575 "S-Log",

576 "S-Log2",

577 "S-Log3",

578 "SMPTE 240M",

579 "ST 2084",

580 "T-Log",

581 "V-Log",

582 "ViperLog",

583 "sRGB",

584]

585

586 LiteralOOTF = Literal["ITU-R BT.2100 HLG", "ITU-R BT.2100 PQ"]

587

588 LiteralOOTFInverse = Literal["ITU-R BT.2100 HLG", "ITU-R BT.2100 PQ"]

589

590 LiteralLUTReadMethod = Literal[

591 "Cinespace",

592 "Iridas Cube",

593 "Resolve Cube",

594 "Sony SPI1D",

595 "Sony SPI3D",

596 "Sony SPImtx",

597]

598

599 LiteralLUTWriteMethod = Literal[

600 "Cinespace",

601 "Iridas Cube",

602 "Resolve Cube",

603 "Sony SPI1D",

604 "Sony SPI3D",

605 "Sony SPImtx",

606]

607

608 LiteralDeltaEMethod = Literal[

609 "CAM02-LCD",

610 "CAM02-SCD",

611 "CAM02-UCS",

612 "CAM16-LCD",

613 "CAM16-SCD",

614 "CAM16-UCS",

615 "CIE 1976",

616 "CIE 1994",

617 "CIE 2000",

618 "CMC",

619 "DIN99",

620 "HyAB",

621 "HyCH",

622 "ITP",

623 "cie1976",

624 "cie1994",

625 "cie2000",

626]

627

628 LiteralFontScaling = Literal[

629 "xx-small",

630 "x-small",

631 "small",

632 "medium",

633 "large",

634 "x-large",

635 "xx-large",

636 "larger",

637 "smaller",

638 "xx-small-colour-science",

639 "x-small-colour-science",

640 "small-colour-science",

641 "medium-colour-science",

642 "large-colour-science",

643 "x-large-colour-science",

644 "xx-large-colour-science",

645]

646# LITERALISE::END

647

648

649 def arraylike(a: ArrayLike) -> NDArray: ...

650

651

652 def number_or_arraylike(a: ArrayLike) -> NDArray: ...

653

654

655 a: DTypeFloat = np.float64(1)

656 b: float = 1

657 c: float = 1

658 d: ArrayLike = [c, c]

659 e: ArrayLike = d

660 s_a: Sequence[DTypeFloat] = [a, a]

661 s_b: Sequence[float] = [b, b]

662 s_c: Sequence[float] = [c, c]

663

664 arraylike(a)

665 arraylike(b)

666 arraylike(c)

667 arraylike(d)

668 arraylike([d, d])

669 arraylike(e)

670 arraylike([e, e])

671 arraylike(s_a)

672 arraylike(s_b)

673 arraylike(s_c)

674

675 number_or_arraylike(a)

676 number_or_arraylike(b)

677 number_or_arraylike(c)

678 number_or_arraylike(d)

679 number_or_arraylike([d, d])

680 number_or_arraylike(e)

681 number_or_arraylike([e, e])

682 number_or_arraylike(s_a)

683 number_or_arraylike(s_b)

684 number_or_arraylike(s_c)

685

686 np.atleast_1d(a)

687 np.atleast_1d(b)

688 np.atleast_1d(c)

689 np.atleast_1d(arraylike(d))

690 np.atleast_1d(arraylike([d, d]))

691 np.atleast_1d(arraylike(e))

692 np.atleast_1d(arraylike([e, e]))

693 np.atleast_1d(s_a)

694 np.atleast_1d(s_b)

695 np.atleast_1d(s_c)

696

697 del a, b, c, d, e, s_a, s_b, s_c

698

699# ----------------------------------------------------------------------------#

700# --- API Changes and Deprecation Management ---#

701# ----------------------------------------------------------------------------#

702 if not typing.TYPE_CHECKING:

703 DTypeFloating = DTypeFloat

704 DTypeInteger = DTypeInt

705 DTypeNumber = DTypeReal

706 Boolean = bool

707 Floating = float

708 Integer = int

709 Number = Real

710 FloatingOrArrayLike = ArrayLike

711 FloatingOrNDArray = NDArrayFloat