Coverage for src/toolbox_python/checkers.py: 100%

1# ============================================================================ #

2# #

3# Title: Checkers #

4# Purpose: Check certain values against other objects. #

5# #

6# ============================================================================ #

9# ---------------------------------------------------------------------------- #

10# #

11# Setup ####

12# #

13# ---------------------------------------------------------------------------- #

16## --------------------------------------------------------------------------- #

17## Imports ####

18## --------------------------------------------------------------------------- #

21# ## Python StdLib Imports ----

22from typing import Any, Union

24# ## Python Third Party Imports ----

25from typeguard import typechecked

27# ## Local First Party Imports ----

28from toolbox_python.collection_types import (

29 any_collection,

30 scalar,

31 str_collection,

32 str_list,

33)

36## --------------------------------------------------------------------------- #

37## Exports ####

38## --------------------------------------------------------------------------- #

41__all__: str_list = [

42 "all_elements_contains",

43 "any_element_contains",

44 "assert_all_in",

45 "assert_all_type",

46 "assert_all_values_in_iterable",

47 "assert_all_values_of_type",

48 "assert_any_in",

49 "assert_any_type",

50 "assert_any_values_in_iterable",

51 "assert_in",

52 "assert_type",

53 "assert_value_in_iterable",

54 "assert_value_of_type",

55 "get_elements_containing",

56 "is_all_in",

57 "is_all_type",

58 "is_all_values_in_iterable",

59 "is_all_values_of_type",

60 "is_any_in",

61 "is_any_type",

62 "is_any_values_in_iterable",

63 "is_in",

64 "is_type",

65 "is_value_in_iterable",

66 "is_value_of_type",

67]

70# ---------------------------------------------------------------------------- #

71# #

72# Main Section ####

73# #

74# ---------------------------------------------------------------------------- #

77## --------------------------------------------------------------------------- #

78## `is_*()` functions ####

79## --------------------------------------------------------------------------- #

82def is_value_of_type(

83 value: Any,

84 check_type: Union[type, tuple[type, ...]],

85) -> bool:

86 """

87 !!! summary "Summary"

88 Check if a given value is of a specified type or types.

90 ???+ info "Details"

91 This function is used to verify if a given value matches a specified type or any of the types in a tuple of types.

93 Params:

94 value (Any):

95 The value to check.

96 check_type (Union[type, tuple[type]]):

97 The type or tuple of types to check against.

99 Returns:

100 (bool):

101 `#!py True` if the value is of the specified type or one of the specified types; `#!py False` otherwise.

102

103 ???+ example "Examples"

104

105 Check if a value is of a specific type:

106

107 ```{.py .python linenums="1" title="Prepare data"}

108 >>> value = 42

109 >>> check_type = int

110 ```

111

112 ```{.py .python linenums="1" title="Example 1: Check if value is of type `#!py int`"}

113 >>> is_value_of_type(value, check_type)

114 ```

115 <div class="result" markdown>

116 ```{.sh .shell title="Output"}

117 True

118 ```

119 !!! success "Conclusion: The value is of type `#!py int`."

120

121 </div>

122

123 ```{.py .python linenums="1" title="Example 2: Check if value is of type `#!py str`"}

124 >>> is_value_of_type(value, str)

125 ```

126 <div class="result" markdown>

127 ```{.sh .shell title="Output"}

128 False

129 ```

130 !!! failure "Conclusion: The value is not of type `#!py str`."

131

132 </div>

133

134 ??? tip "See Also"

135 - [`is_value_of_type()`][toolbox_python.checkers.is_value_of_type]

136 - [`is_type()`][toolbox_python.checkers.is_type]

137 """

138 return isinstance(value, check_type)

139

140

141def is_all_values_of_type(

142 values: any_collection,

143 check_type: Union[type, tuple[type, ...]],

144) -> bool:

145 """

146 !!! summary "Summary"

147 Check if all values in an iterable are of a specified type or types.

148

149 ???+ info "Details"

150 This function is used to verify if all values in a given iterable match a specified type or any of the types in a tuple of types.

151

152 Params:

153 values (any_collection):

154 The iterable containing values to check.

155 check_type (Union[type, tuple[type]]):

156 The type or tuple of types to check against.

157

158 Returns:

159 (bool):

160 `#!py True` if all values are of the specified type or one of the specified types; `#!py False` otherwise.

161

162 ???+ example "Examples"

163

164 Check if all values in an iterable are of a specific type:

165

166 ```{.py .python linenums="1" title="Prepare data"}

167 >>> values = [1, 2, 3]

168 >>> check_type = int

169 ```

170

171 ```{.py .python linenums="1" title="Example 1: Check if all values are of type `#!py int`"}

172 >>> is_all_values_of_type(values, check_type)

173 ```

174 <div class="result" markdown>

175 ```{.sh .shell title="Output"}

176 True

177 ```

178 !!! success "Conclusion: All values are of type `#!py int`."

179

180 </div>

181

182 ```{.py .python linenums="1" title="Example 2: Check if all values are of type `#!py str`"}

183 >>> is_all_values_of_type(values, str)

184 ```

185 <div class="result" markdown>

186 ```{.sh .shell title="Output"}

187 False

188 ```

189 !!! failure "Conclusion: Not all values are of type `#!py str`."

190

191 </div>

192

193 ??? tip "See Also"

194 - [`is_value_of_type()`][toolbox_python.checkers.is_value_of_type]

195 - [`is_all_values_of_type()`][toolbox_python.checkers.is_all_values_of_type]

196 - [`is_type()`][toolbox_python.checkers.is_type]

197 - [`is_all_type()`][toolbox_python.checkers.is_all_type]

198 """

