Skip to content

Commit 2945bf3

Browse files
cmlcciecmlccie
authored
Convert README to reStructuredText and Revise #15 (#18)
New README.rst updated to use a narrative format and reStructuredText.
1 parent b4beba2 commit 2945bf3

File tree

3 files changed

+202
-74
lines changed

3 files changed

+202
-74
lines changed

‎README.md

Lines changed: 0 additions & 73 deletions
This file was deleted.

‎README.rst

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
=============
2+
ciscosparkapi
3+
=============
4+
5+
-------------------------------------------------------------------------
6+
Simple, lightweight, scalable Python API wrapper for the Cisco Spark APIs
7+
-------------------------------------------------------------------------
8+
9+
.. image:: https://img.shields.io/pypi/v/ciscosparkapi.svg
10+
:target: https://pypi.python.org/pypi/ciscosparkapi
11+
12+
Sure, working with the Cisco Spark APIs is easy (see `developer.ciscospark.com`_). They are *RESTful*, *naturally structured*, require only a *simple Access Token for authentication*, and *the data is elegantly represented in intuitive JSON*. What could be easier?
13+
14+
.. code-block:: python
15+
16+
import requests
17+
18+
URL = 'https://api.ciscospark.com/v1/messages'
19+
ACCESS_TOKEN = '<your_access_token>'
20+
ROOM_ID = '<room_id>'
21+
MESSAGE_TEXT = '<message_text>'
22+
23+
headers = {'Authorization': 'Bearer ' + ACCESS_TOKEN,
24+
'Content-type': 'application/json;charset=utf-8'}
25+
post_data = {'roomId': ROOM_ID,
26+
'text': MESSAGE_TEXT}
27+
response = requests.post(URL, json=post_data, headers=headers)
28+
if response.status_code == 200:
29+
# Great your message was posted!
30+
message_id = response.json['id']
31+
message_text = response.json['id']
32+
print("New message created, with ID:", message_id)
33+
print(message_text)
34+
else:
35+
# Oops something went wrong... Better do something about it.
36+
print(response.status_code, response.text)
37+
38+
Like I said, *EASY*. However, in use, the code can be rather repetitive...
39+
40+
- You have to setup the environment every time
41+
- You have to remember URLs and request arguments (or reference the docs)
42+
- You have to parse the returned JSON and setup variables to hold the attributes you need
43+
- When requesting lists of items, you have to deal with pagination_
44+
45+
46+
Enter **ciscosparkapi**, a simple API wrapper that wraps all of the Spark API calls and returned JSON objects within native Python objects and function calls.
47+
48+
With ciscosparkapi, the above Python code can be consolidated to the following:
49+
50+
.. code-block:: python
51+
52+
from ciscosparkapi import CiscoSparkAPI
53+
54+
api = CiscoSparkAPI()
55+
try:
56+
message = api.messages.create('<room_id>', text='<message_text>')
57+
print("New message created, with ID:", message.id)
58+
print(message.text)
59+
except SparkApiError as e:
60+
print(e)
61+
62+
The ciscosparkapi package handles all of this for you:
63+
64+
+ Reads your Spark access token from a ``SPARK_ACCESS_TOKEN`` environment variable
65+
+ Wraps and represents all Spark API calls as a simple hierarchical tree of native-Python methods (with default arguments provided everywhere possible!)
66+
+ If your Python IDE supports **auto-completion** (like PyCharm_), you can navigate the available methods and object attributes right within your IDE
67+
+ Represents all returned JSON objects as native Python objects - you can access all of the object's attributes using native *dot.syntax*
68+
+ **Automatic and Transparent Pagination!** When requesting 'lists of objects' from Spark, requests for additional pages of responses are efficiently and automatically requested as needed
69+
+ Multipart encoding and uploading of local files, when creating messages with local file attachments
70+
71+
All of this, combined, lets you do powerful things simply:
72+
73+
.. code-block:: python
74+
75+
from ciscosparkapi import CiscoSparkAPI
76+
77+
api = CiscoSparkAPI()
78+
79+
# Find all rooms that have 'ciscosparkapi Demo' in their title
80+
all_rooms = api.rooms.list()
81+
demo_rooms = [room for room in all_rooms if 'ciscosparkapi Demo' in room.title]
82+
83+
# Delete all of the demo rooms
84+
for room in demo_rooms:
85+
api.rooms.delete(room.id)
86+
87+
# Create a new demo room
88+
demo_room = api.rooms.create('ciscosparkapi Demo')
89+
90+
# Add people to the new demo room
91+
email_addresses = ["[email protected]", "[email protected]"]
92+
for email in email_addresses:
93+
api.memberships.create(demo_room.id, personEmail=email)
94+
95+
# Post a message to the new room, and upload a file
96+
api.message.create(demo_room.id, text="Welcome to the room!", files=["welcome.jpg"])
97+
98+
That's more than six Spark API calls in less than 23 lines of script code (with comments)!
99+
...and likely more than that depending on how many rooms are returned by Spark (remember pagination is handled for you automatically)
100+
101+
102+
Installation
103+
------------
104+
105+
Installation and updating of ciscosparkapi is easy:
106+
107+
**Install via PIP**
108+
109+
.. code-block:: bash
110+
111+
$ pip install ciscosparkapi
112+
113+
**Upgrading to the latest Version**
114+
115+
.. code-block:: bash
116+
117+
$ pip install ciscosparkapi --upgrade
118+
119+
120+
Releases & Release Notes
121+
------------------------
122+
123+
Complete and usable *Beta* releases_ have been published for this package.
124+
125+
While the package APIs may change (while the package is in beta), the package capabilities should all be functional. If you experience any issues using this package, please report them using the issues_ log.
126+
127+
Please see the releases_ page for release notes on the incremental functionality and bug fixes that have been incorporated into the published releases.
128+
129+
130+
Examples
131+
--------
132+
133+
Looking for some examples or sample scripts? Check out the examples_ folder!
134+
135+
Have a good example script you would like to share? Please feel free to contribute!
136+
137+
138+
Documentation
139+
-------------
140+
141+
All of the user-facing methods have complete docstrings. You can view the docstrings for any method either from the `source files`_, or by using the Python ``help()`` function.
142+
143+
.. code-block:: python
144+
145+
>>> from ciscosparkapi import CiscoSparkAPI
146+
>>> api = CiscoSparkAPI()
147+
>>> help(api.messages.create)
148+
create(self, roomId=None, toPersonId=None, toPersonEmail=None, text=None, markdown=None, files=None) method of ciscosparkapi.api.messages.MessagesAPI instance
149+
Posts a message to a room.
150+
151+
Posts a message, and optionally, a media content attachment, to a room.
152+
153+
You must specify either a roomId, toPersonId or toPersonEmail when
154+
posting a message, and you must supply some message content (text,
155+
markdown, files).
156+
157+
Args:
158+
roomId(string_types): The room ID.
159+
toPersonId(string_types): The ID of the recipient when sending a
160+
private 1:1 message.
161+
...
162+
163+
Full standalone online documentation is coming soon (it's on the backlog!).
164+
165+
166+
Contribution
167+
------------
168+
169+
ciscosparkapi_ and it's sister project ciscosparksdk_ are community development projects. Feedback, thoughts, ideas and code contributions are most welcome!
170+
171+
To contribute to ciscosparkapi please use the following resources:
172+
173+
Feedback, issues, thoughts and ideas... Please use the issues_ log.
174+
175+
Interested in contributing code?
176+
177+
#. Check for open issues_ or create a new one.
178+
179+
* Assign yourself to the issue you want to work on, and communicate with any others that may be working the issue.
180+
* Project workflow is being managed via the GitHub projects_ feature. Move your issue to the 'In Progress' column of the project being worked.
181+
182+
#. Review the project charter_ for coding standards and practices.
183+
#. Fork a copy of `the repository`_.
184+
#. Add your code to your forked repository.
185+
#. Submit a `pull request`_, and move your issue to the 'Code Review' column on the projects_ page.
186+
187+
188+
.. _developer.ciscospark.com: https://developer.ciscospark.com
189+
.. _pagination: https://developer.ciscospark.com/pagination.html
190+
.. _PyCharm: https://www.jetbrains.com/pycharm/
191+
.. _examples: https://github.com/CiscoDevNet/ciscosparkapi/tree/master/examples
192+
.. _source files: https://github.com/CiscoDevNet/ciscosparkapi/tree/master/ciscosparkapi
193+
.. _ciscosparkapi: https://github.com/CiscoDevNet/ciscosparkapi
194+
.. _ciscosparksdk: https://github.com/CiscoDevNet/ciscosparksdk
195+
.. _issues: https://github.com/CiscoDevNet/ciscosparkapi/issues
196+
.. _projects: https://github.com/CiscoDevNet/ciscosparkapi/projects
197+
.. _pull requests: https://github.com/CiscoDevNet/ciscosparkapi/pulls
198+
.. _releases: https://github.com/CiscoDevNet/ciscosparkapi/releases
199+
.. _charter: https://github.com/CiscoDevNet/spark-python-packages-team/blob/master/Charter.md
200+
.. _the repository: ciscosparkapi_
201+
.. _pull request: `pull requests`_

‎setup.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414

1515
# Get the long description from the README file
16-
with open(path.join(here, 'README.md'), encoding='utf-8') as f:
16+
with open(path.join(here, 'README.rst'), encoding='utf-8') as f:
1717
long_description = f.read()
1818

1919

0 commit comments

Comments
 (0)