Logical Implementation of Shor Algorithm - #12317

Thanks for the pure-Python Shor implementation @joelkurien — keeping it dependency-free is a good fit for the collection. A few issues to address before merge:

1. Module docstring placement. The triple-quoted description sits after import math / import random, so Python doesn't treat it as the module docstring. Move it to the very top of the file, above the imports.
2. Import-time side effects. shor = Shor() and print(shor.shor_algorithm(15)) run at module top level, so they execute on import (during test collection and DIRECTORY generation). Please move them under if __name__ == "__main__":, and add import doctest; doctest.testmod() there.
3. Re-seeding inside the loop (bug). shor_algorithm calls random.seed(0) inside while True, so every iteration draws the same num; if that candidate never yields a factor, the loop spins forever. Seed once before the loop (or not at all) and let num vary across iterations.
4. Minor: with the loop restructured, make sure the annotated -> tuple[int, int] return always holds (no implicit None fall-through).

Type hints and the period_find doctest are good — the above are the main blockers.