1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
setopt(option, value) -> None
Set curl session option. Corresponds to `curl_easy_setopt`_ in libcurl.
*option* specifies which option to set. PycURL defines constants
corresponding to ``CURLOPT_*`` constants in libcurl, except that
the ``CURLOPT_`` prefix is removed. For example, ``CURLOPT_URL`` is
exposed in PycURL as ``pycurl.URL``, with some exceptions as detailed below.
For convenience, ``CURLOPT_*``
constants are also exposed on the Curl objects themselves::
import pycurl
c = pycurl.Curl()
c.setopt(pycurl.URL, "http://www.python.org/")
# Same as:
c.setopt(c.URL, "http://www.python.org/")
The following are exceptions to option constant naming convention:
- ``CURLOPT_FILETIME`` is mapped as ``pycurl.OPT_FILETIME``
- ``CURLOPT_CERTINFO`` is mapped as ``pycurl.OPT_CERTINFO``
- ``CURLOPT_COOKIELIST`` is mapped as ``pycurl.COOKIELIST``
*value* specifies the value to set the option to. Different options accept
values of different types:
- Options specified by `curl_easy_setopt`_ as accepting ``1`` or an
integer value accept Python integers, long integers (on Python 2.x) and
booleans::
c.setopt(pycurl.FOLLOWLOCATION, True)
c.setopt(pycurl.FOLLOWLOCATION, 1)
# Python 2.x only:
c.setopt(pycurl.FOLLOWLOCATION, 1L)
- Options specified as accepting strings by ``curl_easy_setopt`` accept
byte strings (``str`` on Python 2, ``bytes`` on Python 3) and
Unicode strings with ASCII code points only.
For more information, please refer to :ref:`unicode`. Example::
c.setopt(pycurl.URL, "http://www.python.org/")
c.setopt(pycurl.URL, u"http://www.python.org/")
# Python 3.x only:
c.setopt(pycurl.URL, b"http://www.python.org/")
- ``HTTP200ALIASES``, ``HTTPHEADER``, ``POSTQUOTE``, ``PREQUOTE``,
``PROXYHEADER`` and
``QUOTE`` accept a list or tuple of strings. The same rules apply to these
strings as do to string option values. Example::
c.setopt(pycurl.HTTPHEADER, ["Accept:"])
c.setopt(pycurl.HTTPHEADER, ("Accept:",))
- ``READDATA`` accepts a file object or any Python object which has
a ``read`` method. On Python 2, a file object will be passed directly
to libcurl and may result in greater transfer efficiency, unless
PycURL has been compiled with ``AVOID_STDIO`` option.
On Python 3 and on Python 2 when the value is not a true file object,
``READDATA`` is emulated in PycURL via ``READFUNCTION``.
The file should generally be opened in binary mode. Example::
f = open('file.txt', 'rb')
c.setopt(c.READDATA, f)
- ``WRITEDATA`` and ``WRITEHEADER`` accept a file object or any Python
object which has a ``write`` method. On Python 2, a file object will
be passed directly to libcurl and may result in greater transfer efficiency,
unless PycURL has been compiled with ``AVOID_STDIO`` option.
On Python 3 and on Python 2 when the value is not a true file object,
``WRITEDATA`` is emulated in PycURL via ``WRITEFUNCTION``.
The file should generally be opened in binary mode. Example::
f = open('/dev/null', 'wb')
c.setopt(c.WRITEDATA, f)
- ``*FUNCTION`` options accept a function. Supported callbacks are documented
in :ref:`callbacks`. Example::
# Python 2
import StringIO
b = StringIO.StringIO()
c.setopt(pycurl.WRITEFUNCTION, b.write)
- ``SHARE`` option accepts a :ref:`curlshareobject`.
It is possible to set integer options - and only them - that PycURL does
not know about by using the numeric value of the option constant directly.
For example, ``pycurl.VERBOSE`` has the value 42, and may be set as follows::
c.setopt(42, 1)
*setopt* can reset some options to their default value, performing the job of
:py:meth:`pycurl.Curl.unsetopt`, if ``None`` is passed
for the option value. The following two calls are equivalent::
c.setopt(c.URL, None)
c.unsetopt(c.URL)
Raises TypeError when the option value is not of a type accepted by the
respective option, and pycurl.error exception when libcurl rejects the
option or its value.
.. _curl_easy_setopt: https://curl.haxx.se/libcurl/c/curl_easy_setopt.html
|
