| Name | h-api JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | https://github.com/hypothesis/h-api |
| Summary | Tools and components for calling the H API. |
| upload_time | 2023-08-09 12:53:35 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<a href="https://github.com/hypothesis/h-api/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/hypothesis/h-api/ci.yml?branch=main"></a>
<a href="https://pypi.org/project/h-api"><img src="https://img.shields.io/pypi/v/h-api"></a>
<a><img src="https://img.shields.io/badge/python-3.9 | 3.8-success"></a>
<a href="https://github.com/hypothesis/h-api/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-BSD--2--Clause-success"></a>
<a href="https://github.com/hypothesis/cookiecutters/tree/main/pypackage"><img src="https://img.shields.io/badge/cookiecutter-pypackage-success"></a>
<a href="https://black.readthedocs.io/en/stable/"><img src="https://img.shields.io/badge/code%20style-black-000000"></a>
# h-api
Tools and components for calling the H API.
This package is not likely to be of use to you
----------------------------------------------
Unless you work for Hypothesis, then this package is not going to be very
useful to you. Feel free to have a poke about, but don't be surprised if it
doesn't make much sense.
At the present time not only should you not use this package, our
authentication will also prevent it.
Usage
-----
To construct NDJSON for Bulk API calls:
```python
from h_api.enums import ViewType
from h_api.bulk_api import CommandBuilder, BulkAPI, Executor
nd_json = BulkAPI.to_string([
# It's your job to put the right commands here.
# This also accepts a generator
CommandBuilder.configure(
effective_user="acct:example@lms.hypothes.is",
total_instructions=4,
view=ViewType.BASIC),
CommandBuilder.user.upsert({
"username": "username",
"authority": "authority",
"display_name": "display_name",
"identities": [{
"provider": "provider",
"provider_unique_id": "provider_unique_id"
}],
}, "user_ref"),
CommandBuilder.group.upsert({
"name": "name",
"authority": "authority",
"authority_provided_id": "authority_provided_id"
}, "group_ref"),
# These references here match those we assigned to the objects above
CommandBuilder.group_membership.create("user_ref", "group_ref")
])
# It's now your job to send this off to H
```
To accept and process an NDJSON request like the above:
```python
class MyExectutor(Executor):
def execute_batch(self, command_type, data_type, default_config, batch):
"""Implement your insertion logic here and return Report Objects"""
rows = BulkAPI.from_byte_stream(http_streaming_body, executor=MyExectutor())
if rows:
# Turn each row into JSON and return to your caller
# You have to do this
```
## Setting up Your h-api Development Environment
First you'll need to install:
* [Git](https://git-scm.com/).
On Ubuntu: `sudo apt install git`, on macOS: `brew install git`.
* [GNU Make](https://www.gnu.org/software/make/).
This is probably already installed, run `make --version` to check.
* [pyenv](https://github.com/pyenv/pyenv).
Follow the instructions in pyenv's README to install it.
The **Homebrew** method works best on macOS.
The **Basic GitHub Checkout** method works best on Ubuntu.
You _don't_ need to set up pyenv's shell integration ("shims"), you can
[use pyenv without shims](https://github.com/pyenv/pyenv#using-pyenv-without-shims).
Then to set up your development environment:
```terminal
git clone https://github.com/hypothesis/h-api.git
cd h-api
make help
```
## Releasing a New Version of the Project
1. First, to get PyPI publishing working you need to go to:
<https://github.com/organizations/hypothesis/settings/secrets/actions/PYPI_TOKEN>
and add h-api to the `PYPI_TOKEN` secret's selected
repositories.
2. Now that the h-api project has access to the `PYPI_TOKEN` secret
you can release a new version by just [creating a new GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository).
Publishing a new GitHub release will automatically trigger
[a GitHub Actions workflow](.github/workflows/pypi.yml)
that will build the new version of your Python package and upload it to
<https://pypi.org/project/h-api>.
## Changing the Project's Python Versions
To change what versions of Python the project uses:
1. Change the Python versions in the
[cookiecutter.json](.cookiecutter/cookiecutter.json) file. For example:
```json
"python_versions": "3.10.4, 3.9.12",
```
2. Re-run the cookiecutter template:
```terminal
make template
```
3. Commit everything to git and send a pull request
## Changing the Project's Python Dependencies
To change the production dependencies in the `setup.cfg` file:
1. Change the dependencies in the [`.cookiecutter/includes/setuptools/install_requires`](.cookiecutter/includes/setuptools/install_requires) file.
If this file doesn't exist yet create it and add some dependencies to it.
For example:
```
pyramid
sqlalchemy
celery
```
2. Re-run the cookiecutter template:
```terminal
make template
```
3. Commit everything to git and send a pull request
To change the project's formatting, linting and test dependencies:
1. Change the dependencies in the [`.cookiecutter/includes/tox/deps`](.cookiecutter/includes/tox/deps) file.
If this file doesn't exist yet create it and add some dependencies to it.
Use tox's [factor-conditional settings](https://tox.wiki/en/latest/config.html#factors-and-factor-conditional-settings)
to limit which environment(s) each dependency is used in.
For example:
```
lint: flake8,
format: autopep8,
lint,tests: pytest-faker,
```
2. Re-run the cookiecutter template:
```terminal
make template
```
3. Commit everything to git and send a pull request
Raw data
{
"_id": null,
"home_page": "https://github.com/hypothesis/h-api",
"name": "h-api",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/4a/47/129b35ef4bb7dda521ad62bd91b0fdcdee341eba0b20231cd537b336e762/h-api-1.1.0.tar.gz",
"platform": null,
"description": "<a href=\"https://github.com/hypothesis/h-api/actions/workflows/ci.yml?query=branch%3Amain\"><img src=\"https://img.shields.io/github/actions/workflow/status/hypothesis/h-api/ci.yml?branch=main\"></a>\n<a href=\"https://pypi.org/project/h-api\"><img src=\"https://img.shields.io/pypi/v/h-api\"></a>\n<a><img src=\"https://img.shields.io/badge/python-3.9 | 3.8-success\"></a>\n<a href=\"https://github.com/hypothesis/h-api/blob/main/LICENSE\"><img src=\"https://img.shields.io/badge/license-BSD--2--Clause-success\"></a>\n<a href=\"https://github.com/hypothesis/cookiecutters/tree/main/pypackage\"><img src=\"https://img.shields.io/badge/cookiecutter-pypackage-success\"></a>\n<a href=\"https://black.readthedocs.io/en/stable/\"><img src=\"https://img.shields.io/badge/code%20style-black-000000\"></a>\n\n# h-api\n\nTools and components for calling the H API.\n\nThis package is not likely to be of use to you\n----------------------------------------------\n\nUnless you work for Hypothesis, then this package is not going to be very\nuseful to you. Feel free to have a poke about, but don't be surprised if it\ndoesn't make much sense.\n\nAt the present time not only should you not use this package, our \nauthentication will also prevent it.\n\nUsage\n-----\n\nTo construct NDJSON for Bulk API calls:\n\n```python\nfrom h_api.enums import ViewType\n\nfrom h_api.bulk_api import CommandBuilder, BulkAPI, Executor\n\nnd_json = BulkAPI.to_string([\n # It's your job to put the right commands here. \n # This also accepts a generator\n\n CommandBuilder.configure(\n effective_user=\"acct:example@lms.hypothes.is\", \n total_instructions=4, \n view=ViewType.BASIC),\n\n CommandBuilder.user.upsert({\n \"username\": \"username\",\n \"authority\": \"authority\",\n \"display_name\": \"display_name\",\n \"identities\": [{\n \"provider\": \"provider\",\n \"provider_unique_id\": \"provider_unique_id\"\n }],\n }, \"user_ref\"),\n\n CommandBuilder.group.upsert({\n \"name\": \"name\",\n \"authority\": \"authority\",\n \"authority_provided_id\": \"authority_provided_id\"\n }, \"group_ref\"),\n \n # These references here match those we assigned to the objects above\n CommandBuilder.group_membership.create(\"user_ref\", \"group_ref\")\n])\n\n# It's now your job to send this off to H\n```\n\nTo accept and process an NDJSON request like the above:\n```python\nclass MyExectutor(Executor):\n def execute_batch(self, command_type, data_type, default_config, batch):\n \"\"\"Implement your insertion logic here and return Report Objects\"\"\"\n \nrows = BulkAPI.from_byte_stream(http_streaming_body, executor=MyExectutor())\n\nif rows:\n # Turn each row into JSON and return to your caller\n # You have to do this\n```\n\n## Setting up Your h-api Development Environment\n\nFirst you'll need to install:\n\n* [Git](https://git-scm.com/).\n On Ubuntu: `sudo apt install git`, on macOS: `brew install git`.\n* [GNU Make](https://www.gnu.org/software/make/).\n This is probably already installed, run `make --version` to check.\n* [pyenv](https://github.com/pyenv/pyenv).\n Follow the instructions in pyenv's README to install it.\n The **Homebrew** method works best on macOS.\n The **Basic GitHub Checkout** method works best on Ubuntu.\n You _don't_ need to set up pyenv's shell integration (\"shims\"), you can\n [use pyenv without shims](https://github.com/pyenv/pyenv#using-pyenv-without-shims).\n\nThen to set up your development environment:\n\n```terminal\ngit clone https://github.com/hypothesis/h-api.git\ncd h-api\nmake help\n```\n\n## Releasing a New Version of the Project\n\n1. First, to get PyPI publishing working you need to go to:\n <https://github.com/organizations/hypothesis/settings/secrets/actions/PYPI_TOKEN>\n and add h-api to the `PYPI_TOKEN` secret's selected\n repositories.\n\n2. Now that the h-api project has access to the `PYPI_TOKEN` secret\n you can release a new version by just [creating a new GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository).\n Publishing a new GitHub release will automatically trigger\n [a GitHub Actions workflow](.github/workflows/pypi.yml)\n that will build the new version of your Python package and upload it to\n <https://pypi.org/project/h-api>.\n\n## Changing the Project's Python Versions\n\nTo change what versions of Python the project uses:\n\n1. Change the Python versions in the\n [cookiecutter.json](.cookiecutter/cookiecutter.json) file. For example:\n\n ```json\n \"python_versions\": \"3.10.4, 3.9.12\",\n ```\n\n2. Re-run the cookiecutter template:\n\n ```terminal\n make template\n ```\n\n3. Commit everything to git and send a pull request\n\n## Changing the Project's Python Dependencies\n\nTo change the production dependencies in the `setup.cfg` file:\n\n1. Change the dependencies in the [`.cookiecutter/includes/setuptools/install_requires`](.cookiecutter/includes/setuptools/install_requires) file.\n If this file doesn't exist yet create it and add some dependencies to it.\n For example:\n\n ```\n pyramid\n sqlalchemy\n celery\n ```\n\n2. Re-run the cookiecutter template:\n\n ```terminal\n make template\n ```\n\n3. Commit everything to git and send a pull request\n\nTo change the project's formatting, linting and test dependencies:\n\n1. Change the dependencies in the [`.cookiecutter/includes/tox/deps`](.cookiecutter/includes/tox/deps) file.\n If this file doesn't exist yet create it and add some dependencies to it.\n Use tox's [factor-conditional settings](https://tox.wiki/en/latest/config.html#factors-and-factor-conditional-settings)\n to limit which environment(s) each dependency is used in.\n For example:\n\n ```\n lint: flake8,\n format: autopep8,\n lint,tests: pytest-faker,\n ```\n\n2. Re-run the cookiecutter template:\n\n ```terminal\n make template\n ```\n\n3. Commit everything to git and send a pull request\n",
"bugtrack_url": null,
"license": "",
"summary": "Tools and components for calling the H API.",
"version": "1.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/hypothesis/h-api/issues",
"Changelog": "https://github.com/hypothesis/h-api/releases",
"Homepage": "https://github.com/hypothesis/h-api"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "69e5f03798803864eb5c13c1907c6466645c66d5408c8422501bcbaca9f8346a",
"md5": "4952a620eede4d19622ddd45b84074d8",
"sha256": "2bb5521506016a9759d1784ab363442424464fb4af3a502994069684f7848f06"
},
"downloads": -1,
"filename": "h_api-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4952a620eede4d19622ddd45b84074d8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 30168,
"upload_time": "2023-08-09T12:53:33",
"upload_time_iso_8601": "2023-08-09T12:53:33.435157Z",
"url": "https://files.pythonhosted.org/packages/69/e5/f03798803864eb5c13c1907c6466645c66d5408c8422501bcbaca9f8346a/h_api-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4a47129b35ef4bb7dda521ad62bd91b0fdcdee341eba0b20231cd537b336e762",
"md5": "6586855d7f610c80d84553dcd893ecce",
"sha256": "f96f329f1c1cff40425fc629da8ade0cfff26c4503bb88170ccc3700f071bda5"
},
"downloads": -1,
"filename": "h-api-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "6586855d7f610c80d84553dcd893ecce",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 72655,
"upload_time": "2023-08-09T12:53:35",
"upload_time_iso_8601": "2023-08-09T12:53:35.224892Z",
"url": "https://files.pythonhosted.org/packages/4a/47/129b35ef4bb7dda521ad62bd91b0fdcdee341eba0b20231cd537b336e762/h-api-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-09 12:53:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hypothesis",
"github_project": "h-api",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "h-api"
}
