Add missing type annotations, unit tests, and targeted bug fixes across Python-Head-First-Design-Patterns

[rebuild-123]

Goal

Improve code quality and reliability in this repository by:

1. adding missing or incomplete type annotations,
2. introducing or expanding unit tests,
3. fixing real bugs discovered during inspection, testing, or implementation.

Scope

Apply incremental, targeted changes only.

Required work:

1. Identify modules with missing or inconsistent type annotations and improve them.
2. Add unit tests for the modules that are modified.
3. Reproduce and fix real bugs that are discovered while reading the code, annotating types, or running tests.
4. Keep the implementation limited to the affected modules and their directly related tests.

Constraints

1. Do not refactor unrelated code.
2. Do not add new dependencies unless strictly required.
3. Prefer the smallest safe change set.
4. Preserve current behavior unless a bug is being fixed.
5. If repository reality contradicts the current plan, stop and report it instead of expanding scope.

Expected output

Please produce:

1. a concrete plan,
2. a list of files to change,
3. type-annotation improvements,
4. unit tests for the changed behavior,
5. bug fixes only when supported by evidence,
6. validation results.

Acceptance criteria

The task is complete only if:

1. the modified Python code has meaningful type annotations,
2. new or updated unit tests exist for the changed behavior,
3. each claimed bug fix includes:
   • what the bug was,
   • how it was detected or reproduced,
   • how it was fixed,
4. relevant tests pass,
5. the final diff remains within the approved scope.

Notes

Prioritize correctness over breadth.
If the repository is too inconsistent for a clean incremental change, report blockers instead of widening scope.

[rebuild-123]

/codex plan branch=codex/type-tests-bugfix-v2

[github-actions]

Codex Plan

• Branch: codex/type-tests-bugfix-v2
• Base branch: main
• Issue: Add missing type annotations, unit tests, and targeted bug fixes across Python-Head-First-Design-Patterns #9

This is now the latest plan for this issue and branch.

Goal

Add targeted type annotations, unit tests, and a bug fix in a tightly scoped area of the repository, while keeping behavior unchanged except for the verified bug.

Problem statement

The repository currently has no stable test entrypoint and no existing tests/ layout.
In singleton/subclass, there is a real bug: CoolerSingleton.getInstance() and HotterSingleton.getInstance() both return a base Singleton instance (verified on 2026-04-11 by runtime check: both types were Singleton, and both calls returned the same object), which breaks subclass singleton semantics.

Affected files

Planned changes (only):

1. singleton/subclass/Singleton.py
2. singleton/subclass/CoolerSingleton.py
3. singleton/subclass/HotterSingleton.py
4. tests/test_singleton_subclass.py (new)
5. tests/__init__.py (new, minimal; optional but preferred for stable discovery)

Chosen approach

1. Keep scope to singleton/subclass only (plus directly related tests).
2. Fix singleton construction logic so getInstance() is class-aware and returns the calling subclass instance.
3. Add meaningful type annotations for singleton instance storage and getInstance() return type (e.g., TypeVar + Type[SelfT] style for subclass-correct typing).
4. Add unittest coverage for:
   • subclass instance type correctness,
   • singleton identity per class,
   • non-aliasing between CoolerSingleton and HotterSingleton.
5. Establish minimal tests/ layout as repository test entrypoint.

Milestones

1. Confirm baseline bug reproduction in singleton/subclass (completed in analysis).
2. Annotate and patch singleton/subclass/Singleton.py with class-aware singleton creation.
3. Add/adjust minimal annotations in CoolerSingleton.py and HotterSingleton.py only if required by tests/types.
4. Add tests/test_singleton_subclass.py with focused unittest cases.
5. Run targeted test module first, then full tests discovery.

Validation steps

1. Run smallest relevant tests first:
   python -m unittest tests.test_singleton_subclass -v
2. Run suite discovery entrypoint:
   python -m unittest discover -s tests -p 'test_*.py' -v
3. Explicitly report any failures with traceback and file references.

Risks

1. Existing examples may implicitly rely on a single global singleton instance across subclasses; fixing behavior could surface that assumption.
2. Class variable name-mangling (__uniqueInstance) can cause subtle subclass storage behavior; implementation must be deliberate and tested.

Rollback strategy

1. Revert only the touched singleton subclass files and new tests.
2. If behavior conflicts with expected repository intent, keep type-only annotations and remove behavioral change, then report blocker with evidence.

Out-of-scope items

1. Changes outside singleton/subclass and its direct tests.
2. Broad repo-wide typing cleanup.
3. Adding third-party dependencies (including pytest/type-checker tooling).
4. Refactors unrelated to the verified singleton subclass bug.

