aboutsummaryrefslogtreecommitdiff
drime - by Antoine Amarilli
A French rhyme dictionary
Licence: GPL version 3


== 1. Features ==

drime is a French rhyme dictionary engine with advanced features, most
notably rhyme selection based on phonetic or visual similarity,
frequency, syllable count, and rhyme gender.

== 2. Requirements ==

drime requires a working Python3 installation.

drime requires the haspirater module <https://a3nm.net/git/haspirater/>. Just
place the "haspirater.py" and "haspirater.json" file in the same folder as the
other files. It also requires the "rhyme.py", "options.py" and "vowels.py"
modules from plint <https://a3nm.net/git/plint/> that you should put in the same
folder, and also "frhyme.py" (see plint's documentation).

drime also requires PyMySQL <http://www.pymysql.org> and Flask
<http://flask.pocoo.org/> for Python3. To install PyMySQL, use for instance:

  sudo pip3 install pymysql
  sudo apt-get install python3-flask

drime requires a working MySQL installation (package mysql-server on Debian
systems) and the instructions in this README require the MySQL client (package
mysql-client) to populate the database. You will probably want to create a
database and a user for drime, probably along the lines of the following SQL
commands executed using "mysql -u root -p":

  CREATE DATABASE drime;
  CREATE USER 'drime'@'localhost' IDENTIFIED BY 'mysecretpassword';
  GRANT ALL ON drime.* TO 'drime'@'localhost';

== 3. Generating the DB ==

The program database isn't shipped, but scripts are provided to build it
from the Lexique3 database <http://lexique.org/>:

- lexique_retrieve.sh retrieves a version of Lexique applies a few
  tweaks, and outputs it to stdout.

- lexique2sql.sh takes the tweaked version of Lexique on stdin and produces
  the SQL database on stdout.

You should therefore run:

  ./lexique_retrieve.sh | ./lexique2sql.sh > output.sql

If this is not your first attempt, unzip might prompt you about overwriting
existing files. Answer 'A'.

To import the output of lexique2sql.sh in a MySQL database (on localhost,
database 'drime', as user 'drime', interactive password authentication, the
password being "mysecretpassword" if you followed the instructions of the
previous section), run:

  cat output.sql |
    cat <(echo 'use drime;') - |
    cat - <(echo 'CREATE UNIQUE INDEX main ON words(word, phon);') |
    sed 's/varchar([0-9]*)/& collate utf8_bin/g' |
    mysql --default-character-set=utf8 -D drime -u drime -p

To monitor progress, use the pv utility (replace "cat output.sql" by
"pv -l output.sql").

== 4. Using the DB ==

== 4.1. Configuring database access ==

Create a file with the connection parameters:

cat > db_mysql_config.py <<EOF
#!/usr/bin/python3 -O

config = {
      'host': 'HOST',
      'user': 'USER',
      'passwd': 'PASSWD',
      'db': 'DB',
    }
EOF

== 4.2. Querying from the web ==

To start the Flask development server, run:

  ./drime.py

You can also deploy as WSGI with Apache2 using drime.wsgi. The configuration
specifics are left as an unpleasant exercise to the reader.

== 4.3. Querying from the command line ==

Run:

  ./query.py QUERY [NSYL [GENDER [CLASSICAL [PAGE]]]]

The parameters are the same as the four fields of the web interface, with the
option to specify a page. For instance, to request rhymes for "chanter" with
between 2-4 syllables, respecting genre but not classical constraints, run:

  ./query.py chanter 2-4 true true

To get the second page of results, run:

  ./query.py chanter 2-4 true true 2

Results are returned in a raw format (if the query is successful). To
pretty-print, do:

  ./query.py bonjour | column -t -s '|'