PycURL: Python interface to libcurl

PycURL is a Python interface to libcurl. PycURL can be used to fetch objects identified by a URL from a Python program, similar to the urllib Python module. PycURL is mature, very fast, and supports a lot of features.

Overview

• libcurl is a free and easy-to-use client-side URL transfer library, supporting FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, LDAP, LDAPS, FILE, IMAP, SMTP, POP3 and RTSP. libcurl supports SSL certificates, HTTP POST, HTTP PUT, FTP uploading, HTTP form based upload, proxies, cookies, user+password authentication (Basic, Digest, NTLM, Negotiate, Kerberos4), file transfer resume, http proxy tunneling and more!
• libcurl is highly portable, it builds and works identically on numerous platforms, including Solaris, NetBSD, FreeBSD, OpenBSD, Darwin, HPUX, IRIX, AIX, Tru64, Linux, UnixWare, HURD, Windows, Amiga, OS/2, BeOs, Mac OS X, Ultrix, QNX, OpenVMS, RISC OS, Novell NetWare, DOS and more...
• libcurl is free, thread-safe, IPv6 compatible, feature rich, well supported, fast, thoroughly documented and is already used by many known, big and successful companies and numerous applications.

Requirements

• Python 2.4 through 2.7, 3.1 through 3.3.
• libcurl 7.19.0 or better.

Installation

You can install the most recent PycURL version using easy_install:

easy_install pycurl

or pip:

pip install pycurl

Installing from source is performed via setup.py:

python setup.py install

You will need libcurl headers and libraries installed to install PycURL from source. PycURL uses curl-config to determine correct flags/libraries to use during compilation; you can override the location of curl-config if it is not in PATH or you want to use a custom libcurl installation:

python setup.py --curl-config=/path/to/curl-config install

Sometimes it is more convenient to use an environment variable, if you are not directly invoking setup.py:

PYCURL_CURL_CONFIG=/path/to/curl-config python setup.py install

curl-config is expected to support the following options:

• --version
• --cflags
• --libs
• --static-libs (if --libs does not work)

Automated Tests

PycURL comes with an automated test suite. To run the tests, execute:

make test

The suite depends on packages nose, bottle and cherrypy.

Some tests use vsftpd configured to accept anonymous uploads. These tests are not run by default. As configured, vsftpd will allow reads and writes to anything the user running the tests has read and write access. To run vsftpd tests you must explicitly set PYCURL_VSFTPD_PATH variable like so:

# use vsftpd in PATH
export PYCURL_VSFTPD_PATH=vsftpd

# specify full path to vsftpd
export PYCURL_VSFTPD_PATH=/usr/local/libexec/vsftpd

These instructions work for Python 2.5 through 2.7 and 3.1 through 3.3.

Test Matrix

The test matrix is a separate framework that runs tests on more esoteric configurations. It supports:

• Testing against Python 2.4, which bottle does not support.
• Testing against Python compiled without threads, which requires an out of process test server.
• Testing against locally compiled libcurl with arbitrary options.

To use the test matrix, first you need to start the test server from Python 2.5+ by running::

python -m tests.appmanager

Then in a different shell, and preferably in a separate user account, run the test matrix::

# run ftp tests, etc.
export PYCURL_VSFTPD_PATH=vsftpd
# create a new work directory, preferably not under pycurl tree
mkdir testmatrix
cd testmatrix
# run the matrix specifying absolute path
python /path/to/pycurl/tests/matrix.py

The test matrix will download, build and install supported Python versions and supported libcurl versions, then run pycurl tests against each combination. To see what the combinations are, look in tests/matrix.py.

Contribute

For smaller changes:

1. Fork the repository on Github.
2. Create a branch off master.
3. Make your changes.
4. Write a test which shows that the bug was fixed or that the feature works as expected.
5. Send a pull request.

For larger changes:

1. Join the mailing list.
2. Discuss your proposal on the mailing list.
3. When consensus is reached, implement it as described above.

License

Copyright (C) 2001-2008 by Kjetil Jacobsen <kjetilja at gmail.com>
Copyright (C) 2001-2008 by Markus F.X.J. Oberhumer <markus at oberhumer.com>

All rights reserved.

PycURL is dual licensed under the LGPL and an MIT/X derivative license
based on the cURL license.  A full copy of the LGPL license is included
in the file COPYING-LGPL.  A full copy of the MIT/X derivative license is
included in the file COPYING-MIT.  You can redistribute and/or modify PycURL
according to the terms of either license.