[rebuild-123]

/codex implement branch=codex/type-tests-bugfix-v2

[github-actions]

Codex Implementation

• Branch: codex/type-tests-bugfix-v2
• Base branch: main
• Issue: Add missing type annotations, unit tests, and targeted bug fixes across Python-Head-First-Design-Patterns #9
• Plan source: link
• Blocking review source: none
• Changes pushed: yes
• Diff vs base branch: yes
• PR: not created

Plan Executed

1. Inspect only approved files in .codex/codex-plan.md.
2. Apply minimal singleton subclass bug fix and type annotations in singleton/subclass.
3. Create minimal tests/ entrypoint and targeted unittest file.
4. Run targeted test first, then required discovery command.

Files Changed

1. singleton/subclass/Singleton.py
2. singleton/subclass/CoolerSingleton.py
3. singleton/subclass/HotterSingleton.py
4. tests/init.py
5. tests/test_singleton_subclass.py

Type Annotation Improvements

1. Singleton.__uniqueInstance annotated as ClassVar[Optional["Singleton"]] (Singleton.py:10).
2. Singleton.getInstance converted to typed classmethod with subclass-correct return type: def getInstance(cls: Type[SelfT]) -> SelfT (Singleton.py:18).
3. Constructor return annotations added:
   • CoolerSingleton.py:8
   • HotterSingleton.py:7
   • Singleton.py:15

Bug Fix (With Evidence)

1. Bug: CoolerSingleton.getInstance() and HotterSingleton.getInstance() returned base Singleton instance due to static method hardcoding Singleton() and base storage.
2. Detection/Reproduction: documented in approved plan (.codex/codex-plan.md) as confirmed runtime behavior on 2026-04-11.
3. Fix: changed to class-aware classmethod using cls() and per-calling-class storage via cls.__uniqueInstance (Singleton.py:18-23).

Unit Tests Added

1. tests/test_singleton_subclass.py:22: subclass type correctness for CoolerSingleton.
2. tests/test_singleton_subclass.py:26: subclass type correctness for HotterSingleton.
3. tests/test_singleton_subclass.py:30: singleton identity per class + non-aliasing between classes.
4. Test isolation resets singleton state in setUp (tests/test_singleton_subclass.py:16).

Validation Results

1. python -m unittest tests.test_singleton_subclass -v
   Result: Ran 3 tests ... OK
2. PYTHONPATH=. python -m unittest discover -s tests -p 'test*.py' -t .
   Result: Ran 3 tests ... OK

.codex/codex-review.md was not present, so there were no additional mandatory findings to apply.

[rebuild-123]

/codex review branch=codex/type-tests-bugfix-v2

[rebuild-123]

/codex review branch=codex/type-tests-bugfix-v2

[github-actions]

Codex Review

• Branch: codex/type-tests-bugfix-v2
• Base branch: main
• Issue: Add missing type annotations, unit tests, and targeted bug fixes across Python-Head-First-Design-Patterns #9
• Plan source: link
• Implementation source: link

The latest review is blocking and recommends re-planning before the next implement run.

REVIEW_STATUS: BLOCKED
REPLAN_REQUIRED: true

summary
The branch is close to scope, but the core singleton bug fix is incomplete: subclass calls can still return a Singleton instance depending on call order. Current tests all pass, but they miss this case.

blocking findings

• Incorrect subclass behavior still reproducible when base class is initialized first.
  Evidence: with current getInstance, calling Singleton.getInstance() before CoolerSingleton.getInstance() makes CoolerSingleton.getInstance() return the same base Singleton object.
  Root cause: lookup uses inherited cls._Singleton__uniqueInstance, so subclasses read base storage if they have not set their own yet.
  Location: Singleton.py:19

non-blocking findings

• CoolerSingleton still declares a private __uniqueInstance that is not used by the new base logic (_CoolerSingleton__uniqueInstance vs _Singleton__uniqueInstance), which is confusing and increases maintenance risk.
  Location: CoolerSingleton.py:6

validation gaps

• Missing regression test for call-order bug (Singleton.getInstance() first, then subclass getInstance()), so the reported bug fix is not fully covered.
  Test file: test_singleton_subclass.py
• Executed tests:
  • python -m unittest tests.test_singleton_subclass -v (pass)
  • PYTHONPATH=. python -m unittest discover -s tests -p 'test*.py' -t . -v (pass)

next action
Update the plan and implement a true per-class storage strategy in Singleton.getInstance (not inherited fallback), then add a regression test covering base-first call order and rerun the same targeted validation commands.