telepress 0.1.0__py3-none-any.whl

telepress/__init__.py

@@ -0,0 +1,116 @@
+"""
+TelePress - Publish content to Telegraph easily.
+
+Basic usage:
+    >>> from telepress import publish, TelegraphPublisher
+    >>> 
+    >>> # Quick publish (one-liner)
+    >>> url = publish("article.md", title="My Article")
+    >>> 
+    >>> # Or use the class for more control
+    >>> publisher = TelegraphPublisher()
+    >>> url = publisher.publish("article.md")
+    >>> url = publisher.publish_text("# Hello\n\nWorld!", title="Test")
+"""
+
+from .core import TelegraphPublisher
+from .exceptions import (
+    TelePressError,
+    ValidationError,
+    UploadError,
+    AuthenticationError,
+    SecurityError,
+    DependencyError,
+    ConversionError
+)
+from .utils import (
+    MAX_FILE_SIZE,
+    MAX_PAGES,
+    MAX_TOTAL_IMAGES,
+    MAX_IMAGES_PER_PAGE,
+    ALLOWED_TEXT_EXTENSIONS,
+    ALLOWED_IMAGE_EXTENSIONS,
+    ALLOWED_ARCHIVE_EXTENSIONS
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    # Main class
+    'TelegraphPublisher',
+    
+    # Convenience function
+    'publish',
+    'publish_text',
+    
+    # Exceptions
+    'TelePressError',
+    'ValidationError', 
+    'UploadError',
+    'AuthenticationError',
+    'SecurityError',
+    'DependencyError',
+    'ConversionError',
+    
+    # Constants
+    'MAX_FILE_SIZE',
+    'MAX_PAGES',
+    'MAX_TOTAL_IMAGES',
+    'MAX_IMAGES_PER_PAGE',
+    'ALLOWED_TEXT_EXTENSIONS',
+    'ALLOWED_IMAGE_EXTENSIONS',
+    'ALLOWED_ARCHIVE_EXTENSIONS',
+]
+
+# Singleton publisher for convenience functions
+_default_publisher = None
+
+def _get_publisher(token=None):
+    """Get or create default publisher instance."""
+    global _default_publisher
+    if token:
+        return TelegraphPublisher(token=token)
+    if _default_publisher is None:
+        _default_publisher = TelegraphPublisher()
+    return _default_publisher
+
+
+def publish(file_path: str, title: str = None, token: str = None) -> str:
+    """
+    Convenience function to publish a file to Telegraph.
+    
+    Args:
+        file_path: Path to file (.md, .txt, .jpg, .png, .zip, etc.)
+        title: Optional title (defaults to filename)
+        token: Optional Telegraph token (uses cached token if not provided)
+    
+    Returns:
+        str: URL of the published Telegraph page
+    
+    Example:
+        >>> from telepress import publish
+        >>> url = publish("article.md", title="My Article")
+        >>> print(url)
+        https://telegra.ph/My-Article-12-07
+    """
+    return _get_publisher(token).publish(file_path, title=title)
+
+
+def publish_text(content: str, title: str, token: str = None) -> str:
+    """
+    Convenience function to publish text content directly to Telegraph.
+    
+    Args:
+        content: Markdown or plain text content
+        title: Page title (required)
+        token: Optional Telegraph token
+    
+    Returns:
+        str: URL of the published Telegraph page
+    
+    Example:
+        >>> from telepress import publish_text
+        >>> url = publish_text("# Hello\n\nThis is my article.", title="Hello World")
+        >>> print(url)
+        https://telegra.ph/Hello-World-12-07
+    """
+    return _get_publisher(token).publish_text(content, title=title)

telepress/auth.py

