1PycURL -- A Python Interface To The cURL library
2================================================
3
4.. image:: https://github.com/pycurl/pycurl/workflows/CI/badge.svg
5	   :target: https://github.com/pycurl/pycurl/actions
6
7PycURL is a Python interface to `libcurl`_, the multiprotocol file
8transfer library. Similarly to the urllib_ Python module,
9PycURL can be used to fetch objects identified by a URL from a Python program.
10Beyond simple fetches however PycURL exposes most of the functionality of
11libcurl, including:
12
13- Speed - libcurl is very fast and PycURL, being a thin wrapper above
14  libcurl, is very fast as well. PycURL `was benchmarked`_ to be several
15  times faster than requests_.
16- Features including multiple protocol support, SSL, authentication and
17  proxy options. PycURL supports most of libcurl's callbacks.
18- Multi_ and share_ interfaces.
19- Sockets used for network operations, permitting integration of PycURL
20  into the application's I/O loop (e.g., using Tornado_).
21
22.. _was benchmarked: http://stackoverflow.com/questions/15461995/python-requests-vs-pycurl-performance
23.. _requests: http://python-requests.org/
24.. _Multi: https://curl.haxx.se/libcurl/c/libcurl-multi.html
25.. _share: https://curl.haxx.se/libcurl/c/libcurl-share.html
26.. _Tornado: http://www.tornadoweb.org/
27
28
29Requirements
30------------
31
32- Python 3.5-3.8.
33- libcurl 7.19.0 or better.
34
35
36Installation
37------------
38
39Download source and binary distributions from `PyPI`_.
40Binary wheels are now available for 32 and 64 bit Windows versions.
41
42Please see `INSTALL.rst`_ for installation instructions. If installing from
43a Git checkout, please follow instruction in the `Git Checkout`_ section
44of INSTALL.rst.
45
46.. _PyPI: https://pypi.python.org/pypi/pycurl
47.. _INSTALL.rst: http://pycurl.io/docs/latest/install.html
48.. _Git Checkout: http://pycurl.io/docs/latest/install.html#git-checkout
49
50
51Documentation
52-------------
53
54Documentation for the most recent PycURL release is available on
55`PycURL website <http://pycurl.io/docs/latest/>`_.
56
57Documentation for the development version of PycURL
58is available `here <http://pycurl.io/docs/dev/>`_.
59
60To build documentation from source, run ``make docs``.
61Building documentation requires `Sphinx <http://sphinx-doc.org/>`_ to
62be installed, as well as pycurl extension module built as docstrings are
63extracted from it. Built documentation is stored in ``build/doc``
64subdirectory.
65
66
67Support
68-------
69
70For support questions please use `curl-and-python mailing list`_.
71`Mailing list archives`_ are available for your perusal as well.
72
73Although not an official support venue, `Stack Overflow`_ has been
74popular with some PycURL users.
75
76Bugs can be reported `via GitHub`_. Please use GitHub only for bug
77reports and direct questions to our mailing list instead.
78
79.. _curl-and-python mailing list: http://cool.haxx.se/mailman/listinfo/curl-and-python
80.. _Stack Overflow: http://stackoverflow.com/questions/tagged/pycurl
81.. _Mailing list archives: https://curl.haxx.se/mail/list.cgi?list=curl-and-python
82.. _via GitHub: https://github.com/pycurl/pycurl/issues
83
84
85Automated Tests
86---------------
87
88PycURL comes with an automated test suite. To run the tests, execute::
89
90    make test
91
92The suite depends on packages `pytest`_ and `bottle`_, as well as `vsftpd`_.
93
94Some tests use vsftpd configured to accept anonymous uploads. These tests
95are not run by default. As configured, vsftpd will allow reads and writes to
96anything the user running the tests has read and write access. To run
97vsftpd tests you must explicitly set PYCURL_VSFTPD_PATH variable like so::
98
99    # use vsftpd in PATH
100    export PYCURL_VSFTPD_PATH=vsftpd
101
102    # specify full path to vsftpd
103    export PYCURL_VSFTPD_PATH=/usr/local/libexec/vsftpd
104
105.. _pytest: https://pytest.org/
106.. _bottle: http://bottlepy.org/
107.. _vsftpd: http://vsftpd.beasts.org/
108
109
110Test Matrix
111-----------
112
113The test matrix is a separate framework that runs tests on more esoteric
114configurations. It supports:
115
116- Testing against Python 2.4, which bottle does not support.
117- Testing against Python compiled without threads, which requires an out of
118  process test server.
119- Testing against locally compiled libcurl with arbitrary options.
120
121To use the test matrix, first start the test server from Python 2.5+ by
122running::
123
124    python -m tests.appmanager
125
126Then in a different shell, and preferably in a separate user account,
127run the test matrix::
128
129    # run ftp tests, etc.
130    export PYCURL_VSFTPD_PATH=vsftpd
131    # create a new work directory, preferably not under pycurl tree
132    mkdir testmatrix
133    cd testmatrix
134    # run the matrix specifying absolute path
135    python /path/to/pycurl/tests/matrix.py
136
137The test matrix will download, build and install supported Python versions
138and supported libcurl versions, then run pycurl tests against each combination.
139To see what the combinations are, look in
140`tests/matrix.py <tests/matrix.py>`_.
141
142
143Contribute
144----------
145
146For smaller changes:
147
148#. Fork `the repository`_ on Github.
149#. Create a branch off **master**.
150#. Make your changes.
151#. Write a test which shows that the bug was fixed or that the feature
152   works as expected.
153#. Send a pull request.
154#. Check back after 10-15 minutes to see if tests passed on Travis CI.
155   PycURL supports old Python and libcurl releases and their support is tested
156   on Travis.
157
158For larger changes:
159
160#. Join the `mailing list`_.
161#. Discuss your proposal on the mailing list.
162#. When consensus is reached, implement it as described above.
163
164Please contribute binary distributions for your system to the
165`downloads repository`_.
166
167
168License
169-------
170
171::
172
173    Copyright (C) 2001-2008 by Kjetil Jacobsen <kjetilja at gmail.com>
174    Copyright (C) 2001-2008 by Markus F.X.J. Oberhumer <markus at oberhumer.com>
175    Copyright (C) 2013-2021 by Oleg Pudeyev <oleg at bsdpower.com>
176
177    All rights reserved.
178
179    PycURL is dual licensed under the LGPL and an MIT/X derivative license
180    based on the cURL license.  A full copy of the LGPL license is included
181    in the file COPYING-LGPL.  A full copy of the MIT/X derivative license is
182    included in the file COPYING-MIT.  You can redistribute and/or modify PycURL
183    according to the terms of either license.
184
185.. _PycURL: http://pycurl.io/
186.. _libcurl: https://curl.haxx.se/libcurl/
187.. _urllib: http://docs.python.org/library/urllib.html
188.. _`the repository`: https://github.com/pycurl/pycurl
189.. _`mailing list`: http://cool.haxx.se/mailman/listinfo/curl-and-python
190.. _`downloads repository`: https://github.com/pycurl/downloads
191