Metadata-Version: 2.3
Name: instawow
Version: 4.4.2
Summary: World of Warcraft add-on manager
Project-URL: homepage, http://github.com/layday/instawow
Author-email: layday <layday@protonmail.com>
License-Expression: GPL-3.0-or-later
License-File: COPYING
Requires-Python: >=3.10
Requires-Dist: aiohttp-client-cache>=0.9.1
Requires-Dist: aiohttp<4,>=3.9.3
Requires-Dist: attrs>=23.2.0
Requires-Dist: cattrs>=23.2.3
Requires-Dist: click>=8.1.6
Requires-Dist: diskcache>=5.6.3
Requires-Dist: iso8601>=1.0.2; python_version < '3.11'
Requires-Dist: loguru>=0.7.2
Requires-Dist: packaging>=23.2
Requires-Dist: pluggy>=1.4.0
Requires-Dist: prompt-toolkit>=3.0.44
Requires-Dist: rapidfuzz>=3.6.1
Requires-Dist: truststore>=0.7.0; python_version < '3.13'
Requires-Dist: truststore>=0.9.1; python_version >= '3.13'
Requires-Dist: typing-extensions>=4.11.0; python_version < '3.13'
Requires-Dist: typing-extensions>=4.12.0rc1; python_version >= '3.13'
Requires-Dist: yarl>=1.9.3
Provides-Extra: gui
Requires-Dist: aiohttp-rpc>=1.0.0; extra == 'gui'
Requires-Dist: toga-core>=0.4.5; extra == 'gui'
Requires-Dist: toga>=0.4.5; extra == 'gui'
Provides-Extra: skeletal-gui
Requires-Dist: aiohttp-rpc>=1.0.0; extra == 'skeletal-gui'
Requires-Dist: toga-core>=0.4.5; extra == 'skeletal-gui'
Provides-Extra: test
Requires-Dist: anyio>=4.3.0; extra == 'test'
Requires-Dist: aresponses>=3; extra == 'test'
Requires-Dist: coverage[toml]>=7.4.3; extra == 'test'
Requires-Dist: pytest-xdist>=3.5.0; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Provides-Extra: types
Requires-Dist: diskcache-stubs; extra == 'types'
Description-Content-Type: text/x-rst

*instawow*
==========

.. image:: https://img.shields.io/matrix/wow-addon-management:matrix.org
   :target: https://matrix.to/#/#wow-addon-management:matrix.org?via=matrix.org
   :alt: Matrix channel

*instawow* is an add-on manager for World of Warcraft.
It can be used to install, update and remove add-ons from GitHub,
CurseForge, WoWInterface and Tukui.
*instawow* has an interoperable CLI and GUI, fuzzy search with download scoring
and several other goodies.

.. list-table::
   :widths: 50 50

   * - .. figure:: https://asciinema.org/a/8m36ncAoyTmig4MXfQM8YjE6a.svg
          :target: https://asciinema.org/a/8m36ncAoyTmig4MXfQM8YjE6a?autoplay=1
          :alt: Asciicast demonstrating the operation of instawow
          :width: 640
     - .. figure:: https://raw.githubusercontent.com/layday/instawow/main/instawow-gui/screenshots/v1.34.1.png
          :target: https://github.com/layday/instawow/releases/latest
          :alt: instawow-gui main window
          :width: 640

Installation
------------

You can download `pre-built binaries  <https://github.com/layday/instawow/releases/latest>`__
of *instawow* from GitHub.  `bin <https://github.com/marcosnils/bin>`__
users can install the CLI binaries by running::

    bin install github.com/layday/instawow

If you'd prefer to install *instawow* from source, you are able to choose from:

- `pipx <https://github.com/pipxproject/pipx>`__:
  ``pipx install instawow`` or ``pipx install instawow[gui]`` for the GUI
- Vanilla pip:
  ``python -m pip install -U instawow`` or ``python -m pip install -U instawow[gui]`` for the GUI
- `Nix or NixOS <https://nixos.org/>`__: the CLI-only version of *instawow*
  is available as the ``instawow`` package.

CLI operation
-------------

tl;dr
~~~~~

Begin by running ``instawow reconcile``
to register previously-installed add-ons with *instawow*
(or ``instawow reconcile --auto`` to do the same without user input).
To install add-ons, you can search for them using the ``search`` command::

    instawow search molinari

In addition, *instawow* is able to interpret add-on URLs and *instawow*-specific
URIs of slugs and host IDs.
All of the following will install Molinari::

    instawow install https://www.curseforge.com/wow/addons/molinari
    instawow install curse:molinari
    instawow install curse:20338
    instawow install https://github.com/p3lim-wow/Molinari
    instawow install github:p3lim-wow/molinari

You can ``update`` add-ons and ``remove`` them just as you'd install them.
If ``update`` is invoked without arguments, it will update all of your
installed add-ons.  You can ``list`` add-ons and view detailed information about
them using ``list --format detailed``.
For ``list`` and similarly non-destructive commands, the source can be omitted
and the alias can be shortened, e.g. ``instawow reveal moli``
will bring up the Molinari add-on folder in your file manager.

