Metadata-Version: 2.4
Name: googleplay-python
Version: 0.1.0
Summary: A Python client for Google Play authentication, metadata, and APK delivery.
Author: Zenofex
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/Zenofex/googleplay-python
Project-URL: Repository, https://github.com/Zenofex/googleplay-python
Project-URL: Issues, https://github.com/Zenofex/googleplay-python/issues
Keywords: google-play,play-store,android,apk,googleplay
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: protobuf<5,>=3.20
Requires-Dist: requests<3,>=2.28
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# googleplay-python

A Python client for Google Play authentication, metadata, and APK delivery.

`googleplay-python` is an unofficial library for Google Play workflows that are
not covered by the public Play Developer APIs. It provides:

- OAuth cookie to AAS token exchange
- Google Play checkin and bearer-token login
- authenticated app details lookup
- authenticated APK and OBB delivery
- lightweight Play web search and public detail scraping

This library is aimed at automation and research use cases that need a Python
API instead of shelling out to external tools.

## Status

The project is usable, but it is still early.

- The authenticated client is covered by unit tests and opt-in live tests.
- The web search/detail client is intentionally small and only extracts the
  fields used by the library's compatibility layer.
- Google can change private or undocumented endpoints at any time.

Treat the API as stable enough for integration work, but expect occasional
maintenance when Google changes upstream behavior.

## Installation

```bash
pip install googleplay-python
```

For development:

```bash
pip install -e .[test]
```

## Quick Start

### Exchange an OAuth cookie for an AAS token

```python
from googleplay import TokenExchangeClient

client = TokenExchangeClient()
aas_token = client.request_aas_token(
    email="account@example.com",
    oauth_token="oauth2_4/...",
)
print(aas_token)
```

### Log in and fetch app details

```python
from googleplay import GooglePlayClient

client = GooglePlayClient(
    email="account@example.com",
    aas_token="your-aas-token",
    device_codename="px_9a",
)
client.login()

details = client.details("com.google.android.calculator")
print(details["details"]["appDetails"]["versionString"])
```

### Download an APK

```python
from pathlib import Path

from googleplay import GooglePlayClient

client = GooglePlayClient(
    email="account@example.com",
    aas_token="your-aas-token",
)
client.login()

delivery = client.download("com.google.android.calculator")
apk_path = Path("calculator.apk")
with apk_path.open("wb") as handle:
    for chunk in delivery["file"].iter_content(client.session):
        if chunk:
            handle.write(chunk)
```

### Web search and public details

```python
from googleplay import WebPlayClient

client = WebPlayClient(lang="en", country="us")
results = client.search("calculator", n_hits=5)
print(results[0]["appId"])

public_details = client.details("com.google.android.calculator")
print(public_details["developerEmail"])
```

## AAS Token Setup

The authenticated client expects an AAS token, not a Google password.

A common flow is:

1. Open `https://accounts.google.com/EmbeddedSetup` in a browser.
2. Complete the sign-in flow.
3. Capture the `oauth_token` response cookie value.
4. Exchange that one-time token with `TokenExchangeClient`.

The EmbeddedSetup flow and the token exchange are unofficial and may change.

## Devices

The client ships with bundled Android device profiles and defaults to `px_9a`.
You can select a different bundled device with `device_codename=...` when you
construct `GooglePlayClient`.

## Testing

Run the offline test suite with:

```bash
pytest
```

Live tests are opt-in and require credentials:

```bash
export GOOGLEPLAY_TEST_EMAIL='account@example.com'
export GOOGLEPLAY_TEST_AAS_TOKEN='your-aas-token'
pytest tests/test_live.py
```

Optional live-test settings:

```bash
export GOOGLEPLAY_TEST_DEVICE='px_9a'
export GOOGLEPLAY_TEST_LOCALE='en_US'
export GOOGLEPLAY_TEST_TIMEZONE='UTC'
```

## Caveats

- This is not an official Google library.
- Private Google Play endpoints can change without notice.
- Some workflows depend on account state, device profile, and Play terms.
- Use a dedicated account for automated testing.

## Provenance

This project is informed by prior Google Play client work, including older
Python `gpapi` implementations and newer Rust-based clients. The current code is
packaged as a standalone Python library with its own tests and bundled runtime
assets.

## License

This repository is licensed under GPL-3.0-only. See [LICENSE](LICENSE).
