11 Emzed Projects¶

Initializing projects¶

To create a new project type:

emzed_project_new('test_project')

create virtual env at C:\Users\pkiefer\AppData\Roaming\emzed3\emzed3_projects\test_project\.venv

As you might have realized initializing a new project takes a moiment. This is because for each project a virtual environment with current versions of all used packages is created including the current emzed version to minimize version conflict issues of used packages.

After initializing project is finished you are asked to …

After closing the current an opening a now console the active project test_project is indicated at the beginning of the command line

Moreover, a file setup.py was opened in Spyder editor. It contains basic project information i.e. version, author, and a short description of package. setup also provides a gnu license protecting your project authorship. Just fill in required information.

Finally we save the file and we run the command

emzed_project_update()

We can use the Spyder file browser to closer inspect the project structure

Our project test_project is a subfolder of emzed3_projects. test_project contains the setup.py we have just modified. Moerover, it contains the 3 subfolder .venv, src, and tests. All project scripts will be saved in ./src/emzed_ext_test_project. By default the folder contains already the files __init__.py and example_module.py. By clicking the file __init__.py it will open in the editor

import pkg_resources

__version__ = tuple(map(int, pkg_resources.require(__name__)[0].version.split(".")))


# IMPORTS WHICH SHOULD APPEAR IN emzed.ext.test_project
# AFTER INSTALLING THE PACKAGE:
from .example_module import compute

Most important: the __init__ file handles the project name space. You can design your name space by importing different modules or module functions. By default, the current name space of test_project contains the function compute from example_module. We can access now the project name space via emzed.ext.'my_project' as shown here:

Next we will add a new module awsome.py to the project by saving it into

./src/emzed_ext_test_project

and we will add a function to our module awsome:

def monty():
    return 'Python'

Now we will update again the __init__ file to add the function monty to test_project name_space:

from .awsome import monty

Note the . prior to the module name is important since it refers to the local project path.

After saving and opening a new console we can execute

Remark: the command emzed_project_activate('project_name')allows switching between projects If you do not provide a name, an indexed list of all existing projects is provided and you can select a project by index. With the command emzed_project_deactivate() you can leave the project environment.

Code testing¶

emzed3 features Pytest for better code development. With increasing project complexity testing beocmes mandatory to obtain stable code. emzed3 provides a structured testing environment. All code tests scripts are saved in the tests subfolder. It already contains the file test_test_project.py containing tests of example_module:

from emzed_ext_test_project import compute
from emzed_ext_test_project.example_module import \
    path_to_data_file


def test_compute():
    assert compute() == 42


def test_read_data_file():
    with open(path_to_data_file("readme.txt")) as fh:
        txt = fh.read()
    assert txt != ""

We can run the tests with the command

emzed_project_test()

As we can see, both test pass. The next important question is about test completeness. How much of our code is covered by the current tests? We can check this with the command

emzed_project_test_coverage()

resulting

The command not only runs the test but also analyzes how much of the code is covered by the current test of all project modules. Currently, tests do only partially cover the code of modules example_module and awesome. Note, the coverage of awesome is already 67 % although we didn’t write any test. This is due to empty lines and comments in the module which do not require a test but will be counted to determine the percentage of module code tested. To yield complete code coverage two more tests are required.

1. example_module has the function

add(a, b)

A test function could look like

def test_add():
    a=3.3
    b=2.5
    assert add(a,b) == a + b

2. awsome has the function

monty()

An the obvious test function would be

def test_monty():
    assert monty() == 'Python'

We can now adding both tests to provided test file. Before we can run the tests, we have to import monty first. The resulting test script looks like this:

Now we can execute again the command

emzed_project_test_coverage()

resulting

Tests cover now 100% of code. Note, this doesn’t mean that the code is fine because not all use cases have been tested.

To share the code with other users two more steps are missing. To test whether current emzed project is installable we have to run

emzed_project_test_installability()

Note, running the command might take a while since all previous commands will be executed again. Though time consuming, such procedure guarantees that all required quality checks were applied to the current version. Now the project is ready to be shared.

Sharing projects¶

emzed features two ways of project sharing. If you want to distribute your project only to a limited number of users i.e. to your coworkers, the easiest way to do so is creating a wheel. In emzed you can create the wheel with the command

emzed_project_build_wheel()

REMARKS:

• Each time you update your project, you should also change the version number of your project. emzed uses sequence-based scheme, with each version is a sequence of numbers separated by dots . i.e. 1.1.23 following the scheme MAJOR.MINOR.MICRO. Good practice about how to handle version changes are exemplarily explained here.

• To distribute your code to a larger community you can make it available via the Python Package Index PyPi. Since emzed projects are fully packaged you can upload them directly to PyPI without further processing. As already mentioned above it is necessary to register first. Once this is done we can share the project. It is good practice to upload your package to the TestPyPI instance.

• Make sure your project was build with the latest emzed version. Remember each project has it’s own virtual environment. You can upgrade the version of your emzed project by executing the command emzed_update() when the project is activated

Since publishing procedure on PyPI and on TestPyPI is identical we will demonstrate the principle on the test instance. Note, the command

emzed_project_build_wheel()

must be executed first!

To publish on PyPI use the command

emzed_project_upload()

Installing emzed projects¶

You can install all emzed projects as extension using pip install command. To install an emzed project as wheel from a local source, we select the folder containing the wheel file in Spyder file browser window:

And we can install the wheel directly:

pip install emzed_ext_test_project-0.0.1-py3-none-any.whl

Alternatively, you can also provide the path to the wheel relative to the current folder. After opening a new IPython console the project will be available as extension:

installing third party Python packages¶

The emzed project environment allows you testing and installing other python packages safely since each project has its own virtual environment and potential conflicts with emzed core packages will not harm your emzed installation. For instance, to add my_package, do the following:

1. Create a new or activate an existing project

emzed_project_new('name')

or

emzed_project_activate()

2. open emzed project setup.py

3. add the package to requirements

4. run

emzed_project_update()

5. test whether the installed package is compatible with emzed.

6. To add other required packages continue with 2)

Compatible packages might be installed directly using pip install.

Note: In that particular case it makes not too much sense uploading the package to PyPI or creating a wheel. In case you have the feeling there exists a general high demand for a certain package by the emzed community, you can directly ask the developers to integrate the package into emzed3.