@@ -0,0 +1,57 @@
+import os
+from typing import Optional
+from .exceptions import DependencyError, AuthenticationError
+
+try:
+    from telegraph import Telegraph
+except ImportError:
+    Telegraph = None
+
+DEFAULT_TOKEN_FILE = os.path.expanduser("~/.telegraph_token")
+
+class TelegraphAuth:
+    def __init__(self, token_file: str = DEFAULT_TOKEN_FILE):
+        if Telegraph is None:
+            raise DependencyError("telegraph library is required")
+        self.token_file = token_file
+
+    def get_client(self, token: Optional[str] = None, short_name: str = "TelegraphClient") -> Telegraph:
+        """
+        Returns an authenticated Telegraph client.
+        Priorities:
+        1. Explicit token argument
+        2. Stored token in file
+        3. Create new account and store token
+        """
+        # 1. Explicit token
+        if token:
+            return Telegraph(access_token=token)
+
+        # 2. Stored token
+        if os.path.exists(self.token_file):
+            try:
+                with open(self.token_file, 'r') as f:
+                    stored_token = f.read().strip()
+                client = Telegraph(access_token=stored_token)
+                # Verify token
+                client.get_account_info(['short_name'])
+                return client
+            except Exception:
+                # Log or just proceed to create new
+                pass
+
+        # 3. Create new
+        try:
+            client = Telegraph()
+            response = client.create_account(short_name=short_name)
+            new_token = response['access_token']
+            
+            # Ensure directory exists
+            os.makedirs(os.path.dirname(self.token_file), exist_ok=True)
+            
+            with open(self.token_file, 'w') as f:
+                f.write(new_token)
+            
+            return Telegraph(access_token=new_token)
+        except Exception as e:
+            raise AuthenticationError(f"Failed to create new Telegraph account: {e}")

telepress/cli.py

