manual/connection.mdown

   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 loggin in to pod and other stuff,
   9
  10
  11 `Connection()` is the most low-level part of `diaspy` and provides everything
  12 what is needed to talk to a pod.
  13
  14 However, using only `Connection()` would be hard and cumberstone so there are
  15 other modules to aid you and you are strongly encouraged to use them.
  16
  17
  18 ----
  19
  20 ##### Login procedure
  21
  22 `Client()` object available in `diapsy` will login you automatically - provided
  23 you gave it valid pod, username and password.
  24
  25 On the other hand, `Connection()` is more stupid and it will not log you in unless
  26 you explicitly order it to do so.
  27 Logging in with `Connection()` is done via `login()` method.
  28
  29 **Example:**
  30
  31     connection = diaspy.connection.Connection(pod='https://pod.example.com')
  32     connection.login('user', 'password')
  33
  34     OR
  35
  36     connection = diaspy.connection.Connection(pod='https://pod.example.com',
  37                                               username='user',
  38                                               password='password')
  39     connection.login()
  40
  41
  42 In the example above two ways of logging in were shown.
  43 In the first one only *pod* is passed to the object and
  44 *username* and *password* were passed to `login()` method.
  45
  46 In the second one everything is passed directly to the object being
  47 created and `login()` is called without any arguments.
  48
  49 Both ways are valid and will result in exactly the same connection.
  50 But consider the following example:
  51
  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 not only *override* but
  63 also *overwrite* the username and password!
  64
  65
  66 ----
  67
  68 ##### Switching pods
  69
  70 `Connection()` provides functionality for switching pods on the fly.
  71 This can be achieved with `podswitch()` method.
  72
  73 If login to a new pod is successful your connection is just changed
  74 overwritten but if it fails everything else also fails and the current
  75 connection is broken.
  76
  77
  78 ----
  79
  80 If you want to write your own interface or client for D\*
  81 `Connection()` will be the only object you need.
  82