199 return all(isinstance(value, check_type) for value in values)

200

201

202def is_any_values_of_type(

203 values: any_collection,

204 check_type: Union[type, tuple[type, ...]],

205) -> bool:

206 """

207 !!! summary "Summary"

208 Check if any value in an iterable is of a specified type or types.

209

210 ???+ info "Details"

211 This function is used to verify if any value in a given iterable matches a specified type or any of the types in a tuple of types.

212

213 Params:

214 values (any_collection):

215 The iterable containing values to check.

216 check_type (Union[type, tuple[type]]):

217 The type or tuple of types to check against.

218

219 Returns:

220 (bool):

221 `#!py True` if any value is of the specified type or one of the specified types; `#!py False` otherwise.

222

223 ???+ example "Examples"

224

225 Check if any value in an iterable is of a specific type:

226

227 ```{.py .python linenums="1" title="Prepare data"}

228 >>> values = [1, 'a', 3.0]

229 >>> check_type = str

230 ```

231

232 ```{.py .python linenums="1" title="Example 1: Check if any value is of type `#!py str`"}

233 >>> is_any_values_of_type(values, check_type)

234 ```

235 <div class="result" markdown>

236 ```{.sh .shell title="Output"}

237 True

238 ```

239 !!! success "Conclusion: At least one value is of type `#!py str`."

240

241 </div>

242

243 ```{.py .python linenums="1" title="Example 2: Check if any value is of type `#!py dict`"}

244 >>> is_any_values_of_type(values, dict)

245 ```

246 <div class="result" markdown>

247 ```{.sh .shell title="Output"}

248 False

249 ```

250 !!! failure "Conclusion: No values are of type `#!py dict`."

251

252 </div>

253

254 ??? tip "See Also"

255 - [`is_value_of_type()`][toolbox_python.checkers.is_value_of_type]

256 - [`is_any_values_of_type()`][toolbox_python.checkers.is_any_values_of_type]

257 - [`is_type()`][toolbox_python.checkers.is_type]

258 - [`is_any_type()`][toolbox_python.checkers.is_any_type]

259 """

260 return any(isinstance(value, check_type) for value in values)

261

262

263def is_value_in_iterable(

264 value: scalar,

265 iterable: any_collection,

266) -> bool:

267 """

268 !!! summary "Summary"

269 Check if a given value is present in an iterable.

270

271 ???+ info "Details"

272 This function is used to verify if a given value exists within an iterable such as a list, tuple, or set.

273

274 Params:

275 value (scalar):

276 The value to check.

277 iterable (any_collection):

278 The iterable to check within.

279

280 Returns:

281 (bool):

282 `#!py True` if the value is found in the iterable; `#!py False` otherwise.

283

284 ???+ example "Examples"

285

286 Check if a value is in an iterable:

287

288 ```{.py .python linenums="1" title="Prepare data"}

289 >>> value = 2

290 >>> iterable = [1, 2, 3]

291 ```

292

293 ```{.py .python linenums="1" title="Example 1: Check if value is in the iterable"}

294 >>> is_value_in_iterable(value, iterable)

295 ```

296 <div class="result" markdown>

297 ```{.sh .shell title="Output"}

298 True

299 ```

300 !!! success "Conclusion: The value is in the iterable."

301

302 </div>

303

304 ```{.py .python linenums="1" title="Example 2: Check if value is not in the iterable"}

305 >>> is_value_in_iterable(4, iterable)

306 ```

307 <div class="result" markdown>

308 ```{.sh .shell title="Output"}

309 False

310 ```

311 !!! failure "Conclusion: The value is not in the iterable."

312

313 </div>

314

315 ??? tip "See Also"

316 - [`is_value_in_iterable()`][toolbox_python.checkers.is_value_in_iterable]

317 - [`is_in()`][toolbox_python.checkers.is_in]

318 """

319 return value in iterable

320

321

