Contributing Guide
Welcome! We appreciate your interest in contributing to the google-play-scraper project. This document outlines the expected workflow and coding standards to help you get started quickly and ensure your contributions are seamlessly integrated.
Development Environment Setup
This project uses uv to manage Python dependencies and virtual environments. It is significantly faster than standard pip or poetry.
1. Install uv
If you haven't already, install uv.
2. Clone and Sync
git clone https://github.com/mdrakibhasanbd/google-play-scraper.git
cd google-play-scraper
# Sync dependencies and create the .venv
uv sync
3. Install Pre-commit Hooks
We use pre-commit to automatically run code quality checks before you commit.
Coding Standards & Workflow
We hold strict standards for code quality to ensure long-term maintainability.
The Toolchain
- Linting & Style: We use
ruffto enforce PEP8 standards, sort imports, and catch common logic errors.blackis used for uncompromising, consistent code formatting. - Type Safety:
mypyis configured in strict mode. All functions, methods, and variables should have explicit type hints.
Running Checks Manually
Before submitting a Pull Request, you must ensure all checks pass locally:
# Auto-fix linting issues and sort imports
uv run ruff check . --fix
# Format code
uv run black .
# Enforce strict type checking
uv run mypy src
Note: If you installed pre-commit, these checks will automatically run when you type git commit.
Modifying the Scraper
Google Play's HTML structure can be volatile. When modifying the core PlayScraper class:
1. Prefer Internal APIs: We heavily rely on Google's internal JSON endpoints (like /_/PlayStoreUi/data/batchexecute) rather than scraping pure HTML elements.
2. Use Pydantic: Ensure any new data structures are strictly typed using Pydantic models in models.py.
Automation Scripts (Maintainers Only)
We provide a suite of custom Python and Bash scripts in the scripts/ directory to automate versioning, building, and releasing.
scripts/release.sh
Primary entry point for releases.
This script orchestrates the entire release lifecycle.
1. Validates you are on the main branch with a clean working tree.
2. Pulls the latest code from origin.
3. Automatically delegates to bump-version.sh to update pyproject.toml.
4. Automatically delegates to tag-release.sh to create the git commit, tag, and push everything to origin.
Usage:
scripts/tag-release.sh
Git tagging automation.
This script handles the Git-specific operations for a release. It reads the current version from pyproject.toml, ensures no uncommitted changes exist, safely manages existing tags (prompting for deletion if a conflict occurs), generates a release notes file (docs/release_notes.md), commits the notes, creates the annotated Git tag, and pushes to origin.
Note: You usually do not call this directly; release.sh calls it for you.
scripts/build-release.sh
Verification and packaging.
Before publishing to PyPI or creating a GitHub Release, this script acts as a final safeguard. It:
1. Cleans the dist/ directory.
2. Runs all verification tools: ruff (with auto-fix), black, mypy, and pytest.
3. Runs uv build to assemble the .whl and .tar.gz packages.
Usage:
scripts/bump-version.sh
Versioning wrapper.
A Bash wrapper that enforces Git constraints (must be on main, must be clean) before explicitly calling the underlying Python script to alter the pyproject.toml file.
Note: You usually do not call this directly; release.sh calls it for you.
scripts/bump_version.py
Core versioning logic.
This Python script performs the actual semantic versioning math. It reads pyproject.toml via string parsing, increments the specified field based on SemVer rules, and writes the new version back to the file. It is designed to be called by the bump-version.sh wrapper, but can be used standalone if you only want to affect the TOML file without Git enforcement.
Usage: