instapost 0.1.0__tar.gz

instapost-0.1.0/.gitignore

@@ -0,0 +1,138 @@
+*.ipynb
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+*.ipynb
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Project specific
+*.pem
+*.key
+.flake8

instapost-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Blaya Luz
+
+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.

instapost-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include requirements.txt
+recursive-exclude * __pycache__
+recursive-exclude * *.py[cod]
+recursive-exclude tests *

instapost-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: instapost
+Version: 0.1.0
+Summary: A Python library for automating Instagram posting (images, reels, carousels)
+Project-URL: Homepage, https://blaya.ia.br
+Project-URL: Repository, https://github.com/pedroluz/instapost
+Project-URL: Documentation, https://github.com/pedroluz/instapost#readme
+Project-URL: Issues, https://github.com/pedroluz/instapost/issues
+Author-email: Pedro Luz <blaya.luz@gmail.com>
+Maintainer-email: Pedro Luz <blaya.luz@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: automation,carousel,graph-api,instagram,meta,reels,social-media
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Office/Business
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# instapost
+
+
+<img src="logo.png" width="300px" align="right" alt="logo">
+
+A simple and powerful Python library for posting to Instagram using the Instagram Graph API. 
+
+Post images, reels, and carousels with just a few lines of code. Auto-upload local files or use remote URLs. 
+
+
+
+
+**How it works:**
+
+```python
+from instapost import InstagramPoster
+
+poster = InstagramPoster(access_token="YOUR_TOKEN",
+                         ig_user_id="YOUR_IG_ID"
+)
+
+poster.post_image(image="./photo.jpg",
+                  caption="Check this out! 📸")
+```
+
+That's it. Your photo is on Instagram.
+
+## Setup (5 minutes)
+
+**What you need:**
+- Instagram Business account (connected to Facebook)
+- Meta for Developers account (free)
+
+**Steps:**
+
+1. Create a Meta App → [developers.facebook.com/apps/create](https://developers.facebook.com/apps/create/)
+2. Click **Add Product** and set up Instagram
+3. In **App Roles > Roles**, assign **Instagram Tester** to your account
+4. Go to **Instagram > API Setup with Instagram login**, add your account, click **Generate token**
+5. Copy the token—you're done!
+
+✨ **That's it.** No app review needed for personal use. Your token works immediately in Development Mode.
+
+## Usage
+
+```python
+from instapost import InstagramPoster
+
+poster = InstagramPoster(
+    access_token="YOUR_TOKEN",
+    ig_user_id="YOUR_IG_ID"
+)
+
+# Post an image
+poster.post_image(image="./photo.jpg", caption="Check this out! 📸")
+
+# Post a reel
+poster.post_reel(video="./video.mp4", caption="New reel! 🎬", share_to_feed=True)
+
+# Post a carousel
+poster.post_carousel(
+    media_urls=[
+        {"media": "./photo1.jpg", "type": "IMAGE"},
+        {"media": "./video.mp4", "type": "VIDEO"},
+    ],
+    caption="Swipe through! 👉"
+)
+
+# Verify you're connected
+print(poster.verify()['username'])
+```
+
+**Local files?** Just pass the file path—instapost auto-uploads to Catbox. Remote URLs work too. Mix them in one post.
+
+## Requirements
+
+- Instagram Business account connected to Facebook
+- Meta for Developers account (free)
+- Python 3.7+
+
+## Installation
+
+```bash
+pip install instapost
+```
+
+## Media Specs
+
+| Type | Format | Size | Duration |
+|------|--------|------|----------|
+| Images | JPEG, PNG, WebP, GIF | ≤ 8MB | — |
+| Reels | MP4 | ≤ 1GB | 3-90s |
+| Carousel | 2-10 items | per item | — |
+
+## How it works
+
+- **Local files** → Auto-upload to Catbox → Send to Instagram API
+- **Remote URLs** → Send directly to Instagram API
+
+## Learn more
+
+- [Instagram Graph API Docs](https://developers.facebook.com/docs/instagram-platform/content-publishing)
+- [Meta for Developers](https://developers.facebook.com)

instapost-0.1.0/README.md

@@ -0,0 +1,103 @@
+# instapost
+
+
+<img src="logo.png" width="300px" align="right" alt="logo">
+
+A simple and powerful Python library for posting to Instagram using the Instagram Graph API. 
+
+Post images, reels, and carousels with just a few lines of code. Auto-upload local files or use remote URLs. 
+
+
+
+
+**How it works:**
+
+```python
+from instapost import InstagramPoster
+
+poster = InstagramPoster(access_token="YOUR_TOKEN",
+                         ig_user_id="YOUR_IG_ID"
+)
+
+poster.post_image(image="./photo.jpg",
+                  caption="Check this out! 📸")
+```
+
+That's it. Your photo is on Instagram.
+
+## Setup (5 minutes)
+
+**What you need:**
+- Instagram Business account (connected to Facebook)
+- Meta for Developers account (free)
+
+**Steps:**
+
+1. Create a Meta App → [developers.facebook.com/apps/create](https://developers.facebook.com/apps/create/)
+2. Click **Add Product** and set up Instagram
+3. In **App Roles > Roles**, assign **Instagram Tester** to your account
+4. Go to **Instagram > API Setup with Instagram login**, add your account, click **Generate token**
+5. Copy the token—you're done!
+
+✨ **That's it.** No app review needed for personal use. Your token works immediately in Development Mode.
+
+## Usage
+
+```python
+from instapost import InstagramPoster
+
+poster = InstagramPoster(
+    access_token="YOUR_TOKEN",
+    ig_user_id="YOUR_IG_ID"
+)
+
+# Post an image
+poster.post_image(image="./photo.jpg", caption="Check this out! 📸")
+
+# Post a reel
+poster.post_reel(video="./video.mp4", caption="New reel! 🎬", share_to_feed=True)
+
+# Post a carousel
+poster.post_carousel(
+    media_urls=[
+        {"media": "./photo1.jpg", "type": "IMAGE"},
+        {"media": "./video.mp4", "type": "VIDEO"},
+    ],
+    caption="Swipe through! 👉"
+)
+
+# Verify you're connected
+print(poster.verify()['username'])
+```
+
+**Local files?** Just pass the file path—instapost auto-uploads to Catbox. Remote URLs work too. Mix them in one post.
+
+## Requirements
+
+- Instagram Business account connected to Facebook
+- Meta for Developers account (free)
+- Python 3.7+
+
+## Installation
+
+```bash
+pip install instapost
+```
+
+## Media Specs
+
+| Type | Format | Size | Duration |
+|------|--------|------|----------|
+| Images | JPEG, PNG, WebP, GIF | ≤ 8MB | — |
+| Reels | MP4 | ≤ 1GB | 3-90s |
+| Carousel | 2-10 items | per item | — |
+
+## How it works
+
+- **Local files** → Auto-upload to Catbox → Send to Instagram API
+- **Remote URLs** → Send directly to Instagram API
+
+## Learn more
+
+- [Instagram Graph API Docs](https://developers.facebook.com/docs/instagram-platform/content-publishing)
+- [Meta for Developers](https://developers.facebook.com)

instapost-0.1.0/instapost/__init__.py

@@ -0,0 +1,22 @@
+from .exceptions import (
+    InstagramAPIError,
+    ContainerProcessingError,
+    ContainerTimeoutError,
+)
+from .api.base import BaseInstagramClient
+from .posting.image import ImagePoster
+from .posting.reel import ReelPoster
+from .posting.carousel import CarouselPoster
+from .client import InstagramPoster
+
+__all__ = [
+    "InstagramPoster",
+    "ImagePoster",
+    "ReelPoster",
+    "CarouselPoster",
+    "BaseInstagramClient",
+    "InstagramAPIError",
+    "ContainerProcessingError",
+    "ContainerTimeoutError",
+]
+__version__ = "0.1.0"

instapost-0.1.0/instapost/api/__init__.py

@@ -0,0 +1,3 @@
+from .base import BaseInstagramClient
+
+__all__ = ["BaseInstagramClient"]

instapost-0.1.0/instapost/api/base.py

@@ -0,0 +1,83 @@
+import requests
+import time
+from abc import ABC, abstractmethod
+
+from ..exceptions import ContainerProcessingError, ContainerTimeoutError
+
+
+class BaseInstagramClient(ABC):
+    """Base class for Instagram API clients."""
+
+    BASE_URL = "https://graph.instagram.com"
+
+    def __init__(self, access_token: str, ig_user_id: str):
+        self.access_token = access_token
+        self.ig_user_id = ig_user_id
+
+    def _request(self, method: str, endpoint: str, **kwargs) -> dict:
+        """Make a request to the Graph API."""
+        url = f"{self.BASE_URL}/{endpoint}"
+        kwargs.setdefault("params", {})["access_token"] = self.access_token
+        response = requests.request(method, url, **kwargs)
+        response.raise_for_status()
+        return response.json()
+
+    def _create_container(self, params: dict) -> str:
+        """Create a media container and return its ID."""
+        result = self._request("POST", "me/media", params=params)
+        return result["id"]
+
+    def _publish_container(self, container_id: str) -> dict:
+        """Publish a media container."""
+        return self._request(
+            "POST",
+            "me/media_publish",
+            params={"creation_id": container_id},
+        )
+
+    def _wait_for_container(self, container_id: str, timeout: int = 60, interval: int = 5) -> None:
+        """Wait for a media container to finish processing."""
+        elapsed = 0
+        while elapsed < timeout:
+            result = self._request("GET", container_id, params={"fields": "status_code,status"})
+            status = result.get("status_code")
+
+            if status == "FINISHED":
+                return
+            if status == "ERROR":
+                raise ContainerProcessingError(f"Container processing failed: {result.get('status')}")
+
+            time.sleep(interval)
+            elapsed += interval
+
+        raise ContainerTimeoutError(f"Container {container_id} did not finish processing in {timeout}s")
+
+    def verify(self) -> dict:
+        """Verify credentials and return account info."""
+        return self._request(
+            "GET",
+            "me",
+            params={"fields": "id,username,name"},
+        )
+
+    def publish(self, container_id: str) -> dict:
+        """
+        Publish a previously uploaded media container.
+
+        Args:
+            container_id: The container ID returned by upload().
+
+        Returns:
+            API response with the published media ID.
+        """
+        return self._publish_container(container_id)
+
+    @abstractmethod
+    def upload(self, *args, **kwargs) -> str:
+        """Upload content and return the container ID."""
+        pass
+
+    def post(self, *args, **kwargs) -> dict:
+        """Upload and publish content in one step."""
+        container_id = self.upload(*args, **kwargs)
+        return self.publish(container_id)

instapost-0.1.0/instapost/client.py

@@ -0,0 +1,118 @@
+from typing import Optional
+import os
+
+from .api.base import BaseInstagramClient
+from .posting.image import ImagePoster
+from .posting.reel import ReelPoster
+from .posting.carousel import CarouselPoster
+from .media.uploader import MediaUploader
+
+
+class InstagramPoster(BaseInstagramClient):
+    """Unified client for posting images, reels, and carousels to Instagram."""
+
+    def __init__(self, access_token: str, ig_user_id: str):
+        super().__init__(access_token, ig_user_id)
+        self._image = ImagePoster(access_token, ig_user_id)
+        self._reel = ReelPoster(access_token, ig_user_id)
+        self._carousel = CarouselPoster(access_token, ig_user_id)
+
+    def upload(self, *args, **kwargs) -> str:
+        """Upload content. Use upload_image, upload_reel, or upload_carousel for specific types."""
+        raise NotImplementedError("Use upload_image, upload_reel, or upload_carousel instead")
+
+    def post(self, *args, **kwargs) -> dict:
+        """Post content. Use post_image, post_reel, or post_carousel for specific types."""
+        raise NotImplementedError("Use post_image, post_reel, or post_carousel instead")
+
+    # Image methods
+    def upload_image(self, image_url: str, caption: str = "") -> str:
+        """Upload a single image and return container ID."""
+        return self._image.upload(image_url, caption)
+
+    def post_image(self, image_url: str, caption: str = "") -> dict:
+        """Upload and publish a single image.
+
+        Args:
+            image_url: URL or local file path to image
+            caption: Optional caption
+
+        Returns:
+            API response with published media ID
+        """
+        # Auto-upload if local file
+        if os.path.exists(image_url):
+            image_url = MediaUploader.upload_image(image_url)
+
+        return self._image.post(image_url, caption)
+
+    # Reel methods
+    def upload_reel(
+        self,
+        video_url: str,
+        caption: str = "",
+        cover_url: Optional[str] = None,
+        share_to_feed: bool = True,
+        timeout: int = 120,
+    ) -> str:
+        """Upload a reel and return container ID."""
+        return self._reel.upload(video_url, caption, cover_url, share_to_feed, timeout)
+
+    def post_reel(
+        self,
+        video_url: str,
+        caption: str = "",
+        cover_url: Optional[str] = None,
+        share_to_feed: bool = True,
+        timeout: int = 120,
+    ) -> dict:
+        """Upload and publish a reel.
+
+        Args:
+            video_url: URL or local file path to video
+            caption: Optional caption
+            cover_url: Optional URL or local path to cover image
+            share_to_feed: Whether to also share to feed
+            timeout: Video processing timeout in seconds
+
+        Returns:
+            API response with published media ID
+        """
+        # Auto-upload if local files
+        if os.path.exists(video_url):
+            video_url = MediaUploader.upload_video(video_url)
+
+        if cover_url and os.path.exists(cover_url):
+            cover_url = MediaUploader.upload_image(cover_url)
+
+        return self._reel.post(video_url, caption, cover_url, share_to_feed, timeout)
+
+    # Carousel methods
+    def upload_carousel(self, media_urls: list[dict], caption: str = "") -> str:
+        """Upload a carousel and return container ID."""
+        return self._carousel.upload(media_urls, caption)
+
+    def post_carousel(self, media_urls: list[dict], caption: str = "") -> dict:
+        """Upload and publish a carousel.
+
+        Args:
+            media_urls: List of dicts with 'media' (local file path or publicly accessible URL)
+                       and 'type' keys. Type must be 'IMAGE' or 'VIDEO'
+            caption: Optional caption
+
+        Returns:
+            API response with published media ID
+        """
+        # Auto-upload local files
+        processed_urls = []
+        for item in media_urls:
+            media = item['media']
+            if os.path.exists(media):
+                media = MediaUploader.upload(media)
+
+            processed_urls.append({
+                'media': media,
+                'type': item['type']
+            })
+
+        return self._carousel.post(processed_urls, caption)

instapost-0.1.0/instapost/exceptions.py

@@ -0,0 +1,13 @@
+class InstagramAPIError(Exception):
+    """Raised when Instagram API returns an error."""
+    pass
+
+
+class ContainerProcessingError(InstagramAPIError):
+    """Raised when a media container fails to process."""
+    pass
+
+
+class ContainerTimeoutError(InstagramAPIError):
+    """Raised when a media container times out during processing."""
+    pass

instapost-0.1.0/instapost/media/__init__.py

@@ -0,0 +1,3 @@
+from .uploader import MediaUploader
+
+__all__ = ["MediaUploader"]