docs: modernize README/docs and document every symbol

[wolph]

What & why

Two documentation improvements, no code-behavior changes.

1. Modernize README & Sphinx docs

• Rewrite README.md with an SVG hero banner, a badge row, a feature grid
  covering all public modules, and themed runnable examples.
• Overhaul the Sphinx docs: restructured landing page, new MyST guide pages
  (getting started, async, containers, conversions & formatting, performance,
  what's new), and a complete API reference — the previous autodoc page was
  missing 5 modules (aio, containers, generators, exceptions, types).
• Add docs/_static/banner.svg and extend pyproject keywords.

2. Document every symbol

• Google-style docstrings + #: autodoc comments so every construct is
  documented top to bottom: private helpers, inner closures, dunder methods,
  @typing.overload stubs, TypeVars, type aliases and module constants
  (the logger Protocol/methods, aliases, terminal helpers, time/aio
  internals, …). Enriched thin docstrings, added inline comments to the denser
  logic, and fixed a typo.
• Added module + per-test docstrings across the whole test suite.

Backwards compatibility

Docstrings/comments only — the public API is byte-identical (__all__
unchanged; the only code-shape change is @overload/Protocol stubs trading a
bare ... for a docstring body, which is semantically inert).

Verification (all green locally)

ruff check · ruff format · pytest (100% coverage, all doctests) ·
mypy · basedpyright · pyrefly · sphinx-build -W (zero warnings) ·
twine check (wheel + sdist).

[gemini-code-assist]

Code Review

This pull request modernizes the codebase and documentation for version 4.0, adding comprehensive docstrings, type annotations, and detailed guides for lazy imports, async helpers, and smart containers. It also introduces a complete test suite to maintain high coverage. The review feedback identifies two inaccuracies in the newly added docstrings: one in CastedDict.__setitem__ regarding key casting, and another in ioctl_gwinsz regarding the return types of terminal dimensions.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Copilot]

Pull request overview

This PR focuses on documentation quality and completeness: it modernizes the project’s README and Sphinx site (including new guide pages and assets) and enriches in-code docstrings/autodoc comments across the package and test suite, aiming to document every symbol without changing runtime behavior.

Changes:

• Revamps README.md with a banner, badges, a “what’s inside” module grid, and expanded runnable examples.
• Restructures and expands Sphinx docs (new landing page, new guide pages, a “What’s new” page, and expanded API reference coverage).
• Adds/expands docstrings and #: autodoc comments throughout python_utils/* and across the test suite.

Reviewed changes

Copilot reviewed 36 out of 37 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
README.md	New banner/badges layout, highlights, module overview, and examples.
pyproject.toml	Expands project keywords metadata.
docs/index.rst	New docs landing page with banner, badges, and reorganized toctrees.
docs/python_utils.rst	Updates API reference page to include additional submodules.
docs/whats-new.md	Adds a v4.0 “What’s new” guide page.
docs/getting-started.md	Adds a new getting-started guide page.
docs/guide/async.md	Adds an async helpers guide page.
docs/guide/containers.md	Adds a containers guide page.
docs/guide/conversions-and-formatting.md	Adds a conversions/formatting guide page.
docs/guide/performance.md	Adds a lazy-imports/performance guide page.
docs/conf.py	Updates Sphinx exclude patterns.
docs/_static/banner.svg	Adds an SVG banner asset.
python_utils/init.py	Expands docstrings for lazy import hooks (__getattr__, __dir__).
python_utils/about.py	Adds #: comments for package metadata fields.
python_utils/_aliases.py	Adds #: comments clarifying public type aliases.
python_utils/aio.py	Expands module/function docstrings; adds #: comments for type vars.
python_utils/containers.py	Improves reST formatting in module docstring; adds/expands docstrings and #: comments.
python_utils/converters.py	Adds type alias docs; adds overload docstrings; fixes a spelling error in remap docs.
python_utils/decorators.py	Adds docstrings/comments clarifying decorator wrappers and annotation handling.
python_utils/exceptions.py	Improves docstring formatting; adds docstring for inner raiser closure.
python_utils/generators.py	Adds #: comment for batching element TypeVar.
python_utils/import_.py	Converts a legacy-alias comment to #: autodoc form.
python_utils/logger.py	Adds #: comments; adds docstrings for protocol/methods and logger helpers.
python_utils/terminal.py	Adds #: comments for type aliases; adds docstrings/comments for size detection helpers.
python_utils/time.py	Adds #: comments for typing vars/constants; expands docstrings on helpers and decorators.
_python_utils_tests/init.py	Adds a package docstring for the test suite.
_python_utils_tests/test_aio.py	Adds module/test/helper docstrings.
_python_utils_tests/test_aliases.py	Adds docstrings describing alias/typing_extensions expectations.
_python_utils_tests/test_containers.py	Adds module/test docstrings for container behaviors.
_python_utils_tests/test_decorators.py	Adds module/test docstrings and class/method docstrings.
_python_utils_tests/test_generators.py	Adds module/test docstrings for batching behaviors.
_python_utils_tests/test_import.py	Adds module/test/helper docstrings for import helper tests.
_python_utils_tests/test_import_footprint.py	Adds docstrings for import-footprint guard tests.
_python_utils_tests/test_lazy_imports.py	Adds docstrings for lazy import behavior tests/helpers.
_python_utils_tests/test_logger.py	Adds module/test docstrings for loguru mixin behavior.
_python_utils_tests/test_python_utils.py	Adds module/test docstrings for __about__ metadata checks.
_python_utils_tests/test_time.py	Adds module/test/helper docstrings for timeout generator behaviors.

Comments suppressed due to low confidence (1)

docs/python_utils.rst:124

• docs/python_utils.rst ends with .. automodule:: python_utils but no :members:/:undoc-members: options. This likely drops the top-level package API from the generated reference, which conflicts with the goal of a complete API reference.

Module contents
---------------

.. automodule:: python_utils

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6ab25ca2d7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".