You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Thank you for your interest in improving this project.
4
-
This project is open-source under the [MIT license] and
5
-
welcomes contributions in the form of bug reports, feature requests, and pull requests.
3
+
Thank you for your interest in improving this project. This project is open-source under the [MIT license] and welcomes contributions in the form of bug reports, feature requests, and pull requests.
6
4
7
5
Here is a list of important resources for contributors:
8
6
@@ -28,138 +26,131 @@ When filing an issue, make sure to answer these questions:
28
26
- What did you expect to see?
29
27
- What did you see instead?
30
28
31
-
The best way to get your bug fixed is to provide a test case,
32
-
and/or steps to reproduce the issue.
29
+
The best way to get your bug fixed is to provide a test case, and/or steps to reproduce the issue.
33
30
34
31
## How to request a feature
35
32
36
-
Features that improve `sectionproperties` can be suggested on the [Issue Tracker].
37
-
It's a good idea to first submit the proposal as a feature request prior to submitting
38
-
a pull request as this allows for the best coordination of efforts by preventing the
39
-
duplication of work, and allows for feedback on your ideas.
33
+
Features that improve `sectionproperties` can be suggested on the [Issue Tracker]. It's a good idea to first submit the proposal as a feature request prior to submitting a pull request as this allows for the best coordination of efforts by preventing the duplication of work, and allows for feedback on your ideas.
40
34
41
35
## How to set up your development environment
42
36
43
-
You need Python 3.10, 3.11 or 3.12, and the following tools:
37
+
`sectionproperties` uses `uv` for python project management. `uv` can be installed on using the standalone installer:
44
38
45
-
-[Poetry]
46
-
-[Nox]
47
-
-[nox-poetry]
39
+
```shell
40
+
curl -LsSf https://astral.sh/uv/install.sh | sh
41
+
```
42
+
43
+
Installation instructions for other methods and Windows can be found [here](https://docs.astral.sh/uv/getting-started/installation/).
48
44
49
-
Recommended dependency installation method:
45
+
`uv` can then be used to install the latest compatible version of python:
`sectionproperties` and it's development dependencies can be installed with:
52
52
53
53
```shell
54
-
python3 -m pip install --user pipx
55
-
python3 -m pipx ensurepath
54
+
uv sync
56
55
```
57
56
58
-
2. Install [Poetry]:
57
+
If you have other versions of python installed on your machine you may need to add the `-p` flag to ensure the correct version of python is used:
59
58
60
59
```shell
61
-
pipx install poetry
62
-
poetry --version
60
+
uv sync -p 3.12
61
+
uv run -p 3.12 example.py
63
62
```
64
63
65
-
3. Install [Nox] and [nox-poetry]:
64
+
Specific extras (e.g. `numba`) can be installed with the `--extra` flag or all extras with the `--all-extras` flag:
66
65
67
66
```shell
68
-
pipx install nox
69
-
pipx inject nox nox-poetry
67
+
uv sync --extra numba
68
+
uv sync --all-extras
70
69
```
71
70
72
-
4. If you do not have `pandoc` installed, it will be required to build the docs. The
73
-
[installation method](https://pandoc.org/installing.html) depends on what OS you are
74
-
running.
71
+
If you want to build the documentation locally, you will need to install `pandoc`. The [installation method](https://pandoc.org/installing.html) depends on what OS you are running.
75
72
76
-
Now that you have all the dependencies up and running, you can install
77
-
`sectionproperties` with development requirements:
73
+
To run a script using the development virtual environment, you can run:
Refer to the `uv`[documentation](https://docs.astral.sh/uv/) for more information relating to using `uv` for project management.
80
+
81
+
## How to test the project
82
+
83
+
### Pre-commit
84
+
85
+
[Pre-commit](https://pre-commit.com/) ensures code quality and consistency by running the `ruff` linter and formatter, stripping out execution cells in jupyter notebooks, and running several pre-commit hooks.
86
+
87
+
These can be run against all files in the project with:
86
88
87
89
```shell
88
-
poetry install --extras "dxf rhino"
90
+
uv run pre-commit run --all-files
89
91
```
90
92
91
-
You can now run an interactive Python session, or the command-line interface:
93
+
However, the best way to ensure code quality is by installing the git pre-commit hook:
92
94
93
95
```shell
94
-
poetry run python
95
-
poetry run sectionproperties
96
+
uv run pre-commit install
96
97
```
97
98
98
-
[poetry]: https://python-poetry.org/
99
-
[nox]: https://nox.thea.codes/
100
-
[nox-poetry]: https://nox-poetry.readthedocs.io/
99
+
This will run `pre-commit` against all changed files when attempting to `git commit`. You will need to fix the offending files prior to being able to commit a change unless you run `git commit --no-verify`.
101
100
102
-
##How to test the project
101
+
### Type Checking
103
102
104
-
Run the full test suite:
103
+
`sectionproperties` uses `pyright` to ensure strict type-checking where possible. `pyright` can be run on all files with:
105
104
106
105
```shell
107
-
nox
106
+
uv run pyright
108
107
```
109
108
110
-
List the available Nox sessions:
109
+
### Tests
110
+
111
+
The `sectionproperties` tests are located in the `tests/` directory and are written using the [pytest] testing framework. The test suite can be run with:
111
112
112
113
```shell
113
-
nox --list-sessions
114
+
uv run pytest -m 'not benchmark_suite'
114
115
```
115
116
116
-
You can also run a specific Nox session. For example, invoke the unit test suite like
117
-
this:
117
+
#### Benchmarks
118
+
119
+
If the code you are modifying may affect the performance of `sectionproperties`, it is recommended that you run the benchmarking tests to verify the performance before and after your changes. There are three different benchmarking suites: `geometry`, `meshing` and `analysis`. These can be run like this:
118
120
119
121
```shell
120
-
nox --session=tests
122
+
uv run pytest -m benchmark_geom
123
+
uv run pytest -m benchmark_mesh
124
+
uv run pytest -m benchmark_analysis
121
125
```
122
126
123
-
Unit tests are located in the _tests_ directory, and are written using the [pytest]
124
-
testing framework.
127
+
Note that a plot of the results can be generated by adding the `--benchmark-histogram` option to the above commands.
128
+
129
+
[pytest]: https://pytest.readthedocs.io/
125
130
126
-
### Benchmarks
131
+
### Documentation
127
132
128
-
If the code you are modifying may affect the performance of `sectionproperties`, it is
129
-
recommended that you run the benchmarking tests to verify the performance before and
130
-
after your changes. There are three different benchmarking suites: `geometry`, `meshing`
131
-
and `analysis`. These can be run like this:
133
+
You can build the documentation locally with:
132
134
133
135
```shell
134
-
poetry run pytest -m benchmark_geom
135
-
poetry run pytest -m benchmark_mesh
136
-
poetry run pytest -m benchmark_analysis
136
+
uv run sphinx-build docs docs/_build
137
137
```
138
138
139
-
Note that a plot of the results can be generated by adding the `--benchmark-histogram`
140
-
option to the above commands.
139
+
Make sure that you have a recent version of `pandoc` installed so that the example notebooks can be generated.
141
140
142
-
[pytest]: https://pytest.readthedocs.io/
141
+
Note that all pull requests also build the documentation on Read the Docs, so building the documentation locally is not required.
143
142
144
143
## How to submit changes
145
144
146
145
Open a [pull request] to submit changes to this project.
147
146
148
147
Your pull request needs to meet the following guidelines for acceptance:
149
148
150
-
- The Nox test suite must pass without errors and warnings.
149
+
- The test suite, pre-commit and pyright checks must pass without errors and warnings.
151
150
- Include unit tests. This project aims for a high code coverage.
152
151
- If your changes add functionality, update the documentation accordingly.
153
152
154
-
To run linting and code formatting checks before committing your change, you can install
155
-
pre-commit as a Git hook by running the following command:
156
-
157
-
```shell
158
-
nox --session=pre-commit -- install
159
-
```
160
-
161
-
It is recommended to open an issue before starting work on anything.
162
-
This will allow a chance to talk it over with the owners and validate your approach.
153
+
It is recommended to open an issue before starting work on anything. This will allow a chance to talk it over with the owners and validate your approach.
[][read the docs]
0 commit comments