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