Intended use of "Extending the CLI" funcionality

[pawelad]

Hi!

I'm currently playing around with Starlite and was very pleased that it has a CLI and even a concept of extending it, but I think might've misunderstood the purpose / target audience.

Is it meant for third party (pip installable) plugins, or is it meant for adding project specific scripts (the equivalent of custom Django commands)?

I was looking for the latter (custom project specific scripts), but - and please correct me if I'm wrong - it's currently meant for third party (pip installable) plugins?

I tried hacking my way to add a custom click based subcommand to it but with no luck. If you'd be open to the idea let me know so I can create a proper feature request and even potentially work on implementing it.

[provinzkraut]

Is it meant for third party (pip installable) plugins, or is it meant for adding project specific scripts

Both actually, but I can see why it's not very intuitive how to do that for local scripts. We should extend the documentation there.

The CLI discovers additional commands via entry points, as described in the docs. These still work for local projects, if you install them. poetry install for example will install your local package by default (unless configured not to), making defined entrypoints available.

The reasoning behind doing it like that was that other ways require quite a bit of workarounds and magic to end up with a solution that behaves like you'd expect it to in all situations (for example, if you have a programmatic hook, this won't be available before your code runs, meaning you can't run code from the same module via the CLI). The easiest solution for this was to simply use entry points for 3rd party and local packages alike.

The only other somewhat viable option I could think of would be to have some autodiscovery magic, that picks up commands from a predefined path, e.g. starlite_commands.

Currently, the solution is to do something like

[tool.poetry.plugins."starlite.commands"]
my_command = "my_app.cli:main"

assuming you my_app.cli is the module wherein you define your CLI and main is the main click.Group.

Would this be sufficient for your use case for the time being? You are of course welcome to make suggestions for how to better handle this.

[pawelad]

Thank you for getting back to me so quickly, and sorry it took me so long to get back to you.

The thing is, I don't use poetry (nor I intend to) and I never install the web applications as (editable) Python packages (I never got the upside) - with those two caveats, it's currently impossible for me to extend the CLI with custom scripts, right?

[provinzkraut]

The poetry thing is just an example. The docs include an example for using setup.py as well.

with those two caveats, it's currently impossible for me to extend the CLI with custom scripts, right?

Well, it's not entirely impossible, but impractical.

The reason for using entrypoints is this: If you want to add commands from within a module, the CLI would somehow have to know about this module before it starts, which means importing that module. But if the module is what adds those commands to the CLI in the first place.. Well, I guess you can see the issue here ;)

The entrypoints API is simply the canonical way for Python scripts to make themselves available, and it's what's being used for things like markdown or Sphinx extensions, poetry plugins, Flask CLI extensions, etc., pretty much everything where you run into this problem.

There are other ways to solve this, but they're all a bit hacky. When I first designed the CLI, I actually included such a mechanism, but I wasn't happy with the API and removed it, planning to revisit once a proper use case came along.

Maybe you could tell me how you would like a feature like this to work, so we can come up with a good solution?

[pawelad]

The poetry thing is just an example. The docs include an example for using setup.py as well.

But both of these depend on the web app / project (built with Litestar) being installed locally as a Python package (via poetry or pip install -e ., right? I think this is essentially my question : )

with those two caveats, it's currently impossible for me to extend the CLI with custom scripts, right?

Well, it's not entirely impossible, but impractical.

Sorry, I meant in the current version of Litestar and me refusing to install the web app / project locally as a package : )

The reason for using entrypoints is this: If you want to add commands from within a module, the CLI would somehow have to know about this module before it starts, which means importing that module. But if the module is what adds those commands to the CLI in the first place.. Well, I guess you can see the issue here ;)

Yes, absolutely. I was gonna suggest adding the extra CLI commands as part of the Litestar app / class arguments, but that suffers from the same problem.

Maybe you could tell me how you would like a feature like this to work, so we can come up with a good solution?

I think I'm essentially asking for the equivalent of custom Django commands I mentioned in the original post (which are discovered by being in a predefined directory, and thus don't need the web app / project to be installed locally as a package).

At the same time, I understand the current approach, I just wanted to make sure I'm not missing anything : )

---

To sum up, the "Extending the CLI" can be used by both third party (pip installable) plugins and for custom project specific scripts, with the caveat of requiring the project to also be installed as a Python package for the entrypoints to work. Is that correct?

[provinzkraut]

To sum up, the "Extending the CLI" can be used by both third party (pip installable) plugins and for custom project specific scripts, with the caveat of requiring the project to also be installed as a Python package for the entrypoints to work. Is that correct?

Pretty much, yes.

I think I'm essentially asking for the equivalent of custom Django commands

As I said in an earlier comment, I too think this is the best solution. If you feel like it you can open an issue with an enhancement proposal and we can start tracking this.