* Limited the column width of the manual files a little.
* etc.
-`Connection()` is the most low-level part of `diaspy` and provides everything
-what is needed to talk to a pod.
+`Connection()` is the most low-level part of `diaspy` and provides
+everything what is needed to talk to a pod.
-However, using only `Connection()` would be hard and cumberstone so there are
-other modules to aid you and you are strongly encouraged to use them.
+However, using only `Connection()` would be hard and cumberstone so
+there are other modules to aid you and you are strongly encouraged to
+use them.
----
##### Login procedure
-`Client()` object available in `diaspy` will login you automatically - provided
-you gave it valid pod, username and password.
-
-On the other hand, `Connection()` is more stupid and it will not log you in unless
-you explicitly order it to do so.
-Logging in with `Connection()` is done via `login()` method.
+`Connection()` will not log you in unless you explicitly order it to
+do so. Logging in with `Connection()` is done via `login()` method.
**Example:**
password `passphrase` because data passed to `login()` overrides data
passed directly to object.
-**Remember:** if you pass something to `login()` it will *override* credentials set when the
-connection was created.
-
+**Remember:** if you pass something to `login()` it will *override*
+credentials set when the connection was created.
----
##### Authentication
Authentication in Diaspora\* is done with *token*. It is a string
-which is passed to pod with several requests to prove you are who you are
-pretending to be.
+which is passed to pod with several requests to prove you are who you
+are pretending to be.
`Connection` provides you with a method to fetch this token and perform
various actions on your account.
You can save time by using `get_token()` method.
It will check whether the token had been already fetched and reuse it.
This is especially useful on slow or unstable connections.
-`get_token()` has an optional `fetch` argument (it is of `bool` type, by default `False`)
-which will tell it to fetch new token if you find suitable.
-
-However, recommended way of dealing with token is to use `repr()` function on
-`Connection` object. This will allow of your programs to be future-proof because if
-for any reason we will change the way in which authorization is handled `get_token()`
-method may be gone -- `repr()` will stay.
+`get_token()` has an optional `fetch` argument (it is of `bool` type,
+by default `False`) which will tell it to fetch new token if you find
+suitable.
+
+However, recommended way of dealing with token is to use `repr()`
+function on `Connection` object. This will allow of your programs to be
+future-proof because if for any reason we will change the way in which
+authorization is handled `get_token()` method may be gone -- `repr()`
+will stay.
Here is how you should create your auth flow:
##### Initialization
-First argument is always `Connection` object stored in `self._connection`.
-Parameters specific to each model go after it.
+First argument is always `Connection` object stored in
+`self._connection`. Parameters specific to each model go after it.
-If model requires some king of id (guid, conversation id, post id) it is simply `id`.
+If model requires some king of id (guid, conversation id, post id) it is
+ simply `id`.
#### `Notifications()` object
-In order to get list of notifications use `diaspy.notifications.Notifications()` object.
-It support iteration and indexing.
+In order to get list of notifications use
+`diaspy.notifications.Notifications()` object. It support iteration and
+indexing.
-When creating new instance of `Notifications` only `Connection` object is needed.
+When creating new instance of `Notifications` only `Connection` object
+is needed.
#### Methods
##### `get()`
-This is slightly more advanced then `last()`. It allows you to specify how many
-notifications per page you want to get and which page you want to recieve.
+This is slightly more advanced then `last()`. It allows you to specify
+how many notifications per page you want to get and which page you want
+to recieve.
+
+##### `update()`
+
+This will insert new notifications to the object.
+
+##### `more()`
+
+This will append older notifications to the object.
+
+
----
#### `Notification()` model
-Single notification (it should be obvious that it requires object of its own) is located in
-`diaspy.models.Notification()`. It has several methods you can use.
+Single notification (it should be obvious that it requires object of its
+ own) is located in `diaspy.models.Notification()`. It has several
+methods you can use.
##### 1. `who()`
-This method will return list of guids of the users who caused you to get this notification.
+This method will return list of guids of the users who caused you to get
+ this notification.
##### 2. `when()`
##### 3. `mark()`
-To mark notification as `read` or `unread`. It has one parameter - `unread` which is boolean.
+To mark notification as `read` or `unread`. It has one parameter -
+`unread` which is boolean.
-Also, you can use `str()` and `repr()` on the `Notification()` and you will get nice
-string.
+Also, you can use `str()` and `repr()` on the `Notification()` and you
+will get nice string.
----
Also `User` object contains a stream for this user.
-* `stream`, `diaspy.streams.Outer`, stream of the user (provides all methods of generic stream);
+* `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.
+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.
+
+#### Methods
+
+##### `get()`
+
+The `set` parameter 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.
+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.
+
+The `page` parameter expects a `int` as page number. By default the
+`get()` method will only load page `1`. If the given page number doesn't
+ have any contacts it will return a empty `list`.
+
+##### `addAspect()`
+
+The `addAspect()` method only requires a name (`str`) for the new aspect
+ as a parameter. The second parameter wich is optional
+ (*default `False`*) sets if contacts in that aspect are visible to each
+ other, the parameter should be a `bool`.
+
+If succesfull it will return the `id` for the new aspect.
+
+##### `deleteAspect()`
+
+This deletes a aspect with given **aspect** `id`. As parameter it
+expects a aspect `id`.
+
+##### `add()`
+This adds the given **user** `id` to the given **aspect** `id`. First
+parameter **aspect** `id`, second parameter **user** `id`.
-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.
+##### `remove()`
+This removes the given **user** `id` from the given **aspect** `id`.
+First parameter **aspect** `id`, second parameter **user** `id`.
----
`Post` object is used to represent a post on D\*.
+#### Methods
+
+##### `fetch()`
+
+Use this method to get or update the post. As first parameter a `bool`
+can be given wich if is `True` will also fetch comments, default it
+won't.
+
+##### `data()`
+
+Set or get the current data for this post. If this method is called
+without any argument it will return a dict with the post data. To set
+post data for this post use the post data to set as first parameter
+(normaly you don't want to set this manualy).
+
+##### `like()`
+
+Likes this post.
+
+##### `reshare()`
+
+Reshares this post.
+
+##### `comment()`
+
+Comments on this post. First parameter a `str` with the text to comment.
+
+##### `vote_poll()`
+
+If the post contains a poll, you can vote on it by calling this method
+with as parameter the poll **answer** `id`.
+
+##### `hide()`
+
+Hides this post.
+
+##### `mute()`
+
+Blocks the post author.
+
+##### `subscribe()`
+
+Subscribes to this post (receive notifications on this post and its
+comments).
+
+##### `unsubscribe()`
+
+Unsubscribes from this post if you don't want to receive any
+notifications about this post anymore.
+
+##### `report()`
+This function is `TODO`, it doesn't work yet.
+
+##### `delete()`
+
+If you own this post you can delete it by calling this method.
+
+##### `delete_comment()`
+
+If you commented on this post and want to delete the comment call this
+method with as paramter the **comment** `id`.
+
+##### `delete_like()`
+
+If you liked this post you can call `delete_like()` to undo that.
+
+##### `author()`
+
+By default it returns the **author** `name`. As parameter you can give
+another key like **`id`**, **`guid`**, **`diaspora_id`** or
+**`avatar`**.
+
----
##### Posting
Posting is done through a `Stream` object method `post()`.
-It supports posting just text, images or text and images.
+It supports posting just text, images, a poll and a combination of those.
+
+Additional you can set the provider name displayed in the post (wich can
+ be your application it's name.) by setting the `provider_display_name`
+ parameter wich expects a `str`.
`Stream().post()` returns `Post` object referring to the post
which have just been created.
It will return `Post` you have just created.
+##### Poll
+
+If you want to post a poll you have to provide the following:
+
+* A `str` as the `poll_question` parameter wich will represent the poll
+question.
+* A `list` with strings as the `poll_answers` parameter wich represent
+the poll options.
##### Posting images
`post()` has two very similar arguments used for posting photos.
They are `photos` - which takes id and `photo` - which takes filename.
-You can post images using either of them. Even passing them side by side
-is accepted but remember that `photos` will overwrite data set by `photo`.
+You can post images using either of them. Even passing them side by side
+ is accepted but remember that `photos` will overwrite data set by
+ `photo`.
Example #1: using `photo`
The effect will be the same.
-To either call you can append `text` argument which will be posted alongside
-the image.
+To either call you can append `text` argument which will be posted
+alongside the image.
----
#### `Search()` object
-Searching is useful only if it comes to searching for users.
-Tags can be searched for just by creating `Tag` object using
-tag-name as an arument.
+Searching is useful only if it comes to searching for users or tags.
----
##### `lookup_user()`
-This method is used for telling a pod "Hey, I want this user searchable via you!"
+This method is used for telling a pod "Hey, I want this user searchable
+via you!"
##### `user()`
-This method will return you a list of dictionaries containg data of users whose
-handle conatins query you have used.
+This method will return you a list of dictionaries containg data of
+users whose handle conatins query you have used.
+
+##### `tags()`
+
+This method will return you a `list` with with `str`'s (tag names). As
+first parameter it expects a `str` representing the search phrase. The
+second parameter `limit` is optional, it can be set to increase or
+decrease the maximum returned results. The default for the `limit`
+parameter is `10`.
#### `Stream()` object
This object is used to represent user's stream on D\*.
-It is returned by `Client()`'s method `get_stream()` and
-is basically a list of posts.
+It is basically a list of posts.
----
username='foo',
password='bar')
c.login()
- stream = diaspy.models.Stream(c)
+ stream = diaspy.streams.Stream(c)
-Now you have a stream filled with posts (if any can be found on user's stream).
+Now you have a stream filled with posts (if any can be found on user's
+stream).
+
+Other streams you can use are `Activity()`, `Aspects()`, `Commented()`,
+`Liked()`, `Mentions()`, `FollowedTags()` and `Tag()`.
+
+Example: `stream = diaspy.streams.Activity(c)`
----
##### `fill()`, `update()` and `more()`
-When you want to refresh stream call it's `fill()` method. It will overwrite old stream
-contents.
+When you want to refresh stream call it's `fill()` method. It will
+overwrite old stream contents.
-On the contrary, `update()` will get a new stream but will not overwrite old stream saved
-in the object memory. It will append every new post to the old stream.
+On the contrary, `update()` will get a new stream but will not overwrite
+ old stream saved in the object memory. It will append every new post to
+ the old stream.
-`more()` complements `update()` it will fetch you older posts instead of newer ones.
+`more()` complements `update()` it will fetch you older posts instead of
+ newer ones.
----
len(stream)
10
-When you want to iterate over a stream (e.g. when you want to print first *n* posts on
-the stream) you can do it in two ways.
+When you want to iterate over a stream (e.g. when you want to print
+first *n* posts on the stream) you can do it in two ways.
First, using `len()` and `range()` functions.
##### Posting data to stream
-This is described in [`posting`](./posting.markdown) document in this manual.
+This is described in [`posting`](./posting.markdown) document in this
+manual.
----
##### `purge()`
-This will scan stream for nonexistent posts (eg. deleted) and remove them.
+This will scan stream for nonexistent posts (eg. deleted) and remove
+them.
----
projects / diaspy.git / commitdiff