Metadata-Version: 2.4
Name: autoffice
Version: 0.2.0
Summary: Automate Microsoft Excel (.xlsx) files from the command line.
License: MIT
Keywords: excel,xlsx,automation,cli,spreadsheet
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: openpyxl>=3.1
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: types-openpyxl>=3.1; extra == "dev"
Provides-Extra: build
Requires-Dist: pyinstaller>=6.8; extra == "build"

# Autoffice

A local-first command-line tool for automating Microsoft Excel (`.xlsx`) files.
Reads a JSON mapping file, updates one or more cells across one or more worksheets,
optionally applies formatting changes, and saves the result as a new workbook —
**without ever touching the original file**.

Works on **Linux x86_64, Linux ARM64, Raspberry Pi, Android Termux, Windows, and macOS**.
Pure Python runtime — **no Rust, Cargo, or compiler required**.

## Install

```bash
pip install autoffice
```

Or download a pre-built binary from the [Releases](../../releases) page (no Python required):

| Platform | File |
|---|---|
| Linux x86\_64 | `autoffice-linux-x86_64` |
| Linux ARM64 (Raspberry Pi, servers) | `autoffice-linux-arm64` |
| Windows x86\_64 | `autoffice-windows-x86_64.exe` |
| macOS Intel | `autoffice-macos-x86_64` |
| macOS Apple Silicon | `autoffice-macos-arm64` |
| Debian/Ubuntu amd64 | `autoffice_<ver>_amd64.deb` |
| Debian/Ubuntu arm64 | `autoffice_<ver>_arm64.deb` |

### Android Termux

On Android Termux, install via pip (the pre-built Linux binary uses glibc and
will not run on Termux's Bionic libc):

```bash
pkg install python
pip install autoffice
```

### Debian / Ubuntu (.deb)

```bash
wget https://github.com/your-org/autoffice/releases/latest/download/autoffice_0.2.0_amd64.deb
sudo dpkg -i autoffice_0.2.0_amd64.deb
```

## Usage

```
autoffice fill <workbook.xlsx> <mapping.json> [--force]
```

Example:

```bash
autoffice fill report.xlsx data.json
```

Writes `report_filled.xlsx` next to `report.xlsx`.

Use `--force` / `-f` to overwrite an existing output file.

## Mapping file format

Each key uses `<SheetName>!<CellReference>` notation.

```json
{
  "Sheet1!B19": {
    "value": "Hasan",
    "bold": true
  },
  "Sheet1!C19": {
    "value": 50000
  },
  "Summary!A1": {
    "value": "Completed",
    "italic": true,
    "font_size": 12
  }
}
```

### Cell update fields

| Field | Type | Required | Description |
|---|---|---|---|
| `value` | any | ✅ | New cell value (`null` clears the cell) |
| `bold` | bool | — | Set bold on/off |
| `italic` | bool | — | Set italic on/off |
| `font_size` | number > 0 | — | Font size in points |

Only the fields you specify are changed — all other font attributes
(name, colour, underline, etc.) are preserved as-is.

## Logging

Set `AUTOFFICE_LOG_LEVEL` to enable verbose output:

```bash
# Show what cells are being updated
AUTOFFICE_LOG_LEVEL=INFO autoffice fill report.xlsx data.json

# Full debug trace (workbook open, each cell, save path)
AUTOFFICE_LOG_LEVEL=DEBUG autoffice fill report.xlsx data.json
```

Accepted values: `DEBUG`, `INFO`, `WARNING` (default), `ERROR`.

## Validation

Validation runs **before** any writes. If validation fails:

- No cells are modified
- No output file is created
- Exit code `1` is returned
- A human-readable error message is printed

What is validated:

- Key format must be `<SheetName>!<CellRef>`
- Cell reference must be valid (`A1`, `AA500`, …)
- Every referenced worksheet must exist in the workbook
- `font_size` must be a positive number

## Exit codes

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | Validation or usage error |
| `2` | Unexpected internal error |

## Development

```bash
pip install -e ".[dev]"

# Run tests
pytest

# Lint & format
ruff check autoffice tests
ruff format autoffice tests

# Type-check
mypy autoffice
```

## CI / CD

GitHub Actions runs automatically on every push and pull request:

1. **Lint** — ruff + mypy
2. **Tests** — pytest on Python 3.11, 3.12, and 3.13
3. **Build** — PyInstaller binaries for five platform targets
4. **Deb** — `.deb` packages for amd64 and arm64
5. **Release** — GitHub Release with all binaries and `.deb` files (triggered by `v*.*.*` tags)

To release a new version:

```bash
# Bump version in autoffice/__init__.py and pyproject.toml, then:
git tag v0.2.0
git push origin v0.2.0
```

## Compatibility

| Platform | pip install | Binary |
|---|---|---|
| Linux x86\_64 | ✅ | ✅ |
| Linux ARM64 | ✅ | ✅ |
| Android Termux ARM64 | ✅ | ❌ (glibc binary, use pip) |
| Raspberry Pi | ✅ | ✅ (arm64) |
| Windows x86\_64 | ✅ | ✅ |
| macOS Intel | ✅ | ✅ |
| macOS Apple Silicon | ✅ | ✅ |

Python versions: **3.11, 3.12, 3.13**

## Non-goals (v1)

- Formula evaluation
- `.xls` / `.xlsm` support
- YAML / CSV input
- Template engines
- Cloud services / COM automation
- GUI
