Quick Start

This section provides a comprehensive introduction to P3G, helping you quickly understand and learn the basic usage of its commonly used modules. We also welcome your feedback and suggestions in our GitHub issues to help us improve P3G.

1. Installation

To begin using P3G, first ensure you have the latest version:

pip install -U p3g

Then navigate to the directory where you want to create your project and run:

p3g generate

2. Input Variables

The template generator will prompt you to provide several configuration variables. Below are the input variables with their default values:

Parameter	Default value	Description
project_name	python-project	The name of your project. Check availability before creating.
project_description	based on the project_name	A brief description of your project.
organization	based on the project_name	Organization name for LICENSE and pyproject.toml ownership details.
license	MIT	Choose from: MIT, BSD-3, GNU GPL v3.0, or Apache Software License 2.0.
minimal_python_version	3.7	Minimum Python version (3.7, 3.8, or 3.9) for builds, GitHub workflows, and formatters.
github_name	based on the organization	GitHub username for hosting, README.md, pyproject.toml, and GitHub templates.
email	based on the organization	Email for CODE_OF_CONDUCT.md, SECURITY.md, and project ownership in pyproject.toml.
version	0.1.0	Initial package version (follows Semantic Versioning).
line_length	88	Maximum line length for code style (black and isort). Must be between 50-300.
using_tsinghua_mirror_source	false	Whether to use Tsinghua Poetry mirror source.
create_example_template	cli	Template type: "cli" creates a simple CLI app with Typer and Rich; "none" for no template.
create_docs	true	Whether to create a documentation site with VitePress.

All input values will be saved in the cookiecutter-config-file.yml file for future reference. 😉

3. Demo

4. More Details

Your generated project will include a comprehensive DELETE_ME.md file with detailed instructions for development, deployment, and more.

5. Initial Setup

5.1. Initialize poetry

Install Poetry and set up your project dependencies by running:

pip install poetry & make install

After project creation, you'll see instructions on how to initialize the project in your terminal.

5.2. Initialize pre-commit

If you initialize a git repository before running make install, pre-commit will be automatically installed. If the installation fails, simply run make install again to properly install pre-commit hooks to your .git directory.

6. Package Management

Want to learn more about Poetry? Check its official documentation.

6.1. Details about Poetry

Poetry's commands are intuitive and easy to learn, such as:

• poetry add numpy@latest - Add a package dependency
• poetry run pytest - Run tests
• poetry publish --build - Build and publish your package

6.2. CLI Example

If you selected cli for the create_example_template option, your project will include a simple CLI application example. This example uses Typer and Rich for input validation and beautiful terminal formatting.

After installation via make install (recommended) or poetry install, try the example:

poetry run <project_name> --help

poetry run <project_name> --name Roman

7. Building and Releasing Your Package

Building a new version of your application involves these steps:

1. Bump the package version with poetry version <version>. You can specify the new version explicitly or use rules like major, minor, or patch. For more details, see the Semantic Versioning standard.
2. Commit your changes to GitHub.
3. Create a GitHub release.
4. Publish your package with poetry publish --build.

8. Makefile Usage

The Makefile includes numerous functions to accelerate your development workflow.

8.1. Install Dependencies and Pre-commit Hooks

Install all requirements:

make install

Install pre-commit hooks after git init:

make pre-commit-install

8.2. Code Style and Type Checks

Format your code automatically using ruff:

make format

Check code style without modifying files:

make check-codestyle

Note: check-codestyle uses ruff and darglint libraries

8.3. Code Security

Run security checks:

make check-safety

This command runs Poetry integrity checks and identifies security issues using Safety and Bandit.

8.4. Tests with Coverage Badges

Run tests with pytest:

make test

8.5. All Linters

Run all linters with a single command:

make lint

This is equivalent to:

make check-codestyle && make test && make check-safety

8.6. Docker

Build a Docker image:

make docker-build

This is equivalent to:

make docker-build VERSION=latest

Remove the Docker image:

make docker-remove

For more information, see the Docker documentation.

8.7. Cleanup

Delete Python cache files:

make pycache-remove

Remove package build artifacts:

make build-remove

Delete .DS_STORE files:

make dsstore-remove

Remove .mypycache:

make mypycache-remove

Or run all cleanup tasks at once:

make cleanup

9. 📚 Documentation with VitePress

P3G includes built-in support for creating beautiful documentation using VitePress, a modern static site generator powered by Vue.

9.1. Documentation Structure

Your project comes with a pre-configured documentation structure in the docs directory:

docs/
├── .vitepress/        # VitePress configuration
├── get_started/       # Getting started guides
├── components/        # Vue components for docs
├── public/            # Static assets
├── index.md           # Home page
└── package.json       # Node dependencies

9.2. Setting Up Documentation

To set up and start working with your documentation:

cd docs
npm install      # or yarn install
npm run dev      # start dev server

9.3. Building Documentation

To build your documentation for production:

cd docs
npm run build

This will generate static files in the .vitepress/dist directory that you can deploy to any static hosting service.

9.4. Customizing Documentation

You can customize your documentation by editing the VitePress configuration in docs/.vitepress/config.js:

• Change theme colors and appearance
• Configure navigation and sidebar
• Add plugins and extensions
• Set up search functionality

For more details, refer to the VitePress documentation.