FAQ¶
Common questions about building, installing and testing the Python library. Each answer links to the page where the topic is covered in full.
What is the difference between a module, a package and a library?
A module is a single .py file; a package is a folder of modules
imported as one unit, normally marked by an __init__.py; a library is a
package meant to be reused by other code.
A distribution is the installable bundle pip fetches. See
What is a library.
Do I need setup.py? What is pyproject.toml?
No — pyproject.toml is the modern, standardised replacement for setup.py.
It holds the project metadata, dependencies and build configuration in one
file. See Organization § pyproject.toml.
Why is the code under src/ instead of at the repository root?
So the package is not importable by accident from the project root. The
src/ layout forces you to install the package before importing it, so your
tests run against the installed library exactly as a user would get it. See
Organization § src.
What is the difference between requirements.txt and pyproject.toml?
pyproject.toml declares what the library needs as part of its identity —
the source of truth when someone installs it. requirements.txt is a
convenience list for pinning a reproducible environment. This library is
rule-based, so it has no runtime dependencies and requirements.txt is
essentially empty. See Organization § requirements.txt.
What does __init__.py do?
It marks a directory as a regular package and defines what the package exposes when imported. (Since Python 3.3 a folder without one is still importable, as a namespace package, but a library should be explicit.) Here it declares the version and, as the library grows, is where public classes are re-exported. See Organization § init.py.
How do I install the library in a Google Colab notebook?
Install it straight from GitHub in a cell, then import it:
What does pip install -e \".[test]\" mean?
-e installs the package in editable mode (a link to your source, so
edits take effect immediately), and .[test] also installs the test extra
(pytest). It is the standard setup for developing the library. See
Installation and usage § Install locally.
I installed a new version in a notebook but nothing changed. Why?
Python caches imported modules for the session. After installing a new version, restart the runtime (Runtime → Restart) so the new code is loaded. See Installation and usage.
What is __all__ for?
It names a module's public objects: it documents the intended API and
controls what from esperantilo import * brings in. Names outside it (and
names starting with _) are treated as private. See API § What an API is here.
Why model the API on spaCy?
Because spaCy's typed Doc / Token design is a proven, pleasant way to
represent analysed text, and Esperanto's regular grammar makes those
attributes computable by rule. It gives a concrete target to imitate. See
API § A spaCy-like API.
How do I run the tests?
Install the test extra and run pytest:
pytest discovers files named test_*.py and functions named test_*
automatically. See Testing.
Do the tests run automatically?
Yes. The tests.yml GitHub Actions workflow runs pytest on every push and
pull request, and branch protection can make passing tests required before
a merge. See Testing § Tests in continuous integration.