efl.ecore_con.Url
Class¶efl.ecore_con.
Url
(url, custom_request=None, **kargs)¶Bases: efl.eo.Eo
New in version 1.17.
Url
object with ecore_con.Url(‘myurl’)on_complete_event_add()
,
on_progress_event_add()
and on_data_event_add()
to
receive the response, e.g. for HTTP/FTP downloads.get()
, head()
and post()
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.
Parameters: |
|
---|
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()
or post()
call.
Parameters: |
|
---|
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.
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.
Parameters: | 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.
Type: | 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
Type: | 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.
Type: | int (writeonly) |
---|
ftp_upload
(filename, user, passwd, upload_dir)¶Upload a file to an ftp site.
Parameters: |
|
---|---|
Returns: |
|
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()
or
on_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()
or
on_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
or
ECORE_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: |
|
---|---|
Returns: |
|
Return type: | bool |
Warning
Require libcurl >= 7.19.1 to work, otherwise will
always return False
.
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 an EventUrlComplete
instance.
See: | on_complete_event_del() |
---|
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 an EventUrlData
instance.
See: | on_data_event_del() |
---|
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 an EventUrlProgress
instance.
See: | on_progress_event_del() |
---|
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()
or
on_complete_event_add()
to get more information about its result.
Parameters: |
|
---|---|
Returns: |
|
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: |
|
---|
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) |
---|
efl.ecore_con.
EventUrlComplete
¶Bases: efl.ecore.Event
This event notifies the operation is completed.
Url
): the object that generate the eventefl.ecore_con.
EventUrlProgress
¶Bases: efl.ecore.Event
This event notifies the progress of the current operation.
Url
): the object that generate the eventefl.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
): the object that generate the event