kattis-cli 1.0.6__py3-none-any.whl → 1.1.0__py3-none-any.whl

kattis_cli/download.py

@@ -1,5 +1,9 @@
-"""Download sample data and problem metadata from Kattis
-    and save them to data folders.
+"""Download sample data and problem metadata from Kattis and save them.
+
+This module provides a :class:`DownloadManager` that encapsulates
+the download and metadata parsing logic. For backward compatibility the
+module also exposes the original functions which delegate to a default
+``DownloadManager`` instance.
 """
 
 import shutil
@@ -12,168 +16,215 @@ from .utils import config, utility
 from . import settings
 
 
-def create_problem_folder(problemid: str) -> Path:
-    """Get existing problem folder in the current path.
+class DownloadManager:
+    """Manager responsible for fetching problem metadata and sample data."""
 
-    Args:
-        problemid (str): problemid
+    def create_problem_folder(self, problemid: str) -> Path | Any:
+        """Ensure and return the root folder for a problem.
 
-    Returns:
-        Path: problem folder
-    """
-    try:
-        root_problem_folder = utility.find_problem_root_folder(
-            Path.cwd(), f"{problemid}.yaml")
-    except FileNotFoundError:
-        root_problem_folder = Path.cwd().joinpath(problemid)
-        if not root_problem_folder.exists():
-            root_problem_folder.mkdir()
+        If a problem folder cannot be resolved by searching the current
+        working tree, create a new folder named after the problem id.
 
-    return root_problem_folder
+        Args:
+            problemid: The Kattis problem id.
 
+        Returns:
+            Path to the root problem folder, or Any on failure.
+        """
 
-def download_html(problemid: str) -> str:
-    """Get html content from Kattis problem page.
+        try:
+            root_problem_folder = utility.find_problem_root_folder(
+                Path.cwd(), f"{problemid}.yaml")
+        except FileNotFoundError:
+            root_problem_folder = Path.cwd().joinpath(problemid)
+            if not root_problem_folder.exists():
+                root_problem_folder.mkdir()
 
-    Args:
-        problemid (str): problemid
-    """
-    response = requests.get(settings.KATTIS_PROBLEM_URL + problemid, timeout=5)
-    if response.status_code == 200:
-        return response.text.strip()
-    else:
-        raise requests.exceptions.InvalidURL(f"Error: {response.status_code}")
+        return root_problem_folder
 
+    def download_html(self, problemid: str) -> str:
+        """Download the problem HTML page for a given problem id.
 
-def load_problem_metadata(problemid: str = '') -> Dict[Any, Any]:
-    """Load problem metadata from problem folder.
+        Returns the HTML body as a stripped string when successful or
+        raises an HTTP-related exception on failure.
+        """
 
-    Args:
-        problemid (str): problemid
+        response = requests.get(
+            settings.KATTIS_PROBLEM_URL + problemid, timeout=5)
+        if response.status_code == 200:
+            return response.text.strip()
+        else:
+            raise requests.exceptions.InvalidURL(
+                f"Error: {response.status_code}")
 
