{"id":38766321,"url":"https://github.com/blues/notehub-py","last_synced_at":"2026-01-17T12:00:57.096Z","repository":{"id":237960718,"uuid":"795151903","full_name":"blues/notehub-py","owner":"blues","description":"Python-based library for accessing the Blues Notehub API.","archived":false,"fork":false,"pushed_at":"2026-01-14T21:11:14.000Z","size":1880,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-14T23:26:03.028Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blues.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-05-02T17:25:51.000Z","updated_at":"2025-12-22T19:06:58.000Z","dependencies_parsed_at":"2026-01-14T21:06:11.460Z","dependency_job_id":null,"html_url":"https://github.com/blues/notehub-py","commit_stats":null,"previous_names":["blues/notehub-py"],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/blues/notehub-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blues%2Fnotehub-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blues%2Fnotehub-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blues%2Fnotehub-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blues%2Fnotehub-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blues","download_url":"https://codeload.github.com/blues/notehub-py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blues%2Fnotehub-py/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28508464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T11:50:55.898Z","status":"ssl_error","status_checked_at":"2026-01-17T11:50:55.569Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T12:00:32.490Z","updated_at":"2026-01-17T12:00:56.944Z","avatar_url":"https://github.com/blues.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blues Notehub Py\n\n![Python Version Support](https://img.shields.io/pypi/pyversions/notehub-py)\n![PyPI Version](https://img.shields.io/pypi/v/notehub-py)\n![Wheel Support](https://img.shields.io/pypi/wheel/notehub-py)\n\nThe notehub-py library is a Python implementation for communicating with the [Blues Notehub API](https://dev.blues.io/reference/notehub-api/api-introduction/)\ngenerated by the [OpenAPI Generator](https://openapi-generator.tech) tool.\n\nThis library is auto-generated via the `openapi.yaml` file from the Blues Wireless Notehub project and published\nto [PyPI](https://pypi.org/project/notehub-py/) for ease of use in Python-based projects that need to interact with [Notehub.io][notehub].\n\n## Table of Contents \n\n- [Blues Notehub Py](#blues-notehub-py)\n  - [Table of Contents](#table-of-contents)\n  - [Package Installation](#package-installation)\n  - [Usage](#usage)\n  - [Sample Code](#sample-code)\n  - [Library Documentation and Code Examples](#library-documentation-and-code-examples)\n  - [Project Structure](#project-structure)\n    - [High Level Project Overview](#high-level-project-overview)\n    - [Root Folder](#root-folder)\n    - [`src/` Folder](#src-folder)\n  - [Repo Usage](#repo-usage)\n    - [Initial Project Setup and Dependencies](#initial-project-setup-and-dependencies)\n    - [Modifying the Project](#modifying-the-project)\n    - [Updating the Auto-Generated notehub-py Package](#updating-the-auto-generated-notehub-py-package)\n    - [Testing the Package Locally](#testing-the-package-locally)\n  - [Generate and Publish the Notehub API Python SDK to PyPI](#generate-and-publish-the-notehub-api-python-sdk-to-pypi)\n    - [Steps to Publish an Updated notehub\\_py Package to PyPI](#steps-to-publish-an-updated-notehub_py-package-to-pypi)\n  - [Contributing](#contributing)\n    - [Resources](#resources)\n  - [To learn more about Blues, the Notecard and Notehub, see:](#to-learn-more-about-blues-the-notecard-and-notehub-see)\n  - [License](#license)\n\n\n## Package Installation\n\nWith `pip` via PyPy:\n\n```bash\npython3 -m pip install notehub-py\n```\n\nor\n\n```bash\npython3 -m pip3 install notehub-py\n```\n\n## Usage\n\nOnce the package is installed, you can import it into a Python file using `import`.\n\n```python\nimport notehub_py\n```\n\n## Sample Code\n\nHere's an example script to fetch all the devices associated with a Notehub project.\n\nThe `access_token` variable declared below is a Personal Access Token (PAT) required for all Notehub API requests.\n\n**Creating a Personal Access Token**\n\nTo create a PAT:\n\n1. Sign into [Notehub](https://notehub.io)\n2. Select \"API Access\" from the user menu\n3. Click \"Create New Token\"\n4. Name the token and set an expiration date\n5. Copy the generated token immediately (it won't be shown again)\n\nPersonal Access Tokens have the same permissions as your Notehub user account and should be stored securely like passwords. For more details, see the [Notehub API documentation on Personal Access Tokens](https://dev.blues.io/api-reference/notehub-api/api-introduction/#authentication-with-personal-access-tokens).\n\nOnce you have your PAT, supply it to the library by setting it equal to: `access_token = os.environ[\"BEARER_TOKEN\"]` in the code.\n\n\u003e **NOTE:** Be aware that all Notehub API calls made using the Notehub Py library utilize your account's [Consumption Credits](https://dev.blues.io/reference/glossary#consumption-credit) (CCs). For more information, please consult our [pricing page](https://blues.com/pricing/).\n\n```python\nimport notehub_py\nfrom notehub_py.rest import ApiException\nfrom pprint import pprint\n\n# Defining the host is optional and defaults to https://api.notefile.net\nconfiguration = notehub_py.Configuration(\n    host = \"https://api.notefile.net\"\n)\n\n# Configure Bearer authorization: personalAccessToken\nconfiguration = notehub_py.Configuration(\n    access_token = os.environ[\"BEARER_TOKEN\"]\n)\n\n# Enter a context with an instance of the API client\nwith notehub_py.ApiClient(configuration) as api_client:\n    # Create an instance of the API class\n    api_instance = notehub_py.DeviceApi(api_client)\n    project_or_product_uid = 'app:00000000-0000-0000-0000-000000000000' # str |\n    device_uid = 'dev:000000000000000' # str |\n\n    try:\n        api_response = api_instance.get_device(project_or_product_uid, device_uid)\n        print(\"The response of DeviceApi-\u003eget_device:\\n\")\n        pprint(api_response)\n    except Exception as e:\n        print(\"Exception when calling DeviceApi-\u003eget_device: %s\\n\" % e)\n```\n\n## Library Documentation and Code Examples\n\nIf 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.\n\nEach API (device, event, fleet, etc.) had a `.md` file displaying:\n\n* All the HTTP methods it supports,\n* A full URL string of what the HTTP request looks like (including required and optional parameters),\n* An example of how to implement the code for a particular method inside of a Python file,\n* A sample return type from a particular method,\n* Required authorization to access the method.\n\n## Project Structure\n\nAs this project is partially generated via the OpenAPI Generator tool, it has a rather unique structure and some important files to be aware of.\n\n### High Level Project Overview\n\n```plaintext\n.\n├── .github/\n│   └── workflows/\n│       └── create-pr.yml\n│       └── publish-pypi.yml\n├── lib_template/\n│   └── python library template files\n├── src/\n│   ├── notehub_py/\n│   │   └── Python-based API and model files\n│   ├── docs/\n│   │   └── MD documentation\n│   ├── test/\n│   │   └── unit tests\n│   ├── dist/\n│   │   └── bundled .tar and .whl binaries for PyPI\n│   ├── pyproject.toml\n│   ├── requirements.txt\n│   └── setup.py\n├── openapi.yaml\n├── config.json\n├── README.md\n└── scripts.py\n```\n\n### Root Folder\n\nFiles and folders to be aware of in the root of the project.\n\n- The [`.github/`](.github/) folder holds the GitHub Actions workflows that automate common tasks in the repo. Key workflows include:\n\n  - `create-pr.yml` - Workflow to create new PR for review when `openapi.yaml` file is updated.\n  - `publish-pypi.yml` - Production workflow for publishing to PyPI via trusted publishing\n  \n  See the [Modifying the Project](#modifying-the-project) section for further information.\n\n- The [`openapi.yaml`](openapi.yaml) is 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.\n\n- The [`lib_template/`](/lib_template/) folder is the Python library template that the OpenAPI generator uses to generate the `src/` folder where auto-generated Python library is created.\n\n\u003e **NOTE:** In many scenarios, downloading the OpenAPI Generator library template is not necessary, but there were some [minor modifications](https://openapi-generator.tech/docs/templating/#modifying-templates) 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.\n\n- The [`config.json`](config.json) file 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.\n\n- The [`scripts.py`](scripts.py) file 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.\n\n### `src/` Folder\n\nThe `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:\n\n- The [`docs/`](src/docs/) folder documenting how to access the API endpoints via the library,\n- The internal [`notehub_py/`](src/notehub_py/) folder that holds the Python-based `api` and `model` files for each endpoint,\n- The [`test/`](src/test/) folder for unit tests,\n- And the `dist/` folder that contains the packaged up `.tar` file (source distribution) and `.whl` file (built distribution) that are uploaded to PyPI.\n\n\u003e **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.\n\n## Repo Usage\n\nInstructions for how to modify or run this project locally.\n\n### Initial Project Setup and Dependencies \n\nThis project requires [Python v3](https://www.python.org/downloads/) runtime, [pip](https://pypi.org/project/pip/), and the [OpenAPI Generator CLI Tool](https://openapi-generator.tech/).\n\nFollow the installation instructions for Python and pip, and see the note about globally installing the OpenAPI generator CLI below.\n\n\u003e **NOTE:** For best results, it's recommended to install the OpenAPI Generator CLI Tool globally through the terminal.\n\n```bash\nnpm install @openapitools/openapi-generator-cli -g\n```\n\nNow you should be ready to work with the package locally or make changes and modifications.\n\n### Modifying the Project\n\nMost of the files stored at the root of this project should require little to no modifications.\n\nThe [`lib_template`](lib_template/) folder holds the Python generator template files the OpenAPI Generator tool relies upon to build its library in the `src/` folder.\n\nThe [`.github/`](.github/) folder holds a set of GitHub Actions workflows that automate common tasks like [creating PRs](.github/workflows/create-pr.yml) out of new branches and publishing new releases to PyPI. All PyPI publishes use trusted publishing with OIDC for enhanced security.\n\nThe [`openapi.yaml`](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][notehub] 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.\n\nThe [`config.json`](config.json) file is the one that will require changes before a new version of the package is published to PyPI. The [next section](#updating-the-auto-generated-notehub-py-package) will elaborate further.\n\n### Updating the Auto-Generated notehub-py Package\n\nWhen 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](https://github.com/features/actions).\n\nWhen this occurs, it's time to regenerate the notehub-py Python package based on the newly updated `openapi.yaml`.\n\n**To regenerate the notehub_py package:**\n\n1. Git clone the repo from GitHub.\n\n```shell\n$ git clone git@github.com:blues/notehub-py.git\n```\n\n2. Check out the newly created remote branch from GitHub locally. (It will be named something like `feat-XYZ`.)\n3. Update the `config.json` file at the project's root so the `packageVersion` parameter is incremented (please follow [semantic versioning](https://semver.org/) practices here).\n4. At the root of the project, run the following script command from your terminal:\n\n```shell\n$ python3 scripts.py generate_and_format\n```\n\nThis command will run the following subcommands:\n\n- `remove_deprecated_parameters` - This 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.\n- `generate_package` - This kicks 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).\n- `format_code` - This runs the Prettier formatter on the markdown docs, and the Black formatter on the Python docs within the new `src/` directory to make them look nice.\n- `build_distro_package` - This builds the distribution package that will be published to PyPI.\n\n1. Once all of these steps have successfully run, you'll be ready to merge the change to `main` and publish on PyPI.\n\n\u003e **NOTE:** If you'd like more information about what exactly the `generate_package` script is doing with its OpenAPI generator CLI commands, you can see the documentation for them [here](https://openapi-generator.tech/docs/usage/).\n\n### Testing the Package Locally\n\nIf 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:\n\n```bash\ncd src/ # \u003c---- path to folder where you want to test the local notehub_py SDK package\npython3 -m venv .venv\nsource ./.venv/bin/activate # \u003c---- path to the script to Activate the Python virtual environment may vary\npip3 install -r requirements.txt\n```\n\nOnce the dependencies are installed, import the library using `import` code and test it out.\n\n```python\nimport notehub_py\n\n# some more code here\n```\n\nAll of these directions are also available in the auto-generated [`README.md`](src/README.md) in the `src/` folder as well, for reference.\n\n\u003e **NOTE:** Even testing locally, you will need a Personal Access Token (this is the 'access_token' referenced in the code examples). See [these directions](https://dev.blues.io/api-reference/notehub-api/api-introduction/#authentication-with-personal-access-tokens) on the Blues Developer Experience site to generate one.\n\n## Generate and Publish the Notehub API Python SDK to PyPI\n\nAlthough 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.\n\nRun 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.\n\n### Steps to Publish an Updated notehub_py Package to PyPI\n\n1. Update the `\"packageVersion\"` in the `config.json` file. Follow [semantic versioning](https://semver.org/) for this.\n2. Run the all-in-one command that removes the deprecated query params from the original `openapi.yaml` file, generates a fresh version of the package, formats the auto generated files with black and Prettier, and then builds the distro packages for the PyPI package repository.\n\n```bash\npython3 scripts.py generate_and_format\n```\n\n\u003e **NOTE:** This convenience command can be done in separate steps if you prefer. Just run the following steps in order from the command line.\n\u003e \n\u003e  1. Create a new copy of the `openapi_filtered.yaml` file that removes all deprecated query params from the original `openapi.yaml` file.\n\u003e \n\u003e ```bash\n\u003e python3 scripts.py remove_deprecated_parameters\n\u003e ```\n\u003e\n\u003e 2. Generate the new version of the package.\n\u003e\n\u003e ```bash\n\u003e python3 scripts.py generate_package\n\u003e ```\n\u003e\n\u003e 3. Format the auto generated docs in the SDK folder with Prettier\n\u003e\n\u003e ```bash\n\u003e python3 scripts.py run_prettier_on_docs\n\u003e ```\n\u003e\n\u003e 4. Format the auto generated Python in the SDK folder with black\n\u003e\n\u003e ```bash\n\u003e python3 scripts.py run_black_on_python\n\u003e ```\n\u003e\n\u003e 5. Rebuild the distribution packages for the PyPI package repository.\n\u003e\n\u003e ```bash\n\u003e python3 scripts.py build_distro_package\n\u003e ```\n\n1. 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](CONTRIBUTING.md) for further details around a good PR and commit messages.\n2. Get the PR approved and merged to `main`.\n3. Create a new release with a tag following the [semantic versioning](https://semver.org/) 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.\n\n## Contributing\n\nWe love issues, fixes, and pull requests from everyone. By participating in this project, you agree to abide by\nthe Blues Inc. [code of conduct].\n\nFor details on contributions we accept and the process for contributing, see our\n[contribution guide](CONTRIBUTING.md).\n\n### Resources\n\n- [Contributing guide](CONTRIBUTING.md)\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n\n## To learn more about Blues, the Notecard and Notehub, see:\n\n- [blues.com][blues]\n- [notehub.io][notehub]\n- [Blues Developer Experience Site][blues.dev]\n\n## License\n\nCopyright (c) 2024 Blues Inc. Released under the MIT license. See\n[LICENSE](LICENSE) for details.\n\n[blues]: https://blues.com\n[blues.dev]: https://blues.dev\n[code of conduct]: https://blues.github.io/opensource/code-of-conduct\n[notehub]: https://notehub.io","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblues%2Fnotehub-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblues%2Fnotehub-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblues%2Fnotehub-py/lists"}