flavortui 1.0.0__tar.gz

flavortui-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+# python stuff
+venv/
+__pycache__/
+
+# api cache
+.cache/
+
+# might use this at some point (its for debugging 😱)
+debug.log
+
+# I hate macos
+.DS_Store

flavortui-1.0.0/.pylintrc

@@ -0,0 +1,10 @@
+[MASTER]
+init-hook='import os, sys; sys.path.insert(0, os.getcwd())'
+ignore=venv,.venv,__pycache__
+
+[MESSAGES CONTROL]
+disable=
+    duplicate-code,
+    missing-module-docstring,
+    missing-class-docstring,
+    missing-function-docstring

flavortui-1.0.0/LICENSE.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026-present BookCatKid <99609593+BookCatKid@users.noreply.github.com>
+
+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.

flavortui-1.0.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: flavortui
+Version: 1.0.0
+Summary: Feature-rich terminal UI for Flavortown: devlogs, projects, shop, and more.
+Project-URL: Documentation, https://github.com/BookCatKid/flavortui#readme
+Project-URL: Issues, https://github.com/BookCatKid/flavortui/issues
+Project-URL: Source, https://github.com/BookCatKid/flavortui
+Author-email: BookCatKid <99609593+BookCatKid@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+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 :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: keyring
+Requires-Dist: platformdirs
+Requires-Dist: requests
+Requires-Dist: textual
+Requires-Dist: textual-image[textual]
+Description-Content-Type: text/markdown
+
+# FlavorTUI
+
+[![PyPI - Version](https://img.shields.io/pypi/v/flavortui.svg)](https://pypi.org/project/flavortui)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flavortui.svg)](https://pypi.org/project/flavortui)
+
+FlavorTUI is a feature-rich terminal user interface (TUI) for Flavortown. With FlavorTUI, you can browse and create devlogs, manage your projects, explore the shop, and access other Flavortown features, all from an interactive terminal interface.
+
+It is built using the `textual` library, which provides (imo) a great terminal UI experience. The TUI is of course written in Python 🥰. This is my first time creating a TUI so I hope its good :) Depending on your terminal, the ui might look different. It all depends on how well your terminal supports different things.
+
+Your API key is stored "securely" using the `keyring` library, so you don't have to worry about it being exposed in your terminal history or config files.
+
+Additionaly, your settings are store using the `platformdirs` `user_config_dir` function. Your settings are probobly stored in `~/Library/Application Support/flavortui` on macOS, `C:\Users\<user>\AppData\Local\flavortui` on Windows (`%localappdata%`), and ~/.config/flavortui (or $XDG_CONFIG_HOME) on Linux.
+
+<div>
+  <img src="screenshots/kitchen.png" alt="Kitchen Screenshot" style="width:49%;">
+  <img src="screenshots/with_sidebar.png" alt="Shop Screenshot" style="width:49%;">
+</div>
+
+## Installation
+
+```bash
+pip install flavortui
+```
+
+## Local Development
+
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install -e .
+```
+
+Run with either:
+
+```bash
+flavortui
+```
+
+or:
+
+```bash
+python -m flavortui
+```
+
+## API
+
+Flavortown API docs can be found [here](https://flavortown.hackclub.com/api/v1/docs).
+
+## License
+
+`flavortui` is distributed under the terms of the MIT license.

flavortui-1.0.0/README.md

@@ -0,0 +1,51 @@
+# FlavorTUI
+
+[![PyPI - Version](https://img.shields.io/pypi/v/flavortui.svg)](https://pypi.org/project/flavortui)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flavortui.svg)](https://pypi.org/project/flavortui)
+
+FlavorTUI is a feature-rich terminal user interface (TUI) for Flavortown. With FlavorTUI, you can browse and create devlogs, manage your projects, explore the shop, and access other Flavortown features, all from an interactive terminal interface.
+
+It is built using the `textual` library, which provides (imo) a great terminal UI experience. The TUI is of course written in Python 🥰. This is my first time creating a TUI so I hope its good :) Depending on your terminal, the ui might look different. It all depends on how well your terminal supports different things.
+
+Your API key is stored "securely" using the `keyring` library, so you don't have to worry about it being exposed in your terminal history or config files.
+
+Additionaly, your settings are store using the `platformdirs` `user_config_dir` function. Your settings are probobly stored in `~/Library/Application Support/flavortui` on macOS, `C:\Users\<user>\AppData\Local\flavortui` on Windows (`%localappdata%`), and ~/.config/flavortui (or $XDG_CONFIG_HOME) on Linux.
+
+<div>
+  <img src="screenshots/kitchen.png" alt="Kitchen Screenshot" style="width:49%;">
+  <img src="screenshots/with_sidebar.png" alt="Shop Screenshot" style="width:49%;">
+</div>
+
+## Installation
+
+```bash
+pip install flavortui
+```
+
+## Local Development
+
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install -e .
+```
+
+Run with either:
+
+```bash
+flavortui
+```
+
+or:
+
+```bash
+python -m flavortui
+```
+
+## API
+
+Flavortown API docs can be found [here](https://flavortown.hackclub.com/api/v1/docs).
+
+## License
+
+`flavortui` is distributed under the terms of the MIT license.

flavortui-1.0.0/TODO.md

@@ -0,0 +1,21 @@
+# TODO
+
+- performance kinda sucks (bruh)
+- offline mode
+- working keyboard support (oops)
+
+- video showing off the app
+- polish for ship
+
+- refresh button?
+
+duh:
+
+- projects page
+- explore page
+- settings page
+- shop page
+
+
+- name of project creator + picture?
+- demo, readme, repo urls

flavortui-1.0.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "flavortui"
+dynamic = ["version"]
+description = 'Feature-rich terminal UI for Flavortown: devlogs, projects, shop, and more.'
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = []
+authors = [
+  { name = "BookCatKid", email = "99609593+BookCatKid@users.noreply.github.com" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Programming Language :: Python :: Implementation :: PyPy",
+]
+dependencies = [
+  "textual",
+  "textual-image[textual]",
+  "requests",
+  "platformdirs",
+  "keyring",
+]
+
+[project.scripts]
+flavortui = "flavortui.main:main"
+
+[project.urls]
+Documentation = "https://github.com/BookCatKid/flavortui#readme"
+Issues = "https://github.com/BookCatKid/flavortui/issues"
+Source = "https://github.com/BookCatKid/flavortui"
+
+[tool.hatch.version]
+path = "src/flavortui/__about__.py"
+
+[tool.hatch.envs.types]
+extra-dependencies = [
+  "mypy>=1.0.0",
+]
+[tool.hatch.envs.types.scripts]
+check = "mypy --install-types --non-interactive {args:src/flavortui tests}"
+
+[tool.coverage.run]
+source_pkgs = ["flavortui", "tests"]
+branch = true
+parallel = true
+omit = [
+  "src/flavortui/__about__.py",
+]
+
+[tool.coverage.paths]
+flavortui = ["src/flavortui", "*/flavortui/src/flavortui"]
+tests = ["tests", "*/flavortui/tests"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]

flavortui-1.0.0/requirements.txt

@@ -0,0 +1,4 @@
+textual
+keyring
+requests
+textual-image[textual]

flavortui-1.0.0/src/flavortui/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2026-present BookCatKid <99609593+BookCatKid@users.noreply.github.com>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "1.0.0"

flavortui-1.0.0/src/flavortui/__init__.py

@@ -0,0 +1,3 @@
+from .__about__ import __version__
+
+__all__ = ["__version__"]

flavortui-1.0.0/src/flavortui/__main__.py

@@ -0,0 +1,4 @@
+from flavortui.main import main
+
+if __name__ == "__main__":
+    main()

flavortui-1.0.0/src/flavortui/api/api.py

@@ -0,0 +1,75 @@
+from urllib.parse import urlencode
+
+from flavortui.api.client import get_client
+
+# This file is surprisingly simple!
+
+# simple helper func
+
+
+def fetch_endpoint(endpoint, api_key):
+    return get_client(api_key).fetch_endpoint(endpoint)
+
+
+# User stuff
+
+
+def get_user(api_key, user_id="me"):
+    status_code, response = fetch_endpoint(f"users/{user_id}", api_key)
+    return status_code, response
+
+
+def get_users(api_key, query="", page=1):
+    params = urlencode({"page": page, "query": query})
+    return fetch_endpoint(f"users?{params}", api_key)
+
+
+# Store stuff
+
+
+def get_store(api_key):
+    return fetch_endpoint("store", api_key)
+
+
+# don't think I'll ever use this but ok?
+def get_store_item(api_key, item_id):
+    return fetch_endpoint(f"store/{item_id}", api_key)
+
+
+# Projects
+
+
+def get_project(api_key, project_id):
+    return fetch_endpoint(f"projects/{project_id}", api_key)
+
+
+def get_projects_for_user(api_key, user_id="me"):
+    user = get_user(api_key, user_id)
+    projects = []
+    for project_id in user[1]["project_ids"]:
+        projects.append(get_project(api_key, project_id))
+    return projects
+
+
+def get_projects(api_key, page=1, query=""):
+    params = urlencode({"page": page, "query": query})
+    return fetch_endpoint(f"projects?{params}", api_key)
+
+
+# Devlogs
+
+
+def get_project_devlogs(api_key, project_id):
+    return fetch_endpoint(f"projects/{project_id}/devlogs", api_key)
+
+
+def get_devlogs(api_key, page=1):
+    params = urlencode({"page": page})
+    return fetch_endpoint(f"devlogs?{params}", api_key)
+
+
+# Check api key
+
+
+def check_api_key(api_key):
+    return get_user(api_key, "me")[0] == 200

flavortui-1.0.0/src/flavortui/api/api_key.py

@@ -0,0 +1,16 @@
+import keyring
+
+SERVICE = "flavortown-cli"
+ACCOUNT = "default"
+
+
+def get_api_key():
+    return keyring.get_password(SERVICE, ACCOUNT)
+
+
+def save_api_key(key: str):
+    keyring.set_password(SERVICE, ACCOUNT, key)
+
+
+def delete_api_key():
+    keyring.delete_password(SERVICE, ACCOUNT)

flavortui-1.0.0/src/flavortui/api/client.py

@@ -0,0 +1,168 @@
+import hashlib
+import json
+import os
+import threading
+import time
+import urllib.parse
+
+import requests
+
+CACHE_DIR = ".cache"
+API_TIMEOUT = (3.05, 10)
+IMAGE_TIMEOUT = (3.05, 20)
+
+
+class OfflineError(Exception):
+    pass
+
+
+class ApiClient:
+    def __init__(self, api_key, settings=None):
+        self.api_key = api_key
+        self.settings = settings or {}
+        self.base_url = "https://flavortown.hackclub.com/api/v1"
+        self.headers = {
+            "Authorization": f"Bearer {api_key}",
+            "X-Flavortown-Ext-16596": "true",
+        }
+        self.is_offline = False
+
+        self._ensure_cache_dir()
+
+        self.rate_limits = {
+            # In seconds, how long we should wait between requests.
+            # In general we go for double the "required" time.
+            "projects": 24,
+            "store": 24,
+            "users_list": 24,
+            "projects_id": 4,
+            "store_id": 4,
+            "default": 2,
+        }
+
+    def _ensure_cache_dir(self):
+        os.makedirs(CACHE_DIR, exist_ok=True)
+
+    def _get_cache_file(self, endpoint, file_format):
+        hashed_key = hashlib.sha256(endpoint.encode()).hexdigest()
+        return os.path.join(CACHE_DIR, f"{hashed_key}.{file_format}")
+
+    def _save_to_cache(self, endpoint, response, status_code):
+        self._ensure_cache_dir()
+        file_name = self._get_cache_file(endpoint, "json")
+        with open(file_name, "w", encoding="utf-8") as file:
+            json.dump(
+                {
+                    "timestamp": time.time(),
+                    "data": response,
+                    "status_code": status_code,
+                },
+                file,
+            )
+
+    def _load_from_cache(self, endpoint):
+        file_name = self._get_cache_file(endpoint, "json")
+        if os.path.exists(file_name):
+            with open(file_name, "r", encoding="utf-8") as f:
+                return json.load(f)
+        return None
+
+    def _get_endpoint_rate_limit(self, endpoint):
+        parts = endpoint.split("/")
+        base = parts[0]
+
+        if base == "users":
+            if len(parts) == 1:
+                return self.rate_limits["users_list"]
+            return self.rate_limits["default"]
+
+        if base == "store":
+            if len(parts) == 1:
+                return self.rate_limits["store"]
+            return self.rate_limits["store_id"]
+
+        if base == "projects":
+            if len(parts) == 1:
+                return self.rate_limits["projects"]
+            return self.rate_limits["projects_id"]
+
+        # add other bases here later
+
+        return self.rate_limits["default"]
+
+    def _revalidate(self, endpoint):
+        try:
+            response = requests.get(
+                f"{self.base_url}/{endpoint}",
+                headers=self.headers,
+                timeout=API_TIMEOUT,
+            )
+            self._save_to_cache(endpoint, response.json(), response.status_code)
+        except Exception:
+            pass
+
+    def fetch_endpoint(self, endpoint):
+        cached_file = self._load_from_cache(endpoint)
+        caching_strategy = self.settings.get("caching_strategy", "timed")
+        if cached_file:
+            # default caching
+            if (
+                time.time() - cached_file["timestamp"]
+                < self._get_endpoint_rate_limit(endpoint)
+                and caching_strategy == "timed"
+            ):
+                return cached_file["status_code"], cached_file["data"]
+            # extended caching
+            if (
+                time.time() - cached_file["timestamp"]
+                < self._get_endpoint_rate_limit(endpoint) * 15
+                and caching_strategy == "extended"
+            ):
+                return cached_file["status_code"], cached_file["data"]
+            # swr caching
+            if caching_strategy == "swr":
+                if time.time() - cached_file[
+                    "timestamp"
+                ] >= self._get_endpoint_rate_limit(endpoint):
+                    threading.Thread(
+                        target=self._revalidate, args=(endpoint,), daemon=True
+                    ).start()
+                return cached_file["status_code"], cached_file["data"]
+
+        url = f"{self.base_url}/{endpoint}"
+
+        try:
+            response = requests.get(url, headers=self.headers, timeout=API_TIMEOUT)
+        except requests.ConnectionError as e:
+            self.is_offline = True
+            if cached_file:
+                return cached_file["status_code"], cached_file["data"]
+            raise OfflineError("Could not connect to the Flavortown server.") from e
+        self.is_offline = False
+        data = response.json()
+        self._save_to_cache(endpoint, data, response.status_code)
+        return response.status_code, data
+
+    def fetch_image(self, url):
+        ext = os.path.splitext(urllib.parse.urlparse(url).path)[1].lstrip(".") or "png"
+        if not os.path.exists(self._get_cache_file(url, ext)):
+            try:
+                response = requests.get(url, timeout=IMAGE_TIMEOUT)
+                response.raise_for_status()
+            except requests.ConnectionError:
+                raise OfflineError("Could not connect to the Flavortown server.")
+            with open(self._get_cache_file(url, ext), "wb") as f:
+                f.write(response.content)
+        return self._get_cache_file(url, ext)
+
+
+_GLOBAL_CLIENT = None
+
+
+def get_client(api_key, settings=None):
+    global _GLOBAL_CLIENT
+    if not _GLOBAL_CLIENT or _GLOBAL_CLIENT.api_key != api_key:
+        _GLOBAL_CLIENT = ApiClient(api_key, settings)
+    elif settings is not None:
+        _GLOBAL_CLIENT.settings = settings
+    return _GLOBAL_CLIENT

flavortui-1.0.0/src/flavortui/api/functions.py

@@ -0,0 +1,14 @@
+from datetime import datetime, timezone
+
+
+def format_seconds(seconds):
+    try:
+        hours = seconds // 3600
+        minutes = (seconds % 3600) // 60
+        return f"{hours}h {minutes}m"
+    except Exception:
+        return "0h 0m"
+
+
+def get_days_ago(utc_time_string):
+    return (datetime.now(timezone.utc) - datetime.fromisoformat(utc_time_string)).days

flavortui-1.0.0/src/flavortui/api/settings.py

@@ -0,0 +1,24 @@
+import json
+from pathlib import Path
+
+from platformdirs import user_config_dir
+
+SETTINGS_PATH = Path(user_config_dir("flavortui")) / "settings.json"
+DEFAULTS = {"image_mode": "auto", "caching_strategy": "swr"}
+
+
+def load_settings() -> dict:
+    if SETTINGS_PATH.exists():
+        try:
+            with open(SETTINGS_PATH, encoding="utf-8") as f:
+                saved = json.load(f)
+            return {**DEFAULTS, **saved}
+        except (json.JSONDecodeError, OSError):
+            pass
+    return dict(DEFAULTS)
+
+
+def save_settings(settings: dict) -> None:
+    SETTINGS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with open(SETTINGS_PATH, "w", encoding="utf-8") as f:
+        json.dump(settings, f, indent=2)

flavortui-1.0.0/src/flavortui/components/api_key_input.py

@@ -0,0 +1,84 @@
+from textual.app import ComposeResult
+from textual.widgets import Button, Input, Static
+
+from flavortui.api.api import check_api_key
+from flavortui.api.api_key import delete_api_key, get_api_key, save_api_key
+from flavortui.components.popup_modal import PopupModal
+
+
+class ApiKeyInput(PopupModal):
+    DEFAULT_CSS = """
+    #dialog {
+        height: auto;
+        max-height: 90%;
+        padding: 2 4;
+    }
+
+    #dialog-content {
+        height: auto;
+        align-horizontal: center;
+    }
+
+    #title {
+        text-align: center;
+        width: 100%;
+        margin-bottom: 1;
+    }
+
+    #subtitle {
+        text-align: center;
+        width: 100%;
+        margin-bottom: 1;
+    }
+    """
+
+    def __init__(self, callback_function, **kwargs):
+        super().__init__(**kwargs)
+        self._callback_function = callback_function
+
+    def compose_content(self) -> ComposeResult:
+        yield Static("🔒 Flavortown Api Key Required", id="title")
+        yield Static("Please enter your api key to continue.", id="subtitle")
+        yield Input(password=True, placeholder="Api Key")
+
+    def compose_footer(self) -> ComposeResult:
+        return [
+            Button("Save API Key", id="save_key", variant="success"),
+            Button("Print API Key", id="print_key", variant="primary"),
+            Button("Delete API Key", id="delete_key", variant="error"),
+            Button("Close", id="close", variant="default"),
+        ]
+
+    def on_button_pressed(self, event: Button.Pressed):
+        if event.button.id == "save_key":
+            self._save_key()
+        elif event.button.id == "print_key":
+            key = get_api_key()
+            if key:
+                self.notify(f"API Key: {key}", timeout=5.0)
+            else:
+                self.notify("No API key saved.", timeout=3.0)
+        elif event.button.id == "delete_key":
+            try:
+                delete_api_key()
+                self.notify("API key deleted successfully.", timeout=2.0)
+            except Exception as e:
+                self.notify(f"Error deleting API key: {e}", timeout=2.0)
+        elif event.button.id == "close":
+            self.app.pop_screen()
+
+    def _save_key(self) -> None:
+        value = self.query_one(Input).value
+        if not value.strip():
+            self.notify("API key cannot be empty.", timeout=2.0)
+            return
+        if not check_api_key(value):
+            self.notify("Invalid API key. Please check and try again.", timeout=4.0)
+            return
+        try:
+            save_api_key(value)
+            self.notify("Api key saved successfully!", timeout=2.0)
+            self.app.pop_screen()
+            self._callback_function()
+        except Exception as e:
+            self.notify(f"Error saving api key: {e}", timeout=2.0)