# Empty Trash

Console script for permanently deleting trashed content that has exceeded a
configurable retention period. The script processes all Plone sites in a Zope
instance and removes items from the trash container that are older than the
specified number of days.

## Overview

When content is deleted by editors, it is moved to a per-site trash container
(`cms_trash_container`) rather than being permanently removed. Over time the
trash accumulates and should be cleaned up. The `empty-trash` console script
automates this cleanup by permanently deleting trashed items older than a given
retention threshold.

Key characteristics:

- Operates on **all Plone sites** within the Zope instance
- Uses each item's trashed timestamp (UTC ISO format annotation) to determine age
- Permanently deletes items using `manage_immediatelyDeleteObjects` (bypasses the trash)
- Commits per Plone site to limit transaction size
- Logs per-site deletion counts


## Usage

```bash
./bin/empty-trash <path-to-zope.conf> <days>
```

**Arguments:**

| Argument | Description |
|---|---|
| `zopeconf` | Absolute path to the Zope configuration file (`zope.conf`) |
| `days` | Number of days to retain trashed items. Items older than this are deleted. |

**Example:**

```bash
# Delete all trashed items older than 30 days
./bin/empty-trash instance/etc/zope.conf 30

# Delete all trashed items older than 90 days
./bin/empty-trash instance/etc/zope.conf 90
```


## Scheduling with Cron

The script is designed to be run as a scheduled task. A typical cron entry:

```bash
# Run nightly at 2:00 AM, delete items trashed more than 30 days ago
0 2 * * * /path/to/bin/empty-trash /path/to/instance/etc/zope.conf 30
```


## Logging

The script logs to the `wcs.backend.trash.empty_trash` logger at INFO level.
Output is written to stdout with the format `%(message)s`.

Example output:

```text
mysite: Deleted 12 item(s) older than 30 days.
othersite: No items older than 30 days.
thirdsite: No trash container found, skipping.
```


## File Locations

- **Console script**: `wcs/backend/trash/empty_trash.py`
- **Entry point**: `empty-trash = wcs.backend.trash.empty_trash:main` (in `setup.py`)
- **Trash utilities**: `wcs/backend/trash/utils.py`
- **Trasher (annotation handling)**: `wcs/backend/trash/trasher.py`