Started on converting html documentation to restructured text (html2rst run)

5 files changed, 449 insertions, 0 deletions

diff --git a/doc/callbacks.rst b/doc/callbacks.rst
new file mode 100644
index 0000000..fca89b7
--- /dev/null
+++ b/doc/callbacks.rst
@@ -0,0 +1,118 @@
+Callbacks
+=========
+
+For more fine-grained control, libcurl allows a number of callbacks to be
+associated with each connection. In pycurl, callbacks are defined using the
+``setopt()`` method for Curl objects with options WRITEFUNCTION,
+READFUNCTION, HEADERFUNCTION, PROGRESSFUNCTION, IOCTLFUNCTION, or
+DEBUGFUNCTION. These options correspond to the libcurl options with CURLOPT_*
+prefix removed. A callback in pycurl must be either a regular Python
+function, a class method or an extension type function.
+
+There are some limitations to some of the options which can be used
+concurrently with the pycurl callbacks compared to the libcurl callbacks.
+This is to allow different callback functions to be associated with different
+Curl objects. More specifically, WRITEDATA cannot be used with WRITEFUNCTION,
+READDATA cannot be used with READFUNCTION, WRITEHEADER cannot be used with
+HEADERFUNCTION, PROGRESSDATA cannot be used with PROGRESSFUNCTION, IOCTLDATA
+cannot be used with IOCTLFUNCTION, and DEBUGDATA cannot be used with
+DEBUGFUNCTION. In practice, these limitations can be overcome by having a
+callback function be a class instance method and rather use the class
+instance attributes to store per object data such as files used in the
+callbacks.
+
+The signature of each callback used in pycurl is as follows:
+> <br> ``WRITEFUNCTION(``*string*``) ``*-> number of characters written
+> <em>
+> <code>READFUNCTION(<code>*number of characters to read*``)``*-> string*
+> <br> ``HEADERFUNCTION(``*string*``)``* -> number of characters written
+> <em>
+> <code>PROGRESSFUNCTION(<code>*download total, downloaded, upload total,
+uploaded*``) ``*-> status*
+> <br> ``DEBUGFUNCTION(``*debug message type, debug message string*``)`` *->
+None
+><em>
+> <code>IOCTLFUNCTION(<code>*ioctl cmd*``)`` *-> status
+><em>
+> <p>In addition, <code>READFUNCTION<code> may return ``READFUNC_ABORT`` or
+``READFUNC_PAUSE``. See the libcurl documentation for an explanation of these
+values. The ``WRITEFUNCTION`` and ``HEADERFUNCTION`` callbacks may return
+``None``, which is an alternate way of indicating that the callback has
+consumed all of the string passed to it.
+
+--------
+
+> <h2>Example: Callbacks for document header and body<h2>
+
+This example prints the header data to stderr and the body data to stdout.
+Also note that neither callback returns the number of bytes written. For
+WRITEFUNCTION and HEADERFUNCTION callbacks, returning None implies that all
+bytes where written.
+
+::
+        ## Callback function invoked when body data is ready
+        def body(buf):
+            # Print body data to stdout
+            import sys
+            sys.stdout.write(buf)
+            # Returning None implies that all bytes were written
+
+        ## Callback function invoked when header data is ready
+        def header(buf):
+            # Print header data to stderr
+            import sys
+            sys.stderr.write(buf)
+            # Returning None implies that all bytes were written
+
+        c = pycurl.Curl()
+        c.setopt(pycurl.URL, "http://www.python.org/")
+        c.setopt(pycurl.WRITEFUNCTION, body)
+        c.setopt(pycurl.HEADERFUNCTION, header)
+        c.perform()
+
+Example: Download/upload progress callback
+------------------------------------------
+
+This example shows how to use the progress callback. When downloading a
+document, the arguments related to uploads are zero, and vice versa.
+
+::
+        ## Callback function invoked when download/upload has
+        progress
+        def progress(download_t, download_d, upload_t, upload_d):
+            print "Total to download", download_t
+            print "Total downloaded", download_d
+            print "Total to upload", upload_t
+            print "Total uploaded", upload_d
+
+        c.setopt(c.URL, "http://slashdot.org/")
+        c.setopt(c.NOPROGRESS, 0)
+        c.setopt(c.PROGRESSFUNCTION, progress)
+        c.perform()
+
+Example: Debug callbacks
+------------------------
+
+This example shows how to use the debug callback. The debug message type is
+an integer indicating the type of debug message. The VERBOSE option must be
+enabled for this callback to be invoked.
+
+::
+        def test(debug_type, debug_msg):
+            print "debug(%d): %s" % (debug_type, debug_msg)
+
+        c = pycurl.Curl()
+        c.setopt(pycurl.URL, "http://curl.haxx.se/")
+        c.setopt(pycurl.VERBOSE, 1)
+        c.setopt(pycurl.DEBUGFUNCTION, test)
+        c.perform()
+
+Other examples
+--------------
+
+The pycurl distribution also contains a number of test scripts and examples
+which show how to use the various callbacks in libcurl. For instance, the
+file 'examples/file_upload.py' in the distribution contains example code for
+using READFUNCTION, 'tests/test_cb.py' shows WRITEFUNCTION and
+HEADERFUNCTION, 'tests/test_debug.py' shows DEBUGFUNCTION, and
+'tests/test_getinfo.py' shows PROGRESSFUNCTION.
diff --git a/doc/curlmultiobject.rst b/doc/curlmultiobject.rst
new file mode 100644
index 0000000..8d5aaec
--- /dev/null
+++ b/doc/curlmultiobject.rst
@@ -0,0 +1,100 @@
+CurlMulti Object
+================
+
+CurlMulti objects have the following methods:
+
+``close()`` -> *None*
+
+Corresponds to ```curl_multi_cleanup()```_ in libcurl. This method is
+automatically called by pycurl when a CurlMulti object no longer has any
+references to it, but can also be called explicitly.
+
+``perform()`` -> *tuple of status and the number of active Curl objects*
+
+Corresponds to ```curl_multi_perform()```_ in libcurl.
+
+``add_handle(``*Curl object*``) ``-> *None*
+
+Corresponds to ```curl_multi_add_handle()```_ in libcurl. This method adds an
+existing and valid Curl object to the CurlMulti object.
+
+IMPORTANT NOTE: add_handle does not implicitly add a Python reference to the
+Curl object (and thus does not increase the reference count on the Curl
+object).
+
+``remove_handle(``*Curl object*``)`` -> *None*
+
+Corresponds to ```curl_multi_remove_handle()```_ in libcurl. This method
+removes an existing and valid Curl object from the CurlMulti object.
+
+IMPORTANT NOTE: remove_handle does not implicitly remove a Python reference
+from the Curl object (and thus does not decrease the reference count on the
+Curl object).
+
+``fdset()`` -> *triple of lists with active file descriptors, readable,
+writeable, exceptions.*
+
+Corresponds to ```curl_multi_fdset()```_ in libcurl. This method extracts the
+file descriptor information from a CurlMulti object. The returned lists can
+be used with the ``select`` module to poll for events.
+
+Example usage:
+
+::
+    import pycurl
+    c = pycurl.Curl()
+    c.setopt(pycurl.URL, "http://curl.haxx.se")
+    m = pycurl.CurlMulti()
+    m.add_handle(c)
+    while 1:
+        ret, num_handles = m.perform()
+        if ret != pycurl.E_CALL_MULTI_PERFORM: break
+    while num_handles:
+        apply(select.select, m.fdset() + (1,))
+        while 1:
+            ret, num_handles = m.perform()
+            if ret != pycurl.E_CALL_MULTI_PERFORM: break
+     ``select(``*timeout*``)`` -> *number of ready file descriptors or
+     -1 on timeout*
+
+This is a convenience function which simplifies the combined use of
+``fdset()`` and the ``select`` module.
+
+Example usage:
+
+::import pycurl
+    c = pycurl.Curl()
+    c.setopt(pycurl.URL, "http://curl.haxx.se")
+    m = pycurl.CurlMulti()
+    m.add_handle(c)
+    while 1:
+        ret, num_handles = m.perform()
+        if ret != pycurl.E_CALL_MULTI_PERFORM: break
+    while num_handles:
+        ret = m.select(1.0)
+        if ret == -1:  continue
+        while 1:
+            ret, num_handles = m.perform()
+            if ret != pycurl.E_CALL_MULTI_PERFORM: break
+     ``info_read(``*[max]*``)`` -> *numberof queued messages, a list of
+     successful objects, a list of failed objects*
+
+Corresponds to the ```curl_multi_info_read()```_ function in libcurl. This
+method extracts at most *max* messages from the multi stack and returns them
+in two lists. The first list contains the handles which completed
+successfully and the second list contains a tuple *<curl object, curl error
+number, curl error message>* for each failed curl object. The number of
+queued messages after this method has been called is also returned.
+
+.. _curl_multi_cleanup():
+    http://curl.haxx.se/libcurl/c/curl_multi_cleanup.html
+.. _curl_multi_perform():
+    http://curl.haxx.se/libcurl/c/curl_multi_perform.html
+.. _curl_multi_add_handle():
+    http://curl.haxx.se/libcurl/c/curl_multi_add_handle.html
+.. _curl_multi_remove_handle():
+    http://curl.haxx.se/libcurl/c/curl_multi_remove_handle.html
+.. _curl_multi_fdset():
+    http://curl.haxx.se/libcurl/c/curl_multi_fdset.html
+.. _curl_multi_info_read():
+    http://curl.haxx.se/libcurl/c/curl_multi_info_read.html
diff --git a/doc/curlobject.rst b/doc/curlobject.rst
new file mode 100644
index 0000000..d6cb95d
--- /dev/null
+++ b/doc/curlobject.rst
@@ -0,0 +1,89 @@
+Curl Object
+===========
+
+Curl objects have the following methods:
+
+``close()`` -> *None*
+
+Corresponds to ```curl_easy_cleanup```_ in libcurl. This method is
+automatically called by pycurl when a Curl object no longer has any
+references to it, but can also be called explicitly.
+
+``perform()`` -> *None*
+
+Corresponds to ```curl_easy_perform```_ in libcurl.
+
+``reset()`` -> *None*
+
+Corresponds to ```curl_easy_reset```_ in libcurl.
+
+``setopt(``*option, value*``)`` -> *None*
+
+Corresponds to ```curl_easy_setopt```_ in libcurl, where *option* is
+specified with the CURLOPT_* constants in libcurl, except that the CURLOPT_
+prefix has been removed. (See below for exceptions.) The type for *value*
+depends on the option, and can be either a string, integer, long integer,
+file object, list, or function.
+
+Example usage:
+
+::
+    import pycurl
+    c = pycurl.Curl()
+    c.setopt(pycurl.URL, "http://www.python.org/")
+    c.setopt(pycurl.HTTPHEADER, ["Accept:"])
+    import StringIO
+    b = StringIO.StringIO()
+    c.setopt(pycurl.WRITEFUNCTION, b.write)
+    c.setopt(pycurl.FOLLOWLOCATION, 1)
+    c.setopt(pycurl.MAXREDIRS, 5)
+    c.perform()
+    print b.getvalue()
+    ...
+     ``getinfo(``*option*``) ``-> *Result*
+
+Corresponds to ```curl_easy_getinfo```_ in libcurl, where *option* is the
+same as the CURLINFO_* constants in libcurl, except that the CURLINFO_ prefix
+has been removed. (See below for exceptions.) *Result* contains an integer,
+float or string, depending on which option is given. The ``getinfo`` method
+should not be called unless ``perform`` has been called and finished.
+
+Example usage:
+
+::
+    import pycurl
+    c = pycurl.Curl()
+    c.setopt(pycurl.URL, "http://sf.net")
+    c.setopt(pycurl.FOLLOWLOCATION, 1)
+    c.perform()
+    print c.getinfo(pycurl.HTTP_CODE), c.getinfo(pycurl.EFFECTIVE_URL)
+    ...
+    --> 200 "http://sourceforge.net/"
+     ``pause(``*bitmask*``) ``-> *None*
+
+Corresponds to ```curl_easy_pause```_ in libcurl. The argument should be
+derived from the ``PAUSE_RECV``, ``PAUSE_SEND``, ``PAUSE_ALL`` and
+``PAUSE_CONT`` constants.
+
+``errstr()`` -> *String*
+
+Returns the internal libcurl error buffer of this handle as a string.
+
+In order to distinguish between similarly-named CURLOPT and CURLINFO
+constants, some have ``OPT_`` and ``INFO_`` prefixes. These are
+``INFO_FILETIME``, ``OPT_FILETIME``, ``INFO_COOKIELIST`` (but ``setopt`` uses
+``COOKIELIST``!), ``INFO_CERTINFO``, and ``OPT_CERTINFO``.
+
+The value returned by ``getinfo(INFO_CERTINFO)`` is a list with one element
+per certificate in the chain, starting with the leaf; each element is a
+sequence of ``(``*key*``, ``*value*``)`` tuples.
+
+.. _curl_easy_cleanup:
+    http://curl.haxx.se/libcurl/c/curl_easy_cleanup.html
+.. _curl_easy_perform:
+    http://curl.haxx.se/libcurl/c/curl_easy_perform.html
+.. _curl_easy_reset: http://curl.haxx.se/libcurl/c/curl_easy_reset.html
+.. _curl_easy_setopt: http://curl.haxx.se/libcurl/c/curl_easy_setopt.html
+.. _curl_easy_getinfo:
+    http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html
+.. _curl_easy_pause: http://curl.haxx.se/libcurl/c/curl_easy_pause.html
diff --git a/doc/curlshareobject.rst b/doc/curlshareobject.rst
new file mode 100644
index 0000000..ba0434b
--- /dev/null
+++ b/doc/curlshareobject.rst
@@ -0,0 +1,28 @@
+CurlShare Object
+================
+
+CurlShare objects have the following methods:
+
+``setopt(``*option, value*``)`` -> *None*
+
+Corresponds to ```curl_share_setopt```_ in libcurl, where *option* is
+specified with the CURLSHOPT_* constants in libcurl, except that the
+CURLSHOPT_ prefix has been changed to SH_. Currently, *value* must be either
+LOCK_DATA_COOKIE or LOCK_DATA_DNS.
+
+Example usage:
+
+::
+    import pycurl
+    curl = pycurl.Curl()
+    s = pycurl.CurlShare()
+    s.setopt(pycurl.SH_SHARE, pycurl.LOCK_DATA_COOKIE)
+    s.setopt(pycurl.SH_SHARE, pycurl.LOCK_DATA_DNS)
+    curl.setopt(pycurl.URL, 'http://curl.haxx.se')
+    curl.setopt(pycurl.SHARE, s)
+    curl.perform()
+    curl.close()
+
+
+.. _curl_share_setopt:
+    http://curl.haxx.se/libcurl/c/curl_share_setopt.html
diff --git a/doc/pycurl.rst b/doc/pycurl.rst
new file mode 100644
index 0000000..13bbdd3
--- /dev/null
+++ b/doc/pycurl.rst
@@ -0,0 +1,114 @@
+``PycURL`` -- A Python Interface To The cURL library
+====================================================
+
+The pycurl package is a Python interface to libcurl
+(`http://curl.haxx.se/libcurl/`_). pycurl has been successfully built and
+tested with Python versions from 2.4 to 2.7.
+
+libcurl is a client-side URL transfer library supporting FTP, FTPS, HTTP,
+HTTPS, GOPHER, TELNET, DICT, FILE and LDAP. libcurl also supports HTTPS
+certificates, HTTP POST, HTTP PUT, FTP uploads, proxies, cookies, basic
+authentication, file transfer resume of FTP sessions, HTTP proxy tunneling
+and more.
+
+All the functionality provided by libcurl can used through the pycurl
+interface. The following subsections describe how to use the pycurl
+interface, and assume familiarity with how libcurl works. For information on
+how libcurl works, please consult the curl library web pages
+(`http://curl.haxx.se/libcurl/c/`_).
+
+--------
+
+> <h1>Module Functionality<h1>  ``pycurl.global_init(``*option*``)`` ->*None*
+
+*option* is one of the constants pycurl.GLOBAL_SSL, pycurl.GLOBAL_WIN32,
+pycurl.GLOBAL_ALL, pycurl.GLOBAL_NOTHING, pycurl.GLOBAL_DEFAULT. Corresponds
+to ```curl_global_init()```_ in libcurl.
+
+``pycurl.global_cleanup()`` -> *None*
+
+Corresponds to ```curl_global_cleanup()```_ in libcurl.
+
+``pycurl.version``
+
+This is a string with version information on libcurl, corresponding to
+```curl_version()```_ in libcurl.
+
+Example usage:
+
+::
+    >>> import pycurl
+    >>> pycurl.version
+    'libcurl/7.12.3 OpenSSL/0.9.7e zlib/1.2.2.1 libidn/0.5.12'
+     ``pycurl.version_info()`` -> *Tuple*
+
+Corresponds to ```curl_version_info()```_ in libcurl. Returns a tuple of
+information which is similar to the ``curl_version_info_data`` struct
+returned by ``curl_version_info()`` in libcurl.
+
+Example usage:
+
+::
+    >>> import pycurl
+    >>> pycurl.version_info()
+    (2, '7.12.3', 461827, 'i586-pc-linux-gnu', 1565, 'OpenSSL/0.9.7e',
+    9465951,
+    '1.2.2.1', ('ftp', 'gopher', 'telnet', 'dict', 'ldap', 'http',
+    'file',
+    'https', 'ftps'), None, 0, '0.5.12')
+     ``pycurl.Curl()`` -> *Curl object*
+
+This function creates a new `Curl object`_ which corresponds to a ``CURL``
+handle in libcurl. Curl objects automatically set CURLOPT_VERBOSE to 0,
+CURLOPT_NOPROGRESS to 1, provide a default CURLOPT_USERAGENT and setup
+CURLOPT_ERRORBUFFER to point to a private error buffer.
+
+``pycurl.CurlMulti()`` -> *CurlMulti object*
+
+This function creates a new `CurlMulti object`_ which corresponds to a
+``CURLM`` handle in libcurl.
+
+``pycurl.CurlShare()`` -> *CurlShare object*
+
+This function creates a new `CurlShare object`_ which corresponds to a
+``CURLSH`` handle in libcurl. CurlShare objects is what you pass as an
+argument to the SHARE option on Curl objects.
+
+--------
+
+> <h1>Subsections<h1>
+
+-   `Curl objects`_
+-   `CurlMulti objects`_
+-   `CurlShare objects`_
+-   `Callbacks`_
+-   `Unicode handling`_
+-   `File handling`_
+
+
+Documentation For Developers
+============================
+
+-   `Notes on PycURL internals`_
+-   `Release process`_
+
+.. _http://curl.haxx.se/libcurl/: http://curl.haxx.se/libcurl/
+.. _http://curl.haxx.se/libcurl/c/: http://curl.haxx.se/libcurl/c/
+.. _curl_global_init():
+    http://curl.haxx.se/libcurl/c/curl_global_init.html
+.. _curl_global_cleanup():
+    http://curl.haxx.se/libcurl/c/curl_global_cleanup.html
+.. _curl_version(): http://curl.haxx.se/libcurl/c/curl_version.html
+.. _curl_version_info():
+    http://curl.haxx.se/libcurl/c/curl_version_info.html
+.. _Curl object: curlobject.html
+.. _Curl objects: curlobject.html
+.. _CurlMulti object: curlmultiobject.html
+.. _CurlMulti objects: curlmultiobject.html
+.. _CurlShare object: curlshareobject.html
+.. _CurlShare objects: curlshareobject.html
+.. _Callbacks: callbacks.html
+.. _Unicode handling: unicode.html
+.. _File handling: files.html
+.. _Notes on PycURL internals: internals.html
+.. _Release process: release-process.html