From cc8bef9e628456ee278f59521754c7570684e6cf Mon Sep 17 00:00:00 2001 From: CYBERDEViLNL Date: Thu, 1 Nov 2018 23:35:43 +0100 Subject: [PATCH] * Manual update. * Limited the column width of the manual files a little. --- manual/connection.markdown | 42 ++++++++-------- manual/models.markdown | 7 +-- manual/notifications.markdown | 38 ++++++++++---- manual/people.markdown | 57 ++++++++++++++++----- manual/posting.markdown | 95 +++++++++++++++++++++++++++++++++-- manual/search.markdown | 19 ++++--- manual/streams.markdown | 35 ++++++++----- 7 files changed, 221 insertions(+), 72 deletions(-) diff --git a/manual/connection.markdown b/manual/connection.markdown index dba2790..24f6379 100644 --- a/manual/connection.markdown +++ b/manual/connection.markdown @@ -9,23 +9,20 @@ It is pushed around and used by various methods and other objects: * 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:** @@ -59,17 +56,16 @@ This code will result in connection with username `loser` and 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. @@ -80,13 +76,15 @@ Once a token is fetched there is no use for doing it again. 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: diff --git a/manual/models.markdown b/manual/models.markdown index 910ca26..720e4c9 100644 --- a/manual/models.markdown +++ b/manual/models.markdown @@ -5,7 +5,8 @@ Design of models in `diaspy` follow few simple rules. ##### 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`. diff --git a/manual/notifications.markdown b/manual/notifications.markdown index 4312865..8de7832 100644 --- a/manual/notifications.markdown +++ b/manual/notifications.markdown @@ -1,9 +1,11 @@ #### `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 @@ -13,19 +15,32 @@ This method will return you last five notifications. ##### `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()` @@ -33,12 +48,13 @@ This method will return UTC time when you get the notification. ##### 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. ---- diff --git a/manual/people.markdown b/manual/people.markdown index 88f18e0..de31edc 100644 --- a/manual/people.markdown +++ b/manual/people.markdown @@ -43,7 +43,8 @@ The object is subscriptable so you can do like this: 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); ==== @@ -51,23 +52,55 @@ Also `User` object contains a stream for this user. #### `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`. ---- diff --git a/manual/posting.markdown b/manual/posting.markdown index ca76707..e82c126 100644 --- a/manual/posting.markdown +++ b/manual/posting.markdown @@ -2,12 +2,88 @@ `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. @@ -22,6 +98,14 @@ If you want to post just text you should call `post()` method with 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 @@ -37,8 +121,9 @@ sent by request. This is handled by `post()` method. `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` @@ -55,8 +140,8 @@ Example #2: using `photos` 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. ---- diff --git a/manual/search.markdown b/manual/search.markdown index 69bfa9e..af617f0 100644 --- a/manual/search.markdown +++ b/manual/search.markdown @@ -1,16 +1,23 @@ #### `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`. diff --git a/manual/streams.markdown b/manual/streams.markdown index 9c56936..e2a2674 100644 --- a/manual/streams.markdown +++ b/manual/streams.markdown @@ -1,8 +1,7 @@ #### `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. ---- @@ -15,21 +14,29 @@ this is required by `Stream()`'s constructor. 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. ---- @@ -40,8 +47,8 @@ Stream's length can be checked by calling `len()` on it. 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. @@ -58,7 +65,8 @@ Second, iterating directly over the stream contents: ##### 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. ---- @@ -71,7 +79,8 @@ This will remove all posts from visible stream. ##### `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. ---- -- 2.25.1