tephpy.plotting.logo
====================

.. py:module:: tephpy.plotting.logo

.. autoapi-nested-parse::

   Place the tephpy logo on a figure or an axes.

   The masters under ``_static`` are byte-identical copies of the published brand
   bundle (logo spec §3.2), kept that way by a drift guard in
   ``tests/plotting/test_logo.py``. Sizing is a height in inches and is
   dpi-independent (logo spec §3.3); placement follows the ``legend`` vocabulary
   (logo spec §3.4).

   ..
       !! processed by numpydoc !!


Functions
---------

.. autoapisummary::

   tephpy.plotting.logo.add_logo


Module Contents
---------------

.. py:function:: add_logo(target: matplotlib.figure.Figure | matplotlib.axes.Axes | None = None, *, form: str = 'lockup', size: str | float = 'small', theme: str = 'auto', loc: str | tuple[float, float] = 'lower left', pad: float | None = None, zorder: float | None = None, **kwargs: Any) -> matplotlib.offsetbox.AnnotationBbox

   
   Draw the tephpy logo on a figure or an axes.

   The logo is an :class:`matplotlib.offsetbox.AnnotationBbox` anchored in the
   target's own fraction coordinates, so a figure target places it against the
   figure edges and an axes target against the axes edges, exactly as
   :meth:`matplotlib.axes.Axes.legend` does (logo spec §3.4). Its rendered
   height is the number of inches asked for whatever the figure dpi
   (logo spec §3.3).

   :Parameters:

       **target** : :obj:`matplotlib.figure.Figure` or :obj:`matplotlib.axes.Axes`, optional
           What to brand, and what the position is relative to. ``None`` takes the
           current figure.

       **form** : :class:`python:str`, optional
           Which mark to draw: ``"lockup"``, ``"stacked"`` or ``"icon"``.

       **size** : :class:`python:str` or :class:`python:float`, optional
           A preset, ``"small"`` or ``"large"``, or an explicit height in inches.

       **theme** : :class:`python:str`, optional
           Which variant to draw: ``"auto"``, ``"light"`` or ``"dark"``. The name is
           the *background* the logo is drawn on, so ``"dark"`` is the variant for a
           dark background. ``"auto"`` reads the target's facecolor.

       **loc** : :class:`python:str` or :class:`python:tuple` of :class:`python:float`, optional
           A :meth:`matplotlib.axes.Axes.legend` placement string, or an
           ``(x, y)`` pair in the target's fraction coordinates giving the
           logo's lower-left corner.

       **pad** : :class:`python:float`, optional
           Points between the logo and the target's edge. ``None`` takes
           ``LOGO_PAD``. Ignored when `loc` is a pair, but still validated:
           ``add_logo(ax, loc=(0.5, 0.5), pad=float("nan"))`` raises.

       **zorder** : :class:`python:float`, optional
           Draw order. ``None`` takes ``LOGO_ZORDER``, which is above lines, text
           and legends.

       **\*\*kwargs** : :obj:`Any`
           Passed through to :class:`matplotlib.offsetbox.OffsetImage`: ``alpha``,
           ``filternorm``, ``filterrad``, ``interpolation`` and ``resample``.



   :Returns:

       :obj:`matplotlib.offsetbox.AnnotationBbox`
           The artist, already added to the target, for restyling or removal.




   :Raises:

       :obj:`TypeError`
           If `target` is neither a figure nor an axes, if `loc` is neither a
           placement string nor a pair of floats, if `pad` or `zorder` is not a
           real number (e.g., a list), or if a keyword is not a
           :class:`matplotlib.offsetbox.OffsetImage` option.

       :obj:`ValueError`
           If `form`, `size`, `theme` or `loc` names something that does not
           exist, if `size` is not a positive finite height, if a `loc` pair
           holds a non-finite coordinate, if `pad` or `zorder` is a string, or
           if `pad` or `zorder` is not finite.







   ..
       !! processed by numpydoc !!