Python Package Template

A template repository for developing Python packages using Poetry in a VSCode devcontainer. Comes pre-configured with Poetry and Quarto for package documentation.

Features

• Devcontainer configuration for VSCode
• Poetry for dependency management
• Quarto for documentation
• Pre-configured development environment

Quick Start

Pre-requisites: Ensure you have the following installed on your system: Visual Studio Code (VSCode) and Docker Desktop

1. Click "Use this template" to create a new repository
2. Clone your new repository
3. Open in VSCode with devcontainer extension
4. VSCode will prompt to reopen in container - accept this (will take a few minutes)

Alternatively, click 'Use this template' in this repository, then select 'Open in a codespace' to try it out directly in your browser.

Project Setup

Open a terminal in your container workspace and run the following:

1. Initialize Poetry project:

poetry init

2. Set up development dependencies:

poetry add --group dev pytest
poetry add --group dev quartodocs

3. Create your package structure:

mkdir your_package_name
touch your_package_name/__init__.py

Documentation

Documentation is handled through Quarto. To build the documentation:

quarto render

Example Project

After creating a new repository from this template:

Alternatively, replace steps 1 and 2 by clicking 'Use this template' in this repository, then select 'Open in a codespace' to try it out directly in your browser.

1. Clone your repository and open in VSCode

   git clone <your-repo-url>
   code <repo-directory>

2. When prompted, reopen in container (or use Command Palette: "Reopen in Container")

3. Initialize your Poetry project (update with your details)

   poetry init --name hellopy \
            --description "Your package description" \
            --author "Your Name <[email protected]>" \
            --python "^3.11" \
            -n

4. Create initial package structure

   mkdir hellopy && \
   touch hellopy/__init__.py && \
   touch hellopy/hello.py

5. Populate hello.py with the following

    def hello():
        """
        Print a greeting message.
   
        Example usage:
        ```{python}
        from hellopy.hello import hello
        hello()
        ```
        """
        print("Hello!")

6. Install your package in editor mode, add IPython and Jupyter to aid development, and activate virtual

   poetry install && \
   poetry add --group dev ipython jupyter

7. Activate virtual environment

   source .venv/bin/activate

8. Start Ipython (or an interactive Jupyter window)

   ipython

9. In Ipython, import hello()

   from hellopy.hello import hello

10. Enjoy developing your package!

    # Try editing `hello.py` and re-running the `hello()` command
    hello()