instapost 0.1.0__py3-none-any.whl

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/api/__init__.py

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

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/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/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/media/__init__.py

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

instapost/media/uploader.py

@@ -0,0 +1,115 @@
+"""
+Media upload utilities for converting local files to public URLs.
+Uses Catbox for all file uploads (images and videos).
+"""
+
+import os
+import requests
+from pathlib import Path
+
+
+class MediaUploader:
+    """Upload local media files to Catbox and return public URLs."""
+
+    CATBOX_UPLOAD_URL = "https://catbox.moe/user/api.php"
+
+    # Supported file extensions
+    SUPPORTED_IMAGES = {'.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'}
+    SUPPORTED_VIDEOS = {'.mp4', '.mov', '.avi', '.mkv', '.flv', '.wmv', '.m4v'}
+
+    @classmethod
+    def upload(cls, file_path: str) -> str:
+        """
+        Upload a media file (image or video) to Catbox.
+
+        Args:
+            file_path: Path to local media file
+
+        Returns:
+            Public URL of the uploaded file
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ValueError: If file type is not supported
+            requests.RequestException: If upload fails
+        """
+        if not os.path.exists(file_path):
+            raise FileNotFoundError(f"Media file not found: {file_path}")
+
+        file_ext = Path(file_path).suffix.lower()
+
+        # Validate file type
+        if file_ext not in (cls.SUPPORTED_IMAGES | cls.SUPPORTED_VIDEOS):
+            raise ValueError(
+                f"Unsupported file type: {file_ext}. "
+                f"Supported: {cls.SUPPORTED_IMAGES | cls.SUPPORTED_VIDEOS}"
+            )
+
+        return cls._upload_to_catbox(file_path)
+
+    @classmethod
+    def upload_image(cls, image_path: str) -> str:
+        """
+        Upload an image to Catbox.
+
+        Args:
+            image_path: Path to local image file
+
+        Returns:
+            Public URL of the uploaded image
+        """
+        if not os.path.exists(image_path):
+            raise FileNotFoundError(f"Image file not found: {image_path}")
+
+        file_ext = Path(image_path).suffix.lower()
+        if file_ext not in cls.SUPPORTED_IMAGES:
+            raise ValueError(f"Unsupported image format: {file_ext}")
+
+        return cls._upload_to_catbox(image_path)
+
+    @classmethod
+    def upload_video(cls, video_path: str) -> str:
+        """
+        Upload a video to Catbox.
+
+        Args:
+            video_path: Path to local video file
+
+        Returns:
+            Public URL of the uploaded video
+        """
+        if not os.path.exists(video_path):
+            raise FileNotFoundError(f"Video file not found: {video_path}")
+
+        file_ext = Path(video_path).suffix.lower()
+        if file_ext not in cls.SUPPORTED_VIDEOS:
+            raise ValueError(f"Unsupported video format: {file_ext}")
+
+        return cls._upload_to_catbox(video_path)
+
+    @classmethod
+    def _upload_to_catbox(cls, file_path: str) -> str:
+        """
+        Internal method to upload file to Catbox.
+
+        Args:
+            file_path: Path to file
+
+        Returns:
+            Public URL
+
+        Raises:
+            requests.RequestException: If upload fails
+        """
+        with open(file_path, 'rb') as f:
+            files = {'fileToUpload': f}
+            data = {'reqtype': 'fileupload'}
+            response = requests.post(cls.CATBOX_UPLOAD_URL, data=data, files=files)
+
+        response.raise_for_status()
+        url = response.text.strip()
+
+        if not url or url.startswith('error'):
+            raise requests.RequestException(f"Catbox upload failed: {url}")
+
+        return url

instapost/posting/__init__.py

@@ -0,0 +1,5 @@
+from .image import ImagePoster
+from .reel import ReelPoster
+from .carousel import CarouselPoster
+
+__all__ = ["ImagePoster", "ReelPoster", "CarouselPoster"]

instapost/posting/carousel.py

@@ -0,0 +1,52 @@
+from ..api.base import BaseInstagramClient
+
+
+class CarouselPoster(BaseInstagramClient):
+    """Post carousels (multiple images/videos) to Instagram."""
+
+    MIN_ITEMS = 2
+    MAX_ITEMS = 10
+
+    def upload(self, media_urls: list[dict], caption: str = "") -> str:
+        """
+        Upload a carousel to Instagram.
+
+        Args:
+            media_urls: List of dicts with 'media' (local file path or publicly accessible URL)
+                       and 'type' ('IMAGE' or 'VIDEO') keys.
+            caption: Optional caption for the carousel.
+
+        Returns:
+            Container ID for publishing.
+        """
+        if not self.MIN_ITEMS <= len(media_urls) <= self.MAX_ITEMS:
+            raise ValueError(f"Carousel must have between {self.MIN_ITEMS} and {self.MAX_ITEMS} items")
+
+        children_ids = [self._create_child(media) for media in media_urls]
+        return self._create_container({
+            "media_type": "CAROUSEL",
+            "children": ",".join(children_ids),
+            "caption": caption,
+        })
+
+    def post(self, media_urls: list[dict], caption: str = "") -> dict:
+        """Upload and publish a carousel."""
+        return self.publish(self.upload(media_urls, caption))
+
+    def _create_child(self, media: dict) -> str:
+        """Create a child container for a carousel item."""
+        media_type = media.get("type", "IMAGE").upper()
+        params = {"is_carousel_item": "true"}
+
+        if media_type == "IMAGE":
+            params["image_url"] = media["media"]
+        else:
+            params["media_type"] = "VIDEO"
+            params["video_url"] = media["media"]
+
+        container_id = self._create_container(params)
+
+        if media_type == "VIDEO":
+            self._wait_for_container(container_id)
+
+        return container_id

