pokemon.py - Automatically poke back on Facebook

by Klaus-Uwe Mitterer <pokemon@klaus-uwe.me>

== Prerequisites ==

This script requires the modules urllib, cookielib, urllib2, signal, time and BeautifulSoup. You should be able to install those using pip if you don't have them anyway, but I'm not going to give detailed installation instructions.

== Setup ==

Before you can get started, you have to change two settings in pokemon.py (lines 13-14):

--------------------------
  email = "something"
  password = "something"
--------------------------

In those two lines, replace "something" with your email address and password, respectively. Make sure not to break any indentation as this will prevent the script from working.

If your password contains special characters, specifically double quotes (") or backslashes (\), you will have to escape it. For details, check out the Troubleshooting section below.

== Running the script ==

If you have changed the settings as intended, you should be ready to go. Simply run the script by double-clicking it in your GUI or through your console like so:

--------------------------
cd PATH_TO_POKEMON
./pokemon.py
--------------------------

Obviously, replace PATH_TO_POKEMON with the actual path in your file system where you put pokemon.py.

If you provided the correct email address and password, you should now receive the following output:

--------------------------
Login successful!
--------------------------

Then, each time the script actually pokes somebody, it will notify you of this with the following output:

--------------------------
Poke!
--------------------------

== Stopping the script ==

In order to stop the script, simply issue a Ctrl+C in the terminal it is running in, or close the respective window.

== Tweaking ==

By default, the script will check for new inbound pokes every 30 seconds. You can modify this in the last line (line 66). Please note that a higher refresh/poke rate may cause the bot to run into a rate limit.

You may also turn the script into what I call a "Nuclear Poke Bot". By commenting out (putting a # in front of it) or deleting line 62 (if not "suggestion" in url:), you can cause it to not only poke back people who poked you, but also poke people Facebook suggests you to poke - over time, it will poke all your friends.

== Troubleshooting ==

If you have trouble signing in, chances are that you simply got a typo in your email address or password. Please double check.

In case you have double quotes (") or backslashes (\) in your password, you will need to escape them, i.e. put a backslash (\) in front of them. For instance, if your password were to be Fo0\6ar" you would have to use the following password line:

--------------------------
  password = "Fo0\\6ar\""
--------------------------

If despite all this, you can not get the script running, chances are that Facebook changed something on their end. Please send an email to <pokemon@klaus-uwe.me> and I'll try to help you.

There are several reasons why the script may suddenly stop working. Most of the time you will just need to take a little break and try again later. 

If you keep getting messages like this:

--------------------------
Poke timed out.
--------------------------

Chances are that your Internet connection is slow. This message is just a notice - no changes on your end should be necessary. You may, however, try to increase the script's waiting time at line 67 (time = 10). Values like 15 or 20 (seconds) will still be sensible and may reduce the number of messages.

Generally, the script should recover from most problems automatically. If it ends up stalling anyway, you will have to kill it manually with Ctrl+C. But really, this shouldn't happen.