Skip to content

Commit f7b1a73

Browse files
cmlcciecmlccie
committed
Initial MembershipsAPI wrapper
Add wrapper classes for the Cisco Spark Memberships-API.
1 parent 474adb7 commit f7b1a73

File tree

2 files changed

+280
-3
lines changed

2 files changed

+280
-3
lines changed

‎ciscosparkapi/__init__.py

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
from exceptions import ciscosparkapiException, SparkApiError
22
from restsession import RestSession
3-
from api.rooms import Room, RoomsAPI
43
from api.people import Person, PeopleAPI
5-
4+
from api.rooms import Room, RoomsAPI
5+
from api.memberships import Membership, MembershipsAPI
66

77
class CiscoSparkAPI(object):
88
"""Cisco Spark API wrapper class."""
@@ -22,8 +22,9 @@ def __init__(self, access_token, base_url=None, timeout=None):
2222
self.session = RestSession(access_token, **session_args)
2323

2424
# Spark API wrappers
25-
self.rooms = RoomsAPI(self.session)
2625
self.people = PeopleAPI(self.session)
26+
self.rooms = RoomsAPI(self.session)
27+
self.memberships = MembershipsAPI(self.session)
2728

2829
@property
2930
def access_token(self):

‎ciscosparkapi/api/memberships.py

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
"""Cisco Spark Memberships-API wrapper classes.
2+
3+
Classes:
4+
Membership: Models a Spark 'membership' JSON object as a native Python
5+
object.
6+
MembershipsAPI: Wrappers the Cisco Spark Memberships-API and exposes the
7+
API calls as Python method calls that return native Python objects.
8+
9+
"""
10+
11+
12+
from ciscosparkapi.exceptions import ciscosparkapiException
13+
from ciscosparkapi.helper import utf8, generator_container
14+
from ciscosparkapi.restsession import RestSession
15+
from ciscosparkapi.sparkdata import SparkData
16+
17+
18+
class Membership(SparkData):
19+
"""Model a Spark 'membership' JSON object as a native Python object."""
20+
21+
def __init__(self, json):
22+
"""Init a new Membership data object from a JSON dictionary or string.
23+
24+
Args:
25+
json(dict, unicode, str): Input JSON object.
26+
27+
Raises:
28+
TypeError: If the input object is not a dictionary or string.
29+
30+
"""
31+
super(Membership, self).__init__(json)
32+
33+
@property
34+
def id(self):
35+
return self._json[u'id']
36+
37+
@property
38+
def roomId(self):
39+
return self._json[u'roomId']
40+
41+
@property
42+
def personId(self):
43+
return self._json[u'personId']
44+
45+
@property
46+
def personEmail(self):
47+
return self._json[u'personEmail']
48+
49+
@property
50+
def personDisplayName(self):
51+
return self._json[u'personDisplayName']
52+
53+
@property
54+
def isModerator(self):
55+
return self._json[u'isModerator']
56+
57+
@property
58+
def isMonitor(self):
59+
return self._json[u'isMonitor']
60+
61+
@property
62+
def created(self):
63+
return self._json[u'created']
64+
65+
66+
class MembershipsAPI(object):
67+
"""Cisco Spark Memberships-API wrapper class.
68+
69+
Wrappers the Cisco Spark Memberships-API and exposes the API calls as
70+
Python method calls that return native Python objects.
71+
72+
Attributes:
73+
session(RestSession): The RESTful session object to be used for API
74+
calls to the Cisco Spark service.
75+
76+
"""
77+
78+
def __init__(self, session):
79+
"""Init a new MembershipsAPI object with the provided RestSession.
80+
81+
Args:
82+
session(RestSession): The RESTful session object to be used for
83+
API calls to the Cisco Spark service.
84+
85+
Raises:
86+
AssertionError: If the parameter types are incorrect.
87+
88+
"""
89+
assert isinstance(session, RestSession)
90+
super(MembershipsAPI, self).__init__()
91+
self.session = session
92+
93+
@generator_container
94+
def list(self, roomId=None, personId=None, personEmail=None, max=None):
95+
"""List room memberships.
96+
97+
By default, lists memberships for rooms to which the authenticated
98+
user belongs.
99+
100+
Use query parameters to filter the response.
101+
102+
Use roomId to list memberships for a room, by ID.
103+
104+
Use either personId or personEmail to filter the results.
105+
106+
This method supports Cisco Spark's implementation of RFC5988 Web
107+
Linking to provide pagination support. It returns a generator
108+
container that incrementally yield all memberships returned by the
109+
query. The generator will automatically request additional 'pages' of
110+
responses from Spark as needed until all responses have been returned.
111+
The container makes the generator safe for reuse. A new API call will
112+
be made, using the same parameters that were specified when the
113+
generator was created, every time a new iterator is requested from the
114+
container.
115+
116+
Args:
117+
roomId(unicode, str): List memberships for the room with roomId.
118+
personId(unicode, str): Filter results to include only those with
119+
personId.
120+
personEmail(unicode, str): Filter results to include only those
121+
with personEmail.
122+
max(int): Limits the maximum number of memberships returned from
123+
the Spark service per request.
124+
125+
126+
Yields:
127+
Membership: The the next membership from the Cisco Spark query.
128+
129+
Raises:
130+
AssertionError: If the parameter types are incorrect.
131+
ciscosparkapiException: If a personId or personEmail argument is
132+
specified without providing a roomId argument.
133+
SparkApiError: If the Cisco Spark cloud returns an error.
134+
135+
"""
136+
# Process args
137+
assert roomId is None or isinstance(roomId, basestring)
138+
assert personId is None or isinstance(personId, basestring)
139+
assert personEmail is None or isinstance(personEmail, basestring)
140+
assert max is None or isinstance(max, int)
141+
params = {}
142+
if roomId:
143+
params[u'roomId'] = utf8(roomId)
144+
if personId:
145+
params[u'personId'] = utf8(personId)
146+
elif personEmail:
147+
params[u'personEmail'] = utf8(personEmail)
148+
elif personId or personEmail:
149+
error_message = "A roomId must be specified. A personId or " \
150+
"personEmail filter may only be specified when " \
151+
"requesting the memberships for a room with the " \
152+
"roomId argument."
153+
raise ciscosparkapiException(error_message)
154+
if max:
155+
params[u'max'] = max
156+
# API request - get items
157+
items = self.session.get_items('memberships', params=params)
158+
# Yield Person objects created from the returned items JSON objects
159+
for item in items:
160+
yield Membership(item)
161+
162+
def create(self, roomId, personId=None, personEmail=None,
163+
isModerator=False):
164+
"""Add someone to a room by Person ID or email address.
165+
166+
Add someone to a room by Person ID or email address; optionally
167+
making them a moderator.
168+
169+
Args:
170+
roomId(unicode, str): ID of the room to which the person will be
171+
added.
172+
personId(unicode, str): ID of the person to be added to the room.
173+
personEmail(unicode, str): Email address of the person to be added
174+
to the room.
175+
isModerator(bool): If True, adds the person as a moderator for the
176+
room. If False, adds the person as normal member of the room.
177+
178+
Raises:
179+
AssertionError: If the parameter types are incorrect.
180+
ciscosparkapiException: If neither a personId or personEmail are
181+
provided.
182+
SparkApiError: If the Cisco Spark cloud returns an error.
183+
184+
"""
185+
# Process args
186+
assert isinstance(roomId, basestring)
187+
assert personId is None or isinstance(personId, basestring)
188+
assert personEmail is None or isinstance(personEmail, basestring)
189+
assert isModerator is None or isinstance(isModerator, bool)
190+
post_data = {}
191+
post_data[u'roomId'] = utf8(roomId)
192+
if personId:
193+
post_data[u'personId'] = utf8(personId)
194+
elif personEmail:
195+
post_data[u'personEmail'] = utf8(personEmail)
196+
else:
197+
error_message = "personId or personEmail must be provided to " \
198+
"add a person to a room. Neither were provided."
199+
raise ciscosparkapiException(error_message)
200+
post_data[u'isModerator'] = isModerator
201+
# API request
202+
json_obj = self.session.post('memberships', json=post_data)
203+
# Return a Membership object created from the response JSON data
204+
return Membership(json_obj)
205+
206+
def get(self, membershipId):
207+
"""Get details for a membership by ID.
208+
209+
Args:
210+
membershipId(unicode, str): The membershipId of the membership.
211+
212+
Raises:
213+
AssertionError: If the parameter types are incorrect.
214+
SparkApiError: If the Cisco Spark cloud returns an error.
215+
216+
"""
217+
# Process args
218+
assert isinstance(membershipId, basestring)
219+
# API request
220+
json_obj = self.session.get('memberships/'+membershipId)
221+
# Return a Membership object created from the response JSON data
222+
return Membership(json_obj)
223+
224+
def update(self, membershipId, **update_attributes):
225+
"""Update details for a membership.
226+
227+
Args:
228+
membershipId(unicode, str): The membershipId of the membership to
229+
be updated.
230+
231+
**update_attributes:
232+
isModerator(bool): If True, sets the person as a moderator for the
233+
room. If False, removes the person as a moderator for the room.
234+
235+
Returns:
236+
A Person object with the updated Spark membership details.
237+
238+
Raises:
239+
AssertionError: If the parameter types are incorrect.
240+
ciscosparkapiException: If an update attribute is not provided.
241+
SparkApiError: If the Cisco Spark cloud returns an error.
242+
243+
"""
244+
# Process args
245+
assert isinstance(membershipId, basestring)
246+
# Process update_attributes keyword arguments
247+
if not update_attributes:
248+
error_message = "At least one **update_attributes keyword " \
249+
"argument must be specified."
250+
raise ciscosparkapiException(error_message)
251+
put_data = {}
252+
for param, value in update_attributes.items():
253+
if isinstance(value, basestring):
254+
value = utf8(value)
255+
put_data[utf8(param)] = value
256+
# API request
257+
json_obj = self.session.post('memberships', json=put_data)
258+
# Return a Membership object created from the response JSON data
259+
return Membership(json_obj)
260+
261+
def delete(self, membershipId):
262+
"""Delete a membership, by ID.
263+
264+
Args:
265+
membershipId(unicode, str): The membershipId of the membership to
266+
be deleted.
267+
268+
Raises:
269+
AssertionError: If the parameter types are incorrect.
270+
SparkApiError: If the Cisco Spark cloud returns an error.
271+
272+
"""
273+
# Process args
274+
assert isinstance(membershipId, basestring)
275+
# API request
276+
self.session.delete('memberships/'+membershipId)

0 commit comments

Comments
 (0)