Analisando downloads de pacotes PyPI#

Esta seção cobre como usar o conjunto de dados de estatísticas de download público do PyPI para saber mais sobre os downloads de um pacote (ou pacotes) hospedado no PyPI. Por exemplo, você pode usá-lo para descobrir a distribuição das versões do Python usadas para baixar um pacote.

Contexto#

O PyPI não exibe estatísticas de download por vários motivos: [1]

  • Ineficiente para fazer funcionar com uma Rede de Distribuição de Conteúdo (CDN): As estatísticas de download mudam constantemente. Incluí-las nas páginas do projeto, que são altamente armazenadas em cache, exigiria a invalidação do cache com mais frequência e reduziria a eficácia geral do cache.

  • Altamente imprecisa: Várias coisas impedem que as contagens de download sejam precisas, algumas das quais incluem:

    • Cache de download do pip (diminui a contagem de downloads)

    • Espelhos internos ou não oficiais (pode aumentar ou diminuir as contagens de download)

    • Pacotes não hospedados no PyPI (para fins de comparação)

    • Scripts não oficiais ou tentativas de aumento da contagem de download (aumenta a contagem de downloads)

    • Problemas conhecidos de qualidade de dados históricos (diminui a contagem de downloads)

  • Não é particularmente útil: Só porque um projeto foi muito baixado, não significa que ele seja bom; Da mesma forma, só porque um projeto não foi muito baixado, não significa que ele seja ruim!

Resumindo, como seu valor é baixo por vários motivos e as compensações necessárias para fazê-lo funcionar são altas, não tem sido um uso eficaz de recursos limitados.

Conjunto de dados públicos#

Como alternativa, o projeto Linehaul transmite registros de download do PyPI para o Google BigQuery [2], onde são armazenados como um conjunto de dados público.

Preparando-se#

Para usar o Google BigQuery para consultar o conjunto de dados público de estatísticas de download do PyPI, você precisará de uma conta do Google e habilitar a API do BigQuery em um projeto do Google Cloud Platform. Você pode executar até 1 TB de consultas por mês usando o free tier do BigQuery sem um cartão de crédito

Para obter instruções mais detalhadas sobre como começar a usar o BigQuery, consulte o guia de início rápido do BigQuery.

Esquema de dados#

Linehaul escreve uma entrada em uma tabela bigquery-public-data.pypi.file_downloads para cada download. A tabela contém informações sobre qual arquivo foi baixado e como foi baixado. Algumas colunas úteis do esquema da tabela inclui:

Coluna

Descrição

Exemplos

timestamp

Data e hora

2020-03-09 00:33:03 UTC

file.project

Nome do projeto

pipenv, nose

file.version

Versão do pacote

0.1.6, 1.4.2

details.installer.name

Instalador

pip, bandersnatch

details.python

Versão do Python

2.7.12, 3.6.4

Consultas úteis#

Executa consultas na interface web do BigQuery clicando no botão “Compose query”.

Observe que as linhas são armazenadas em uma tabela particionada, o que ajuda a limitar o custo das consultas. Essas consultas de exemplo analisam downloads do histórico recente filtrando na coluna timestamp.

Contando downloads de pacotes#

A consulta a seguir conta o número total de downloads do projeto “pytest”.

#standardSQL
SELECT COUNT(*) AS num_downloads
FROM `bigquery-public-data.pypi.file_downloads`
WHERE file.project = 'pytest'
  -- Only query the last 30 days of history
  AND DATE(timestamp)
    BETWEEN DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
    AND CURRENT_DATE()

num_downloads

26190085

Para contar apenas os downloads do pip, filtre na coluna details.installer.name.

#standardSQL
SELECT COUNT(*) AS num_downloads
FROM `bigquery-public-data.pypi.file_downloads`
WHERE file.project = 'pytest'
  AND details.installer.name = 'pip'
  -- Only query the last 30 days of history
  AND DATE(timestamp)
    BETWEEN DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
    AND CURRENT_DATE()

