Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve docs regarding import of 'main' #1804

Closed
spencerchubb opened this issue Jan 21, 2023 · 3 comments
Closed

Improve docs regarding import of 'main' #1804

spencerchubb opened this issue Jan 21, 2023 · 3 comments
Labels
docs Documentation

Comments

@spencerchubb
Copy link

I spent so long banging my head against the wall, and I feel like a clarification in the docs could help others.

In all the tutorials, you import a variable called 'main' but never actually use the variable. I thought it was weird, so I just removed the import. After many hours, I realized that it is very necessary to import main...

I have never seen an API that requires importing a variable but not using the variable. In fact, most linters will say this is an error. I think because of this non-standard API choice, the tutorials should warn people that 'main' MUST be imported for apps to be served properly.

@spencerchubb spencerchubb added the bug Bug in code label Jan 21, 2023
@mturoci mturoci added docs Documentation and removed bug Bug in code labels Jan 23, 2023
@mturoci
Copy link
Collaborator

mturoci commented Jan 26, 2023

Thanks for reporting @spencerchubb! The main is being imported so that we can hack around Uvicorn requiring if __name__ == main as an entry point. If you are familiar with marker interface, this is very similar and can be called a "marker import".

While I agree the unused import is non-standard, it's the best we can do. Any PR that could make it better is more than welcome.

Meanwhile, do you have any suggestions on where this should be included in the docs to save time and prevent head injuries from banging against the wall? :)

@spencerchubb
Copy link
Author

Perhaps in the 'Apps' section of the docs would be a good place to put it? Since it seems to be required for apps but not for scripts

https://wave.h2o.ai/docs/apps

Something like this:

# Note: main must be imported even though it is not used
from h2o_wave import main, app, Q, ui

@app('/foo')
async def serve(q: Q):
    # Modify the page
    q.page['qux'] = ui.some_card()

    # Save the page
    await q.page.save()

@mturoci
Copy link
Collaborator

mturoci commented Jan 27, 2023

Yes, that sounds reasonable. Would you mind opening a PR yourself?

@mturoci mturoci closed this as completed in 8f7cc2d Feb 3, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation
Projects
None yet
Development

No branches or pull requests

2 participants