Metadata-Version: 2.4
Name: py2adobe_reporting
Version: 1.0.1
Summary: Data Engineering tool for accessing Adobe CJA Reporting API
Project-URL: Homepage, https://github.com/jaytmii/py2adobe_reporting_package
Project-URL: Repository, https://github.com/jaytmii/py2adobe_reporting_package
Project-URL: Issues, https://github.com/jaytmii/py2adobe_reporting_package/issues
Author-email: James Mitchell <jaytmii@gmail.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Requires-Dist: flask>=3.1.2
Requires-Dist: numpy>=2.2.4
Requires-Dist: pandas>=2.2.3
Requires-Dist: plotly>=6.5.0
Requires-Dist: psycopg2-binary>=2.9.10
Requires-Dist: pytz>=2024.1
Requires-Dist: requests>=2.32.3
Requires-Dist: sqlalchemy>=2.0.41
Requires-Dist: werkzeug>=3.1.5
Provides-Extra: dev
Requires-Dist: pylint>=4.0.4; extra == 'dev'
Requires-Dist: pytest>=8.2.2; extra == 'dev'
Description-Content-Type: text/markdown

# py2adobe_reporting

A Python wrapper for Adobe Customer Journey Analytics (CJA) Reporting API and Adobe Experience Platform (AEP) Data Distiller access that enables analysts to extract and analyze data programmatically.

## New in v1.0.0

### JSON Extractor Tool
A visual web-based tool that extracts table and visualization metadata from Adobe CJA Analysis Workspace projects and automatically generates API request bodies.

- **Import Workspace Projects** – Fetch any project by ID and extract all metadata
- **10+ Visualization Types** – Generates request bodies for Freeform Tables, Area Charts, Bar Charts, Key Metric Summary, and more
- **Smart Source Resolution** – Visualizations automatically inherit data from linked source tables
- **Component Mining** – Recursively extracts all segments, metrics, dimensions, and date ranges
- **Modern UI** – Dark theme with color-coded badges and collapsible sections

```python
from py2adobe_reporting.cja_functions.reporting_management import Reporting

reporting = Reporting()
url = reporting.json_extractor_launch(headers)
# Browser opens to the JSON Extractor UI

# When done:
reporting.json_extractor_stop()
```

See [JSON Extractor Documentation](docs/json_extractor.md) for full details.

## Features

- **Time Series Reports** - Flexible time-based reports with configurable granularity (minute, hour, day, week, month, quarter, year)
- **Multi-Metric Analysis** - Pull multiple metrics in a single report
- **Dimension Breakdowns** - Break down metrics by two dimensions simultaneously
- **Segmentation Support** - Segment your data for your reports to tailor your analysis
- **Top Items Analysis** - Get top 10 dimension items with optional search
- **Pagination Support** - Handle large datasets with automatic pagination (up to 50,000 rows per page)
- **Component Discovery** - List available segments, metrics, dimensions, and calculated metrics for a data view
- **JSON Extractor Tool** - Visual UI for extracting request bodies from Analysis Workspace projects
- **Data Distiller Access** - Connect to AEP Data Distiller databases and run SQL queries into pandas DataFrames
- **Server-to-Server Authentication** - Secure OAuth 2.0 authentication

## Installation

```bash
pip install py2adobe_reporting
```

Or install from source:

```bash
git clone https://github.com/jaytmii/py2adobe_reporting_package.git
cd py2adobe_reporting_package
pip install -e .
```

## Requirements

- Python >= 3.8
- Adobe CJA API credentials (OAuth 2.0 Server-to-Server)
- SQLAlchemy and a PostgreSQL-compatible driver for Data Distiller access

## Quick Start

### 1. Set Up Authentication

Create a JSON configuration file with your Adobe credentials:
```json
{
  "client_secret": "your-client-secret",
  "company_id": "your-company-id",
  "ims_host": "ims",
  "token_url": "token_url",
  "default_headers": {
    "x-api-key": "your-api-key",
    "x-gw-ims-org-id": "your-org-id"
  },
  "scopes": "api_scopes",
"db_user": "your-db-username",
"db_password": "your-db-password",
"db_host": "your-db-host",
"db_port": "5432",
"db_name": "your-db-name"
}
```

### 2. Authenticate

```python
from py2adobe_reporting.auth import s2s_auth

# Authenticate and get environment object
env = s2s_auth("path/to/config.json")
```

### 3. Generate Headers

```python
from py2adobe_reporting.auth import cja_oauth_headers

# Create headers for API calls
headers = cja_oauth_headers("path/to/config.json", env.token)
```

