Update to version 0.4.2

[diaspy.git] / manual / connection.markdown

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