Come utilizzare l'API GitHub in Python: una guida completa

L'API GitHub apre un entusiasmante mondo di possibilità per automatizzare i flussi di lavoro, integrarsi con GitHub, gestire progetti e analizzare dati. Come sviluppatori Python, possiamo sfruttare appieno l'API per aumentare la nostra produttività e creare strumenti utili.

In questa guida completa e passo passo imparerai come utilizzare l'API GitHub utilizzando Python.

Perché utilizzare l'API GitHub con Python?

Prima di addentrarci nel codice, vediamo perché usare l'API GitHub con Python è così potente:

Automatizza i flussi di lavoro – Elimina le attività ripetitive scrivendo script per creare problemi, aprire e unire PR, rilasciare file binari, ecc.
Migliora la produttività – Integra strumenti personalizzati nel tuo ambiente di sviluppo per migliorare i flussi di lavoro.
Gestisci progetti – Gestire a livello di codice problemi, etichette e tappe fondamentali nei repository.
Analizzare i dati – Estrai metriche e approfondimenti interessanti dagli oltre 96 milioni di repository.
Integra ed estendi GitHub – Crea app Web personalizzate, visualizzazioni, strumenti CLI, bot e altro ancora!

L'API apre molti modi creativi per aumentare la produttività e creare straordinari strumenti ed esperienze per gli sviluppatori.

Panoramica dell'API GitHub

L'API GitHub fornisce endpoint RESTful per accedere ai dati e ai servizi GitHub. Puoi:

Gestisci repository, sintesi, problemi, richieste pull
Interagisci con i dati Git: commit, rami, tag
Recupera profili utente, organizzazioni, team
Cerca codice, problemi, repository, utenti
Accedi a metadati, problemi, PR, file, commit
Analizzare le tendenze della comunità, progettare fork

E altre ancora… molto di piu!

L'API utilizza JSON per serializzare i dati e utilizza OAuth per l'autenticazione. Tutte le richieste devono essere effettuate tramite HTTPS.

Per utilizzare l'API è sufficiente:

Crea un account GitHub
Genera un token di accesso personale per l'autenticazione
Effettua richieste API e gestisci le risposte

Ora vediamolo in azione con esempi Python!

Effettuare richieste API GitHub

Python requests La libreria semplifica l'interazione con le API Web. Recuperiamo alcuni dati utente GitHub:

import requests

username = "defunkt"
response = requests.get(f"https://api.github.com/users/{username}")

print(response.json())

Questo stampa informazioni come:

{
  "login": "defunkt",
  "id": 2,
  "node_id": "MDQ6VXNlcjI=",
  "avatar_url": "https://avatars.githubusercontent.com/u/2?v=4",
  "gravatar_id": "",
  "url": "https://api.github.com/users/defunkt",
  "html_url": "https://github.com/defunkt",

  //...
}

Possiamo accedere a qualsiasi percorso API non autenticato in questo modo. Per accedere ai dati privati, dobbiamo passare un token di autenticazione.

Creazione di un token di accesso personale GitHub

Per generare un token:

Vai su Impostazioni > Impostazioni sviluppatore > Token di accesso personali
Clicchi Genera nuovo token
Dagli una descrizione come "Il mio script Python"
Seleziona gli ambiti/autorizzazioni desiderati
Clicchi Genera token

Assicurati di copiare il token: non potrai recuperarlo di nuovo in seguito!

Gli ambiti comuni includono:

repo – Accedi ai repository privati
admin:org – Gestire le organizzazioni
notifications – Accedi alle notifiche
user – Accesso in lettura/scrittura alle informazioni del profilo

Usiamo il nostro token per creare un nuovo repository:

import requests

token = "ghp_123abcMyToken"

data = {"name": "My New Repo"}

response = requests.post(
  "https://api.github.com/user/repos", 
  json=data,
  headers={"Authorization": f"token {token}"}
)

print(response.status_code) # 201 = Success!

