Skip to content

Commit 0326064

Browse files
iu2frliu2frl
committed
First test of Python library
1 parent 269937d commit 0326064

15 files changed

Lines changed: 739 additions & 3 deletions

File tree

‎.github/workflows/publish.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Upload Python Package to PyPI when a Release is Created
2+
3+
on:
4+
release:
5+
types: [created]
6+
workflow_dispatch:
7+
8+
jobs:
9+
10+
call-validate-local:
11+
name: Call Test Python Code with Local Libraries
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v4
15+
- name: Check local files
16+
run: |
17+
ls -a
18+
- name: Call action to validate local code
19+
uses: ./.github/workflows/validate-local/
20+
21+
call-validate-wheel:
22+
name: Call Test Python Code to Build Wheel
23+
runs-on: ubuntu-latest
24+
steps:
25+
- uses: actions/checkout@v4
26+
- name: Check local files
27+
run: |
28+
ls -a
29+
- name: Call action to validate wheel
30+
uses: ./.github/workflows/validate-wheel/
31+
32+
pypi-publish:
33+
needs: [ call-validate-local, call-validate-wheel ]
34+
name: Publish release to PyPI
35+
runs-on: ubuntu-latest
36+
environment:
37+
name: pypi
38+
url: https://pypi.org/p/python-vor
39+
permissions:
40+
id-token: write
41+
steps:
42+
- uses: actions/checkout@v4
43+
- uses: actions-ecosystem/action-get-latest-tag@v1
44+
id: get-latest-tag
45+
- name: Set up Python
46+
uses: actions/setup-python@v4
47+
with:
48+
python-version: "3.x"
49+
- name: Install dependencies and build package
50+
run: |
51+
python -m venv venv
52+
source ./venv/bin/activate
53+
pip install --upgrade pip
54+
pip install setuptools wheel build
55+
pip install -r src/python_vor/requirements.txt
56+
sed -i 's/version = "v0.0.0"/version = "${{ steps.get-latest-tag.outputs.tag }}"/' ./pyproject.toml
57+
python -m build
58+
- name: Publish package distributions to PyPI
59+
uses: pypa/gh-action-pypi-publish@release/v1

‎.github/workflows/test-code.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Validate Python Package and test code
2+
3+
on:
4+
pull_request:
5+
types: [opened, synchronize]
6+
push:
7+
branches:
8+
- main
9+
workflow_dispatch:
10+
11+
jobs:
12+
13+
call-validate-local:
14+
name: Call Test Python Code with Local Libraries
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
- name: Check local files
19+
run: |
20+
ls -a
21+
- name: Call action to validate local code
22+
uses: ./.github/workflows/validate-local/
23+
24+
call-validate-wheel:
25+
name: Call Test Python Code to Build Wheel
26+
runs-on: ubuntu-latest
27+
steps:
28+
- uses: actions/checkout@v4
29+
- name: Check local files
30+
run: |
31+
ls -a
32+
- name: Call action to validate wheel
33+
uses: ./.github/workflows/validate-wheel/

‎.github/workflows/validate-local/action.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: Validate Python libraries and runs tests
2+
description: 'Validates Python libraries and runs tests'
3+
4+
runs:
5+
using: "composite"
6+
steps:
7+
- uses: actions/checkout@v4
8+
- name: Set up Python
9+
uses: actions/setup-python@v4
10+
with:
11+
python-version: "3.x"
12+
- name: Install dependencies
13+
shell: bash
14+
run: |
15+
python -m venv venv
16+
source ./venv/bin/activate
17+
pip install --upgrade pip
18+
pip install -r src/python_vor/requirements.txt
19+
- name: Run bearings validation
20+
shell: bash
21+
run: |
22+
source ./venv/bin/activate
23+
python3 ./tests/bearings_validation.py