Add-on reconciliation
~~~~~~~~~~~~~~~~~~~~~

Add-on reconciliation is not automatic – *instawow* makes a point
of not automatically assuming ownership of your add-ons.
However, you can automate reconciliation with ``reconcile --auto``
and *instawow* will prioritise add-ons from CurseForge.
Reconciled add-ons are reinstalled because the installed version cannot be
extracted reliably.

Add-on search
~~~~~~~~~~~~~

*instawow* comes with a rudimentary ``search`` command
with results ranked based on edit distance and popularity.
Search uses a collated add-on catalogue which is updated
`once daily <https://github.com/layday/instawow-data/tree/data>`__.
You can install multiple add-ons directly from search.

Install strategies
~~~~~~~~~~~~~~~~~~

Add-ons take a number of options which determine how they are resolved:

- ``any_flavour`` to ignore game version compatibility by prioriting "affine" game versions
- ``any_release_type`` to ignore add-on stability
- ``version_eq=[VERSION]`` to install a specific add-on version

In the CLI, you can pass strategies in the fragment portion of the add-on URI,
separated by a comma, e.g. ``instawow install curse:molinari#any_release_type,any_flavour``.
Strategies are respected by ``install`` and ``update``.  To reset an add-on's strategies on update,
you can pass a ``=`` fragment, e.g. ``instawow update curse:molinari#=``.

Reverting add-on updates
~~~~~~~~~~~~~~~~~~~~~~~~

*instawow* keeps a log of all versions of an add-on it has previously
installed.
Add-on updates can be undone using the ``instawow rollback`` command.
Add-ons which have been rolled back are pinned and will not receive updates.
Rollbacks can themselves be undone with ``instawow rollback --undo``,
which will install the latest version of the specified add-on using
the ``default`` strategy.

Profiles
~~~~~~~~

*instawow* supports multiple game versions by means of profiles.
Assuming your default profile is configured for retail,
you can create a pristine profile for classic with::

    instawow -p classic configure

"``classic``" is simply the name of the profile; you will be asked to select
the game flavour that it corresponds to.  You can have several profiles
of the same flavour (think alpha, beta and PTR).

``-p`` is a global option. You can prefix any *instawow* command with ``-p``.
For instance, to update your Classic add-ons, you would run::

    instawow -p classic update

You can omit ``-p`` for the default profile if one exists.

Migrating Classic profiles
^^^^^^^^^^^^^^^^^^^^^^^^^^

With the exception of "Classic Era" profiles
(``vanilla_classic`` in *instawow* parlance), classic profiles will start
receiving updates for the latest Classic release once it is supported by
*instawow*.  No user intervention is necessary, save for updating *instawow*.

WeakAura updater
~~~~~~~~~~~~~~~~

*instawow* contains a WeakAura updater modelled after
`WeakAuras Companion <https://weakauras.wtf/>`__.  To use the updater
and provided that you have WeakAuras installed::

    instawow plugins weakauras-companion build
    instawow install instawow:weakauras-companion

You will have to rebuild the companion add-on prior to updating
to receive aura updates.  If you would like to check for updates on
every invocation of ``instawow update``, install the
``instawow:weakauras-companion-autoupdate`` variant::

    instawow install instawow:weakauras-companion-autoupdate
    instawow update

Plug-ins
~~~~~~~~

*instawow* can be extended using plug-ins.  Plug-ins can be used to add support
for arbitrary hosts and add new commands to the CLI.  You will find a sample
plug-in in ``tests/plugin``.

Metadata sourcing
-----------------

CurseForge
~~~~~~~~~~

CurseForge is set to retire its unauthenticated add-on API by the end of Q1 2022.
CurseForge will be issuing keys for the new API conditionally and which
add-on managers are obligated to conceal.
The new API is therefore unworkable for add-on managers except through a
proxy service, which the author of this particular add-on manager cannot afford.
At the same time, CurseForge will be providing the option for authors to unlist
their add-ons from the new API, and downloads intitiated through the new API
will not count towards author credits for the ad revenue sharing programme.

GitHub
~~~~~~

*instawow* supports WoW add-ons *released* on GitHub – that is to say that
the repository must have a release (tags won't work) and the release must
have an add-on ZIP file attached to it as an asset.
*instawow* will not install or build add-ons directly from
source, or from tarballs or 'zipballs', and will not validate
the contents of the ZIP file.

Transparency
------------

Web requests initiated by *instawow* can be identified by its user agent string.

Every 24 hours, on launch, *instawow* will query `PyPI <https://pypi.org>`__ –
the canonical Python package index – to check for *instawow* updates.

Contributing
------------

Bug reports and fixes are welcome.  Do open an issue before committing to
making any significant changes.

Related work
------------

The author of `strongbox <https://github.com/ogri-la/strongbox>`__ has been
cataloguing similar software.  If you are unhappy
with *instawow*, you might find one of these
`other <https://ogri-la.github.io/wow-addon-managers/>`__ add-on managers more
to your liking.
