Skip to content

Commit 9ad4f7b

Browse files
pariterrepariterre
committed
Basic structure of the project
1 parent 76379c8 commit 9ad4f7b

15 files changed

Lines changed: 285 additions & 0 deletions

File tree

‎.github/workflows/isblacked.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
#Checks if the code is formatted with black.
2+
3+
name: Is your code linted with black?
4+
on: [pull_request]
5+
jobs:
6+
build:
7+
runs-on: ubuntu-latest
8+
steps:
9+
- uses: actions/checkout@v4
10+
11+
- name: Set up Python
12+
uses: actions/setup-python@v5
13+
14+
- name: Install Black
15+
run: pip install black
16+
17+
- name: Run black --check .
18+
run: black . --check -l120 --verbose

‎.github/workflows/run_tests.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Run the tests
2+
3+
on: [pull_request]
4+
5+
env:
6+
EXAMPLES_FOLDER: examples
7+
8+
jobs:
9+
build:
10+
strategy:
11+
matrix:
12+
os: [ubuntu-latest, macos-latest, macos-13, windows-latest]
13+
include:
14+
- os: ubuntu-latest
15+
label: linux-64
16+
prefix: /usr/share/miniconda3/envs/project_template
17+
- os: macos-latest
18+
label: osx-arm64
19+
prefix: /Users/runner/miniconda3/envs/project_template
20+
- os: macos-13
21+
label: osx-intel
22+
prefix: /Users/runner/miniconda3/envs/project_template
23+
- os: windows-latest
24+
label: win-64
25+
prefix: C:\Miniconda3\envs\project_template
26+
name: ${{ matrix.label }}
27+
runs-on: ${{ matrix.os }}
28+
defaults:
29+
run:
30+
shell: bash -l {0}
31+
steps:
32+
- name: Checkout code
33+
uses: actions/checkout@v4
34+
35+
- name: Set up Python
36+
uses: actions/setup-python@v5
37+
38+
- name: Install dependencies
39+
run: pip install -r requirements.txt
40+
41+
- name: Install test dependencies
42+
run: pip install pytest pytest-cov codecov
43+
44+
- name: Run tests with code coverage
45+
run: pytest -v --color=yes --cov-branch --cov-report=xml --cov=project_template tests
46+
if: matrix.os == 'ubuntu-latest'
47+
48+
- name: Upload coverage reports to Codecov
49+
uses: codecov/codecov-action@v5
50+
with:
51+
fail_ci_if_error: true
52+
verbose: true
53+
if: matrix.os == 'ubuntu-latest'
54+
55+
- name: Test installed version of python
56+
run: |
57+
BASE_FOLDER=`pwd`
58+
pip install .
59+
cd
60+
python -c "import project_template"
61+
cd $BASE_FOLDER
62+

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,3 +169,6 @@ cython_debug/
169169

170170
# PyPI configuration file
171171
.pypirc
172+
173+
# Working directory
174+
sandbox/

‎.vscode/launch.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
// Utilisez IntelliSense pour en savoir plus sur les attributs possibles.
3+
// Pointez pour afficher la description des attributs existants.
4+
// Pour plus d'informations, visitez : https://go.microsoft.com/fwlink/?linkid=830387
5+
"version": "0.2.0",
6+
"configurations": [
7+
{
8+
"name": "Print version",
9+
"type": "debugpy",
10+
"request": "launch",
11+
"program": "${workspaceFolder}/examples/print_version.py",
12+
"console": "integratedTerminal",
13+
"justMyCode": true,
14+
"env": {"PYTHONPATH": "${workspaceFolder}"},
15+
"cwd": "${workspaceFolder}/examples/"
16+
},
17+
]
18+
}

‎.vscode/settings.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"python.testing.pytestArgs": ["tests"],
3+
"python.testing.unittestEnabled": false,
4+
"python.testing.pytestEnabled": true,
5+
"python.testing.pytestPath": "${workspaceFolder}",
6+
"[python]": {
7+
"editor.defaultFormatter": "ms-python.black-formatter",
8+
"editor.formatOnSave": true,
9+
"editor.rulers": [120],
10+
}
11+
}

