# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

`upyog` is a Python utility library collecting commonly used functions across various projects. It provides utilities for image manipulation, OS operations, ML/data science workflows, and general Python development.

## Build and Test Commands

```bash
# Install for development
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run a single test file
pytest tests/utils/utils_test.py

# Build for PyPI
python setup.py sdist bdist_wheel
twine check dist/*

# Upload to PyPI
twine upload --repository pypi dist/*
```

## Architecture

### Module Structure

- **`upyog.all`** - Convenience import that loads everything plus initializes logging/tqdm
- **`upyog.imports`** - Common imports and the `PathLike` type alias
- **`upyog.cli`** - CLI utilities built on `fastcore.script` with custom `Param`/`P` classes and `@call_parse` decorator

### Subpackages

- **`upyog.image`** - PIL Image utilities including:
  - Operator overloading: `img1 | img2` (horizontal join), `img1 // img2` (vertical join)
  - I/O, drawing, composition, and visualization functions

- **`upyog.os`** - File system utilities, path operations, and pathlib patches

- **`upyog.utils`** - General utilities: boxes, downloads, zip handling, DataFrame prettification, dates, `Dictionary` class for dot notation access

- **`upyog.ml`** - ML utilities: activations, preprocessing, model utils, UMAP, CoreML support (conditional)

- **`upyog.ann`** - Approximate nearest neighbor utilities (Annoy-based)

### CLI Entry Points

Defined in `setup.cfg` under `[options.entry_points]`:
- `remove-duplicates-from-folder`
- `print-folder-distribution`
- `generate-image-grid`
- `add-parent-folder-name`
- `move-files`
- `find-common-files-between-folders`
- `nb2script`
- `img-downloader`
- `extract-and-organise-tar-archive`

### Key Patterns

- Uses `fastcore.patch` decorator to add methods to existing classes (e.g., PIL.Image operators)
- Uses `loguru` for logging with color support
- The `@call_parse` decorator creates functions usable both as regular code and CLI commands
