Skip to content

Commit dc9a42c

Browse files
DpbmDpbm
authored
Initial commit
0 parents  commit dc9a42c

18 files changed

Lines changed: 660 additions & 0 deletions

‎.github/workflows/build_test_publish.yml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
name: Build, Test and publish
2+
3+
on:
4+
push:
5+
branches:
6+
- '*'
7+
tags:
8+
- '*'
9+
jobs:
10+
tox:
11+
name: Run Tox python-${{ matrix.version }} ${{ matrix.os }}
12+
runs-on: ${{ matrix.os }}
13+
strategy:
14+
fail-fast: false
15+
matrix:
16+
version:
17+
- '3.12'
18+
- '3.11'
19+
- '3.10'
20+
os:
21+
- ubuntu-20.04
22+
- ubuntu-22.04-arm
23+
24+
permissions:
25+
contents: read
26+
27+
steps:
28+
- uses: actions/checkout@v4
29+
30+
- uses: actions/setup-python@v5
31+
with:
32+
python-version: ${{ matrix.version }}
33+
34+
- name: install dependencies
35+
run: |
36+
pip install -r requirements.txt -r dev-requirements.txt
37+
38+
- name: Run tox checks
39+
run: tox
40+
41+
publish:
42+
name: Upload package to PYPI
43+
runs-on: ubuntu-24.04
44+
45+
needs: tox
46+
47+
if: startsWith(github.ref, 'refs/tags/')
48+
49+
environment:
50+
name: pypi
51+
url: https://pypi.org/p/example_plugin # change example_plugin to your project's name
52+
53+
permissions:
54+
id-token: write
55+
56+
steps:
57+
- uses: actions/checkout@v4
58+
59+
- name: Set up Python 3.12
60+
uses: actions/setup-python@v5
61+
with:
62+
python-version: 3.12.8
63+
64+
- name: build package
65+
run: |
66+
python3 -m pip install --upgrade build
67+
python3 -m build
68+
69+
- name: Publish to PYPI
70+
uses: pypa/gh-action-pypi-publish@release/v1
71+
72+
# to properly publish that take a look at:
73+
# https://github.com/marketplace/actions/pypi-publish
74+
# https://medium.com/@blackary/publishing-a-python-package-from-github-to-pypi-in-2024-a6fb8635d45d

‎.github/workflows/release.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
name: Release
2+
on:
3+
push:
4+
tags:
5+
- '*'
6+
jobs:
7+
release:
8+
runs-on: ubuntu-24.04
9+
permissions:
10+
contents: write
11+
12+
steps:
13+
- uses: actions/checkout@v3
14+
15+
- name: create release
16+
uses: ncipollo/release-action@v1

