Permalink
Browse files

Made README easier to read raw

  • Loading branch information...
1 parent 76e7abf commit 46f99cae03d96918f033d128e17b8583f683d610 @pilliq committed Dec 28, 2012
Showing with 51 additions and 18 deletions.
  1. +51 −18 README.md
View
@@ -6,7 +6,8 @@ A Python client for [Scratch](scratch.mit.edu)
1. Start up Scratch
-2. [Enable remote sensor connections](http://wiki.scratch.mit.edu/wiki/Remote_Sensor_Connections#Enabling), or "Host Mesh" in [BYOB](http://byob.berkeley.edu/)
+2. [Enable remote sensor connections](http://wiki.scratch.mit.edu/wiki/Remote_Sensor_Connections#Enabling),
+ or "Host Mesh" in [BYOB](http://byob.berkeley.edu/)
3. Create a variable for all sprites named `foo`
@@ -30,7 +31,8 @@ Or
# easy_install scratchpy
```
-If you're installing from source, you can untar the source tarball, `cd` into the project directory and run
+If you're installing from source, you can untar the source tarball, `cd` into
+the project directory and run
```
# make install
@@ -46,7 +48,9 @@ import scratch
s = scratch.Scratch()
```
-This will create a connection on `localhost` port 42001 and set `s.connected` to `True`. If you want to change the host or port, you can provide them to the constructor
+This will create a connection on `localhost` port 42001 and set `s.connected`
+to `True`. If you want to change the host or port, you can provide them to the
+constructor
```
s = scratch.Scratch(host='0.0.0.0', port=40000)
@@ -59,7 +63,8 @@ s.connect()
```
### Broadcasting
-Broadcasting messages to Scratch will function like a broadcast block in Scratch. You can broadcast either a single message
+Broadcasting messages to Scratch will function like a broadcast block in
+Scratch. You can broadcast either a single message
```
s.broadcast('Hello, Scratch!')
@@ -71,10 +76,13 @@ Or a list of messages
s.broadcast(['Hello, Scratch!', 'How are you doing?'])
```
-Actually, you can give `broadcast` any iterable object (list, tuple, set, generator, etc.).
+Actually, you can give `broadcast` any iterable object (list, tuple, set,
+generator, etc.).
### Sensor updates
-Sending sensor updates to Scratch will create new sensors in the Sensing category, or update sensors with new values. The `sensorupdate` method accepts a dict whose keys are sensor names, and values are sensor values.
+Sending sensor updates to Scratch will create new sensors in the Sensing
+category, or update sensors with new values. The `sensorupdate` method accepts
+a dict whose keys are sensor names, and values are sensor values.
```
s.sensorupdate({'temperature' : 75})
@@ -87,28 +95,43 @@ Use the `receive` method to receive messages from Scratch
msg = s.receive()
```
-A call to `receive` will block until it reads a message from Scratch. If the call is successful, it returns a tuple of the message received. If the call failed, it raises an exception. If the message received is not a proper Scratch message, `receive` returns `None`.
+A call to `receive` will block until it reads a message from Scratch. If the
+call is successful, it returns a tuple of the message received. If the call
+failed, it raises an exception. If the message received is not a proper Scratch
+message, `receive` returns `None`.
-The first element of the tuple will be the message type and the second element will be the message data.
+The first element of the tuple will be the message type and the second element
+will be the message data.
-Two types of messages can be received: broadcast messages and sensor update messages.
+Two types of messages can be received: broadcast messages and sensor update
+messages.
#### Broadcasts
-Broadcast messages are received anytime a broadcast block is executed in Scratch. The message data is a string of the message that was broadcast. An example broadcast message returned from `receive` looks like this:
+Broadcast messages are received anytime a broadcast block is executed in
+Scratch. The message data is a string of the message that was broadcast. An
+example broadcast message returned from `receive` looks like this:
```
('broadcast', 'Hello, Python!')
```
#### Sensor updates
-Sensor updates are received when global variables (i.e. variables created for all sprites) are created, or when their value changes. The message data is a dict that maps global variable names to their values. Suppose you created two variables, `foo` and `bar`. Upon their creation, `receive` would return a message that looks like this:
+Sensor updates are received when global variables (i.e. variables created for
+all sprites) are created, or when their value changes. The message data is a
+dict that maps global variable names to their values. Suppose you created two
+variables, `foo` and `bar`. Upon their creation, `receive` would return a
+message that looks like this:
```
('sensor-update', {'foo': 0, 'bar': 0})
```
#### Handling Multiple Messages
-`receive` returns only one message. If Scratch has sent more than one message, they will stay on the network buffer until `receive` is called again. To receive all the messages from Scratch you must repeatedly call `receive`. A nice way to handle this is to have a generator function that yields a message everytime it receives, and exits on error.
+`receive` returns only one message. If Scratch has sent more than one message,
+they will stay on the network buffer until `receive` is called again. To
+receive all the messages from Scratch you must repeatedly call `receive`. A
+nice way to handle this is to have a generator function that yields a message
+everytime it receives, and exits on error.
```
def listen():
@@ -129,7 +152,8 @@ for msg in listen():
# code to handle sensor updates
```
-If an error occurs or the connection to Scratch is closed, Python simply exits the loop.
+If an error occurs or the connection to Scratch is closed, Python simply exits
+the loop.
### Disconnecting
To close a connection to Scratch
@@ -138,16 +162,25 @@ To close a connection to Scratch
s.disconnect()
```
-A disconnection may occur without an explicit call to `disconnect`. These usually happen when either Scratch is closed, remote sensor connections are disabled, or when there is something up with the network.
+A disconnection may occur without an explicit call to `disconnect`. These
+usually happen when either Scratch is closed, remote sensor connections are
+disabled, or when there is something up with the network.
### Errors
-There are two kinds of errors that can be caught in `connect`, `receive`, `broadcast`, and `sensorupdate`:
+There are two kinds of errors that can be caught in `connect`, `receive`,
+`broadcast`, and `sensorupdate`:
-`ScratchError` is raised when there are errors with the network (e.g. connection refused, connection established, etc. basically any error from [errno](http://docs.python.org/2/library/errno.html)). The error message returned is the error message from `errno`.
+`ScratchError` is raised when there are errors with the network (e.g.
+connection refused, connection established, etc. basically any error from
+[errno](http://docs.python.org/2/library/errno.html)). The error message
+returned is the error message from `errno`.
-`ScratchConnectionError` is raised when reading or writing data has no effect (i.e. reading from Scratch returns an empty string, or writing to Scratch writes 0 bytes). This is usually a sign that Scratch has been disconnected.
+`ScratchConnectionError` is raised when reading or writing data has no effect
+(i.e. reading from Scratch returns an empty string, or writing to Scratch
+writes 0 bytes). This is usually a sign that Scratch has been disconnected.
-If you do not care about the difference, you can just except `ScratchError` and it will also catch `ScratchConnectionError`.
+If you do not care about the difference, you can just except `ScratchError` and
+it will also catch `ScratchConnectionError`.
## License
MIT

0 comments on commit 46f99ca

Please sign in to comment.