Comment 2 for bug 562833

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