Repository: googleapis/google-cloud-python

Issue:
Pubsub surface uses long imports
In the pubsub surface docs page, we use long-style imports instead of the shortcut ones, that is:

``` python
from gcloud.pubsub.topic import Topic
topic = Topic('topic_name')
```

instead of

``` python
from gcloud import pubsub
topic = pubsub.Topic('topic_name')
```

or 

``` python
from gcloud.pubsub import Topic
topic = Topic('topic_name')
```



Discussion:
@tseaver What is the overall future of this document?

Dunno.  In my mind, this kind of overview is useful for developers coming to the library fresh.

I actually prefer the long imports, myself, as being more "explicit" than the convenience façades / shortcuts:  they make it obvious where to go looking in the code when chasing bugs.

> Dunno. In my mind, this kind of overview is useful for developers coming to the library fresh.

I agree with this. I think the "here's how to do common stuff" is really helpful.

> I actually prefer the long imports, myself, as being more "explicit" than the convenience façades ...

As you sort of hint, shorter is typically more convenient... I think we should optimize for that over all else.

We don't want users to have to go look in code chasing for bugs. That's what documentation is for. 

Alex Martelli really impacted me at PyCon 2013 when he [said](https://www.youtube.com/watch?v=yo4Uqq7NXQc&t=15m35s):

> Don't take the fact that you are open source as an excuse to not give a good tutorial, example cases and a reference. In other words, no cowboy coding please

(See [slide 13](http://www.aleax.it/pycon13_geige.pdf).)

I'm talking about chasing bugs in _our_ code -- having to unwind aliases everywhere makes that extra hard.

I was too. Why would we want our users to have to find our bugs?

Sure... so I still think that if we're putting convenience for the user first, the aliases are the better choice... Do we have any idea of _how_ extra hard this becomes given aliases? If it becomes ridiculous, then I can let it drop. If it's not all that bad, ... I would vote that the convenience outweighs the extra work and I'd like to take it on...

@dhermes one of the major wins for open-sourcing _any_ library is that users help us find the bugs.

@jgeewax I don't feel super-strongly about it, but I really don't share the "save a couple of characters in an import statement" sensibility: the only place that seems like a win to me is at the interactive prompt:  I don't think many of our users are going to be typing imports directly there.  I can live with it in the docs, though.

@jgeewax would it be better if the "short form" was the only public / API version?  I.e., we could rename the sub-modules (`topic` -> `_topic`) to indicate that they are _not_ part of the API, and that clients should therefore not rely on them.

Big time -1 on that suggestion

Having more than one canonical place to import things is a Zen of Python violation:  if the short form is the one we document everywhere, then why keep the long form as a public API?  (I _like_ the long form myself, but am trying to figure out what @jgeewax is looking for here).

If the short form is just a convenience (e.g., for use at the REPL prompt), then the documentation should probably show the long form to indicate that it is the supported / public API form.

I definitely understand that we're strictly violating the ZoP... However we're also violating it in a few other places (ie, `pubsub/__init__.py` imports stuff from `pubsub/api.py` -- so we could use it from either spot, right?) That said, this isn't to say that breaking the rule in one place means we should always break it in another...

Put simply: I think the usefulness and convenience of shorter imports is worth taking on the future potential issues of "more than one way to do things".

Here's an example of BDFL doing the same thing to resolve https://code.google.com/p/appengine-ndb-experiment/issues/detail?id=102 --> https://code.google.com/p/appengine-ndb-experiment/source/detail?r=ed282c7ebf0b77882229e8a75f5340d5fa88d838&path=/ndb/__init__.py

OK, I'll just update the docs (once #842 lands).


Resolving patch:
diff --git a/gcloud/pubsub/__init__.py b/gcloud/pubsub/__init__.py
--- a/gcloud/pubsub/__init__.py
+++ b/gcloud/pubsub/__init__.py
@@ -32,6 +32,8 @@
 from gcloud.pubsub.api import list_subscriptions
 from gcloud.pubsub.api import list_topics
 from gcloud.pubsub.connection import Connection
+from gcloud.pubsub.subscription import Subscription
+from gcloud.pubsub.topic import Topic
 
 
 SCOPE = ('https://www.googleapis.com/auth/pubsub',


Test patch: