e3-core API highlights

e3-core comes with many useful modules, you might find the above selection useful to start using the e3-core API.

e3.fs and e3.os.fs

e3.fs and e3.os.fs modules contain several helpers for writing portable and robust applications.

For instance rm() tries very hard to remove files or directories. On Windows system it is using the e3.os.windows.fs.NTFile class that relies on ctypes to call the Windows native API. This made the removal of files much more reliable on Windows. Using it is as simple as:

rm('/path/to/file')
rm('/path/to/directory', recurive=True)
rm('\*.py')

e3.fs also comes with many other useful functions such as e3.fs.sync_tree() which implement a local rsync, with a very similar API.

Both modules implement many functions that tries to mimic the well known POSIX tools and that are heavily tested on UNIX like platforms and Windows.

e3.os.process

In e3.os.process the e3.os.process.Run class allows running processes under a time limit.

Running:

Run(['python'], timeout=2)

will exit the python program after 2 seconds whereas

Run(['python'])

will never end.

e3.os.process.Run can also be used to pipe several commands, e.g.

p = Run([['tar', 'cf', '-', 'a_dir'], ['gzip', '-9']],
        output='a_dir.tgz',
        error=my_error_log_stream)
assert p.status == 0

e3.main and e3.env

e3.main.Main simply the writing of command line clients depending on --build, --host, --target arguments. It uses e3.env.Env to set the platform environment, which is very useful if your the tool you are writing supports multiple platforms and cross platform environment.

Adding the following code in show-platform

from e3.main import Main
from e3.env import Env
m = Main(platform_args=True)
m.argument_parser.add_argument(
   '--show-platform')
m.parse_args()
print(Env().platform)

will print the following on a macos machine:

$ show-platform
x86_64-darwin

$ show-platform --target=x86-windows --host=x86_64-linux
x86-windows-linux64

Add print(Env().build will output more info on the build platform:

platform: x86_64-darwin
machine:  ida
is_hie:   False
is_host:  True
triplet:  x86_64-apple-darwin16.5.0
domain:   unknown
OS
   name:          darwin
   version:       16.5.0
   exeext:
   dllext:        .dylib
   is_bareboard:  False
CPU
   name:   x86_64
   bits:   64
   endian: little
   cores:  4show-platform

e3.yaml

e3.yaml comes with a YAML loader that loads mappings into ordered dictionaries and with case parser adding case statement in configuration files.

A case parser can be help when you want to pick different packages depending on the build platform.

If we start with a file packages.yaml:

packages:
    - args-0.1.0-py2-none-any.whl
    - enum34-1.1.6-py2-none-any.whl

case_build_os_name:
    linux:
        +packages:
            - psutil-4.3.1.tar.gz
            - netifaces-0.10.4.tar.gz
    windows:
        +packages:
            - psutil-4.3.1-cp27-none-win32.whl
            - netifaces-0.10.4-cp27-none-win32.whl

Also note the special syntax +packages that adds the new entries to the existing packages list.

The function e3.yaml.load_with_config() combines both:

e3.yaml.load_with_config('y.yaml', {'build_os_name': 'x86-windows'})

returns

{'packages': [
    'args-0.1.0-py2-none-any.whl',
    'enum34-1.1.6-py2-none-any.whl',
    'psutil-4.3.1-cp27-none-win32.whl',
    'netifaces-0.10.4-cp27-none-win32.whl']}