instapipe 0.1.0__tar.gz

instapipe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aroaxinping
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

instapipe-0.1.0/PKG-INFO

@@ -0,0 +1,361 @@
+Metadata-Version: 2.4
+Name: instapipe
+Version: 0.1.0
+Summary: Data pipeline for Instagram analytics. Your Meta Business Suite exports in, real metrics out.
+Author: aroaxinping
+License-Expression: MIT
+Keywords: instagram,analytics,data-pipeline,content-creator,reels
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.0
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: seaborn>=0.13
+Provides-Extra: dashboard
+Requires-Dist: plotly>=5.0; extra == "dashboard"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Dynamic: license-file
+
+# instapipe
+
+[![CI](https://github.com/aroaxinping/instapipe/actions/workflows/ci.yml/badge.svg)](https://github.com/aroaxinping/instapipe/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/Python-3.10%2B-blue?logo=python)
+![License](https://img.shields.io/badge/License-MIT-green)
+![Meta Business Suite](https://img.shields.io/badge/Data%20source-Meta%20Business%20Suite-1877F2?logo=meta)
+
+Data pipeline for Instagram analytics. Import your exported data from Meta Business Suite, clean it, compute real metrics, and visualize what actually works.
+
+No APIs, no scraping, no third-party tokens. Just your Instagram export files (CSV/XLSX) and Python.
+
+### Why instapipe?
+
+Most Instagram analytics tools are either paid dashboards, require API tokens, or scrape data in ways that break with every update. instapipe takes a different approach: you export your own data from Meta Business Suite (a manual download, 30 seconds), and instapipe does the rest — cleaning, metric computation, and visualization. You own your data, you control the pipeline, and you can extend it however you want.
+
+---
+
+## What it generates
+
+<p align="center">
+  <img src="examples/output/engagement.png" alt="Engagement Rate Distribution" width="48%"/>
+  <img src="examples/output/best_hours.png" alt="Best Posting Hours" width="48%"/>
+</p>
+<p align="center">
+  <img src="examples/output/top_reels.png" alt="Top Reels by Engagement" width="48%"/>
+  <img src="examples/output/save_rate.png" alt="Save Rate vs Engagement" width="48%"/>
+</p>
+
+> Generated from sample data included in `examples/`. Try it yourself:
+> ```bash
+> instapipe analyze examples/sample_data.csv --output results/
+> ```
+
+---
+
+## Architecture
+
+```
+instapipe follows a classic ETL pipeline structure:
+
+  Export (Meta Business Suite CSV/XLSX)
+        |
+        v
+  +-----------+
+  |  ingest   |  --> Load and validate raw export files (utf-8-sig & utf-16)
+  +-----------+
+        |
+        v
+  +-----------+
+  |  clean    |  --> Normalize columns (ES/EN), fix types, parse dates
+  +-----------+
+        |
+        v
+  +-----------+
+  |  metrics  |  --> Compute engagement, save rate, share rate, conversion
+  +-----------+
+        |
+        v
+  +-----------+
+  |  output   |  --> Dataframes, CSV export, visualizations
+  +-----------+
+```
+
+### Modules
+
+| Module | What it does |
+|---|---|
+| `instapipe.ingest` | Reads Instagram export files (CSV, XLSX). Handles Meta Business Suite's utf-16 daily CSVs and utf-8-sig content CSVs transparently. |
+| `instapipe.clean` | Maps column names (Spanish/English) to internal names, converts date/number types, parses publication time into date, hour, and day of week. |
+| `instapipe.metrics` | Computes derived metrics: engagement rate (based on reach), save rate, share rate, follower conversion rate, best posting hour/day. |
+| `instapipe.output` | Exports results to CSV/JSON. Generates matplotlib/seaborn visualizations (engagement distribution, best hours, save rate scatter, top reels). |
+
+---
+
+## Requirements
+
+### 1. Instagram Professional Account (Creator or Business)
+
+The free personal Instagram account does not give you access to analytics. You need to switch to a **Professional** account — it's free and takes 30 seconds.
+
+**How to switch:**
+1. Open Instagram > your profile > **Settings and privacy**
+2. Scroll to **Account type and tools** > **Switch to professional account**
+3. Choose **Creator** (recommended for content creators) or **Business**
+4. Pick a category that describes you (e.g. Digital Creator, Personal Blog, Entrepreneur)
+5. Tap **Done**
+
+Once you switch, Instagram starts collecting analytics for your account. You'll see a new **Insights** button on your profile and on each post.
+
+> **Note:** Instagram only starts tracking metrics from the moment you switch. You won't have historical data from before the switch. If you just switched, wait at least 7 days and publish some content before exporting — otherwise you'll have an empty file.
+
+### 2. Meta Business Suite (free)
+
+Meta Business Suite is the web tool where you export your Instagram data as CSV files. It's free, provided by Meta, and automatically available when you have a professional Instagram account.
+
+**How to access it:**
+1. Go to [business.facebook.com](https://business.facebook.com) from a desktop browser
+2. Log in with the **Facebook account linked to your Instagram** — if you don't have one linked, Instagram prompts you to create or connect a Facebook Page when you switch to a professional account
+3. Once inside, click **Insights** in the left sidebar
+4. Make sure your Instagram account appears at the top — if it does, you're ready to export
+
+> **Don't have a Facebook account linked?** Go to Instagram > Settings > Accounts Center > Accounts > Add Facebook account. You need this connection for Meta Business Suite to see your Instagram data.
+
+### 3. Export your data
+
+instapipe works with CSV files exported from Meta Business Suite. There are two types:
+
+#### Content/Posts CSV (the main one — required)
+
+This is the file with one row per Reel/post and all the metrics for each one.
+
+1. Open [Meta Business Suite](https://business.facebook.com) > **Insights** > **Content**
+2. Filter by **Instagram** (top left, make sure you're not looking at Facebook)
+3. Select the **date range** you want to analyze (e.g. last 28 days)
+4. Click **Export** (top right corner) > choose **CSV**
+5. A file like `Contenido_Posts_Feb24_Mar23.csv` downloads
+
+This CSV includes: description, publication time, views, reach, likes, comments, saves, shares, followers gained, duration, and permalink for each Reel/post.
+
+#### Daily metric CSVs (optional — for trend analysis)
+
+These are individual CSVs with one data point per day for a specific metric (e.g. daily reach, daily views).
+
+1. Open Meta Business Suite > **Insights** > **Overview**
+2. For each metric you want (Reach, Views, Followers, Interactions, Profile visits), click the small **Export** icon next to it
+3. Each one downloads as a separate CSV (e.g. `Alcance.csv`, `Visualizaciones.csv`, `Seguidores.csv`)
+
+These files use **utf-16 encoding** with a 3-line header — instapipe handles this automatically, you don't need to do anything special.
+
+### 4. Python >= 3.10
+
+```bash
+python3 --version  # Should be 3.10 or higher
+```
+
+All Python dependencies are installed automatically when you run `pip install`: pandas, openpyxl, matplotlib, seaborn.
+
+---
+
+## Installation
+
+```bash
+# Clone the repo
+git clone https://github.com/aroaxinping/instapipe.git
+cd instapipe
+
+# Create a virtual environment (recommended)
+python -m venv .venv
+source .venv/bin/activate
+
+# Install in editable mode with all dependencies
+pip install -e .
+```
+
+---
+
+## Usage
+
+### 1. Quick run (CLI)
+
+```bash
+instapipe analyze path/to/Contenido_Posts.csv --output results/
+```
+
+This runs the full pipeline (ingest -> clean -> metrics -> output) and saves a CSV report + charts to the output directory.
+
+### 2. Python API
+
+```python
+from instapipe import ingest, clean, metrics, output
+
+# Load your content/posts export
+raw = ingest.load("path/to/Contenido_Posts.csv")
+
+# Clean and normalize
+df = clean.normalize(raw)
+
+# Compute metrics
+report = metrics.compute(df)
+
+# Print summary
+print(report.summary())
+
+# Export results
+output.to_csv(report, "results.csv")
+
+# Generate visualizations
+output.plot_engagement(report, save_to="engagement.png")
+output.plot_best_hours(report, save_to="best_hours.png")
+output.plot_save_rate(report, save_to="save_rate.png")
+output.plot_top_reels(report, save_to="top_reels.png")
+```
+
+### 3. Daily metrics (optional)
+
+For the individual daily metric CSVs exported from Meta Business Suite Overview:
+
+```python
+from instapipe.ingest import load_daily
+
+views = load_daily("Visualizaciones.csv", "visualizaciones")
+reach = load_daily("Alcance.csv", "alcance")
+followers = load_daily("Seguidores.csv", "seguidores_ganados")
+```
+
+---
+
+## Available metrics
+
+| Metric | Formula | Why this denominator |
+|---|---|---|
+| Engagement rate | (likes + comments + saves + shares) / reach x 100 | Reach = unique accounts. Industry standard for Instagram. |
+| Save rate | saves / reach x 100 | Saves are the strongest quality signal on Instagram. |
+| Share rate | shares / views x 100 | Shares drive distribution, measured against total impressions. |
+| Follower conversion | followers gained / reach x 100 | How efficiently a Reel converts viewers into followers. |
+| Best posting hour | Hour with highest median engagement | Based on your own data, not generic advice. |
+| Best posting day | Day of week with highest median engagement | Same — your audience, your data. |
+| Top performers | Reels above 90th percentile engagement | Focus on what actually works for you. |
+
+---
+
+## Instagram vs TikTok metrics
+
+If you also use TikTok, check out [tokpipe](https://github.com/aroaxinping/tokpipe) — same philosophy, adapted for TikTok exports.
+
+Key differences:
+- **Instagram** uses **reach** (unique accounts) as the engagement denominator. **TikTok** uses **views** (total plays).
+- Instagram exports come from **Meta Business Suite** (utf-16 daily CSVs + utf-8-sig content CSVs). TikTok exports come from **TikTok Studio** (XLSX/CSV).
+- Instagram has **saves** as a key metric. TikTok has **watch time** and **completion rate**.
+
+---
+
+## Try it without an Instagram account
+
+The repo includes a sample CSV with 10 fake reels so you can try the full pipeline immediately:
+
+```bash
+# After installation
+instapipe analyze examples/sample_data.csv --output results/
+```
+
+This generates:
+- `results/report.csv` — cleaned data with all computed metrics
+- `results/engagement.png` — engagement rate distribution
+- `results/best_hours.png` — best posting hours
+- `results/save_rate.png` — save rate vs engagement scatter
+- `results/top_reels.png` — top reels by engagement rate
+
+---
+
+## Troubleshooting
+
+### `ModuleNotFoundError: No module named 'instapipe'`
+
+You haven't installed instapipe or your virtual environment isn't active.
+
+```bash
+source .venv/bin/activate   # activate the venv
+pip install -e .             # install instapipe
+```
+
+### `ValueError: Could not find a reach or views column`
+
+Your CSV column names don't match what instapipe expects. This usually happens when Meta Business Suite exports in a language other than Spanish or English.
+
+Check your CSV header row:
+```bash
+head -1 your_file.csv
+```
+
+If the columns are in another language, open an issue with the header row and we'll add support for it.
+
+### `UnicodeDecodeError` when loading a daily metric CSV
+
+Use `load_daily()` instead of `load()` for the individual daily metric CSVs (Alcance.csv, Visualizaciones.csv, etc.) — they use utf-16 encoding:
+
+```python
+from instapipe.ingest import load_daily
+df = load_daily("Alcance.csv", "alcance")
+```
+
+### `FileNotFoundError`
+
+Double-check the path to your CSV file. If your file has spaces in the name, wrap the path in quotes:
+
+```bash
+instapipe analyze "path/to/My Export File.csv"
+```
+
+### Charts look wrong or empty
+
+Make sure your CSV has at least 3-5 rows of data. Charts generated from 1-2 reels won't be very informative.
+
+---
+
+## Project structure
+
+```
+instapipe/
+  src/
+    instapipe/
+      __init__.py       # Package init, version
+      ingest.py         # Load Meta Business Suite exports
+      clean.py          # Normalize and clean data
+      metrics.py        # Compute derived metrics
+      output.py         # Export and visualize
+      cli.py            # Command-line interface
+  tests/
+    test_ingest.py
+    test_clean.py
+    test_metrics.py
+  examples/
+    sample_data.csv     # Fake dataset (10 reels) for testing
+    output/             # Pre-generated charts from sample data
+    basic_analysis.py   # Minimal working example
+  .github/
+    workflows/ci.yml    # CI pipeline (pytest on Python 3.10-3.13)
+    ISSUE_TEMPLATE/     # Bug report & feature request templates
+  pyproject.toml        # Package config
+  LICENSE
+  CONTRIBUTING.md
+  README.md
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).