322def is_all_values_in_iterable(

323 values: any_collection,

324 iterable: any_collection,

325) -> bool:

326 """

327 !!! summary "Summary"

328 Check if all values in an iterable are present in another iterable.

329

330 ???+ info "Details"

331 This function is used to verify if all values in a given iterable exist within another iterable.

332

333 Params:

334 values (any_collection):

335 The iterable containing values to check.

336 iterable (any_collection):

337 The iterable to check within.

338

339 Returns:

340 (bool):

341 `#!py True` if all values are found in the iterable; `#!py False` otherwise.

342

343 ???+ example "Examples"

344

345 Check if all values in an iterable are present in another iterable:

346

347 ```{.py .python linenums="1" title="Prepare data"}

348 >>> values = [1, 2]

349 >>> iterable = [1, 2, 3]

350 ```

351

352 ```{.py .python linenums="1" title="Example 1: Check if all values are in the iterable"}

353 >>> is_all_values_in_iterable(values, iterable)

354 ```

355 <div class="result" markdown>

356 ```{.sh .shell title="Output"}

357 True

358 ```

359 !!! success "Conclusion: All values are in the iterable."

360

361 </div>

362

363 ```{.py .python linenums="1" title="Example 2: Check if all values are not in the iterable"}

364 >>> is_all_values_in_iterable([1, 4], iterable)

365 ```

366 <div class="result" markdown>

367 ```{.sh .shell title="Output"}

368 False

369 ```

370 !!! failure "Conclusion: Not all values are in the iterable."

371

372 </div>

373

374 ??? tip "See Also"

375 - [`is_value_in_iterable()`][toolbox_python.checkers.is_value_in_iterable]

376 - [`is_all_values_of_type()`][toolbox_python.checkers.is_all_values_of_type]

377 - [`is_in()`][toolbox_python.checkers.is_in]

378 - [`is_all_in()`][toolbox_python.checkers.is_all_in]

379 """

380 return all(value in iterable for value in values)

381

382

383def is_any_values_in_iterable(

384 values: any_collection,

385 iterable: any_collection,

386) -> bool:

387 """

388 !!! summary "Summary"

389 Check if any value in an iterable is present in another iterable.

390

391 ???+ info "Details"

392 This function is used to verify if any value in a given iterable exists within another iterable.

393

394 Params:

395 values (any_collection):

396 The iterable containing values to check.

397 iterable (any_collection):

398 The iterable to check within.

399

400 Returns:

401 (bool):

402 `#!py True` if any value is found in the iterable; `#!py False` otherwise.

403

404 ???+ example "Examples"

405

406 Check if any value in an iterable is present in another iterable:

407

408 ```{.py .python linenums="1" title="Prepare data"}

409 >>> values = [1, 4]

410 >>> iterable = [1, 2, 3]

411 ```

412

413 ```{.py .python linenums="1" title="Example 1: Check if any value is in the iterable"}

414 >>> is_any_values_in_iterable(values, iterable)

415 ```

416 <div class="result" markdown>

417 ```{.sh .shell title="Output"}

418 True

419 ```

420 !!! success "Conclusion: At least one value is in the iterable."

421

422 </div>

423

424 ```{.py .python linenums="1" title="Example 2: Check if any value is not in the iterable"}

425 >>> is_any_values_in_iterable([4, 5], iterable)

426 ```

427 <div class="result" markdown>

428 ```{.sh .shell title="Output"}

429 False

430 ```

431 !!! failure "Conclusion: None of the values are in the iterable."

432

433 </div>

434

435 ??? tip "See Also"

436 - [`is_value_in_iterable()`][toolbox_python.checkers.is_value_in_iterable]

437 - [`is_any_values_of_type()`][toolbox_python.checkers.is_any_values_of_type]

438 - [`is_in()`][toolbox_python.checkers.is_in]

439 - [`is_any_in()`][toolbox_python.checkers.is_any_in]

440 """

441 return any(value in iterable for value in values)

442

443

444### Aliases ----

445is_type = is_value_of_type

446is_all_type = is_all_values_of_type

447is_any_type = is_any_values_of_type

448is_in = is_value_in_iterable

449is_any_in = is_any_values_in_iterable

450is_all_in = is_all_values_in_iterable

451

452

453## --------------------------------------------------------------------------- #

454## `assert_*()` functions ####

455## --------------------------------------------------------------------------- #

456

457

458def assert_value_of_type(

459 value: Any,

460 check_type: Union[type, tuple[type, ...]],

461) -> None:

