Part 1: Creating Your First Project
Throughout this tutorial we will be building a task management application called todo. We will begin with a barebones template using the cement generate tool, and build up from there to cover as much of the core features of the framework as possible.
Our application will include the following features:
Ability to create, update, and delete task items
List and display tasks via Jinja2 templates
Persist data using TinyDB
Send an email message when tasks are complete
A video walk-thru of the tutorial is also available.
Cement includes a developer utility called cement that includes tools to make our lives easier. This was introduced in Cement 3, and will continue to grow as feature requests are made for new and improved ways of streamlining the development process.
Create a new project with the following command and parameters:
$ cement generate project ./todoINFO: Generating cement project in ./todoApp Label [myapp]: todoApp Name [My Application]: My TODO ApplicationApp Class Name [MyApp]: TodoApp Description [MyApp Does Amazing Things!]: A Simple TODO ApplicationCreator Name [John Doe]: Your NameCreator Email [john.doe@example.com]: you@yourdomain.comProject URL [https://github.com/johndoe/myapp/]: https://github.com/yourname/todo/License [unlicensed]:
The following covers the primary components included with your new project. First, take a look at the generated directory:
.├── CHANGELOG.md├── Dockerfile├── LICENSE.md├── MANIFEST.in├── Makefile├── README.md├── config│ └── todo.yml.example├── docs├── requirements-dev.txt├── requirements.txt├── setup.cfg├── setup.py├── tests│ ├── conftest.py│ └── test_main.py└── todo├── controllers│ └── base.py├── core│ ├── exc.py│ └── version.py├── ext├── main.py├── plugins└── templates└── command1.jinja29 directories, 24 files
This looks like a lot, however there is a lot of placeholders here for best practice or recommended design. Keep in mind, a Cement application can be as simple as a single file script... however we know that our TODO application will be disrupting the industry of task management, therefore we want to start things on the right track.
Let's break this down into more manageable pieces:
Common Project Files
├── CHANGELOG.md├── LICENSE.md├── README.md
These files should look familiar as they are common in most projects. The README.md is populated with some starter info to help get more familiar with the layout and navigation of the project. You should read the README.md now.
Common Python Packaging Files
├── MANIFEST.in├── requirements-dev.txt├── requirements.txt├── setup.cfg├── setup.py
These files should look familiar to anyone who has packaged and distributed a Python project before, and are required for proper installation, setup, and distribution. Note that the requirements.txt lists dependencies that are strictly required for deployment (production), where the additional requirements-dev.txt includes additional dependencies that are only required for development (running tests, building documentation, etc).
Miscellaneous Development Files
├── Dockerfile├── Makefile
The included Dockerfile gives you a working Docker image out-of-the box, while the Makefile includes several helpers for common development tasks such as creating a virtualenv, running tests, building docker, etc.
Default Configuration, Documentation, and Tests
├── config│ └── todo.yml.example├── docs├── tests│ ├── conftest.py│ └── test_main.py
A good application has excellent documentation and testing, along with example configuration files of the applications settings (and their defaults). As configuration defaults are added (or modified) in the application, the config/todo.yml.example should be updated to reflect them.
Our Application Module
└── todo├── controllers│ └── base.py├── core│ ├── exc.py│ └── version.py├── ext├── main.py├── plugins└── templates└── command1.jinja2
Finally, our code lives in a python module called todo, with what should be an obvious breakdown of submodules that clearly separate code into relevant and organized buckets. Take a moment to briefly review all of the files provided in the generated project repository.
Again, note that a Cement project does not need to be organized this way but is a solid starting point to streamline development. If you aren't entirely happy with the layout and organization of the generated projects you can always create your own templates to start from.
Our generated project includes a Makefile with several helpers to streamline the development process. You can use these helpers, add your own, or do away with it and follow any other development process you are more familiar with.
First we will setup our VirtualENV:
$ make virtualenv$ source env/bin/activate|> todo <| $
This runs common commands to create our virtual environment in ./env/, and then runs pip to install our dependencies. We activate the environment, and are ready to run our TODO application:
|> todo <| $ todo --helpusage: todo [-h] [-d] [-q] [-v]{command1} ...A Simple TODO Applicationoptional arguments:-h, --help show this help message and exit-d, --debug full application debug mode-q, --quiet suppress all console output-v, --version show program's version number and exitsub-commands:{command1}command1 example sub command1Usage: todo command1 --foo bar
Look at that! Let's play around with some of the pre-built features:
### display version information$ todo --versionA Simple TODO Application 0.0.1.dev20180730022818Cement Framework 3.0.0Python 3.7.0Platform Darwin-17.7.0-x86_64-i386-64bit### display sub-command help$ todo command1 --helpusage: todo command1 [-h] [-f FOO]optional arguments:-h, --help show this help message and exit-f FOO, --foo FOO notorious foo option### execute the example command1 sub-command$ todo command1 -f barExample Template (templates/command1.jinja2)Foo => bar
And that completes Part 1. In the next section we will add the functionality of managing task items, storing data in a database, and sending email messages when completing tasks.