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
  13 everything what is needed to talk to a pod.
  14
  15 However, using only `Connection()` would be hard and cumberstone so
  16 there are other modules to aid you and you are strongly encouraged to
  17 use them.
  18
  19
  20 ----
  21
  22 ##### Login procedure
  23
  24 `Connection()`  will not log you in unless you explicitly order it to
  25 do so. Logging in with `Connection()` is done via `login()` method.
  26
  27 **Example:**
  28
  29     connection = diaspy.connection.Connection(pod='https://pod.example.com',
  30                                               username='user',
  31                                               password='password')
  32     connection.login()
  33
  34 ----
  35
  36 ##### Authentication
  37
  38 Authentication in Diaspora\* is done with *token*. It is a string
  39 which is passed to pod with several requests to prove you are who you
  40 are pretending to be.
  41
  42 `Connection` provides you with a method to fetch this token and perform
  43 various actions on your account.
  44 This method is called `_fetchtoken()`.
  45 It will try to download a token for you.
  46
  47 Once a token is fetched there is no use for doing it again.
  48 You can save time by using `get_token()` method.
  49 It will check whether the token had been already fetched and reuse it.
  50 This is especially useful on slow or unstable connections.
  51 `get_token()` has an optional `fetch` argument (it is of `bool` type,
  52 by default `False`) which will tell it to fetch new token if you find
  53 suitable.
  54
  55 However, recommended way of dealing with token is to use `repr()`
  56 function on `Connection` object. This will allow of your programs to be
  57 future-proof because if for any reason we will change the way in which
  58 authorization is handled `get_token()` method may be gone -- `repr()`
  59 will stay.
  60
  61 Here is how you should create your auth flow:
  62
  63     connection = diaspy.connection.Connection(...)
  64     connection.login()
  65
  66     token = repr(connection)
  67
  68
  69 ----
  70
  71 ##### Note for developers
  72
  73 If you want to write your own interface or client for D\*
  74 `Connection()` is the only object you need.
  75
  76 ----
  77
  78 ###### Manual for `diaspy`, written by Marek Marecki