Skip to content

Quick Start#

Welcome to quick start section. We will explain here how to get started using the PyOctocat library. Great efforts have been made to make the API as high-level, readable and intuitive as possible. Overall, we are happy with the results and hope that the behavior of this library will also appeal to users.

Creating a GitHub client#

As library name implies, PyOctocat is mainly designed to be asynchronous library and thus requires code to be run in async functions. Therefore basic template which will be used for rest of this tutorial looks following way:

1
2
3
4
5
6
7
8
9
import asyncio


async def main():
    ...


if __name__ == "__main__":
    raise SystemExit(asyncio.run(main()))

All executable code goes into async def main() function shown above. Imports can be still kept at the top of the file (and it is recommended).

To begin with using PyOctocat, you will have to create instance of GitHub object, which takes username and github token as arguments. It will be used to acquire objects from Github API and control session availability.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import asyncio
from async_py_octocat import GitHub


async def main():
    gh = GitHub("username", "ghp_...")
    ...


if __name__ == "__main__":
    raise SystemExit(asyncio.run(main()))

Interacting with Github API#

Important

ALL interaction with Github API (sending and receiving data) can only be done withing async with block in async function.

All interaction, requiring internet access, outside async with, will either fail or finish with unexpected results.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import asyncio
from async_py_octocat import GitHub


async def main():
    gh = GitHub("username", "ghp_...")
    async with gh as client:
        ...


if __name__ == "__main__":
    raise SystemExit(asyncio.run(main()))

At this point we can acquire user information via Github API with call to .user(...) function. When called with no arguments, it will return currently authenticated user, otherwise expects string containing user name and returns wrapper object containing details acquired from API.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import asyncio
from async_py_octocat import GitHub


async def main():
    gh = GitHub("username", "ghp_...")
    async with gh as client:
        user = client.user("Argmaster")
        ...

if __name__ == "__main__":
    raise SystemExit(asyncio.run(main()))

Having the user object, we can get the repository of which he is the owner. We do this by using the repository() method, which takes the name of the repository as an argument.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import asyncio
from async_py_octocat import GitHub


async def main():
    gh = GitHub("username", "ghp_...")
    async with gh as client:
        user = await client.user("Argmaster")
        repo = await user.repository("repo_name")
        ...

if __name__ == "__main__":
    raise SystemExit(asyncio.run(main()))

Info

Your next steps depend on your needs, unfortunately rest of API is currently not implemented. Hopefully, in the next release we will put in your hands the tools to use the data contained in the repository.

Last update: July 3, 2022
Created: July 3, 2022