‎.gitignore‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
6+
# C extensions
7+
*.so
8+
9+
# Distribution / packaging
10+
.Python
11+
build/
12+
develop-eggs/
13+
dist/
14+
downloads/
15+
eggs/
16+
.eggs/
17+
lib/
18+
lib64/
19+
parts/
20+
sdist/
21+
var/
22+
wheels/
23+
share/python-wheels/
24+
*.egg-info/
25+
.installed.cfg
26+
*.egg
27+
MANIFEST
28+
29+
# PyInstaller
30+
# Usually these files are written by a python script from a template
31+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
32+
*.manifest
33+
*.spec
34+
35+
# Installer logs
36+
pip-log.txt
37+
pip-delete-this-directory.txt
38+
39+
# Unit test / coverage reports
40+
htmlcov/
41+
.tox/
42+
.nox/
43+
.coverage
44+
.coverage.*
45+
.cache
46+
nosetests.xml
47+
coverage.xml
48+
*.cover
49+
*.py,cover
50+
.hypothesis/
51+
.pytest_cache/
52+
cover/
53+
54+
# Translations
55+
*.mo
56+
*.pot
57+
58+
# Django stuff:
59+
*.log
60+
local_settings.py
61+
db.sqlite3
62+
db.sqlite3-journal
63+
64+
# Flask stuff:
65+
instance/
66+
.webassets-cache
67+
68+
# Scrapy stuff:
69+
.scrapy
70+
71+
# Sphinx documentation
72+
docs/_build/
73+
74+
# PyBuilder
75+
.pybuilder/
76+
target/
77+
78+
# Jupyter Notebook
79+
.ipynb_checkpoints
80+
81+
# IPython
82+
profile_default/
83+
ipython_config.py
84+
85+
# pyenv
86+
# For a library or package, you might want to ignore these files since the code is
87+
# intended to run in multiple environments; otherwise, check them in:
88+
# .python-version
89+
90+
# pipenv
91+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
93+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
94+
# install all needed dependencies.
95+
#Pipfile.lock
96+
97+
# poetry
98+
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
99+
# This is especially recommended for binary packages to ensure reproducibility, and is more
100+
# commonly ignored for libraries.
101+
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
102+
#poetry.lock
103+
104+
# pdm
105+
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
106+
#pdm.lock
107+
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
108+
# in version control.
109+
# https://pdm.fming.dev/#use-with-ide
110+
.pdm.toml
111+
112+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
113+
__pypackages__/
114+
115+
# Celery stuff
116+
celerybeat-schedule
117+
celerybeat.pid
118+
119+
# SageMath parsed files
120+
*.sage.py
121+
122+
# Environments
123+
.env
124+
.venv
125+
env/
126+
venv/
127+
ENV/
128+
env.bak/
129+
venv.bak/
130+
131+
# Spyder project settings
132+
.spyderproject
133+
.spyproject
134+
135+
# Rope project settings
136+
.ropeproject
137+
138+
# mkdocs documentation
139+
/site
140+
141+
# mypy
142+
.mypy_cache/
143+
.dmypy.json
144+
dmypy.json
145+
146+
# Pyre type checker
147+
.pyre/
148+
149+
# pytype static type analyzer
150+
.pytype/
151+
152+
# Cython debug symbols
153+
cython_debug/
154+
155+
# PyCharm
156+
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
157+
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
158+
# and can be added to the global gitignore or merged into this file. For a more nuclear
159+
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
160+
#.idea/
161+
162+
### Python Patch ###
163+
# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
164+
poetry.toml
165+
166+
# ruff
167+
.ruff_cache/
168+
169+
# LSP config files
170+
pyrightconfig.json
171+
172+
173+
.vscode

‎.pylintrc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
[MAIN]
2+
3+
ignore =
4+
build,
5+
__pycache__,
6+
.tox,
7+
tests
8+
9+
[MESSAGES CONTROL]
10+
11+
disable =
12+
missing-module-docstring,
13+
too-few-public-methods

‎LICENSE‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Copyright <YEAR> <COPYRIGHT HOLDER>
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4+
5+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6+
7+
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
8+

‎MANIFEST.in‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
include requirements.txt
2+
include README.md
3+
include example_plugin/backends.txt #change it to your plugin folder

