DOCSEARCHbyAlgolia
Submit Docs

pypistats

repository·main·Indexed 42 days ago

https://github.com/hugovk/pypistats

A Python library and CLI tool providing an interface to the PyPI Stats API to fetch download statistics for PyPI packages. It supports retrieving recent, overall, Python version, and operating system statistics, with output options including JSON, Markdown, NumPy arrays, and pandas DataFrames.

Tokens
3.5K
Snippets
16
Records
19
Agent score
52%

What's inside pypistats

  1. Overview of pypistats

    main

    pypistats is a Python interface for the PyPI Stats API. It allows you to retrieve aggregate download statistics for Python packages on the Python Package Index (PyPI) without needing to perform direct queries against Google BigQuery.

    Note on data availability: The API provides data for the last 180 days. For historical data spanning longer periods, you may need to use pypinfo with an API key.

  2. Use pypistats CLI subcommands

    main

    The pypistats command-line tool operates using subcommands that correspond to PyPI Stats API endpoints. To see all available subcommands, run pypistats --help.

    Available subcommands:

    • recent: Retrieve aggregate download quantities for the last 1, 7, or 30 days.
    • overall: Retrieve overall download statistics.
    • python_major: Retrieve download statistics by Python major version.
    • python_minor: Retrieve download statistics by Python minor version.
    • system: Retrieve download statistics by operating system.
    $ pypistats --help
usage: pypistats [-h] [-V] {recent,overall,python_major,python_minor,system} ...

  3. Use local paths to resolve package names

    main

    Instead of providing a package name string, you can provide a path to a local directory. pypistats will attempt to find the package name by inspecting pyproject.toml or setup.cfg within that directory.

    $ pypistats recent .
$ pypistats recent ../Pillow

  4. Install NumPy and pandas extras for pypistats

    main

    To use pypistats with NumPy or pandas for data analysis and plotting, you must install the corresponding extras using pip:

    pip install --upgrade "pypistats[numpy]"
pip install --upgrade "pypistats[pandas]"
pip install --upgrade "pypistats[numpy,pandas]"
    pip install --upgrade "pypistats[numpy,pandas]"

  5. Install pypistats

    main

    You can install pypistats via PyPI using pip, or by cloning the source repository and installing it locally.

    # From PyPI
python3 -m pip install --upgrade pypistats

# From source
git clone https://github.com/hugovk/pypistats
cd pypistats
python3 -m pip install .

  6. Specify package via name or directory

    main

    The package argument in most pypistats commands is flexible. You can provide:

    1. A direct package name.
    2. A directory path containing a pyproject.toml or setup.cfg file. The CLI will automatically extract the package name from these configuration files.

    If a directory is provided, it looks for project.name in pyproject.toml or metadata.name in setup.cfg.

  7. Create download charts using pandas

    main

    Once you have retrieved data in a pandas DataFrame, you can use pandas' plotting capabilities to visualize download trends over time.

    Example: Plotting overall downloads excluding mirrors:

    1. Fetch data with format="pandas".
    2. Filter the category column for without_mirrors.
    3. Sort by date.
    4. Use .plot() to generate the chart.
    import pypistats

# Show overall downloads over time, excluding mirrors
data = pypistats.overall("pillow", total="daily", format="pandas")
data = data.groupby("category").get_group("without_mirrors").sort_values("date")

chart = data.plot(x="date", y="downloads", figsize=(10, 2))
chart.figure.show()
chart.figure.savefig("overall.png")

  8. Format pypistats output for GitHub

    main

    You can export pypistats results in Markdown format, which is ideal for pasting directly into GitHub issues or Pull Requests.

    Use the --format md or --format markdown flag to generate a Markdown table.

    $ pypistats python_minor pillow --last-month --format md

  9. Get data as NumPy arrays or pandas DataFrames

    main

    By setting the format parameter to numpy or pandas, you can retrieve statistics directly into data science structures for further processing.

    • NumPy: Returns a numpy.ndarray.
    • pandas: Returns a pandas.core.frame.DataFrame with columns typically including category, date, percent, and downloads.
    import pypistats

# Get data as a NumPy array
numpy_array = pypistats.overall("pyvista", total="daily", format="numpy")

# Get data as a pandas DataFrame
pandas_dataframe = pypistats.overall("pyvista", total="daily", format="pandas")

  10. Retrieve downloads by Python minor version with 'python_minor'

    main

    The python_minor subcommand retrieves the aggregate daily download time series by Python minor version number.

    Arguments:

    • package: The name of the package, or a directory containing pyproject.toml or setup.cfg.

    Options:

    • -V, --version VERSION: Filter by a specific Python version (e.g., 2.7 or 3.6).
    • -f, --format {html,json,pretty,md,markdown,rst,tsv}: Output format.
    • -j, --json: Shortcut for -f json.
    • -sd, --start-date yyyy-mm[-dd]|name: Start date.
    • -ed, --end-date yyyy-mm[-dd]|name: End date.
    • -m, --month yyyy-mm|name: Shortcut for setting both start and end date for a single month.
    • -l, --last-month: Shortcut for the last month.
    • -t, --this-month: Shortcut for the current month.
    • -d, --daily: Show daily downloads.
    • --monthly: Show monthly downloads.
    • -s, --sort SORT: Column to sort by (e.g., downloads, date, category). Default is downloads.
    • -c, --color {yes,no,auto}: Terminal color output.
    • -v, --verbose: Print debug messages to stderr.
    $ pypistats python_minor pillow --last-month

  11. Use pypistats programmatically

    main

    You can use pypistats as a Python library to fetch package statistics. The return values correspond to the JSON responses from the PyPI Stats API.

    Available core functions include:

    • recent(package, period, format): Fetches recent download statistics. period can be day, week, or month.
    • overall(package, mirrors, format): Fetches overall download statistics. mirrors is a boolean.
    • python_major(package, version, format): Fetches statistics for a specific Python major version.
    • python_minor(package, version, format): Fetches statistics for a specific Python minor version.
    • system(package, os, format): Fetches statistics for a specific operating system.

    You can specify the output format as markdown, rst, html, json, numpy, or pandas.

    import pypistats
from pprint import pprint

# Example: Fetching recent downloads for 'pillow' in markdown format
print(pypistats.recent("pillow", "day", format="markdown"))

# Example: Fetching overall downloads for 'pillow' in JSON format
pprint(pypistats.overall("pillow", mirrors=False, format="json"))

# Example: Fetching Python 3 statistics
print(pypistats.python_major("pillow", version=3, format="markdown"))

  12. Retrieve recent downloads with the 'recent' subcommand

    main

    The recent subcommand retrieves aggregate download quantities for the last day, week, or month, excluding downloads from mirrors.

    Arguments:

    • package: The name of the package, or a directory containing pyproject.toml or setup.cfg to resolve the name.

    Options:

    • -p, --period {day,week,month}: The time period to retrieve (default: day is implied by the output columns, but the flag allows selection).
    • -f, --format {html,json,pretty,md,markdown,rst,tsv}: The output format (default: pretty).
    • -j, --json: Shortcut for -f json.
    • -v, --verbose: Print debug messages to stderr.
    $ pypistats recent pillow