printables-stats 0.1.0

Python library and CLI tool to scrape public user statistics from Printables.com

Printables Stats Scraper

A Python library and CLI tool to scrape public user statistics from Printables.com, including detailed badge levels.

Features

• Public Stats: Fetches downloads, likes, followers, following, joined date, and model count.
• Detailed Badges: Parses badges into a dictionary of {Name: Level} (e.g., {'Designer': 1, 'Maker': 4}).

Installation

From PyPI

pip install printables-stats

From Source

This project uses uv for dependency management.

# Clone the repository
git clone https://gitlab.com/yourusername/printables-stats.git
cd printables-stats

# Install dependencies
uv sync

Usage

CLI

You can use the included script to fetch stats for a specific user via environment variable.

export PRINTABLES_USER_ID='@josefprusa'
uv run python -m printables_stats

Output Example:

{
  "downloads": 4,
  "likes": 1,
  "followers": 0,
  "following": 4,
  "joined_date": "November 6, 2025",
  "models_count": 4,
  "badges": {
    "Designer": 1,
    "Maker": 4,
    "Download Maniac": 3,
    "Printables Maniac": 1
  }
}

Library

from printables_stats import PrintablesClient

client = PrintablesClient()
stats = client.get_user_stats('@josefprusa')

if stats:
    print(f"Downloads: {stats.get('downloads')}")
    print(f"Badges: {stats.get('badges')}")

Development

Run quality checks and tests:

uv run ruff check .

uv run ruff format .

uv run ty check .

uv run pytest

Releasing to PyPI

This project uses GitLab CI with PyPI Trusted Publisher (OIDC) for secure, token-less automated releases.

Prerequisites

Configure the Trusted Publisher on PyPI (one-time setup):

1. Go to https://pypi.org/manage/account/publishing/
2. Add a new Trusted Publisher with these details:
   • PyPI Project Name: printables-stats
   • Publisher: GitLab
   • Owner: Your GitLab username or group
   • Repository name: printables-stats
   • Workflow filename: .gitlab-ci.yml
   • Environment name: Leave empty (or specify if using environments)

No API tokens needed! GitLab authenticates via OIDC.

Release Process

1. Update the version in pyproject.toml
2. Commit and push your changes
3. Create and push a git tag:

   git tag v0.1.0
   git push origin v0.1.0
   

4. In GitLab, navigate to CI/CD → Pipelines
5. Manually trigger the release job to publish to PyPI
6. Verify the package on https://pypi.org/project/printables-stats/