The notehub-py library is a Python implementation for communicating with the Blues Notehub API generated by the OpenAPI Generator tool.
This library is auto-generated via the openapi.yaml file from the Blues Wireless Notehub project and published
to PyPi for ease of use in Python-based projects that need to interact with Notehub.io.
- Blues Notehub Py
With pip via PyPy:
python3 -m pip install notehub-pyor
python3 -m pip3 install notehub-pyOnce the package is installed, you can import it into a Python file using import.
import notehub_pyHere's an example script to fetch all the devices associated with a Notehub project.
The token variable declared below is an X-SESSION-TOKEN authentication token required for all Notehub API requests.
It can be obtained by using the Notehub Py SDK to call the Notehub API's /auth/login endpoint via the notehub_py.AuthorizationApi method while supplying a Notehub username and password in the login_request object.
Then using the newly generated authentication token to whatever method the package needs, by setting it equal to: configuration.api_key['api_key'] = token.
NOTE: Be aware that all Notehub API calls made using the Notehub Py library utilize your account's Consumption Credits (CCs). For more information, please consult our pricing page.
import notehub_py
from notehub_py.rest import ApiException
from pprint import pprint
# Defining the host is optional and defaults to https://api.notefile.net
# See configuration.py for a list of all supported configuration parameters.
configuration = notehub_py.Configuration(
host = "https://api.notefile.net" #
)
with notehub_py.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = notehub_py.AuthorizationApi(api_client)
login_request = {"username":"name@example.com","password":"test-password"} # LoginRequest |
api_response = api_instance.login(login_request)
token = api_response.session_token
configuration.api_key['api_key'] = token
# Enter a context with an instance of the API client
with notehub_py.ApiClient(configuration) as api_client:
# Create an instance of the API class
device_api_instance = notehub_py.DeviceApi(api_client)
env_api_instance = notehub_py.DeviceApi(api_client)
project_uid = 'notehub-project-uid-goes-here' # str |
device_uid = 'dev:xxxxxxxxxxxxxxxx' # str |
page_size = 50 # int | (optional) (default to 50)
page_num = 1 # int | (optional) (default to 1)
api_response = device_api_instance.get_device(project_uid, device_uid)
print("The response of DevicesApi->get_project_device:\n")
pprint(api_response)If you want more information, code examples of how to use each of the Notehub API endpoints are located in the src/docs/ folder and available on the Blues Developer Experience site.
Each API (device, event, fleet, etc.) had a .md file displaying:
- All the HTTP methods it supports,
- A full URL string of what the HTTP request looks like (including required and optional parameters),
- An example of how to implement the code for a particular method inside of a Python file,
- A sample return type from a particular method,
- Required authorization to access the method.
As this project is partially generated via the OpenAPI Generator tool, it has a rather unique structure and some important files to be aware of.
.
├── .github/
│ └── workflows/
│ └── GH Action files
├── lib_template/
│ └── python library template files
├── src/
│ ├── notehub_py/
│ │ └── Python-based API and model files
│ ├── docs/
│ │ └── MD documentation
│ ├── test/
│ │ └── unit tests
│ ├── dist/
│ │ └── bundled .tar and .whl binaries for PyPi
│ ├── pyproject.toml
│ ├── requirements.txt
│ └── setup.py
├── openapi.yaml
├── config.json
├── README.md
└── scripts.py
Files and folders to be aware of in the root of the project.
-
The
.github/folder holds the GitHub Actions workflows that automate common tasks in the repo. See the Modifying the Project section for further information. -
The
openapi.yamlis a key player for this project: it provides the documentation of all the Notehub API endpoints that the OpenAPI Generator tool uses to build the library - without this file, the project doesn't exist. -
The
lib_template/folder is the Python library template that the OpenAPI generator uses to generate thesrc/folder where auto-generated Python library is created.
NOTE: In many scenarios, downloading the OpenAPI Generator library template is not necessary, but there were some minor modifications needed in the template's generation to make the package notes published in PyPi more user friendly. Being able to download and modify those files offered the fine-grained control needed when generating the Python library code.
-
The
config.jsonfile is a configuration file of additional properties used by the OpenAPI Generator and its Python library template to define certain variables like package name, version, etc. -
The
scripts.pyfile is a set of reusable commands to automate the steps of updating this repo and packaging it up for publishing a new version to PyPi.
The src/ folder inside the root of the project contains the contents of the auto-generated notehub_py package that is eventually published to PyPi, including:
- The
docs/folder documenting how to access the API endpoints via the library, - The internal
notehub_py/folder that holds the Python-basedapiandmodelfiles for each endpoint, - The
test/folder for unit tests, - And the
dist/folder that contains the packaged up.tarfile (source distribution) and.whlfile (built distribution) that are uploaded to PyPi.
NOTE: Do not modify the files in the
src/folder. These are all auto-generated by the OpenAPI Generator tool and the next time the generator command is run to update the library any manual changes will be overwritten.
Instructions for how to modify or run this project locally.
This project requires Python v3 runtime, pip, and the OpenAPI Generator CLI Tool.
Follow the installation instructions for Python and pip, and see the note about globally installing the OpenAPI generator CLI below.
NOTE: For best results, it's recommended to install the OpenAPI Generator CLI Tool globally through the terminal.
npm install @openapitools/openapi-generator-cli -gNow you should be ready to work with the package locally or make changes and modifications.
Most of the files stored at the root of this project should require little to no modifications.
The lib_template folder holds the Python generator template files the OpenAPI Generator tool relies upon to build its library in the src/ folder.
The .github/ folder holds a set of GitHub Actions workflows that automate common tasks like creating PRs out of new branches and publishing new releases to PyPi.
The openapi.yaml file is a copy of the one in the Notehub repo (a private Blues repository). Any time a new version of Notehub.io is deployed and the openapi.yaml file there is updated, a fresh copy of that file is added to this project in a new branch via a GitHub Actions workflow.
The config.json file is the one that will require changes before a new version of the package is published to PyPi. The next section will elaborate further.
When the openapi.yaml file is updated in the original Notehub repo which this library supports, the updated file is copied over into a new feature branch in this repo through the magic of GitHub Actions.
When this occurs, it's time to regenerate the notehub-py Python package based on the newly updated openapi.yaml.
To regenerate the notehub_py package:
- Git clone the repo from GitHub.
$ git clone git@github.com:blues/notehub-py.git- Check out the newly created remote branch from GitHub locally. (It will be named something like
feat-XYZ.) - Update the
config.jsonfile at the project's root so thepackageVersionparameter is incremented (please follow semantic versioning practices here). - At the root of the project, run the following script command from your terminal:
$ python3 scripts.py remove_deprecated_parametersThis command will make a copy of the openapi.yaml file named openapi_filtered.yaml which has removed any query parameters marked as deprecated from the openapi.yaml file. Removing these now deprecated params ensures the generated SDK docs and sample code is clear and up to date, and no longer has potentially confusing artifacts to trip up users.
- Still at the root of the project, run the following script command from your terminal:
$ python3 scripts.py generate_packageThis command will kick off the OpenAPI Generator tool to generate a new copy of the library inside of the src/ folder (using the newly updated openapi_filtered.yaml file), which can then be merged to the main repo branch and published to PyPi.
NOTE: If you'd like more information about what exactly the
generate_packagescript is doing with its OpenAPI generator CLI commands, you can see the documentation for them here.
If you'd like to test some changes you've made to the notehub-py API locally before submitting a new PR to the repo, follow steps 1 - 4 above and then use the following commands to migrate to the correct folder and install the dependencies locally:
cd src/ # <---- path to folder where you want to test the local notehub_py SDK package
python3 -m venv .venv
source ./.venv/bin/activate # <---- path to the script to Activate the Python virtual environment may vary
pip3 install -r requirements.txtOnce the dependencies are installed, import the library using import code and test it out.
import notehub_py
# some more code hereAll of these directions are also available in the auto-generated README.md in the src/ folder as well, for reference.
NOTE: Even testing locally, you will need an
X-SESSION-TOKEN(this is the 'api-key' referenced in the code examples). See these directions on the Blues Developer Experience site to generate one.
Although many of the processes around this repository are automated with GitHub Actions, publishing an updated version of the repo requires some human intervention as well.
Run the following commands from the notehub-py root directory in this order to make a new version of the openapi.yaml file ready to deploy to PyPi.
- Update the
"packageVersion"in theconfig.jsonfile. Follow semantic versioning for this. - Create a new copy of the
openapi_filtered.yamlfile that removes all deprecated query params from the originalopenapi.yamlfile.
python3 scripts.py remove_deprecated_parameters- Generate the new version of the package.
python3 scripts.py generate_package- Rebuild the distribution packages for the PyPi package repository.
python3 scripts.py build_distro_package- Commit and push the changes to a new branch in GitHub and open a new pull request when the branch is ready for review. See the contribution documentation for further details around a good PR and commit messages.
- Get the PR approved and merged to
main. - Create a new release with a tag following the semantic versioning style of [vX.X.X], click the "Generate release notes" button, and publish the release. For example: a new release with a tag named v1.0.2.
We love issues, fixes, and pull requests from everyone. By participating in this project, you agree to abide by the Blues Inc. code of conduct.
For details on contributions we accept and the process for contributing, see our contribution guide.
Copyright (c) 2024 Blues Inc. Released under the MIT license. See LICENSE for details.