efl.ecore_con.Url
Class¶
- class efl.ecore_con.Url(url, custom_request=None, **kargs)¶
Bases:
efl.eo.Eo
Utility class to make it easy to perform http requests (POST, GET, etc).
New in version 1.17.
- Brief usage:
Create an
Url
object with ecore_con.Url(‘myurl’)Register object callbacks using
on_complete_event_add()
,on_progress_event_add()
andon_data_event_add()
to receive the response, e.g. for HTTP/FTP downloads.
If it’s necessary use the
url
property. to change the object url.Note
It is good practice to reuse
Url
objects wherever possible, but bear in mind that each one can only perform one operation at a time. You need to wait for the complete event before re-using or destroying the object.Warning
It is really important to call the
delete()
method as soon as you have finished with your object, as it automatically remove all the registered events for you, that will otherwise continue to use resources.Basic usage examples:
# HTTP GET u = ecore.Url("http://www.google.com") u.get() # HTTP POST u = ecore.Url('https://httpbin.org/post') u.post(b'my data to post', 'text/txt') # FTP download u = ecore.Url("ftp://ftp.example.com/pub/myfile") u.get() # FTP upload as ftp://ftp.example.com/file u = ecore.Url("ftp://ftp.example.com") u.ftp_upload("/tmp/file", "user", "pass", None) # FTP upload as ftp://ftp.example.com/dir/file u = ecore.Url("ftp://ftp.example.com") u.ftp_upload("/tmp/file", "user", "pass", "dir")
To actually make something usefull with your request you will need to connect the
EventUrlComplete
,EventUrlProgress
andEventUrlData
events using theon_complete_event_add()
and friends functions.A more complete example:
from efl import ecore def on_data(event): print("data: " + str(event.data[:80])) # do something here with the received data def on_progress(event): # print(event) print("received %d on a total of %d bytes" % ( event.down_now, event.down_total)) def on_complete(event): # print(event) print("http result: %d" % event.status) print("Total received bytes: %d" % event.url.received_bytes) u.delete() # don't forget to delete !! u = ecore.Url('http://www.google.com', verbose=False) u.on_data_event_add(on_data) u.on_progress_event_add(on_progress) u.on_complete_event_add(on_complete) u.get() ecore.main_loop_begin()
If you need to save the received data to a file use the
fd
property, as:fd = open('/tmp/tmpMxBtta', 'w') u = ecore.Url('http://example.com', fd=fd.fileno()) u.get()
See also
If you just need to download a file please consider using the simpler
efl.ecore.FileDownload
class instead.See also
The ecore module level functions
url_pipeline_set()
andurl_pipeline_get()
to enable HTTP 1.1 pipelining.- Parameters
url (string) – URL that will receive requests.
custom_request (string) – Custom request (e.g. GET, POST, HEAD, PUT, HEAD, SUBSCRIBE and other obscure HTTP requests)
**kwargs – All the remaining keyword arguments are interpreted as properties of the instance
New in version 1.17.
- additional_header_add(key, value)¶
Add an additional header to the request connection object.
Add an additional header (User-Agent, Content-Type, etc.) to the request connection object. This addition will be valid for only one
get()
orpost()
call.- Parameters
key (string) – Header key
value (string) – Header value
Some functions like
time()
also add headers to the request.
- additional_headers_clear()¶
Clean additional headers.
Clean additional headers associated with a connection object (previously added with :func:additional_header_add`).
- cookies_clear()¶
Clear currently loaded cookies.
The cleared cookies are removed and will not be sent in subsequent HTTP requests, nor will they be written to the cookiejar file set via
cookies_jar_file
.Note
This function will initialize the cookie engine if it has not been initialized yet. The cookie files set by
cookies_file_add()
aren’t loaded immediately, just when the request is started. Thus, if you ask to clear the cookies, but has a file already set by that function, the cookies will then be loaded and you will have old cookies set. In order to don’t have any old cookie set, you need to don’t callcookies_file_add()
ever on theUrl
class, and call this function to clear any cookie set by a previous request on this handler.
- cookies_file_add(file_name)¶
Add a file to the list of files from which to load cookies.
- Files must contain cookies defined according to two possible formats:
HTTP-style header (“Set-Cookie: …”).
Netscape/Mozilla cookie data format.
Cookies will only be read from this file. If you want to save cookies to a file, use
cookies_jar_file
. Also notice that this function supports the both types of cookie file cited above, whilecookies_jar_file
will save only in the Netscape/Mozilla’s format.Please notice that the file will not be read immediately, but rather added to a list of files that will be loaded and parsed at a later time.
Note
This function will initialize the cookie engine if it has not been initialized yet.
- Parameters
file_name (string) – Name of the file that will be added to the list.
- cookies_ignore_old_session¶
Control whether session cookies from previous sessions shall be loaded.
Session cookies are cookies with no expire date set, which usually means they are removed after the current session is closed.
By default, when Ecore_Con_Url loads cookies from a file, all cookies are loaded, including session cookies, which, most of the time, were supposed to be loaded and valid only for that session.
If ignore is set to
True
, when Ecore_Con_Url loads cookies from the files passed tocookies_file_add()
, session cookies will not be loaded.- Type
bool (writeonly)
- cookies_init()¶
Enable the cookie engine for subsequent HTTP requests.
After this function is called, cookies set by the server in HTTP responses will be parsed and stored, as well as sent back to the server in new HTTP requests.
- cookies_jar_file¶
The name of the file to which all current cookies will be written when either cookies are flushed or Ecore_Con is shut down.
Cookies are written following Netscape/Mozilla’s data format, also known as cookie-jar.
Cookies will only be saved to this file. If you need to read cookies from a file, use ecore_con_url_cookies_file_add() instead.
Note
This function will initialize the cookie engine if it has not been initialized yet.
See also
- Type
string (writeonly)
- cookies_jar_write()¶
Write all current cookies to the cookie jar immediately.
A cookie-jar file must have been previously set by
cookies_jar_file
, otherwise nothing will be done.Note
This function will initialize the cookie engine if it has not been initialized yet.
See also
- cookies_session_clear()¶
Clear currently loaded session cookies.
Session cookies are cookies with no expire date set, which usually means they are removed after the current session is closed.
The cleared cookies are removed and will not be sent in subsequent HTTP requests, nor will they be written to the cookiejar file set via
cookies_jar_file
.Note
This function will initialize the cookie engine if it has not been initialized yet. The cookie files set by
cookies_file_add()
aren’t loaded immediately, just when the request is started. Thus, if you ask to clear the session cookies, but has a file already set by that function, the session cookies will then be loaded and you will have old cookies set. In order to don’t have any old session cookie set, you need to don’t callcookies_file_add()
ever on theUrl
class, and call this function to clear any session cookie set by a previous request on this handler. An easier way to don’t use old session cookies is by using the functioncookies_ignore_old_session
.
- delete()¶
Delete the
Url
object and free all used resources.Note
This is really important to call as soon as you have finished with your object, as it automatically remove all the registered events. That will otherwise continue to use resources.
- fd¶
Set up a file to have response data written into.
This attr can be used to easily setup a file where the downloaded data will be saved.
Note that
EventUrlData
events will not be emitted if a file has been set to receive the response data.See also
If you just need to download a file please consider using the simpler
efl.ecore.FileDownload
class instead.- Type
int (writeonly)
- ftp_upload(filename, user, passwd, upload_dir)¶
Upload a file to an ftp site.
- Parameters
filename (string) – The path to the file to send
user (string) – The username to log in with
passwd (string) – The password to log in with
upload_dir (string) – The directory to which the file will upload
- Returns
True
on success,False
otherwise.- Return type
bool
- ftp_use_epsv¶
Enable or disable EPSV extension.
- Type
bool (writeonly)
- get()¶
Send a GET request.
The request is performed immediately, but you need to setup event handlers with
on_complete_event_add()
oron_complete_event_add()
to get more information about its result.- Returns
True
on success,False
on error.
- head()¶
Send a HEAD request.
The request is performed immediately, but you need to setup event handlers with
on_complete_event_add()
oron_complete_event_add()
to get more information about its result.- Returns
True
on success,False
on error.
- http_version¶
The HTTP version used for the request.
Can be
ECORE_CON_URL_HTTP_VERSION_1_0
orECORE_CON_URL_HTTP_VERSION_1_1
- Type
Ecore Con Url Http Version (writeonly)
- httpauth_set(username, password, safe)¶
Set to use http auth, with given username and password
- Parameters
username (string) – Username to use in authentication
password (string) – Password to use in authentication
safe (bool) – Whether to use “safer” methods (eg, NOT http basic auth)
- Returns
True
on success,False
on error.- Return type
bool
Warning
Require libcurl >= 7.19.1 to work, otherwise will always return
False
.
- is_deleted()¶
Check if the object has been deleted thus leaving the object shallow.
- Returns
True if the object has been deleted yet, False otherwise.
- Return type
bool
- on_complete_event_add(func, *args, **kargs)¶
Adds event listener to know when the Url operation is completed.
The given function will be called with the following signature:
func(event, *args, **kargs)
The
event
parameter is anEventUrlComplete
instance.
- on_complete_event_del(func, *args, **kargs)¶
Removes an event listener previously registered
Parameters must match exactly the ones given in the
on_complete_event_add()
call- Raises
ValueError – if parameters don’t match an already registered callback.
- on_data_event_add(func, *args, **kargs)¶
Adds event listener to collect the data while they are received.
The given function will be called with the following signature:
func(event, *args, **kargs)
The
event
parameter is anEventUrlData
instance.
- on_data_event_del(func, *args, **kargs)¶
Removes an event listener previously registered
Parameters must match exactly the ones given in the
on_data_event_add()
call- Raises
ValueError – if parameters don’t match an already registered callback.
- on_progress_event_add(func, *args, **kargs)¶
Adds event listener to know the operation status progress.
The given function will be called with the following signature:
func(event, *args, **kargs)
The
event
parameter is anEventUrlProgress
instance.
- on_progress_event_del(func, *args, **kargs)¶
Removes an event listener previously registered
Parameters must match exactly the ones given in the
on_progress_event_add()
call- Raises
ValueError – if parameters don’t match an already registered callback.
- post(data, content_type)¶
Send a post request.
The request is performed immediately, but you need to setup event handlers with
on_complete_event_add()
oron_complete_event_add()
to get more information about its result.- Parameters
data (bytes) – Payload (data sent on the request). Can be
None
.content_type (string) – Content type of the payload (e.g. text/xml). Can be
None
.
- Returns
True
on success,False
on error.
- proxy¶
Set the HTTP proxy to use.
The parameter is the host name or dotted IP address. To specify port number in this string, append :[port] to the end of the host name. The proxy string may be prefixed with [protocol]:// since any such prefix will be ignored. The proxy’s port number may optionally be specified with the separate option. If not specified, libcurl will default to using port 1080 for proxies.
Set this to
None
to disable the usage of proxy.- Type
string (writeonly)
- proxy_password¶
Password to use for proxy.
If socks protocol is used for proxy, protocol should be socks5 and above.
- Type
string (writeonly)
- proxy_username¶
Username to use for proxy.
If socks protocol is used for proxy, protocol should be socks5 and above.
- Type
string (writeonly)
- received_bytes¶
The number of bytes received.
Retrieve the number of bytes received on the last request of the
Url
object.- Type
int (readonly)
- response_headers¶
The headers from last request sent.
Retrieve a list containing the response headers. This function should be used after an
EventUrlComplete
event (headers should normally be ready at that time).- Type
list of strings (readonly)
- ssl_ca¶
Set a custom CA to trust for SSL/TLS connections.
Specify the path of a file (in PEM format) containing one or more CA certificate(s) to use for the validation of the server certificate.
This can also disable CA validation if set to
None
. However, the server certificate still needs to be valid for the connection to succeed (i.e., the certificate must concern the server the connection is made to).- Type
string (writeonly)
- ssl_verify_peer¶
Toggle libcurl’s verify peer’s certificate option.
If this is
True
, libcurl will verify the authenticity of the peer’s certificate, otherwise it will not. Default behavior of libcurl is to check peer’s certificate.- Type
bool (writeonly)
- status_code¶
The returned HTTP STATUS code.
This is used to, at any time, try to return the status code for a transmission.
- Type
int (readonly)
- time(time_condition, timestamp)¶
Whether HTTP requests should be conditional, dependent on modification time.
This function may set the header If-Modified-Since or If-Unmodified-Since, depending on the value of time_condition, with the value timestamp.
- Parameters
time_condition (Ecore Con Url Time) – Condition to use for HTTP requests.
timestamp (double) – Time since 1 Jan 1970 to use in the condition.
- timeout¶
transfer timeout in seconds.
The maximum time in seconds that you allow the
Url
class transfer operation to take. Normally, name lookups can take a considerable time and limiting operations to less than a few minutes risk aborting perfectly normal operations.- Type
double (writeonly)
- url¶
Controls the URL to send the request to.
- Type
string
- verbose¶
Toggle libcurl’s verbose output.
If set to
True
, libcurl will output a lot of verbose information about its operations, which is useful for debugging. The verbose information will be sent to stderr.- Type
bool (writeonly)
- class efl.ecore_con.EventUrlComplete¶
Bases:
efl.ecore.Event
Represents Ecore_Con_Event_Url_Complete event from C-api.
This event notifies the operation is completed.
- attributes:
url (
Url
): the object that generate the eventstatus(int): HTTP status code of the operation (200, 404, 401, etc.)
- class efl.ecore_con.EventUrlProgress¶
Bases:
efl.ecore.Event
Represents Ecore_Con_Event_Url_Progress event from C-api.
This event notifies the progress of the current operation.
- attributes:
url (
Url
): the object that generate the eventdown_total(double): total size of the downloading data (in bytes)
down_now(double): current size of the downloading data (in bytes)
up_total(double): total size of the uploading data (in bytes)
up_now(double): current size of the uploading data (in bytes)
- class efl.ecore_con.EventUrlData¶
Bases:
efl.ecore.Event
Represents Ecore_Con_Event_Url_Data event from C-api.
This event hold the data while the are received.
Note
The data attribute is a raw series of bytes, map to
str
in python2 andbytes
in python3.- attributes:
url (
Url
): the object that generate the eventsize(int): the size of the current received data (in bytes)
data(bytes): the data received on this event