efl.ecore.Exe Class

class efl.ecore.Exe(exe_cmd, int flags=0, data=None)

Bases: object

Spawns a child process with its stdin/out available for communication.

This function forks and runs the given command using /bin/sh.

Note that the process handle is only valid until a child process terminated event is received. After all handlers for the child process terminated event have been called, the handle will be freed by Ecore. In this case the Python wrapper becomes “shallow” and all operations will fail or return bogus/dummy values, although it should not crash.

This class behavior is configurable by means of given constructor flags, that will make Ecore monitor process’ stdout and stderr, emitting events on main loop.

To write use send(). To read listen to ECORE_EXE_EVENT_DATA or ECORE_EXE_EVENT_ERROR events (see below). Ecore may buffer read and error data until a newline character if asked for with the flags. All data will be included in the events (newlines will be replaced with NULLS if line is buffered).

ECORE_EXE_EVENT_DATA events will only happen if the process is run with ECORE_EXE_PIPE_READ enabled in the flags. The same with the error version. Writing will only be allowed with ECORE_EXE_PIPE_WRITE enabled in the flags.

Instance Event Handling

To make use easier, there are methods that automatically filter events for this instance and deletes them when the Exe is deleted:

• on_add_event_add()

• on_add_event_del()

• on_del_event_add()

• on_del_event_del()

• on_data_event_add()

• on_data_event_del()

• on_error_event_add()

• on_error_event_del()

The callback signatures are:

func(exe, event, *args, **kargs)

In contrast with C-api conformant functions. This only receives the events from this exact exe instance. The signature is also very different, the first parameter is the Exe reference and the return value does not removes the event listener!

Using this method is likely more efficient than the C-api since it will not convert from C to Python lots of times, possibly useless.

However, there are C-api conformat functions as well.

Event Handling (C-api conformant)

Getting data from executed processed is done by means of event handling, which is also used to notify whenever this process really started or died.

One should listen to events in the main loop, such as:

EventExeAdd

listen with on_exe_add_event_add() to know when sub processes were started and ready to be used.

EventExeDel

listen with on_exe_del_event_add() to know when sub processes died.

EventExeData

listen with on_exe_data_event_add() to know when sub processes output data to their stdout.

EventExeError

listen with on_exe_error_event_add() to know when sub processes output data to their stderr.

Events will have the following signature, as explained in EventHandler:

func(event, *args, **kargs): bool

That mean once registered, your callback func will be called for all known Exe instances (that were created from Python!). You can query which instance created such event with event.exe property. Thus you often need to filter if the event you got is from the instance you need! (This is designed to match C-api).

Once your function returns evaluates to False (note: not returning means returning None, that evaluates to False!), your callback will not be called anymore and your handler is deleted.

One may delete handlers explicitly with EventHandler.delete() method.

Parameters

• exe_cmd (str) – command to execute as subprocess.

• flags (int) –

  if given (!= 0), should be bitwise OR of

  ECORE_EXE_PIPE_READ

  Exe Pipe Read mask

  ECORE_EXE_PIPE_WRITE

  Exe Pipe Write mask

  ECORE_EXE_PIPE_ERROR

  Exe Pipe error mask

  ECORE_EXE_PIPE_READ_LINE_BUFFERED

  Reads are buffered until a newline and delivered 1 event per line.

  ECORE_EXE_PIPE_ERROR_LINE_BUFFERED

  Errors are buffered until a newline and delivered 1 event per line.

  ECORE_EXE_PIPE_AUTO

  stdout and stderr are buffered automatically

  ECORE_EXE_RESPAWN

  Exe is restarted if it dies

  ECORE_EXE_USE_SH

  Use /bin/sh to run the command.

  ECORE_EXE_NOT_LEADER

  Do not use setsid() to have the executed process be its own session leader

  ECORE_EXE_TERM_WITH_PARENT

  Makes child receive SIGTERM when parent dies

  ECORE_EXE_ISOLATE_IO

  Try and isolate stdin/out and err of the process so it isn’t shared with the parent. Since 1.21

