`efl.ecore_con.Url` Class¶

class efl.ecore_con.Url(url, custom_request=None, **kargs)¶

Bases: efl.eo.Eo

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() and on_data_event_add() to receive the response, e.g. for HTTP/FTP downloads.
Perform the operation with 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:	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() or post() 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 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.

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, 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.

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 to cookies_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

cookies_jar_write()

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_jar_file

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 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:	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() 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:	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 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:	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

This event notifies the operation is completed.

attributes:

url (Url): the object that generate the event
status(int): HTTP status code of the operation (200, 404, 401, etc.)

class efl.ecore_con.EventUrlProgress¶

Bases: efl.ecore.Event

This event notifies the progress of the current operation.

attributes:

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)

class 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.

attributes:

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

Previous topic

Next topic

`efl.ecore_con.Url` Class¶

efl.ecore_con.Url Class¶

`efl.ecore_con.Url` Class¶