Cement Application Framework

The generate extension allows you to create project templates using .generate.yml files. It uses a unified variables: list where each entry defines a type: (string, boolean, or choice).

Resolved variables are placed at the top level of the template context. This allows you to use them directly in Jinja2 or Mustache templates using standard conditional logic (e.g., {% if docker %} or {% if web_framework == 'flask' %}).

Note on Boolean Interpolation: When interpolating a boolean as text (e.g., {{ docker }}), it renders as the capitalized Python representation (True or False), not true/false. Use conditionals for logic instead of text interpolation.

variables:
    -   name: project_name
        type: string
        prompt: "Project Name"
        default: "myproject"

A Dockerfile is included for containerized builds. You can build the image and run the CLI application using the Makefile and docker commands.

$ make docker
$ docker run -it {{ label }} --help

To install the TODO application locally, use pip from the project root.

$ pip install .

To develop on this project, you need Python 3.10+ and PDM. Use the provided Makefile to automate environment setup and testing.

1. Install dependencies: Run make setup to install dependencies and automatically create a virtual environment.
2. Run the application: Use pdm run {{ label }} --help to execute the CLI application within the managed environment.
3. Run tests: Use make test to execute pytest and coverage reports.

$ make setup
$ pdm run {{ label }} --help
$ make test

Windows development is not the primary target and is not 100% complete. If you must develop natively on Windows, follow these steps:

Prerequisites

• Python 3.x (latest stable)
• pip, pipx, and pdm
• Visual C++ 14.0 or Greater Build Tools (including CMake)

Setup Steps

1. Install pdm via pipx:

   pip install pipx
   pipx install pdm

2. Create a development virtual environment:
   ```bash
pdm venv create

3. Install dependencies (excluding memcached):

   pdm install --without memcached

4. Run core tests:
   ```bash
pdm run pytest --cov=cement.core tests/core
   # OR
   make test-core

5. Run the Cement CLI:

   pdm run cement --help

To release the project to PyPI, first ensure your credentials are configured in your ~/.pypirc file:

[pypi]
username = YOUR_USERNAME
password = YOUR_PASSWORD

Then, use the Makefile helpers to build and upload the distribution:

1. Build the distribution: make dist
2. Upload to PyPI: make dist-upload

$ make dist
$ make dist-upload

Some Cement extensions require external dependencies. Cement does not include these by default. You must install them using the extension's optional package syntax.

Examples:

• For colorlog: pip install cement[colorlog]
• For redis: pip install cement[redis]

Refer to the official extensions documentation for a full list.

If you prefer Docker, the project includes a Docker Compose configuration that sets up all required services and dependencies.

Launch Development Container

To create the containers and launch a BASH shell within the cement container, run:

make dev

This is equivalent to:

docker compose up -d
docker compose exec cement /bin/bash

Testing Alternative Python Versions

Docker containers are provided for testing against different Python versions (e.g., cement-py310, cement-py311).

1. List available containers:

   docker-compose ps

2. Execute a shell in a specific version container:

   docker-compose exec cement-py310 /bin/bash

The project uses pdm for packaging. You can set up the project and its development dependencies using the provided Makefile or by running pdm install directly.

$ make setup    # or: pdm install

You can use the generate command to scaffold projects either interactively or using defaults. Run these commands from the directory containing your entry point (e.g., myapp.py).

# Generate using all default values (no interactive prompts)
pdm run python myapp.py generate webapp /tmp/myproject --defaults

# Generate interactively (prompts for each variable)
pdm run python myapp.py generate webapp /tmp/myproject

# Generate using defaults and overwrite existing files
pdm run python myapp.py generate webapp /tmp/myproject --defaults --force