[diaspy.git] / manual / streams.markdown

#### `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. 

----

##### Getting stream

To get basic stream you have to have working `Connection()` as 
this is required by `Stream()`'s constructor.

    c = diaspy.connection.Connection(pod='https://pod.example.com',
                                     username='foo',
                                     password='bar')
    c.login()
    stream = diaspy.models.Stream(c)

Now you have a stream filled with posts (if any can be found on user's stream).

----

##### `fill()`, `update()` and `more()`

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.

`more()` complements `update()` it will fetch you older posts instead of newer ones.

----

##### Length of and iterating over a stream

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.

First, using `len()` and `range()` functions.

    for i in range(len(stream)):
        # do stuff...

Second, iterating directly over the stream contents:

    for post in stream:
        # do stuff...


----

##### Posting data to stream

This is described in [`posting`](./posting.markdown) document in this manual.


----

##### Clearing stream

##### `clear()`

This will remove all posts from visible stream.

##### `purge()`

This will scan stream for nonexistent posts (eg. deleted) and remove them.

----

###### Manual for `diaspy`, written by Marek Marecki
Commit	Line	Data
7a31b4aa MM	1	#### `Stream()` object
	2
	3	This object is used to represent user's stream on D\*.
	4	It is returned by `Client()`'s method `get_stream()` and
8b013ef4	5	is basically a list of posts.
7a31b4aa MM	6
	7	----
	8
	9	##### Getting stream
	10
	11	To get basic stream you have to have working `Connection()` as
	12	this is required by `Stream()`'s constructor.
	13
	14	c = diaspy.connection.Connection(pod='https://pod.example.com',
	15	username='foo',
	16	password='bar')
	17	c.login()
	18	stream = diaspy.models.Stream(c)
	19
	20	Now you have a stream filled with posts (if any can be found on user's stream).
	21
	22	----
	23
6d8d47ce	24	##### `fill()`, `update()` and `more()`
cdbe5f4e MM	25
	26	When you want to refresh stream call it's `fill()` method. It will overwrite old stream
	27	contents.
	28
	29	On the contrary, `update()` will get a new stream but will not overwrite old stream saved
	30	in the object memory. It will append every new post to the old stream.
	31
6d8d47ce MM	32	`more()` complements `update()` it will fetch you older posts instead of newer ones.
6d8d47ce MM	33
cdbe5f4e MM	34	----
	35
	36	##### Length of and iterating over a stream
7a31b4aa MM	37
	38	Stream's length can be checked by calling `len()` on it.
	39
	40	len(stream)
	41	10
cdbe5f4e MM	42
	43	When you want to iterate over a stream (e.g. when you want to print first n posts on
	44	the stream) you can do it in two ways.
	45
	46	First, using `len()` and `range()` functions.
	47
	48	for i in range(len(stream)):
	49	# do stuff...
	50
	51	Second, iterating directly over the stream contents:
	52
	53	for post in stream:
	54	# do stuff...
	55
	56
8b013ef4 MM	57	----
	58
	59	##### Posting data to stream
	60
10e37b5a	61	This is described in [`posting`](./posting.markdown) document in this manual.
8b013ef4	62
6d8d47ce MM	63
	64	----
	65
	66	##### Clearing stream
	67
	68	##### `clear()`
	69
	70	This will remove all posts from visible stream.
	71
	72	##### `purge()`
	73
	74	This will scan stream for nonexistent posts (eg. deleted) and remove them.
	75
cdbe5f4e MM	76	----
	77
	78	###### Manual for `diaspy`, written by Marek Marecki