obspy/obspy — pull request #876 by bmorg (2014-09-05 12:53:17+00:00)
Title: Easy-to-use SeedLink interface

I have created a new interface to the `obspy.seedlink` module (and now finally finished writing the corresponding docs). It drastically simplifies connecting to SeedLink servers:

```python
from obspy.seedlink.easyseedlink import EasySeedLinkClient

# Subclass the client class
class MyClient(EasySeedLinkClient):
# Override the callback for data reception
def on_data(self, trace):
print 'Received trace:'
print trace
print

# Initialize and connect the client
client = MyClient('geofon.gfz-potsdam.de')

# Use it to e.g. fetch the INFO:ID response
client.get_info('ID')
# Returns u'\n\n'

# Select a stream...
client.select_stream('BW', 'MANZ', 'EHZ')

# ... and start streaming data
client.loop()

"""
Output:

Received trace:
BW.MANZ..EHZ | 2014-09-05T12:24:25.775000Z - 2014-09-05T12:24:27.770000Z | 200.0 Hz, 400 samples

Received trace:
BW.MANZ..EHZ | 2014-09-05T12:24:27.775000Z - 2014-09-05T12:24:29.610000Z | 200.0 Hz, 368 samples

Received trace:
BW.MANZ..EHZ | 2014-09-05T12:24:29.615000Z - 2014-09-05T12:24:31.570000Z | 200.0 Hz, 392 samples

...
```

There is also a shortcut function to avoid the subclassing:

```python
from obspy.seedlink.easyseedlink import create_client

# Define a function to handle the received data
def handle_data(trace):
print 'Received trace:'
print trace
print

# Pass it to the create_client() function
client = create_client('geofon.gfz-potsdam.de', on_data=handle_data)

# The client can then be used as above
client.select_stream('BW', 'MANZ', 'EHZ')
client.loop()
```

More importantly, I have tried to document the usage extensively. I have uploaded the rendered documentation for review: [tutorial](http://bmorg.github.io/obspy/doc-easyseedlink/tutorial/code_snippets/easyseedlink.html), [module](http://bmorg.github.io/obspy/doc-easyseedlink/packages/autogen/obspy.seedlink.easyseedlink.html), [class](http://bmorg.github.io/obspy/doc-easyseedlink/packages/autogen/obspy.seedlink.easyseedlink.EasySeedLinkClient.html).

I still have some problems regarding documentation:
* Is there a generic way to link to the tutorial? It is linked in the class docstring. Should I just use `../../tutorial`?
* The *Attributes* section of the class shows `__dict__`, `__doc__`, `__module__` and `__weakref__`,
which isn't very useful. But I guess that happens for all classes? Can I turn it off?

Also I am thinking it might be better to make the callbacks private, i.e. `on_data()` -> `_on_data()`, to indicate that these should never be called from the outside.

Another issue is testing. This would probably require a mock SeedLink server...?

Opinions?