phrasebook¶
Store phrases (SQL, messages, what-have-you) alongside your modules.
Getting Started¶
Now What?¶
Check out the tutorial.
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.
Using the Command Line Application¶
This project contains a command line application (phrasebook) based on Click.
Installation¶
The command line application is installed automatically when the package is installed.
Running the CLI in the Development Environment¶
If you need to run the application from within the project’s own development environment, you can use the make build target.
make build
Getting Help¶
The command line application has a help function which you can access with the –help flag.
phrasebook --help
API Documentation¶
phrasebook¶
Note
Most of the functions and objects defined in the phrasebook.phrasebook module are actually available in the top-level (phrasebook) namespace.
Store phrases (SQL, messages, what-have-you) alongside your modules.
-
phrasebook.phrasebook.
PHRASES_SUFFIX
= '.phr'¶ the standard suffix for phrasebook directories
-
class
phrasebook.phrasebook.
Phrasebook
(path: str = None, suffixes: Iterable[str] = None)[source]¶ Bases:
object
A phrasebook is an indexed collection of string templates.
-
__init__
(path: str = None, suffixes: Iterable[str] = None)[source]¶ - Parameters
path – the path to the phrases directory, or a file that has an accompanying phrasebook directory
suffixes – the suffixes of phrase files
See also
-
get
(phrase: str, default: str = None) → string.Template[source]¶ Get a phrase template.
- Parameters
phrase – the name of the phrase template
default – a default template or string
- Returns
the template (or the default), or None if no template is defined
See also
-
gets
(phrase: str, default: str = None) → str[source]¶ Get a phrase template string.
- Parameters
phrase – the name of the phrase template
default – a default template or string
- Returns
the template (or the default), or None if no template is defined
-
property
path
¶ Get the path to the phrases directory.
-
substitute
(phrase: str, default: str = None, safe: bool = True, **kwargs) → str[source]¶ Perform substitutions on a phrase template and return the result.
- Parameters
phrase – the phrase
default – a default template
safe – True (the default) to leave the original placeholder in the template in place if no matching keyword is found
kwargs – the substitution arguments
- Returns
the substitution result
-
property
suffixes
¶ Get the recognized suffixes for phrase files.
-
phrasebook.sql¶
SQL phrases (y’know… like queries and query fragments and such…)
-
class
phrasebook.sql.
SqlPhrasebook
(path: str = None, suffixes: Iterable[str] = ('.sql', ))[source]¶ Bases:
phrasebook.phrasebook.Phrasebook
A SQL phrasebook is an indexed collection of string templates that is particular to SQL phrases.
Development¶
Getting Started¶
This section provides instructions for setting up your development environment. If you follow the steps from top to bottom you should be ready to roll by the end.
Get the Source¶
The source code for the phrasebook project lives at github. You can use git clone to get it.
git clone https://github.com/patdaburu/phrasebook
Create the Virtual Environment¶
You can create a virtual environment and install the project’s dependencies using make.
make venv
make install
source venv/bin/activate
Try It Out¶
One way to test out the environment is to run the tests. You can do this with the make test target.
make test
If the tests run and pass, you’re ready to roll.
Getting Answers¶
Once the environment is set up, you can perform a quick build of this project documentation using the make answers target.
make answers
Using the Makefile¶
This project includes a Makefile
that you can use to perform common tasks such as running
tests and building documentation.
Targets¶
This section contains a brief description of the targets defined in the Makefile
.
clean
¶
Remove generated packages, documentation, temporary files, etc.
test
¶
Run the unit tests.
docs
¶
Build the documentation for production.
answers
¶
Perform a quick build of the documentation and open it in your browser.
package
¶
Build the package for publishing.
publish
¶
Publish the package to your repository.
build
¶
Install the current project locally so that you may run the command-line application.
venv
¶
Create a virtual environment.
install
¶
Install (or update) project dependencies.
licenses
¶
Generate a report of the projects dependencies and respective licenses.
Note
If project dependencies change, please update this documentation.
Publishing the Package¶
As you make changes to the project, you’ll probably want to publish new version of the package. (That’s the point, right?)
Publishing¶
The actual process of publishing the project is just a matter of running the publish target.
make publish
Installing¶
If you just need to install the library in your project, have a look at the general tutorial article.
Indices and tables¶
Python Module Dependencies¶
The requirements.txt
file contains this project’s module dependencies. You can install these dependencies
using pip
.
pip install -r requirements.txt
requirements.txt¶
click>=7.0,<8
pip-check-reqs>=2.0.1,<3
pip-licenses>=1.7.1,<2
pylint>=1.8.4,<2
pytest>=3.4.0,<4
pytest-cov>=2.5.1,<3
pytest-pythonpath>=0.7.2,<1
setuptools>=38.4.0
Sphinx==1.7.2
sphinx-rtd-theme==0.3.0
toml>=0.10.0
tox>=3.0.0,<4
twine>=1.11.0,<2
Runtime Dependencies and Licenses¶
Name |
Version |
License |
URL |
Click |
7.0 |
BSD |
|
bleach |
3.1.0 |
Apache Software License |
|
filelock |
3.0.10 |
License |
|
readme-renderer |
24.0 |
Apache License, Version 2.0 |
|
toml |
0.10.0 |
MIT |
|
webencodings |
0.5.1 |
BSD |