‎README.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Quantum Server Plugin
2+
3+
4+
![Build, Test and publish](https://github.com/quantum-plugins/quantum-server-plugin-template/actions/workflows/build_test_publish.yml/badge.svg)
5+
![release version](https://github.com/quantum-plugins/quantum-server-plugin-template/actions/workflows/release.yml/badge.svg)
6+
7+
To create a plugin for [local-quantum-server](https://github.com/Dpbm/local-quantum-server), `start by using this template` and then follow the steps below.
8+
9+
## Setup your plugin
10+
11+
1. Setup your `requirements.txt`
12+
13+
In your plugin, you'll probably need some external dependencies, like `qiskit`, `cirq`, `pennylane`, `numpy`, etc. List every required dependency inside the [requirements.txt file](./requirements.txt), line by line.
14+
15+
2. Create a virtual environment
16+
17+
To keep your work clean, make sure to use a virtual environment, this way your work won't get conflicted with pre-installed system dependencies.
18+
19+
Also, using environment managers allows you to easily change python versions. By default I'm using the `python 3.12.8`, however it maybe not the perfect match for your plugin. So remember to change it and explicit it on your project.
20+
21+
3. Add your code
22+
23+
After that, update the folder [example_plugin](./example_plugin/) to your plugin's name and start adding your code.
24+
25+
`Note: Make sure your folder name is the same as the plugin's name on setup.py.`
26+
27+
Inside [example_plugin](./example_plugin/) directory, you'll find some files:
28+
29+
- [interface.py](./example_plugin/interface.py): that's the file that creates the abstract class `Plugin`, which your project must use to ensure the correct usability.
30+
Don't change this file. Only `import` the `types`, `classes` and `functions` you need.
31+
- [plugin.py](./example_plugin/plugin.py): that's the plugin starting point. In it, you need to add some logic to handle the user input inside the `execute` method. By default, the class uses some decorators to ensure that only correct values are passed (backend name, result type and qasm file (check if it exists)). However, you're free to implement your logic and do further checks.
32+
- [backends.txt](./example_plugin/backends.txt): this file, is responsible to store the list of backends your plugin support. Make sure to clean that and add the names line by line. Don't delete this file.
33+
- [config.py](./example_plugin/config.py): that's the python file that keeps all the plugin configs. Please, don't change it.
34+
35+
Besides that, you're allowed to add new files and create your structure. But, keep in mind that, more complex projects may need additional configurations on either [setup.py](./setup.py) or [pyproject.toml](./pyproject.toml).
36+
37+
Also, you need to ensure the correct handling of the `result_types`, the possible inputs are: `'quasi_dist', 'counts', 'expval'` for now. `counts` and `quasi_dists` must return a `dict` and `expval` a `list of float`.
38+
39+
4. Add tests
40+
41+
Inside [tests directory](./tests/) add your tests using pytest. Although it's not mandatory, it's a nice practice to make your project easier to manipulate.
42+
43+
By default, `tox` is configured to run lint and type checks, as well as code tests. so remember to install the `dev-dependencies` and run tox:
44+
45+
```bash
46+
pip install -r dev-requirements.txt
47+
tox
48+
```
49+
50+
5. Update the [setup.py](./setup.py)
51+
52+
With your code done, start adding your info to [setup.py](./setup.py). If you have a more complex structure, you may need to add more configurations to that, so remember to check the [setuptools guide](https://setuptools.pypa.io/en/latest/index.html).
53+
54+
Also, take a look into [Manifest.in](./MANIFEST.in) and change the required lines.
55+
56+
6. Update the [LICENSE](./LICENSE)
57+
58+
The License for plugins is always `MIT`. So before proceeding, remember to update the [LICENSE file](./LICENSE) adding the year and your name.
59+
60+
6. Update the [README.md file](./README.md)
61+
62+
Doing that, delete everything in this very `README.md` file and describe your project.
63+
64+
7. Update GH Actions workflow
65+
66+
To be an accepted plugin, your must have your code on github. Due to that, it's possible to run some CI workflows to ensure you're code is correct and ready to be distributed.
67+
68+
So, to do that, go to [.github/workflows/build_test_publish.yml](./.github/workflows/build_test_publish.yml) and them ensure to update what's being required inside.
69+
70+
For plugins, every time it's pushed to the main branch, the code is built, tested and them published to PYPI automatically. To ensure that everything is going to go well, create and account at [pypi.org](https://pypi.org/) and setup a [Trusted publisher](https://docs.pypi.org/trusted-publishers/) mapping to your github workflow.
71+
72+
It's not mandatory publishing it to PYPI, but it's a nice way to share it abroad. If you don't want this part, remove the `publish` job from [.github/workflows/build_test_publish.yml](./.github/workflows/build_test_publish.yml) workflow.
73+
74+
8. Request your plugin to be added to the list
75+
76+
After that, open an issue on [github.com/quantum-plugins/plugins-list](https://github.com/quantum-plugins/plugins-list) requesting your plugin to be added on the official plugins list.
77+
78+
As soon as possible we'll see that and procede with the addition and your plugins will be called official 😊
79+
80+
## CONGRATS!!!
81+
82+
Now, you have a quantum plugin!!!!
83+
84+
Thank you so much for joining this amazing community🎉🎉🎉

‎dev-requirements.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
black
2+
pylint
3+
tox
4+
mypy
5+
setuptools
6+
types-setuptools
7+
pytest

‎example_plugin/__init__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
from .plugin import Plugin
2+
3+
__all__ = ["Plugin"]

‎example_plugin/backends.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Name the backends you have line by line

0 commit comments

Comments
 (0)