]> git.somenet.org - pub/jan/mattermost-api-python.git/blob - mattermost/__init__.py
README.md
[pub/jan/mattermost-api-python.git] / mattermost / __init__.py
1 #!/usr/bin/env python3
2 """
3 Someone's Mattermost API v4 bindings.
4   Copyright (c) 2016-2021 by Someone <someone@somenet.org> (aka. Jan Vales <jan@jvales.net>)
5   published under MIT-License
6 """
7
8 import logging
9 import json
10 import random
11 import warnings
12
13 import requests
14
15 from .version import __version__
16
17 logger = logging.getLogger("mattermost")
18
19
20 class ApiException(Exception):
21     """ if exc == True: Thrown when any status_code >=400 gets returned """
22
23
24 class MMApi:
25     """Mattermost API v4 bindings."""
26
27     def __init__(self, url):
28         self._url = url
29         self._bearer = None
30
31         # temp/retrieved data.
32         self._my_user_id = None
33
34         # the only way to detect our session :/
35         self._my_user_agent = "SomeMMApi-"+__version__+"-"+str(random.randrange(100000000000, 999999999999))
36         self._headers = requests.utils.default_headers()
37         self._headers.update({"User-Agent": self._headers["User-Agent"]+" "+self._my_user_agent})
38
39
40     def _get(self, endpoint, params=None, raw=False, exc=True):
41         """
42         Do a get-request.
43
44         Args:
45             endpoint (string): API-Endpoint to call, including /v4/..., excluding /api/
46             params (dict, optional): url-parameters-dict
47             raw (bool, optional): return result raw (useful if it is a file download)
48             exc (bool, optional): Throw exceptions if error code >= 400 (default=True. Can be disabled for backward-compatability for a while)
49
50         Returns:
51             dict: requested data.
52
53         Raises:
54             ApiException: If exc==True and a non-OK HTTP-Statuscode is received.
55         """
56         res = requests.get(self._url + endpoint, headers=self._headers, params=params)
57         if raw:
58             return res
59
60         logger.info("[GET] %s --> %d", endpoint, res.status_code)
61         logger.debug(json.dumps(json.loads(res.text), indent=4))
62         if exc and res.status_code >= 400:
63             raise ApiException(json.loads(res.text))
64
65         return json.loads(res.text)
66
67
68     def _put(self, endpoint, params=None, data=None, exc=True):
69         """
70         Do a put-request.
71
72         Args:
73             endpoint (string): API-Endpoint to call, including /v4/..., excluding /api/
74             params (dict, optional): url-parameters-dict
75             data (dict, optional): json-data to put, if any
76             raw (bool, optional): return result raw (useful if it is a file download)
77             exc (bool, optional): Throw exceptions if error code >= 400 (default=True. Can be disabled for backward-compatability for a while)
78
79         Returns:
80             dict: requested data.
81
82         Raises:
83             ApiException: If exc==True and a non-OK HTTP-Statuscode is received.
84         """
85         logger.debug(json.dumps(data, indent=4))
86         res = requests.put(self._url + endpoint, headers=self._headers, params=params, data=json.dumps(data))
87         logger.info("[PUT] %s --> %d", endpoint, res.status_code)
88         logger.debug(json.dumps(json.loads(res.text), indent=4))
89         if exc and res.status_code >= 400:
90             raise ApiException(json.loads(res.text))
91
92         return json.loads(res.text)
93
94
95     def _post(self, endpoint, params=None, data=None, multipart_formdata=None, exc=True):
96         """
97         Do a post-request.
98
99         Args:
100             endpoint (string): API-Endpoint to call, including /v4/..., excluding /api/
101             params (dict, optional): url-parameters-dict
102             data (dict, optional): json-data to post, if any
103             exc (bool, optional): Throw exceptions if error code >= 400 (default=True. Can be disabled for backward-compatability for a while)
104
105         Returns:
106             dict: requested data.
107
108         Raises:
109             ApiException: If exc==True and a non-OK HTTP-Statuscode is received.
110         """
111         logger.debug(json.dumps(data, indent=4))
112         if data is not None:
113             data = json.dumps(data)
114
115         res = requests.post(self._url + endpoint, headers=self._headers, params=params, data=data, files=multipart_formdata)
116         logger.info("[POST] %s --> %d", endpoint, res.status_code)
117         logger.debug(json.dumps(json.loads(res.text), indent=4))
118         if exc and res.status_code >= 400:
119             raise ApiException(json.loads(res.text))
120
121         return json.loads(res.text)
122
123
124     def _delete(self, endpoint, params=None, data=None, exc=True):
125         """
126         Do a delete-request.
127
128         Args:
129             endpoint (string): API-Endpoint to call, including /v4/..., excluding /api/
130             params (dict, optional): url-parameters-dict
131             data (dict, optional): json-data to delete, if any
132             exc (bool, optional): Throw exceptions if error code >= 400 (default=True. Can be disabled for backward-compatability for a while)
133
134         Returns:
135             dict: requested data.
136
137         Raises:
138             ApiException: If exc==True and a non-OK HTTP-Statuscode is received.
139         """
140         logger.debug(json.dumps(data, indent=4))
141         res = requests.delete(self._url + endpoint, headers=self._headers, params=params, data=json.dumps(data))
142         logger.info("[DELETE] %s --> %d", endpoint, res.status_code)
143         logger.debug(json.dumps(json.loads(res.text), indent=4))
144         if exc and res.status_code >= 400:
145             raise ApiException(json.loads(res.text))
146
147         return json.loads(res.text)
148
149
150 ################################################
151 #+ **LOGIN/LOGOUT**
152
153
154     # login is special - dont use helpers above. We also need login to be called, even if bearer is used, so we know out user-id and session-id.
155     def login(self, login_id=None, password=None, token=None, bearer=None):
156         """
157         Login to the corresponding (self._url) mattermost instance.
158         Use login_id and password, optionally token (totp)
159         If bearer is passed this token is used instead.
160
161         Unlike the MM-api this package requires to login() with bearer-tokens, because otherwise we cannot reliably and/or non-ugly get stuff like the user's id.
162         """
163         if self._bearer:
164             logger.warning("Already logged in. Ignoring new attempt.")
165             return None
166
167         # note: bearer vs self._bearer
168         if not bearer:
169             props = {"login_id": login_id, "password": password, "token":token}
170             res = requests.post(self._url + "/v4/users/login", headers=self._headers, data=json.dumps(props))
171
172             if res.status_code != 200:
173                 logger.critical("User-Login failed: %d", res.status_code)
174                 return None
175
176             self._bearer = str(res.headers["Token"])
177
178         else:
179             self._bearer = bearer
180
181         logger.info("Token Bearer: %s", self._bearer)
182         self._headers.update({"Authorization": "Bearer "+self._bearer})
183
184         if bearer:
185             res = requests.get(self._url + "/v4/users/me", headers=self._headers)
186             if res.status_code != 200:
187                 logger.critical("Bearer-Login failed: %d", res.status_code)
188                 return None
189
190         # also store our user_id
191         ret = json.loads(res.text)
192         self._my_user_id = ret["id"]
193         return ret
194
195
196     def logout(self, **kwargs):
197         """
198         This will end the session at the server and invalidate this MMApi-object.
199         """
200         return self._post("/v4/users/logout", **kwargs)
201
202
203
204 ################################################
205 #+ **USERS**
206
207
208     #def create_user() #NOT_IMPLEMENTED
209
210
211
212     def get_users(self, in_team=None, not_in_team=None, in_channel=None, not_in_channel=None, group_constrained=None, without_team=None, sort=None, **kwargs):
213         """
214         Generator: iterates over all users. Results can be restricted based on other parameters.
215
216         Args:
217             in_team (string, optional): see MM-API doc.
218             not_in_team (string, optional): see MM-API doc.
219             in_channel (string, optional): see MM-API doc.
220             not_in_channel (string, optional): see MM-API doc.
221             group_constrained (bool, optional): see MM-API doc.
222             without_team (bool, optional): see MM-API doc.
223             sort (string, optional): see MM-API doc.
224
225         Returns:
226             generates: One User at a time.
227
228         Raises:
229             ApiException: Passed on from lower layers.
230         """
231         page = 0
232         while True:
233             data_page = self._get("/v4/users", params={
234                 "page":str(page),
235                 "per_page":"200",
236                 **({"in_team": in_team} if in_team else {}),
237                 **({"not_in_team": not_in_team} if not_in_team else {}),
238                 **({"not_in_team": not_in_team} if not_in_team else {}),
239                 **({"in_channel": in_channel} if in_channel else {}),
240                 **({"not_in_channel": not_in_channel} if not_in_channel else {}),
241                 **({"group_constrained": group_constrained} if group_constrained else {}),
242                 **({"without_team": without_team} if without_team else {}),
243                 **({"sort": sort} if sort else {}),
244             }, **kwargs)
245
246             if data_page == []:
247                 break
248             page += 1
249
250             for data in data_page:
251                 yield data
252
253
254
255     def get_users_by_ids_list(self, user_ids_list, **kwargs): #UNTESTED
256         """
257         Get a list of users based on a provided list of user ids.
258
259         Args:
260             user_ids_list (list): see MM-API doc.
261
262         Returns:
263             list: of Users.
264
265         Raises:
266             ApiException: Passed on from lower layers.
267         """
268         return self._post("/v4/users/ids", data=user_ids_list, **kwargs)
269
270
271
272     def get_users_by_group_channel_ids_list(self, group_channel_ids_list, **kwargs): #UNTESTED
273         """
274         Get an object containing a key per group channel id in the query and its value as a list of users members of that group channel.
275
276         Args:
277             group_channel_ids_list (list): see MM-API doc.
278
279         Returns:
280             list: of channel_ids: list of Users.
281
282         Raises:
283             ApiException: Passed on from lower layers.
284         """
285         return self._post("/v4/users/group_channels", data=group_channel_ids_list, **kwargs)
286
287
288
289     def get_users_by_usernames_list(self, usernames_list, **kwargs):
290         """
291         Get a list of users based on a provided list of usernames.
292
293         Args:
294             usernames_list (list): see MM-API doc.
295
296         Returns:
297             list: of Users.
298
299         Raises:
300             ApiException: Passed on from lower layers.
301         """
302         return self._post("/v4/users/usernames", data=usernames_list, **kwargs)
303
304
305
306     #def search_users() #NOT_IMPLEMENTED
307     #def autocomplete_users() #NOT_IMPLEMENTED
308     #def get_user_ids_of_known_users() #NOT_IMPLEMENTED
309     #def get_total_count_of_users_in_system() #NOT_IMPLEMENTED
310
311
312
313     def get_user(self, user_id=None, **kwargs):
314         """
315         Get a list of users based on a provided list of usernames.
316
317         Args:
318             user_id (string, optional): if not given, returns Data on calling user. (/me)
319
320         Returns:
321             dict: User.
322
323         Raises:
324             ApiException: Passed on from lower layers.
325         """
326         if user_id is None:
327             return self._get("/v4/users/me", **kwargs)
328
329         return self._get("/v4/users/"+user_id, **kwargs)
330
331
332
333     #def update_user() #NOT_IMPLEMENTED: # use patch_user
334     #def deactivate_user() #NOT_IMPLEMENTED
335
336
337
338     def patch_user(self, user_id, props=None, **kwargs):
339         """
340         Partially update a user by providing only the fields you want to update.
341
342         Args:
343             user_id (string): User to patch.
344             props (dict, optional): fields you want to update.
345
346         Returns:
347             dict: User.
348
349         Raises:
350             ApiException: Passed on from lower layers.
351         """
352         return self._put("/v4/users/"+user_id+"/patch", data=props, **kwargs)
353
354
355
356     #def update_user_roles() #NOT_IMPLEMENTED
357     #def update_user_active_status() #NOT_IMPLEMENTED
358     #def get_user_profile_image() #NOT_IMPLEMENTED
359     #def set_user_profile_image() #NOT_IMPLEMENTED
360     #def delete_user_profile_image() #NOT_IMPLEMENTED
361     #def get_user_default_profile_image() #NOT_IMPLEMENTED
362
363
364
365     def get_user_by_username(self, username, **kwargs):
366         """
367         Get a user object by providing a username.
368         Sensitive information will be sanitized out.
369
370         Args:
371             username (string): User's username.
372
373         Returns:
374             dict: User.
375
376         Raises:
377             ApiException: Passed on from lower layers.
378         """
379         return self._get("/v4/users/username/"+username, **kwargs)
380
381
382
383     #def reset_user_password() #NOT_IMPLEMENTED
384     #def update_user_mfa() #NOT_IMPLEMENTED
385     #def generate_user_mfa_secret() #NOT_IMPLEMENTED
386
387
388
389     def demote_a_user(self, user_id, **kwargs):
390         """
391         Convert a regular user into a guest.
392         This will convert the user into a guest for the whole system while retaining their existing team and channel memberships.
393
394         Args:
395             user_id (string): User to demote.
396
397         Returns:
398             string: Status.
399
400         Raises:
401             ApiException: Passed on from lower layers.
402         """
403         return self._post("/v4/users/"+user_id+"/demote", **kwargs)
404
405
406
407     def promote_a_guest(self, user_id, **kwargs):
408         """
409         Convert a guest into a regular user.
410         This will convert the guest into a user for the whole system while retaining any team and channel memberships and automatically joining them to the default channels.
411
412         Args:
413             user_id (string): User to promote   .
414
415         Returns:
416             string: Status.
417
418         Raises:
419             ApiException: Passed on from lower layers.
420         """
421         return self._post("/v4/users/"+user_id+"/promote", **kwargs)
422
423
424
425     #def check_user_mfa() #NOT_IMPLEMENTED
426     #def update_user_password() #NOT_IMPLEMENTED
427     #def send_user_password_reset_mail() #NOT_IMPLEMENTED
428     #def get_user_by_email() #NOT_IMPLEMENTED
429
430
431
432     def get_user_sessions(self, user_id=None, **kwargs):
433         """
434         Get a list of sessions by providing the user GUID. Sensitive information will be sanitized out.
435
436         Args:
437             user_id (string, optional): if not given, returns Data on logged in user. (/me)
438
439         Returns:
440             list: of dicts of Sessions.
441
442         Raises:
443             ApiException: Passed on from lower layers.
444         """
445         if user_id is None:
446             user_id = self._my_user_id
447
448         return self._get("/v4/users/"+user_id+"/sessions", **kwargs)
449
450
451
452     def revoke_user_session(self, user_id=None, session_id=None, **kwargs):
453         """
454         Revokes a user session from the provided user id and session id strings.
455         Previously this was the only way to logout.
456         Please migrate to logout()
457
458         """
459         if not user_id and not session_id:
460             warnings.warn("revoke_user_session() without arguments is deprecated; use logout().", category=DeprecationWarning)
461
462         if user_id is None:
463             user_id = self._my_user_id
464
465         if session_id is None:
466             session_id = self._bearer
467
468         return self._post("/v4/users/"+user_id+"/sessions/revoke", data={"session_id": session_id}, **kwargs)
469
470
471
472     #def revoke_all_user_sessions() #NOT_IMPLEMENTED
473     #def attach_mobile_device_to_user_session() #NOT_IMPLEMENTED
474     #def get_user_audit() #NOT_IMPLEMENTED
475     #def admin_verify_user_email_() #NOT_IMPLEMENTED
476     #def verify_user_email_() #NOT_IMPLEMENTED
477     #def send_user_email_verification() #NOT_IMPLEMENTED
478     #def switch_user_login_method() #NOT_IMPLEMENTED
479     #def create_user_access_token() #NOT_IMPLEMENTED
480     #def get_user_access_tokens() #NOT_IMPLEMENTED
481     #def revoke_user_access_token() #NOT_IMPLEMENTED
482     #def get_user_access_token() #NOT_IMPLEMENTED
483     #def disable_user_access_token() #NOT_IMPLEMENTED
484     #def enable_user_access_token() #NOT_IMPLEMENTED
485     #def search_user_access_tokens() #NOT_IMPLEMENTED
486     #def update_user_auth_method() #NOT_IMPLEMENTED
487     #def record_user_action_custom_tos() #NOT_IMPLEMENTED
488     #def fetch_user_latest_accepted_custom_tos() #NOT_IMPLEMENTED
489     #def revoke_all_users_all_sessions() #NOT_IMPLEMENTED #MM, ARE YOU INSANE?!
490
491
492
493 ################################################
494 #+ **BOTS** #NOT_IMPLEMENTED
495
496
497
498 ################################################
499 #+ **TEAMS**
500
501
502
503     #def create_team() #NOT_IMPLEMENTED
504
505
506
507     def get_teams(self, include_total_count=None, **kwargs):
508         """
509         Generator: Get regular users only returns open teams. Users with the "manage_system" permission will return teams regardless of type.
510
511         Args:
512             include_total_count (bool, optional): see MM-API doc.
513
514         Returns:
515             generates: One Team at a time.
516
517         Raises:
518             ApiException: Passed on from lower layers.
519         """
520         page = 0
521         while True:
522             data_page = self._get("/v4/teams", params={
523                 "page":str(page),
524                 **({"include_total_count": include_total_count} if include_total_count else {}),
525             }, **kwargs)
526
527             if data_page == []:
528                 break
529             page += 1
530
531             for data in data_page:
532                 yield data
533
534
535
536     def get_team(self, team_id, **kwargs):
537         """
538         Get a team on the system.
539
540         Args:
541             team_id (string): team_id.
542
543         Returns:
544             dict: Team.
545
546         Raises:
547             ApiException: Passed on from lower layers.
548         """
549         return self._get("/v4/teams/"+team_id, **kwargs)
550
551
552
553     #def update_team() #NOT_IMPLEMENTED
554     #def delete_team() #NOT_IMPLEMENTED
555     #def patch_team() #NOT_IMPLEMENTED
556     #def update_team_privacy() #NOT_IMPLEMENTED
557     #def restore_team() #NOT_IMPLEMENTED
558     #def get_team_by_name() #NOT_IMPLEMENTED
559     #def search_teams() #NOT_IMPLEMENTED
560     #def exists_team() #NOT_IMPLEMENTED
561     #def get_teams_for_user() #NOT_IMPLEMENTED
562
563
564
565     def get_team_members(self, team_id, **kwargs):
566         """
567         Generator: Get a page team members list.
568
569         Args:
570             team_id (string): team_id.
571
572         Returns:
573             generates: One User at a time.
574
575         Raises:
576             ApiException: Passed on from lower layers.
577         """
578         page = 0
579         while True:
580             data_page = self._get("/v4/teams/"+team_id+"/members", params={"page":str(page)}, **kwargs)
581
582             if data_page == []:
583                 break
584             page += 1
585
586             for data in data_page:
587                 yield data
588
589
590
591     def add_user_to_team(self, team_id, user_id, **kwargs):
592         """
593         Add user to the team by user_id.
594
595         Args:
596             team_id (string): team_id to add the user to.
597             user_id (string): user_id to add to team.
598
599         Returns:
600             dict: Teammembership.
601
602         Raises:
603             ApiException: Passed on from lower layers.
604         """
605         return self._post("/v4/teams/"+team_id+"/members", data={
606             "team_id": team_id,
607             "user_id": user_id,
608         }, **kwargs)
609
610
611
612     #def add_user_to_team_from_invite() #NOT_IMPLEMENTED
613     #def add_multiple_users_to_team() #NOT_IMPLEMENTED WHY?!
614     #def get_team_members_for_a_user() #NOT_IMPLEMENTED WHY NOT NAMING STUFF USEFULLY?!
615
616
617
618     def get_team_member(self, team_id, user_id, **kwargs):
619         """
620         Add user to the team by user_id.
621
622         Args:
623             team_id (string): team_id to add the user to.
624             user_id (string): user_id to add to team.
625
626         Returns:
627             dict: Teammembership.
628
629         Raises:
630             ApiException: Passed on from lower layers.
631         """
632         return self._get("/v4/teams/"+team_id+"/members/"+user_id, **kwargs)
633
634
635
636     def remove_user_from_team(self, team_id, user_id, **kwargs):
637         """
638         Delete the team member object for a user, effectively removing them from a team.
639
640         Args:
641             team_id (string): team_id to remove the user from.
642             user_id (string): user_id to remove.
643
644         Returns:
645             dict: status.
646
647         Raises:
648             ApiException: Passed on from lower layers.
649         """
650         return self._delete("/v4/teams/"+team_id+"/members/"+user_id, **kwargs)
651
652
653
654     #def get_team_members_by_id() #NOT_IMPLEMENTED
655     #def get_team_stats() #NOT_IMPLEMENTED
656     #def regenerate_team_invite_id() #NOT_IMPLEMENTED
657     #def get_team_icon() #NOT_IMPLEMENTED
658     #def set_team_icon() #NOT_IMPLEMENTED
659     #def remove_team_icon() #NOT_IMPLEMENTED
660     #def update_team_members_roles() #NOT_IMPLEMENTED
661
662
663
664     def update_team_members_scheme_roles(self, team_id, user_id, props, **kwargs):
665         """
666         Update a team member's scheme_admin/scheme_user properties.
667         Typically this should either be {scheme_admin=false, scheme_user=true} for ordinary team member, or {scheme_admin=true, scheme_user=true} for a team admin.
668
669         Args:
670             team_id (string): obvious
671             user_id (string): obvious
672             props (dict): see MM-API docs.
673
674         Returns:
675             dict: status.
676
677         Raises:
678             ApiException: Passed on from lower layers.
679         """
680         return self._put("/v4/teams/"+team_id+"/members/"+user_id+"/schemeRoles", data=props, **kwargs)
681
682
683
684     #def get_team_unreads_for_user() #NOT_IMPLEMENTED
685     #def get_team_unreads() #NOT_IMPLEMENTED
686     #def invite_users_to_team_by_email() #NOT_IMPLEMENTED
687
688
689
690     def invite_guests_to_team_by_email(self, team_id, guest_email, channels, message, **kwargs):
691         """
692         Invite guests to existing team channels usign the user's email.
693         The number of emails that can be sent is rate limited to 20 per hour with a burst of 20 emails. If the rate limit exceeds, the error message contains details on when to retry and when the timer will be reset.
694
695         Args:
696             team_id (string): obvious
697             guest_email (strings): whom to invite.
698             channels (list of channel_ids): into which channels.
699             message (string, optional): optional message
700
701         Returns:
702             dict: status.
703
704         Raises:
705             ApiException: Passed on from lower layers.
706         """
707         return self._post("/v4/teams/"+team_id+"/invite-guests/email", data={
708             "emails": [guest_email],
709             "channels": channels,
710             **({"message": message} if message else {}),
711         }, **kwargs)
712
713
714     #def invalidate_invites_to_team_by_email() #NOT_IMPLEMENTED
715     #def import_team() #NOT_IMPLEMENTED
716     #def get_team_invite_info() #NOT_IMPLEMENTED
717     #def set_team_scheme() #NOT_IMPLEMENTED
718     #def get_team_members_minus_group_members() #NOT_IMPLEMENTED
719
720
721
722     def get_team_channels(self, team_id, **kwargs): #This belongs here, not to channels!
723         """
724         Generator: Get a page of public channels on a team.
725
726         Args:
727             team_id (string): team to get channels from.
728
729         Returns:
730             generates: Channel.
731
732         Raises:
733             ApiException: Passed on from lower layers.
734         """
735         page = 0
736         while True:
737             data_page = self._get("/v4/teams/"+team_id+"/channels", params={"page":str(page)}, **kwargs)
738
739             if data_page == []:
740                 break
741             page += 1
742
743             for data in data_page:
744                 yield data
745
746
747
748 ################################################
749 #+ **CHANNELS**
750
751
752
753     #def get_all_channels() #NOT_IMPLEMENTED NOT USEFUL AT ALL!
754
755
756
757     def create_channel(self, team_id, name, display_name, purpose=None, header=None, chan_type="O", **kwargs):
758         """
759         Create a new channel.
760
761         Args:
762             team_id (string): The team ID of the team to create the channel on.
763             name (string): The unique handle for the channel, will be present in the channel URL.
764             display_name (string): see MM-API docs.
765             purpose (string, optional): see MM-API docs.
766             header (string, optional): see MM-API docs.
767             chan_type (string, default: public): see MM-API docs.
768
769         Returns:
770             dict: created Channel.
771
772         Raises:
773             ApiException: Passed on from lower layers.
774         """
775         return self._post("/v4/channels", data={
776             "team_id": team_id,
777             "name": name,
778             "display_name": display_name,
779             **({"purpose": purpose} if purpose else {}),
780             **({"header": header} if header else {}),
781             "type": chan_type,
782         }, **kwargs)
783
784
785
786     def create_dm_channel_with(self, other_user_id, **kwargs):
787         """
788         Create a new direct message channel between two users.
789
790         Args:
791             other_user_id (string): The other user_id to create the cannel with.
792
793         Returns:
794             dict: created Channel.
795
796         Raises:
797             ApiException: Passed on from lower layers.
798         """
799         return self._post("/v4/channels/direct", data=[self._my_user_id, other_user_id], **kwargs)
800
801
802
803     def create_group_channel_with(self, other_user_ids_list, **kwargs): #UNTESTED
804         """
805         Create a new direct message channel between two users.
806
807         Args:
808             other_user_ids_list (list): List of user_ids to create the cannel with.
809
810         Returns:
811             dict: created Channel.
812
813         Raises:
814             ApiException: Passed on from lower layers.
815         """
816         return self._post("/v4/channels/group", data=other_user_ids_list, **kwargs)
817
818
819
820     #def search_all_private_and_public_channels() #NOT_IMPLEMENTED
821     #def search_all_users_group_channels() #NOT_IMPLEMENTED
822     #def get_team_channels_by_id() #NOT_IMPLEMENTED
823     #def get_timezones_of_users_in_channel() #NOT_IMPLEMENTED
824
825
826
827     def get_channel(self, channel_id, **kwargs):
828         """
829         Get channel from the provided channel id string.
830
831         Args:
832             channel_id (string): channel_id to get.
833
834         Returns:
835             dict: Channel.
836
837         Raises:
838             ApiException: Passed on from lower layers.
839         """
840         return self._get("/v4/channels/"+channel_id, **kwargs)
841
842
843
844     def update_channel(self, channel_id, props, **kwargs):
845         """
846         Update a channel. The fields that can be updated are listed as parameters. Omitted fields will be treated as blanks.
847
848         Args:
849             channel_id (string): channel_id to get.
850             props (dict, optional): fields you want to update.
851
852         Returns:
853             dict: Channel.
854
855         Raises:
856             ApiException: Passed on from lower layers.
857         """
858         return self._put("/v4/channels/"+channel_id, data=props, **kwargs)
859
860
861
862     def patch_channel(self, channel_id, props, **kwargs):
863         """
864         Partially update a channel by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.
865
866         Args:
867             channel_id (string): channel_id to get.
868             props (dict, optional): fields you want to update.
869
870         Returns:
871             dict: Channel.
872
873         Raises:
874             ApiException: Passed on from lower layers.
875         """
876         return self._put("/v4/channels/"+channel_id+"/patch", data=props, **kwargs)
877
878
879
880     def get_channel_posts_pinned(self, channel_id, **kwargs):
881         """
882         Get a list of pinned posts for channel.
883
884         Args:
885             channel_id (string): channel_id to get pinned posts for.
886
887         Returns:
888             dict: Results.
889
890         Raises:
891             ApiException: Passed on from lower layers.
892         """
893         return self._get("/v4/channels/"+channel_id+"/pinned", **kwargs)
894
895
896
897     def search_channel(self, team_id, term, **kwargs):
898         """
899         Search public channels on a team based on the search term provided in the request body.
900
901         Args:
902             team_id (string): team_id to search in.
903             term (string): The search term to match against the name or display name of channels.
904
905         Returns:
906             list: of Channels.
907
908         Raises:
909             ApiException: Passed on from lower layers.
910         """
911         return self._post("/v4/teams/"+team_id+"/channels/search", data={"term": term}, **kwargs)
912
913
914
915     def get_channel_by_name(self, team_id, channel_name, include_deleted=None, **kwargs):
916         """
917         Gets channel from the provided team id and channel name strings.
918
919         Args:
920             team_id (string): team_id to search in.
921             term (string): The search term to match against the name or display name of channels.
922             include_deleted (bool, optional): see MM-API doc.
923
924         Returns:
925             dict: Channel.
926
927         Raises:
928             ApiException: Passed on from lower layers.
929         """
930         return self._get("/v4/teams/"+team_id+"/channels/name/"+channel_name, params={
931             **({"include_deleted": include_deleted} if include_deleted else {}),
932         }, **kwargs)
933
934
935
936     def get_channel_members(self, channel_id, **kwargs):
937         """
938         Generator: Members for a channel.
939
940         Args:
941             channel_id (string): channel_id to get the members for.
942
943         Returns:
944             generates: One Member at a time.
945
946         Raises:
947             ApiException: Passed on from lower layers.
948         """
949         page = 0
950         while True:
951             data_page = self._get("/v4/channels/"+channel_id+"/members", params={"page":str(page)}, **kwargs)
952
953             if data_page == []:
954                 break
955             page += 1
956
957             for data in data_page:
958                 yield data
959
960
961
962     def add_user_to_channel(self, channel_id, user_id, **kwargs):
963         """
964         Add a user to a channel by creating a channel member object.
965
966         Args:
967             channel_id (string): channel_id to add the user to.
968             user_id (string): user_id to add.
969
970         Returns:
971             dict: Membership.
972
973         Raises:
974             ApiException: Passed on from lower layers.
975         """
976         return self._post("/v4/channels/"+channel_id+"/members", data={"user_id": user_id}, **kwargs)
977
978
979
980     def get_channel_member(self, channel_id, user_id, **kwargs):
981         """
982         Gets channel from the provided team id and channel name strings.
983
984         Args:
985             channel_id (string): channel_id to get the members for.
986             user_id (string): user_id to get the member-data for.
987
988         Returns:
989             dict: Membership.
990
991         Raises:
992             ApiException: Passed on from lower layers.
993         """
994         return self._get("/v4/channels/"+channel_id+"/members/"+user_id, **kwargs)
995
996
997
998     def remove_user_from_channel(self, channel_id, user_id, **kwargs):
999         """
1000         Add a user to a channel by creating a channel member object.
1001
1002         Args:
1003             channel_id (string): channel_id to remove the user from.
1004             user_id (string): user_id to remove.
1005
1006         Returns:
1007             dict: status.
1008
1009         Raises:
1010             ApiException: Passed on from lower layers.
1011         """
1012         return self._delete("/v4/channels/"+channel_id+"/members/"+user_id, **kwargs)
1013
1014
1015
1016     def update_channel_members_scheme_roles(self, channel_id, user_id, props, **kwargs):
1017         """
1018         Update a channel member's scheme_admin/scheme_user properties. Typically this should either be scheme_admin=false, scheme_user=true for ordinary channel member, or scheme_admin=true, scheme_user=true for a channel admin.
1019
1020         Args:
1021             channel_id (string): see MM-API doc.
1022             user_id (string): see MM-API doc.
1023             props (dict): see MM-API doc.
1024
1025         Returns:
1026             list: of Channels.
1027
1028         Raises:
1029             ApiException: Passed on from lower layers.
1030         """
1031         return self._put("/v4/channels/"+channel_id+"/members/"+user_id+"/schemeRoles", data=props, **kwargs)
1032
1033
1034
1035     def get_channel_memberships_for_user(self, user_id, team_id, **kwargs):
1036         """
1037         Get all channel memberships and associated membership roles (i.e. channel_user, channel_admin) for a user on a specific team.
1038
1039         Args:
1040             user_id (string): see MM-API doc.
1041             team_id (string): see MM-API doc.
1042
1043         Returns:
1044             list: of Memberships.
1045
1046         Raises:
1047             ApiException: Passed on from lower layers.
1048         """
1049         return self._get("/v4/users/"+user_id+"/teams/"+team_id+"/channels/members", **kwargs)
1050
1051
1052
1053     def get_channels_for_user(self, user_id, team_id, **kwargs):
1054         """
1055         Get all the channels on a team for a user.
1056
1057         Args:
1058             user_id (string): see MM-API doc.
1059             team_id (string): see MM-API doc.
1060
1061         Returns:
1062             list: of Channels.
1063
1064         Raises:
1065             ApiException: Passed on from lower layers.
1066         """
1067         return self._get("/v4/users/"+user_id+"/teams/"+team_id+"/channels", **kwargs)
1068
1069
1070
1071 ################################################
1072 #+ **POSTS**
1073
1074
1075     def create_post(self, channel_id, message, props=None, filepaths=None, root_id=None, **kwargs):
1076         """
1077         Create a new post in a channel. To create the post as a comment on another post, provide root_id.
1078
1079         Args:
1080             channel_id (string): The channel ID to create the post in.
1081             message (string): The message text.
1082             props (string, optional): see MM-API docs.
1083             filepaths (list, optional): Paths to upload files from and attach to post.
1084             root_id (string, optional): see MM-API docs.
1085
1086         Returns:
1087             dict: created Post.
1088
1089         Raises:
1090             ApiException: Passed on from lower layers.
1091         """
1092         file_ids = []
1093         if filepaths:
1094             for filename in filepaths:
1095                 file_ids.append(self.upload_file(channel_id, filename, **kwargs)["id"])
1096
1097         return self._post("/v4/posts", data={
1098             "channel_id": channel_id,
1099             "message": message,
1100             **({"props": props} if props else {"props": {"from_webhook":"true"}}),
1101             "root_id":root_id,
1102             "file_ids": file_ids,
1103         }, **kwargs)
1104
1105
1106
1107     def create_ephemeral_post(self, channel_id, message, user_id, **kwargs):
1108         """
1109         Create a new ephemeral post in a channel.
1110
1111         Args:
1112             channel_id (string): The channel ID to create the post in.
1113             message (string): The message text.
1114             user_id (string): The user ID to display the post to.
1115
1116         Returns:
1117             dict: created Post.
1118
1119         Raises:
1120             ApiException: Passed on from lower layers.
1121         """
1122         return self._post("/v4/posts/ephemeral", data={
1123             "user_id": user_id,
1124             "post":{
1125                 "channel_id": channel_id,
1126                 "message": message,
1127             }
1128         }, **kwargs)
1129
1130
1131
1132     def get_post(self, post_id, **kwargs):
1133         """
1134         Get a single post.
1135
1136         Args:
1137             post_id (string): The post ID to get.
1138
1139         Returns:
1140             dict: Post.
1141
1142         Raises:
1143             ApiException: Passed on from lower layers.
1144         """
1145         return self._get("/v4/posts/"+post_id, **kwargs)
1146
1147
1148
1149     def delete_post(self, post_id, **kwargs):
1150         """
1151         Soft deletes a post, by marking the post as deleted in the database. Soft deleted posts will not be returned in post queries.
1152
1153         Args:
1154             post_id (string): The post ID to delete.
1155
1156         Returns:
1157             string: status.
1158
1159         Raises:
1160             ApiException: Passed on from lower layers.
1161         """
1162         return self._delete("/v4/posts/"+post_id, **kwargs)
1163
1164
1165
1166     def patch_post(self, post_id, message=None, is_pinned=None, file_ids=None, props=None, **kwargs):
1167         """
1168         Partially update a post by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.
1169
1170         Args:
1171             post_id (string): The post ID to patch.
1172             message (string, optional): see MM-API doc.
1173             is_pinned (bool, optional): see MM-API doc.
1174             file_ids (list of file_ids, optional): see MM-API doc.
1175             props (dict, optional): see MM-API doc.
1176
1177         Returns:
1178             dict: Post.
1179
1180         Raises:
1181             ApiException: Passed on from lower layers.
1182         """
1183         return self._put("/v4/posts/"+post_id+"/patch", data={
1184             **({"message": message} if message else {}),
1185             **({"is_pinned": is_pinned} if is_pinned else {}),
1186             **({"file_ids": file_ids} if file_ids else {}),
1187             **({"props": props} if props else {}),
1188         }, **kwargs)
1189
1190
1191
1192     def get_posts_for_channel(self, channel_id, **kwargs):
1193         """
1194         Generator: Get a page of posts in a channel. Use the query parameters to modify the behaviour of this endpoint.
1195
1196         Args:
1197             channel_id (string): The channel ID to iterate over.
1198
1199         Returns:
1200             generates: Post.
1201
1202         Raises:
1203             ApiException: Passed on from lower layers.
1204         """
1205         page = 0
1206         while True:
1207             data_page = self._get("/v4/channels/"+channel_id+"/posts", params={"page":str(page)}, **kwargs)
1208
1209             if data_page["order"] == []:
1210                 break
1211             page += 1
1212
1213             for order in data_page["order"]:
1214                 yield data_page["posts"][order]
1215
1216
1217
1218 ################################################
1219 #+ **FILES**
1220
1221
1222     def upload_file(self, channel_id, filepath, **kwargs):
1223         """
1224         Uploads a file that can later be attached to a post.
1225
1226         Args:
1227             channel_id (string): The channel ID to upload to.
1228             filepath (string): The local path of the source.
1229
1230         Returns:
1231             dict: Uploaded File.
1232
1233         Raises:
1234             ApiException: Passed on from lower layers.
1235         """
1236         return self._post("/v4/files", multipart_formdata={'files':open(filepath, "rb"), "channel_id":(None, channel_id)}, **kwargs)["file_infos"][0]
1237
1238
1239
1240     def get_file(self, file_id, **kwargs):
1241         """
1242         Uploads a file that can later be attached to a post.
1243
1244         Args:
1245             file_id (string): The file ID to get.
1246
1247         Returns:
1248             binary: file-content.
1249
1250         Raises:
1251             ApiException: Passed on from lower layers.
1252         """
1253         return self._get("/v4/files/"+file_id, raw=True, **kwargs)
1254
1255
1256
1257 ################################################
1258 #+ **PREFERENCES** #NOT_IMPLEMENTED
1259
1260 ################################################
1261 #+ **STATUS** #NOT_IMPLEMENTED
1262
1263 ################################################
1264 #+ **EMOJI** #NOT_IMPLEMENTED
1265
1266 ################################################
1267 #+ **REACTIONS**
1268
1269
1270     def create_reaction(self, user_id, post_id, emoji_name, **kwargs):
1271         """
1272         Create a reaction.
1273
1274         Args:
1275             user_id (string): The ID of the user that made this reaction.
1276             post_id (string): The ID of the post to which this reaction was made.
1277             emoji_name (string): The name of the emoji that was used for this reaction.
1278
1279         Returns:
1280             dict: created Reaction.
1281
1282         Raises:
1283             ApiException: Passed on from lower layers.
1284         """
1285         return self._post("/v4/reactions", data={
1286             "user_id": user_id,
1287             "post_id": post_id,
1288             "emoji_name": emoji_name,
1289         }, **kwargs)
1290
1291
1292
1293 ################################################
1294 #+ **WEBHOOKS**
1295
1296
1297     def create_outgoing_hook(self, team_id, display_name, trigger_words, callback_urls, channel_id=None, description=None, trigger_when=0, **kwargs):
1298         """
1299         Create an outgoing webhook for a team.
1300
1301         Args:
1302             team_id (string): The ID of the team that the webhook watchs.
1303             display_name (string): The display name for this outgoing webhook.
1304             trigger_words (list): List of words for the webhook to trigger on.
1305             callback_urls (list): The URLs to POST the payloads to when the webhook is triggered.
1306             channel_id (string, optional): The ID of a public channel that the webhook watchs.
1307             description (string, optional): The description for this outgoing webhook.
1308             trigger_when (string, default int(0)): When to trigger the webhook, 0 when a trigger word is present at all and 1 if the message starts with a trigger word.
1309
1310         Returns:
1311             dict: created Webhook.
1312
1313         Raises:
1314             ApiException: Passed on from lower layers.
1315         """
1316         return self._post("/v4/hooks/outgoing", data={
1317             "team_id": team_id,
1318             "display_name": display_name,
1319             "trigger_words": trigger_words,
1320             "callback_urls": callback_urls,
1321             **({"channel_id": channel_id} if channel_id else {}),
1322             **({"description": description} if description else {}),
1323             "trigger_when": trigger_when,
1324             "content_type": "application/json",
1325         }, **kwargs)
1326
1327
1328
1329     def list_outgoing_hooks(self, team_id, channel_id=None, **kwargs):
1330         """
1331         Generator: Get a page of a list of outgoing webhooks. Optionally filter for a specific channel using query parameters.
1332
1333         Args:
1334             team_id (string): The ID of the team to get hooks for.
1335             channel_id (string, optional): The ID of the channel to get hooks for.
1336
1337         Returns:
1338             generates: One Webhook at a time.
1339
1340         Raises:
1341             ApiException: Passed on from lower layers.
1342         """
1343         return self._get("/v4/hooks/outgoing", params={
1344             "team_id":team_id,
1345             **({"channel_id": channel_id} if channel_id else {}),
1346         }, **kwargs)
1347
1348
1349
1350     def delete_outgoing_hook(self, hook_id, **kwargs):
1351         """
1352         Delete an outgoing webhook given the hook id.
1353
1354         Args:
1355             hook_id (string): The ID of the hook to delete.
1356
1357         Returns:
1358             string: status.
1359
1360         Raises:
1361             ApiException: Passed on from lower layers.
1362         """
1363         return self._delete("/v4/hooks/outgoing/"+hook_id, **kwargs)
1364
1365
1366
1367 ################################################
1368 #+ **COMMANDS**
1369
1370
1371     def create_slash_command(self, team_id, trigger, url, **kwargs):
1372         """
1373         Create a command for a team.
1374
1375         Args:
1376             team_id (string): Team ID to where the command should be created.
1377             trigger (string): Activation word to trigger the command.
1378             url (string): The URL that the command will make the request.
1379
1380         Returns:
1381             dict: created Command.
1382
1383         Raises:
1384             ApiException: Passed on from lower layers.
1385         """
1386         return self._post("/v4/commands", data={
1387             "team_id": team_id,
1388             "trigger": trigger,
1389             "url": url,
1390             "method": "P",
1391         }, **kwargs)
1392
1393
1394
1395     def list_custom_slash_commands_for_team(self, team_id, **kwargs):
1396         """
1397         List commands for a team.
1398
1399         Args:
1400             team_id (string): The ID of the team to get hooks for.
1401
1402         Returns:
1403             list: of Commands.
1404
1405         Raises:
1406             ApiException: Passed on from lower layers.
1407         """
1408         return self._get("/v4/commands", params={
1409             "team_id":team_id,
1410             "custom_only":True,
1411         }, **kwargs)
1412
1413
1414
1415     def update_slash_command(self, data, **kwargs):
1416         """
1417         Update a single command based on command id string and Command struct.
1418
1419         Args:
1420             data (dict): Command to update.
1421
1422         Returns:
1423             dict: updated Command.
1424
1425         Raises:
1426             ApiException: Passed on from lower layers.
1427         """
1428         return self._put("/v4/commands/"+data["id"], data=data, **kwargs)
1429
1430
1431
1432     def delete_slash_command(self, command_id, **kwargs):
1433         """
1434         Delete a command based on command id string.
1435
1436         Args:
1437             command_id (string): ID of the command to delete.
1438
1439         Returns:
1440             string: status.
1441
1442         Raises:
1443             ApiException: Passed on from lower layers.
1444         """
1445         return self._delete("/v4/commands/"+command_id, **kwargs)
1446
1447
1448
1449 ################################################
1450 #+ **OPENGRAPH** #NOT_IMPLEMENTED
1451
1452 ################################################
1453 #+ **SYSTEM** #NOT_IMPLEMENTED
1454
1455 ################################################
1456 #+ **BRAND** #NOT_IMPLEMENTED
1457
1458 ################################################
1459 #+ **OAUTH** #NOT_IMPLEMENTED
1460
1461 ################################################
1462 #+ **SAML** #NOT_IMPLEMENTED
1463
1464 ################################################
1465 #+ **LDAP** #NOT_IMPLEMENTED
1466
1467 ################################################
1468 #+ **GROUPS** #NOT_IMPLEMENTED
1469
1470 ################################################
1471 #+ **COMPLIANCE** #NOT_IMPLEMENTED
1472
1473 ################################################
1474 #+ **CLUSTER** #NOT_IMPLEMENTED
1475
1476 ################################################
1477 #+ **ELASTICSEARCH** #NOT_IMPLEMENTED
1478
1479 ################################################
1480 #+ **BLEVE** #NOT_IMPLEMENTED
1481
1482 ################################################
1483 #+ **DATARETENTION** #NOT_IMPLEMENTED
1484
1485 ################################################
1486 #+ **JOBS** #NOT_IMPLEMENTED
1487
1488 ################################################
1489 #+ **PLUGINS** #NOT_IMPLEMENTED
1490
1491 ################################################
1492 #+ **ROLES** #NOT_IMPLEMENTED
1493
1494 ################################################
1495 #+ **SCHEMES** #NOT_IMPLEMENTED
1496
1497 ################################################
1498 #+ **INTEGRATION_ACTIONS**
1499
1500
1501     def open_dialog(self, trigger_id, response_url, dialog, **kwargs):
1502         """
1503         Open an interactive dialog using a trigger ID provided by a slash command, or some other action payload. See https://docs.mattermost.com/developer/interactive-dialogs.html for more information on interactive dialogs.
1504
1505         Args:
1506             trigger_id (string): Trigger ID provided by other action.
1507             response_url (string): The URL to send the submitted dialog payload to.
1508             dialog (dict): Dialog definition.
1509
1510         Returns:
1511             string: status
1512
1513         Raises:
1514             ApiException: Passed on from lower layers.
1515         """
1516         return self._post("/v4/actions/dialogs/open", data={
1517             "trigger_id": trigger_id,
1518             "url": response_url,
1519             "dialog": dialog,
1520         }, **kwargs)
1521
1522
1523
1524 ################################################
1525 #+ **TERMS_OF_SERVICE** #NOT_IMPLEMENTED