-    Returns:
-        Dict: problem metadata
-    """
-    metadata: Dict[str, Any] = dict()
-
-    filename = "*.yaml"
-    if problemid:
-        filename = f"{problemid}.yaml"
-    try:
-        # print('search ', filename, Path.cwd())
-        root_problem_folder = utility.find_problem_root_folder(
-            Path.cwd(), filename)
-        if not problemid:
-            problemid = root_problem_folder.name
-    except FileNotFoundError:
-        # print('file not found...')
-        if not problemid:
-            return metadata
+    def load_problem_metadata(self, problemid: str = '') -> Dict[Any, Any]:
+        """Load problem metadata from disk or by scraping the problem page.
+
+        If a local YAML metadata file is present it is loaded. Otherwise
+        the problem page is downloaded and parsed, and the metadata is
+        saved locally before being returned.
+        """
+
+        metadata: Dict[str, Any] = dict()
+
+        filename = "*.yaml"
+        if problemid:
+            filename = f"{problemid}.yaml"
+        try:
+            root_problem_folder = utility.find_problem_root_folder(
+                Path.cwd(), filename)
+            if not problemid:
+                problemid = root_problem_folder.name
+        except FileNotFoundError:
+            if not problemid:
+                return metadata
+            else:
+                root_problem_folder = Path.cwd().joinpath(problemid)
+                if not root_problem_folder.exists():
+                    root_problem_folder.mkdir()
+
+        metadata_file = root_problem_folder.joinpath(f"{problemid}.yaml")
+        if metadata_file.exists():
+            with open(metadata_file, "r", encoding='utf-8') as f:
+                metadata = yaml.safe_load(f)
+                if 'submissions' not in metadata:
+                    metadata['submissions'] = 0
+                    metadata['accepted'] = 0
+                    config.update_problem_metadata(problemid, metadata)
         else:
-            root_problem_folder = Path.cwd().joinpath(problemid)
-            if not root_problem_folder.exists():
-                root_problem_folder.mkdir()
-    # print('root_problem_folder', root_problem_folder)
-    metadata_file = root_problem_folder.joinpath(f"{problemid}.yaml")
-    # print('metadata_file', metadata_file)
-    if metadata_file.exists():
-        with open(metadata_file, "r", encoding='utf-8') as f:
-            metadata = yaml.safe_load(f)
-            if 'submissions' not in metadata:
-                metadata['submissions'] = 0
-                metadata['accepted'] = 0
-                config.update_problem_metadata(problemid, metadata)
-    else:
-        html = download_html(problemid)
-        metadata = _parse_metadata(problemid, html)
-        save_metadata(problemid, metadata)
-    return metadata
-
-
-def _parse_metadata(problemid: str,
-                    html: str,
-                    ) -> Dict[str, Any]:
-    """Parse metadata from Kattis problm page.
-    This function should only be called if
-    the metadata file does not exist.
-
-    Args:
-        root_problem_folder (Path): problem folder
-        problemid (str): Kattis problemid
-
-    Returns:
-        Dict: problem metadata
+            html = self.download_html(problemid)
+            metadata = self._parse_metadata(problemid, html)
+            self.save_metadata(problemid, metadata)
+        return metadata
+
+    def _parse_metadata(self, problemid: str, html: str) -> Dict[str, Any]:
+        """Internal parser that extracts metadata from problem HTML.
+
+        This method uses BeautifulSoup to extract title, limits,
+        difficulty and basic submission stats from the problem page.
+        """
+
+        soup = BeautifulSoup(html, "html.parser")
+        meta_data = {'problemid': problemid, 'title': '',
+                     'cpu_limit': 'None', 'mem_limit': 'None',
+                     'difficulty': 'None',
+                     'submissions': 0, 'accepted': 0}
+
+        title = soup.find("h1")
+        if title:
+            meta_data["title"] = title.text
+
+        data = soup.find("div", {"class": "metadata-grid"})
+        name_mapping = {'metadata-cpu-card': 'cpu_limit',
+                        'metadata-memmory-card': 'mem_limit',
+                        'metadata-difficulty-card': 'difficulty',
+                        }
+
+        for key, key1 in name_mapping.items():
+            try:
+                value = ''
+                # Use .find() instead of deprecated .findChild()
+                div = data.find('div', {'class': key})  # type: ignore
+                if key == 'metadata-difficulty-card':
+                    cls = {'class': 'difficulty_number'}
+                    span = div.find('span', cls)  # type: ignore
+                    if span:
+                        value += span.text.strip() + ' '  # type: ignore
+                cls2 = {'class': 'text-blue-200'}
+                span = div.find('span', cls2)  # type: ignore
+                if span:
+                    value += span.text.strip()  # type: ignore
+                meta_data[key1] = value
+            except AttributeError:
+                pass
+        return meta_data
+
+    def parse_metadata(self, problemid: str, html: str) -> Dict[str, Any]:
+        """Public alias for the internal metadata parser.
+
+        Keeping a public method makes it easier for external callers and
+        the compatibility wrapper to access parsing without touching a
+        protected member.
+        """
+        return self._parse_metadata(problemid, html)
+
+    def save_metadata(self, problemid: str, metadata: Dict[str, Any]) -> None:
+        """Persist metadata dictionary to the problem YAML file."""
+
+        root_problem_folder = self.create_problem_folder(problemid)
+        metadata_file = root_problem_folder.joinpath(f"{problemid}.yaml")
+        with open(metadata_file, "w", encoding='utf-8') as f:
+            yaml.dump(metadata, f, default_flow_style=False,
+                      allow_unicode=True)
+
+    def download_sample_data(self, problemid: str) -> None:
+        """Download the sample data zip for a problem and unpack it.
+
+        The samples are downloaded into a `data/` folder inside the
+        problem root folder and the zip is removed after extraction.
+        """
+
+        uri = f'{settings.KATTIS_PROBLEM_URL}{problemid}'
+        uri += '/file/statement/samples.zip'
+
+        root_problem_folder = self.create_problem_folder(problemid)
+
+        data_folder = root_problem_folder.joinpath('data')
+        data_folder.mkdir(exist_ok=True)
+        response = requests.get(uri, allow_redirects=True, timeout=10)
+        if response.status_code == 200:
+            zip_path = data_folder.joinpath('samples.zip')
+            with open(data_folder.joinpath('samples.zip'), 'wb') as f:
+                f.write(response.content)
+            shutil.unpack_archive(zip_path, data_folder)
+            zip_path.unlink()
+        else:
+            raise requests.exceptions.InvalidURL(
+                f"Error: {response.status_code}")
+
+
+# Default manager instance for compatibility with existing imports
+_manager = DownloadManager()
+
+
+def create_problem_folder(problemid: str) -> Path:
+    """Module-level wrapper returning the problem root folder.
+
+    Delegates to the default :class:`DownloadManager` instance so code
+    using the previous functional API continues to work.
     """
 
