Tutorial¶
phrasebook is designed to make it relatively simple for you to place files containing string templates alongside your python modules. You have a few different options for doing so: You can place all your strings in a single file or you can break them out into multiple files within a directory. While we’ve tried to use simple naming conventions to minimize the boiler plate for creating a single phrasebook for a module, you can also create as many phrasebooks as you need by specifying the path for each one.
Single File Phrasebook¶
If you have just a few simple strings, you can place them all in a single toml file.
txt1 = "Hello, $NAME."
txt2 = "Hello, $YOURNAME. My name is $MYNAME."
[sub1]
txt1 = "Hello again, $NAME"
txt2 = "Hello again, $YOURNAME. My name is still $MYNAME."
You can then access it from a python module with the same base name.
Note
If you don’t supply the path constructor argument, the
Phrasebook
class will attempt to
find a file or directory with the same name as the current module with the .phr suffix.
from phrasebook import Phrasebook
phrasebook = Phrasebook().load()
print(phrasebook.substitute('txt1', NAME='Eric'))
print(phrasebook.substitute('txt2', YOURNAME='Eric', MYNAME='Terry'))
print(phrasebook.substitute('sub1.txt1', NAME='Eric'))
print(phrasebook.substitute('sub1.txt2', YOURNAME='Eric', MYNAME='Terry'))
Hello, Eric.
Hello, Eric. My name is Terry.
Hello again, Eric
Hello again, Eric. My name is still Terry.
Phrasebook Directory¶
SELECT $COLUMN FROM $TABLE
SELECT $COLUMN1, $COLUMN2 FROM $TABLE
from phrasebook import Phrasebook
phrasebook = Phrasebook().load()
print(phrasebook.substitute('query1', COLUMN='first', TABLE='names'))
print(
phrasebook.substitute(
'sub1.query2',
COLUMN1='first',
COLUMN2='last',
TABLE='names'
)
)
SELECT first FROM names
SELECT first, last FROM names
Specifying the Path¶
You may not always want your phrasebooks to reside alongside your modules; sometimes you may want
to share phrasebooks across modules. In those cases, you can provide a
path
argument to indicate the file or directory that
contains your phrases.
phrasebook = Phrasebook(path='/path/to/my/phrases.phr').load()
Specifying Suffixes¶
If you have a phrases directory that contains many different types of files, you can indicate which
files you want to include by specifying their extensions using the
suffixes
constructor argument. You can use this
convention if you need to put other types of files (perhaps something like a README.md file that
provides some documentation for the phrases) alongside the phrase files.
phrasebook = Phrasebook(suffixes=['.sql']).load()
Note
The example above demonstrates how you might create a phrase book that is particular to SQL
phrases, but there is also a built-in SqlPhrasebook
that you can use for that particular purpose.