recard 0.2.0__tar.gz

recard-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HATheekshana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

recard-0.2.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: recard
+Version: 0.2.0
+Summary: Async Genshin Impact character card generator (Enka.Network showcase -> image), styled after zenka for ZZZ.
+Author: HATheekshana
+License: MIT
+Project-URL: Homepage, https://github.com/HATheekshana/recard
+Keywords: genshin,genshin-impact,enka,card,zenka
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4,>=3.12
+Requires-Dist: Pillow>=10.0
+Requires-Dist: enka<3,>=2.5.20
+Provides-Extra: fast-dns
+Requires-Dist: aiodns>=3.2.0; extra == "fast-dns"
+Requires-Dist: pycares<4.4.0; extra == "fast-dns"
+Dynamic: license-file
+
+# recard
+
+Async Genshin Impact character card generator, built the same way you'd use
+[`zenka`](https://pypi.org/project/zenka/) for Zenless Zone Zero: give it a
+UID, get back rendered card images.
+
+```bash
+pip install ./recard   # local build, see "Installing" below
+```
+
+```python
+import asyncio
+import recard
+
+async def main():
+    async with recard.Client() as client:
+        # list everything currently in the player's public showcase
+        showcase = await client.get_api(700000000)
+        for char in showcase:
+            print(char.id, char.name, char.element)
+
+        # render one character by name
+        result = await client.card(700000000, "Hu Tao")
+        for card in result.cards:
+            card.card.save(f"{card.name}.png")   # card.card is a PIL.Image
+
+        # ...or by exact avatar ID, same call shape
+        result = await client.card(700000000, 10000046)
+
+        # or render the whole showcase at once
+        result = await client.card(700000000)
+        for card in result.cards:
+            card.card.save(f"{card.name}.png")
+
+asyncio.run(main())
+```
+
+## How it works / limitations
+
+- Uses [enka-py](https://github.com/seriaati/enka-py), installed automatically
+  as the `enka` dependency. Public `Client.get_api()` and `Client.card()`
+  calls keep the same interface and return types.
+- Only characters available in the player's public Enka showcase can be
+  rendered. No HoYoLAB login or cookie fallback is included.
+- Character names, artwork, namecards, talents, constellations, weapons,
+  and artifacts come from enka-py's enriched models. The four bundled
+  metadata JSON files are no longer needed or shipped.
+- enka-py downloads its metadata on first use into `.enka_py/assets`
+  under the process working directory, which must be writable. First use
+  needs an internet connection. Refresh assets after game patches:
+
+  ```python
+  async with recard.Client() as client:
+      await client.update_assets()
+  ```
+
+  The command `python -m recard.data.update_data` also performs this refresh.
+  Updates depend on the upstream asset sources supporting the new characters.
+- Network and parsing errors now propagate instead of appearing as an empty
+  showcase. An empty public showcase still returns an empty list; requesting
+  a missing character raises `recard.CharacterNotFound`.
+- Custom splash art is read from
+  `~/.recard/custom_splash/<char_id>.(png|jpg|jpeg|webp)`.
+- Internal JSON-path constructor options and placeholder HoYoLAB hooks were
+  removed. Integrations using those internals should use the public Client.
+
+## Installing
+
+This isn't published to PyPI yet. Until then:
+
+```bash
+pip install ./recard
+# or, for local editing:
+pip install -e ./recard
+```
+
+Once published:
+
+```bash
+pip install recard
+```
+
+## License
+
+The code in this repository is MIT-licensed - see `LICENSE`.
+
+**Note on bundled assets:** `recard/assets/` ships
+fonts, icons, and character art from Genshin Impact,
+© COGNOSPHERE PTE. LTD. / HoYoverse. These are included for card
+rendering purposes only, are not covered by this project's MIT license,
+and all rights to them remain with their original owner. This project
+is an unofficial fan tool and is not affiliated with or endorsed by
+HoYoverse.
+
+The enka-py dependency has its own GPL-3.0 license; see its repository for details.

recard-0.2.0/README.md

@@ -0,0 +1,95 @@
+# recard
+
+Async Genshin Impact character card generator, built the same way you'd use
+[`zenka`](https://pypi.org/project/zenka/) for Zenless Zone Zero: give it a
+UID, get back rendered card images.
+
+```bash
+pip install ./recard   # local build, see "Installing" below
+```
+
+```python
+import asyncio
+import recard
+
+async def main():
+    async with recard.Client() as client:
+        # list everything currently in the player's public showcase
+        showcase = await client.get_api(700000000)
+        for char in showcase:
+            print(char.id, char.name, char.element)
+
+        # render one character by name
+        result = await client.card(700000000, "Hu Tao")
+        for card in result.cards:
+            card.card.save(f"{card.name}.png")   # card.card is a PIL.Image
+
+        # ...or by exact avatar ID, same call shape
+        result = await client.card(700000000, 10000046)
+
+        # or render the whole showcase at once
+        result = await client.card(700000000)
+        for card in result.cards:
+            card.card.save(f"{card.name}.png")
+
+asyncio.run(main())
+```
+
+## How it works / limitations
+
+- Uses [enka-py](https://github.com/seriaati/enka-py), installed automatically
+  as the `enka` dependency. Public `Client.get_api()` and `Client.card()`
+  calls keep the same interface and return types.
+- Only characters available in the player's public Enka showcase can be
+  rendered. No HoYoLAB login or cookie fallback is included.
+- Character names, artwork, namecards, talents, constellations, weapons,
+  and artifacts come from enka-py's enriched models. The four bundled
+  metadata JSON files are no longer needed or shipped.
+- enka-py downloads its metadata on first use into `.enka_py/assets`
+  under the process working directory, which must be writable. First use
+  needs an internet connection. Refresh assets after game patches:
+
+  ```python
+  async with recard.Client() as client:
+      await client.update_assets()
+  ```
+
+  The command `python -m recard.data.update_data` also performs this refresh.
+  Updates depend on the upstream asset sources supporting the new characters.
+- Network and parsing errors now propagate instead of appearing as an empty
+  showcase. An empty public showcase still returns an empty list; requesting
+  a missing character raises `recard.CharacterNotFound`.
+- Custom splash art is read from
+  `~/.recard/custom_splash/<char_id>.(png|jpg|jpeg|webp)`.
+- Internal JSON-path constructor options and placeholder HoYoLAB hooks were
+  removed. Integrations using those internals should use the public Client.
+
+## Installing
+
+This isn't published to PyPI yet. Until then:
+
+```bash
+pip install ./recard
+# or, for local editing:
+pip install -e ./recard
+```
+
+Once published:
+
+```bash
+pip install recard
+```
+
+## License
+
+The code in this repository is MIT-licensed - see `LICENSE`.
+
+**Note on bundled assets:** `recard/assets/` ships
+fonts, icons, and character art from Genshin Impact,
+© COGNOSPHERE PTE. LTD. / HoYoverse. These are included for card
+rendering purposes only, are not covered by this project's MIT license,
+and all rights to them remain with their original owner. This project
+is an unofficial fan tool and is not affiliated with or endorsed by
+HoYoverse.
+
+The enka-py dependency has its own GPL-3.0 license; see its repository for details.

recard-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "recard"
+version = "0.2.0"
+description = "Async Genshin Impact character card generator (Enka.Network showcase -> image), styled after zenka for ZZZ."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "HATheekshana" }]
+keywords = ["genshin", "genshin-impact", "enka", "card", "zenka"]
+dependencies = [
+    "aiohttp>=3.12,<4",
+    "Pillow>=10.0",
+    "enka>=2.5.20,<3",
+]
+
+[project.optional-dependencies]
+# Faster/more reliable DNS resolution - genuinely optional: net.py already
+# falls back to aiohttp's default resolver when this isn't installed.
+# Needs a C compiler on some platforms (notably Windows without MSVC Build
+# Tools), so it's kept out of the required dependency list.
+fast-dns = [
+    "aiodns>=3.2.0",
+    "pycares<4.4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/HATheekshana/recard"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["recard*"]
+
+[tool.setuptools.package-data]
+recard = [
+    "assets/**/*",
+]

recard-0.2.0/recard/__init__.py

@@ -0,0 +1,29 @@
+"""
+recard - Genshin Impact character card generator.
+
+Same usage pattern as zenka (the ZZZ card library):
+
+    import asyncio
+    import recard
+
+    async def main():
+        async with recard.Client() as client:
+            result = await client.card(700000000, character="Hu Tao")
+            for card in result.cards:
+                card.card.save(f"{card.name}.png")
+
+    asyncio.run(main())
+"""
+
+from .client import Card, CardResult, CharacterNotFound, Client, ShowcaseCharacter
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Client",
+    "ShowcaseCharacter",
+    "Card",
+    "CardResult",
+    "CharacterNotFound",
+    "__version__",
+]

recard-0.2.0/recard/cards/artifacts.py

@@ -0,0 +1,170 @@
+import asyncio
+import logging
+from io import BytesIO
+from PIL import Image, ImageDraw, ImageFont
+
+from pathlib import Path as _Path
+_PKG_ROOT = _Path(__file__).resolve().parent.parent
+
+logger = logging.getLogger("recard")
+
+# Stat Mapping for icons (Local files)
+STAT_MAP = {
+    "FIGHT_PROP_HP": "hp", "FIGHT_PROP_HP_PERCENT": "hp",
+    "FIGHT_PROP_ATTACK": "atk", "FIGHT_PROP_ATTACK_PERCENT": "atk",
+    "FIGHT_PROP_DEFENSE": "def", "FIGHT_PROP_DEFENSE_PERCENT": "def",
+    "FIGHT_PROP_ELEMENT_MASTERY": "em", "FIGHT_PROP_CHARGE_EFFICIENCY": "er",
+    "FIGHT_PROP_CRITICAL": "cr", "FIGHT_PROP_CRITICAL_HURT": "cd",
+    "FIGHT_PROP_FIRE_ADD_HURT": "pyro", "FIGHT_PROP_WATER_ADD_HURT": "hydro",
+    "FIGHT_PROP_GRASS_ADD_HURT": "dendro", "FIGHT_PROP_ELEC_ADD_HURT": "electro",
+    "FIGHT_PROP_ICE_ADD_HURT": "cryo", "FIGHT_PROP_WIND_ADD_HURT": "anemo",
+    "FIGHT_PROP_ROCK_ADD_HURT": "geo", "FIGHT_PROP_PHYSICAL_ADD_HURT": "phys"
+}
+
+# Flower, Feather, Sands, Goblet, Circlet
+EQUIP_ORDER = ["EQUIP_BRACER", "EQUIP_NECKLACE", "EQUIP_SHOES", "EQUIP_RING", "EQUIP_DRESS"]
+
+
+def _compute_cv(main_data, sub_stats):
+    """CV (crit value) = CR% * 2 + CD%, summed across the main stat (only
+    relevant for circlets, whose main stat can itself be CR or CD) and all
+    substats. Both crit stats stack additively across an artifact, so this
+    is just a running total, not an average."""
+    cr = 0.0
+    cd = 0.0
+
+    main_prop = main_data.get("mainPropId")
+    if main_prop == "FIGHT_PROP_CRITICAL":
+        cr += main_data.get("statValue", 0) or 0
+    elif main_prop == "FIGHT_PROP_CRITICAL_HURT":
+        cd += main_data.get("statValue", 0) or 0
+
+    for stat in sub_stats:
+        prop_id = stat.get("appendPropId")
+        if prop_id == "FIGHT_PROP_CRITICAL":
+            cr += stat.get("statValue", 0) or 0
+        elif prop_id == "FIGHT_PROP_CRITICAL_HURT":
+            cd += stat.get("statValue", 0) or 0
+
+    return cr * 2 + cd
+
+
+async def draw_artifact_card(session, base_image, x, y, art_data, font):
+    draw = ImageDraw.Draw(base_image)
+    CARD_W, CARD_H = 330, 200 
+    ICONS_PATH = f"{_PKG_ROOT}/assets/icons/"
+    STARS_PATH = f"{_PKG_ROOT}/assets/icons/stars/" 
+    
+    # 1. Background Card - Using a slightly more transparent fill for that glassmorphism look
+    draw.rounded_rectangle([x, y, x + CARD_W, y + CARD_H], radius=12, fill=(0, 0, 0, 80), outline=(255, 255, 255, 40))
+
+    flat = art_data.get("flat", {})
+    relic_core = art_data.get("reliquary", {})
+    main_data = flat.get("reliquaryMainstat", {})
+    sub_stats = flat.get("reliquarySubstats", [])
+
+    # 2. Artifact Piece Icon (The Gear piece)
+    icon_name = flat.get("icon")
+    # Live HoYoLAB data (character/detail fallback) gives a full,
+    # directly-fetchable CDN URL - it's hash-named, so it can't be
+    # reconstructed as an enka.network/ui/... path the way Enka's own
+    # semantic icon names can.
+    icon_url = flat.get("icon_url") or (f"https://enka.network/ui/{icon_name}.png" if icon_name else None)
+    if icon_url:
+        url = icon_url
+        async with session.get(url) as response:
+            if response.status == 200:
+                img_data = await response.read()
+                art_img = Image.open(BytesIO(img_data)).convert("RGBA").resize((140, 140), Image.Resampling.LANCZOS)
+                # Icon background
+                base_image.paste(art_img, (x + 15, y + 30), art_img)
+
+    # 4. Rarity Stars (NEW)
+    rarity = flat.get("rankLevel", 5)
+    try:
+        # 1. Open and convert
+        star_img = Image.open(f"{STARS_PATH}Star{rarity}.png").convert("RGBA")
+        
+        # 2. Resize directly to the target size (Re-assigning the variable!)
+        star_img = star_img.resize((98, 28), Image.Resampling.LANCZOS)
+        
+        # 3. Paste
+        base_image.paste(star_img, (x + 30, y + 140), star_img)
+    except Exception as e:
+        logger.warning("Error loading star image Star%s.png: %s", rarity, e)
+    # 3. Main Stat Icon - PASTE THIS LAST so it's on top
+    main_prop = main_data.get("mainPropId")
+    if main_prop:
+        icon_key = STAT_MAP.get(main_prop, "atk").lower()
+        try:
+            # We move the main stat icon to the top right of the gear box
+            m_icon = Image.open(f"{ICONS_PATH}{icon_key}.png").convert("RGBA").resize((28, 28))
+            base_image.paste(m_icon, (x + 10, y + 10), m_icon)
+        except Exception:
+            pass
+
+    # 4. Sub-Stat Grid
+    grid_x = x + 150
+    for i, stat in enumerate(sub_stats[:4]):
+        col, row = i % 1, i // 1
+        bx = grid_x + (col * 135)
+        by = y + 15 + (row * 45)
+        
+        # Substat box
+        draw.rounded_rectangle([bx, by, bx + 170, by + 38], radius=10, fill=(20, 20, 30, 150))
+        
+        prop_id = stat.get("appendPropId")
+        icon_file = STAT_MAP.get(prop_id, "atk").lower()
+        try:
+            s_icon = Image.open(f"{ICONS_PATH}{icon_file}.png").convert("RGBA").resize((22, 22))
+            base_image.paste(s_icon, (bx + 8, by + 8), s_icon)
+        except Exception:
+            pass
+        
+        val = stat.get("statValue")
+        is_percent = any(k in prop_id for k in ["PERCENT", "CRITICAL", "EFFICIENCY", "HURT"])
+        val_str = f"+{val}%" if is_percent else f"+{val}"
+        draw.text((bx + 55, by + 19), val_str, font=font, fill=(255, 255, 255), anchor="lm")
+
+    # 5. Main Stat Value - bottom left of the card (where the level used to sit).
+    if main_prop:
+        main_val = main_data.get("statValue")
+        is_percent = any(k in main_prop for k in ["PERCENT", "CRITICAL", "EFFICIENCY", "HURT"])
+        main_val_str = f"{main_val}%" if is_percent else f"{int(main_val)}"
+        draw.text((x + 5, y + CARD_H - 15), main_val_str, font=font, fill=(255, 255, 255), anchor="lm", stroke_width=1, stroke_fill=(0, 0, 0))
+
+    # 6. Enhancement level - bottom right of the card.
+    raw_level = relic_core.get("level", 1)
+    display_level = f"+{raw_level - 1}"
+    draw.text((x + CARD_W - 185, y + CARD_H - 15), display_level, font=font, fill=(255, 204, 0), stroke_width=1, stroke_fill=(0, 0, 0), anchor="rm")
+
+    # 7. CV (crit value) score - top right of the card. Drawn last, on top
+    # of everything else (icon/stars/grid), so it's never painted over.
+    cv_score = _compute_cv(main_data, sub_stats)
+    cv_text = f"CV{cv_score:.1f}"
+    draw.text((x + CARD_W - 185, y + 25), cv_text, font=font, fill=(255, 255, 255), stroke_width=1, stroke_fill=(0, 0, 0), anchor="rm")
+
+async def draw_horizontal_artifacts(session, background, char_data, start_x, start_y, font):
+    """
+    Finds all artifacts for a single character and draws them in a 
+    horizontal row (Flower -> Feather -> Sands -> Goblet -> Circlet).
+    """
+    # Filter only relics (artifacts)
+    relics = [e for e in char_data.get("equipList", []) if "reliquary" in e]
+    
+    # Sort by EQUIP_ORDER
+    sorted_relics = sorted(
+        relics, 
+        key=lambda x: EQUIP_ORDER.index(x.get("flat", {}).get("equipType", "")) 
+        if x.get("flat", {}).get("equipType") in EQUIP_ORDER else 99
+    )
+
+    tasks = []
+    spacing_x = 345
+
+    for i, art in enumerate(sorted_relics[:5]):
+        curr_x = start_x + (i * spacing_x)
+        tasks.append(draw_artifact_card(session, background, curr_x, start_y, art, font))
+    
+    if tasks:
+        await asyncio.gather(*tasks)