manual/posting.markdown

   1 #### `Post()` object and posting
   2
   3 `Post` object is used to represent a post on D\*.
   4
   5 ----
   6
   7 ##### Posting
   8
   9 Posting is done through a `Stream` object method `post()`.
  10 It supports posting just text, images or text and images.
  11
  12 `Stream().post()` returns `Post` object referring to the post
  13 which have just been created.
  14
  15
  16 ##### Text
  17
  18 If you want to post just text you should call `post()` method with
  19 `text` argument.
  20
  21     stream.post(text='Your post.')
  22
  23 It will return `Post` you have just created.
  24
  25
  26 ##### Posting images
  27
  28 Posting images, from back-end point of view, is a two-step process.
  29 First, you have to *upload* an image to the desired pod.
  30 This is done by `_photoupload()` method.
  31 It will return *id* of uploaded image.
  32
  33 Then you have to actually post your image and this is done by appending
  34 `photos` field containg the id of uploaded image to the data being
  35 sent by request. This is handled by `post()` method.
  36
  37 `post()` has two very similar arguments used for posting photos.
  38 They are `photos` - which takes id and `photo` - which takes filename.
  39
  40 You can post images using either of them. Even passing them side by side
  41 is accepted but remember that `photos` will overwrite data set by `photo`.
  42
  43
  44 Example #1: using `photo`
  45
  46
  47     stream.post(photo='./kitten-image.png')
  48
  49
  50 Example #2: using `photos`
  51
  52
  53     id = stream._photoupload(filename='./kitten-image.png')
  54     stream.post(photos=id)
  55
  56
  57 The effect will be the same.
  58 To either call you can append `text` argument which will be posted alongside
  59 the image.
  60
  61 ----
  62
  63 ###### Manual for `diaspy`, written by Marek Marecki