• data – extra data to be associated and available with data_get()

auto_limits_set(start_bytes, end_bytes, start_lines, end_lines)

Sets the auto pipe limits for the given process handle

Parameters

• start_bytes – limit of bytes at start of output to buffer.

• end_bytes – limit of bytes at end of output to buffer.

• start_lines – limit of lines at start of output to buffer.

• end_lines – limit of lines at end of output to buffer.

close_stdin()

Close executed process’ stdin.

The stdin of the given child process will not be closed immediately. Instead it will be closed when the write buffer is empty.

cmd_get()

Retrieves the command of the executed process.

Returns

the command line string if execution succeeded, None otherwise.

Return type

str or None

continue_()

Send continue signal (SIGCONT) to executed process.

This resumes application previously paused with pause()

data_get()

delete()

Forcefully frees the given process handle.

Note that the process that the handle represents is unaffected by this function, this just stops monitoring the stdout/stderr and emitting related events.

To finish the process call terminate() or kill().

flags_get()

Retrieves the flags attached to the given process handle.

• ECORE_EXE_PIPE_READ: Exe Pipe Read mask

• ECORE_EXE_PIPE_WRITE: Exe Pipe Write mask

• ECORE_EXE_PIPE_ERROR: Exe Pipe error mask

• ECORE_EXE_PIPE_READ_LINE_BUFFERED: Reads are buffered until a newline and delivered 1 event per line.

• ECORE_EXE_PIPE_ERROR_LINE_BUFFERED: Errors are buffered until a newline and delivered 1 event per line

• ECORE_EXE_PIPE_AUTO: stdout and stderr are buffered automatically

• ECORE_EXE_RESPAWN: Exe is restarted if it dies

• ECORE_EXE_USE_SH: Use /bin/sh to run the command.

• ECORE_EXE_NOT_LEADER Do not use setsid() to have the executed process be its own session leader

• ECORE_EXE_TERM_WITH_PARENT Makes child receive SIGTERM when parent dies

• ECORE_EXE_ISOLATE_IO Try and isolate stdin/out and err of the process so it isn’t shared with the parent

Returns

set of masks, ORed.

free()

Alias for delete() to keep compatibility with C-api.

hup()

Send hup signal (SIGHUP) to executed process.

interrupt()

Send interrupt signal (SIGINT) to executed process.

Note

Python usually installs SIGINT handler to generate KeyboardInterrupt, however Ecore will override this handler with its own that generates ECORE_EVENT_SIGNAL_EXIT in its main loop for the application to handle. Pay attention to this detail if your child process is also using Ecore.

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

New in version 1.18.

kill()

Send kill signal (SIGKILL) to executed process.

This signal is fatal and will exit the application as it cannot be blocked.

on_add_event_add(func, *args, **kargs)

Adds event listener to know when this Exe was actually started.

The given function will be called with the following signature every time this Exe receives an ECORE_EXE_EVENT_ADD signal:

func(exe, event, *args, **kargs)

In contrast with on_exe_add_event_add(), this only receives the events from this exact exe instance. The signature is also very different, the first parameter is the Exe reference and the return value does not removes the event listener!

See

on_add_event_del()

See

on_exe_add_event_add()

on_add_event_del(func, *args, **kargs)

Removes the event listener registered with on_add_event_add().

Parameters must be exactly the same.

Raises

ValueError – if parameters don’t match an already registered callback.

on_data_event_add(func, *args, **kargs)

Adds event listener to know when this Exe was actually started.

The given function will be called with the following signature every time this Exe receives an ECORE_EXE_EVENT_DATA signal:

func(exe, event, *args, **kargs)

In contrast with on_exe_data_event_add(), this only receives the events from this exact exe instance. The signature is also very different, the first parameter is the Exe reference and the return value does not removes the event listener!

See

on_data_event_del()

See

on_exe_data_event_add()

on_data_event_del(func, *args, **kargs)

Removes the event listener registered with on_data_event_add().