instapost/posting/image.py

@@ -0,0 +1,22 @@
+from ..api.base import BaseInstagramClient
+
+
+class ImagePoster(BaseInstagramClient):
+    """Post single images to Instagram."""
+
+    def upload(self, image: str, caption: str = "") -> str:
+        """
+        Upload a single image to Instagram.
+
+        Args:
+            image: Local file path or publicly accessible URL of the image (JPEG, max 8MB).
+            caption: Optional caption for the post.
+
+        Returns:
+            Container ID for publishing.
+        """
+        return self._create_container({"image_url": image, "caption": caption})
+
+    def post(self, image: str, caption: str = "") -> dict:
+        """Upload and publish a single image."""
+        return self.publish(self.upload(image, caption))

instapost/posting/reel.py

@@ -0,0 +1,52 @@
+from typing import Optional
+
+from ..api.base import BaseInstagramClient
+
+
+class ReelPoster(BaseInstagramClient):
+    """Post reels to Instagram."""
+
+    def upload(
+        self,
+        video: str,
+        caption: str = "",
+        cover: Optional[str] = None,
+        share_to_feed: bool = True,
+        timeout: int = 120,
+    ) -> str:
+        """
+        Upload a reel to Instagram.
+
+        Args:
+            video: Local file path or publicly accessible URL of the video (MP4, max 1GB, 3-90 seconds).
+            caption: Optional caption for the reel.
+            cover: Optional local file path or URL for custom cover image.
+            share_to_feed: Whether to also share the reel to the feed.
+            timeout: Maximum time to wait for video processing in seconds.
+
+        Returns:
+            Container ID for publishing.
+        """
+        params = {
+            "media_type": "REELS",
+            "video_url": video,
+            "caption": caption,
+            "share_to_feed": str(share_to_feed).lower(),
+        }
+        if cover:
+            params["cover_url"] = cover
+
+        container_id = self._create_container(params)
+        self._wait_for_container(container_id, timeout=timeout)
+        return container_id
+
+    def post(
+        self,
+        video: str,
+        caption: str = "",
+        cover: Optional[str] = None,
+        share_to_feed: bool = True,
+        timeout: int = 120,
+    ) -> dict:
+        """Upload and publish a reel."""
+        return self.publish(self.upload(video, caption, cover, share_to_feed, timeout))

instapost-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+instapost/__init__.py,sha256=HhTIume5EvcD7jWTFnJmZee3h0dpramjur8501ccWLs,539
+instapost/client.py,sha256=Z8fZXW8PDUo2RYUb0_QaK2feJa6ZQMlm0KI0GKg5H3E,4190
+instapost/exceptions.py,sha256=M7G5fXuLjDNoRnDSvyVqVXluHx8pxYn1VxtDX3qf3BU,347
+instapost/api/__init__.py,sha256=6RVaMnFTtJm0l9nIC5tMBxJw7B_NFXxor7AlsqWb7hc,73
+instapost/api/base.py,sha256=eNVUOqF_er1Kt6MMwdsk-FfO-3lUI0L-CcmPcDCy4Ko,2836
+instapost/media/__init__.py,sha256=rhLMklySKJzeL1cCvhYfX4x-n23NAhgIzDXUT-0Aav0,65
+instapost/media/uploader.py,sha256=cLbXUNau8EqtmnSj1xXOox4UuhHRnBo0fqlETWMcoMU,3384
+instapost/posting/__init__.py,sha256=Jedqh7qWBfGtE9AoVPV8dWzZoNZ6xbZbejxbpmUU4lI,156
+instapost/posting/carousel.py,sha256=XZwLfsSNiOjNzIRQOQj8k5kLQChbgUOgF0uSaZ2H32g,1782
+instapost/posting/image.py,sha256=RH5VUyDkeiO6twRLklnLbvPkS_TJSxLG-Dl19oulHX8,721
+instapost/posting/reel.py,sha256=-Uwbz2HoCmYzI-ZHJ97LPFMmmc4acnt0rRwgBH24RVU,1564
+instapost-0.1.0.dist-info/METADATA,sha256=cAaCgW_vKrNz5jg1nWJkNlyB2hpOlCV3RYRMfcVBdoY,4198
+instapost-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+instapost-0.1.0.dist-info/licenses/LICENSE,sha256=xnrd2Cc6EdHcx_2R8NQjcSHqSMmn3AfsT-0Jv9dI8xA,1072
+instapost-0.1.0.dist-info/RECORD,,

instapost-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

instapost-0.1.0.dist-info/licenses/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.