Skip to content

Latest commit

 

History

History
222 lines (144 loc) · 6.52 KB

octomachinery-cmd-line.rst

File metadata and controls

222 lines (144 loc) · 6.52 KB

Using octomachinery client on the command line

Let's do some simple exercises of using GitHub API to create an issue. We'll be doing this locally using the command line, instead of actually creating the issue on GitHub website.

Install octomachinery

Install octomachinery if you have not already. Using a virtual environment is recommended.

python3.7 -m pip install octomachinery==|octomachinery_version|

Create GitHub Personal Access Token

In order to use GitHub API, you'll need to create a personal access token that will be used to authenticate you in GitHub.

  1. Go to https://github.com/settings/tokens.

    Or, from GitHub, go to your profile Settings > Developer Settings > Personal access tokens.

  2. Click Generate new token.

  3. Under Token description, enter a short description, to identify the purpose of this token. I recommend something like: pycon bot tutorial.

  4. Under select scopes, check the repo scope. You can read all about the available scopes here. In this tutorial, we'll only be using the token to work with repositories, and nothing else. But this can be edited later. What the repo scope allows your bot to do is explained in GitHub's scope documentation.

  5. Press generate. You will see a really long string (40 characters). Copy that, and paste it locally in a text file for now.

    This is the only time you'll see this token in GitHub. If you lost it, you'll need to create another one.

Store the Personal Access Token as an environment variable

In Unix / Mac OS:

export GITHUB_TOKEN=your token

In Windows:

set GITHUB_TOKEN=your token

Note that these will only set the token for the current process. If you want this value stored permanently, you have to use another way of doing this, like using dotenv, direnv or similar (we'll omit this as it is out of scope of this tutorial).

Let's get coding!

Create a new Python file, for example: create_issue.py, and open it in your favorite text editor.

Note

You can optionally create a working directory where you'll put this file but for the purposes of this tutorial page it's unnecessary.

Copy the following into create_issue.py:

.. literalinclude:: resources/octomachinery-cmd-line/hello_world.py
   :language: python

Save and run it in the command line:

python3.7 -m create_issue

You should see "Hello world." printed. That was "Hello world" with asyncio! 😎

Create an issue

Ok now we want to actually work with GitHub and octomachinery.

Add the following imports:

.. literalinclude:: resources/octomachinery-cmd-line/create_issue.py
   :language: python
   :lines: 2-6

And replace print("Hello world.") with:

.. literalinclude:: resources/octomachinery-cmd-line/create_issue.py
   :language: python
   :lines: 10-16
   :dedent: 4

Instead of "webknjaz" however, use your own GitHub username.

The full code now looks like the following:

.. literalinclude:: resources/octomachinery-cmd-line/create_issue.py
   :language: python
   :lines: -16,24-
   :emphasize-lines: 2-6,10-16

So instead of printing out hello world, we're now instantiating a GitHub API client from octomachinery, we're telling it who we are ("webknjaz" in this example), and we're giving it the GitHub personal access token, which were stored as the GITHUB_TOKEN environment variable.

Now, let's create an issue in my personal repo.

Take a look at GitHub's documentation for creating a new issue.

It says, you can create the issue by making a POST request to the url /repos/:owner/:repo/issues and supply the parameters like title (required) and body.

With octomachinery's GitHub API client, this looks like the following:

.. literalinclude:: resources/octomachinery-cmd-line/create_issue.py
   :language: python
   :lines: 17-23
   :dedent: 8

Go ahead and add the above code right after you instantiate RawGitHubAPI.

Your file should now look like the following:

.. literalinclude:: resources/octomachinery-cmd-line/create_issue.py
   :language: python
   :emphasize-lines: 17-23

Feel free to change the title and the body of the message.

Save and run that. There should be a new issue created in the test repo. Check it out: https://github.com/mariatta/strange-relationship/issues

Comment on issue

Let's try a different exercise, to get ourselves more familiar with GitHub APIs.

Take a look at GitHub's create a comment documentation.

Try this yourself, and leave a comment in the issue you just created.

Close the issue

Let's now close the issue that you've just created.

Take a look at the documentation to edit an issue.

The method for closing an issue is PATCH instead of POST, which we've seen in the previous two examples. In addition, to delete an issue, you're basically editing an issue, and setting the state to closed.

Use GitHub API client to patch the issue:

.. literalinclude:: resources/octomachinery-cmd-line/close_issue.py
   :language: python
   :lines: 17-21
   :emphasize-lines: 4
   :dedent: 8

Replace 28 with the issue number you created.

Bonus exercise

Add reaction to an issue.

Attention!

Pay attention at the blue Note: box in the docs. Using this API endpoint requires setting a special marker with squirrel-girl codename in order to flag GitHub that you really want to access this preview api version. If you miss that, attempting to use this API will result in an error response from the GitHub platform.

Please, pass it as preview_api_version='squirrel-girl' argument each time you make this API call.