# Copyright Kevin Deldycke <[email protected]> and contributors.
#
# This program is Free Software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
"""Terminal rendition of the mpm brand mark, and the `--version` screen it decorates.
The mark is the isometric open box of `docs/assets/logo-square.svg`, redrawn as a
half-block raster: two sub-pixel rows share one terminal line, so {data}`LOGO` paints
as half as many lines as it has rows.
Half-blocks are the primitive because a terminal cell is twice as tall as it is
wide, which makes their sub-pixels square. That also rules out the alternative
worth naming, since it looks obvious and is not: drawing the mark as directional
line-art characters (`╱`, `╲`, `│`), the way edge-detection ASCII art does. An
isometric edge sits at slope `0.25` in cell space, far too shallow for `╱`, and
that figure is scale-invariant: no height fixes it. Stretching the projection to
45° earns the diagonals but leaves the mark only ~12 columns wide, too few for
the four flaps.
click-extra's {class}`~click_extra.version.VersionScreen` lays the mark out beside
the facts of {func}`facts`, and draws it only when the terminal allows it.
```{caution}
The mark's structure is carried by *color* alone: strip the ANSI codes and it
collapses into one solid silhouette. click-extra therefore only draws the screen
when color reaches the output, falling back to its plain rendering everywhere else.
That plain form is also the one machine readers parse, the bar plugin probing
`mpm --no-color --version`.
```
"""
from __future__ import annotations
from click_extra import VersionScreen, default_facts, style
from . import (
__build_os__,
__build_target__,
__build_target_arch__,
__build_time__,
)
from .pool import pool
DOCS_URL = "https://mpm.run"
"""Canonical documentation host, advertised on the version screen."""
TAGLINE = "Meta Package Manager"
"""What the `mpm` acronym stands for, as spelled out under the logo's wordmark."""
LOGO: tuple[str, ...] = (
" .. .. ",
" ..... ..... ",
" ......::++...... ",
" ......::::++++...... ",
" ....::::....++++.... ",
" .:::::++::+++++. ",
" ...::::++::++++... ",
" ......:::+:+++...... ",
" ......:::+++...... ",
" +......:+......: ",
" +++....+:....::: ",
" ++++++++:::::::: ",
" ++++++++:::::::: ",
" ++++++++:::::::: ",
" +++++++::::::: ",
" +++++::::: ",
" +++::: ",
" +: ",
)
"""The mark, as one shading tone per sub-pixel, two rows to a rendered line.
A space is transparent and leaves the terminal's own background alone. The rest name
the plane the sub-pixel faces, which is what an isometric solid shades by: `.` up
(the flap tops and the cube's lid), `:` right, `+` left. No outlines: the solid is
reconstructed from the three shades its planes catch, the way an unlit render reads.
Rasterized from a model re-derived from the SVG's polygon geometry, with the rim,
flap fold depth, body height and cube placement all measured off it, then mirrored
about its vertical axis, swapping `+` for `:` since what faces left on one side
faces right on the other. Symmetry is imposed at that point rather than left to the
rasterizer, which drifted three separate ways: a column count rounded off the row
scale left the sampling grid off-centre, paint order tilted mirror-paired surfaces,
and an odd column count gave the axis a column that would have had to face both
ways at once.
The box is open, so the two far walls show through its rim, and they carry the
plane *opposite* the one they sit behind: the far-left wall is lit as a right-facing
face, which is why the interior's left half is `:` where the exterior's is `+`. That
mirroring is what keeps the floating cube legible against the wall behind it, each
of its faces landing on the other tone. The interior cells were filled by testing
every empty cell's centre against the rim quadrilateral in the artwork's own
coordinates, so they cannot drift from the SVG the way an eyeballed fill would.
Hand-editing a row is fine, but keep the rows equal in length and even in number,
keep the width even, and keep every row symmetric.
"""
BRAND_WASH = "#d3d3f6"
"""The pale lavender of the artwork's lit planes.
One of the two colors the whole identity is drawn from, with {data}`BRAND_INK`.
Declared here as well as in `docs/brand_update.py` because runtime code cannot
read the SVG sources, which are not shipped in the wheel;
`test_ansi_logo_tracks_the_brand_palette` fails if the two ever disagree.
"""
BRAND_INK = "#2d2364"
"""The deep purple of the artwork's shadowed planes, and of its lettering.
The second of the two brand colors, with {data}`BRAND_WASH`.
"""
BRAND_MID = "#807bad"
"""The midpoint of the two, for the third plane an isometric solid needs.
Computed rather than chosen, so the palette remains two colors and a derivation.
With no outline separating the faces, a right-facing plane cannot share a value
with a left-facing one.
"""
TONES: dict[str, int] = {
".": 189, # `#d7d7ff`, the palette's nearest to BRAND_WASH.
":": 103, # `#8787af`, its nearest to BRAND_MID.
"+": 17, # `#00005f`, its nearest chromatic entry to BRAND_INK.
}
"""Xterm-256 palette index per shading tone of {data}`LOGO`.
One index per plane, mapped to the closest thing the palette can render: the lit
faces take {data}`BRAND_WASH`, the shadowed ones {data}`BRAND_INK`, and the
right-hand planes {data}`BRAND_MID`.
Indices rather than truecolor: the 256-color cube is the widest-supported palette,
and click emits no downgrade of its own for a terminal that cannot do 24-bit,
Apple's own Terminal included, where a 24-bit sequence would take the mark with
it. The cost is borne entirely by the ink: the cube resolves dark colors coarsely,
so `#00005f` is as close as it gets (a perceptual distance of ~24, against ~3 for
the wash). It is the nearest entry that keeps any chroma at all, the closer ones
by raw distance all being grays, which would paint a purple mark in ash.
"""
LOGO_WIDTH = len(LOGO[0])
"""Columns the mark occupies, every rendered line being padded to it."""
LOGO_LINES = len(LOGO) // 2
"""Terminal lines the mark renders to, two sub-pixel rows making one."""
_UPPER = "▀"
_LOWER = "▄"
_FULL = "█"
Colors = tuple[int | None, int | None]
"""A cell's foreground and background palette indices.
`None` is transparent, leaving the terminal's own color to show through.
"""
[docs]
def build_rows() -> tuple[tuple[str, str], ...]:
"""When and for what target this executable was compiled, or nothing at all.
Reads the placeholders `click-extra prebake all` fills in the release workflow.
They carry nothing outside a compiled binary, and the rows are dropped there: on
a source install the interpreter and the platform already rowed above *are* the
build, so repeating them says nothing new.
The target names the floor the binary was compiled for (`macosx-11.0-arm64`),
where the `Platform` row names the machine running it now. Those answer
different questions in a bug report, which is what earns the second row.
Two rows rather than one sentence, because the version screen sizes the whole
layout against its widest line and falls back to the plain message when that
overflows the terminal. Joined up, this metadata is wide enough to cost a binary
its version screen on an 80-column terminal; stacked, it costs no width at all.
"""
if not __build_time__:
return ()
target = __build_target__ or " ".join(
part for part in (__build_os__, __build_target_arch__) if part
)
return (("Built", __build_time__), *((("Target", target),) if target else ()))
[docs]
def render_logo() -> tuple[str, ...]:
"""Paint {data}`LOGO` into styled lines, one per pair of sub-pixel rows.
A cell whose two sub-pixels carry different tones paints the top one as
foreground over the bottom one as background, which is what fits two independent
colors on one line. Runs of cells sharing a color pair are styled together rather
than one escape sequence per character, keeping the mark from tripling in size.
"""
lines = []
for row in range(0, len(LOGO), 2):
line = ""
run = ""
colors: Colors = (None, None)
for over, under in zip(LOGO[row], LOGO[row + 1]):
pair: Colors
if over == " " and under == " ":
char, pair = " ", (None, None)
elif under == " ":
char, pair = _UPPER, (TONES[over], None)
elif over == " ":
char, pair = _LOWER, (TONES[under], None)
elif over == under:
char, pair = _FULL, (TONES[over], None)
else:
char, pair = _UPPER, (TONES[over], TONES[under])
if pair != colors:
line += _paint(run, colors)
run, colors = "", pair
run += char
lines.append(line + _paint(run, colors))
return tuple(lines)
def _paint(run: str, colors: Colors) -> str:
"""Style a run of cells, leaving fully transparent ones as bare spaces.
Transparent runs must not go through `style()`: it would wrap them in a reset
sequence, which costs bytes and, worse, cancels nothing while looking like it
might.
"""
if not run or colors == (None, None):
return run
return style(run, fg=colors[0], bg=colors[1])
[docs]
def facts() -> dict[str, str]:
"""The rows the version screen draws beside the mark, below the version line.
click-extra's own `Python` and `Platform` rows come first: the two facts its
`env_summary()` joins for the plain message. The build rows of a binary, the
manager count and the documentation host follow.
"""
supported = len(pool.default_manager_ids)
total = len(pool.all_manager_ids)
return (
default_facts()
| dict(build_rows())
| {
"Managers": f"{supported} supported here, {total} total",
"Docs": DOCS_URL,
}
)
VERSION_SCREEN = VersionScreen(logo=render_logo, tagline=TAGLINE, facts=facts)
"""The `--version` screen, which click-extra lays out and measures.
The mark and the facts are both callables, so only a `--version` that draws the
screen pays for them.
"""