==========
piw-remove
==========

The piw-remove script is used to manually remove a package (or a version of a
package) from the system. All builds for the specified package (or version)
will be forgotten, and all files generated by such builds will be deleted.

By default, the package (or version) removed will be deleted entirely (*not*
marked to skip). Optionally, you can provide a skip reason; in this case the
version will not be deleted (though its builds and files will), but will be
left marked to skip to prevent future rebuilds.

Synopsis
========

.. code-block:: text

    piw-remove [-h] [--version] [-c FILE] [-q] [-v] [-l FILE] [-y]
               [-s REASON] [--import-queue ADDR]
               package [version]

Description
===========

.. program:: piw-remove

.. option:: package

    The name of the package to remove

.. option:: version

    The version of the package to remove. If omitted, removes the entire
    package

.. option:: -h, --help

    Show this help message and exit

.. option:: --version

    Show program's version number and exit

.. option:: -c FILE, --configuration FILE

    Specify a configuration file to load

.. option:: -q, --quiet

    Produce less console output

.. option:: -v, --verbose

    Produce more console output

.. option:: -l FILE, --log-file FILE

    Log messages to the specified file

.. option:: -y, --yes

    Run non-interactively; never prompt during operation

.. option:: -s REASON, --skip REASON

    Leave the version in place, but marked with a reason to prevent future
    build attempts

.. option:: --import-queue ADDR

    The address of the queue used by piw-remove (default:
    (ipc:///tmp/piw-import); this should always be an ipc address


Usage
=====

This utility is typically used in response to a request from a package
maintainer to remove a specific build from the system. Usually because the
presence of a piwheels build is causing issues in and of itself.

.. note::

    Older versions of piwheels didn't heed PyPI deletion messages. This is no
    longer the case and this utility is no longer required to manually remove
    deleted packages.

The utility can be run in a batch mode with :option:`--yes` but still requires
invoking once per deletion required (you cannot remove multiple versions in a
single invocation).

The return code will be 0 if the package (or version) was successfully removed.
If anything fails, the return code will be non-zero and no files should be
deleted (but this cannot be guaranteed in all circumstances).

The utility should only ever be run directly on the master node (opening the
import queue to other machines is a potential security risk).