@@ -0,0 +1,26 @@
+import argparse
+import sys
+from .core import TelegraphPublisher
+from .exceptions import TelePressError
+
+def main():
+    parser = argparse.ArgumentParser(description="TelePress: Publish files (txt, md, images, zip) to Telegraph.")
+    parser.add_argument("file", help="Path to the file to convert")
+    parser.add_argument("--title", help="Custom title for the page", default=None)
+    parser.add_argument("--token", help="Telegraph access token (optional)", default=None)
+    
+    args = parser.parse_args()
+
+    try:
+        publisher = TelegraphPublisher(token=args.token)
+        url = publisher.publish(args.file, title=args.title)
+        print(f"\n✅ Success! Page created: {url}")
+    except TelePressError as e:
+        print(f"\n❌ Error: {e}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"\n❌ Unexpected Error: {e}")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

telepress/converter.py

@@ -0,0 +1,36 @@
+import re
+from typing import List, Dict, Union
+from .utils import sanitize_nodes
+from .exceptions import DependencyError
+
+try:
+    import markdown
+    from telegraph.utils import html_to_nodes
+except ImportError:
+    markdown = None
+    html_to_nodes = None
+
+class MarkdownConverter:
+    def __init__(self):
+        if markdown is None:
+            raise DependencyError("markdown library is required")
+
+    def convert(self, md_content: str) -> List[Dict]:
+        """Converts Markdown content to Telegraph DOM nodes."""
+        html_content = markdown.markdown(md_content)
+        
+        # Pre-process HTML string for headers
+        # Telegraph doesn't support h1/h2
+        html_content = re.sub(r'<h1', '<h3', html_content)
+        html_content = re.sub(r'</h1>', '</h3>', html_content)
+        html_content = re.sub(r'<h2', '<h4', html_content)
+        html_content = re.sub(r'</h2>', '</h4>', html_content)
+        html_content = re.sub(r'<h[56]', '<h4', html_content)
+        html_content = re.sub(r'</h[56]>', '</h4>', html_content)
+
+        if html_to_nodes:
+            nodes = html_to_nodes(html_content)
+            return sanitize_nodes(nodes)
+        else:
+            # Fallback (though utils should be present if telegraph is installed)
+            return [{'tag': 'p', 'children': [md_content]}]

telepress/core.py

@@ -0,0 +1,329 @@
+import os
+import tempfile
+import zipfile
+from typing import Optional, List, Dict
+from .auth import TelegraphAuth
+from .converter import MarkdownConverter
+from .uploader import ImageUploader
+from .utils import (
+    natural_sort_key, safe_extract_zip, validate_file_size,
+    MAX_TEXT_SIZE, MAX_IMAGES_PER_PAGE, MAX_PAGES, MAX_TOTAL_IMAGES, MAX_FILE_SIZE,
+    ALLOWED_TEXT_EXTENSIONS, ALLOWED_ARCHIVE_EXTENSIONS, ALLOWED_IMAGE_EXTENSIONS
+)
+from .exceptions import UploadError, ValidationError
+from .interfaces import IPublisher
+
+class TelegraphPublisher(IPublisher):
+    """
+    Main interface for publishing content to Telegraph.
+    """
+    IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'}
+
+    def __init__(self, token: Optional[str] = None, short_name: str = "TelegraphPublisher"):
+        self.auth = TelegraphAuth()
+        self.client = self.auth.get_client(token, short_name)
+        self.converter = MarkdownConverter()
+        self.uploader = ImageUploader()
+
+    def publish(self, file_path: str, title: Optional[str] = None) -> str:
+        """
+        Publishes a file (md, txt, image, zip) to Telegraph.
+        
+        Supported formats:
+        - Text: .txt, .md, .markdown, .rst, .text
+        - Images: .jpg, .jpeg, .png, .gif, .webp, .bmp
+        - Archives: .zip (containing images)
+        
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ValidationError: If file type not supported or file too large
+        """
+        if not os.path.exists(file_path):
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        file_name = os.path.basename(file_path)
+        if not title:
+            title = os.path.splitext(file_name)[0]
+        ext = os.path.splitext(file_name)[1].lower()
+        
+        # Validate file size
+        file_size = os.path.getsize(file_path)
+        if file_size > MAX_FILE_SIZE:
+            raise ValidationError(
+                f"File too large: {file_size / 1024 / 1024:.1f}MB. "
+                f"Maximum allowed: {MAX_FILE_SIZE / 1024 / 1024:.0f}MB"
+            )
+        
+        # Validate file type and route to appropriate handler
+        if ext in ALLOWED_ARCHIVE_EXTENSIONS:
+            return self.publish_zip_gallery(file_path, title)
+        elif ext in self.IMAGE_EXTENSIONS:
+            return self.publish_image(file_path, title)
+        elif ext in ALLOWED_TEXT_EXTENSIONS:
+            return self.publish_markdown(file_path, title)
+        else:
+            # Unsupported file type
+            supported = sorted(ALLOWED_TEXT_EXTENSIONS | self.IMAGE_EXTENSIONS | ALLOWED_ARCHIVE_EXTENSIONS)
+            raise ValidationError(
+                f"Unsupported file type: '{ext}'. "
+                f"Supported formats: {', '.join(supported)}"
+            )
+
+    def _link_pages(self, pages_info: List[Dict]):
+        """
+        Helper to add navigation links (Prev/Next/Index) to a list of pages.
+        """
+        total_parts = len(pages_info)
+        if total_parts <= 1:
+            return
+
+        print(f"Linking {total_parts} pages...")
+        for i, info in enumerate(pages_info):
+            nav_nodes = []
+            
+            # 1. Navigation Links (Prev/Next)
+            nav_links = []
+            if i > 0:
+                prev_url = pages_info[i-1]['url']
+                nav_links.append({
+                    'tag': 'a',
+                    'attrs': {'href': prev_url},
+                    'children': [f'◀ Previous / 上一页']
+                })
+                nav_links.append(" | ")
+            
+            if i < total_parts - 1:
+                next_url = pages_info[i+1]['url']
+                nav_links.append({
+                    'tag': 'a',
+                    'attrs': {'href': next_url},
+                    'children': [f'Next / 下一页 ▶']
+                })
+            
+            if nav_links:
+                nav_nodes.append({'tag': 'p', 'children': nav_links})
+            
+            # 2. Pagination Index (Page Numbers)
+            # Limit index if too many pages to avoid hitting node limits on the index itself
+            # Show: [1] ... [current-2] [current-1] [current] [current+1] [current+2] ... [last]
+            page_index_nodes = ["Pages: "]
+            
+            # Simple full list for now, optimized for < 100 pages
+            if total_parts < 50:
+                for p_idx, p_info in enumerate(pages_info):
+                    label = str(p_idx + 1)
+                    if p_idx == i:
+                        page_index_nodes.append({'tag': 'b', 'children': [f"[{label}]"]})
+                    else:
+                        page_index_nodes.append({'tag': 'a', 'attrs': {'href': p_info['url']}, 'children': [f"[{label}]"]})
+                    page_index_nodes.append(" ")
+            else:
+                # Simplified index for very large sets
+                page_index_nodes.append(f"{i+1} / {total_parts}")
+
+            nav_nodes.append({'tag': 'p', 'children': page_index_nodes})
+
+            if nav_nodes:
+                new_content = info['content'] + [{'tag': 'hr'}] + nav_nodes
+                try:
+                    self.client.edit_page(
+                        path=info['path'],
+                        title=info['title'],
+                        content=new_content
+                    )
+                except Exception as e:
+                    print(f"Warning: Failed to add navigation to Part {i+1}: {e}")
+
+    def publish_markdown(self, file_path: str, title: str) -> str:
+        """
+        Publish a markdown/text file to Telegraph.
+        Large files are automatically split into multiple pages.
+        
+        Limits:
+        - Maximum ~4 million characters (100 pages × 40000 chars)
+        - Files exceeding this will be truncated with a warning
+        """
+        # Validate file can be read as text
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                content = f.read()
+        except UnicodeDecodeError:
+            raise ValidationError(
+                f"Cannot read file as text. File may be binary (PDF, DOCX, etc.). "
+                f"Only plain text files (.txt, .md) are supported."
+            )
+        
+        # Split content if too large
+        # Telegraph safe limit is around 60KB JSON, so ~30-40KB text is safe.
+        SAFE_CHUNK_SIZE = 40000 
+        
+        chunks = []
+        if len(content) > SAFE_CHUNK_SIZE:
+            print(f"Text too large ({len(content)} chars). Splitting...")
+            current_chunk = []
+            current_len = 0
+            # Split by lines to preserve markdown structure somewhat
+            for line in content.splitlines(keepends=True):
+                if current_len + len(line) > SAFE_CHUNK_SIZE:
+                    chunks.append("".join(current_chunk))
+                    current_chunk = []
+                    current_len = 0
+                current_chunk.append(line)
+                current_len += len(line)
+            if current_chunk:
+                chunks.append("".join(current_chunk))
+        else:
+            chunks = [content]
+        
+        # Enforce page limit
+        if len(chunks) > MAX_PAGES:
+            original_count = len(chunks)
+            chunks = chunks[:MAX_PAGES]
+            print(f"Warning: Content truncated from {original_count} to {MAX_PAGES} pages (max limit).")
+
+        total_parts = len(chunks)
+        pages_info = []
+
+        for i, chunk_text in enumerate(chunks):
+            part_num = i + 1
+            page_title = title
+            if total_parts > 1:
+                page_title = f"{title} ({part_num}/{total_parts})"
+            
+            print(f"Publishing Part {part_num}/{total_parts} ({len(chunk_text)} chars)...")
+            nodes = self.converter.convert(chunk_text)
+            
+            try:
+                response = self.client.create_page(title=page_title, content=nodes)
+                pages_info.append({
+                    'path': response['path'],
+                    'url': response['url'],
+                    'title': page_title,
+                    'content': nodes
+                })
+            except Exception as e:
+                 raise RuntimeError(f"Failed to publish Part {part_num}: {e}")
+
+        # Link pages if multiple
+        self._link_pages(pages_info)
+
+        return pages_info[0]['url'] if pages_info else ""
+
+    def publish_image(self, image_path: str, title: str) -> str:
+        """Publish a single image to Telegraph."""
+        url = self.uploader.upload(image_path)
+        content = [{'tag': 'img', 'attrs': {'src': url}}]
+        response = self.client.create_page(title=title, content=content)
+        return response['url']
+
+    def publish_text(self, content: str, title: str) -> str:
+        """
+        Publish text/markdown content directly to Telegraph.
+        
+        This is useful for programmatic publishing without creating a temp file.
+        
+        Args:
+            content: Markdown or plain text content
+            title: Page title
+        
+        Returns:
+            str: URL of the published Telegraph page
+        
+        Example:
+            >>> publisher = TelegraphPublisher()
+            >>> url = publisher.publish_text("# Hello\n\nWorld!", title="Test")
+        """
+        import tempfile
+        import os
+        
+        # Write content to temp file and use existing publish_markdown logic
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False, encoding='utf-8') as f:
+            f.write(content)
+            tmp_path = f.name
+        
+        try:
+            return self.publish_markdown(tmp_path, title)
+        finally:
+            os.unlink(tmp_path)
+
+    def publish_zip_gallery(self, zip_path: str, title: str) -> str:
+        """
+        Publish a zip file containing images as a gallery.
+        
+        Limits:
+        - Maximum 5000 images (50 pages × 100 images)
+        - Images exceeding this will be truncated with a warning
+        """
+        with tempfile.TemporaryDirectory() as temp_dir:
+            try:
+                safe_extract_zip(zip_path, temp_dir)
+            except zipfile.BadZipFile:
+                raise ValidationError("Invalid zip file")
+
+            images = []
+            for root, _, files in os.walk(temp_dir):
+                for file in files:
+                    if os.path.splitext(file)[1].lower() in self.IMAGE_EXTENSIONS:
+                        images.append(os.path.join(root, file))
+            
+            images.sort(key=lambda x: natural_sort_key(os.path.basename(x)))
+            
+            if not images:
+                raise ValidationError("No images found in zip file")
+            
+            # Enforce image limit
+            if len(images) > MAX_TOTAL_IMAGES:
+                print(f"Warning: Gallery truncated from {len(images)} to {MAX_TOTAL_IMAGES} images (max limit).")
+                images = images[:MAX_TOTAL_IMAGES]
+            
+            # Pagination logic
+            chunk_size = MAX_IMAGES_PER_PAGE
+            chunks = [images[i:i + chunk_size] for i in range(0, len(images), chunk_size)]
+            total_parts = len(chunks)
+            
+            if total_parts > 1:
+                print(f"Gallery has {len(images)} images. Splitting into {total_parts} pages.")
+            
+            # Two-pass approach to support Prev/Next links
+            # Pass 1: Create all pages
+            pages_info = [] # Stores {'path': str, 'url': str, 'title': str, 'content': list}
+            
+            for i, chunk_images in enumerate(chunks):
+                part_num = i + 1
+                page_title = title
+                if total_parts > 1:
+                    page_title = f"{title} ({part_num}/{total_parts})"
+                
+                print(f"Uploading Part {part_num}/{total_parts} ({len(chunk_images)} images)...")
+                
+                content = []
+                for img_path in chunk_images:
+                    try:
+                        url = self.uploader.upload(img_path)
+                        content.append({'tag': 'img', 'attrs': {'src': url}})
+                    except UploadError as e:
+                        print(f"Warning: Failed to upload {os.path.basename(img_path)}: {e}")
+                
+                if not content and len(chunk_images) > 0:
+                     print(f"Warning: Part {part_num} resulted in empty content.")
+
+                try:
+                    # Create initial page
+                    response = self.client.create_page(
+                        title=page_title,
+                        html_content=None,
+                        content=content if content else [{'tag': 'p', 'children': ['(Empty Page)']}]
+                    )
+                    pages_info.append({
+                        'path': response['path'],
+                        'url': response['url'],
+                        'title': page_title,
+                        'content': content
+                    })
+                except Exception as e:
+                    raise RuntimeError(f"Failed to publish Part {part_num}: {e}")
+
+            # Pass 2: Update pages with navigation
+            self._link_pages(pages_info)
+
+            return pages_info[0]['url'] if pages_info else ""

