Part 1: Creating Your First Project

Introduction
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.
Generating a New Project Repository
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:
1
$ cement generate project ./todo
2
INFO: Generating cement project in ./todo
3
App Label [myapp]: todo
4
App Name [My Application]: My TODO Application
5
App Class Name [MyApp]: Todo
6
App Description [MyApp Does Amazing Things!]: A Simple TODO Application
7
Creator Name [John Doe]: Your Name
8
Creator Email [[email protected]]: [email protected]
9
Project URL [https://github.com/johndoe/myapp/]: https://github.com/yourname/todo/
10
License [unlicensed]:
Copied!
Exploring The TODO Project
The following covers the primary components included with your new project. First, take a look at the generated directory:
1
.
2
├── CHANGELOG.md
3
├── Dockerfile
4
├── LICENSE.md
5
├── MANIFEST.in
6
├── Makefile
7
├── README.md
8
├── config
9
│   └── todo.yml.example
10
├── docs
11
├── requirements-dev.txt
12
├── requirements.txt
13
├── setup.cfg
14
├── setup.py
15
├── tests
16
│   ├── conftest.py
17
│   └── test_main.py
18
└── todo
19
    ├── controllers
20
    │   └── base.py
21
    ├── core
22
    │   ├── exc.py
23
    │   └── version.py
24
    ├── ext
25
    ├── main.py
26
    ├── plugins
27
    └── templates
28
        └── command1.jinja2
29
​
30
9 directories, 24 files
Copied!
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
1
├── CHANGELOG.md
2
├── LICENSE.md
3
├── README.md
Copied!
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
1
├── MANIFEST.in
2
├── requirements-dev.txt
3
├── requirements.txt
4
├── setup.cfg
5
├── setup.py
Copied!
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
1
├── Dockerfile
2
├── Makefile
Copied!
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
1
├── config
2
│   └── todo.yml.example
3
├── docs
4
├── tests
5
│   ├── conftest.py
6
│   └── test_main.py
Copied!
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
1
└── todo
2
    ├── controllers
3
    │   └── base.py
4
    ├── core
5
    │   ├── exc.py
6
    │   └── version.py
7
    ├── ext
8
    ├── main.py
9
    ├── plugins
10
    └── templates
11
        └── command1.jinja2
Copied!
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.
Setting up Our Development Environment
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:
1
$ make virtualenv
2
​
3
$ source env/bin/activate
4
​
5
|> todo <| $
Copied!
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:
1
|> todo <| $ todo --help
2
usage: todo [-h] [-d] [-q] [-v]
3
            {command1} ...
4
​
5
A Simple TODO Application
6
​
7
optional arguments:
8
  -h, --help            show this help message and exit
9
  -d, --debug           full application debug mode
10
  -q, --quiet           suppress all console output
11
  -v, --version         show program's version number and exit
12
​
13
sub-commands:
14
  {command1}
15
    command1            example sub command1
16
​
17
Usage: todo command1 --foo bar
Copied!
Look at that! Let's play around with some of the pre-built features:
1
### display version information
2
​
3
$ todo --version
4
A Simple TODO Application 0.0.1.dev20180730022818
5
Cement Framework 3.0.0 
6
Python 3.7.0
7
Platform Darwin-17.7.0-x86_64-i386-64bit
8
​
9
### display sub-command help
10
​
11
$ todo command1 --help
12
usage: todo command1 [-h] [-f FOO]
13
​
14
optional arguments:
15
  -h, --help         show this help message and exit
16
  -f FOO, --foo FOO  notorious foo option
17
​
18
### execute the example command1 sub-command
19
​
20
$ todo command1 -f bar
21
Example Template (templates/command1.jinja2)
22
Foo => bar
Copied!
Conclusion
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.
Beginner Tutorial
Part 2: Adding Features
Last modified 3yr ago
Copy link
Contents
Introduction
Generating a New Project Repository
Exploring The TODO Project
Setting up Our Development Environment
Conclusion