service roots not listed in pydoc

[Robert Collins]

 affects launchpad
 done

launchpadlib.launchpad contains STAGING_SERVICE_ROOT etc, but they are
not listed in pydoc launchpadlib.launchpad, which makes it annoying to
figure out what ones to use etc.

[Leonard Richardson (leonardr)]

The constants in launchpadlib.launchpad are imported from launchpadlib.uris for backwards compatibility. Please use the more complete set of constants declared in launchpadlib.uris.

What would you like to see in the pydoc?

[Robert Collins (lifeless)]

On Thu, Apr 15, 2010 at 9:37 PM, Leonard Richardson <
<email address hidden>> wrote:

> The constants in launchpadlib.launchpad are imported from
> launchpadlib.uris for backwards compatibility. Please use the more
> complete set of constants declared in launchpadlib.uris.
>

Ok, cool. The sample code on dev.launchpad.net still imports from
launchpadlib.launchpad - I'd consider updating those docs as part of fixing
this bug.

> What would you like to see in the pydoc?
>

It currently says:
=>
    The code in this module lets users say "edge" when they mean
    "https://api.edge.launchpad.net/".
...
DATA
__all__ = ['lookup_service_root', 'lookup_web_root']
=>

I think it should be comprehensive enough to make things discoverable.
Something like, fo the static top text:
The code in this module lets users provide a short name that is expanded
into a complete URL. For instance, "staging" is expanded to "
https://api.staging.launchpad.net/". The available short names can be seen
by::
>>> uris.short_names.keys()

And you should include short_names (or whatever the actual thing to use to
discover names is), in __all__, because __all__ filters what pydoc shows.

Secondly, the python constants like EDE_SERVICE_ROOT, should be similarly
treated: "There are named constants for use in python, which match the short
names. These are usually named as ${host}_SERVICE_ROOT, for instance,
EDGE_SERVICE_ROOT, except for the production instance, which is not called
PRODUCTION_SERVICE_ROOT, rather it is called LPNET_SERVICE_ROOT.

basically, you shouldn't need to look at the source code for the module to
learn anything about it which you can be reasonably expected to want to know
as a consumer of its API.

Cheers,
Rob

[Leonard Richardson (leonardr)]

I am confused. There shouldn't be any sample code on dev.launchpad.net (and I can't find any) since that's the wiki about developing Launchpad itself. I think you mean https://help.launchpad.net/API/launchpadlib, but the sample code there doesn't mention *SERVICE_ROOT except in a section "If this complains that 'staging' isn't a URL, then you're not running the most up-to-date launchpadlib..." Are we okay here or is there still some out-of-date information on the wiki?

Thanks for the pydoc help.

[Robert Collins (lifeless)]

Sorry yes, help.launchpad.net: https://help.launchpad.net/API/Examples

[Leonard Richardson (leonardr)]

Ah. Not that this is really what the bug is about, but i've removed all references to EDGE_SERVICE_ROOT from API/Examples.