462 """

463 !!! summary "Summary"

464 Assert that a given value is of a specified type or types.

465

466 ???+ info "Details"

467 This function is used to assert that a given value matches a specified type or any of the types in a tuple of types. If the value does not match the specified type(s), a `#!py TypeError` is raised.

468

469 Params:

470 value (Any):

471 The value to check.

472 check_type (Union[type, tuple[type]]):

473 The type or tuple of types to check against.

474

475 Raises:

476 (TypeError):

477 If the value is not of the specified type or one of the specified types.

478

479 ???+ example "Examples"

480

481 Assert that a value is of a specific type:

482

483 ```{.py .python linenums="1" title="Prepare data"}

484 >>> value = 42

485 >>> check_type = int

486 ```

487

488 ```{.py .python linenums="1" title="Example 1: Assert that value is of type int"}

489 >>> assert_value_of_type(value, check_type)

490 ```

491 <div class="result" markdown>

492 ```{.sh .shell title="Output"}

493 (no output, no exception raised)

494 ```

495 !!! success "Conclusion: The value is of type `#!py int`."

496

497 </div>

498

499 ```{.py .python linenums="1" title="Example 2: Assert that value is of type str"}

500 >>> assert_value_of_type(value, str)

501 ```

502 <div class="result" markdown>

503 ```{.sh .shell title="Output"}

504 Traceback (most recent call last):

505 ...

506 TypeError: Value '42' is not correct type: 'int'. Must be: 'str'

507 ```

508 !!! failure "Conclusion: The value is not of type `#!py str`."

509

510 </div>

511

512 ```{.py .python linenums="1" title="Example 3: Assert that value is of type int or float"}

513 >>> assert_value_of_type(value, (int, float))

514 ```

515 <div class="result" markdown>

516 ```{.sh .shell title="Output"}

517 (no output, no exception raised)

518 ```

519 !!! success "Conclusion: The value is of type `#!py int` or `#!py float`."

520

521 </div>

522

523 ```{.py .python linenums="1" title="Example 4: Assert that value is of type str or dict"}

524 >>> assert_value_of_type(value, (str, dict))

525 ```

526 <div class="result" markdown>

527 ```{.sh .shell title="Output"}

528 Traceback (most recent call last):

529 ...

530 TypeError: Value '42' is not correct type: 'int'. Must be: 'str' or 'dict'.

531 ```

532 !!! failure "Conclusion: The value is not of type `#!py str` or `#!py dict`."

533

534 </div>

535

536 ??? tip "See Also"

537 - [`is_value_of_type()`][toolbox_python.checkers.is_value_of_type]

538 - [`is_type()`][toolbox_python.checkers.is_type]

539 """

540 if not is_type(value=value, check_type=check_type):

541 msg: str = f"Value '{value}' is not correct type: '{type(value).__name__}'. "

542 if isinstance(check_type, type):

543 msg += f"Must be: '{check_type.__name__}'."

544 else:

545 msg += f"Must be: '{' or '.join([typ.__name__ for typ in check_type])}'."

546 raise TypeError(msg)

547

548

549def assert_all_values_of_type(

550 values: any_collection,

551 check_type: Union[type, tuple[type, ...]],

552) -> None:

553 """

554 !!! summary "Summary"

555 Assert that all values in an iterable are of a specified type or types.

556

557 ???+ info "Details"

558 This function is used to assert that all values in a given iterable match a specified type or any of the types in a tuple of types. If any value does not match the specified type(s), a `#!py TypeError` is raised.

559

560 Params:

561 values (any_collection):

562 The iterable containing values to check.

563 check_type (Union[type, tuple[type]]):

564 The type or tuple of types to check against.

565

566 Raises:

567 (TypeError):

568 If any value is not of the specified type or one of the specified types.

569

570 ???+ example "Examples"

571

572 Assert that all values in an iterable are of a specific type:

573

574 ```{.py .python linenums="1" title="Prepare data"}

575 >>> values = [1, 2, 3]

576 >>> check_type = int

577 ```

578

579 ```{.py .python linenums="1" title="Example 1: Assert that all values are of type int"}

580 >>> assert_all_values_of_type(values, check_type)

581 ```

582 <div class="result" markdown>

583 ```{.sh .shell title="Output"}

584 (no output, no exception raised)

585 ```

586 !!! success "Conclusion: All values are of type `#!py int`."

587

588 </div>

589

590 ```{.py .python linenums="1" title="Example 2: Assert that all values are of type str"}

591 >>> assert_all_values_of_type(values, str)

592 ```

593 <div class="result" markdown>

594 ```{.sh .shell title="Output"}

595 Traceback (most recent call last):

596 ...

597 TypeError: Some elements [1, 2, 3] have the incorrect type ['int', 'int', 'int']. Must be 'str'

598 ```

599 !!! failure "Conclusion: Not all values are of type `#!py str`."

600

601 </div>

602

603 ```{.py .python linenums="1" title="Example 3: Assert that all values are of type int or float"}

604 >>> assert_all_values_of_type(values, (int, float))

605 ```

606 <div class="result" markdown>

607 ```{.sh .shell title="Output"}

608 (no output, no exception raised)

609 ```

610 !!! success "Conclusion: All values are of type `#!py int` or `#!py float`."

611

612 </div>

613

614 ```{.py .python linenums="1" title="Example 4: Assert that all values are of type str or dict"}

615 >>> assert_all_values_of_type(values, (str, dict))

616 ```

617 <div class="result" markdown>

618 ```{.sh .shell title="Output"}

619 Traceback (most recent call last):

620 ...

621 TypeError: Some elements [1, 2, 3] have the incorrect type ['int', 'int', 'int']. Must be: 'str' or 'dict'

622 ```

623 !!! failure "Conclusion: Not all values are of type `#!py str` or `#!py dict`."

624

625 </div>

626

627 ??? tip "See Also"

628 - [`is_value_of_type()`][toolbox_python.checkers.is_value_of_type]

629 - [`is_all_values_of_type()`][toolbox_python.checkers.is_all_values_of_type]

630 - [`is_type()`][toolbox_python.checkers.is_type]

631 - [`is_all_type()`][toolbox_python.checkers.is_all_type]

632 """

