[katello-devel] Foreman cli - design proposal

[Jason Connor]

Just my 2¢, but we've really enjoyed using Okaara on Pulp. One of the main design goals was testability, which makes a huge difference imho.

Cheers!

On Apr 29, 2013, at 2:42 AM, Tomas Strachota <tstrachota at redhat.com> wrote:

> Hi team,
> I'm sending my design proposal for Foreman CLI.
> 
> See my gist for better reading experience:
> https://gist.github.com/tstrachota/fb4c84d422841008fd6b#file-foreman-cli-on-okaara-md
> 
> Martin Bacovsky is working on another (ruby based) proposal. His solution will follow soon.
> 
> Regards
> Tomas
> 
> 
> CLI for Foreman
> ===============
> The goal of this task was to create an official CLI for Foreman that would ideally be extensible with plugins.
> Three framework options came up from the first exploration:
> * Thor[1] or Boson[2] (in ruby, Martin Bacovsky looked at them and will cover the outcome in a dedicated email)
> * Okaara[3] (in python)
> I experimented with Okaara and will try to draw the design in following lines.
> 
> Okaara
> ======
> From it's documentation:
> 
> *Okaara is a series of utilities for writing command line interfaces in Python. The provided functionality can be broken down into three categories: reading and writing utilities, an interactive shell framework, and a command line interface framework.*
> 
> Okaara was created as a part of Pulp's project that successfully uses it for it's admin and consumer CLIs. It has lot in common with Katello CLI's codebase. They solve the same problems but Okaara is usually more general purpose solution.
> 
> The Design
> ==========
> 
> Given the fact there are duplicities in Katello CLI vs Okaara, all three projects (Katello, Foreman, Pulp) could benefit if we used Okaara also for Foreman's CLI.
> 
> My idea is to create an Okaara based CLI project that would provide common behavior desired for Foreman and Katello cli, giving it same look and feel. I use working title *Pertinax*.
> 
> Pertinax would introduce modularity. I've already created a draft of such functionality. I took it from pulp-admin (this piece was not part of Okaara) and made it a bit more universal. It uses python entry points[4] for adding custom commands via initializer function. See Pulp's documentation[5] for details about this approach.
> 
> Usage of Pertinax would also enable to get rid of duplicities in Katello. I was very successful with porting current cli code to Okaara. All the modifications were made on level of the base classes. There was only very little to change on the commands itself (init functions, imports). There's example diff of necessary changes for commands org and provider[6].
> 
> Foreman cli would use directly Pertinax without need of any changes. Commands have very simple structure. I created an example of command user[7].
> 
> There are currently no api bindings for Foreman in Python. I solved that issue by modifying existing apipie generator of ruby bindings. More on that topic later.
> 
> Python Bindings
> ===============
> 
> There are no released python api bindings at the moment. I modified templates existing generator of ruby bindings[10] to produce python output. It serves the purpose but the directory structure is not the cleanest as original generator was intended to be used only for ruby. This part would need some polishing.
> 
> I think it is worth finishing the generator even if we decide not to use python for our cli. Official python bindings might be valuable for the community.
> 
> 
> Benefits/Drawbacks of This Solution
> ===================================
> 
> I tried to cover all the requirements I can imagine. So to summarize it I see following benefits/drawbacks:
> * [+] one can share commands from both Katello and Foreman for integration into a common cli
> * [+] command completion and shell is solved once for both
> * [+] cli is easily extensible via python entry points[4]
> * [?] we'd have to polish python bindings generator; on the other hand when we have it, it's definitely a benefit
> * [-] we'd be introducing another language into the project
> 
> 
> Current Status
> ==============
> * there's a simple draft for python based foreman cli[8]
> * pertinax[9] is currently a common set of libs extracted from katello, we should eventually give it better structure
> * apipie python bindings generator is now only modification of foreman_api[10], we should split it
> * by experimenting with Okaara I actually ported katello; the transition was smooth, we'd only have to get rid of libs that are now redundant
> * I've got small update for Okaara
> * all the above would need to be packaged
> 
> 
> 
> [1]: https://github.com/wycats/thor
> [2]: https://github.com/cldwalker/boson
> [3]: https://github.com/jdob/okaara
> [4]: http://pythonhosted.org/distribute/pkg_resources.html
> [5]: https://github.com/pulp/pulp/blob/master/docs/sphinx/dev-guide/newtypesupport/client/extensions.rst
> [6]: https://github.com/tstrachota/katello/commit/5c69bf90f8f180835175a49c8cc9827792be9c41
> [7]: https://github.com/tstrachota/foreman-cli/blob/master/foreman/commands/user.py
> [8]: https://github.com/tstrachota/foreman-cli
> [9]: https://github.com/tstrachota/pertinax
> [10]: https://github.com/mbacovsky/foreman_api/
> 
> _______________________________________________
> katello-devel mailing list
> katello-devel at redhat.com
> https://www.redhat.com/mailman/listinfo/katello-devel

Jason L Connor
linear on freenode #pulp
http://pulpproject.org/
RHCE: 805010912355231
GPG Fingerprint: 2048R/CC4ED7C1