#### `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

`Connection()`  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',
                                              username='user',
                                              password='password')
    connection.login()

----

##### 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