{"id":20109774,"url":"https://github.com/hyper63/hyper-connect-py","last_synced_at":"2025-11-27T09:04:47.250Z","repository":{"id":37904751,"uuid":"491118608","full_name":"hyper63/hyper-connect-py","owner":"hyper63","description":null,"archived":false,"fork":false,"pushed_at":"2023-02-22T17:58:49.000Z","size":1441,"stargazers_count":1,"open_issues_count":8,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-14T09:48:39.427Z","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyper63.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.MD","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"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}},"created_at":"2022-05-11T13:16:26.000Z","updated_at":"2022-06-08T18:00:31.000Z","dependencies_parsed_at":"2025-01-13T05:40:31.403Z","dependency_job_id":"31ee0646-85d7-4bef-b5b6-29e0a2f2430b","html_url":"https://github.com/hyper63/hyper-connect-py","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyper63%2Fhyper-connect-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyper63%2Fhyper-connect-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyper63%2Fhyper-connect-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyper63%2Fhyper-connect-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyper63","download_url":"https://codeload.github.com/hyper63/hyper-connect-py/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241550015,"owners_count":19980639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2024-11-13T18:09:23.969Z","updated_at":"2025-11-27T09:04:47.127Z","avatar_url":"https://github.com/hyper63.png","language":"Python","readme":"\u003ch1 align=\"center\"\u003e🐍 hyper-connect 🐍\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n\u003ccode\u003ehyper-connect\u003c/code\u003e is the python SDK package for \u003ca href=\"https://hyper.io\"\u003ehyper\u003c/a\u003e.\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\nOfficial hyper \u003ca href=\"https://docs.hyper.io\"\u003edocumentation\u003c/a\u003e.\n\u003c/p\u003e\n\n- [Install](#install)\n- [Usage](#usage)\n- [Services and Actions](#services-and-actions)\n- [hyper vision 😎](#hyper-vision-😎)\n- [Types and type checking](#types-and-type-checking)\n- [Examples](#examples)\n- [Synchronous and asynchronous support](#synchronous-and-asynchronous-support)\n- [Async examples](#async-examples)\n- [Contributing](#contributing)\n- [License](#license)\n- [Code of Conduct](#code-of-conduct)\n- [Linting](#linting)\n- [Tests](#tests)\n- [Tag and Release](#tag-and-release)\n- [Build](#build)\n- [Publishing to TestPyPI](#publishing-to-testpypi)\n- [Publishing to PyPI](#publishing-to-pypi)\n\n## Install\n\nThe following command will install the latest version of the `hyper-connect` module and its dependencies from the Python Packaging Index (PyPI):\n\n```\npip install hyper-connect\n```\n\n## Usage\n\n`hyper-connect` wraps a hyper app's REST API, generating a short-lived JWT using a [connection string](https://docs.hyper.io/app-keys) from one of your hyper app's app keys.\n\n`hyper-connect` supports both synchronous and asynchronous calls.\n\nOnce you've created an environment variable named `HYPER` with the value of a connection string, you're ready to make a call to the `connect` function which returns a `Hyper` object:\n\n\n```py\nfrom hyper_connect import connect\nfrom hyper_connect.types import Hyper\nfrom dotenv import dotenv_values\nfrom typing import Dict\n\nconfig = dotenv_values(\"./.env\")\n\nconnection_string: str = str(config[\"HYPER\"])\nhyper: Hyper = connect(connection_string)\n\nmovie: Dict = {\n    \"_id\": \"movie-4000\",\n    \"type\": \"movie\",\n    \"title\": \"Back to the Future\",\n    \"year\": \"1985\",\n}\n\nresult = hyper.data.add(movie)\nprint(\"hyper.data.add result --\u003e \", result)\n# hyper.data.add result --\u003e  {'id': 'movie-4000', 'ok': True, 'status': 201}\n```\n\n## Services and Actions\n\nhyper is a suite of service apis, with hyper connect you can specify the API you want to connect with and the action you want to perform.\nhyper.[service].[action] - with each service there are a different set of actions to call. This table breaks down the service and action with description of the action.\n\n### data\n\n| Service | Action | Description                                                         |\n| ------- | ------ | ------------------------------------------------------------------- |\n| data    | add    | creates a json document in the hyper data store                     |\n| data    | list   | lists the documents given a start,stop,limit range                  |\n| data    | get    | retrieves a document by id                                          |\n| data    | update | updates a given document by id                                      |\n| data    | remove | removes a document from the store                                   |\n| data    | query  | queries the store for a set of documents based on selector criteria |\n| data    | index  | creates an index for the data store                                 |\n| data    | bulk   | inserts, updates, and removed document via a batch of documents     |\n\n### cache\n\n| Service | Action | Description                                                         |\n| ------- | ------ | ------------------------------------------------------------------- |\n| cache   | add    | creates a json document in the hyper cache store with a key         |\n| cache   | get    | retrieves a document by key                                         |\n| cache   | set    | sets a given document by key                                        |\n| cache   | remove | removes a document from the cache                                   |\n| cache   | query  | queries the cache for a set of documents based on a pattern matcher |\n\n### search\n\n| Service | Action | Description                                       |\n| ------- | ------ | ------------------------------------------------- |\n| search  | add    | indexes a json document in the hyper search index |\n| search  | get    | retrieves a document from index                   |\n| search  | update | updates a document in the hyper search index      |\n| search  | remove | removes a document from the index                 |\n| search  | query  | searches index by text                            |\n| search  | load   | loads a batch of documents                        |\n\n### storage\n\n| Service | Action   | Description                              |\n| ------- | -------- | ---------------------------------------- |\n| storage | upload   | adds object/file to hyper storage bucket |\n| storage | download | retrieves a object/file from bucket      |\n| storage | remove   | removes a object/file from the bucket    |\n\n### queue\n\n| Service | Action  | Description                                                |\n| ------- | ------- | ---------------------------------------------------------- |\n| queue   | enqueue | posts object to queue                                      |\n| queue   | errors  | gets list of errors occured with queue                     |\n| queue   | queued  | gets list of objects that are queued and ready to be sent. |\n\n\n## hyper vision 😎\n\n[hyper vision](https://docs.hyper.io/hyper-vision) is a UI dev tool to browse hyper cloud data, cache, search, etc. via an app key's connection string.  It is available at https://vision.hyper.io/.\n\n![hyper vision cache](./hyper-vision.png)\n\n\n## Types and type checking\n\nCommon types you'll encounter include `HYPER`, `ListOptions`, `QueryOptions`, and `SearchQueryOptions`.\n\n```py\nfrom hyper_connect import connect\nfrom hyper_connect.types import Hyper, ListOptions, QueryOptions, SearchQueryOptions\n```\n\nThe SDK performs runtime type checking on the arguments passed into methods and functions, as well as, the return value.\n\nPassing incorrect types will cause a `TypeError` to be raised:\n\n\n```py\ndef data_list_bad_keys_sync(self):\n    options: ListOptions = {\n        \"startkey\": None,\n        \"limit\": None,\n        \"endkey\": None,\n        \"keys\": 6,\n        \"descending\": None,\n    }\n\n    try:\n        result = hyper.data.list(options)\n    except TypeError as err:\n        print('data_list_bad_keys_sync TypeError -\u003e ', err)\n        # data_list_bad_keys_sync TypeError -\u003e type of dict item \"params\" for argument \"req_params\" must be one of (hyper_connect.types._types.ListOptions, hyper_connect.types._types.QueryOptions, Dict[str, str], NoneType); got dict instead\n\n```\n\nSome keys within `ListOptions`, `QueryOptions`, and `SearchQueryOptions` are optional.  For example both of the following typed Dictionaries are valid types:\n\n```py\nvalid_data_list_options: ListOptions = {\n    \"startkey\": \"book-000105\",\n    \"limit\": None,\n    \"endkey\": \"book-000106\",\n    \"keys\": None,\n    \"descending\": None,\n}\n\nalso_valid_options: ListOptions = {\n    \"startkey\": \"book-000105\",\n    \"endkey\": \"book-000106\"\n}\n```\n\n\n## Examples\n\nSee **[examples.py](https://github.com/hyper63/hyper-connect-py/blob/main/examples.py)**\n\n## Synchronous and asynchronous support\n\n`hyper_connect` supports both synchronous and asynchronous methods for each service type (data, cache, storage, etc.).  It's easy to distinguish between the two.  Synchronous method names will **not** end in `_async`.\n\n```py\nresult = hyper.data.add(movie)\n```\n\nWhile asynchronous methods end in `_async`:\n\n```py\nresult = await hyper.data.add_async(movie)\n```\n\n\u003e Async can be a little tricky.  Here are a couple of good resources to help avoid the pitfalls 😵‍💫:\n\u003e [How to Create an Async API Call with asyncio](https://www.youtube.com/watch?v=t0JXiljpNRo) and\n\u003e [Common Mistakes Using Python3 asyncio](https://xinhuang.github.io/posts/2017-07-31-common-mistakes-using-python3-asyncio.html)\n\n\n- You must use the `async` and `await` syntax:\n\n    ```py\n    async def data_add():\n\n        movie: Dict = {\n            \"_id\": \"movie-5000\",\n            \"type\": \"movie\",\n            \"title\": \"Back to the Future 2\",\n            \"year\": \"1987\",\n        }\n\n        result: IdResult = await hyper.data.add_async(movie)\n        print(\"hyper.data.add_async result --\u003e \", result)\n        # hyper.data.add_async result --\u003e  {'id': 'movie-4000', 'ok': True, 'status': 201}\n    ```\n\n- To run your asyncronous function, use [`asyncio`](https://docs.python.org/3/library/asyncio.html) which is a library to write concurrent code using the async/await syntax:\n\n    ```py\n    from examples_async import data_add\n    import asyncio\n    asyncio.run(data_add())\n\n    # hyper.data.add result --\u003e  {'id': 'movie-5000', 'ok': True, 'status': 201}\n    ```\n\n- Calls to asynchronous methods return JS style promises.  Compose your Hyper services to create complex flows:\n\n    ```py\n    async def data_cache_compose():\n        movie: Dict = {\n            \"_id\": \"movie-5001\",\n            \"type\": \"movie\",\n            \"title\": \"Back to the Future 3\",\n            \"year\": \"1989\",\n        }\n\n        result = await hyper.data.add_async(movie).then(\n            lambda _: hyper.cache.add_async(\n                key=movie[\"_id\"], value=movie, ttl=\"1d\"\n            )\n        )\n        print(\"hyper data and cache add result --\u003e \", result)\n        # hyper data and cache add_async result --\u003e  {'ok': True, 'status': 201}\n    ```\n\n## Async examples\n\nSee **[examples_async.py](https://github.com/hyper63/hyper-connect-py/blob/main/examples_async.py)**\n\n## Contributing\n\nInterested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.\n\nSee [Contributing](./CONTRIBUTING.md).\n\n## License\n\n`hyper_connect` was created by the hyper team. It is licensed under the terms of the Apache 2.0 license.\n\nSee [Licence](./LICENCE).\n\n## Code of Conduct\n\nSee [Code of Conduct](./CONDUCT.md)\n\n### Developer Setup\n\nWe prefer you use Gitpod.  Gitpod provides a fully initialized, perfectly set-up developer environmment for the hyper connect SDK.\n\n\u003e We recommend you [install the Gitpod browser extension](https://www.gitpod.io/docs/browser-extension) to make this a one-click operation.\n\n[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/tripott/hyper-connect-py-test)\n\n### Environment Variables\n\nIf you plan on running tests, you'll need to create an environment variable named `HYPER`.\n\n```bash\nHYPER=cloud://your app key:your app secret--gI1MkcrUqFPMR@cloud.hyper.io/express-quickstart\n```\n\nOne way to add an environment variable is to use a **.env** file.  Feel free to provide environment variables in a way that makes sense to you.\n\n- Create a **.env** file in the project root.\n- Within **.env**, create an environment variable named `HYPER` with a value of your hyper app's [connection string](https://docs.hyper.io/app-keys#nq-connection-string).\n\n\n## Linting\n\nWe use git pre-commit hooks, black, and isort to prettify the code and run static type checking with mypy.   See the **.pre-commit-config.yaml**.\n\nTo run these checks, execute the `make lint` command.\n\n## Tests\n\n\u003e Heads up! Integration tests assume a hyper app and services have been created.  See https://docs.hyper.io/applications for details on creating hyper applications and services.\n\nA storage service should have the following setup:\n\n![Search Service Config](search-svc-config.png)\n\nRun the `make test` script to run the unit and integration tests.\n\n## Tag and Release\n\nBump the semver value within **pyproject.toml**.  Create tag and push tag:\n\n```bash\n$ git tag v0.0.3\n$ git push --tags\n```\n\nNow if you go to the repository on GitHub and navigate to the “Releases” tab, you should see the new tag.\n\nCreate a release from the tag in GitHub.\n\n\u003e See https://py-pkgs.org/03-how-to-package-a-python#tagging-a-package-release-with-version-control\n\n## Build\n\nWe can easily create an sdist and wheel of a package with poetry using the command `poetry build`.  Both files are created in a directory named **dist/**.  Those two new files are the sdist and wheel for our package.\n\n```bash\n$ poetry build\n```\n\n\u003e See https://py-pkgs.org/03-how-to-package-a-python#building-your-package\n\n## Publishing to TestPyPI\n\nDo a “dry run” and check that everything works as expected by submitting to TestPyPi first.  `poetry` has a `publish` command, which we can use to do this, however the default behavior is to publish to PyPI. So we need to add TestPyPI to the list of repositories `poetry` knows about using the following command:\n\n```bash\n$ poetry config repositories.test-pypi https://test.pypi.org/legacy/\n```\n\nTo publish to TestPyPI we can use poetry publish (you will be prompted for your username and password for TestPyPI).\n\n```bash\n$ poetry publish -r test-pypi\n```\n\nNow we should be able to visit our package on TestPyPI: https://test.pypi.org/project/hyper-connect/\n\nWe can try installing our package using pip from the command line with the following command:\n\n```bash\n$ pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple hyper-connect\n```\n\n\u003e See https://py-pkgs.org/03-how-to-package-a-python#publishing-to-testpypi\n\n\n## Publishing to PyPI\n\nIf you were able to upload your package to TestPyPI and install it without error, you’re ready to publish your package to PyPI. You can publish to PyPI using the `poetry publish` command without any arguments:\n\n```bash\n$ poetry publish\n```\n\nYour package will then be available on PyPI (https://pypi.org/project/hyper-connect/) and can be installed by anyone using pip:\n\n\u003e See https://py-pkgs.org/03-how-to-package-a-python#publishing-to-pypi\n\n### COMING SOON: Verify Signature\n\nhyper Queue allows you to create a target web hook endpoint to receive jobs, in order to secure that endpoint to only receive jobs from hyper, you can implement a secret, this secret using sha256 to encode a `nounce` timestamp and a signature of the job payload. We created a function on `hyper_connect` to make it easier to implement your own middleware to validate these incoming jobs in a secure way.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyper63%2Fhyper-connect-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyper63%2Fhyper-connect-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyper63%2Fhyper-connect-py/lists"}