Parameters must be exactly the same.

Raises

ValueError – if parameters don’t match an already registered callback.

on_del_event_add(func, *args, **kargs)

Adds event listener to know when this Exe was actually started.

The given function will be called with the following signature every time this Exe receives an ECORE_EXE_EVENT_DEL signal:

func(exe, event, *args, **kargs)

In contrast with on_exe_del_event_add(), this only receives the events from this exact exe instance. The signature is also very different, the first parameter is the Exe reference and the return value does not removes the event listener!

See

on_del_event_del()

See

on_exe_del_event_add()

on_del_event_del(func, *args, **kargs)

Removes the event listener registered with :py:func`on_del_event_add`.

Parameters must be exactly the same.

Raises

ValueError – if parameters don’t match an already registered callback.

on_error_event_add(func, *args, **kargs)

Adds event listener to know when this Exe was actually started.

The given function will be called with the following signature every time this Exe receives an ECORE_EXE_EVENT_ERROR signal:

func(exe, event, *args, **kargs)

In contrast with on_exe_error_event_add(), this only receives the events from this exact exe instance. The signature is also very different, the first parameter is the Exe reference and the return value does not remove the event listener!

See

on_error_event_del()

See

on_exe_error_event_add()

on_error_event_del(func, *args, **kargs)

Removes the event listener registered with on_error_event_add().

Parameters must be exactly the same.

Raises

ValueError – if parameters don’t match an already registered callback.

pause()

Send pause signal (SIGSTOP) to executed process.

In order to resume application execution, use continue_()

pid_get()

Retrieves the process ID of the executed process.

Return type

int

quit()

Send quit signal (SIGQUIT) to executed process.

resume()

Alias for continue_()

send(buf, size=0)

Sends data to the executed process, which it receives on stdin.

This function writes to a child processes standard in, with unlimited buffering. This call will never block. It may fail if the system runs out of memory.

Parameters

• buffer – object that implements buffer interface, such as strings (str).

• size – if greater than zero, then this will limit the size of given buffer. If None, then the exact buffer size is used.

Raises

ValueError – if size is larger than buffer size.

Returns

success or failure.

Return type

bool

signal(num)

Send SIGUSR1 or SIGUSR2 to executed process.

Parm num

user signal number, either 1 or 2.

See

POSIX kill(2) and kill(1) man pages.

Raises

ValueError – if num is not 1 or 2.

stop()

Alias for pause

tag_get()

Retrieves the tag attached to the given process.

This is a string that is attached to this handle and may serve as further information.

Note

not much useful in Python, but kept for compatibility with C-api.

Return type

str or None

tag_set(*tag)

Sets the string tag for the given process.

This is a string that is attached to this handle and may serve as further information.

Note

not much useful in Python, but kept for compatibility with C-api.

terminate()

Send terminate signal (SIGTERM) to executed process.

class efl.ecore.EventExeAdd

Bases: efl.ecore.Event

Represents Ecore_Exe_Event_Add event from C-api.

This event notifies that the process created with Exe has been started.

Variables

exe (Exe) – Instance of Exe that created this event.

class efl.ecore.EventExeDel

Bases: efl.ecore.Event

Represents Ecore_Exe_Event_Del from C-api.

This event notifies that the process created with Exe is now dead.

Variables

• exe (Exe) – Instance of Exe that created this event.

• pid (int) – Process ID

• exit_code (int) – Exit code

• exit_signal (int) – Exit signal

• exited (bool) – Has process exited

• signalled (bool) – Has process been signalled

class efl.ecore.EventExeData

Bases: efl.ecore.Event

Represents Ecore_Exe_Event_Data from C-api.

This event is issued by Exe instances created with flags that allow reading from either stdout or stderr.

Variables

• exe (Exe) – Instance of Exe that created this event.

• ~EventExeData.data (string) – The raw string buffer with binary data from child process.

• ~EventExeData.size (int) – The size of data (same as len(data))

• lines (list) – List of strings with all text lines