‎.github/workflows/validate-wheel/action.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
name: Validate Python Package and test code
2+
description: 'Validates Python package and runs tests'
3+
4+
runs:
5+
using: "composite"
6+
steps:
7+
- uses: actions/checkout@v4
8+
- name: Set up Python
9+
uses: actions/setup-python@v4
10+
with:
11+
python-version: "3.x"
12+
- name: Install dependencies
13+
shell: bash
14+
run: |
15+
python -m venv venv
16+
source ./venv/bin/activate
17+
pip install --upgrade pip
18+
pip install -r src/python_vor/requirements.txt
19+
pip install --upgrade build
20+
- name: Build package
21+
shell: bash
22+
run: |
23+
source ./venv/bin/activate
24+
python -m build
25+
- name: Install package
26+
shell: bash
27+
run: |
28+
source ./venv/bin/activate
29+
python -m build
30+
pip install ./dist/python_vor-0.0.0.tar.gz
31+
- name: Run bearings validation
32+
shell: bash
33+
run: |
34+
source ./venv/bin/activate
35+
python3 ./tests/bearings_validation.py

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,7 @@
11
*.wav
22
!audio/*.wav
3+
venv/*
4+
*.pyc
5+
__pycache__/
6+
src/python_vor.egg-info/*
7+
dist/*

‎CODE_OF_CONDUCT.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Code of Conduct
2+
3+
## Introduction
4+
5+
Welcome to the **Python VOR** repository. We strive to create an inclusive and respectful community where all contributors feel welcome and valued. This Code of Conduct outlines our expectations for behavior and the consequences of unacceptable conduct.
6+
7+
## Our Pledge
8+
9+
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and community a harassment-free experience for everyone, regardless of age, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
10+
11+
## Expected Behavior
12+
13+
- Be respectful and considerate to all contributors.
14+
- Communicate in a professional and constructive manner.
15+
- Be open to feedback and be willing to collaborate.
16+
- Give credit where credit is due.
17+
- Help create a welcoming and inclusive environment.
18+
19+
## Unacceptable Behavior
20+
21+
- Harassment, abuse, or discrimination of any kind.
22+
- Personal attacks, trolling, or inflammatory comments.
23+
- Publishing private information of others without consent.
24+
- Any form of disruptive or unethical behavior.
25+
26+
## Reporting Violations
27+
28+
If you witness or experience unacceptable behavior, please report it to the repository maintainers via GitHub Issues or email. All reports will be reviewed and addressed promptly and confidentially.
29+
30+
## Enforcement
31+
32+
Maintainers have the right to remove comments, issues, or contributors who violate this Code of Conduct. In severe cases, contributors may be banned from participating in the project.
33+
34+
## Acknowledgment
35+
36+
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.
37+
38+
By participating in this project, you agree to abide by this Code of Conduct.

‎CONTRIBUTING.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# IU2FRL VOR Python Library
2+
3+
## Guidelines for Contributions
4+
5+
Thank you for your interest in contributing to the IU2FRL VOR Python Library! The following guidelines will help maintain code quality and ensure smooth collaboration.
6+
7+
### General Contribution Process
8+
9+
- Fork the Repository: Create a fork of the main repository.
10+
- Create a Branch: Work on a separate branch for your feature or bugfix.
11+
- Implement Changes: Follow the guidelines outlined in this document for adding new functionality.
12+
- Write Tests: Ensure all new code is covered by appropriate tests.
13+
- Run Tests Locally: Verify that all tests pass before submitting a merge request (MR).
14+
- Submit a Merge Request: Open a merge request, providing a clear description of your changes.
15+
16+
#### Pull Request Guidelines
17+
18+
- Keep PRs focused on a single feature or fix.
19+
- Ensure tests pass before submitting.
20+
- Include a concise summary of changes in the PR description.
21+
22+
#### Code Style and Best Practices
23+
24+
- Follow PEP 8 for Python code styling.
25+
- Use meaningful commit messages.
26+
- Maintain consistency with existing code structures.
27+
- Keep functions and classes well-documented (docstrings are mandatory).
28+
29+
## Reporting Issues
30+
31+
- Before reporting a bug, check open issues to avoid duplicates.
32+
- Provide clear reproduction steps and logs when applicable.
33+
- Include environment details (Python version, OS, etc.).
34+
35+
## Developers instructions
36+
37+
This chapter covers the steps required for contributing to this library. Please review all the points before starting editing the library and submitting a MR.
38+
39+
> [!IMPORTANT]
40+
> Do not rename the `tests` folder or any files in such folder, as those are used for automated testing.
41+
42+
### Adding methods to the library
43+
44+
New methods should be added to the `python_vor` package, which is located in the `src/python_vor/` directory of the project. The package should contain all the methods that are used to calculate the bearing of a VOR signal from a WAV file.
45+
46+
After defining the public methods, you should add them to the `__init__.py` file in the `src/python_vor/` directory. This file is used to define the public API of the package, and it should include all the methods that are intended to be used by the users of the library.
47+
48+
### Update pyproject.toml
49+
50+
> [!IMPORTANT]
51+
> Do not edit the line with `version = "v0.0.0"` as this is automatically set by GitHub when building the new release
52+
53+
If any dependency is added, please update the `pyproject.toml` file in the root directory of the project. This file contains the metadata for the project, including dependencies, version, and entry points.
54+
55+
### Create a test script
56+
57+
To test the new methods, you should create a test script in the `tests` folder. The test script should import the methods from the `python_vor` package and use them to calculate the bearing of a VOR signal from a WAV file.
58+
59+
> [!WARNING]
60+
> Make sure to uninstall any version of the library that was previously installed using `pip uninstall python-vor` or the newly created device will be ignored
61+
62+
Add the test script to the `tests` folder, and make sure to name it appropriately (e.g., `test_<feature_name>.py`). The test script should include:
63+
64+
- Importing the necessary methods from the `python_vor` package.
65+
- Loading a WAV file from the `audio` folder.
66+
- Calling the methods with the WAV file and any required parameters.
67+
- Printing the results or asserting expected values.
68+
69+
### Manual build procedure
70+
71+
Before sending the merge request, please try to build the package locally and make sure everything works
72+
73+
> [!WARNING]
74+
> Make sure to uninstall any version of the library that was previously installed using `pip uninstall python-vor` or the newly created device will be ignored
75+
76+
1. Move to the root directory of the project (where the `pyproject.toml` file is located)
77+
2. Install the build tools: `python -m pip install --upgrade build`
78+
3. Build the wheel package: `python -m build`
79+
4. Install the package that was just built: `pip install ./dist/python_vor-0.0.0.tar.gz`
80+
5. Test the package using the existing test codes in the `tests/` folder
81+
6. Test the package using the code in the test file you just created
82+
83+
### Removing the manually built package
84+
85+
If you need to remove the manually built package, you can do so by running:
86+
87+
1. Uninstall the package: `pip uninstall python-vor`
88+
2. Confirm the uninstallation when prompted.
89+
90+
### 7. Submit a Merge Request
91+
92+
Once you have tested your new device and everything is working as expected, you can submit a merge request (MR) to the main repository.
93+
94+
Please ensure that your MR includes:
95+
96+
- A clear description of the changes made.
97+
- Any relevant documentation updates.
98+
- A link (or reference) to the test script you created for the new device.
99+
100+
We will review your MR and provide feedback if necessary. If everything looks good, we will merge your changes into the main branch.
101+
102+
We appreciate your contributions and look forward to collaborating with you!

‎README.md‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ The following test points were used, with their respective bearings:
4343
- Recording should be saved with a minimum sample rate of 48KHz (96KHz preferred)
4444
- There is no need to record more than 1 second of audio, as the decoder processes the signal in chunks.
4545

46-
### Jupyter Notebook processing
46+
### Calculating using Jupyter Notebook
4747

4848
The Jupyter Notebook `VOR_Decoder.ipynb` provides an interactive environment to process the recorded WAV file and extract the bearing.
4949

@@ -52,6 +52,19 @@ It displays the decoding steps, including the original signal, filtered signals,
5252
1. **Set the `FILENAME` variable** in the notebook or script to point to your WAV file.
5353
1. **Run the notebook or script** to process the signal and extract the bearing.
5454

55+
### Calculating using Python library
56+
57+
1. Install the library using pip: `pip install python-vor`
58+
2. Import the `get_bearing` function from the library: `from python_vor import get_bearing`
59+
3. Call the function with the WAV file path and optional parameters:
60+
61+
```python
62+
from python_vor import get_bearing
63+
offset = 216 # Optional offset to add in the VOR calculation
64+
bearing = get_bearing(str(wav_file), offset=offset)
65+
print(f"Bearing for {wav_file.name}: {bearing:.2f}°")
66+
```
67+
5568
### Processing details
5669

5770
The processing steps include:
@@ -66,12 +79,13 @@ The processing steps include:
6679

6780
- numpy
6881
- scipy
69-
- matplotlib
82+
- matplotlib (only for the Jupyter Notebook visualization)
7083

7184
Install them via pip if needed:
7285

7386
```bash
74-
pip install numpy scipy matplotlib
87+
pip install scipy==1.16.0
88+
pip install numpy==2.3.1
7589
```
7690

7791
## Attribution

‎pyproject.toml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
[project]
2+
name = "python-vor"
3+
authors = [
4+
{ name="Luca Bennati", email="lucabennati1996@gmail.com" }
5+
]
6+
description = "A small library to calculate the bearing of a VOR signal from a WAV file."
7+
readme = "README.md"
8+
license-files = [ "LICENSE", "CODE_OF_CONDUCT.md", "README.md", "CONTRIBUTING.md" ]
9+
keywords = ["vor", "bearing", "airports", "location", "navigation", "signal processing"]
10+
requires-python = ">=3.8"
11+
dependencies = [
12+
"scipy == 1.16.0",
13+
"numpy == 2.3.1"
14+
]
15+
classifiers = [
16+
"Development Status :: 4 - Beta",
17+
"Intended Audience :: Developers",
18+
"Programming Language :: Python",
19+
"Programming Language :: Python :: 3",
20+
"Programming Language :: Python :: 3.10",
21+
"Programming Language :: Python :: 3.11",
22+
"Programming Language :: Python :: 3.12",
23+
"Operating System :: OS Independent",
24+
]
25+
version = "v0.0.0"
26+
27+
[project.urls]
28+
Homepage = "https://github.com/iu2frl/python_vor"
29+
Source = "https://github.com/iu2frl/python_vor"
30+
Issues = "https://github.com/iu2frl/python_vor/issues"
31+
32+
[build-system]
33+
requires = ["setuptools", "scipy==1.16.0", "numpy == 2.3.1", "wheel"]
34+
build-backend = "setuptools.build_meta"
35+
36+
# Define entry points
37+
[project.entry-points."python_vor.python_vor"]

‎src/python_vor/__init__.py‎

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

0 commit comments

Comments
 (0)