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