[reportlab] Use TypedDict with Unpack for BaseDocTemplate kwargs

[Ashid332]

You are a senior Typeshed contributor working on the ReportLab stubs.

Objective

Resolve the remaining TODO: Use TypedDict with Unpack for **kw in:

stubs/reportlab/reportlab/platypus/doctemplate.pyi

by replacing the untyped **kw parameter in BaseDocTemplate.__init__ with a precise TypedDict using PEP 692 Unpack.

This is a stub-only typing improvement. Do not modify runtime behavior or public APIs.

---

Phase 1 — Investigation

Inspect:

• stubs/reportlab/reportlab/platypus/doctemplate.pyi
• The corresponding ReportLab runtime implementation of BaseDocTemplate
• Any related ReportLab stubs defining PageTemplate, Flowable, or shared aliases

Before making changes:

1. Enumerate every keyword argument accepted by BaseDocTemplate.__init__.
2. Verify default values and optionality.
3. Confirm which attributes are assigned directly from **kw.
4. Reuse existing types where available instead of introducing new aliases.
5. Preserve existing Typeshed style and naming conventions.

Do not infer unsupported keyword arguments.

---

Phase 2 -Introduce TypedDict

Import:

• TypedDict from typing
• Unpack from typing_extensions

Create:

@type_check_only
class _DocTemplateKwargs(TypedDict, total=False):
    ...

[github-actions]

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉

[srittau]

@Daverball Do you remember why this is supposed to be a TypedDict, instead of inlining the arguments?

[Daverball]

I'm not fully sure I remember, but I think it was mostly because it is **kw in the original source code, so stubtest would complain if we inlined the arguments.

But it also will be slightly nicer for overriding __init__ in subclasses, reusing this TypedDict is a lot more readable and maintainable than duplicating the entire argument list that might later get desynced when reportlab adds more arguments. Desync can still happen, since stubtest won't help us detect the desync, but at least it would only have to be fixed in these stubs and not in everyone's downstream code as well, as long as they reused the type from the stubs.

If there were fewer keyword arguments, then I would probably prefer inlining them as well. But in this case I think a TypedDict provides slightly better ergonomics.

[srittau]

I'm not fully sure I remember, but I think it was mostly because it is **kw in the original source code, so stubtest would complain if we inlined the arguments.

Your other arguments make sense, but if I remember correctly, stubtest doesn't complain when concrete arguments are used in the stubs in place of **kw in the implementation.