[tor-commits] [stem/master] Using SocksiPy for client usage tutorial

[atagar at torproject.org]

commit a72e22512e86653d86ec2015bbf3416a3de52aae
Author: Damian Johnson <atagar at torproject.org>
Date:   Mon May 13 08:45:51 2013 -0700

    Using SocksiPy for client usage tutorial
    
    Exemplifying using tor with both SocksiPy and PycURL. It's quite a bit simpler
    with SocksiPy so I'll probably use this for most other examples. Change is
    thanks to Ashish.
---
 docs/tutorials/to_russia_with_love.rst |   74 ++++++++++++++++++++++++--------
 1 files changed, 56 insertions(+), 18 deletions(-)

diff --git a/docs/tutorials/to_russia_with_love.rst b/docs/tutorials/to_russia_with_love.rst
index a2e9647..da0c05f 100644
--- a/docs/tutorials/to_russia_with_love.rst
+++ b/docs/tutorials/to_russia_with_love.rst
@@ -1,6 +1,14 @@
 To Russia With Love
 ===================
 
+* :ref:`using-socksipy`
+* :ref:`using-pycurl`
+
+.. _using-socksipy:
+
+Using SocksiPy
+--------------
+
 Say it's 1982, the height of the Cold War, and you're a journalist doing a piece on how the Internet looks from behind the Iron Curtain. Ignoring the minor detail that the Internet doesn't yet exist, we'll walk you through how you could do it - no passport required!
 
 The Internet isn't uniform. Localization, censorship, and selective service based on your IP's geographic location can make the Internet a very different place depending on where you're coming from.
@@ -9,40 +17,38 @@ Tor relays are scattered all over the world and, as such, you can pretend to be
 
 Tor makes `configuring your exit locale <https://www.torproject.org/docs/faq.html.en#ChooseEntryExit>`_ easy through the **ExitNodes** torrc option. Note that you don't need a control port (or even stem) to do this, though they can be useful if you later want to do something more elaborate.
 
-In the following example we're using stem to `start Tor <../api/process.html>`_, then reading a site through it with `PycURL <http://pycurl.sourceforge.net/>`_. This is not always reliable (some relays are lemons) so you may need to run this more than once.
+In the following example we're using stem to `start Tor <../api/process.html>`_, then reading a site through it with `SocksiPy <http://socksipy.sourceforge.net/>`_. This is not always reliable (some relays are lemons) so you may need to run this more than once.
 
 **Do not rely on the following not to leak.** Though it seems to work, DNS resolution and other edge cases might expose your real IP. If you have a suggestion for how to improve this example then please `let me know <http://www.atagar.com/contact/>`_!
 
 ::
 
   import StringIO
+  import urllib
 
-  import pycurl
+  import socks  # SocksiPy module
   import stem.process
 
   from stem.util import term
 
   SOCKS_PORT = 7000
 
-  def curl(url):
-    """ 
-    Uses pycurl to fetch a site using the proxy on the SOCKS_PORT.
-    """
+  # Set socks proxy and wrap the urllib module
 
-    output = StringIO.StringIO()
+  socks.setdefaultproxy(socks.PROXY_TYPE_SOCKS5, '127.0.0.1', SOCKS_PORT)
+  socks.wrapmodule(urllib)
 
-    query = pycurl.Curl()
-    query.setopt(pycurl.URL, url)
-    query.setopt(pycurl.PROXY, 'localhost')
-    query.setopt(pycurl.PROXYPORT, SOCKS_PORT)
-    query.setopt(pycurl.PROXYTYPE, pycurl.PROXYTYPE_SOCKS5)
-    query.setopt(pycurl.WRITEFUNCTION, output.write)
+
+  def query(url):
+    """
+    Uses urllib to fetch a site using SocksiPy for Tor over the SOCKS_PORT.
+    """
 
     try:
-      query.perform()
-      return output.getvalue()
-    except pycurl.error as exc:
-      return "Unable to reach %s (%s)" % (url, exc)
+      return urllib.urlopen(url).read()
+    except:
+      return "Unable to reach %s" % url
+
 
   # Start an instance of tor configured to only exit through Russia. This prints
   # tor's bootstrap information as it starts. Note that this likely will not
@@ -52,6 +58,7 @@ In the following example we're using stem to `start Tor <../api/process.html>`_,
     if "Bootstrapped " in line:
       print term.format(line, term.Color.BLUE)
 
+
   print term.format("Starting Tor:\n", term.Attr.BOLD)
 
   tor_process = stem.process.launch_tor_with_config(
@@ -63,9 +70,40 @@ In the following example we're using stem to `start Tor <../api/process.html>`_,
   )
 
   print term.format("\nChecking our endpoint:\n", term.Attr.BOLD)
-  print term.format(curl("http://www.atagar.com/echo.php"), term.Color.BLUE)
+  print term.format(query("http://www.atagar.com/echo.php"), term.Color.BLUE)
 
   tor_process.kill()  # stops tor
 
 .. image:: /_static/locale_selection_output.png
 
+.. _using-pycurl:
+
+Using PycURL
+------------
+
+Besides SocksiPy, you can also use `PycURL <http://pycurl.sourceforge.net/>`_ to do the same. To do so replace the query() function above with...
+
+::
+
+  import pycurl
+
+  def query(url):
+    """ 
+    Uses pycurl to fetch a site using the proxy on the SOCKS_PORT.
+    """
+
+    output = StringIO.StringIO()
+
+    query = pycurl.Curl()
+    query.setopt(pycurl.URL, url)
+    query.setopt(pycurl.PROXY, 'localhost')
+    query.setopt(pycurl.PROXYPORT, SOCKS_PORT)
+    query.setopt(pycurl.PROXYTYPE, pycurl.PROXYTYPE_SOCKS5)
+    query.setopt(pycurl.WRITEFUNCTION, output.write)
+
+    try:
+      query.perform()
+      return output.getvalue()
+    except pycurl.error as exc:
+      return "Unable to reach %s (%s)" % (url, exc)
+