manual/posting.markdown

   1 #### `Post()` object and posting
   2
   3 `Post` object is used to represent a post on D\*.
   4
   5 #### Methods
   6
   7 ##### `fetch()`
   8
   9 Use this method to get or update the post. As first parameter a `bool`
  10 can be given wich if is `True` will also fetch comments, default it
  11 won't.
  12
  13 ##### `data()`
  14
  15 Set or get the current data for this post. If this method is called
  16 without any argument it will return a dict with the post data. To set
  17 post data for this post use the post data to set as first parameter
  18 (normaly you don't want to set this manualy).
  19
  20 ##### `like()`
  21
  22 Likes this post.
  23
  24 ##### `reshare()`
  25
  26 Reshares this post.
  27
  28 ##### `comment()`
  29
  30 Comments on this post. First parameter a `str` with the text to comment.
  31
  32 ##### `vote_poll()`
  33
  34 If the post contains a poll, you can vote on it by calling this method
  35 with as parameter the poll **answer** `id`.
  36
  37 ##### `hide()`
  38
  39 Hides this post.
  40
  41 ##### `mute()`
  42
  43 Blocks the post author.
  44
  45 ##### `subscribe()`
  46
  47 Subscribes to this post (receive notifications on this post and its
  48 comments).
  49
  50 ##### `unsubscribe()`
  51
  52 Unsubscribes from this post if you don't want to receive any
  53 notifications about this post anymore.
  54
  55 ##### `report()`
  56 This function is `TODO`, it doesn't work yet.
  57
  58 ##### `delete()`
  59
  60 If you own this post you can delete it by calling this method.
  61
  62 ##### `delete_comment()`
  63
  64 If you commented on this post and want to delete the comment call this
  65 method with as paramter the **comment** `id`.
  66
  67 ##### `delete_like()`
  68
  69 If you liked this post you can call `delete_like()` to undo that.
  70
  71 ##### `author()`
  72
  73 By default it returns the **author** `name`. As parameter you can give
  74 another key like **`id`**,  **`guid`**,  **`diaspora_id`** or
  75 **`avatar`**. *Note*: parameter is expected to be a `str`.
  76
  77 ----
  78
  79 ##### Posting
  80
  81 Posting is done through a `Stream` object method `post()`.
  82 It supports posting just text, images, a poll and a combination of those.
  83
  84 Additional you can set the provider name displayed in the post (wich can
  85  be your application it's name.) by setting the `provider_display_name`
  86  parameter wich expects a `str`.
  87
  88 `Stream().post()` returns `Post` object referring to the post
  89 which have just been created.
  90
  91
  92 ##### Text
  93
  94 If you want to post just text you should call `post()` method with
  95 `text` argument.
  96
  97     stream.post(text='Your post.')
  98
  99 It will return `Post` you have just created.
 100
 101 ##### Poll
 102
 103 If you want to post a poll you have to provide the following:
 104
 105 * A `str` as the `poll_question` parameter wich will represent the poll
 106 question.
 107 * A `list` with strings as the `poll_answers` parameter wich represent
 108 the poll options.
 109
 110 ##### Posting images
 111
 112 Posting images, from back-end point of view, is a two-step process.
 113 First, you have to *upload* an image to the desired pod.
 114 This is done by `_photoupload()` method.
 115 It will return *id* of uploaded image.
 116
 117 Then you have to actually post your image and this is done by appending
 118 `photos` field containg the id of uploaded image to the data being
 119 sent by request. This is handled by `post()` method.
 120
 121 `post()` has two very similar arguments used for posting photos.
 122 They are `photos` - which takes id and `photo` - which takes filename.
 123
 124 You can post images using either of them. Even passing them side by side
 125  is accepted but remember that `photos` will overwrite data set by
 126  `photo`.
 127
 128
 129 Example #1: using `photo`
 130
 131
 132     stream.post(photo='./kitten-image.png')
 133
 134
 135 Example #2: using `photos`
 136
 137
 138     id = stream._photoupload(filename='./kitten-image.png')
 139     stream.post(photos=id)
 140
 141
 142 The effect will be the same.
 143 To either call you can append `text` argument which will be posted
 144 alongside the image.
 145
 146 ----
 147
 148 ###### Manual for `diaspy`, written by Marek Marecki