manual/people.markdown

   1 #### `User()` object
   2
   3 This object is used to represent a D\* user.
   4
   5 ----
   6
   7 ##### `User()` object -- getting user data
   8
   9 You have to know either GUID or *handle* of a user.
  10 Assume that *1234567890abcdef* and *otheruser@pod.example.com* point to
  11 the same user.
  12
  13     >>> c = diaspy.connection.Connection('https://pod.example.com', 'foo', 'bar')
  14     >>>
  15     >>> user_guid = diaspy.people.User(c, guid='1234567890abcdef')
  16     >>> user_handle = diaspy.people.User(c, handle='otheruser@pod.example.com')
  17
  18 Now, you have two `User` objects containing the data of one user.
  19
  20 The object is subscriptable so you can do like this:
  21
  22     >>> user_guid['handle']
  23     'otheruser@pod.example.com'
  24     >>>
  25     >>> user_handle['guid']
  26     '1234567890abcdef'
  27
  28 `User` object contains following items in its `data` dict:
  29
  30 * `id`, `str`, id of the user;
  31 * `guid`, `str`, guid of the user;
  32 * `handle`, `str`, D\* id (or handle) of the user;
  33 * `name`, `str`, name of the user;
  34 * `avatar`, `dict`, links to avatars of the user;
  35
  36 >   **Historical note:** the above values were changed in version `0.3.0`.
  37 >   `diaspora_id` became `handle` and `image_urls` became `avatar` to have more
  38 >   consistent results.
  39 >   This is because we can get only user data and this returns dict containing
  40 >   `handle` and `avatar` and not `diaspora_id` and `image_urls`.
  41 >   Users who migrated from version `0.2.x` and before to version `0.3.0` had to
  42 >   update their software.
  43
  44 Also `User` object contains a stream for this user.
  45
  46 * `stream`, `diaspy.streams.Outer`, stream of the user (provides all methods of generic stream);
  47
  48 ====
  49
  50
  51 #### `Contacts()` object
  52
  53 This is object abstracting list of user's contacts.
  54 It may be slightly confusing to use and reading just docs could be not enough.
  55
  56 The only method of this object is `get()` and its only parameter is `set` which
  57 is optional (defaults to empty string).
  58 If called without specifying `set` `get()` will return list of users (`User` objects)
  59 who are in your aspects.
  60
  61 Optional `set` parameter can be either `all` or `only_sharing`.
  62 If passed as `only_sharing` it will return only users who are not in your aspects but who share
  63 with you - which means that you are in their aspects.
  64 If passed as `all` it will return list of *all* your contacts - those who are in your aspects and
  65 those who are not.
  66
  67
  68 To sum up: people *who you share with* are *in* your aspects. People *who share with you* have you in
  69 their aspects. These two states can be mixed.
  70
  71
  72 ----
  73
  74 ###### Manual for `diaspy`, written by Marek Marecki