Add additional docs for importing code with asyncio #2338

bdraco · 2024-09-26T13:34:51Z

Proposed change

Add additional docs for importing code with asyncio

When its safe to import keeps confusing devs so we need to provide more clarity here

Type of change

Document existing features within Home Assistant
Document new or changing features which there is an existing pull request elsewhere
Spelling or grammatical corrections, or rewording for improved clarity
Changes to the backend of this documentation
Removed stale or deprecated documentation

Additional information

This PR fixes or closes issue: fixes #
Link to relevant existing code or pull request:

coderabbitai · 2024-09-26T13:48:54Z

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

📥 Commits

Files that changed from the base of the PR and between cabd4e9 and 5563a4d.

📒 Files selected for processing (3)

docs/asyncio_blocking_operations.md (1 hunks)
docs/asyncio_imports.md (1 hunks)
sidebars.js (1 hunks)

__________________________________________________________
< Keep your friends close, but your code reviewers closer. >
----------------------------------------------------------
 \
  \   \
       \ /\
       ( )
     .( o ).

Tip

CodeRabbit can approve the review once all CodeRabbit's comments are resolved.

Enable the reviews.request_changes_workflow setting in your project's settings in CodeRabbit to automatically approve the review once all CodeRabbit's comments are resolved.

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Generate unit testing code for this file.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai generate unit testing code for this file.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and generate unit testing code.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai or @coderabbitai title anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

emontnemery

A couple of comments

emontnemery · 2024-09-26T15:39:06Z

docs/asyncio_imports.md

+
+## Top-level imports
+
+Suppose your imports happen at the top-level (nearly all code at indentation level 0). Home Assistant will import your code before the event loop starts or import it in the import executor when your integration is loaded. In this case, you likely do not need to consider whether your imports are safe.


I think the correct term is "module level" since it mentions indentation level 0?
Should we explain there needs to a chain of imports starting from a package's __init__.py?

emontnemery · 2024-09-26T15:43:50Z

docs/asyncio_imports.md

+
+## Imports outside of top-level
+
+If your imports are not happening at top-level, you must carefully consider each import, as the import machinery has to read the module from disk which does blocking I/O. If possible, it's usually best to change to a top-level import, as it avoids much complexity and the risk of mistakes. Importing modules is both CPU-intensive and involves blocking I/O, so it is crucial to ensure these operations are executed in the executor.


I think there are two reasons for doing non module-level imports:

Breaking circular import chains

Here, we could maybe mention imports which are only there for the benefit of the type check can be hidden behind an if TYPE_CHECKING: guard

We should probably also explain that if the import is imported also via an import chain starting at module-level of __init__.py it's safe to do a local import

Avoiding importing a large set of modules which will mostly be unused

I think this is the case where it's relevant to manually do imports in the executor?

frenck · 2024-09-30T20:16:49Z

Drafted the PR as changes have been requested.

bdraco added 3 commits September 26, 2024 08:34

Add additional docs for importing code with asyncio

5a05583

Add additional docs for importing code with asyncio

2d9ab44

Add additional docs for importing code with asyncio

abce36e

bdraco added 3 commits September 26, 2024 08:52

Add additional docs for importing code with asyncio

fc6d890

Add additional docs for importing code with asyncio

a84ad0a

Add additional docs for importing code with asyncio

5563a4d

bdraco marked this pull request as ready for review September 26, 2024 13:59

emontnemery reviewed Sep 26, 2024

View reviewed changes

frenck marked this pull request as draft September 30, 2024 20:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add additional docs for importing code with asyncio #2338

Add additional docs for importing code with asyncio #2338

bdraco commented Sep 26, 2024

coderabbitai bot commented Sep 26, 2024 •

edited

Loading

Chat

CodeRabbit Commands (Invoked using PR comments)

Other keywords and placeholders

CodeRabbit Configuration File (`.coderabbit.yaml`)

Documentation and Community

emontnemery left a comment

emontnemery Sep 26, 2024

emontnemery Sep 26, 2024

frenck commented Sep 30, 2024


		## Top-level imports

		Suppose your imports happen at the top-level (nearly all code at indentation level 0). Home Assistant will import your code before the event loop starts or import it in the import executor when your integration is loaded. In this case, you likely do not need to consider whether your imports are safe.


		## Imports outside of top-level

		If your imports are not happening at top-level, you must carefully consider each import, as the import machinery has to read the module from disk which does blocking I/O. If possible, it's usually best to change to a top-level import, as it avoids much complexity and the risk of mistakes. Importing modules is both CPU-intensive and involves blocking I/O, so it is crucial to ensure these operations are executed in the executor.

Add additional docs for importing code with asyncio #2338

Are you sure you want to change the base?

Add additional docs for importing code with asyncio #2338

Conversation

bdraco commented Sep 26, 2024

Proposed change

Type of change

Additional information

coderabbitai bot commented Sep 26, 2024 • edited Loading

Chat

CodeRabbit Commands (Invoked using PR comments)

Other keywords and placeholders

CodeRabbit Configuration File (.coderabbit.yaml)

Documentation and Community

emontnemery left a comment

Choose a reason for hiding this comment

emontnemery Sep 26, 2024

Choose a reason for hiding this comment

emontnemery Sep 26, 2024

Choose a reason for hiding this comment

frenck commented Sep 30, 2024

coderabbitai bot commented Sep 26, 2024 •

edited

Loading

CodeRabbit Configuration File (`.coderabbit.yaml`)