633 if not is_all_type(values=values, check_type=check_type):

634 invalid_values = [value for value in values if not is_type(value, check_type)]

635 invalid_types = [

636 f"'{type(value).__name__}'"

637 for value in values

638 if not is_type(value, check_type)

639 ]

640 msg: str = (

641 f"Some elements {invalid_values} have the incorrect type {invalid_types}. "

642 )

643 if isinstance(check_type, type):

644 msg += f"Must be '{check_type}'"

645 else:

646 types: str_list = [f"'{typ.__name__}'" for typ in check_type]

647 msg += f"Must be: {' or '.join(types)}"

648 raise TypeError(msg)

649

650

651def assert_any_values_of_type(

652 values: any_collection,

653 check_type: Union[type, tuple[type, ...]],

654) -> None:

655 """

656 !!! summary "Summary"

657 Assert that any value in an iterable is of a specified type or types.

658

659 ???+ info "Details"

660 This function is used to assert that at least one value in a given iterable matches a specified type or any of the types in a tuple of types. If none of the values match the specified type(s), a `#!py TypeError` is raised.

661

662 Params:

663 values (any_collection):

664 The iterable containing values to check.

665 check_type (Union[type, tuple[type]]):

666 The type or tuple of types to check against.

667

668 Raises:

669 (TypeError):

670 If none of the values are of the specified type or one of the specified types.

671

672 ???+ example "Examples"

673

674 Assert that any value in an iterable is of a specific type:

675

676 ```{.py .python linenums="1" title="Prepare data"}

677 >>> values = [1, 'a', 3.0]

678 >>> check_type = str

679 ```

680

681 ```{.py .python linenums="1" title="Example 1: Assert that any value is of type str"}

682 >>> assert_any_values_of_type(values, check_type)

683 ```

684 <div class="result" markdown>

685 ```{.sh .shell title="Output"}

686 (no output, no exception raised)

687 ```

688 !!! success "Conclusion: At least one value is of type `#!py str`."

689

690 </div>

691

692 ```{.py .python linenums="1" title="Example 2: Assert that any value is of type dict"}

693 >>> assert_any_values_of_type(values, dict)

694 ```

695 <div class="result" markdown>

696 ```{.sh .shell title="Output"}

697 Traceback (most recent call last):

698 ...

699 TypeError: None of the elements in [1, 'a', 3.0] have the correct type. Must be: 'dict'

700 ```

701 !!! failure "Conclusion: None of the values are of type `#!py dict`."

702

703 </div>

704

705 ```{.py .python linenums="1" title="Example 3: Assert that any value is of type int or float"}

706 >>> assert_any_values_of_type(values, (int, float))

707 ```

708 <div class="result" markdown>

709 ```{.sh .shell title="Output"}

710 (no output, no exception raised)

711 ```

712 !!! success "Conclusion: At least one value is of type `#!py int` or `#!py float`."

713

714 </div>

715

716 ```{.py .python linenums="1" title="Example 4: Assert that any value is of type dict or list"}

717 >>> assert_any_values_of_type(values, (dict, list))

718 ```

719 <div class="result" markdown>

720 ```{.sh .shell title="Output"}

721 Traceback (most recent call last):

722 ...

723 TypeError: None of the elements in [1, 'a', 3.0] have the correct type. Must be: 'dict' or 'list'

724 ```

725 !!! failure "Conclusion: None of the values are of type `#!py dict` or `#!py list`."

726

727 </div>

728

729 ??? tip "See Also"

730 - [`is_value_of_type()`][toolbox_python.checkers.is_value_of_type]

731 - [`is_any_values_of_type()`][toolbox_python.checkers.is_any_values_of_type]

732 - [`is_type()`][toolbox_python.checkers.is_type]

733 - [`is_any_type()`][toolbox_python.checkers.is_any_type]

734 """

