music.setup_engine

music.setup_engine(method='http')

Clone the eCantorix repository into the user’s cache directory.

The engine is a Perl program driving espeak through a Makefile, so it is cloned rather than installed from PyPI, and it needs git, make, perl, espeak, abc2midi and sox on the system, and the Perl modules in PERL_MODULES. Set $MUSIC_ECANTORIX_DIR to choose a different location.

Parameters:

method{‘http’, ‘ssh’}

How to reach GitHub.

Returns:

str

The engine directory, whether it was just cloned or already present. A new clone is of ENGINE_REVISION; one already present is used as it is, so an engine cloned before the revision was pinned stays what it was until its directory is removed and this is run again.

Raises:

ValueError

If method is not ‘http’ or ‘ssh’.

RuntimeError

If a required external program is missing, the clone fails, or the directory already holds something that is not the engine. git refuses to clone into a directory that is not empty, and said so as an exit status; this says which directory, and leaves what is in it alone.

Examples

>>> setup_engine()
'.../music/ecantorix'