Metadata-Version: 2.4
Name: pyguitarpro
Version: 0.10
Summary: Read, write, and manipulate GP3, GP4 and GP5 files.
Author: Sviatoslav Abakumov
Author-email: Sviatoslav Abakumov <dust.harvesting@gmail.com>
License-Expression: LGPL-3.0-only
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Artistic Software
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Dist: attrs>=19.2
Requires-Python: >=3.9
Project-URL: Documentation, https://pyguitarpro.readthedocs.io/
Project-URL: Issue tracker, https://github.com/Perlence/PyGuitarPro/issues
Project-URL: Source code, https://github.com/Perlence/PyGuitarPro
Description-Content-Type: text/x-rst

PyGuitarPro
===========

.. image:: https://img.shields.io/pypi/v/pyguitarpro.svg?style=flat
   :alt: PyPI Package latest release
   :target: https://pypi.org/project/PyGuitarPro/


Introduction
------------

PyGuitarPro is a package to read, write and manipulate GP3, GP4 and GP5 files. Initially PyGuitarPro is a Python port
of `AlphaTab <https://www.alphatab.net/>`_ which originally was a Haxe port of
`TuxGuitar <https://sourceforge.net/projects/tuxguitar/>`_.

This package helps you achieve several goals you might find yourself yearning to do in a day-to-day tabber life:

- Transpose a track without messing the fingering
- Add the first string to the track without messing the fingering
- Map percussion notes to different values

Reading ``.gp*`` files is as easy as:

.. code-block:: python

   import guitarpro
   curl = guitarpro.parse('Mastodon - Curl of the Burl.gp5')

Writing ``.gp*`` files isn't that hard either:

.. code-block:: python

   guitarpro.write(curl, 'Mastodon - Curl of the Burl 2.gp5')

All objects representing GP entities are hashable and comparable. This gives a great opportunity to apply the *diff*
algorithm to tabs, or even the *diff3* algorithm to merge tablatures.

For those looking to create the best guitar tablature editor in Python, this package is a good place to start.

Examples
--------

Several usage examples are included in the ``/examples`` folder. Feel free to add your own examples or improve existing
ones. Then, submit them via pull request.

To run one of the examples in your local environment, simply:

.. code-block:: sh

   cd PyGuitarPro
   uv run examples/transpose.py --help


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

Install PyGuitarPro from PyPI:

.. code-block:: sh

   pip install PyGuitarPro


Documentation
-------------

Package documentation is located at `Read the Docs <https://pyguitarpro.readthedocs.io/>`_.


Development
-----------

Install the development version of PyGuitarPro with `uv <https://docs.astral.sh/uv/>`_:

.. code-block:: sh

   git clone https://github.com/Perlence/PyGuitarPro.git
   cd PyGuitarPro
   uv sync

Run the tests:

.. code-block:: sh

   uv run pytest

Install the `pre-commit hook <https://adamj.eu/tech/2025/05/07/pre-commit-install-uv/>`_:

.. code-block:: sh

   uv run pre-commit install


Licensing
---------

Please see the file called ``LICENSE``.

.. vim: tw=120 cc=121
