py-for-ai 0.1.0__tar.gz

py_for_ai-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+.venv/
+.idea/
+dist/

py_for_ai-0.1.0/LICENSE

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

py_for_ai-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: py-for-ai
+Version: 0.1.0
+Summary: A command-line utility to pack Python codebases into a single text file for AI context, with clipboard support.
+Project-URL: Homepage, https://github.com/Maksum867/py-ai
+Author: Maksym Khlystun
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Requires-Dist: pyperclip>=1.8.2
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# py-ai 🚀
+
+[![PyPI version](https://img.shields.io/pypi/v/py-ai-pack.svg)](https://pypi.org/project/py-ai-pack/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Maksum867/py-ai/blob/main/LICENSE)
+[![Python Support](https://img.shields.io/pypi/pyversions/py-ai-pack.svg)](https://pypi.org/project/py-ai-pack/)
+
+`py-ai` is a lightweight, zero-configuration command-line interface (CLI) tool designed for developers. It recursively scans your local Python codebase, filters out unnecessary files, and compiles your entire project—complete with a beautiful ASCII directory tree—into a single, organized text file while automatically copying it to your clipboard. 
+
+Perfect for instantly feeding your codebase context into Large Language Models (LLMs) like ChatGPT, Claude, and Gemini.
+
+</div>
+
+---
+
+## ✨ Features
+
+- **Smart Filtering**: Automatically ignores VCS folders (`.git`), virtual environments (`.venv`, `venv`), IDE settings (`.vscode`, `.idea`), build artifacts (`dist`, `build`), and binary files (images, archives, databases).
+- **ASCII Directory Tree**: Generates a clean, sorted representation of your project layout at the top of the output.
+- **Normalized File Markers**: Wraps each file's code in distinct delimiters (`--- START OF FILE: ... ---`) using normalized cross-platform POSIX paths (`/`).
+- **Clipboard Integration**: Automatically copies the packed content. Gracefully falls back with a warning in headless/SSH environments rather than crashing.
+- **PyPI & Hatchling Ready**: Out-of-the-box support for modern PEP 621 packaging.
+
+---
+
+## 📂 Project Layout
+
+```text
+py_ai_project/
+├── pyproject.toml
+├── README.md
+└── src/
+    └── py_ai/
+        ├── __init__.py
+        ├── __main__.py
+        ├── core.py
+        └── cli.py
+```
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+Install the utility directly from PyPI:
+
+```bash
+pip install py-ai
+```
+
+*(Or install it locally for development)*:
+
+```bash
+git clone https://github.com/Maksum867/py-ai.git
+cd py_ai_project
+pip install -e .
+```
+
+### Usage
+
+Run the utility from any terminal session:
+
+```bash
+# 1. Pack current directory and copy to clipboard:
+pyai
+
+# 2. Pack a specific directory:
+pyai /path/to/your/project
+
+# 3. Save the results to a custom file:
+pyai . -o custom_output.txt
+
+# 4. Run without clipboard copy (ideal for remote servers or CI/CD):
+pyai --no-clipboard
+```
+
+---
+
+## 📄 Output Format Example
+
+```text
+================================================================================
+PROJECT CONTEXT PACK: my_project
+Generated on: 2026-07-31 12:00:00
+Total files packed: 2
+================================================================================
+
+================================================================================
+DIRECTORY TREE
+================================================================================
+my_project/
+├── src/
+│   └── main.py
+└── pyproject.toml
+
+================================================================================
+FILES CONTENT
+================================================================================
+
+--- START OF FILE: pyproject.toml ---
+[project]
+name = "my_project"
+version = "0.1.0"
+--- END OF FILE: pyproject.toml ---
+
+--- START OF FILE: src/main.py ---
+def main():
+    print("Hello, AI!")
+--- END OF FILE: src/main.py ---
+```
+
+---
+
+## 🛠️ Requirements & Dependencies
+
+- Python `3.8` or higher.
+- `pyperclip` (for clipboard operations).

py_for_ai-0.1.0/README.md

@@ -0,0 +1,119 @@
+<div align="center">
+
+# py-ai 🚀
+
+[![PyPI version](https://img.shields.io/pypi/v/py-ai-pack.svg)](https://pypi.org/project/py-ai-pack/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Maksum867/py-ai/blob/main/LICENSE)
+[![Python Support](https://img.shields.io/pypi/pyversions/py-ai-pack.svg)](https://pypi.org/project/py-ai-pack/)
+
+`py-ai` is a lightweight, zero-configuration command-line interface (CLI) tool designed for developers. It recursively scans your local Python codebase, filters out unnecessary files, and compiles your entire project—complete with a beautiful ASCII directory tree—into a single, organized text file while automatically copying it to your clipboard. 
+
+Perfect for instantly feeding your codebase context into Large Language Models (LLMs) like ChatGPT, Claude, and Gemini.
+
+</div>
+
+---
+
+## ✨ Features
+
+- **Smart Filtering**: Automatically ignores VCS folders (`.git`), virtual environments (`.venv`, `venv`), IDE settings (`.vscode`, `.idea`), build artifacts (`dist`, `build`), and binary files (images, archives, databases).
+- **ASCII Directory Tree**: Generates a clean, sorted representation of your project layout at the top of the output.
+- **Normalized File Markers**: Wraps each file's code in distinct delimiters (`--- START OF FILE: ... ---`) using normalized cross-platform POSIX paths (`/`).
+- **Clipboard Integration**: Automatically copies the packed content. Gracefully falls back with a warning in headless/SSH environments rather than crashing.
+- **PyPI & Hatchling Ready**: Out-of-the-box support for modern PEP 621 packaging.
+
+---
+
+## 📂 Project Layout
+
+```text
+py_ai_project/
+├── pyproject.toml
+├── README.md
+└── src/
+    └── py_ai/
+        ├── __init__.py
+        ├── __main__.py
+        ├── core.py
+        └── cli.py
+```
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+Install the utility directly from PyPI:
+
+```bash
+pip install py-ai
+```
+
+*(Or install it locally for development)*:
+
+```bash
+git clone https://github.com/Maksum867/py-ai.git
+cd py_ai_project
+pip install -e .
+```
+
+### Usage
+
+Run the utility from any terminal session:
+
+```bash
+# 1. Pack current directory and copy to clipboard:
+pyai
+
+# 2. Pack a specific directory:
+pyai /path/to/your/project
+
+# 3. Save the results to a custom file:
+pyai . -o custom_output.txt
+
+# 4. Run without clipboard copy (ideal for remote servers or CI/CD):
+pyai --no-clipboard
+```
+
+---
+
+## 📄 Output Format Example
+
+```text
+================================================================================
+PROJECT CONTEXT PACK: my_project
+Generated on: 2026-07-31 12:00:00
+Total files packed: 2
+================================================================================
+
+================================================================================
+DIRECTORY TREE
+================================================================================
+my_project/
+├── src/
+│   └── main.py
+└── pyproject.toml
+
+================================================================================
+FILES CONTENT
+================================================================================
+
+--- START OF FILE: pyproject.toml ---
+[project]
+name = "my_project"
+version = "0.1.0"
+--- END OF FILE: pyproject.toml ---
+
+--- START OF FILE: src/main.py ---
+def main():
+    print("Hello, AI!")
+--- END OF FILE: src/main.py ---
+```
+
+---
+
+## 🛠️ Requirements & Dependencies
+
+- Python `3.8` or higher.
+- `pyperclip` (for clipboard operations).

py_for_ai-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "py-for-ai"
+version = "0.1.0"
+description = "A command-line utility to pack Python codebases into a single text file for AI context, with clipboard support."
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "Maksym Khlystun"}
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "pyperclip>=1.8.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/Maksum867/py-ai"
+
+[project.scripts]
+pyai = "py_ai.cli:main"
+py-ai = "py_ai.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/py_ai"]

py_for_ai-0.1.0/src/py_ai/__init__.py

@@ -0,0 +1,6 @@
+"""
+py-ai: A Python CLI utility to package a codebase into a single text file/clipboard for AI context.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Maksym Khlystun"

py_for_ai-0.1.0/src/py_ai/__main__.py

@@ -0,0 +1,7 @@
+"""
+Entry point for running the utility as a module: `python -m py_ai`
+"""
+from py_ai.cli import main
+
+if __name__ == "__main__":
+    main()

py_for_ai-0.1.0/src/py_ai/cli.py

@@ -0,0 +1,89 @@
+"""
+cli.py module
+=============
+Command-line interface (CLI) for the py-ai utility using the built-in argparse.
+Provides user interaction, argument parsing, and triggers the packing logic.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+from py_ai.core import pack_project
+
+
+def main():
+    """
+    Main entry point for the command-line interface. Parses CLI arguments,
+    starts the project packaging process, and prints results to the console.
+    """
+    parser = argparse.ArgumentParser(
+        description="py-ai: A command-line utility to pack your project's codebase into a single text file and copy it to the clipboard for LLM context."
+    )
+
+    parser.add_argument(
+        "root_dir",
+        nargs="?",
+        default=".",
+        help="Path to the project directory to pack (default: current directory '.')"
+    )
+
+    parser.add_argument(
+        "-o", "--output",
+        default="ai_context.txt",
+        help="Name or path of the output file (default: 'ai_context.txt')"
+    )
+
+    parser.add_argument(
+        "--no-clipboard",
+        action="store_true",
+        help="Disable automatic copying of the generated context to the system clipboard (useful for headless servers or CI/CD pipelines)."
+    )
+
+    args = parser.parse_args()
+
+    root_path = Path(args.root_dir)
+    output_path = Path(args.output)
+
+    print(f"🔍 Scanning project directory: {root_path.resolve()}")
+
+    try:
+        # Trigger the core packing logic
+        stats = pack_project(
+            root_dir=root_path,
+            output_file=output_path,
+            copy_to_clipboard=not args.no_clipboard
+        )
+
+        print("\n✨ Project successfully packed!")
+        print(f"📁 Root Directory:   {stats['root_dir']}")
+        print(f"📄 Output File:      {stats['output_file']}")
+        print(f"📦 Packed Files:     {stats['packed_count']}")
+
+        if stats['failed_count'] > 0:
+            print(f"⚠️  Skipped Files:    {stats['failed_count']} (see warning messages above)")
+
+        if stats['clipboard_copied']:
+            print("📋 Project context copied to clipboard successfully!")
+        else:
+            if args.no_clipboard:
+                print("ℹ️  Clipboard copying was disabled by the --no-clipboard flag.")
+            else:
+                print(
+                    f"⚠️  Could not copy to clipboard.\n"
+                    f"   Details: {stats['clipboard_error'] or 'Unknown error'}.\n"
+                    f"   The output was still saved successfully to the output file."
+                )
+
+    except FileNotFoundError as e:
+        print(f"❌ Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except IOError as e:
+        print(f"❌ Write Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"❌ Unexpected Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

py_for_ai-0.1.0/src/py_ai/core.py

@@ -0,0 +1,264 @@
+"""
+core.py module
+==============
+Contains the core business logic for the py-ai utility:
+- File and directory ignore checks (should_ignore).
+- Project directory tree generation in ASCII format.
+- Gathering allowed file contents and writing them to the final context file.
+- Copying the generated output to the system clipboard.
+"""
+
+import os
+import sys
+from pathlib import Path
+from datetime import datetime
+import pyperclip
+
+# Standard lists of exclusions for ignore checks
+IGNORED_NAMES = {
+    # Version control and system folders
+    '.git', '.github', '.gitlab', '.svn', '.hg', 'node_modules',
+    # Python runtime and caches
+    '__pycache__', '.venv', 'venv', 'env', '.env', '.pytest_cache',
+    '.mypy_cache', '.ruff_cache', '.tox', '.nox', '.egg-info', 'build', 'dist',
+    # IDE and editor settings
+    '.idea', '.vscode', '.settings',
+    # OS system files
+    '.DS_Store', 'Thumbs.db', 'desktop.ini'
+}
+
+IGNORED_EXTENSIONS = {
+    # Compiled Python and binary artifacts
+    '.pyc', '.pyo', '.pyd', '.class', '.o', '.obj', '.dll', '.so', '.dylib',
+    # Archives/Compressed files
+    '.zip', '.tar', '.gz', '.bz2', '.xz', '.rar', '.7z', '.tgz',
+    # Images and multimedia
+    '.png', '.jpg', '.jpeg', '.gif', '.bmp', '.ico', '.webp', '.tiff', '.svg',
+    '.mp3', '.wav', '.ogg', '.flac', '.mp4', '.mkv', '.avi', '.mov', '.webm',
+    # Fonts
+    '.woff', '.woff2', '.ttf', '.eot', '.otf',
+    # Databases and binary documents
+    '.db', '.sqlite', '.sqlite3', '.pdf', '.epub',
+    # Office documents
+    '.docx', '.xlsx', '.pptx', '.doc', '.xls', '.ppt'
+}
+
+
+def should_ignore(path: Path, root_dir: Path) -> bool:
+    """
+    Checks if a file or directory should be ignored based on standard exclusions.
+
+    :param path: Path to the file or folder to verify.
+    :param root_dir: Root directory of the project.
+    :return: True if the path should be ignored, False otherwise.
+    """
+    try:
+        # Resolve to absolute paths to avoid issues with relative path operations
+        abs_root = root_dir.resolve()
+        abs_path = path.resolve()
+        # Calculate path relative to the root directory
+        rel_path = abs_path.relative_to(abs_root)
+    except ValueError:
+        # Fallback if the path is not under the root directory
+        rel_path = path
+
+    # Check each part of the relative path.
+    # If any parent folder is in the ignored list, ignore the entire subtree.
+    for part in rel_path.parts:
+        if part in IGNORED_NAMES or part.lower() in IGNORED_NAMES:
+            return True
+        
+        # Ignore any hidden folders/files (starting with a dot),
+        # except allowed configuration files such as .gitignore or .env.example
+        if part.startswith('.') and part not in ('.gitignore', '.env.example', '.env.template', '.pylintrc'):
+            return True
+
+    # Additional file-level checks for extensions and file names
+    if path.is_file():
+        if path.suffix.lower() in IGNORED_EXTENSIONS:
+            return True
+        if path.name.lower() in IGNORED_NAMES:
+            return True
+
+    return False
+
+
+def build_tree_lines(path: Path, root_dir: Path, prefix: str = "", is_last: bool = True, is_root: bool = False) -> list[str]:
+    """
+    Recursively generates the ASCII project tree, skipping ignored files and folders.
+
+    :param path: Current path (file or folder).
+    :param root_dir: Root directory of the project (for should_ignore checks).
+    :param prefix: Prefix for the current line (indentation and connection symbols).
+    :param is_last: Whether the current item is the last one in its parent directory.
+    :param is_root: Whether the current item is the root folder of the project.
+    :return: List of strings forming the ASCII tree.
+    """
+    lines = []
+    
+    # Root directory displays with its name and a trailing slash
+    if is_root:
+        lines.append(f"{path.name}/")
+    else:
+        connector = "└── " if is_last else "├── "
+        display_name = path.name + ("/" if path.is_dir() else "")
+        lines.append(f"{prefix}{connector}{display_name}")
+
+    if path.is_dir():
+        try:
+            # List directory items, sort them: directories first, then files (case-insensitive)
+            # Filter out any ignored items immediately
+            items = sorted(
+                [item for item in path.iterdir() if not should_ignore(item, root_dir)],
+                key=lambda x: (not x.is_dir(), x.name.lower())
+            )
+        except OSError as e:
+            # Handle permission errors or system issues gracefully in the tree
+            connector = "└── " if is_last else "├── "
+            lines.append(f"{prefix}{connector}[Permission denied/Error accessing directory: {e}]")
+            return lines
+
+        for i, item in enumerate(items):
+            item_is_last = (i == len(items) - 1)
+            # Calculate next indentation prefix for child elements
+            if is_root:
+                next_prefix = ""
+            else:
+                next_prefix = prefix + ("    " if is_last else "│   ")
+            
+            lines.extend(build_tree_lines(item, root_dir, next_prefix, item_is_last, is_root=False))
+
+    return lines
+
+
+def pack_project(root_dir: str | Path, output_file: str | Path, copy_to_clipboard: bool = True) -> dict:
+    """
+    Recursively scans the project, builds an ASCII tree, gathers all text file contents,
+    saves the aggregated output to a single file, and copies it to the system clipboard.
+
+    :param root_dir: Path to the root folder of the project.
+    :param output_file: Path to the target output text file.
+    :param copy_to_clipboard: Whether to copy the generated context to the clipboard.
+    :return: Dictionary containing execution statistics.
+    """
+    root_path = Path(root_dir).resolve()
+    output_path = Path(output_file).resolve()
+
+    if not root_path.exists() or not root_path.is_dir():
+        raise FileNotFoundError(f"The specified directory '{root_path}' does not exist or is not a directory.")
+
+    # 1. Generate the ASCII directory tree
+    tree_lines = build_tree_lines(root_path, root_path, is_root=True)
+    tree_text = "\n".join(tree_lines)
+
+    # 2. Collect all allowed files for code packing
+    files_to_pack = []
+
+    def recursive_walk(current_dir: Path):
+        try:
+            # Sort items for a deterministic walking order
+            items = sorted(current_dir.iterdir(), key=lambda x: (not x.is_dir(), x.name.lower()))
+        except PermissionError as e:
+            print(f"Warning: Permission denied reading directory {current_dir}: {e}", file=sys.stderr)
+            return
+
+        for item in items:
+            if should_ignore(item, root_path):
+                continue
+            if item.is_dir():
+                recursive_walk(item)
+            elif item.is_file():
+                # Avoid packing the output file itself if it is located inside the root project directory
+                if item.resolve() == output_path:
+                    continue
+                files_to_pack.append(item)
+
+    recursive_walk(root_path)
+
+    # 3. Read file contents and format blocks
+    content_blocks = []
+    packed_count = 0
+    failed_count = 0
+
+    for file_path in files_to_pack:
+        try:
+            rel_path = file_path.relative_to(root_path).as_posix()
+        except ValueError:
+            rel_path = file_path.as_posix() if hasattr(file_path, "as_posix") else str(file_path)
+
+        try:
+            # Read files using UTF-8 encoding
+            with open(file_path, "r", encoding="utf-8") as f:
+                content = f.read()
+
+            # Format the code block with clean delimiters
+            block = f"--- START OF FILE: {rel_path} ---\n{content}\n--- END OF FILE: {rel_path} ---"
+            content_blocks.append(block)
+            packed_count += 1
+        except UnicodeDecodeError:
+            # Handle binary files that cannot be decoded as standard text
+            print(f"Warning: Skipped '{rel_path}' due to encoding error (likely a binary file).", file=sys.stderr)
+            failed_count += 1
+        except PermissionError:
+            print(f"Warning: Skipped '{rel_path}' due to permission error.", file=sys.stderr)
+            failed_count += 1
+        except Exception as e:
+            print(f"Warning: Skipped '{rel_path}' due to an error: {e}", file=sys.stderr)
+            failed_count += 1
+
+    # 4. Formulate the single aggregated output
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    
+    header = (
+        "================================================================================\n"
+        f"PROJECT CONTEXT PACK: {root_path.name}\n"
+        f"Generated on: {timestamp}\n"
+        f"Total files packed: {packed_count}\n"
+        "================================================================================\n"
+    )
+
+    tree_section = (
+        "================================================================================\n"
+        "DIRECTORY TREE\n"
+        "================================================================================\n"
+        f"{tree_text}\n"
+    )
+
+    files_section_header = (
+        "================================================================================\n"
+        "FILES CONTENT\n"
+        "================================================================================\n"
+    )
+
+    files_content = "\n\n".join(content_blocks)
+    full_output = f"{header}\n{tree_section}\n{files_section_header}\n{files_content}\n"
+
+    # 5. Write to the output file
+    try:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(full_output)
+    except Exception as e:
+        raise IOError(f"Failed to write results to '{output_path}': {e}")
+
+    # 6. Copy to the system clipboard if enabled
+    clipboard_copied = False
+    clipboard_error = None
+
+    if copy_to_clipboard:
+        try:
+            pyperclip.copy(full_output)
+            clipboard_copied = True
+        except Exception as e:
+            clipboard_error = str(e)
+            print(f"Warning: Could not copy to clipboard: {e}", file=sys.stderr)
+
+    return {
+        "root_dir": str(root_path),
+        "output_file": str(output_path),
+        "packed_count": packed_count,
+        "failed_count": failed_count,
+        "clipboard_copied": clipboard_copied,
+        "clipboard_error": clipboard_error,
+        "file_size": len(full_output)
+    }