### 4. Pull a Report

```python
from py2adobe_reporting.cja_functions.reporting_management import Reporting

# Initialize reporting class
reporting = Reporting()

# Get daily time series report
df = reporting.get_granularity_report(
    headers=headers,
    data_view_id="your-data-view-id",
    start_date="2024-01-01",
    end_date="2024-01-31",
    dimension_id="variables/daterangeday",
    metric_id="metrics/visits",
    granularity="day"
)

print(df.head())
```

## Available Functions

### Core Reporting Methods
- `get_granularity_report()` - Time-series reports with configurable granularity
- `get_all_rows_report()` - All rows for a dimension with single or multiple metrics
- `get_breakdown_report()` - Break down metrics by two dimensions simultaneously
- `get_top_ten_dimension_items()` - Get top 10 items for a dimension with optional search

### Component Discovery
- `component_reports()` - Get available segments, dimensions, metrics for a data view
- `component_lookup()` - Map component IDs to names with automatic deduplication

### Low-Level Utilities
- `get_single_call_report()` - Single API call with custom request body
- `get_total_table_rows()` - Get total row count for a report configuration
- `get_total_table_pages()` - Calculate total pages needed

### JSON Extractor
- `json_extractor_launch()` - Launch the visual JSON extractor UI
- `json_extractor_stop()` - Stop the extractor server

### Data Distiller
- `DataDistillerAuth.connect_to_db()` - Build a SQLAlchemy engine for AEP Data Distiller
- `query_aep_sandbox_database_table()` - Execute SQL and return a pandas DataFrame

## Documentation

For detailed function parameters and examples, see:
- [Reporting Management Documentation](docs/reporting_management.md)
- [JSON Extractor Documentation](docs/json_extractor.md)

## Data Distiller Quick Start

```python
from py2adobe_reporting.auth import DataDistillerAuth
from py2adobe_reporting.cja_functions.reporting_management import Reporting

# Build DB engine from config file db_* keys
dd_auth = DataDistillerAuth("path/to/config.json")
engine = dd_auth.connect_to_db()

reporting = Reporting()
df = reporting.query_aep_sandbox_database_table(
    engine,
    "SELECT * FROM your_schema.your_table LIMIT 100"
)

print(df.head())
```

## Example Use Cases

### Get Daily Visits
```python
df = reporting.get_granularity_report(
    headers=headers,
    data_view_id="dv_123",
    start_date="2024-01-01",
    end_date="2024-01-31",
    dimension_id="variables/daterangeday",
    metric_id="metrics/visits",
    granularity="day"
)
```

### Get Monthly Visits

```python
df = reporting.get_granularity_report(
    headers=headers,
    data_view_id="dv_123",
    start_date="2024-01-01",
    end_date="2024-12-31",
    dimension_id="variables/daterangemonth",
    metric_id="metrics/visits",
    granularity="month"
)
```

### Get All Rows for a Dimension

```python
df = reporting.get_all_rows_report(
    headers=headers,
    data_view_id="dv_123",
    start_date="2024-01-01",
    end_date="2024-01-31",
    dimension_id="variables/page",
    metric_id="metrics/visits"
)
```

### Pull Multiple Metrics

```python
df = reporting.get_all_rows_report(
    headers=headers,
    data_view_id="dv_123",
    start_date="2024-01-01",
    end_date="2024-01-31",
    dimension_id="variables/page",
    metric_ids=["metrics/visits", "metrics/orders", "metrics/revenue"],
    multiple_metrics=True
)
```

### Breakdown by Multiple Dimensions

```python
df = reporting.get_breakdown_report(
    headers=headers,
    data_view_id="dv_123",
    start_date="2024-01-01",
    end_date="2024-01-31",
    dimension_id="variables/page",
    metric_id="metrics/visits",
    breakdown_dimension="variables/browser",
    segment_included=True,
    segment=["segment_id_123"]
)
```

### Search for Dimension Items

```python
df = reporting.get_top_ten_dimension_items(
    headers=headers,
    data_view_id="dv_123",
    start_date="2024-01-01",
    end_date="2024-01-31",
    dimension="variables/page",
    search_type="contain",
    contains_term="( CONTAINS 'product' )"
)
```

### Discover Available Components

```python
segments, dimensions, metrics, calc_metrics = reporting.component_reports(
    headers=headers,
    data_view_id="dv_123"
)
print(dimensions)  # View available dimensions
print(metrics)     # View available metrics
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Author

James Mitchell - jaytmii@gmail.com

