Add async template loading APIs and async loader/bytecode-cache hooks

[FatimahAlhumaidhi]

Summary

• Adds async template loading APIs to Environment:
  • get_template_async, select_template_async, get_or_select_template_async
  • list_templates_async, compile_templates_async
• Adds async hooks for loaders (BaseLoader.*_async) with sync fallbacks by default.
• Adds async hooks for bytecode caches (BytecodeCache.load_bytecode_async / dump_bytecode_async) and ensures async bucket operations await these hooks.
• Documents the new APIs and provides examples for implementing async loaders and async bytecode caches.

Motivation

Async apps increasingly store templates and caches behind async I/O. Jinja already supports async template execution, but loading and bytecode caching still require sync I/O. This change enables fully async template loading/caching without forcing thread offloading.

Design notes

• Compatibility: existing sync loaders / bytecode caches continue to work.
• Fallback behavior:
  • BaseLoader.get_source_async and list_templates_async default to calling the sync versions.
  • BytecodeCache.load_bytecode_async and dump_bytecode_async default to calling the sync versions.
• Correctness: BytecodeCache.get_bucket_async / set_bucket_async await the async hooks, so async-only caches work as expected.

Tests

Added tests that fail without the change:

• Environment.get_template_async works with sync loaders.
• AsyncEnvironment calls async loader hooks.
• compile_templates_async produces loadable module templates.
• Async-only BytecodeCache hooks are awaited (sync hooks must not be called).

Docs

• Updated docs/api.rst to include the new async APIs and examples.

Changelog

• Added an entry to CHANGES.rst describing async loading/caching APIs.

Links

fixes #2128

Reference links

• Pallets contributing guide: https://palletsprojects.com/contributing/pr
• Code of conduct: https://palletsprojects.com/governance/code-of-conduct/

[FatimahAlhumaidhi]

@davidism I understand you're closing the issue because it's a duplicate
but could you at least give the pr a chance? :)
I made sure not to have new changes that can affect/break current implementation and to make the async APIs completely independent and new

[davidism]

To be honest, this is out of the blue, from an unknown user, and feels LLM-generated. I just don't have the time or energy to review and design a whole API under those circumstances.

[FatimahAlhumaidhi]

To be honest, this is out of the blue, from an unknown user, and feels LLM-generated. I just don't have the time or energy to review and design a whole API under those circumstances.

@davidism
fair enough, the docs and tests are LLM but the code isn't, we've invested time on this as we are currently using this code on a large scale project and would love to give back to our beloved jinja

[FatimahAlhumaidhi]

Hello @davidism
Once again I'd ask you to consider keeping this pull request open and to actually look into the implementation
The added APIs are very much straightforward and doesn't have any extra logic aside from the async/await support
It is a mere copy of the existing similar sync implementation, I added tests to ensure that the sync/async pairs always share the same signature and logic, I also made sure that all the changes are new and doesn't affect any existing code

It is a simple simple addition that will help us and others greatly :)