‎docs/contributing.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Contributing to `project_template`
2+
All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome.
3+
We recommend going through the list of [`issues`](https://github.com/pyomeca/python_project_template/issues) to find issues that interest you, preferable those tagged with `good first issue`.
4+
You can then get your development environment setup with the following instructions.
5+
6+
## Forking `project_template`
7+
8+
You will need your own fork to work on the code.
9+
Go to the [project_template project page](https://github.com/pyomeca/python_project_template/) and hit the `Fork` button.
10+
You will want to clone your fork to your machine:
11+
12+
```bash
13+
git clone https://github.com/your-user-name/python_project_template.git
14+
```
15+
16+
## Creating and activating conda environment
17+
18+
Before starting any development, we recommend that you create an isolated development environment.
19+
The easiest and most efficient way (due to the numerous dependencies of `project_template`) is to use an anaconda virtual environment and to create it based on the `environment.yml` file.
20+
21+
- Install [miniconda](https://conda.io/miniconda.html)
22+
- `cd` to the `project_template` source directory
23+
- Install `project_template` dependencies with:
24+
25+
```bash
26+
conda env create -f environment.yml
27+
conda activate project_template
28+
```
29+
30+
## Implementing new features
31+
32+
Before implementing your awesome new feature, please discuss with the code owner to prevent any clashing with some other competing developments.
33+
It is also a good idea to check the current opened pull-request not to redo something currently being developed.
34+
If your feature is mentioned in the issue section of GitHub, please assign it to yourself.
35+
Otherwise, please open a new issue explaining what you are currently working on (and assign it to yourself!).
36+
37+
As soon as possible, you are asked to open a pull-request (see below) with a short but descriptive name.
38+
Unless that pull-request is ready to be merged, please tag it as `work in progress` by adding `[WIP]` at the beginning of the pull-request name.
39+
If you are ready to get your PR reviewed, you can add the tag `ready to review` by adding `[RTR]`.
40+
If you think your PR is ready for the last review, please use the tag `ready to merge` by adding `[RTM]`.
41+
Send commits that are as small as possible; 1 to 10 lines is probably a good guess, with again short but descriptive commit names.
42+
Be aware of the review done by the maintainers, they will contain useful tips and advice that should be integrated ASAP.
43+
Once you have responded to a specific comment, please respond `Done!` and tag it as resolved.
44+
45+
Make sure you add a minimal but meaningful example of your new feature in the `examples` folder and that you create a test with numerical values for comparison.
46+
If this feature changes the API, this should also be reflected in the ReadMe.
47+
During your development, you can create a `sandbox` folder.
48+
Everything in this folder will automatically be ignored by Git.
49+
If by accident you add a binary file in the history file (by not using a sandbox), your pull-request will be rejected and you will have to produce a new pull-request free from the binary file.
50+
51+
When you have completed the implementation of your new feature, navigate to your pull-request in GitHub and select `Pariterre` in the `Reviewers` drop menu.
52+
At the same time, if you think your review is ready to be merged, remove the `[WIP]` tag in the name (otherwise, your pull-request won't be merged).
53+
If your pull-request is accepted, there is nothing more to do, Congrats!
54+
If changes are required, reply to all the comments and, as stated previously, respond `Done!` and tag them as resolved.
55+
Be aware that sometimes the maintainer can push modifications directly to your branch, so make sure to pull before continuing your work on that branch.
56+
57+
## Testing your code
58+
59+
Adding tests are required to get your development merged to the master branch.
60+
Therefore, it is very good practice to get the habit of writing tests ahead of time so this is never an issue.
61+
The `project_template` test suite runs automatically on GitHub every time a commit is submitted.
62+
However, we strongly encourage running tests locally prior to submitting the pull-request.
63+
To do so, simply run the tests folder in pytest (`pytest tests`).
64+
65+
## Commenting
66+
67+
Every function, class and module should have their respective proper docstrings completed.
68+
The docstring convention used is NumPy.
69+
Moreover, if your new features is available to the lay user (i.e., it changes the API), the `ReadMe.md` should be modified accordingly.
70+
71+
## Convention of coding
72+
73+
`project_template` tries to follow as much as possible the PEP recommendations (https://www.python.org/dev/peps/).
74+
Unless you have good reasons to disregard them, your pull-request is required to follow these recommendations.
75+
I won't get into details here, if you haven't yet, you should read them :)
76+
77+
All variable names that could be plural should be written as such.
78+
79+
Black is used to enforce the code spacing.
80+
`project_template` is linted with the 120-character max per line's option.
81+
This means that your pull-request tests on GitHub will appear to fail if black fails.
82+
The easiest way to make sure black is happy is to locally run this command:
83+
```bash
84+
black . -l120
85+
```
86+
If you need to install black, you can do it via conda using the conda-forge channel.
87+

‎docs/pull_request_template.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
### All Submissions:
2+
3+
* [ ] Have you followed the guidelines in our Contributing document [docs/contribution.md]?
4+
* [ ] Have you checked to ensure there aren't other open [Pull Requests] for the same update/change?
5+
* [ ] Have you opened/linked the issue related to your pull request?
6+
* [ ] Have you used the tag [WIP] for on-going changes, and removed it when the pull request was ready?
7+
* [ ] When ready to merge, have you sent a comment pinging @pariterre in it?
8+
9+
### New Feature Submissions:
10+
11+
1. [ ] Does your submission pass the tests (if not please explain why this is intended)?
12+
2. [ ] Did you write a proper documentation (docstrings and ReadMe)
13+
3. [ ] Have you linted your code locally prior to submission (using the command: `black . -l120"`)?
14+
15+
### Changes to Core Features:
16+
17+
* [ ] Have you added an explanation of what your changes do and why you'd like us to include them?
18+
* [ ] Have you written new examples for your core changes, as applicable?
19+
* [ ] Have you written new tests for your core changes, as applicable?

‎environment.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# create a dev conda environment with: `make create_env` or `conda env create -f environment.yml`
2+
name: project_template
3+
channels:
4+
- conda-forge
5+
dependencies:
6+
- numpy

‎examples/print_version.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
import project_template
2+
3+
4+
def main():
5+
print(project_template.__version__)
6+
7+
8+
if __name__ == "__main__":
9+
main()

‎project_template/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
from .version import __version__

0 commit comments

Comments
 (0)