-    soup = BeautifulSoup(html, "html.parser")
-    meta_data = {'problemid': problemid, 'title': '',
-                 'cpu_limit': 'None', 'mem_limit': 'None',
-                 'difficulty': 'None',
-                 'submissions': 0, 'accepted': 0}
-
-    # get the title of the problem
-    title = soup.find("h1")
-    if title:
-        meta_data["title"] = title.text
-
-    # get the cpu time limit, memory limit, difficulty, and source
-    data = soup.find("div", {"class": "metadata-grid"})
-    name_mapping = {'metadata-cpu-card': 'cpu_limit',
-                    'metadata-memmory-card': 'mem_limit',
-                    'metadata-difficulty-card': 'difficulty',
-                    }
-
-    for key, key1 in name_mapping.items():
-        try:
-            value = ''
-            div = data.findChild('div', {'class': key})  # type: ignore
-            if key == 'metadata-difficulty-card':
-                span = div.findChild(  # type: ignore
-                    'span', {
-                        'class': 'difficulty_number'})
-                value += span.text.strip() + ' '  # type: ignore
-            span = div.findChild('span',  # type: ignore
-                                 {'class': 'text-blue-200'})
-            value += span.text.strip()  # type: ignore
-            meta_data[key1] = value
-        except AttributeError:
-            pass
-    return meta_data
+    return _manager.create_problem_folder(problemid)
+
+
+def download_html(problemid: str) -> str:
+    """Download problem HTML using the module-level manager."""
+
+    return _manager.download_html(problemid)
+
+
+def load_problem_metadata(problemid: str = '') -> Dict[Any, Any]:
+    """Load problem metadata via the default DownloadManager."""
+
+    return _manager.load_problem_metadata(problemid)
 
 
 def save_metadata(problemid: str, metadata: Dict[str, Any]) -> None:
-    """Save metadata to problem folder.
+    """Persist metadata using the default DownloadManager."""
 
-    Args:
-        problemid (str): problemid
-        metadata (Dict[str, Any]): metadata
-    """
-    root_problem_folder = create_problem_folder(problemid)
-    metadata_file = root_problem_folder.joinpath(f"{problemid}.yaml")
-    with open(metadata_file, "w", encoding='utf-8') as f:
-        yaml.dump(metadata, f, default_flow_style=False, allow_unicode=True)
+    return _manager.save_metadata(problemid, metadata)
 
 
 def download_sample_data(problemid: str) -> None:
