Eager to get started? This page gives a good introduction in how to get started with Pycolo. This assumes you already have Pycolo installed. If you do not, head over to the Installation section.
First, make sure that:
Let’s get started with some simple examples.
Making a request with pycolo is very simple.
Begin by importing the pycolo module:
>>> import pycolo
Now, let’s try to get a coap/.well-known. For this example, let’s get GitHub’s public timeline
>>> r = pycolo.get('coap://coap.sieben.fr/.well-known')
Now, we have a Response object called r. We can get all the information we need from this object.
Pycolo simple API means that all forms of CoAP request are as obvious. For example, this is how you make an CoAP POST request:
>>> r = pycolo.post("coap://coap.sieben.fr/post")
Nice, right? What about the other CoAP request types: PUT, DELETE, HEAD and OPTIONS? These are all just as simple:
>>> r = pycolo.put("coap://coap.sieben.fr/put")
>>> r = pycolo.delete("coap://coap.sieben.fr/delete")
>>> r = pycolo.head("coap://coap.sieben.fr/.well-known")
>>> r = pycolo.options("coap://coap.sieben.fr/.well-known")
That’s all well and good, but it’s also only the start of what Pycolo can do.
You often want to send some sort of data in the URL’s query string. If you were constructing the URL by hand, this data would be given as key/value pairs in the URL after a question mark, e.g. coap.sieben.fr/.well-known?key=val. Pycolo allows you to provide these arguments as a dictionary, using the params keyword argument. As an example, if you wanted to pass key1=value1 and key2=value2 to coap.sieben.fr/.well-known, you would use the following code:
>>> payload = {'key1': 'value1', 'key2': 'value2'}
>>> r = pycolo.get("coap://coap.sieben.fr/.well-known", params=payload)
You can see that the URL has been correctly encoded by printing the URL:
>>> print r.url
u'coap://coap.sieben.fr/.well-known?key2=value2&key1=value1'
We can read the content of the server’s response.:
>>> import pycolo
>>> r = pycolo.get('coap://coap.sieben.fr/.well-known')
>>> r.text
'[{"resources":{"temp":42,"url":"coap://coap.sieben.fr/...
Pycolo will automatically decode content from the server. Most unicode charsets are seamlessly decoded.
When you make a request, Pycolo makes educated guesses about the encoding of the response based on the CoAP headers. The text encoding guessed by Pycolo is used when you access r.text. You can find out what encoding Pycolo is using, and change it, using the r.encoding property:
>>> r.encoding
'utf-8'
>>> r.encoding = 'ISO-8859-1'
If you change the encoding, Pycolo will use the new value of r.encoding whenever you call r.text.
Pycolo will also use custom encodings in the event that you need them. If you have created your own encoding and registered it with the codecs module, you can simply use the codec name as the value of r.encoding and Pycolo will handle the decoding for you.
You can also access the response body as bytes, for non-text requests:
>>> r.content
b'[{"resources":{"temp":42,"url":"coap://coap.sieben.fr/...
The gzip and deflate transfer-encodings are automatically decoded for you.
For example, to create an image from binary data returned by a request, you can use the following code:
>>> from PIL import Image
>>> from StringIO import StringIO
>>> i = Image.open(StringIO(r.content))
There’s also a builtin JSON decoder, in case you’re dealing with JSON data:
>>> import pycolo
>>> r = pycolo.get('coap://coap.sieben.fr/.well-known.json')
>>> r.json
[{u'repository': {u'open_issues': 0, u'url': 'coap://coap.sieben.fr/...
In case the JSON decoding fails, r.json simply returns None.
In the rare case that you’d like to get the absolute raw socket response from the server, you can access r.raw:
>>> r.raw.read(10)
'\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\x03'
If you’d like to add CoAP headers to a request, simply pass in a dict to the headers parameter.
For example, we didn’t specify our content-type in the previous example:
>>> import json
>>> url = 'coap://coap.sieben.fr/some/endpoint'
>>> payload = {'some': 'data'}
>>> headers = {'content-type': 'application/json'}
>>> r = pycolo.post(url, data=json.dumps(payload), headers=headers)
Typically, you want to send some form-encoded data — much like an HTML form. To do this, simply pass a dictionary to the data argument. Your dictionary of data will automatically be form-encoded when the request is made:
>>> payload = {'key1': 'value1', 'key2': 'value2'}
>>> r = pycolo.post("coap://coap.sieben.fr/post", data=payload)
>>> print r.text
{
// ...snip... //
"form": {
"key2": "value2",
"key1": "value1"
},
// ...snip... //
}
There are many times that you want to send data that is not form-encoded. If you pass in a string instead of a dict, that data will be posted directly.
For example, the GitHub API v3 accepts JSON-Encoded POST/PATCH data:
>>> import json
>>> url = 'coap://coap.sieben.fr/some/endpoint'
>>> payload = {'some': 'data'}
>>> r = pycolo.post(url, data=json.dumps(payload))
Pycolo makes it simple to upload Multipart-encoded files:
>>> url = 'coap://coap.sieben.fr/post'
>>> files = {'file': open('report.csv', 'rb')}
>>> r = pycolo.post(url, files=files)
>>> r.text
{
// ...snip... //
"files": {
"file": "<censored...binary...data>"
},
// ...snip... //
}
You can set the filename explicitly:
>>> url = 'coap://coap.sieben.fr/post'
>>> files = {'file': ('report.csv', open('report.csv', 'rb'))}
>>> r = pycolo.post(url, files=files)
>>> r.text
{
// ...snip... //
"files": {
"file": "<censored...binary...data>"
},
// ...snip... //
}
If you want, you can send strings to be received as files:
>>> url = 'coap://coap.sieben.fr/post'
>>> files = {'file': ('report.csv', 'some,data,to,send\nanother,row,to,send\n')}
>>> r = pycolo.post(url, files=files)
>>> r.text
{
// ...snip... //
"files": {
"file": "some,data,to,send\\nanother,row,to,send\\n"
},
// ...snip... //
}
We can check the response status code:
>>> r = pycolo.get('coap://coap.sieben.fr/.well-known')
>>> r.status_code
200
Pycolo also comes with a built-in status code lookup object for easy reference:
>>> r.status_code == pycolo.codes.ok
True
If we made a bad request (non-200 response), we can raise it with Response.raise_for_status():
>>> bad_r = pycolo.get('coap://coap.sieben.fr/status/404')
>>> bad_r.status_code
404
>>> bad_r.raise_for_status()
Traceback (most recent call last):
raise coap_error
pycolo.exceptions.COAPError: 404 Client Error
But, since our status_code for r was 200, when we call raise_for_status() we get:
>>> r.raise_for_status()
None
All is well.
We can view the server’s response headers using a Python dictionary:
>>> r.headers
{
'status': '200 OK',
'content-encoding': 'text',
'transfer-encoding': 'chunked',
'connection': 'close',
'server': 'contiki/Erbium',
'x-runtime': '148ms',
'etag': '"e1ca502697e5c9317743dc078f67693f"',
'content-type': 'application/json; charset=utf-8'
}
The dictionary is special, though: it’s made just for CoAP headers, CoAP headers are case-insensitive.
So, we can access the headers using any capitalization we want:
>>> r.headers['Content-Type']
'application/json; charset=utf-8'
>>> r.headers.get('content-type')
'application/json; charset=utf-8'
If a header doesn’t exist in the Response, its value defaults to None:
>>> r.headers['X-Random']
None
You can tell pycolo to stop waiting for a response after a given number of seconds with the timeout parameter:
>>> pycolo.get('coap://coap.sieben.fr/.well-known', timeout=0.001)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
pycolo.exceptions.Timeout: Request timed out.
Note:
timeout only effects the connection process itself, not the downloading of the response body.