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
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
|
from urllib.error import URLError
import urllib.request as url
from hashlib import sha256
from time import time
import json
class BBJ(object):
# this module isnt exactly complete. The below description claims
# `all of its endpoints are mapped to native methods` though this
# is not yet true. The documentation for the API is not yet
# complete, and neither is this client. Currently this module is
# being adapted to fit the needs of the urwid client. As it evolves,
# and the rest of the project evolves, this client will be completed
# and well documented.
"""
A python implementation to the BBJ api: all of its endpoints are
mapped to native methods, it maps error responses to exceptions, and
it includes helper functions for several common patterns.
It should be noted that endpoints utilizing usermaps are returned as
tuples, where [0] is the value and [1] is the usermap dictionary.
Methods who do this will mention it in their documentation.
You can call them like `threads, usermap = bbj.thread_index()`
__init__ can take a host string and a port value (which can be
either int or str). It defaults to "127.0.0.1" and 7099, expanding
out to http://127.0.0.1:7099/.
Standard library exceptions are used, but several new attributes are
attached to them before raising: .code, .description, and .body.
code and description map the same values returned by the api. body
is the raw error object. Classes are mapped as follows:
0, 1, 2: ChildProcessError
3: ValueError
4: UserWarning
5: ConnectionRefusedError
attributes can be accessed as follows:
try:
response = bbj.endpoint():
except UserWarning as e:
assert e.code == 4
print(e.description)
# want the raw error object? thats weird, but whatever.
return e.body
See the offical API error documentation for more details.
"""
def __init__(self, host="127.0.0.1", port=7099, https=False):
"""
Optionally takes port and host as kwargs. It will immediately
try to resolve a connection to the server, if its down, it
raises a URLError.
Important attributes:
.base is a string url for which all requests go to. It is
constructed on instantiation and the standalone host/port
are not stored.
.user_{name,auth} can be None, or strings of the username
and the authorization hash, respectively. When both values
are present (ie both resolve to True in a boolean context),
the request method sends this info with all its requests
and the user is effectively "logged in".
.send_auth, defaulting to True, determines whether to send
authorization information when it is available (see above).
If you set this to False, anonymous network usage is
guaranteed.
"""
self.base = "http{}://{}:{}/api/%s".format("s" if https else "", host, port)
self.user_name = self.user_auth = None
self.send_auth = True
try:
self.user = self("get_me")["data"]
self.update_instance_info()
except URLError:
raise URLError("Cannot connect to %s (is the server down?)" % self.base[0:-2])
def __call__(self, *args, **kwargs):
"""
Calling the network object itself is exactly the same as calling
it's .request() method.
"""
return self.request(*args, **kwargs)
def _hash(self, string):
"""
Handy function to hash a password and return it.
"""
return sha256(bytes(string, "utf8")).hexdigest()
def request(self, endpoint, **params):
"""
Takes the string endpoint, and a variable number of kwargs
to pass into the request body. The parameters required will
vary by endpoint, and if they are wrong, ValueError will be
raised.
However, one kwarg is magical here: no_auth. If you include
this, its not sent with the request, it just disables the
sending of auth info when it is available (for more info,
read __init__'s documentation).
You don't have to use this method yourself, the other methods
must use this as a base though.
See raise_exception() for details on how this function reacts
to various failure conditions.
"""
headers = {"Content-Type": "application/json"}
if params.get("no_auth"):
params.pop("no_auth")
elif all([self.send_auth, self.user_name, self.user_auth]):
headers.update({"User": self.user_name, "Auth": self.user_auth})
data = bytes(json.dumps(params), "utf8")
request = url.Request(
self.base % endpoint,
data=data,
headers=headers)
try:
with url.urlopen(request) as _r:
response = _r.read()
except url.HTTPError as e:
response = e.file.read()
value = json.loads(str(response, "utf8"))
if value and value.get("error"):
self.raise_exception(value["error"])
return value
def raise_exception(self, error_object):
"""
Takes an API error object and raises the appropriate exception,
attaching the code and description to the object. The classes
are mapped to the codes as follows:
0, 1, 2: ChildProcessError (internal server, http, and json errors)
3: ValueError (invalid endpoint arguments)
4: UserWarning (illegal values provided by user, not a real "error")
5: ConnectionRefusedError (authorizations declined)
To capture a code and description in your client:
try:
response = bbj.endpoint():
except UserWarning as e:
assert e.code == 4
print(e.description)
# want the raw error object? thats weird, but whatever.
return e.body
"""
description = error_object["description"]
code = error_object["code"]
if code in [0, 1, 2]:
e = ChildProcessError(description)
elif code == 3:
e = ValueError(description)
elif code == 4:
e = UserWarning(description)
elif code == 5:
e = ConnectionRefusedError(description)
e.code, e.description, e.body = code, description, error_object
raise e
def update_instance_info(self):
"""
Stores configuration info for the connected BBJ server.
{
"instance_name": (string), // a title set by the server owner
"allow_anon": (bool), // whether anonymous participation is allowed
"admins": (list) // usernames of those who have admin rights on the server
}
"""
response = self("instance_info")
self.instance_info = response["data"]
def validate(self, key, value, exception=AssertionError):
"""
Uses the server's db_validate method to verify the validty
of `value` by `key`. If it is invalid, kwarg exception (default
AssertionError) is raised with the exception containing the
attribute .description as the server's reason. Exception can
be a False value to just return boolean False.
Examples:
# this will fail bacause the server wont allow newlines in usernames.
try:
bbj.validate("user_name", "des\nvox")
except AssertionError as e:
print(e.description)
# or you can handle it as a boolean like this:
is_okay = bbj.validate("title", "teacups and roses <3", exception=None)
"""
response = self(
"db_validate",
no_auth=True,
key=key,
value=value
)
if not response["data"]["bool"]:
if not exception:
return False
description = response["data"]["description"]
error = exception(description)
error.description = description
raise error
return True
def validate_all(self, keys_and_values, exception=AssertionError):
"""
Takes a single iterable object as its argument, containing
assertions to make, and applies `validate` to each pair.
See `validate` for full details. This method also takes
the kwarg `exception`, and passes it to validate.
Returns a list containing each response from validate. Under
successful circumstances, each element will be True. If you
specify exception=None, then the elements can contain false
as well.
Example:
values = [
("title", "the wea\nther sucks"),
("body", "rain is gross lmao")
]
try:
bbj.validate_all(values)
except AssertionError as e:
print(e.description)
# as booleans:
validated = bbj.validate_all(values, exception=None)
# => [False, True]
assert all(validated)
"""
return [
self.validate(key, value, exception) for key, value in keys_and_values
]
def set_credentials(self, user_name, user_auth, hash_auth=True, check_validity=True):
"""
Internalizes user_name and user_auth. Unless hash_auth=False is
specified, user_auth is assumed to be an unhashed password
string and it gets hashed with sha256. If you want to handle
hashing yourself, make sure to disable that.
Unless check_validity is set to false, the new credentials are
sent to the server and a ConnectionRefusedError is raised if
they do not match server authentication data. ValueError is
raised if the credentials contain illegal values, or the
specified user is not registered. If you need to differentiate
the two, using the method `user_is_registered` might be more
your speed.
On success, True is returned and the values are set. Subsequent
requests will now be authorized for the user (see request()'s
documentation for details on how to override this behavior
when necessary)
Examples:
try:
bbj.set_credentials("desvox", "i am sandvich")
except ConnectionRefusedError:
# bad auth info
except ValueError:
# paramter validation failed or the user is not registered
# you can handle hashing yourself if you want
password = input("Enter your password:")
bbj.set_credentials(
"desvox",
sha256(bytes(password, "utf8")).hexdigest(),
hash_auth=False
)
"""
if hash_auth:
user_auth = self._hash(user_auth)
if check_validity and not self.validate_credentials(user_name, user_auth):
self.user_auth = self.user_name = None
raise ConnectionRefusedError("Auth and User do not match")
self.user_auth = user_auth
self.user_name = user_name
self.user = self("get_me")["data"]
return True
def validate_credentials(self, user_name, user_auth, exception=True):
"""
Pings the server to check that user_name can be authenticated with
user_auth. Raises ConnectionRefusedError if they cannot. Raises
ValueError if the credentials contain illegal values.
Alternatively, you can specify exception=False to just return a
boolean False if the credentials are incorrect. Will still raise
a ValueError if the parameters are illegal.
Example:
# this method DOES NOT take a password string. it must be hashed.
try: validate_credentials("desvox", hashed_password)
except ConnectionRefusedError:
...
except ValueError:
...
# as a boolean:
is_okay = bbj.validate_credentials("desvox", hashed_password, exception=False)
"""
self.validate_all([
("user_name", user_name),
("auth_hash", user_auth)
], ValueError)
try:
response = self("check_auth",
no_auth=True,
target_user=user_name,
target_hash=user_auth
)
return response["data"]
except ConnectionRefusedError as e:
if exception:
raise e
return False
def user_is_registered(self, user_name):
"""
Returns True or False whether user_name is registered
into the system.
"""
response = self(
"user_is_registered",
no_auth=True,
target_user=user_name
)
return response["data"]
def user_register(self, user_name, user_auth, hash_auth=True, set_as_user=True):
"""
Register user_name into the system with user_auth. Unless hash_auth
is set to false, user_auth should be a password string.
When set_as_user is True, the newly registered user is internalized
and subsequent uses of the object will be authorized for them.
Example:
try:
bbj.user_register("desvox", "sandvich")
except UserWarning as e:
# show this to users. always.
print(e.description)
# the object is now also set for this user...
assert bbj.get_me()["user_name"] == "desvox"
# ...unless you call it like this:
# bbj.user_register("desvox", "sandvich", set_as_user=False)
"""
if hash_auth:
user_auth = sha256(bytes(user_auth, "utf8")).hexdigest()
response = self("user_register",
no_auth=True,
user_name=user_name,
auth_hash=user_auth
)["data"]
assert all([
user_auth == response["auth_hash"],
user_name == response["user_name"]
])
if set_as_user:
self.set_credentials(user_name, user_auth, False)
return response
def user_update(self, **params):
"""
Update the user's data on the server. The new parameters
may be any of `user_name`, `auth_hash`, `quip`, `bio`,
`color`. On success, the newly updated user object is
returned and is also internalized as self.user.
"""
response = self("user_update", **params)
if params.get("user_name"):
self.user_name = params["user_name"]
if params.get("auth_hash"):
self.user_auth = params["auth_hash"]
self.user = self("get_me")["data"]
return response["data"]
def user_get(self, user_id_or_name):
"""
Return a full user object by their id or username.
Note that this isn't required when using thread_load
or thread_index, because they return a usermap which
is a dictionary with keys of the ids connected to these
same objects. You shouldn't use this method when a usermap
is provided.
If the user element isnt found, ValueError is raised.
See also `user_is_registered`
"""
response = self("user_get", target_user=user_id_or_name)
return response["data"]
def thread_index(self, include_op=False):
"""
Returns a tuple where [0] is a list of all threads ordered by
most recently interacted, and [1] is a usermap object.
Example:
threads, usermap = bbj.thread_index()
for thread in threads:
author_id = thread["author"]
print(usermap[author_id]["user_name"])
"""
response = self("thread_index", include_op=include_op)
return response["data"], response["usermap"]
def thread_load(self, thread_id, format=None, op_only=False):
"""
Returns a tuple where [0] is a thread object and [1] is a usermap object.
Example:
thread, usermap = bbj.thread_load(some_id)
for message in thread["messages"]:
author_id = message["author"]
print(usermap[author_id]["user_name"])
print(message["body"])
"""
response = self("thread_load",
format=format, thread_id=thread_id, op_only=op_only)
return response["data"], response["usermap"]
def thread_create(self, title, body):
"""
Submit a new thread, and return its new object. Requires the
string arguments `title` and `body`. Title must be under
120 chars in length, else UserWarning is raised. Body must
also not be empty.
"""
response = self("thread_create", title=title, body=body)
return response["data"]
def thread_reply(self, thread_id, body):
"""
Submits a new reply to a thread and returns the new object.
Requires the thread's id and a non-empty body string.
"""
response = self("thread_reply", thread_id=thread_id, body=body)
return response["data"]
def fake_message(self, body="!!", format="sequential", author=None, post_id=0):
"""
Produce a a valid message object with `body`. Useful for
testing and can also be used mimic server messages in a
client.
"""
return {
"body": self.format_message(body, format),
"author": author or self.user["user_id"],
"post_id": post_id,
"created": time(),
"edited": False,
"send_raw": False,
"thread_id": "gibberish"
}
def format_message(self, body, format="sequential"):
"""
Send `body` to the server to be formatted according to `format`,
defaulting to the sequential parser. Returns the body object.
"""
response = self("format_message", body=body, format=format)
return response["data"]
def message_delete(self, thread_id, post_id):
"""
Delete message `post_id` from `thread_id`. The same rules apply
to deletions as they do for edits. The same exceptions are raised
with the same descriptions. If post_id is 0, this will also delete
the entire thread. Returns True on success.
"""
response = self("delete_post", thread_id=thread_id, post_id=post_id)
return response["data"]
def edit_query(self, thread_id, post_id):
"""
Queries ther server database to see if a post can
be edited by the logged in user. thread_id and
post_id are required.
Returns a message object on success, or raises
a UserWarning describing why it failed.
"""
response = self("edit_query", thread_id=thread_id, post_id=int(post_id))
return response["data"]
def can_edit(self, thread_id, post_id):
"""
Return bool True/False that the post at thread_id | post_id
can be edited by the logged in user. Will not raise UserWarning.
"""
try:
result = bool(self.edit_query(thread_id, post_id))
except UserWarning:
result = False
return result
def edit_message(self, thread_id, post_id, new_body):
"""
Requires the thread_id and post_id. The edit flag is then
set on the message, new_body is set on the server, and the
newly edited message object is returned on success.
Will raise UserWarning if server editing rules are violated.
See also `can_edit` and `edit_query`
"""
response = self(
"edit_post", thread_id=thread_id,
post_id=post_id, body=new_body)
return response["data"]
def set_post_raw(self, thread_id, post_id, value):
"""
This is a subset of `edit_message` that retains the old
body and just sets its `send_raw` to your supplied `value`.
The `edited` parameter of the message on the server is not
modified.
"""
response = self(
"set_post_raw",
thread_id=thread_id,
post_id=post_id,
value=bool(value))
return response["data"]
def user_is_admin(self, user_name_or_id):
"""
Return boolean True or False whether the given user identifier
is an admin on the server. Will raise ValueError if this user
is not registered.
"""
response = self("is_admin", target_user=user_name_or_id)
return response["data"]
def thread_set_pin(self, thread_id, new_status):
"""
Set whether a thread should be pinned or not. new_status
is evaluated as a boolean, and given that the logged in
user is an admin, the thread is set to this status on
the server, and the boolean is returned.
"""
response = self("thread_set_pin", thread_id=thread_id, value=new_status)
return response["data"]
def message_feed(self, time, format=None):
"""
Returns a special object representing all activity on the board since
the argument `time`, a unix/epoch timestamp.
{
"threads": {
"thread_id": {
...thread object
},
...more thread_id/object pairs
},
"messages": [...standard message object array sorted by date],
"usermap": {
...standard user_id mapping object
}
}
The message objects in "messages" are the same objects returned
in threads normally. They each have a thread_id parameter, and
you can access metadata for these threads by the "threads" object
which is also provided. All user_ids can be resolved into full user
objects from the usermap object.
The "messages" array is already sorted by submission time, newest
first. The order in the threads object is undefined and you should
instead use their `last_mod` attribute if you intend to list them
out visually.
the optional argument `format` can be given and bahaves the same
as `thread_load`.
"""
response = self("message_feed", time=time, format=format)
return {
"usermap": response["usermap"],
"threads": response["data"]["threads"],
"messages": response["data"]["messages"]
}
|