1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
|
#### `Connection()` object
This is the object that is used by `diaspy`'s internals.
It is pushed around and used by various methods and other objects:
* `Post()` and `Conversation()` objects require it to authenticate and
do their work,
* streams use it for getting their contents,
* etc.
`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.
----
##### Login procedure
`Connection()` will not log you in unless you explicitly order it to
do so. Logging in with `Connection()` is done via `login()` method.
**Example:**
connection = diaspy.connection.Connection(pod='https://pod.example.com',
username='user',
password='password')
connection.login()
----
##### 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.
`Connection` provides you with a method to fetch this token and perform
various actions on your account.
This method is called `_fetchtoken()`.
It will try to download a token for you.
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.
Here is how you should create your auth flow:
connection = diaspy.connection.Connection(...)
connection.login()
token = repr(connection)
----
##### Note for developers
If you want to write your own interface or client for D\*
`Connection()` is the only object you need.
----
###### Manual for `diaspy`, written by Marek Marecki
|
