feat: Audit: Modernise codebase to Python 3.9+ idioms

[citconv-agents]

Summary

Implements #82

This PR was automatically generated by the Developer Agent.

Original Issue

Scope

Update the entire codebase to use modern Python 3.9+ patterns, removing legacy compatibility code.

What to Review and Update

Type Hints

• Replace typing.Optional[X] with X | None
• Replace typing.Union[X, Y] with X | Y
• Replace typing.List, typing.Dict, typing.Tuple, typing.Set with list, dict, tuple, set
• Replace typing.Sequence, typing.Mapping with collections.abc equivalents where needed
• Add type hints to functions/methods that lack them (focus on public API)

String Formatting

• Replace % formatting and .format() with f-strings where it improves readability
• Don't change logging calls (f-strings in logging are a performance anti-pattern)

Path Handling

• Replace os.path usage with pathlib.Path where appropriate
• Modernise file open patterns

Other Modernisations

• Use dict | other_dict merge syntax (3.9+) where applicable
• Use walrus operator (:=) where it simplifies code
• Replace type(x) == Y with isinstance(x, Y)
• Use from __future__ import annotations consistently for deferred evaluation
• Remove any six or Python 2 compatibility code if present

Packaging

• Verify requires-python = ">=3.9" is set
• Remove any Python 3.7/3.8 specific workarounds

Constraints

• Do NOT change public API signatures or behaviour
• Do NOT modernise test files in this issue (covered by test audit)
• All existing tests must continue to pass

Output

Commit modernisation changes grouped by category (type hints, f-strings, pathlib, etc.) for easy review.

---

Generated by Developer Agent using Claude Code

[citconv-agents]

Security Agent Report

SECURITY_PASS

Security Review — PR #110

Summary

PR #110 is a pure modernization/refactoring PR that updates the codebase to Python 3.9+ idioms. No new functionality is introduced, no new dependencies are added, and no security regressions are present.

Changes Reviewed

All changed files were reviewed:

• src/docx/__init__.py
• src/docx/api.py
• src/docx/blkcntnr.py
• src/docx/dml/color.py
• src/docx/document.py
• src/docx/drawing/__init__.py
• src/docx/enum/base.py (and other enum files)
• src/docx/image/*.py
• src/docx/opc/*.py
• src/docx/oxml/*.py
• src/docx/parts/*.py
• src/docx/section.py
• src/docx/shape.py
• src/docx/shared.py
• src/docx/styles/*.py
• src/docx/table.py
• src/docx/text/*.py

Findings

No Issues Found

Injection Risks — CLEAN

XPath queries with f-strings (e.g. src/docx/oxml/numbering.py, src/docx/oxml/styles.py, src/docx/oxml/section.py):

• The original %-format strings had the same interpolation behavior for these values.
• All interpolated values in XPath expressions are either:
  • Strongly typed integers (e.g. numId typed as ST_DecimalNumber)
  • Internal enum conversions (e.g. WD_HEADER_FOOTER.to_xml(type_))
  • Hardcoded namespace URIs from nsmap (a static constant dict)
• No user-controlled input reaches any XPath or XML construction path in this diff.

XML construction with f-strings (e.g. src/docx/opc/oxml.py):

• All XML namespace URIs (nsmap["ct"], nsmap["pr"]) are hardcoded constants. No user data is interpolated into raw XML strings.

No XXE risk: The existing defusedxml.ElementTree usage in src/docx/image/svg.py is unchanged. The PR does not alter XML parsing configuration.

Path Handling — IMPROVED

os.path.join / os.path.split replaced with pathlib.Path throughout:

• All template file paths are constructed relative to __file__ (the package's own location), never relative to user-supplied input.
• Using Path(...).resolve() for the directory package reader (_DirPkgReader) is slightly stricter than os.path.abspath().
• No path traversal vectors introduced.

Dependencies — CLEAN

No new dependencies added. No pyproject.toml, requirements*.txt, or setup.cfg changes.

Secrets — CLEAN

No API keys, tokens, passwords, or credentials present anywhere in the diff.

Data Exposure — CLEAN

No new file I/O patterns, no logging of sensitive data, no changes to serialization behavior.

Conclusion

All changes are mechanical modernizations:

1. super(ClassName, self).__init__() → super().__init__()
2. %-style string formatting → f-strings
3. typing.List / typing.Dict / typing.Tuple / typing.Type → built-in list / dict / tuple / type
4. import os + os.path.* → from pathlib import Path + Path.*
5. from __future__ import annotations added to remaining files

No security concerns identified.