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
  47 methods of generic stream);
  48
  49 ====
  50
  51
  52 #### `Contacts()` object
  53
  54 This is object abstracting list of user's contacts.
  55 It may be slightly confusing to use and reading just docs could be not
  56 enough.
  57
  58
  59 #### Methods
  60
  61 ##### `get()`
  62
  63 The `set` parameter is optional (defaults to empty string).
  64 If called without specifying `set` `get()` will return list of users
  65 (`User` objects) who are in your aspects.
  66
  67 Optional `set` parameter can be either `all` or `only_sharing`.
  68 If passed as `only_sharing` it will return only users who are not in
  69 your aspects but who share with you - which means that you are in their
  70 aspects. If passed as `all` it will return list of *all* your contacts -
  71  those who are in your aspects and those who are not.
  72
  73 To sum up: people *who you share with* are *in* your aspects. People
  74 *who share with you* have you in their aspects. These two states can be
  75 mixed.
  76
  77 The `page` parameter expects a `int` as page number. By default the
  78 `get()` method will only load page `1`. If the given page number doesn't
  79  have any contacts it will return a empty `list`.
  80
  81 ##### `addAspect()`
  82
  83 The `addAspect()` method only requires a name (`str`) for the new aspect
  84  as a parameter. The second parameter wich is optional
  85  (*default `False`*) sets if contacts in that aspect are visible to each
  86  other, the parameter should be a `bool`.
  87
  88 If succesfull it will return the `id` for the new aspect.
  89
  90 ##### `deleteAspect()`
  91
  92 This deletes a aspect with given **aspect**  `id`. As parameter it
  93 expects a aspect `id`.
  94
  95 ##### `add()`
  96
  97 This adds the given **user** `id` to the given **aspect** `id`. First
  98 parameter **aspect** `id`, second parameter **user** `id`.
  99
 100 ##### `remove()`
 101
 102 This removes the given **user** `id` from the given **aspect** `id`.
 103 First parameter **aspect** `id`, second parameter **user** `id`.
 104
 105 ----
 106
 107 ###### Manual for `diaspy`, written by Marek Marecki