telepress/exceptions.py

@@ -0,0 +1,27 @@
+class TelePressError(Exception):
+    """Base exception for TelePress."""
+    pass
+
+class DependencyError(TelePressError):
+    """Raised when required dependencies are missing."""
+    pass
+
+class AuthenticationError(TelePressError):
+    """Raised when authentication fails."""
+    pass
+
+class ConversionError(TelePressError):
+    """Raised when file conversion fails."""
+    pass
+
+class UploadError(TelePressError):
+    """Raised when file upload fails."""
+    pass
+
+class SecurityError(TelePressError):
+    """Raised when a security violation is detected (e.g. Zip Slip, huge file)."""
+    pass
+
+class ValidationError(TelePressError):
+    """Raised when input data validation fails (e.g. invalid format, limits exceeded)."""
+    pass

telepress/interfaces.py

@@ -0,0 +1,38 @@
+from abc import ABC, abstractmethod
+from typing import Optional, Dict, Any
+
+class IPublisher(ABC):
+    """
+    Abstract Base Class defining the Publisher interface.
+    This allows for different implementations (e.g. Telegraph, Medium, Ghost)
+    to be interchangeable.
+    """
+    
+    @abstractmethod
+    def publish(self, source: Any, title: Optional[str] = None) -> str:
+        """
+        Publish content from the source.
+        
+        Args:
+            source: The content to publish (file path, raw text, etc.)
+            title: Optional title for the publication
+            
+        Returns:
+            str: The URL of the published content
+        """
+        pass
+
+class IConverter(ABC):
+    """Interface for content converters (e.g. Markdown -> Node, RST -> Node)."""
+    
+    @abstractmethod
+    def convert(self, content: str) -> Any:
+        pass
+
+class IUploader(ABC):
+    """Interface for asset uploaders (e.g. Images)."""
+    
+    @abstractmethod
+    def upload(self, source: Any) -> str:
+        """Uploads the asset and returns a public URL."""
+        pass