735 if not is_any_type(values=values, check_type=check_type):

736 invalid_values = [value for value in values if not is_type(value, check_type)]

737 msg: str = f"None of the elements in {invalid_values} have the correct type. "

738 if isinstance(check_type, type):

739 msg += f"Must be: '{check_type.__name__}'"

740 else:

741 types: str_list = [f"'{typ.__name__}'" for typ in check_type]

742 msg += f"Must be: {' or '.join(types)}"

743 raise TypeError(msg)

744

745

746def assert_value_in_iterable(

747 value: scalar,

748 iterable: any_collection,

749) -> None:

750 """

751 !!! summary "Summary"

752 Assert that a given value is present in an iterable.

753

754 ???+ info "Details"

755 This function is used to assert that a given value exists within an iterable such as a `#!py list`, `#!py tuple`, or `#!py set`. If the value is not found in the iterable, a `#!py LookupError` is raised.

756

757 Params:

758 value (scalar):

759 The value to check.

760 iterable (any_collection):

761 The iterable to check within.

762

763 Raises:

764 (LookupError):

765 If the value is not found in the iterable.

766

767 ???+ example "Examples"

768

769 Assert that a value is in an iterable:

770

771 ```{.py .python linenums="1" title="Prepare data"}

772 >>> value = 2

773 >>> iterable = [1, 2, 3]

774 ```

775

776 ```{.py .python linenums="1" title="Example 1: Assert that value is in the iterable"}

777 >>> assert_value_in_iterable(value, iterable)

778 ```

779 <div class="result" markdown>

780 ```{.sh .shell title="Output"}

781 (no output, no exception raised)

782 ```

783 !!! success "Conclusion: The value is in the iterable."

784

785 </div>

786

787 ```{.py .python linenums="1" title="Example 2: Assert that value is not in the iterable"}

788 >>> assert_value_in_iterable(4, iterable)

789 ```

790 <div class="result" markdown>

791 ```{.sh .shell title="Output"}

792 Traceback (most recent call last):

793 ...

794 LookupError: Value '4' not found in iterable: [1, 2, 3]

795 ```

796 !!! failure "Conclusion: The value is not in the iterable."

797

798 </div>

799

800 ??? tip "See Also"

801 - [`is_value_in_iterable()`][toolbox_python.checkers.is_value_in_iterable]

802 - [`is_in()`][toolbox_python.checkers.is_in]

803 """

804 if not is_in(value=value, iterable=iterable):

805 raise LookupError(f"Value '{value}' not found in iterable: {iterable}")

806

807

808def assert_any_values_in_iterable(

809 values: any_collection,

810 iterable: any_collection,

811) -> None:

812 """

813 !!! summary "Summary"

814 Assert that any value in an iterable is present in another iterable.

815

816 ???+ info "Details"

817 This function is used to assert that at least one value in a given iterable exists within another iterable. If none of the values are found in the iterable, a `#!py LookupError` is raised.

818

819 Params:

820 values (any_collection):

821 The iterable containing values to check.

822 iterable (any_collection):

823 The iterable to check within.

824

825 Raises:

826 (LookupError):

827 If none of the values are found in the iterable.

828

829 ???+ example "Examples"

830

831 Assert that any value in an iterable is present in another iterable:

832

833 ```{.py .python linenums="1" title="Prepare data"}

834 >>> values = [1, 4]

835 >>> iterable = [1, 2, 3]

836 ```

837

838 ```{.py .python linenums="1" title="Example 1: Assert that any value is in the iterable"}

839 >>> assert_any_values_in_iterable(values, iterable)

840 ```

841 <div class="result" markdown>

842 ```{.sh .shell title="Output"}

843 (no output, no exception raised)

844 ```

845 !!! success "Conclusion: At least one value is in the iterable."

846

847 </div>

848

849 ```{.py .python linenums="1" title="Example 2: Assert that any value is not in the iterable"}

850 >>> assert_any_values_in_iterable([4, 5], iterable)

851 ```

852 <div class="result" markdown>

853 ```{.sh .shell title="Output"}

854 Traceback (most recent call last):

855 ...

856 LookupError: None of the values in [4, 5] can be found in [1, 2, 3]

857 ```

858 !!! failure "Conclusion: None of the values are in the iterable."

859

860 </div>

861

862 ??? tip "See Also"

863 - [`is_value_in_iterable()`][toolbox_python.checkers.is_value_in_iterable]

864 - [`is_any_values_of_type()`][toolbox_python.checkers.is_any_values_of_type]

865 - [`is_in()`][toolbox_python.checkers.is_in]

866 - [`is_any_in()`][toolbox_python.checkers.is_any_in]

867 """

