pyinitgen 4.0.1

Auto-generate missing __init__.py files to fix Python import issues and ensure proper module discovery.

pyinitgen

Auto-generate missing __init__.py files to fix Python import issues and ensure proper module discovery.

---

⚡ Quick Start

Prerequisites

• Python 3.8 or higher

Installation

pip install pyinitgen

Run

Navigate to your project root and run:

pyinitgen

Demo

# Preview changes without writing (Safe Mode)
pyinitgen --dry-run

# Run and fix your project structure
pyinitgen
# Output:
# Created src/utils/__init__.py
# ✅ Operation complete. Scanned 43 dirs, created 8 new __init__.py files.

---

✨ Features

• 📂 Recursive Scan: Intelligently walks your directory tree to find all Python module folders.
• 🛠️ Auto-creates __init__.py: Generates files only where they are missing.
• 🧠 Smart Exclusions: Automatically ignores node_modules, .git, __pycache__, venv, and other non-Python directories.
• ✍️ Custom Content: Inject custom code (e.g., license headers) into every new __init__.py.
• 👀 Dry-Run Mode: Visualize changes before applying them.
• ✅ Check Flag: CI/CD ready—exit with an error if files are missing without modifying disk.
• 🔒 Zero Destructive Actions: Never overwrites existing files.

---

🛠️ Configuration

Environment Variables

Name	Description	Default	Required
CREATE_DUMP_PALETTE	Select a fixed color palette index (0-5) for the logo.	None (Procedural)	No

CLI Arguments

Flag	Short	Description
--base-dir		Base directory to scan (default: current directory).
--dry-run		Preview changes without writing to disk.
--quiet	-q	Suppress all non-error output.
--verbose	-v	Show all scanned directories (debug mode).
--no-emoji		Disable emoji in the final output.
--init-content		Custom content to write to new __init__.py files.
--check		Check for missing __init__.py files and exit with code 1 if found.
--version		Show the program's version number and exit.

Configuration Files

You can define permanent exclusions in pyproject.toml or .pyinitgen.toml.

pyproject.toml example:

[tool.pyinitgen]
exclude_dirs = ["legacy_code", "test_data"]

.pyinitgenignore example: Create a .pyinitgenignore file in your root to list folders to skip (one per line).

assets
legacy
temp_builds

---

🏗️ Architecture

pyinitgen follows a standard Python CLI structure designed for maintainability and speed.

src/
└── pyinitgen/
    ├── __init__.py
    ├── banner.py   # 🎨 Renders the procedural ASCII art logo
    ├── cli.py      # 🧠 Core logic: Scan, Detect, Create
    ├── config.py   # ⚙️ Configuration loader (TOML handling)
    └── ignores.py  # 🚫 Ignore pattern processing

Data Flow:

1. CLI Entry: Arguments are parsed.
2. Config Load: Global config, local TOML files, and .pyinitgenignore are merged.
3. Walker: Directory tree is traversed, filtering out excluded paths.
4. Creator: Missing __init__.py files are identified and created (or reported in Dry Run).

---

🐞 Troubleshooting

Error Message	Possible Cause	Solution
ModuleNotFoundError: No module named 'rich'	Missing dependency.	Run pip install pyinitgen --upgrade.
Permission denied: '.../__init__.py'	File system permissions.	Run with appropriate permissions or check folder ownership.
No files created	Directories might be ignored.	Check pyproject.toml or .pyinitgenignore exclusions. Use -v to debug.

Debug Mode: Use the verbose flag to see exactly what directories are being scanned:

pyinitgen -v --dry-run

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on how to set up your development environment, run tests, and submit PRs.

Development Setup

1. Clone the repo.
2. Install dev dependencies: pip install -e ".[dev]"
3. Run tests: python -m pytest tests/

---

🗺️ Roadmap

• Custom Exclusions: Support for config files.
• CI/CD Check: --check flag for pipelines.
• Watch Mode: Auto-generate files as directories are created.
• Interactive Mode: Confirm each file creation.

---

GitHub Repository • Report an Issue