Il token ci autentica per creare repository privati.

È inoltre possibile utilizzare App GitHub che hanno accesso con ambito e non scadono come i token utente. Le app devono essere installate da un utente/organizzazione per ottenere l'accesso.

Lavorare con i repository GitHub

Una parte importante dell'API riguarda la gestione dei repository. Esaminiamo alcune attività comuni del repository.

Ottieni un archivio

Per ottenere i metadati di un repository:

response = requests.get("https://api.github.com/repos/pandas-dev/pandas")
repo_info = response.json()

print(repo_info[‘description‘]) 
# Powerful data structures for data analysis, time series, statistics

Possiamo accedere a informazioni come descrizioni, stelle, cloni, contributori, lingue, versioni, commit e molto altro!

Elenca repository

Per elencare i repository per un utente o un'organizzazione:

repos_url = "https://api.github.com/users/octocat/repos"
repos = requests.get(repos_url).json()

for repo in repos:
  print(repo[‘name‘]) # Prints names of each repo

Crea un archivio

Possiamo anche creare nuovi repository:

data = {
  "name": "My New Repo",
  "description": "This is my cool new repo",
  "private": False
}

response = requests.post(
  "https://api.github.com/user/repos", 
  json=data,
  headers={"Authorization": "token {token}"}
)

Elimina un archivio

Per eliminare un archivio:

requests.delete(‘https://api.github.com/repos/octocat/Hello-World‘, 
                headers={"Authorization": "token {token}"})

Ciò ti dà il pieno controllo sulla gestione programmatica dei tuoi repository.

Nota: Tutte le richieste API devono essere effettuate utilizzando HTTPS per motivi di sicurezza.

Lavorare con i problemi nei repository

L'API Issues consente di gestire problemi e richieste pull. Puoi:

Elenca/crea/modifica/chiudi/riapri i problemi
Blocca le conversazioni, unisci i PR
Invia e modifica commenti
Aggiungi etichette, assegnatari, traguardi

Ad esempio, per ottenere problemi da un repository:

response = requests.get(‘https://api.github.com/repos/octocat/hello-world/issues‘)
issues = response.json()

for issue in issues:
  print(issue[‘title‘]) # Prints each issue title

Ciò consente di integrare la gestione dei problemi in strumenti e flussi di lavoro esterni.

Lavorare con Git Data

L'API Git Data fornisce endpoint per interagire direttamente con i repository Git. Puoi:

Gestione branch e tag
Leggere/scrivere dati BLOB
Recupera commit, riferimenti, alberi
Confronta commit, riferimenti, file

Ad esempio, per ottenere commit da un repository:

commits_url = "https://api.github.com/repos/pandas-dev/pandas/commits"
commits = requests.get(commits_url).json()

for commit in commits:
  print(commit[‘sha‘]) # Print commit SHAs
  print(commit[‘commit‘][‘message‘]) # Print messages

Ciò fornisce l'accesso completo per gestire a livello di codice i repository Git.

Ricerca di repository e codice

L'API di ricerca di GitHub consente di eseguire query su quasi qualsiasi cosa negli oltre 96 milioni di repository pubblici.

Ad esempio, per trovare progetti Python relativi alla scienza dei dati:

import requests

query = "language:python data science in:readme"
response = requests.get("https://api.github.com/search/repositories", 
                        params={"q": query})

results = response.json()[‘items‘]
for result in results:
  print(result[‘name‘]) # Prints names of matching repos

La sintassi delle query di ricerca supporta operatori booleani, filtri, selezione del contesto e altro ancora per creare ricerche mirate.

Qualche esempio:

org:facebook language:python stars:>5000 – Repository Python nell'organizzazione Facebook con oltre 5 stelle
filename:requirements.txt django – Repos con require.txt contenente Django
user:defunkt location:san francisco – Trova i repository di Defunkt se la posizione è SF

L'API di ricerca apre molti modi creativi per estrarre set di dati e approfondimenti interessanti dagli open data di GitHub.

Utilizzando l'API GraphQL di GitHub

Oltre all'API REST, GitHub fornisce un'API GraphQL per query più flessibili.

GraphQL ti consente di specificare con precisione i dati desiderati nelle strutture JSON nidificate. Puoi eseguire query su più entità collegate in un'unica richiesta.

Ad esempio, qui interroghiamo i dati del profilo di un utente e i nomi dei repository:

import requests 

query = """
query {
  user(login:"defunkt") {
    name
    repositories(first:10) {
      nodes { 
        name 
      }
    }
  }
}
"""

response = requests.post(‘https://api.github.com/graphql‘, json={‘query‘: query})
print(response.json())

Ciò consente di modellare la risposta esatta di cui hai bisogno. IL Esploratore GraphQL aiuta a creare query in modo interattivo.

Integrazione dell'API GitHub nelle app

Ora che conosci le nozioni di base, esaminiamo la creazione di applicazioni con l'API GitHub.

Autorizzazione dell'app OAuth

Per le app Web, utilizzare GitHub OAuth per l'autorizzazione invece dei token hardcoded. Ciò consente agli utenti di revocare l'accesso.

Registra una nuova app OAuth
Utilizzare l'ID client e il segreto per l'autorizzazione
Reindirizzare gli utenti per richiedere l'accesso a GitHub

Ora la tua app può effettuare chiamate API per conto degli utenti.

Effettuare richieste autenticate

Una volta autorizzato, effettua chiamate con il token di accesso:

access_token = "abc123xxddff" # OAuth token 

response = requests.get(
  "https://api.github.com/user/repos",
  headers={"Authorization": f"token {access_token}"}
)

print(response.json()) # Print user‘s private repos

Ciò ti consente di accedere ai dati privati in base alle autorizzazioni dell'utente.

rate limiting

L'API GitHub prevede limiti di velocità sulle richieste. Monitora lo stato della tua app:

response = requests.get("https://api.github.com/users/octocat") 

print(response.headers[‘X-RateLimit-Limit‘]) # 5000
print(response.headers[‘X-RateLimit-Remaining‘]) # 4999

Distribuisci le richieste nel tempo e memorizza nella cache i dati per evitare limiti.

Gestire gli errori con garbo

Controlla sempre i codici di stato e gestisci gli errori correttamente:

response = requests.get(‘https://api.github.com/invalid/url‘)

if response.status_code == 404:
  print("Resource not found!") 
elif response.status_code == 403:
  print("You do not have access!")
else:
  print("An error occurred.")

Ciò garantisce che la tua app rimanga stabile in produzione.

Seguendo le best practice API, puoi creare integrazioni e strumenti robusti per gli sviluppatori.

Creazione di un'app dashboard GitHub

Mettiamo insieme ciò che abbiamo imparato creando un'app Web per visualizzare il tuo profilo GitHub e i repository utilizzando Flask:

# app.py

from flask import Flask
import requests
from github import Github # pyGithub library

app = Flask(__name__)

@app.route("/")
def dashboard():
  # Use access token for API requests
  github = Github("access_token123xxdd")

  # Fetch user profile info
  user = github.get_user()

  # Fetch list of repos
  repos = user.get_repos() 

  # Pass info to template
  return render_template("dashboard.html", user=user, repos=repos)

if __name__ == "__main__":
  app.run(debug=True)

Usiamo pyGithub per semplificare alcune interazioni API. La home page renderà il file dashboard.html modello:

<!-- dashboard.html -->

<h3>GitHub Dashboard for {{user.name}}</h3>

<img src="{{user.avatar_url}}" style="width:64px">

<h4>Your Repositories</h4>

<ul>
  {% for repo in repos %}
  <li>{{repo.name}}</li>
  {% endfor %}
</ul>

Questo mostra come puoi creare un'app per visualizzare i dati GitHub per un utente registrato!

Le possibilità sono infinite per integrare l'API nelle tue app e nei tuoi strumenti.

Best practice per l'utilizzo dell'API GitHub

Ecco alcune best practice per garantire che le tue applicazioni che utilizzano l'API GitHub siano performanti, sicure e robuste:

Autenticazione – Utilizza token o OAuth, evita di inviare nome utente/password non elaborati.
HTTPS – Utilizza sempre gli endpoint HTTPS per proteggere i dati.
rate limiting – Distribuire le richieste e memorizzare nella cache i dati per evitare limiti.
Impaginazione – Utilizzare i parametri della pagina per scorrere i set di risultati.
Gestione degli errori – Gestire gli errori 4xx e 5xx con garbo.
Testing – Testare approfonditamente le chiamate API, utilizzare il mocking per le iterazioni.
Documentazione – Leggi attentamente i documenti, forniscono esempi di codice per ciascun endpoint.

Il rispetto delle best practice API previene errori evitabili e garantisce app affidabili.

Altre funzionalità dell'API GitHub da esplorare

Abbiamo solo scalfito la superficie di ciò che è possibile fare con l'API GitHub. Ecco alcune altre interessanti funzionalità da verificare:

API delle azioni GitHub – Automatizza i flussi di lavoro attivando azioni con l'API
Pagine GitHub – Gestire in modo programmatico i siti di Pages
Gist – Gestisci frammenti di codice, configurazioni e modelli
Organizations – Gestire i team dell'organizzazione, i membri e le autorizzazioni
Database Git – Accedi direttamente ai dati degli oggetti Git come BLOB e alberi
API del mercato GitHub – Gestisci le app elencate nel Marketplace GitHub
API delle discussioni su GitHub – Costruisci forum della community e integrazioni di domande e risposte

Le funzionalità API si espandono man mano che GitHub aggiunge nuove funzionalità, quindi tieni gli occhi aperti per i nuovi endpoint.

Confronta l'API di GitHub con le alternative

Per gli sviluppatori che lavorano con altre piattaforme, come si confronta l'API di GitHub con concorrenti come GitLab, BitBucket, Azure DevOps, ecc.?

Nel complesso le funzionalità API di GitHub si distinguono in termini di:

Adozione – Di gran lunga la più grande base di utenti e comunità
Documentazione – Documenti estremamente approfonditi con esempi
RESTO + GraphQL – Flessibilità degli endpoint REST e GraphQL
Capacità di ricerca – Potente ricerca indicizzata su tutti i dati pubblici
Ecosistema – Enorme ecosistema di app, strumenti e integrazioni
Analisi del codice – Funzionalità di scansione del codice, linting e analisi della qualità

GitHub è chiaramente leader nella funzionalità API grazie alla sua portata e agli anni di sviluppo. Altri fornitori come GitLab e BitBucket stanno espandendo le capacità API per competere. Ma per ora GitHub rimane l'API più completa per l'interazione a livello di programmazione con i repository Git.

Passaggi successivi e risorse

Spero che questa guida abbia fornito una panoramica completa su come utilizzare l'API GitHub con Python!

Ecco alcuni passaggi successivi e risorse per ulteriori approfondimenti:

Approfondisci i documenti: Documenti per sviluppatori
Guarda i video sull'API: Laboratorio didattico di GitHub
Scopri le app create con l'API: Marketplace di GitHub
Ulteriori informazioni su OAuth: Documenti dell'app OAuth
Scopri librerie come PyGithub e urllib3 per semplificare l'utilizzo dell'API
Prendi in considerazione risposte beffarde per testare l'interazione dell'API
Esplora gli strumenti associati come GitHub CLI e GitHub Actions

L'API GitHub apre un intero mondo di possibilità per creare strumenti per sviluppatori, automatizzare i flussi di lavoro, gestire progetti e analizzare dati. Spero che ti senta ispirato a creare qualcosa di prezioso per la comunità!

Buona programmazione!