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

.. code-block:: bash

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

**Arguments:**

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - 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:**

.. code-block:: 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:

.. code-block:: 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:

.. code-block:: 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``