Skip to content

Installation and usage

Once a library is packaged (Organization), using it is a pip install away. Because most of the work in this course happens in notebooks (Google Colab), the main path is installing straight from GitHub — no local setup, no cloning by hand.

Install from GitHub

Warning

When installing a library locally, it is worth using virtual environments, especially with libraries under development. This keeps our library from being installed system-wide, and keeps the dependencies of different libraries from mixing. Read Install locally for more information.

pip can install a package directly from a Git repository. This is the quickest way to get esperantilo into a notebook while the library is still moving:

pip install git+https://github.com/jparisu/nlp-esperantilo.git

This clones the repository behind the scenes, builds the package from its pyproject.toml, and installs it — exactly as if it came from the Python Package Index.

You can pin a specific branch, tag or commit by appending @<ref>:

pip install git+https://github.com/jparisu/nlp-esperantilo.git@main
pip install git+https://github.com/jparisu/nlp-esperantilo.git@jparisu/v0.1

Why install from GitHub?

While a library is under active development and not yet published to PyPI, installing from GitHub means everyone always gets the latest code from a chosen branch, with a single command and no manual steps. It is the natural fit for a notebook-based workflow.

Use it in a notebook

In a Colab notebook, install in a cell (the leading ! runs a shell command), then import and use the library:

!pip install git+https://github.com/jparisu/nlp-esperantilo.git

import esperantilo

print(esperantilo.__version__)   # 0.1.0

Restart the runtime after installing

If you had already imported esperantilo in a notebook and then install a new version, restart the runtime (Runtime → Restart) so the new code is picked up. Python caches imported modules for the life of the session.

Install locally

For developing the library itself — rather than just using it — install it locally in a virtual environment. A virtual environment is an isolated Python installation for one project, so its dependencies do not clash with anything else on your machine:

python -m venv .venv          # create the environment
source .venv/bin/activate     # activate it (Windows: .venv\Scripts\activate)
pip install -e ".[test]"      # editable install, with the test extra

Two flags make this a development install:

  • -e (editable). The package is installed as a link to your source, so your edits take effect immediately — no reinstalling after every change.
  • .[test] installs the package plus its test extra (pytest), so you can run the suite right away (see Testing). Use .[docs] to work on the documentation instead.

This is exactly what the tests.yml workflow does in CI, so a green local run means a green run on GitHub.

Where to go next

  • API — what a clean public interface for the library should look like.
  • Testing — run and write the test suite.