manual/connection.markdown

   1 #### `Connection()` object
   2
   3 This is the object that is used by `diaspy`'s internals.
   4 It is pushed around and used by various methods and other objects:
   5
   6 *   `Post()` and `Conversation()` objects require it to authenticate and
   7     do their work,
   8 *   streams use it for getting their contents,
   9 *   etc.
  10
  11
  12 `Connection()` is the most low-level part of `diaspy` and provides everything
  13 what is needed to talk to a pod.
  14
  15 However, using only `Connection()` would be hard and cumberstone so there are
  16 other modules to aid you and you are strongly encouraged to use them.
  17
  18
  19 ----
  20
  21 ##### Login procedure
  22
  23 `Client()` object available in `diaspy` will login you automatically - provided
  24 you gave it valid pod, username and password.
  25
  26 On the other hand, `Connection()` is more stupid and it will not log you in unless
  27 you explicitly order it to do so.
  28 Logging in with `Connection()` is done via `login()` method.
  29
  30 **Example:**
  31
  32     connection = diaspy.connection.Connection(pod='https://pod.example.com')
  33     connection.login('user', 'password')
  34
  35     OR
  36
  37     connection = diaspy.connection.Connection(pod='https://pod.example.com',
  38                                               username='user',
  39                                               password='password')
  40     connection.login()
  41
  42
  43 In the example above two ways of logging in were shown.
  44 In the first one only *pod* is passed to the object and
  45 *username* and *password* were passed to `login()` method.
  46
  47 In the second one everything is passed directly to the object being
  48 created and `login()` is called without any arguments.
  49
  50 Both ways are valid and will result in exactly the same connection.
  51 But consider the following example:
  52
  53     connection = diaspy.connection.Connection(pod='https://pod.example.com',
  54                                               username='user',
  55                                               password='password')
  56     connection.login(username='loser', password='passphrase')
  57
  58 This code will result in connection with username `loser` and
  59 password `passphrase` because data passed to `login()` overrides data
  60 passed directly to object.
  61
  62 **Remember:** if you pass something to `login()` it will *override* credentials set when the
  63 connection was created.
  64
  65
  66 ----
  67
  68 ##### Authentication
  69
  70 Authentication in Diaspora\* is done with *token*. It is a string
  71 which is passed to pod with several requests to prove you are who you are
  72 pretending to be.
  73
  74 `Connection` provides you with a method to fetch this token and perform
  75 various actions on your account.
  76 This method is called `_fetchtoken()`.
  77 It will try to download a token for you.
  78
  79 Once a token is fetched there is no use for doing it again.
  80 You can save time by using `get_token()` method.
  81 It will check whether the token had been already fetched and reuse it.
  82 This is especially useful on slow or unstable connections.
  83 `get_token()` has an optional `fetch` argument (it is of `bool` type, by default `False`)
  84 which will tell it to fetch new token if you find suitable.
  85
  86 However, recommended way of dealing with token is to use `repr()` function on
  87 `Connection` object. This will allow of your programs to be future-proof because if
  88 for any reason we will change the way in which authorization is handled `get_token()`
  89 method may be gone -- `repr()` will stay.
  90
  91 Here is how you should create your auth flow:
  92
  93     connection = diaspy.connection.Connection(...)
  94     connection.login()
  95
  96     token = repr(connection)
  97
  98
  99 ----
 100
 101 ##### Note for developers
 102
 103 If you want to write your own interface or client for D\*
 104 `Connection()` is the only object you need.
 105
 106 ----
 107
 108 ###### Manual for `diaspy`, written by Marek Marecki