#### `Connection()` object

This is the object that is used by `diaspy`'s internals. It is pushed around and used by various methods and other objects:

- `Post()` and `Conversation()` objects require it to authenticate and do their work,
- streams use it for getting their contents,
- etc.

`Connection()` is the most low-level part of `diaspy` and provides everything what is needed to talk to a pod.

However, using only `Connection()` would be hard and cumberstone so there are other modules to aid you and you are strongly encouraged to use them.

##### Login procedure

`Client()` object available in `diaspy` will login you automatically - provided you gave it valid pod, username and password.

On the other hand, `Connection()` is more stupid and it will not log you in unless you explicitly order it to do so. Logging in with `Connection()` is done via `login()` method.

Example:

    connection = diaspy.connection.Connection(pod='https://pod.example.com')
    connection.login('user', 'password')

    OR

    connection = diaspy.connection.Connection(pod='https://pod.example.com',
                                              username='user',
                                              password='password')
    connection.login()

In the example above two ways of logging in were shown. In the first one only pod is passed to the object and username and password were passed to `login()` method.

In the second one everything is passed directly to the object being created and `login()` is called without any arguments.

Both ways are valid and will result in exactly the same connection. But consider the following example:

    connection = diaspy.connection.Connection(pod='https://pod.example.com',
                                              username='user',
                                              password='password')
    connection.login(username='loser', password='passphrase')

This code will result in connection with username `loser` and password `passphrase` because data passed to `login()` overrides data passed directly to object.

Remember: if you pass something to `login()` it will override credentials set when the connection was created.

##### Authentication

Authentication in Diaspora* is done with token. It is a string which is passed to pod with several requests to prove you are who you are pretending to be.

`Connection` provides you with a method to fetch this token and perform various actions on your account. This method is called `_fetchtoken()`. It will try to download a token for you.

Once a token is fetched there is no use for doing it again. You can save time by using `get_token()` method. It will check whether the token had been already fetched and reuse it. This is especially useful on slow or unstable connections. `get_token()` has an optional `fetch` argument (it is of `bool` type, by default `False`) which will tell it to fetch new token if you find suitable.

However, recommended way of dealing with token is to use `repr()` function on `Connection` object. This will allow of your programs to be future-proof because if for any reason we will change the way in which authorization is handled `get_token()` method may be gone -- `repr()` will stay.

Here is how you should create your auth flow:

    connection = diaspy.connection.Connection(...)
    connection.login()

    token = repr(connection)

##### Note for developers

If you want to write your own interface or client for D* `Connection()` is the only object you need.

###### Manual for `diaspy`, written by Marek Marecki