[diaspy.git] / manual / people.markdown

#### `User()` object

This object is used to represent a D\* user.

----

##### `User()` object -- getting user data

You have to know either GUID or *handle* of a user. 
Assume that *1234567890abcdef* and *otheruser@pod.example.com* point to 
the same user.

    >>> c = diaspy.connection.Connection('https://pod.example.com', 'foo', 'bar')
    >>> 
    >>> user_guid = diaspy.people.User(c, guid='1234567890abcdef')
    >>> user_handle = diaspy.people.User(c, handle='otheruser@pod.example.com')

Now, you have two `User` objects containing the data of one user.

The object is subscriptable so you can do like this:

    >>> user_guid['handle']
    'otheruser@pod.example.com'
    >>> 
    >>> user_handle['guid']
    '1234567890abcdef'

`User` object contains following items in its `data` dict:

* `id`, `str`, id of the user;
* `guid`, `str`, guid of the user;
* `handle`, `str`, D\* id (or handle) of the user;
* `name`, `str`, name of the user;
* `avatar`, `dict`, links to avatars of the user;

>   **Historical note:** the above values were changed in version `0.3.0`.  
>   `diaspora_id` became `handle` and `image_urls` became `avatar` to have more
>   consistent results.
>   This is because we can get only user data and this returns dict containing 
>   `handle` and `avatar` and not `diaspora_id` and `image_urls`. 
>   Users who migrated from version `0.2.x` and before to version `0.3.0` had to
>   update their software.

Also `User` object contains a stream for this user.

* `stream`, `diaspy.streams.Outer`, stream of the user (provides all methods of generic stream);

====


#### `Contacts()` object

This is object abstracting list of user's contacts. 
It may be slightly confusing to use and reading just docs could be not enough. 

The only method of this object is `get()` and its only parameter is `set` which 
is optional (defaults to empty string).  
If called without specifying `set` `get()` will return list of users (`User` objects) 
who are in your aspects.

Optional `set` parameter can be either `all` or `only_sharing`. 
If passed as `only_sharing` it will return only users who are not in your aspects but who share 
with you - which means that you are in their aspects.
If passed as `all` it will return list of *all* your contacts - those who are in your aspects and 
those who are not.


To sum up: people *who you share with* are *in* your aspects. People *who share with you* have you in 
their aspects. These two states can be mixed.


----

###### Manual for `diaspy`, written by Marek Marecki
Commit	Line	Data
beaa09fb MM	1	#### `User()` object
	2
	3	This object is used to represent a D\* user.
	4
	5	----
	6
6d8d47ce	7	##### `User()` object -- getting user data
beaa09fb	8
6d8d47ce MM	9	You have to know either GUID or handle of a user.
6d8d47ce MM	10	Assume that 1234567890abcdef and otheruser@pod.example.com point to
beaa09fb MM	11	the same user.
beaa09fb MM	12
beaa09fb MM	13	>>> c = diaspy.connection.Connection('https://pod.example.com', 'foo', 'bar')
beaa09fb MM	14	>>>
6d8d47ce MM	15	>>> user_guid = diaspy.people.User(c, guid='1234567890abcdef')
6d8d47ce MM	16	>>> user_handle = diaspy.people.User(c, handle='otheruser@pod.example.com')
beaa09fb	17
6d8d47ce	18	Now, you have two `User` objects containing the data of one user.
beaa09fb MM	19
	20	The object is subscriptable so you can do like this:
	21
6d8d47ce	22	>>> user_guid['handle']
beaa09fb MM	23	'otheruser@pod.example.com'
	24	>>>
	25	>>> user_handle['guid']
6d8d47ce	26	'1234567890abcdef'
beaa09fb	27
6d8d47ce	28	`User` object contains following items in its `data` dict:
beaa09fb MM	29
	30	* `id`, `str`, id of the user;
	31	* `guid`, `str`, guid of the user;
6d8d47ce MM	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;
a8fdc14a	35
6d8d47ce MM	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.
a8fdc14a	43
6d8d47ce	44	Also `User` object contains a stream for this user.
beaa09fb	45
6d8d47ce	46	* `stream`, `diaspy.streams.Outer`, stream of the user (provides all methods of generic stream);
beaa09fb	47
d589deff MM	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).
6d8d47ce	58	If called without specifying `set` `get()` will return list of users (`User` objects)
d589deff MM	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
beaa09fb MM	72	----
	73
	74	###### Manual for `diaspy`, written by Marek Marecki