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 considering contributing to OE Python Template Example!
4
4
5
-
## Setup
6
-
7
-
Clone this GitHub repository via ```git clone git@github.com:helmut-hoffer-von-ankershoffen/oe-python-template-example.git``` and change into the directory of your local OE Python Template Example repository: ```cd oe-python-template-example```
8
5
9
-
Install the dependencies:
6
+
## Setup
10
7
11
-
### macOS
8
+
Install or update tools required for development:
12
9
13
10
```shell
14
-
if!command -v brew &> /dev/null;then# if Homebrew package manager not present ...
15
-
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"# ... install it
16
-
else
17
-
which brew # ... otherwise inform where brew command was found
18
-
fi
19
-
# Install required tools if not present
20
-
which jq &> /dev/null || brew install jq
21
-
which xmllint &> /dev/null || brew install xmllint
22
-
which act &> /dev/null || brew install act
23
-
which pinact &> /dev/null || brew install pinact
24
-
uv run pre-commit install # install pre-commit hooks, see https://pre-commit.com/
11
+
# Install Homebrew, uv package manager, copier and further dev tools
12
+
curl -LsSf https://raw.githubusercontent.com/helmut-hoffer-von-ankershoffen/oe-python-template/HEAD/install.sh | sh
25
13
```
26
14
27
-
### Linux
15
+
[Create a fork](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/fork) and clone your fork using ```git clone URL_OF_YOUR_CLONE```. Then change into the directory of your local OE Python Template Example repository with ```cd oe-python-template-example```.
16
+
17
+
If you are one of the committers of https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example you can directly clone via ```git clone git@github.com:helmut-hoffer-von-ankershoffen/oe-python-template-example.git``` and ```cd oe-python-template-example```.
uv run pre-commit install # see https://pre-commit.com/
33
-
```
34
19
35
-
## Code
20
+
## Directory Layout
36
21
37
22
```
38
-
src/oe_python_template_example/
23
+
├── Makefile # Central entrypoint for build, test, release and deploy
24
+
├── noxfile.py # Noxfile for running tests in multiple python environments and other tasks
25
+
├── .pre-commit-config.yaml # Definition of hooks run on commits
26
+
├── .github/ # GitHub specific files
27
+
│ ├── workflows/ # GitHub Actions workflows
28
+
│ ├── prompts/ # Custom prompots for GitHub Copilot
29
+
│ └── copilot-instructions.md # Insructions for GitHub Copilot
30
+
├── .vscode/ # Recommended VSCode settings and extensions
31
+
├── .env # Environment variables, on .gitignore
32
+
├── .env.example # Example environment variables
33
+
src/oe_python_template_example/ # Source code
39
34
├── __init__.py # Package initialization
40
-
└── cli.py # Command Line Interface
35
+
├── constants.py # Constants used throughout the app
36
+
├── service.py # Service exposed for use as shared library
37
+
├── models.py # Models and data structures
38
+
├── cli.py # CLI enabling to interact with service from terminal
39
+
└── api.py # API exposing service as web service
41
40
tests/ # Unit and E2E tests
42
41
├── cli_tests.py # Verifies the CLI functionality
42
+
├── api_tests.py # Verifies the API functionality
43
43
└── fixtures/ # Fixtures and mock data
44
+
docs/ # Documentation
45
+
├── partials/*.md # Partials to compile README.md, _main partial included in HTML and PDF documentation
46
+
├── ../README.md # Compiled README.md shown on GitHub
47
+
├── source/*.rst # reStructuredText files used to generate HTML and PDF documentation
48
+
├── ../*.md # Markdown files shown on GitHub and imported by .rst files
49
+
├── source/conf.py # Sphinx configuration used to generate HTML and PDF documentation
50
+
├── build/html/* # Generated HTML documentation as multiple pages
51
+
├── build/singlehtml/index.html # HTML documentation as a single page
52
+
└── build/latex/oe-python-template-example.pdf # PDF manual - generate with make docs pdf
44
53
examples/ # Example code demonstrating use of the project
45
54
├── streamlit.py # Streamlit App, deployed in Streamlit Community Cloud
46
55
├── notebook.py # Marimo notebook
47
56
├── notebook.ipynb # Jupyter notebook
48
57
└── script.py # Minimal script
58
+
reports/ # Compliance reports for auditing
59
+
├── junit.xml # Report of executions
60
+
├── mypy_junit.xml # Report of executions
61
+
├── coverage.xml # Test coverage in XML format
62
+
├── coverage_html # Report of test coverage in HTML format
63
+
├── licenses.csv # List of dependencies and their license types
64
+
├── licenses.json # .json file with dependencies their license types
65
+
├── licenses_grouped.json # .json file with dependencies grouped by license type
66
+
├── notebook.ipynb # Jupyter notebook
67
+
└── script.py # Minimal script
49
68
```
50
69
51
-
## Run
52
70
53
-
### .env file
71
+
## Build, Run and Release
72
+
73
+
### Setup project specific development environment
74
+
75
+
```shell
76
+
make setup
77
+
```
54
78
55
79
Don't forget to configure your `.env` file with the required environment variables.
56
80
57
81
Notes:
58
-
1. .env.example is provided as a template.
82
+
1. .env.example is provided as a template, use ```cp .env.example .env``` and edit ```.env``` to create your environment.
59
83
2. .env is excluded from version control, so feel free to add secret values.
60
84
61
-
### update dependencies and create virtual environment
62
-
63
-
```shell
64
-
uv sync # install dependencies
65
-
uv sync --all-extras # install all extras, required for examples
66
-
uv venv # create a virtual environment
67
-
source .venv/bin/activate # activate it
68
-
uv run pre-commit install # Install pre-commit hook etc.
69
-
```
70
-
71
-
### run the CLI
85
+
### Build
72
86
73
87
```shell
74
-
uv run oe-python-template-example # shows help
88
+
make # Runs primary build steps, i.e. formatting, linting, testing, building HTML docs and distribution, auditing
89
+
make help# Shows help with additional build targets, e.g. to build PDF documentation, bump the version to release etc.
75
90
```
76
91
77
-
## Build
92
+
Notes:
93
+
1. Primary build steps defined in `noxfile.py`.
94
+
2. Distribution dumped into ```dist/```
95
+
3. Documentation dumped into ```docs/build/html/``` and ```docs/build/latex/```
96
+
4. Audit reports dumped into ```reports/```
78
97
79
-
All build steps are defined in `noxfile.py`.
98
+
### Run the CLI
80
99
81
100
```shell
82
-
uv run nox # Runs all build steps except setup_dev
101
+
uv run oe-python-template-example # shows help
83
102
```
84
103
85
-
You can run individual build steps - called sessions in nox as follows:
104
+
### Commit and Push your changes
86
105
87
106
```shell
88
-
uv run nox -s test# run tests
89
-
uv run nox -s lint # run formatting and linting
90
-
uv run nox -s audit # run security and license audit, inc. sbom generation
91
-
uv run nox -s docs # build documentation, output in docs/build/html
92
-
uv run nox -s docs_pdf # locally build pdf manual to docs/build/latex/oe-python-template-example.pdf
107
+
git add .
108
+
git commit -m "feat(user): added new api endpoint to offboard user"
109
+
git push
93
110
```
94
111
95
-
As a shortcut, you can run build steps using `./n`, e.g.
112
+
Notes:
113
+
1.[pre-commit hooks](https://pre-commit.com/) will run automatically on commit to ensure code quality.
114
+
2. We use the conventional commits format - see the [code style guide](CODE_STYLE.md) for the mandatory commit message format.
96
115
97
-
```shell
98
-
./n test
99
-
./n lint
100
-
# ...
101
-
```
116
+
### Publish Release
102
117
103
-
Generate a wheel using uv
104
118
```shell
105
-
uv build
119
+
make bump # Patch release
120
+
make minor # Patch release
121
+
make major # Patch release
122
+
make x.y.z # Targeted release
106
123
```
107
124
108
125
Notes:
109
-
1. Reports dumped into ```reports/```
110
-
3. Documentation dumped into ```docs/build/html/```
111
-
2. Distribution dumped into ```dist/```
126
+
1. Changelog generated automatically
127
+
2. Publishes to PyPi, Docker Registries, Read The Docs, Streamlit and Auditing services
112
128
113
-
### Running GitHub CI workflow locally
129
+
130
+
## Advanced usage
131
+
132
+
### Running GitHub CI Workflow locally
114
133
115
134
```shell
116
-
uv run nox -s act
135
+
make act
117
136
```
118
137
119
138
Notes:
@@ -122,34 +141,68 @@ Notes:
122
141
123
142
### Docker
124
143
144
+
Build and run the Docker image with plain Docker
145
+
125
146
```shell
126
-
docker build -t oe-python-template-example .
147
+
# Build from Dockerimage
148
+
make docker build
149
+
# Run the CLI
150
+
docker run --env THE_VAR=THE_VALUE oe-python-template-example --help
127
151
```
128
152
153
+
Build and run the Docker image with docker compose:
154
+
129
155
```shell
130
-
docker run --env THE_VAR=THE_VALUE oe-python-template-example --help
156
+
echo"Building the Docker image with docker compose and running CLI..."
157
+
docker compose run --build oe-python-template --help
158
+
echo"Building the Docker image with docker compose and running API container as a daemon ..."
159
+
docker compose up --build -d
160
+
echo"Waiting for the API server to start..."
161
+
sleep 5
162
+
echo"Checking health of v1 API ..."
163
+
curl http://127.0.0.1:8000/api/v1/healthz
164
+
echo""
165
+
echo"Saying hello world with v1 API ..."
166
+
curl http://127.0.0.1:8000/api/v1/hello-world
167
+
echo""
168
+
echo"Swagger docs of v1 API ..."
169
+
curl http://127.0.0.1:8000/api/v1/docs
170
+
echo""
171
+
echo"Checking health of v2 API ..."
172
+
curl http://127.0.0.1:8000/api/v2/healthz
173
+
echo""
174
+
echo"Saying hello world with v1 API ..."
175
+
curl http://127.0.0.1:8000/api/v2/hello-world
176
+
echo""
177
+
echo"Swagger docs of v2 API ..."
178
+
curl http://127.0.0.1:8000/api/v2/docs
179
+
echo""
180
+
echo"Shutting down the API container ..."
181
+
docker compose down
131
182
```
132
183
133
-
### Pinning github actions
184
+
### Pinning GitHub Actions
134
185
135
186
```shell
136
187
pinact run # See https://dev.to/suzukishunsuke/pin-github-actions-to-a-full-length-commit-sha-for-security-2n7p
137
188
```
138
189
139
-
### Copier
140
190
141
-
Update from template
191
+
## Update from Template
192
+
193
+
Update project to latest version of [oe-python-template](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template) template.
142
194
143
195
```shell
144
-
uv run nox -s update_from_template
196
+
make update_from_template
145
197
```
146
198
199
+
147
200
## Pull Request Guidelines
148
201
149
-
1. Before starting to write code read the [code style guide](CODE_STYLE.md) document for mandatory coding style
150
-
guidelines.
202
+
1. Before starting to write code read the [code style](CODE_STYLE.md) document for mandatory coding style requirements.
151
203
2.**Pre-Commit Hooks:** We use pre-commit hooks to ensure code quality. Please install the pre-commit hooks by running `uv run pre-commit install`. This ensure all tests, linting etc. pass locally before you can commit.
152
204
3.**Squash Commits:** Before submitting a pull request, please squash your commits into a single commit.
153
-
4.**Branch Naming:** Use descriptive branch names like `feature/your-feature` or `fix/issue-number`.
154
-
5.**Testing:** Ensure new features have appropriate test coverage.
155
-
6.**Documentation:** Update documentation to reflect any changes or new features.
205
+
4.**Signed Commits:** Use [signed commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).
206
+
5.**Branch Naming:** Use descriptive branch names like `feature/your-feature` or `fix/issue-number`.
207
+
6.**Testing:** Ensure new features have appropriate test coverage.
208
+
7.**Documentation:** Update documentation to reflect any changes or new features.
0 commit comments