efl.ecore_con.Url
Class¶efl.ecore_con.
Url
(url, custom_request=None, **kargs)¶Bases: efl.eo.Eo
New in version 1.17.
Create an Url
object with ecore_con.Url(‘myurl’)
Register object callbacks using on_complete_event_add()
,
on_progress_event_add()
and on_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
and
EventUrlData
events using the on_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()
and
url_pipeline_get()
to enable HTTP 1.1 pipelining.
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
¶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()
or post()
call.
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`).
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 call
cookies_file_add()
ever on the Url
class, and
call this function to clear any cookie set by a previous request on
this handler.
Add a file to the list of files from which to load cookies.
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, while
cookies_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.
file_name (string) – Name of the file that will be added to the list.
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 to cookies_file_add()
, session cookies
will not be loaded.
bool (writeonly)
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.
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
string (writeonly)
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
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
call cookies_file_add()
ever on the Url
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 function
cookies_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.
int (writeonly)
ftp_upload
¶Upload a file to an ftp site.
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
True
on success, False
otherwise.
bool
ftp_use_epsv
¶Enable or disable EPSV extension.
bool (writeonly)
get
¶Send a GET request.
The request is performed immediately, but you need to setup event
handlers with on_complete_event_add()
or
on_complete_event_add()
to get more information about its result.
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()
or
on_complete_event_add()
to get more information about its result.
True
on success, False
on error.
http_version
¶The HTTP version used for the request.
Can be ECORE_CON_URL_HTTP_VERSION_1_0
or
ECORE_CON_URL_HTTP_VERSION_1_1
Ecore Con Url Http Version (writeonly)
httpauth_set
¶Set to use http auth, with given username and password
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)
True
on success, False
on error.
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.
True if the object has been deleted yet, False otherwise.
bool
on_complete_event_add
¶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 an EventUrlComplete
instance.
on_complete_event_del
¶Removes an event listener previously registered
Parameters must match exactly the ones given in the
on_complete_event_add()
call
ValueError – if parameters don’t match an already registered callback.
on_data_event_add
¶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 an EventUrlData
instance.
on_data_event_del
¶Removes an event listener previously registered
Parameters must match exactly the ones given in the
on_data_event_add()
call
ValueError – if parameters don’t match an already registered callback.
on_progress_event_add
¶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 an EventUrlProgress
instance.
on_progress_event_del
¶Removes an event listener previously registered
Parameters must match exactly the ones given in the
on_progress_event_add()
call
ValueError – if parameters don’t match an already registered callback.
post
¶Send a post request.
The request is performed immediately, but you need to setup event
handlers with on_complete_event_add()
or
on_complete_event_add()
to get more information about its result.
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
.
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.
string (writeonly)
proxy_password
¶Password to use for proxy.
If socks protocol is used for proxy, protocol should be socks5 and above.
string (writeonly)
proxy_username
¶Username to use for proxy.
If socks protocol is used for proxy, protocol should be socks5 and above.
string (writeonly)
received_bytes
¶The number of bytes received.
Retrieve the number of bytes received on the last request of the
Url
object.
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).
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).
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.
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.
int (readonly)
time
¶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.
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.
double (writeonly)
url
¶Controls the URL to send the request to.
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.
bool (writeonly)
efl.ecore_con.
EventUrlComplete
¶Bases: efl.ecore.Event
This event notifies the operation is completed.
url (Url
): the object that generate the event
status(int): HTTP status code of the operation (200, 404, 401, etc.)
efl.ecore_con.
EventUrlProgress
¶Bases: efl.ecore.Event
This event notifies the progress of the current operation.
url (Url
): the object that generate the event
down_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)
efl.ecore_con.
EventUrlData
¶Bases: efl.ecore.Event
This event hold the data while the are received.
Note
The data attribute is a raw series of bytes, map to str
in python2
and bytes
in python3.
url (Url
): the object that generate the event
size(int): the size of the current received data (in bytes)
data(bytes): the data received on this event