Uploader._upload() in pywikibot/site/_upload.py has 48 branches and approximately 138 statements.

Fresh uploads, chunked transfers, stash validation and resumption, warning callbacks, offset correction, polling, and final publication are currently mixed into one recursive workflow.
Warning handling can restart or resume an upload by recursively calling _upload(), making state transitions difficult to follow and modify safely.

Suggested improvements:

• Introduce explicit stages for validation, stash recovery, chunk transfer, warning resolution, polling, and finalization.
• Keep upload progress such as file key and offset in a private state object.
• Replace recursive restarts with iterative stage transitions.
• Extract focused helpers for each stage.
• Preserve existing public behavior, exceptions, logging, warning callbacks, and request parameters.
• Reuse existing upload coverage and add focused offline tests only where state transitions are not already characterized.

Acceptance criteria:

• Upload restarts and resumptions no longer call _upload() recursively.
• Fresh, URL, chunked, resumed, warning, polling, and finalization paths use explicit transitions.
• Uploader.upload() retains its current public interface and behavior.
• _upload() complexity is substantially reduced without transferring it into one large helper.
• Focused tests, Ruff, Flake8, and git diff --check pass.

Benefits:

• Upload state becomes visible and testable.
• Resumption and warning handling are easier to reason about.
• Future upload fixes are less likely to break another upload mode.