-    """Download sample data from Kattis and save them to data folders.
+    """Download and unpack sample data using the default manager."""
+
+    return _manager.download_sample_data(problemid)
+
 
-    Args:
-        problemid (str): Kattis problem id.
+def _parse_metadata(problemid: str, html: str) -> Dict[str, Any]:
+    """Compatibility wrapper for the legacy module-level helper used by
+    tests. Delegates to the DownloadManager implementation.
     """
-    uri = f'{settings.KATTIS_PROBLEM_URL}{problemid}'
-    uri += '/file/statement/samples.zip'
-
-    root_problem_folder = create_problem_folder(problemid)
-
-    data_folder = root_problem_folder.joinpath('data')
-    data_folder.mkdir(exist_ok=True)
-    response = requests.get(uri, allow_redirects=True, timeout=10)
-    if response.status_code == 200:
-        zip_path = data_folder.joinpath('samples.zip')
-        with open(data_folder.joinpath('samples.zip'), 'wb') as f:
-            f.write(response.content)
-        # extract zip file
-        shutil.unpack_archive(zip_path, data_folder)
-        zip_path.unlink()
-    else:
-        raise requests.exceptions.InvalidURL(f"Error: {response.status_code}")
+    # Prefer the public API on the manager to avoid accessing a protected
+    # member from outside the class.
+    return _manager.parse_metadata(problemid, html)

kattis_cli/fireworks.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Headless fireworks animation for CI/Docker.
+
+This script intentionally avoids any GUI libraries and provides a
+terminal-only fireworks animation suitable for headless environments.
+Configuration can be provided via `scripts/ui_config.yml`
+"""
+
+import os
+import sys
+import locale
+import time
+from random import randint, choice
+import subprocess
+from pathlib import Path
+
+
+def run_fireworks() -> None:
+    """Simple ASCII fireworks for headless environments.
+
+    Draws random bursts in the terminal using ANSI colors. Works in CI/Docker
+    and avoids external dependencies.
+    """
+    frames = 40
+    width = 60
+    height = 20
+    message = None
+    symbols = ['*', '•', '✶', '✸']
+    colors = [
+        '\x1b[37m',  # white
+        '\x1b[31m',  # red
+        '\x1b[32m',  # green
+        '\x1b[34m',  # blue
+        '\x1b[33m',  # yellow
+        '\x1b[35m',  # magenta
+        '\x1b[36m',  # cyan
+    ]
+    reset = '\x1b[0m'
+
+    # Only emit ANSI color codes when stdout is a TTY and terminal
+    # appears to support colors. In CI or when output is captured the
+    # escape characters may be shown literally (e.g. as ``\u001b[...]``)
+    # so we disable color codes in that case to avoid escaped sequences
+    # appearing in logs.
+    use_color = sys.stdout.isatty() and os.environ.get('NO_COLOR') is None
+    if os.environ.get('TERM') == 'dumb':
+        use_color = False
+    if not use_color:
+        colors = ['']
+        reset = ''
+
+    # Detect Unicode support in the execution environment. Some minimal
+    # container images or redirected outputs use an ASCII locale so fancy
+    # symbols (✶, ✸, •, emojis) render poorly or get replaced. We fall
+    # back to ASCII symbols when Unicode is not supported.
+    out_encoding = sys.stdout.encoding or \
+        locale.getpreferredencoding(False) or ''
+    out_encoding = (out_encoding or '').lower()
+    supports_unicode = ('utf' in out_encoding)
+    if not supports_unicode:
+        # Simple ASCII fallback symbols
+        symbols = ['*', '+', 'o', '.']
+        # Replace message with ASCII-only fallback if necessary
+        if message:
+            try:
+                message.encode('ascii')
+            except (UnicodeEncodeError, TypeError):
+                message = (message.encode('ascii', 'replace')
+                           .decode('ascii'))
+        # Inform interactive users why we fell back (but avoid noisy logs
+        # in captured/non-interactive runs).
+        if sys.stdout.isatty():
+            print(
+                'Note: terminal does not appear to support UTF-8 — '
+                'using ASCII fallback for fireworks.',
+                file=sys.stderr,
+            )
+
+    try:
+        # Hide cursor (only when terminal supports it)
+        if use_color:
+            sys.stdout.write('\x1b[?25l')
+        for _ in range(frames):
+            # clear screen when supported, otherwise don't emit escapes
+            if use_color:
+                sys.stdout.write('\x1b[2J\x1b[H')
+            cx = randint(width // 4, 3 * width // 4)
+            cy = randint(height // 4, 3 * height // 4)
+            grid = [[' ' for _ in range(width)] for _ in range(height)]
+            # place particles
+            for _ in range(randint(12, 40)):
+                dx = int(randint(-8, 8) * (randint(0, 100) / 100.0))
+                dy = int(randint(-4, 4) * (randint(0, 100) / 100.0))
+                x = max(0, min(width - 1, cx + dx))
+                y = max(0, min(height - 1, cy + dy))
+                grid[y][x] = choice(symbols)
+
+            # render
+            for row in grid:
+                line = ''
+                for ch in row:
+                    if ch == ' ':
+                        line += ' '
+                    else:
+                        line += choice(colors) + ch + reset
+                sys.stdout.write(line + '\n')
+            sys.stdout.flush()
+            time.sleep(0.12)
+
+        # final message
+        msg = message or '🎉 Congratulations — Accepted! 🎉'
+        sys.stdout.write('\n')
+        if use_color:
+            sys.stdout.write('\x1b[1;33m')
+            sys.stdout.write(msg)
+            sys.stdout.write('\x1b[0m\n')
+        else:
+            sys.stdout.write(msg + '\n')
+        sys.stdout.flush()
+    finally:
+        # show cursor again
+        if use_color:
+            sys.stdout.write('\x1b[?25h')
+        sys.stdout.flush()
+
+
+if __name__ == '__main__':
+    run_fireworks()