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:

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:

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. On Ubuntu: sudo apt install git, on macOS: brew install git.
• GNU Make. This is probably already installed, run make --version to check.
• 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.

Then to set up your development environment:

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. Publishing a new GitHub release will automatically trigger a GitHub Actions workflow 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 file. For example:

   "python_versions": "3.10.4, 3.9.12",
   

2. Re-run the cookiecutter template:

   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 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:

   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 file. If this file doesn't exist yet create it and add some dependencies to it. Use tox's 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:

   make template
   

3. Commit everything to git and send a pull request