Metadata-Version: 2.4
Name: megaton
Version: 1.1.0
Summary: Python toolkit for running GA4 and Search Console reports in Colab/Notebooks and publishing results to Google Sheets, CSV, or BigQuery, with built-in retries and easy append/upsert.
Author-email: Makoto Shimizu <aa.analyst.ga@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/mak00s/megaton
Project-URL: Repository, https://github.com/mak00s/megaton
Project-URL: Documentation, https://github.com/mak00s/megaton/tree/main/docs
Project-URL: Issues, https://github.com/mak00s/megaton/issues
Project-URL: Changelog, https://github.com/mak00s/megaton/blob/main/CHANGELOG.md
Keywords: google-analytics,ga4,search-console,google-sheets,bigquery,jupyter,notebook,colab
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.3
Requires-Dist: google-api-python-client>=2.89
Requires-Dist: google-auth>=2.40.0
Requires-Dist: google-api-core>=2.25.0
Requires-Dist: google-auth-oauthlib>=1.0
Requires-Dist: google-analytics-data>=0.18
Requires-Dist: google-analytics-admin>=0.25.0
Requires-Dist: google-cloud-bigquery>=3.11
Requires-Dist: gspread>=5.7
Requires-Dist: oauthlib>=3.2
Requires-Dist: ipywidgets>=8.0
Requires-Dist: gspread-dataframe>=3.0
Requires-Dist: pytz>=2023.3
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Dynamic: license-file

# megaton

[![PyPI version](https://badge.fury.io/py/megaton.svg)](https://pypi.org/project/megaton/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Megaton is a Python toolkit for working with Google Analytics 4, Google Search Console, Google Sheets, and BigQuery from Notebooks with minimal code. It focuses on fast iteration during analysis and provides a UX tailored for Notebook workflows.

## Core Concepts

- **Result objects** — Method chaining via `SearchResult` / `ReportResult`
- **Simple flow** — Open → Set dates → Run → Save
- **Notebook-first** — Designed for inspecting intermediate results at every step

## Quick Start

### Prerequisites

You need a Google Cloud **service account JSON** file with access to GA4, Search Console, or Sheets.
See [Google Cloud docs](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) for how to create one.

### Install

```bash
pip install megaton
```

### Run a GA4 report and save to Google Sheets

```python
from megaton.start import Megaton

mg = Megaton("/path/to/service_account.json")

# GA4: fetch event data
mg.report.set.dates("2024-01-01", "2024-01-31")
result = mg.report.run(d=["date", "eventName"], m=["eventCount"])

# Save to Google Sheets
mg.open.sheet("https://docs.google.com/spreadsheets/d/...")
mg.save.to.sheet("_ga_data", result.df)
```

### Run the same report over multiple date ranges

```python
df = mg.report.run.ranges(
    date_ranges=[("2024-01-01", "2024-01-31"), ("2025-01-01", "2025-01-31")],
    d=["date", "eventName"],
    m=["eventCount"],
)
```

### Read a worksheet as DataFrame

```python
mg.open.sheet("https://docs.google.com/spreadsheets/d/...")
daily_df = mg.sheets.read("daily")
```

### Duplicate a worksheet and patch a cell

```python
mg.open.sheet("https://docs.google.com/spreadsheets/d/...")
mg.sheets.duplicate(
    "template",
    "report_2024_02",
    cell_update={"cell": "B1", "value": "202402"},
)
```

### Search Console with method chaining

```python
# query_map: dict mapping regex patterns to category names
# e.g. {"brand.*keyword": "Brand", ".*": "(other)"}
result = (mg.search
    .run(dimensions=['query', 'page'], clean=True)
    .categorize('query', by=query_map)
    .filter_impressions(min=100)
)

mg.save.to.sheet('_query', result.df, sort_by='impressions')
```

## Installation

```bash
# From PyPI
pip install megaton

# Latest from GitHub
pip install git+https://github.com/mak00s/megaton.git
```

## Documentation

> **Note:** Detailed docs are written in Japanese.

If you're new, start with the **cookbook** for practical examples, then refer to the **API reference** for details.

| Doc | Description |
|-----|-------------|
| [cookbook.md](docs/cookbook.md) | Practical recipes — start here |
| [api-reference.md](docs/api-reference.md) | Full API reference (single source of truth) |
| [cheatsheet.md](docs/cheatsheet.md) | One-line quick reference |
| [design.md](docs/design.md) | Design philosophy and trade-offs |

## Testing & Coverage

```bash
pytest --cov=megaton --cov-report=term-missing
```

- Coverage tracking excludes `megaton/ga3.py`.
- Rationale: GA3 (Universal Analytics) is a legacy compatibility module and is outside the active quality gate for current GA4/Search Console workflows.

## Changelog

- [CHANGELOG.md](CHANGELOG.md)
- [docs/changelog-archive.md](docs/changelog-archive.md) — 0.x series history

## License

MIT License
