Metadata-Version: 2.4
Name: pycociC
Version: 1.1.3
Summary: Remove pycache (and numba cache) files
License-Expression: MIT
License-File: LICENSE
Author: Nikita Denissov
Author-email: n.denissov@proton.me
Requires-Python: >=3.8
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Dist: psutil (>=5.9.0)
Project-URL: Homepage, https://github.com/ndenissov/pycociC
Project-URL: Issues, https://github.com/ndenissov/pycociC/issues
Project-URL: Repository, https://github.com/ndenissov/pycociC
Description-Content-Type: text/markdown

<div align="center">

# 🧹 pycociC

**High-performance, lightweight utility for cleaning Python and Numba bytecode cache files.**

*(Pronounced: **"py-cocky-C(leaner)"** — your bold little cache eater!)*

[![PyPI version](https://img.shields.io/pypi/v/pycociC.svg)](https://pypi.org/project/pycociC/)
[![Downloads](https://static.pepy.tech/badge/pycociC)](https://pepy.tech/project/pycociC)
[![Python versions](https://img.shields.io/pypi/pyversions/pycociC.svg)](https://pypi.org/project/pycociC/)
[![License](https://img.shields.io/pypi/l/pycociC.svg)](https://github.com/ndenissov/pycociC/blob/main/LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/ndenissov/pycociC)](https://github.com/ndenissov/pycociC/stargazers)

</div>

---

## 📖 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
```bash
pip install pycociC
```

### Via pipx (recommended for standalone CLI use)
```bash
pipx install pycociC
```

### Via Poetry
```bash
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:

```bash
python -B -m pycociC -d .
```

Or via the installed console entrypoint:

```bash
PYTHONDONTWRITEBYTECODE=1 pycocic -d .
```

### CLI Arguments

```text
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

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

**Output:**
```text
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

```bash
python -B -m pycociC
```

```text
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
```

> [!TIP]
> If you run `pycociC` without `-B` or without `PYTHONDONTWRITEBYTECODE`, a warning will be logged to remind you so that newly spawned bytecode doesn't immediately take up space.

---

## 🐍 Python API

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

```python
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]|.*\.nb[ci])`). |

---

## 🛠️ 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:
   ```bash
   git clone https://github.com/ndenissov/pycociC.git
   cd pycociC
   ```

2. Install dependencies with Poetry:
   ```bash
   poetry install
   ```

3. Run the doctest suite:
   ```bash
   poetry run python -m doctest -v pycociC/__init__.py
   ```

---

## 📄 License

Distributed under the [MIT License](https://github.com/ndenissov/pycociC/blob/main/LICENSE).

Copyright (c) 2022-2026 Nikita Denissov.

