<div dir="ltr">Hi Sean, <br><div>Yes, please do improve docstrings for the client object! And I think you found that Lorin Hochstein recently added a Python SDK chapter to the end user guide at <a href="http://docs.openstack.org/user-guide/content/ch_sdk.html">http://docs.openstack.org/user-guide/content/ch_sdk.html</a>. </div>
<div><br></div><div>As for the CLI project itself, the docs team has taken all the command help and subcommand help for each python-<project>client and made a CLI reference:<br>
<a href="http://docs.openstack.org/cli-reference/content/neutronclient_commands.html" target="_blank">http://docs.openstack.org/cli-reference/content/neutronclient_commands.html</a><br></div><div><br></div><div>We haven't tackled or planned much for all the python-<project>client docs due to: priorities, resources, and a wait-and-see approach to the unified OpenStack client. </div>
<div><br></div><div>Hope that helps -- happy to plan an attack with you on the openstack-docs list if you have ideas.</div><div><br></div><div>Anne</div><div><br></div><div><br></div>
<div><br></div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Sat, Feb 8, 2014 at 1:20 PM, Collins, Sean <span dir="ltr"><<a href="mailto:Sean_Collins2@cable.comcast.com" target="_blank">Sean_Collins2@cable.comcast.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi,<br>
<br>
I was writing a small script yesterday to parse a list of IP blocks and<br>
create security groups and rules, by using python-neutronclient.<br>
<br>
To be honest, it was very difficult - even though I have actually<br>
written extensions to Python-Neutronclient for the QoS API.<br>
<br>
For those that are trying to use the client from inside their code,<br>
they end up getting zero help as to how to actually call any of the<br>
functions, and what parameters they take.<br>
<br>
<br>
>>> neutron = client.Client('2.0', auth_url=os.environ['OS_AUTH_URL'],<br>
... tenant_id=os.environ['OS_TENANT_ID'],<br>
... username=os.environ['OS_USERNAME'],<br>
... password=os.environ['OS_PASSWORD'])<br>
>>> help(neutron)<br>
<br>
| create_credential = <function with_params><br>
|<br>
| create_firewall = <function with_params><br>
|<br>
| create_firewall_policy = <function with_params><br>
|<br>
| create_firewall_rule = <function with_params><br>
|<br>
| create_floatingip = <function with_params><br>
|<br>
| create_health_monitor = <function with_params><br>
|<br>
| create_ikepolicy = <function with_params><br>
|<br>
| create_ipsec_site_connection = <function with_params><br>
|<br>
| create_ipsecpolicy = <function with_params><br>
|<br>
| create_member = <function with_params><br>
|<br>
| create_metering_label = <function with_params><br>
<br>
<br>
Since there was nothing there, I decided to go check the source of<br>
python-neutronclient and see if there are any examples.<br>
<br>
<a href="https://github.com/openstack/python-neutronclient/blob/master/doc/source/index.rst" target="_blank">https://github.com/openstack/python-neutronclient/blob/master/doc/source/index.rst</a><br>
<br>
If you read closely enough, you'll find out that the function takes a<br>
dictionary, that looks very similar to the request/response examples<br>
listed in the API documentation. So, I went over and checked it out.<br>
<br>
<a href="http://docs.openstack.org/api/openstack-network/2.0/content/POST_security-groups-v2.0_createSecGroup_v2.0_security-groups_security-groups-ext.html" target="_blank">http://docs.openstack.org/api/openstack-network/2.0/content/POST_security-groups-v2.0_createSecGroup_v2.0_security-groups_security-groups-ext.html</a><br>
<br>
So from there, I was able to remember enough that each of these<br>
functions takes a single argument, that is a dictionary, that mimics<br>
the same structure that you see in the API documentation, so from there<br>
it was just some experimentation to get the structure right.<br>
<br>
Honestly it wasn't easy to remember all this stuff, since<br>
it had been a couple months since I had worked with<br>
python-neutronclient, and it had been from inside the library itself.<br>
<br>
This was my first experience using it "on the outside" and it was pretty<br>
tough - so I'm going to try and look into how we can improve the<br>
docstrings for the client object, to make it a bit easier to figure out.<br>
<br>
Thoughts?<br>
<span class="HOEnZb"><font color="#888888"><br>
--<br>
Sean M. Collins<br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</font></span></blockquote></div><br></div>