Open Stack

Hi Sean,
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 http://docs.openstack.org/user-guide/content/ch_sdk.html.

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:
http://docs.openstack.org/cli-reference/content/neutronclient_commands.html

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.

Hope that helps -- happy to plan an attack with you on the openstack-docs
list if you have ideas.

Anne





On Sat, Feb 8, 2014 at 1:20 PM, Collins, Sean <
Sean_Collins2 at cable.comcast.com> wrote:

> Hi,
>
> I was writing a small script yesterday to parse a list of IP blocks and
> create security groups and rules, by using python-neutronclient.
>
> To be honest, it was very difficult - even though I have actually
> written extensions to Python-Neutronclient for the QoS API.
>
> For those that are trying to use the client from inside their code,
> they end up getting zero help as to how to actually call any of the
> functions, and what parameters they take.
>
>
>     >>> neutron = client.Client('2.0', auth_url=os.environ['OS_AUTH_URL'],
>     ...                             tenant_id=os.environ['OS_TENANT_ID'],
>     ...                             username=os.environ['OS_USERNAME'],
>     ...                             password=os.environ['OS_PASSWORD'])
>     >>> help(neutron)
>
>    |  create_credential = <function with_params>
>    |
>    |  create_firewall = <function with_params>
>    |
>    |  create_firewall_policy = <function with_params>
>    |
>    |  create_firewall_rule = <function with_params>
>    |
>    |  create_floatingip = <function with_params>
>    |
>    |  create_health_monitor = <function with_params>
>    |
>    |  create_ikepolicy = <function with_params>
>    |
>    |  create_ipsec_site_connection = <function with_params>
>    |
>    |  create_ipsecpolicy = <function with_params>
>    |
>    |  create_member = <function with_params>
>    |
>    |  create_metering_label = <function with_params>
>
>
> Since there was nothing there, I decided to go check the source of
> python-neutronclient and see if there are any examples.
>
>
> https://github.com/openstack/python-neutronclient/blob/master/doc/source/index.rst
>
> If you read closely enough, you'll find out that the function takes a
> dictionary, that looks very similar to the request/response examples
> listed in the API documentation. So, I went over and checked it out.
>
>
> http://docs.openstack.org/api/openstack-network/2.0/content/POST_security-groups-v2.0_createSecGroup_v2.0_security-groups_security-groups-ext.html
>
> So from there, I was able to remember enough that each of these
> functions takes a single argument, that is a dictionary, that mimics
> the same structure that you see in the API documentation, so from there
> it was just some experimentation to get the structure right.
>
> Honestly it wasn't easy to remember all this stuff, since
> it had been a couple months since I had worked with
> python-neutronclient, and it had been from inside the library itself.
>
> This was my first experience using it "on the outside" and it was pretty
> tough - so I'm going to try and look into how we can improve the
> docstrings for the client object, to make it a bit easier to figure out.
>
> Thoughts?
>
> --
> Sean M. Collins
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140210/5c621f59/attachment.html>