telepress/server.py

@@ -0,0 +1,132 @@
+from fastapi import FastAPI, UploadFile, File, Form, HTTPException, Depends
+from pydantic import BaseModel
+from typing import Optional
+import os
+import shutil
+import tempfile
+from .core import TelegraphPublisher
+from .exceptions import TelePressError
+
+app = FastAPI(
+    title="TelePress API",
+    description="REST API to convert text, markdown, images, and zips to Telegraph pages.",
+    version="0.1.0"
+)
+
+# Request Models
+class TextPublishRequest(BaseModel):
+    content: str
+    title: str
+    token: Optional[str] = None
+
+class PublishResponse(BaseModel):
+    url: str
+    status: str = "success"
+
+def get_publisher(token: Optional[str] = None):
+    try:
+        return TelegraphPublisher(token=token)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.get("/")
+def health_check():
+    return {"status": "ok", "service": "telepress"}
+
+@app.post("/publish/text", response_model=PublishResponse)
+async def publish_text(request: TextPublishRequest):
+    """
+    Publish raw Markdown/Text content directly.
+    """
+    try:
+        # We need to save to a temp file because our core logic expects files
+        # Alternatively, we could refactor core to accept string, but file is safer for large content
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False, encoding='utf-8') as tmp:
+            tmp.write(request.content)
+            tmp_path = tmp.name
+        
+        publisher = get_publisher(request.token)
+        url = publisher.publish(tmp_path, title=request.title)
+        
+        os.unlink(tmp_path)
+        return PublishResponse(url=url)
+        
+    except TelePressError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.post("/publish/file", response_model=PublishResponse)
+async def publish_file(
+    file: UploadFile = File(...),
+    title: Optional[str] = Form(None),
+    token: Optional[str] = Form(None)
+):
+    """
+    Upload a file (md, txt, zip, image) to be processed and published.
+    """
+    try:
+        suffix = os.path.splitext(file.filename)[1]
+        with tempfile.NamedTemporaryFile(delete=False, suffix=suffix) as tmp:
+            shutil.copyfileobj(file.file, tmp)
+            tmp_path = tmp.name
+            
+        publisher = get_publisher(token)
+        
+        # If no title provided, use filename from upload
+        pub_title = title if title else file.filename
+        
+        url = publisher.publish(tmp_path, title=pub_title)
+        
+        os.unlink(tmp_path)
+        return PublishResponse(url=url)
+        
+    except TelePressError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        # Clean up if exists
+        if 'tmp_path' in locals() and os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+        raise HTTPException(status_code=500, detail=str(e))
+
+def start_server(host="0.0.0.0", port=8000):
+    """Start the TelePress API server."""
+    import uvicorn
+    uvicorn.run(app, host=host, port=port)
+
+
+def main():
+    """
+    CLI entry point for telepress-server command.
+    
+    Usage:
+        telepress-server
+        telepress-server --host 127.0.0.1 --port 9000
+    """
+    import argparse
+    
+    parser = argparse.ArgumentParser(
+        description="Start the TelePress REST API server."
+    )
+    parser.add_argument(
+        "--host", 
+        default="0.0.0.0", 
+        help="Host to bind (default: 0.0.0.0)"
+    )
+    parser.add_argument(
+        "--port", 
+        type=int, 
+        default=8000, 
+        help="Port to listen on (default: 8000)"
+    )
+    
+    args = parser.parse_args()
+    
+    print(f"Starting TelePress API server at http://{args.host}:{args.port}")
+    print("API docs available at: http://localhost:{}/docs".format(args.port))
+    
+    start_server(host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

telepress/uploader.py

@@ -0,0 +1,43 @@
+import os
+import time
+from typing import Optional
+from .exceptions import UploadError, DependencyError
+from .utils import validate_file_size, MAX_IMAGE_SIZE
+
+try:
+    from telegraph import upload_file
+except ImportError:
+    upload_file = None
+
+class ImageUploader:
+    def __init__(self):
+        if upload_file is None:
+            raise DependencyError("telegraph library is required")
+
+    def upload(self, path: str, retries: int = 3) -> str:
+        """
+        Uploads an image to Telegraph and returns the URL.
+        Includes validation and retries.
+        """
+        if not os.path.exists(path):
+            raise FileNotFoundError(f"Image not found: {path}")
+            
+        validate_file_size(path, MAX_IMAGE_SIZE, "Image file too large")
+
+        attempt = 0
+        while attempt < retries:
+            try:
+                with open(path, 'rb') as f:
+                    response = upload_file(f)
+                
+                if isinstance(response, list) and len(response) > 0 and 'src' in response[0]:
+                    return "https://telegra.ph" + response[0]['src']
+                
+                # If response format is unexpected but no exception, maybe server issue
+                raise UploadError(f"Invalid response from upload server: {response}")
+                
+            except Exception as e:
+                attempt += 1
+                if attempt >= retries:
+                    raise UploadError(f"Failed to upload image {path} after {retries} attempts: {e}")
+                time.sleep(1) # Wait before retry

telepress/utils.py

@@ -0,0 +1,67 @@
+import re
+import os
+import zipfile
+from typing import List, Dict, Union
+from .exceptions import SecurityError, ValidationError
+
+# Constants for limits
+MAX_TEXT_SIZE = 60 * 1024  # ~60KB safe limit for text content
+MAX_IMAGE_SIZE = 5 * 1024 * 1024  # 5MB limit per image (Telegraph limit)
+MAX_IMAGES_PER_PAGE = 100  # Avoid browser crashes
+MAX_PAGES = 100  # Maximum pages to prevent excessive API calls
+MAX_TOTAL_IMAGES = 5000  # Maximum images in a single gallery
+MAX_FILE_SIZE = 100 * 1024 * 1024  # 100MB max file size
+ALLOWED_IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'}
+ALLOWED_TEXT_EXTENSIONS = {'.txt', '.md', '.markdown', '.rst', '.text'}
+ALLOWED_ARCHIVE_EXTENSIONS = {'.zip'}
+
+def natural_sort_key(s: str) -> List[Union[int, str]]:
+    """
+    Sorts strings containing numbers naturally.
+    e.g. ['1.png', '10.png', '2.png'] -> ['1.png', '2.png', '10.png']
+    """
+    return [int(text) if text.isdigit() else text.lower() for text in re.split('([0-9]+)', s)]
+
+def validate_file_size(path: str, max_size: int, error_msg: str):
+    """Checks if file size is within limits."""
+    if os.path.getsize(path) > max_size:
+        raise ValidationError(f"{error_msg} (Size: {os.path.getsize(path)/1024/1024:.2f}MB, Max: {max_size/1024/1024}MB)")
+
+def safe_extract_zip(zip_path: str, extract_to: str):
+    """
+    Safely extracts a zip file, preventing Zip Slip vulnerabilities.
+    """
+    with zipfile.ZipFile(zip_path, 'r') as zf:
+        for member in zf.namelist():
+            # Resolve the path to ensure it doesn't escape the target directory
+            member_path = os.path.join(extract_to, member)
+            abs_member_path = os.path.abspath(member_path)
+            abs_target_path = os.path.abspath(extract_to)
+            
+            if not abs_member_path.startswith(abs_target_path):
+                raise SecurityError(f"Zip Slip attempt detected: {member}")
+            
+            # Extract only if safe
+            zf.extract(member, extract_to)
+
+def sanitize_nodes(nodes: List[Dict]) -> List[Dict]:
+    """
+    Recursively downgrades headers h1->h3, h2->h4 because Telegraph
+    only supports h3 and h4.
+    """
+    if not isinstance(nodes, list):
+        return nodes
+    
+    for node in nodes:
+        if isinstance(node, dict):
+            tag = node.get('tag')
+            if tag == 'h1':
+                node['tag'] = 'h3'
+            elif tag == 'h2':
+                node['tag'] = 'h4'
+            elif tag in ['h5', 'h6']:
+                node['tag'] = 'h4'
+            
+            if 'children' in node:
+                sanitize_nodes(node['children'])
+    return nodes

telepress-0.1.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: telepress
+Version: 0.1.0
+Summary: Publish Markdown, images and zip archives to Telegraph
+Home-page: https://github.com/zoidberg-xgd/telepress
+Author: zoidberg-xgd
+Author-email: 
+Project-URL: Bug Reports, https://github.com/zoidberg-xgd/telepress/issues
+Project-URL: Source, https://github.com/zoidberg-xgd/telepress
+Keywords: telegraph,markdown,publishing,gallery
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: telegraph
+Requires-Dist: markdown
+Requires-Dist: requests
+Provides-Extra: api
+Requires-Dist: fastapi; extra == "api"
+Requires-Dist: uvicorn; extra == "api"
+Requires-Dist: python-multipart; extra == "api"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# TelePress
+
+[中文文档](README_CN.md)
+
+Publish Markdown, images and zip archives to [Telegraph](https://telegra.ph). Handles large files by auto-splitting into multiple linked pages.
+
+## Install
+
+```bash
+pip install telepress
+
+# with REST API
+pip install telepress[api]
+```
+
+## Usage
+
+```python
+from telepress import publish, publish_text
+
+url = publish("article.md")
+url = publish_text("# Hello\n\nWorld!", title="Test")
+```
+
+CLI:
+```bash
+telepress article.md --title "My Post"
+telepress photos.zip --title "Album"
+```
+
+REST API:
+```bash
+telepress-server --port 8000
+
+curl -X POST localhost:8000/publish/text \
+  -H "Content-Type: application/json" \
+  -d '{"content": "# Title\n\nBody", "title": "Test"}'
+```
+
+## How it works
+
+Text files are converted to Telegraph format (Markdown supported). Large content is split at ~40KB boundaries into multiple pages with prev/next navigation.
+
+Zip files are treated as image galleries. Images are sorted naturally (1, 2, 10 not 1, 10, 2) and paginated at 100 per page.
+
+Token is auto-created on first run and saved to `~/.telegraph_token`.
+
+## Limits
+
+- 100MB max file size
+- 100 pages max (~4M chars text, or 5000 images)
+- 5MB per image (Telegraph limit)
+
+Supported: `.txt` `.md` `.markdown` `.rst` `.jpg` `.png` `.gif` `.webp` `.zip`
+
+Not supported: PDF, DOCX (convert first)
+
+## Project structure
+
+```
+telepress/
+├── core.py       # TelegraphPublisher
+├── auth.py       # token management
+├── converter.py  # markdown to telegraph nodes
+├── uploader.py   # image upload with retry
+├── server.py     # FastAPI service
+└── cli.py        # command line
+```
+
+## Error handling
+
+```python
+from telepress import publish, ValidationError, TelePressError
+
+try:
+    url = publish("file.md")
+except ValidationError as e:
+    # bad input: wrong format, too large, etc
+    print(e)
+except TelePressError as e:
+    # other errors: upload failed, auth failed, etc
+    print(e)
+```
+
+## Integration
+
+```python
+# Flask
+@app.route('/publish', methods=['POST'])
+def api_publish():
+    url = publish_text(request.json['content'], title=request.json['title'])
+    return {'url': url}
+
+# async
+async def async_publish(content, title):
+    return await asyncio.to_thread(publish_text, content, title)
+```
+
+## Dev
+
+```bash
+git clone https://github.com/zoidberg-xgd/telepress
+cd telepress && pip install -e .[dev]
+pytest tests/ -v
+```
+
+## License
+
+MIT

telepress-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+telepress/__init__.py,sha256=lmyGBlMFmrVIcl6ycZtCHYQ3RxkTvspYHkAbsvyJUlM,3080
+telepress/auth.py,sha256=FvwOOwizblK0UkFL5gXOeRm_kTSr4SLbAWPVre2_YZs,1941
+telepress/cli.py,sha256=8J3CWc_Oy9UqptlTErew6Hc01WJPgg5ggYG7Skec4TU,908
+telepress/converter.py,sha256=CPPYXyEnS8c_Ix-jWzXqLlQR1qbmJPJo4W2YSxYxeu0,1316
+telepress/core.py,sha256=-ymrFS4s5AgCruvoe2wo9lkeuTcK07wQNu9uTnJt_1U,13245
+telepress/exceptions.py,sha256=t8MI4atvKYQdhSYUR-s3jiuXmqrc9870DjsWAm9TXyE,734
+telepress/interfaces.py,sha256=6lErqHgC5d1RctIkHYBh9xD__yJJxhVaqPoMdo6kzS0,1084
+telepress/server.py,sha256=fwxvMD0DTZnShKLXnUQBARJs-QmYna36clfPU5-mvN8,3956
+telepress/uploader.py,sha256=lBTAI_emNa2tNXIr47ynrGPcR9onoVCYWwcD7WSK2_o,1563
+telepress/utils.py,sha256=RFbSwhyfEPGOTCEBZjuqbOKXcwoPxMGrdhUyaD8L89Q,2634
+telepress-0.1.0.dist-info/licenses/LICENSE,sha256=o_ZmC5f8PrW9PNmJ0phiUkjz9OBZcJMVe4wo3l-59Ac,1069
+telepress-0.1.0.dist-info/METADATA,sha256=IDYgml3x9SdeOM3tuS3u2XCEI_jvzhIOOV4Aypex8G4,3997
+telepress-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+telepress-0.1.0.dist-info/entry_points.txt,sha256=SENLejDh7RKvraukU5goVTxAuhx96PVV8m8_qOr65aA,90
+telepress-0.1.0.dist-info/top_level.txt,sha256=Dh5UrvGpGy_ZBcI7YC-0xBRFbHe9A5Ae94fjbhe02IU,10
+telepress-0.1.0.dist-info/RECORD,,

telepress-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

telepress-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+telepress = telepress.cli:main
+telepress-server = telepress.server:main

telepress-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 zoidberg-xgd
+
+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.

telepress-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+telepress