---

📖 Overview

pycociC traverses directory trees or entire disk drives to safely detect and delete compiled Python bytecode (.pyc, .pyo) and Numba JIT cache files (.nbc, .nbi) located inside __pycache__ directories.

It automatically prunes empty __pycache__ directories after cleaning, and outputs clear, human-readable statistics on freed disk space.

---

✨ Key Features

• ⚡ Recursive Cache Removal: Scans project directories or all mounted system partitions.
• 🎯 Broad Cache Coverage: Cleans CPython bytecode (.pyc, .pyo) as well as Numba cache files (.nbc, .nbi).
• 📂 Empty Directory Pruning: Removes leftover empty __pycache__ folders upon file deletion.
• 📊 Human-Readable Metrics: Accurately reports reclaimed space using clear SI units (B, kB, MB, GB, up to YB).
• 🛡️ Safe & Fault-Tolerant: Silently bypasses permission-restricted files and runs in an isolated thread with raised recursion limits to navigate deeply nested directory structures.
• 🖥️ CLI & Library: Use directly from terminal (pycocic) or integrate seamlessly into your Python code or CI/CD pipelines.

---

📦 Installation

Install pycociC using your preferred package manager:

Via pip

pip install pycociC

Via pipx (recommended for standalone CLI use)

pipx install pycociC

Via Poetry

poetry add pycociC

---

🚀 CLI Usage

Recommended Command

When cleaning bytecode files, run with Python's -B flag or set PYTHONDONTWRITEBYTECODE=1 to prevent Python from recreating new .pyc files while running the cleaner itself:

python -B -m pycociC -d .

Or via the installed console entrypoint:

PYTHONDONTWRITEBYTECODE=1 pycocic -d .

CLI Arguments

usage: pycociC [-h] [-t DIRS [DIRS ...]]

pycociC - A tool to remove pycache (and numba cache) files

options:
  -h, --help            Show this help message and exit
  -t, -d, --dirs DIRS [DIRS ...]
                        Directories to search for pycache files (default: all mounted disks)

Examples

Clean Specific Directories

python -B -m pycociC -d ./src ./tests

Output:

Starting for ./src, ./tests


src/__pycache__
	module.cpython-311.pyc (3kB 210B)
	helpers.cpython-311.pyc (1kB 450B)
src/__pycache__

tests/__pycache__
	test_module.cpython-311.pyc (2kB 890B)
tests/__pycache__


Removed 7kB 550B

Clean All Disks

python -B -m pycociC

Starting for /, /mnt/data


/home/user/projects/api/__pycache__
	main.cpython-310.pyc (4kB 699B)
	config.cpython-310.pyc (1kB 153B)
/home/user/projects/api/__pycache__

...

Removed 42MB 318kB 912B

---

🐍 Python API

You can also use pycociC programmatically in your build scripts, cleanup routines, or automation tasks:

from pycociC import eat_cache, bytes_to_pretty_view, dont_write_bytecode

# 1. Clean cache files in specified directories
eat_cache(at_dirs=['./backend', './workers'])

# 2. Check if the current environment suppresses bytecode creation
if not dont_write_bytecode():
    print("Warning: Bytecode generation is currently enabled.")

# 3. Format byte sizes nicely into human-readable strings
print(bytes_to_pretty_view(0))              # '0B'
print(bytes_to_pretty_view(1_000_024))      # '1MB 24B'
print(bytes_to_pretty_view(4_294_967_295))  # '4GB 294MB 967kB 295B'

Available API Functions

Function	Description
eat_cache(at_dirs=('.'))	Recursively cleans matching cache files from __pycache__ folders under at_dirs and prints summary.
bytes_to_pretty_view(bytes_size, *, skip_zero=False)	Converts byte counts to formatted SI representation (B, kB, MB, GB, etc.).
dont_write_bytecode()	Returns True if PYTHONDONTWRITEBYTECODE or -B is active, otherwise False.
FP_RE	Compiled regular expression matching target cache extensions (`.*.py([co]

---

🛠️ How It Works

1. Target Regex (FP_RE): Matches files ending in .pyc, .pyo, .nbc, and .nbi inside directories named __pycache__.
2. Drive Auto-Detection: Uses psutil.disk_partitions(all=True) to automatically discover all mounted storage devices when no specific directory argument is provided.
3. Recursion Safety: Decorator _run_with_max_recursion executes directory traversals in a dedicated thread with increased recursion limits (sys.setrecursionlimit) and custom stack sizes, preventing RecursionError on deeply nested directory trees.

---

🧪 Development & Testing

1. Clone the repository:

   git clone https://github.com/ndenissov/pycociC.git
   cd pycociC
   

2. Install dependencies with Poetry:

   poetry install
   

3. Run the doctest suite:

   poetry run python -m doctest -v pycociC/__init__.py
   

---

📄 License

Distributed under the MIT License.

Copyright (c) 2022-2026 Nikita Denissov.