Skip to content

Projects and emzed Extensions

Projects give each piece of work its own isolated Python environment. They are useful when developing emzed extensions, when different analyses need different package versions, or when you want to package and share your work — either by uploading it to PyPI or by building a wheel for direct distribution.

Where projects live

Platform Path
macOS / Linux ~/.emzed3_projects/<name>/
Windows %APPDATA%\emzed3_projects\<name>\

On macOS and Linux the folder is hidden (dot-prefix). You can open it in a terminal with:

cd ~/.emzed3_projects

On Windows, %APPDATA% resolves to C:\Users\<your name>\AppData\Roaming\, which is hidden by default. The easiest way to open it is to paste %APPDATA%\emzed3_projects directly into the Windows Explorer address bar and press Enter.

Each project has a .venv/ subdirectory. The project venv inherits emzed and its dependencies from the shared emzed env, so only project-specific packages need to be installed on top.

Creating a project

emzed_project_new("myproject")

This will:

  1. Create the project folder with a setup.py, requirements_dev.txt, LICENSE.txt, and a src/emzed_ext_myproject/ package skeleton.
  2. Create a .venv/ inheriting from the shared emzed env.
  3. Activate the project and open setup.py in the editor.

After editing setup.py and requirements_dev.txt, run:

emzed_project_update()

Switching projects

emzed_project_activate("myproject")   # switch to a project
emzed_project_deactivate()            # return to the default emzed env
emzed_project_list()                  # show all projects

After activating or deactivating, open a fresh terminal for the change to take effect. The active project name is shown in the terminal prompt, and the startup banner also shows the active project, resolved environment path, and Python version.

Only one project can be active at a time. emzed_project_deactivate() returns to the default shared emzed environment.

Command reference

Function Description
emzed_project_new(name) Create a new project
emzed_project_activate(name) Switch the active project
emzed_project_deactivate() Return to the default emzed env
emzed_project_list() List all projects
emzed_project_update(name) Reinstall after setup.py changes
emzed_project_test(name) Run the test suite
emzed_project_test_coverage(name) Run tests and open coverage report
emzed_project_build_wheel(name) Build a distributable wheel
emzed_project_upload_test(name) Upload to test.pypi.org
emzed_project_upload(name) Upload to pypi.org

The name argument is optional in all cases, but the behaviour when omitted differs:

  • update, test, test_coverage, build_wheel, upload_test, upload — use the currently active project (an error is shown if none is active)
  • activate — shows a numbered list of projects to choose from interactively
  • new — prompts for a name interactively

Publishing a project to PyPI

Use emzed_project_upload_test first to verify the package on test.pypi.org before publishing to the real index:

emzed_project_upload_test()   # uploads to test.pypi.org
emzed_project_upload()        # uploads to pypi.org (requires prior test upload)

Both commands will:

  1. Run the full test suite via tox to check installability.
  2. Build a wheel into the project's dist/ folder.
  3. Prompt for your PyPI username and password and upload via twine.

emzed_project_upload checks that the same version was already successfully uploaded to test.pypi.org before proceeding.