You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Please use the issues_ page to report any issues or feedback regarding the
19
-
documentation.
20
-
21
-
22
-
Introduction
23
-
------------
24
-
25
-
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?
print("New message created, with ID:", message_id)
46
-
print(message_text)
47
-
else:
48
-
# Oops something went wrong... Better do something about it.
49
-
print(response.status_code, response.text)
50
-
51
-
Like I said, EASY. However, in use, the code can become rather repetitive...
52
-
53
-
- You have to setup the environment every time
54
-
- You have to remember URLs and request arguments (or reference the docs)
55
-
- You have to parse the returned JSON and setup variables to hold the attributes you need
56
-
- When requesting lists of items, you have to deal with pagination_
57
-
58
-
59
-
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.
60
-
61
-
With ciscosparkapi, the above Python code can be consolidated to the following:
print("New message created, with ID:", message.id)
71
-
print(message.text)
72
-
except SparkApiError as e:
73
-
print(e)
74
-
75
-
The ciscosparkapi package handles all of this for you:
76
-
77
-
+ Reads your Spark access token from a ``SPARK_ACCESS_TOKEN`` environment variable
78
-
+ Wraps and represents all Spark API calls as a simple hierarchical tree of native-Python methods (with default arguments provided everywhere possible!)
79
-
+ If your Python IDE supports **auto-completion** (like PyCharm_), you can navigate the available methods and object attributes right within your IDE
80
-
+ Represents all returned JSON objects as native Python objects - you can access all of the object's attributes using native *dot.syntax*
81
-
+ **Automatic and Transparent Pagination!** When requesting 'lists of objects' from Spark, requests for additional pages of responses are efficiently and automatically requested as needed
82
-
+ Multipart encoding and uploading of local files, when creating messages with local file attachments
83
-
84
-
All of this, combined, lets you do powerful things simply:
14
+
**ciscosparkapi** is a *community developed* Pythonic wrapping of the Cisco
15
+
Spark APIs, which makes working with Cisco Spark in Python a *native* and
16
+
*natural* experience!
85
17
86
18
.. code-block:: python
87
19
@@ -109,14 +41,49 @@ All of this, combined, lets you do powerful things simply:
109
41
api.messages.create(demo_room.id, text="Welcome to the room!",
That's more than six Spark API calls in less than 23 lines of script code (with comments)!
113
-
...and likely more than that depending on how many rooms are returned by Spark (remember pagination is handled for you automatically)
44
+
45
+
That's more than 6 Spark API calls in less than 23 lines of code (with comments
46
+
and whitespace), and likely more than that since ciscosparkapi handles
47
+
pagination_ for you automatically!
48
+
49
+
ciscosparkapi makes your life better... `Learn how!`__
50
+
51
+
__Introduction_
52
+
53
+
54
+
Features
55
+
--------
56
+
57
+
ciscosparkapi does all of this for you...
58
+
59
+
+ Transparently sources your Spark credentials from your local environment
60
+
61
+
+ Provides and uses default arguments and settings everywhere possible, so you
62
+
don't have to think about things like API endpoint URLs, HTTP headers and
63
+
JSON formats
64
+
65
+
+ Represents all Cisco Spark API interactions using native Python tools
66
+
67
+
+ Authentication and Connection to the Cisco Spark Cloud ==>
68
+
**CiscoSparkAPI** 'Connection Object'
69
+
70
+
+ API Calls ==> Hierarchically organized method calls underneath a
71
+
**CiscoSparkAPI** 'Connection Object'
72
+
73
+
+ Returned Data Objects ==> Native Python objects
74
+
75
+
+ **Automatic and transparent pagination!**
76
+
77
+
+ Multipart encoding and uploading of local files
78
+
79
+
+ Auto-completion in your favorite IDE, descriptive exceptions, and so much
80
+
more...
114
81
115
82
116
83
Installation
117
84
------------
118
85
119
-
Installation and updating of ciscosparkapi is easy:
86
+
Installing and upgrading ciscosparkapi is easy:
120
87
121
88
**Install via PIP**
122
89
@@ -131,85 +98,76 @@ Installation and updating of ciscosparkapi is easy:
131
98
$ pip install ciscosparkapi --upgrade
132
99
133
100
134
-
Releases & Release Notes
135
-
------------------------
136
-
137
-
Complete and usable *Beta* releases_ have been published for this package.
101
+
Documentation
102
+
-------------
138
103
139
-
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.
104
+
**Excellent documentation is now available at:**
105
+
http://ciscosparkapi.readthedocs.io
140
106
141
-
Please see the releases_ page for release notes on the incremental functionality and bug fixes that have been incorporated into the published releases.
107
+
Check out the Quickstart_ to dive in and begin using ciscosparkapi.
142
108
143
109
144
110
Examples
145
111
--------
146
112
147
113
Looking for some examples or sample scripts? Check out the examples_ folder!
148
114
149
-
Have a good example script you would like to share? Please feel free to contribute!
150
-
151
-
152
-
Documentation
153
-
-------------
115
+
Have a good example script you would like to share? Please feel free to
116
+
`contribute`__!
154
117
155
-
**Complete user documentation is now available!**
118
+
__Contribution_
156
119
157
-
Read the Docs at `ciscosparkapi.readthedocs.io`_ !!
158
120
159
-
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.
121
+
Release Notes
122
+
-------------
160
123
161
-
.. code-block:: python
124
+
Complete and fully functional *Beta* releases have been published. Please
125
+
see the releases_ page for release notes on the incremental functionality and
126
+
bug fixes incorporated into the published releases.
**Note:** The package APIs may change, while the package is in beta.
168
129
169
-
Posts a message, and optionally, a media content attachment, to a room.
170
130
171
-
You must specify either a roomId, toPersonId or toPersonEmail when
172
-
posting a message, and you must supply some message content (text,
173
-
markdown, files).
131
+
Support
132
+
-------
174
133
175
-
Args:
176
-
roomId(string_types): The room ID.
177
-
toPersonId(string_types): The ID of the recipient when sending a
178
-
private 1:1 message.
179
-
...
134
+
This is a *community developed* and *community supported* project. If you
135
+
experience any issues using this package, please report them using the
136
+
issues_ log.
180
137
181
138
182
139
Contribution
183
140
------------
184
141
185
-
ciscosparkapi_ and it's sister project ciscosparksdk_ are community development projects. Feedback, thoughts, ideas and code contributions are most welcome!
142
+
ciscosparkapi_ and it's sister project ciscosparksdk_ are community
143
+
development projects. Feedback, thoughts, ideas and code contributions are
144
+
most welcome!
186
145
187
-
To contribute to ciscosparkapi please use the following resources:
146
+
**Feedback, issues, thoughts and ideas...**
188
147
189
-
Feedback, issues, thoughts and ideas... Please use the issues_ log.
148
+
Please use the issues_ log.
190
149
191
-
Interested in contributing code?
150
+
**Interested in contributing code?**
192
151
193
-
#. Check for open issues_ or create a new one.
152
+
#. Check for open issues_ or create a new 'issue' for the item you want
153
+
to work on.
194
154
195
-
* Assign yourself to the issue you want to work on, and communicate with any others that may be working the issue.
196
-
* Project workflow is being managed via the GitHub projects_ feature. Move your issue to the 'In Progress' column of the project being worked.
155
+
* Assign yourself to the issue, and communicate with any others that may be
156
+
working the issue.
197
157
198
158
#. Review the project charter_ for coding standards and practices.
199
159
#. Fork a copy of `the repository`_.
200
160
#. Add your code to your forked repository.
201
-
#. Submit a `pull request`_, and move your issue to the 'Code Review' column on the projects_ page.
0 commit comments