868 if not is_any_in(values=values, iterable=iterable):

869 raise LookupError(f"None of the values in {values} can be found in {iterable}")

870

871

872def assert_all_values_in_iterable(

873 values: any_collection,

874 iterable: any_collection,

875) -> None:

876 """

877 !!! summary "Summary"

878 Assert that all values in an iterable are present in another iterable.

879

880 ???+ info "Details"

881 This function is used to assert that all values in a given iterable exist within another iterable. If any value is not found in the iterable, a `#!py LookupError` is raised.

882

883 Params:

884 values (any_collection):

885 The iterable containing values to check.

886 iterable (any_collection):

887 The iterable to check within.

888

889 Raises:

890 (LookupError):

891 If any value is not found in the iterable.

892

893 ???+ example "Examples"

894

895 Assert that all values in an iterable are present in another iterable:

896

897 ```{.py .python linenums="1" title="Prepare data"}

898 >>> values = [1, 2]

899 >>> iterable = [1, 2, 3]

900 ```

901

902 ```{.py .python linenums="1" title="Example 1: Assert that all values are in the iterable"}

903 >>> assert_all_values_in_iterable(values, iterable)

904 ```

905 <div class="result" markdown>

906 ```{.sh .shell title="Output"}

907 (no output, no exception raised)

908 ```

909 !!! success "Conclusion: All values are in the iterable."

910

911 </div>

912

913 ```{.py .python linenums="1" title="Example 2: Assert that all values are not in the iterable"}

914 >>> assert_all_values_in_iterable([1, 4], iterable)

915 ```

916 <div class="result" markdown>

917 ```{.sh .shell title="Output"}

918 Traceback (most recent call last):

919 ...

920 LookupError: Some values [4] are missing from [1, 2, 3]

921 ```

922 !!! failure "Conclusion: Not all values are in the iterable."

923

924 </div>

925

926 ??? tip "See Also"

927 - [`is_value_in_iterable()`][toolbox_python.checkers.is_value_in_iterable]

928 - [`is_all_values_of_type()`][toolbox_python.checkers.is_all_values_of_type]

929 - [`is_in()`][toolbox_python.checkers.is_in]

930 - [`is_all_in()`][toolbox_python.checkers.is_all_in]

931 """

932 if not is_all_in(values=values, iterable=iterable):

933 missing_values = [value for value in values if not is_in(value, iterable)]

934 raise LookupError(f"Some values {missing_values} are missing from {iterable}")

935

936

937### Aliases ----

938assert_type = assert_value_of_type

939assert_all_type = assert_all_values_of_type

940assert_any_type = assert_any_values_of_type

941assert_in = assert_value_in_iterable

942assert_any_in = assert_any_values_in_iterable

943assert_all_in = assert_all_values_in_iterable

944

945

946## --------------------------------------------------------------------------- #

947## `*_contains()` functions ####

948## --------------------------------------------------------------------------- #

949

950

951@typechecked

952def any_element_contains(

953 iterable: str_collection,

954 check: str,

955) -> bool:

956 """

957 !!! note "Summary"

958 Check to see if any element in a given iterable contains a given string value.

959 !!! warning "Note: This check _is_ case sensitive."

960

961 ???+ abstract "Details"

962 This function is helpful for doing a quick check to see if any element in a `#!py list` contains a given `#!py str` value. For example, checking if any column header contains a specific string value.

963

964 Params:

965 iterable (str_collection):

966 The iterables to check within. Because this function uses an `#!py in` operation to check if `check` string exists in the elements of `iterable`, therefore all elements of `iterable` must be `#!py str` type.

967 check (str):

968 The string value to check exists in any of the elements in `iterable`.

969

970 Raises:

971 TypeError: If any of the inputs parsed to the parameters of this function are not the correct type. Uses the [`@typeguard.typechecked`](https://typeguard.readthedocs.io/en/stable/api.html#typeguard.typechecked) decorator.

972

973 Returns:

974 (bool):

975 `#!py True` if at least one element in `iterable` contains `check` string; `#!py False` if no elements contain `check`.

976

977 ???+ example "Examples"

978

979 Check if any element in an iterable contains a specific string:

980

981 ```{.py .python linenums="1" title="Prepare data"}

982 >>> iterable = ["apple", "banana", "cherry"]

983 >>> check = "an"

984 ```

985

986 ```{.py .python linenums="1" title="Example 1: Check if any element contains 'an'"}

987 >>> any_element_contains(iterable, check)

988 ```

989 <div class="result" markdown>

990 ```{.sh .shell title="Output"}

991 True

992 ```

993 !!! success "Conclusion: At least one element contains `'an'`."

994

995 </div>

996

997 ```{.py .python linenums="1" title="Example 2: Check if any element contains 'xy'"}

998 >>> any_element_contains(iterable, "xy")

999 ```

1000 <div class="result" markdown>

1001 ```{.sh .shell title="Output"}

1002 False

1003 ```

1004 !!! failure "Conclusion: No elements contain `'xy'`."

1005

1006 </div>

1007 """

