diff --git a/.vscode/dev/tasks.json b/.vscode/dev/tasks.json new file mode 100644 index 0000000..796209c --- /dev/null +++ b/.vscode/dev/tasks.json @@ -0,0 +1,27 @@ +{ + // Schema version for tasks — always "2.0.0" for modern VS Code + "version": "2.0.0", + + // List of custom shell tasks you can run via Terminal → Run Task + "tasks": [ + { + // Friendly name shown in task picker + "label": "Install requirements", + + // Task type: run a shell command + "type": "shell", + + // Command to execute (here: install deps inside the venv) + "command": "${workspaceFolder}/.venv/bin/pip install -r requirements.txt", + + // Problem matcher is for parsing compiler errors — empty = no parsing + "problemMatcher": [] + }, + { + "label": "Run tests", + "type": "shell", + "command": "${workspaceFolder}/.venv/bin/pytest tests", + "problemMatcher": [] + } + ] +} diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000..11aa04a --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,49 @@ +{ + // Schema version for debug configs — always stays at "0.2.0" + "version": "0.2.0", + + // List of run/debug configurations + "configurations": [ + { + // Friendly name shown in VS Code debugger dropdown + "name": "Python: Run current file", + + // Debugger type (Python in this case) + "type": "debugpy", + + // "launch" = start a program, "attach" = attach to an existing process + "request": "launch", + + // Program to run — here it means "the file that’s open in the editor" + "program": "${file}", + + // Run in the integrated terminal (respects conda/venv activation) + "console": "integratedTerminal", + + // Ensure src/ is on sys.path while debugging + "env": { + "PYTHONPATH": "${workspaceFolder}/" + } + }, + { + "name": "Python: Run tests", + "type": "debugpy", + "request": "launch", + + // Use pytest as the entry point instead of a file + "module": "pytest", + + // Pass arguments to pytest + "args": [ + "-q", // quiet mode + "${workspaceFolder}/tests" // path to tests + ], + + "console": "integratedTerminal", + + "env": { + "PYTHONPATH": "${workspaceFolder}/" + } + } + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..495ac87 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,19 @@ +{ + // Path to your project’s Python interpreter (usually virtualenv or conda) + "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python", + + // Ensures the terminal auto-activates the interpreter when opened + "python.terminal.activateEnvironment": true, + + // Add src/ folder to module search path (so you can do `import mypackage`) + "terminal.integrated.env.osx": { + "PYTHONPATH": "${workspaceFolder}/" + }, + + // Code formatting/linting preferences + "python.formatting.provider": "black", // use Black formatter + "editor.formatOnSave": true, // format automatically when saving + "python.linting.enabled": true, // enable linting + "python.linting.pylintEnabled": true, // enable pylint + "python.linting.mypyEnabled": true // enable mypy type checking +} \ No newline at end of file diff --git a/README.md b/README.md index 403769f..0086eec 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,10 @@ [![GitHub issues closed](https://img.shields.io/github/issues-closed-raw/dgahle/PythonRepositoryTemplate?style=flat)](https://github.com/dgahle/PythonRepositoryTemplate/issues?q=is%3Aissue+is%3Aclosed) [![GitHub PR closed](https://img.shields.io/github/issues-pr-closed/dgahle/PythonRepositoryTemplate)](https://github.com/dgahle/PythonRepositoryTemplate/pulls?q=is%3Apr+is%3Aclosed) -This repository provides a template structure a software development project with some python functionality that is +This repository provides a template structure a software development project with some python functionality that is generally usefully (demonstrated in `scripts/main.py`). This includes: + - Folder structure - Python script template (`scripts/main.py`) - PyTest example (`tests/test_main.py`) @@ -20,56 +21,63 @@ This includes: As well as tracking information in `.gitignore` and python dependencies `requirements.txt`. -__Requesting changes:__ Raise an issue on the GitHub repository page and describes the error or the desired +**Requesting changes:** Raise an issue on the GitHub repository page and describes the error or the desired functionality, ideally with test data that can be used to make tutorials and unit tests. ## Getting Started (Build, Test, and Run) This example repo has been written in Python 3.9 and the dependencies are listed in requirements.txt. -The script setup_project.sh will build the conda environment, install dependencies, and create the input/output folders +The script setup_project.sh will build the conda environment, install dependencies, and create the input/output folders and the configuration file. The actions the of setup_project.sh are: + 1. Create virtual python environment: -`conda create -n PythonRepositoryTemplate python=3.9 --yes` + + - Global: `conda create -n PythonRepositoryTemplate python=3.9 --yes` or + + - Local: `conda create -p .venv/ python=3.9 --yes` + 2. Install the dependencies: -`pip install -r requirements.txt` + `pip install -r requirements.txt` 3. Setting up the repo directories: -`mkdir input, output` + `mkdir input, output` 4. Create config.JSON for the user (copy from metadata): -`cp metadata/config.json config.json` + `cp metadata/config.json config.json` 5. Test repo setup: -`PYTHONPATH=. pytest` + `PYTHONPATH=. pytest` Now the repository is locally set up you can run `scripts/main.py` which is a template for scripts and modules. -To run from the console run `PYTHONPATH=. python scripts/main.py`, within the virtual environment +To run from the console run `PYTHONPATH=. python scripts/main.py`, within the virtual environment (`conda activate PythonRepositoryTemplate`). ## How to Contribute The following steps describe how to add new functionality to the repo: -1. Raise an issue in this report that describes the functionality you want to add, + +1. Raise an issue in this report that describes the functionality you want to add, 2. branch from `dev` with the name convention `feature\` 3. Add code to `feature\` 4. Create a (draft) pull request with `dev` as the target (link the PR is the corresponding issue) -In the review the scripts will be reviewed against the coding standards below, passing unit tests that verify the -functionality, and updated documentation and tutorials. -Assistance can be provided if you are unfamiliar with implementing some of these standards. +In the review the scripts will be reviewed against the coding standards below, passing unit tests that verify the +functionality, and updated documentation and tutorials. +Assistance can be provided if you are unfamiliar with implementing some of these standards. ### Coding Standards -As the code should be easy if not trivial for others to reuse blind there are a series of standards that example +As the code should be easy if not trivial for others to reuse blind there are a series of standards that example scripts need to meet: + - Descriptive programming style - As in variable, function, and class names should describe what they are/do. - Type hinting - All declared variables should have the types declared alongside it. - Well commented - The example should be understandable from the comments with only brief references to the code. -- Doc string - Comment blocks at the beginning of functions and class methods that describes what the function/method -does and lists the inputs, outputs, and exceptions that could be raised. This is important for the documentation of the -repository. +- Doc string - Comment blocks at the beginning of functions and class methods that describes what the function/method + does and lists the inputs, outputs, and exceptions that could be raised. This is important for the documentation of the + repository. - An example of using the function - This will be used for automated testing to ensure functionality is maintained with -changes in the repo and to write the tutorial in the document. + changes in the repo and to write the tutorial in the document. -`isort` and `black` are used to aid code format standardisation. +`isort` and `black` are used to aid code format standardisation. This can be done from the comand line using: ``` @@ -77,10 +85,10 @@ python -m black . python -m isort . ``` -The configuration for `isort` and `black` are in `pyproject.toml`. +The configuration for `isort` and `black` are in `pyproject.toml`. ### Testing Unit tests should be written to verify that the examples meet their objectives. -GitHub Actions are used to automate the running of the unit tests as a condition for merging into the main and dev +GitHub Actions are used to automate the running of the unit tests as a condition for merging into the main and dev branch. diff --git a/run_pytests.sh b/run_pytests.sh index 955e8c2..c956c94 100644 --- a/run_pytests.sh +++ b/run_pytests.sh @@ -1,3 +1 @@ -source /c/ProgramData/Anaconda3/etc/profile.d/conda.sh -conda activate PythonRepositoryTemplate -PYTHONPATH=. pytest \ No newline at end of file +PYTHONPATH=. .venv/bin/python -m pytest \ No newline at end of file diff --git a/setup_project.sh b/setup_project.sh index 67833dc..1dbf9e6 100644 --- a/setup_project.sh +++ b/setup_project.sh @@ -6,10 +6,9 @@ ######################################################################################################################## ### Setting up the python environment -source /c/ProgramData/Anaconda3/etc/profile.d/conda.sh -conda create -n PythonRepositoryTemplate python=3.9 --yes -conda activate PythonRepositoryTemplate -pip install -r requirements.txt +# source /c/ProgramData/Anaconda3/etc/profile.d/conda.sh +conda create -p ./.venv python=3.9 --yes +.venv/bin/python -m pip install -r requirements.txt ### Setting up the repo directories mkdir input @@ -19,4 +18,4 @@ mkdir output cp metadata/config.json config.json ### Test repo setup -source run_pytests.sh \ No newline at end of file +source run_pytests.sh # PYTHONPATH=. .venv/bin/python -m pytest \ No newline at end of file