gistyc

gistyc is a Python-based library that enables developers to create, update and delete their GitHub GISTs. CLI capabilities allow you to execute the routines from the shell and can be integrated into your project's CI/CD pipeline to automatically create or update your GISTs (e.g., via GitHub actions). Files are separated in GIST sections depending on the separation blocks.

gistyc considers currently only Python files (.py ending) in a Spyder-like code block separation (code block separator: #%%)

Prerequisites

1. Python 3.8 (recommendation: using a virtual environment)
2. A GitHub Personal access token with GIST access:
   • Click on your personal account profile (top right)
   • Click Settings
   • On the left menu bar go to Developer settings and choose Personal access tokens
   • Generate new token and write a name (note) of your token. The note does not affect the functionality, but choose a note that describes the purpose of the token e.g., GIST_token
   • Set a mark at gist (Create gists) and click on Generate token at the bottom of the page
   • IMPORTANT: The displayed token appears only once. Copy it and store it in your GitHub project as a secret and / or locally as an environment variable.

Installation

pip install gistyc

... or install it from the main branch of this repository. You can also download the entire repository to run the tests, download the CI/CD scripts etc.

Python library calls

Please note: ./tests provides some examples that can be reproduced / applied.
We assume:

• AUTH_TOKEN: is the GIST access token
• FILEPATH: is the absolute or relative path of a Python file
• GIST_ID: ID of a GIST.

Create a GIST

# import
import gistyc

# Initiate the GISTyc class with the auth token
gist_api = gistyc.GISTyc(auth_token=AUTH_TOKEN)

# Create a GIST with the sample file
response_data = gist_api.create_gist(file_name=FILEPATH)

Update a GIST

Updating a GIST requires either ONLY the FILEPATH or the FILEPATH AND a corresponding GIST ID, if the GIST repository contains file names that occur more than once. Hint: keep your GIST repository clean from same-name files!

Update using ONLY the FILEPATH:

# import
import gistyc

# Initiate the GISTyc class with the auth token
gist_api = gistyc.GISTyc(auth_token=AUTH_TOKEN)

# Update the GIST with the updated sample file (update is based on the file's name)
response_update_data = gist_api.update_gist(file_name=FILEPATH)

Update using the FILEPATH AND GIST ID:

# import
import gistyc

# Initiate the GISTyc class with the auth token
gist_api = gistyc.GISTyc(auth_token=AUTH_TOKEN)

# Update the GIST based on the GISTs ID
response_update_data = gist_api.update_gist(file_name=FILEPATH,
                                            gist_id=GIST_ID)

Get GISTs

Please note: one can obtain a list of all GISTs via:

# import
import gistyc

# Initiate the GISTyc class with the auth token
gist_api = gistyc.GISTyc(auth_token=AUTH_TOKEN)

# Get a list of GISTs
gist_list = gist_api.get_gists()

Delete a GIST

Deletion using ONLY the FILEPATH

# import
import gistyc

# Initiate the GISTyc class with the auth token
gist_api = gistyc.GISTyc(auth_token=AUTH_TOKEN)

# Delete the GIST, based on the GIST ID
response_data = gist_api.delete_gist(file_name=FILEPATH)

Deletion using ONLY the GIST ID

# import
import gistyc

# Initiate the GISTyc class with the auth token
gist_api = gistyc.GISTyc(auth_token=AUTH_TOKEN)

# Delete the GIST, based on the GIST ID
response_data = gist_api.delete_gist(gist_id=GIST_ID)

CLI

Please note: ./tests provides some examples that can be reproduced / applied.
We assume:

• AUTH_TOKEN: is the GIST access token
• FILEPATH: is the absolute or relative path of a Python file
• GIST_ID: ID of a GIST
• DIRECTORY: A directory (with an arbitrary number of sub-directories) that contains Python files

Create a GIST

gistyc --create --auth-token AUTH_TOKEN --file-name FILEPATH

Update a GIST

Update using ONLY the FILEPATH:

gistyc --update --auth-token AUTH_TOKEN --file-name FILEPATH

Update using the FILEPATH AND GIST ID:

gistyc --update --auth-token AUTH_TOKEN --file-name FILEPATH --gist-id GIST_ID

Delete a GIST

Deletion using ONLY the FILEPATH

gistyc --delete --auth-token AUTH_TOKEN --file-name FILEPATH

Deletion using ONLY the GIST ID

gistyc --delete --auth-token AUTH_TOKEN --gist-id GIST_ID

Directory Create & Update

A second gistyc CLI allows you to provide a directory as an input that recursively gets all Python files and creates or updates GISTs accordingly. Please Note: File names MUST be unique in GIST.

gistyc_dir --auth-token AUTH_TOKEN --directory DIRECTORY

Example

Example Python files (in a directory) can be found here.

The corresponding GISTs are embedded hereinafter: https://gist.github.com/ThomasAlbin/b18383a86cb4396a79a551a73330ce76 https://gist.github.com/ThomasAlbin/caddb300ac663e60ae573b1117599fcc.

GitHub Actions - CI/CD

The following YAML file is used by the gistyc repository to provide an example on how to use gistyc in a CI/CD pipeline. Example Python scripts are stored, added and edited in ./examples. Changes in this directory trigger the pipeline (only after a merge with the main branch).

# CI/CD GitHub Action YAML file
#
# This YAML file executes a gistyc create / update pipeline on all Python files
# within the folder ./examples (after merging to the main branch)
name: GIST CD on main branch and example directory change

# Check if files have been pushed to ./examples
on:
  push:
    paths:
      - examples/**

# Execute the gistyc create / update pipeline
jobs:

  build:

    # Execute the pipeline only on changes on the main branche
    if: github.ref == 'refs/heads/main'

    runs-on: ubuntu-latest

    strategy:
      matrix:
        python-version: ['3.8']

    # Steps:
    # - Checkout the branch & use Python
    # - Install gistyc
    # - Use gistyc_dir, authenticate and use the ./examples directory as an input
    steps:
    - uses: actions/checkout@v2
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v2
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install gistyc
      run: pip install gistyc
    - name: Use gistyc CLI on examples/**
      run: gistyc_dir --auth-token ${{ secrets.GIST_TOKEN }} --directory ./examples/

Support & Contributions

If you have requests, issues or ideas please use the GitHub Issues. Contributions are always welcome and should be provided via a Pull Request. Please note the strict coding standards and other guidelines. These standards are checked for all PRs and can be seen here. Please note that all functions must contain a pytest.

Direct messages to the author of gistyc are always welcome. Please use Twitter, Reddit or Medium for this purpose.

Best,
Thomas