(4.7-project-templates)=
# 🧩 4.7 Project Templates

```{contents}
:depth: 3
```

## 🔰 Tutorial

In this module, you will learn how to use **PyScaffold** and **Cookiecutter** to create project templates, manage dependencies, and publish Python packages to **PyPI**. By the end of this module, you'll be able to:

1. Create a project template using PyScaffold
2. Add project content and initialize a Python project
3. Publish a Python package to PyPI
4. Outline the key benefits of dependency management during software development

### Project Templates with PyScaffold

**PyScaffold** is a tool that helps create the scaffolding for Python projects by generating a clean project structure, setting up version control, documentation, and package configuration. This simplifies the process of initializing new Python projects.

#### Steps to Create a Project Template with PyScaffold:

1. Install PyScaffold:

   ```bash
   pip install --upgrade pyscaffold
   ```

2. Create a New Project:
   Run the following command to initialize a new project:

   ```bash
   putup my_project
   ```

   This will create a project folder called `my_project` template with everything you need for some serious coding with the following structure:

   ```
   my_project/
   ├── src/
   ├── tests/
   ├── docs/
   ├── setup.py
   └── README.rst
   ```

3. Add Features:
   PyScaffold allows you to add features like testing frameworks (e.g., `pytest`) or documentation tools (e.g., `Sphinx`) directly during initialization:

   ```bash
   putup --with-pytest --with-sphinx my_project
   ```

   This command adds both `pytest` and `Sphinx` configurations to the project.

Quick Start: [PyScaffold Demo Project](https://github.com/pyscaffold/pyscaffold-demo)

### Project Templates with Cookiecutter

Cookiecutter is another powerful tool for creating project templates, but it is more customizable than PyScaffold. Cookiecutter allows you to define templates that can be reused across different projects.

#### Steps to Create a Project Template with Cookiecutter:

1. Install Cookiecutter:

   ```bash
   pip install cookiecutter
   ```

2. Use an Existing Template:
   You can initialize a new project from an existing template by running:

   ```bash
   cookiecutter https://github.com/audreyr/cookiecutter-pypackage
   ```

   Follow the prompts to customize the project (e.g., project name, author, license, etc.).

3. Create Your Own Template:
   You can also create your own project template. For example, create a folder structure like:

   ```
   my_template/
   ├── {{cookiecutter.project_name}}/
   │   └── __init__.py
   └── cookiecutter.json
   ```

   The `cookiecutter.json` file defines the variables for your template, such as:

   ```json
   {
     "project_name": "MyProject",
     "author_name": "Your Name"
   }
   ```

   You can use this template across different projects by running:
   ```bash
   cookiecutter path/to/my_template
   ```

Video Tutorial: [Using Cookiecutter for Python Projects](https://www.youtube.com/watch?v=KpGAEsysxpY)

### Adding Project Content and Initialization

After setting up a project template using PyScaffold or Cookiecutter, the next step is to add your own code, documentation, and tests. The structure generated by these tools encourages best practices for organizing code and keeping everything modular and maintainable.

#### Example of Adding Content:

1. Source Code**: Add your Python code under the `src/` directory.

   ```bash
   src/my_project/
       __init__.py
       module.py
   ```

2. Tests**: Place your unit tests under the `tests/` directory.

   ```bash
   tests/
       test_module.py
   ```

3. Documentation**: Sphinx setup will generate documentation files in the `docs/` directory.

4. Version Control: Use Git for version control. The template already includes a `.gitignore` file to exclude unnecessary files from your repository.

### Publishing a Python Package to PyPI

PyPI (Python Package Index) is a repository where you can publish your Python packages so they can be easily installed by others using `pip`. Here's how to package and publish your project to PyPI:

#### Steps to Publish a Package to PyPI:

1. Install Build Tools:
   First, install the required tools for packaging:

   ```bash
   pip install setuptools wheel twine
   ```

2. Build Your Package:
   Inside your project directory, run the following command to create a distribution package:

   ```bash
   python setup.py sdist bdist_wheel
   ```

   This will generate a `dist/` directory containing `.tar.gz` and `.whl` files.

3. Upload to PyPI:
   Create an account on PyPI if you don’t already have one. Then, use `twine` to upload the package:

   ```bash
   twine upload dist/*
   ```

   Your package is now published on PyPI and can be installed using:

   ```bash
   pip install your-package-name
   ```

Video Tutorial: [How to Publish a Package on PyPI](https://www.youtube.com/watch?v=GIF3LaRqgXo)

### Dependency Management in Python

Dependency management ensures that your project has all the necessary external libraries installed, and that these dependencies are consistent across different environments. Proper dependency management is essential for the smooth development and deployment of software projects.

#### Key Benefits of Dependency Management:

1. Consistency: Ensures that everyone working on the project is using the same versions of dependencies.
2. Isolation: Dependencies are isolated in virtual environments (e.g., `venv`, `conda`), preventing conflicts with other projects.
3. Reproducibility: With a `requirements.txt` or `pyproject.toml`, anyone can recreate the exact environment needed to run the project.
4. Security: Dependency management tools can automatically check for outdated or vulnerable libraries, helping keep your project secure.

#### Tools for Managing Dependencies:
- `requirements.txt`: Lists all the dependencies of the project, which can be installed using:
   ```bash
   pip install -r requirements.txt
   ```

- `pyproject.toml`: A modern way to manage dependencies and build system requirements, supported by tools like **Poetry**.

Video Tutorial: [Dependency Management in Python](https://www.youtube.com/watch?v=fKl2JW_qrso)

### Additional Resources

- [PyScaffold Documentation](https://pyscaffold.org/en/stable/)
- [Cookiecutter Documentation](https://cookiecutter.readthedocs.io/en/1.7.2/)
- [Publishing Python Packages to PyPI](https://packaging.python.org/tutorials/packaging-projects/)
- [Dependency Management with Poetry](https://python-poetry.org/)

## 🚀 Quiz

::::{tab-set}
:sync-group: category

:::{tab-item} W 2024
:sync: w2024

:::

:::{tab-item} Sp/Su 2024
:sync: sp2024

https://q.utoronto.ca/courses/370070/assignments/1393629?display=full_width
:::

:::{tab-item} Sp/Su 2025
:sync: sp2025

https://q.utoronto.ca/courses/393352/assignments/1499733?display=full_width_with_nav
:::

::::

## 📄 Assignment

::::{tab-set}
:sync-group: category

:::{tab-item} W 2024
:sync: w2024

:::

:::{tab-item} Sp/Su 2024
:sync: sp2024

https://q.utoronto.ca/courses/370070/assignments/1394237?display=full_width
:::

:::{tab-item} Sp/Su 2025
:sync: sp2025

https://q.utoronto.ca/courses/393352/assignments/1499734?display=full_width_with_nav
:::

::::