Skip to content

A simple asynchronous python wrapper for the GitHub Gists API.

License

Notifications You must be signed in to change notification settings

WitherredAway/gists.py

Repository files navigation

gists.py

A simple asynchronous python wrapper for the GitHub Gists API

This API wrapper mainly focuses on the Gists part of the GitHub API, not the entire API

Features

All unchecked features are planned

Gists

  • GETing from /gists, to get authenticated user's Gists
  • GETing from /users/{username}/gists to get a user's Gists
  • GET ing from /gists/public to get public Gists
  • GET ing from /gists/starred to get authenticated user's starred Gists
  • POSTing to /gists, to create a Gist
  • GET ing from /gists/{gist_id} to get a Gist
  • PATCHing to /gists/{gist_id}, to edit a Gist
  • DELETEing from /gists/{gist_id} to delete a Gist

Gists - Forks

  • POSTing to /gists/{gist_id}/forks to fork a Gist to the authenticated user's profile

Gists - Star

  • GETing from /gists/{gist_id}/star to check if a gist is starred by the authenticated user
  • PUTing /gists/{gist_id}/star to star a Gist with the authenticated user
  • DELETEing from /gists/{gist_id}/star to unstar a Gist with the authenticated user

Gists - Comments

  • GETing from /gists/{gist_id}/comments to get all comments on a Gist
  • POSTing to /gists/{gist_id}/comments to create a comment on a Gist
  • GETing from /gists/{gist_id}/comments/{comment_id} to get a comment on a Gist
  • PATCHing to /gists/{gist_id}/comments/{comment_id} to edit a comment of the authenticated user on a Gist
  • DELETEing from /gists/{gist_id}/comments/{comment_id} to delete a comment of the authenticated user on a Gist

Installation

Windows

py -m pip install gists.py

or

py -m pip install git+https://github.com/WitherredAway/gists.py

Linux/macOS

python3 -m pip install gists.py

or

python3 -m pip install git+https://github.com/WitherredAway/gists.py

Usage examples

This section is a work in progress

Import gists and instantiate a client

# Import asyncio
import asyncio
# Import the package
import gists

# Create a client instance
client = gists.Client()

Get a gist

async def main_get():
    # Getting a gist does not require authorization

    # This method fetches the gist associated with the provided gist id, and returns a Gist object
    gist = await client.get_gist("GIST ID")
    return gist

# Run the main_get() function
gist = asyncio.run(main_get())
# Print the gist's description
print(gist.description)

Create a new gist

async def main_create() -> gists.Gist:
    # Creating a gist requires authorization, use client.authorize to authorize the client
    await client.authorize("YOUR GITHUB PERSONAL ACCESS TOKEN")
    
    # The description to set
    description = "Hi this is a gist"

    # The files to create in the new gist
    files = [
        gists.File(name="example.txt", content="I like turtles"),
        gists.File(name="helloworld.py", content="print(\"Hello, world!\")"),
    ]
    
    # Whether or not the gist should be public
    public = True

    # This method creates a new gist and returns a Gist object associated with that gist
    gist = await client.create_gist(files=files, description=description, public=public)
    return gist
        
# Run the main_create() function
gist_1 = asyncio.run(main_create())
# Print the gist's id
print(gist_1.id)

Edit gist using the edit method of a Gist object

async def main_edit():
    # Editing a gist requires authorization, but we already authorized the client when creating the gist

    # The description to edit to
    description = "Hello this is a gist, but edited"

    # The files to edit in gist

    files = [
        # Use a unique filename for the name parameter to create a new file
        gists.File(name="newfile.txt", content="New file"),
        # Use an existing filename for the name parameter to edit that file
        gists.File(name="example.txt", content="I like all animals"),
        # Use an existing filename for the name parameter and
        # pass in the new_name parameter to edit the name of that file,
        # in which case the content parameter is not mandatory
        gists.File(name="helloworld.py", new_name="hellouniverse.py")
    ]
    await gist_1.edit(files=files, description=description)
    
# Run the main_edit() function
asyncio.run(main_edit())
# Print the gist's edited description
print(gist_1.description)