num_downloads

24334215

Downloads de pacotes ao longo do tempo#

Para agrupar por downloads mensais, use a função TIMESTAMP_TRUNC. Além disso, a filtragem por esta coluna reduz os custos correspondentes.

#standardSQL
SELECT
  COUNT(*) AS num_downloads,
  DATE_TRUNC(DATE(timestamp), MONTH) AS `month`
FROM `bigquery-public-data.pypi.file_downloads`
WHERE
  file.project = 'pytest'
  -- Only query the last 6 months of history
  AND DATE(timestamp)
    BETWEEN DATE_TRUNC(DATE_SUB(CURRENT_DATE(), INTERVAL 6 MONTH), MONTH)
    AND CURRENT_DATE()
GROUP BY `month`
ORDER BY `month` DESC

num_downloads

mês

1956741

2018-01-01

2344692

2017-12-01

1730398

2017-11-01

2047310

2017-10-01

1744443

2017-09-01

1916952

2017-08-01

Versões Python ao longo do tempo#

Extrai a versão Python da coluna details.python. Aviso: esta consulta processa mais de 500 GB de dados.

#standardSQL
SELECT
  REGEXP_EXTRACT(details.python, r"[0-9]+\.[0-9]+") AS python_version,
  COUNT(*) AS num_downloads,
FROM `bigquery-public-data.pypi.file_downloads`
WHERE
  -- Only query the last 6 months of history
  DATE(timestamp)
    BETWEEN DATE_TRUNC(DATE_SUB(CURRENT_DATE(), INTERVAL 6 MONTH), MONTH)
    AND CURRENT_DATE()
GROUP BY `python_version`
ORDER BY `num_downloads` DESC

python

num_downloads

3.7

18051328726

3.6

9635067203

3.8

7781904681

2.7

6381252241

null

2026630299

3.5

1894153540

Ressalvas#

Além das advertências listadas no histórico acima, Linehaul sofreu de um bug que causou um subestimamento das estatísticas de download antes de 26 de julho de 2018. Downloads antes dessa data são proporcionalmente precisos (por exemplo, a porcentagem de Python 2 vs. Python 3 downloads), mas os números totais são menores do que o real em uma ordem de magnitude.

Ferramentas adicionais#

Além de usar o console do BigQuery, existem algumas ferramentas adicionais que podem ser úteis ao analisar estatísticas de download.

google-cloud-bigquery#

Você também pode acessar o conjunto de dados público de estatísticas de download PyPI de maneira programática por meio da API do BigQuery e do projeto google-cloud-bigquery, a biblioteca cliente oficial do Python para BigQuery.

from google.cloud import bigquery

# Note: depending on where this code is being run, you may require
# additional authentication. See:
# https://cloud.google.com/bigquery/docs/authentication/
client = bigquery.Client()

query_job = client.query("""
SELECT COUNT(*) AS num_downloads
FROM `bigquery-public-data.pypi.file_downloads`
WHERE file.project = 'pytest'
  -- Only query the last 30 days of history
  AND DATE(timestamp)
    BETWEEN DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
    AND CURRENT_DATE()""")

results = query_job.result()  # Waits for job to complete.
for row in results:
    print("{} downloads".format(row.num_downloads))

pypinfo#

pypinfo é uma ferramenta de linha de comando que fornece acesso ao conjunto de dados e pode gerar várias consultas úteis. Por exemplo, você pode consultar o número total de downloads de um pacote com o comando pypinfo package_name.

Instale pypinfo usando o pip.

python3 -m pip install pypinfo

Uso:

$ pypinfo requests
Served from cache: False
Data processed: 6.87 GiB
Data billed: 6.87 GiB
Estimated cost: $0.04

| download_count |
| -------------- |
|      9,316,415 |

pandas-gbq#

O projeto pandas-gbq permite acessar resultados de pesquisa com Pandas.

Referências#