drime

French rhyme dictionary with web and CLI interface
git clone https://a3nm.net/git/drime/
Log | Files | Refs | README

README (4398B)

      1 drime - by Antoine Amarilli
      2 A French rhyme dictionary
      3 Licence: see COPYING
      4 
      5 == 0. Author and licence ==
      6 
      7 plint is copyright (C) 2011-2020 by Antoine Amarilli
      8 
      9 This program is free software: you can redistribute it and/or modify it under
     10 the terms of the GNU General Public License as published by the Free Software
     11 Foundation, version 3.
     12 
     13 This program is distributed in the hope that it will be useful, but WITHOUT ANY
     14 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
     15 PARTICULAR PURPOSE.  See the GNU General Public License for more details.
     16 
     17 You should have received a copy of the GNU General Public License along with
     18 this program (see file "COPYING").  If not, see <http://www.gnu.org/licenses/>.
     19 
     20 The files haspirater.json and frhyme.json are a derivative work of the French
     21 lexical database Lexique <http://www.lexique.org/>, version 3.83, by Boris New
     22 <http://psycho-usmb.fr/boris.new/> and Christophe Pallier
     23 <http://www.pallier.org/>. Hence, this file is under the same license as
     24 Lexique, namely, the license CC BY SA 4.0 (according to the file
     25 README-Lexique.txt in the downloadable archive of Lexique). The GNU GPL licence
     26 does *not* apply to this file "data/occurrences".
     27 
     28 == 1. Features ==
     29 
     30 drime is a French rhyme dictionary engine with advanced features, most
     31 notably rhyme selection based on phonetic or visual similarity,
     32 frequency, syllable count, and rhyme gender.
     33 
     34 == 2. Requirements ==
     35 
     36 drime requires a working Python3 installation.
     37 
     38 drime also requires PyMySQL <http://www.pymysql.org> and Flask
     39 <http://flask.pocoo.org/> for Python3. To install PyMySQL, use for instance:
     40 
     41   sudo pip3 install pymysql
     42   sudo apt-get install python3-flask
     43 
     44 drime requires a working MySQL installation (package mysql-server on Debian
     45 systems) and the instructions in this README require the MySQL client (package
     46 mysql-client) to populate the database. You will probably want to create a
     47 database and a user for drime, probably along the lines of the following SQL
     48 commands executed using "mysql -u root -p":
     49 
     50   CREATE DATABASE drime;
     51   CREATE USER 'drime'@'localhost' IDENTIFIED BY 'mysecretpassword';
     52   GRANT ALL ON drime.* TO 'drime'@'localhost';
     53 
     54 == 3. Generating the DB ==
     55 
     56 The program database isn't shipped, but scripts are provided to build it
     57 from the Lexique3 database <http://lexique.org/>:
     58 
     59 - lexique_retrieve.sh retrieves a version of Lexique applies a few
     60   tweaks, and outputs it to stdout.
     61 
     62 - lexique2sql.sh takes the tweaked version of Lexique on stdin and produces
     63   the SQL database on stdout.
     64 
     65 You should therefore run:
     66 
     67   ./lexique_retrieve.sh | ./lexique2sql.sh > output.sql
     68 
     69 If this is not your first attempt, unzip might prompt you about overwriting
     70 existing files. Answer 'A'.
     71 
     72 To import the output of lexique2sql.sh in a MySQL database (on localhost,
     73 database 'drime', as user 'drime', interactive password authentication, the
     74 password being "mysecretpassword" if you followed the instructions of the
     75 previous section), run:
     76 
     77   cat output.sql |
     78     cat <(echo 'use drime;') - |
     79     cat - <(echo 'CREATE UNIQUE INDEX main ON words(word, phon);') |
     80     sed 's/varchar([0-9]*)/& collate utf8_bin/g' |
     81     mysql --default-character-set=utf8 -D drime -u drime -p
     82 
     83 To monitor progress, use the pv utility (replace "cat output.sql" by
     84 "pv -l output.sql").
     85 
     86 == 4. Using the DB ==
     87 
     88 == 4.1. Configuring database access ==
     89 
     90 Create a file with the connection parameters:
     91 
     92 cat > db_mysql_config.py <<EOF
     93 #!/usr/bin/python3 -O
     94 
     95 config = {
     96       'host': 'HOST',
     97       'user': 'USER',
     98       'passwd': 'PASSWD',
     99       'db': 'DB',
    100     }
    101 EOF
    102 
    103 == 4.2. Querying from the web ==
    104 
    105 To start the Flask development server, run:
    106 
    107   ./drime.py
    108 
    109 You can also deploy as WSGI with Apache2 using drime.wsgi. The configuration
    110 specifics are left as an unpleasant exercise to the reader.
    111 
    112 == 4.3. Querying from the command line ==
    113 
    114 Run:
    115 
    116   ./query.py QUERY [NSYL [GENDER [CLASSICAL [PAGE]]]]
    117 
    118 The parameters are the same as the four fields of the web interface, with the
    119 option to specify a page. For instance, to request rhymes for "chanter" with
    120 between 2-4 syllables, respecting genre but not classical constraints, run:
    121 
    122   ./query.py chanter 2-4 true true
    123 
    124 To get the second page of results, run:
    125 
    126   ./query.py chanter 2-4 true true 2
    127 
    128 Results are returned in a raw format (if the query is successful). To
    129 pretty-print, do:
    130 
    131   ./query.py bonjour | column -t -s '|'
    132