Skip to content

Latest commit

 

History

History
139 lines (100 loc) · 10 KB

README.md

File metadata and controls

139 lines (100 loc) · 10 KB

Getting Started with the Right Structure

Table of Contents:

Why Should You Use This Template?

This template is the result of my years refining the best way to structure a project so that it is reproducible and maintainable. Integrated into this template are a suite of tools that I've used to aid in maintaining code quality, codebase dependencies and much more.

This template allows you to:

✅ Create a readable structure for your project

✅ Automatically run tests when committing your code

✅ Enforce type hints at runtime

✅ Check issues in your code before committing

✅ Efficiently manage the dependencies in your project

✅ Create short and readable commands for repeatable tasks

✅ Automatically document your code

Tools used in this Project Template

Template Directory Structure

./{{ cookiecutter.__project_name }}        # Root directory representing the name of the project. This contains all project content and python package.
    ├── .vscode                            # Directory storing VSCode settings specific to the project  
    ├── config                             # Directory used to store configuration files
    ├── data                               # Directory used to organize data used for inputs, outputs and temporary data
    ├── docs                               # Directory containing multiple markdown files and/or other resource documentation for your project
    ├── notebooks                          # Directory to store notebooks
    ├── tests                              # Directory containing tests
    │   └── __init__.py                    # Treat directories contained within tests as modules 
    ├── {{ cookiecutter.__package_name }}  # Directory that contains your package source code for one or more modules
    │   ├── __init__.py                    # Treat directories contained within {{ cookiecutter.__package_name }} as modules
    │   ├── resources                      # Directory containing various files that the the package references. These files are not intended to be modified.
    │   │   └── project_task.xml           # XML template file used when creating a scheduled windows task
    │   ├── utils                          # Module containing project specific resources 
    │   │   ├── __init__.py                # Treat directories contained within utils as modules
    │   │   └── create_tasks.py            # Poetry script to deploy scheduled tasks.
    │   ├── main.py                        # Default main script
    │   └── config.py                      # Store logic to initialize values found in the config directory
    ├── .gitignore                         # File specifying files/directories to ignore as not to commit to Git
    ├── .pre-commit-config.yaml            # Configuration file for pre-commit hooks
    ├── LICENSE                            # Project license file. Choice of "MIT", "BSD", "Apache", "GNU General Public License", "ISC", "Other/Proprietary License"
    ├── poetry.lock                        # Poetry file containing all packages and their exact versions that it downloaded based on dependencies found in poetry.toml
    ├── poetry.toml                        # File containing project specific configurations that override global configurations for Poetry
    ├── pyproject.toml                     # Poetry file containing project dependencies
    └── README.md                          # Markdown file used to describe your project

How to use this Template

  1. Clone dev.env repo down to your local machine if it hasn't already.

  2. Open your command line tool of choice and change the Current Working Directory (CWD) to Python\Template Structure folder.

    👀 ProTip: You can open PowerShell directly from the Template Structure folder in File Explorer by typing PowerShell in the address bar or Shift + Right Click in File Explorer.

  3. Running the following command to install a cookiecutter dependent python environment.

poetry install
  1. Next, activate the installed poetry environment by running the following command:
poetry shell
  1. To deploy the cookiecutter template run:
cookiecutter .

You'll be asked a few questions which will be applied to settings up the project package.

Note: The "." in the command cookiecutter . will reference the cookiecutter template and generate a project directory structure in the CWD. If you would like to specify where to generate output, pass in the -o, --output-dir <PATH> command option.

You will find a generated project directory where {{ cookiecutter.__project_name }} matches your input for the question, project_name. Navigate into that directory and reference the Project README to continue setting up the project environment.

Note: Don't forget to run the command deactivate to disable the poetry environment created in step 3.

Static Code Analysis Tools

Static Code Analysis Tools, also known as linters, are tools that scan through your python codebase to identify possible issues. Think of it as an early warning system to speed up your development by pointing out problems that can be fixed during the development process rather than in the QA stage. The linting tools included in this template include:

  • Black: A code formatter to modify the style of your code (typically resolving around proper whitespace) without affecting the behavior of the program.
  • Mypy: A type checker that verifies that your codebase follows its own type annotations aka type hints.
  • Ruff: An extremely fast error checker written in Rust, that identifies syntax errors or other code that will result in unhandled exceptions and crashes. It's a replacement of Flake8 and many of it's plugins.

Resources

Below are additional resources I've referenced that are worth noting.

Resources for Project Layout and Packaging

Resources Related to Cookiecutter

Resources on Static Code Analysis Tools