[Docs] Help messages, error messages, and documentation for pyflyte package unfortunately result in a very bad first-time UX

[fg91]

Description

Imagine we have a working directory called workflows which contains a file wf.py which I as a first-time user of pyflyte package want to package:

When a user runs pyflyte package —help, they see:

~ pyflyte package —help
…
--source                    -s  DIRECTORY  Local filesystem path to the root of the package.
…

So I ran pyflyte package -s . which gives this error:

<help message>
No packages to scan for flyte entities. Aborting!

When googlingpyflyte package, the first result is this docs page which does, however, not contain any example of how to use pyflyte package.
This docs page which I found next and which describes all pyflyte commands and options also does not contain a working code snippet.

Only when searching further I found this page which gives the first hint that the —source flag is not the right way to specify the workflow package/location but that one needs to use the pyflyte --pkgs <path> package command which notably does not contain —source.

When trying pyflyte --pkgs . package, I get this error:

Failed with Unknown Exception <class 'TypeError'> Reason: the 'package' argument is required to perform a relative import for '.'
…
  File “…/importlib/__init__.py", line 122, in import_module
    raise TypeError(msg.format(name))

Only when trying pyflyte --pkgs workflows package instead of pyflyte --pkgs . package from the parent directory of workflows, it finally works.

Todos for closing this issue:

• Provide a working code snippet in the documentation showing how the —source argument of pyflyte package is used or remove the —source argument if in fact it is not working.
• pyflyte package —help should show a working command including the —pkgs option.
• This and this documentation page should contain a working code snippet for pyflyte package
• pyflyte —pkgs . package should work when passing . as the current working directory or should at least catch the exception and provide a meaningful error message.

Are you sure this issue hasn't been raised already?

• Yes

Have you read the Code of Conduct?

• Yes

[runllm]

The issue you described highlights several pain points with the pyflyte package command, particularly around documentation and error messages. Here are some steps to address these issues:

1. Documentation Update: The documentation should include a working code snippet for the pyflyte package command. According to the Flyte documentation, the --pkgs option is essential for specifying the package to scan for Flyte entities. The --source option specifies the root directory of the package.

2. Help Message Improvement: The help message for pyflyte package should include an example command that uses the --pkgs option correctly. This will guide users on how to use the command effectively.

3. Error Handling: The command should handle cases where the current directory (.) is passed to --pkgs more gracefully, providing a meaningful error message if it fails.

Would you like a detailed breakdown of how to implement these changes or more information on a specific point?

Sources:

• Flyte Documentation
• Flyte GitHub Issue #2640
• Flyte GitHub Issue #2638

---

This is an AI-generated response and your feedback is appreciated! Please leave a 👍 if this is helpful and 👎 if it is not.

Mention @RunLLM to ask follow-up questions. See runllm.com for more!

[sumana-2705]

Hello @fg91
Can you assign this issue to me, I want to work on this.

[fg91]

Hello @fg91 Can you assign this issue to me, I want to work on this.

Done 🙏 You can tag me in the PR as reviewer if you make one.

[sumana-2705]

Definitely @fg91

Thanks for assigning me this issue

[sumana-2705]

Hii @fg91

I wanted to let you know that I added an example to use --source option in the help message and included information about the --pkgs option as well. However, I couldn't find the error message for file handling related to the . option.
Also, I'm unsure where to add a working code snippet for the pyflyte package. I don't have clear references to understand how to use it properly.

Could you please review the work I have completed so far. Additionally, I would like your guidance on how to proceed further.

[davidmirror-ops]

I'm unsure where to add a working code snippet for the pyflyte package

I think the places Fabio mentions in the OP are right:

This and this documentation page should contain a working code snippet for pyflyte package

[fg91]

We'll also need to remove "Like pyflyte register" here, this is not implemented and raises an exception. @sumana-2705 @davidmirror-ops