*******************************************************************************
Python interface
*******************************************************************************

:mod:`emblematic` has a Python interface that can be called from other Python scripts to programmatically generate emblems.

============
Installation
============

:mod:`emblematic` is distributed both via `PyPI`_ and `Steffo's Forge`_.

Use your favorite package manager to install it in your project.

For example, with `Poetry`_ via `PyPI`_:

.. code-block:: console

    $ poetry add emblematic

Or, with `pip`_ via `Steffo's Forge`_:

    $ pip install --index-url 'https://forge.steffo.eu/api/packages/steffo/pypi/simple/' emblematic

.. _PyPI: https://pypi.org/project/emblematic/
.. _Steffo's Forge: https://forge.steffo.eu/steffo/-/packages/pypi/emblematic/
.. _Poetry: https://python-poetry.org/
.. _pip: https://pip.pypa.io/en/stable/

=====
Usage
=====

-----------
Composition
-----------

This package should usually be imported as :mod:`emblematic.composition`:

.. code-block:: python

    from emblematic.composition import compose_basic, compose_solid, compose_shadow, compose_duotone

Each of the ``compose_*`` functions correspond to a mode of the :ref:`cli`, except that they take as input instances of :class:`bs4.BeautifulSoup` to operate on.

A very basic usage example is:

.. code-block:: python

    from bs4 import BeautifulSoup
    from emblematic.composition import compose_basic

    with open("background.svg", encoding="utf-8") as bg_file:
        with open("foreground.svg", encoding="utf-8") as fg_file:
            bg_soup = BeautifulSoup(bg_file, features="lxml-xml")
            fg_soup = BeautifulSoup(fg_file, features="lxml-xml")

    final_soup = compose_basic(
        background=bg_soup,
        foreground=fg_soup,
        final_width_px=512.0,
        final_height_px=512.0,
    )

    final_pretty = final_soup.prettify()

    with open("final.svg", encoding="utf-8") as final_file:
        final_file.write(final_pretty)

-----------------
Converting to PNG
-----------------

If you want to additionally convert to PNG with `Inkscape`_, like the :ref:`cli` does, and assuming you have properly installed the :ref:`prerequisites`, you can use :mod:`subprocess` similarly to this:

.. code-block:: python

    import subprocess

    ...

    destination = "final.png"
    width_px = int(512.0)
    height_px = int(512.0)

    result = subprocess.run(
        args=[
            "inkscape",
            "--pipe",
            "--export-type=png",
            f"--export-filename={destination}",
            f"--export-width={width_px}",
            f"--export-height={height_px}"
        ],
        input=svg_data.encode("utf-8"),
    )
    if result.returncode != 0:
        raise ChildProcessError("Conversion to PNG with Inkscape returned non-zero exit code: ", result.returncode)

.. _Inkscape: https://inkscape.org/

=============
API reference
=============

------------------
Emblem composition
------------------

.. automodule:: emblematic.composition

----------------
SVG modification
----------------

.. automodule:: emblematic.svg

---------------------------------
Command-line interface definition
---------------------------------

.. automodule:: emblematic.cli

Arguments and options
^^^^^^^^^^^^^^^^^^^^^

.. automodule:: emblematic.cli.argopts

Commands
^^^^^^^^

.. automodule:: emblematic.cli.commands

File detection
^^^^^^^^^^^^^^

.. automodule:: emblematic.cli.files