1008 return any(check in elem for elem in iterable)

1009

1010

1011@typechecked

1012def all_elements_contains(iterable: str_collection, check: str) -> bool:

1013 """

1014 !!! note "Summary"

1015 Check to see if all elements in a given iterable contains a given string value.

1016 !!! warning "Note: This check _is_ case sensitive."

1017

1018 ???+ abstract "Details"

1019 This function is helpful for doing a quick check to see if all element in a `#!py list` contains a given `#!py str` value. For example, checking if all columns in a DataFrame contains a specific string value.

1020

1021 Params:

1022 iterable (str_collection):

1023 The iterables to check within. Because this function uses an `#!py in` operation to check if `check` string exists in the elements of `iterable`, therefore all elements of `iterable` must be `#!py str` type.

1024 check (str):

1025 The string value to check exists in any of the elements in `iterable`.

1026

1027 Raises:

1028 TypeError: If any of the inputs parsed to the parameters of this function are not the correct type. Uses the [`@typeguard.typechecked`](https://typeguard.readthedocs.io/en/stable/api.html#typeguard.typechecked) decorator.

1029

1030 Returns:

1031 (bool):

1032 `#!py True` if all elements in `iterable` contains `check` string; `#!py False` otherwise.

1033

1034 ???+ example "Examples"

1035

1036 Check if all elements in an iterable contain a specific string:

1037

1038 ```{.py .python linenums="1" title="Prepare data"}

1039 >>> iterable = ["apple", "banana", "peach"]

1040 >>> check = "a"

1041 ```

1042

1043 ```{.py .python linenums="1" title="Example 1: Check if all elements contain 'a'"}

1044 >>> all_elements_contains(iterable, check)

1045 ```

1046 <div class="result" markdown>

1047 ```{.sh .shell title="Output"}

1048 True

1049 ```

1050 !!! success "Conclusion: All elements contain `'a'`."

1051

1052 </div>

1053

1054 ```{.py .python linenums="1" title="Example 2: Check if all elements contain 'e'"}

1055 >>> all_elements_contains(iterable, "e")

1056 ```

1057 <div class="result" markdown>

1058 ```{.sh .shell title="Output"}

1059 False

1060 ```

1061 !!! failure "Conclusion: Not all elements contain `'e'`."

1062

1063 </div>

1064 """

1065 return all(check in elem for elem in iterable)

1066

1067

1068@typechecked

1069def get_elements_containing(iterable: str_collection, check: str) -> tuple[str, ...]:

1070 """

1071 !!! note "Summary"

1072 Extract all elements in a given iterable which contains a given string value.

1073 !!! warning "Note: This check _is_ case sensitive."

1074

1075 Params:

1076 iterable (str_collection):

1077 The iterables to check within. Because this function uses an `#!py in` operation to check if `check` string exists in the elements of `iterable`, therefore all elements of `iterable` must be `#!py str` type.

1078 check (str):

1079 The string value to check exists in any of the elements in `iterable`.

1080

1081 Raises:

1082 TypeError: If any of the inputs parsed to the parameters of this function are not the correct type. Uses the [`@typeguard.typechecked`](https://typeguard.readthedocs.io/en/stable/api.html#typeguard.typechecked) decorator.

1083

1084 Returns:

1085 (tuple):

1086 A `#!py tuple` containing all the string elements from `iterable` which contains the `check` string.

1087

1088 ???+ example "Examples"

1089

1090 Extract elements in an iterable that contain a specific string:

1091

1092 ```{.py .python linenums="1" title="Prepare data"}

1093 >>> iterable = ["apple", "banana", "cherry"]

1094 >>> check = "an"

1095 ```

1096

1097 ```{.py .python linenums="1" title="Example 1: Extract elements containing 'an'"}

1098 >>> get_elements_containing(iterable, check)

1099 ```

1100 <div class="result" markdown>

1101 ```{.sh .shell title="Output"}

1102 ('banana',)

1103 ```

1104 !!! success "Conclusion: The element(s) containing `'an'` are extracted."

1105

1106 </div>

1107

1108 ```{.py .python linenums="1" title="Example 2: Extract elements containing 'xy'"}

1109 >>> get_elements_containing(iterable, "xy")

1110 ```

1111 <div class="result" markdown>

1112 ```{.sh .shell title="Output"}

1113 ()

1114 ```

1115 !!! failure "Conclusion: No elements contain `'xy'`."

1116

1117 </div>

1118 """

1119 return tuple(elem for elem in iterable if check in elem)