algoux-standard-ranklist-utils 0.3.0__tar.gz

algoux_standard_ranklist_utils-0.3.0/.gitignore

@@ -0,0 +1,16 @@
+.DS_Store
+.idea
+node_modules
+dist
+.pnpm-debug.log
+npm-debug.log*
+.pytest_cache
+.ruff_cache
+.mypy_cache
+__pycache__
+*.egg-info
+python/dist
+python/build
+python/.venv
+go/testdata/*.tmp
+go/.gocache

algoux_standard_ranklist_utils-0.3.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: algoux-standard-ranklist-utils
+Version: 0.3.0
+Summary: Utilities for Standard Ranklist (srk).
+Project-URL: Homepage, https://github.com/algoux/standard-ranklist-utils
+Project-URL: Repository, https://github.com/algoux/standard-ranklist-utils
+Project-URL: Issues, https://github.com/algoux/standard-ranklist-utils/issues
+Author: bLue
+License-Expression: MIT
+Keywords: icpc,ranklist,srk,standard ranklist
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# algoux-standard-ranklist-utils
+
+Python utilities for Standard Ranklist (srk).
+
+Supported srk versions: `>=0.3.0 <0.4.0`.
+
+## Install
+
+```shell
+pip install algoux-standard-ranklist-utils
+```
+
+## Usage Sample
+
+```python
+from standard_ranklist_utils import format_time_duration, resolve_text, sort_rows
+
+format_time_duration([1.5, "h"], "min")  # 90
+resolve_text({"fallback": "English", "zh-CN": "中文"}, ["zh-CN"])  # 中文
+sort_rows(ranklist["rows"], ranklist.get("sorter", {}).get("config"))
+```
+
+## Utilities
+
+### formatters
+
+- `format_time_duration`: Convert an srk `TimeDuration` between `ms`, `s`, `min`, `h`, and `d`.
+- `pre_zero_fill`: Left-pad a number with zeroes for fixed-width display.
+- `sec_to_time_str`: Format elapsed seconds as a ranklist time string such as `1:02:03` or `1D 1:02:03`.
+- `number_to_alphabet`: Convert a zero-based problem index to an alphabetic alias such as `A`, `Z`, or `AA`.
+- `alphabet_to_number`: Convert an alphabetic problem alias back to a zero-based index.
+
+### resolvers
+
+- `resolve_text`: Resolve plain or i18n srk text using explicit language preferences and fallback text.
+- `resolve_contributor`: Parse a contributor string into `name`, optional `email`, and optional `url`.
+- `resolve_color`: Normalize an srk color value to a CSS color string.
+- `resolve_theme_color`: Expand a single color or theme color object into explicit light and dark colors.
+- `resolve_style`: Resolve text/background style colors and auto-pick readable text color when needed.
+- `resolve_user_markers`: Resolve a user's marker IDs to marker definitions from the ranklist config.
+
+### ranklist
+
+- `sort_rows`: Sort rows by ICPC solved count descending and penalty time ascending, with optional ranking-time precision.
+- `regenerate_ranklist_by_solutions`: Rebuild rows, scores, sorting, and problem statistics from solution tetrads.
+- `regenerate_rows_by_incremental_solutions`: Apply incremental solution tetrads to existing rows and re-sort them.
+- `convert_to_static_ranklist`: Add precomputed per-series rank values and segment indexes to each row.

algoux_standard_ranklist_utils-0.3.0/README.md

@@ -0,0 +1,47 @@
+# algoux-standard-ranklist-utils
+
+Python utilities for Standard Ranklist (srk).
+
+Supported srk versions: `>=0.3.0 <0.4.0`.
+
+## Install
+
+```shell
+pip install algoux-standard-ranklist-utils
+```
+
+## Usage Sample
+
+```python
+from standard_ranklist_utils import format_time_duration, resolve_text, sort_rows
+
+format_time_duration([1.5, "h"], "min")  # 90
+resolve_text({"fallback": "English", "zh-CN": "中文"}, ["zh-CN"])  # 中文
+sort_rows(ranklist["rows"], ranklist.get("sorter", {}).get("config"))
+```
+
+## Utilities
+
+### formatters
+
+- `format_time_duration`: Convert an srk `TimeDuration` between `ms`, `s`, `min`, `h`, and `d`.
+- `pre_zero_fill`: Left-pad a number with zeroes for fixed-width display.
+- `sec_to_time_str`: Format elapsed seconds as a ranklist time string such as `1:02:03` or `1D 1:02:03`.
+- `number_to_alphabet`: Convert a zero-based problem index to an alphabetic alias such as `A`, `Z`, or `AA`.
+- `alphabet_to_number`: Convert an alphabetic problem alias back to a zero-based index.
+
+### resolvers
+
+- `resolve_text`: Resolve plain or i18n srk text using explicit language preferences and fallback text.
+- `resolve_contributor`: Parse a contributor string into `name`, optional `email`, and optional `url`.
+- `resolve_color`: Normalize an srk color value to a CSS color string.
+- `resolve_theme_color`: Expand a single color or theme color object into explicit light and dark colors.
+- `resolve_style`: Resolve text/background style colors and auto-pick readable text color when needed.
+- `resolve_user_markers`: Resolve a user's marker IDs to marker definitions from the ranklist config.
+
+### ranklist
+
+- `sort_rows`: Sort rows by ICPC solved count descending and penalty time ascending, with optional ranking-time precision.
+- `regenerate_ranklist_by_solutions`: Rebuild rows, scores, sorting, and problem statistics from solution tetrads.
+- `regenerate_rows_by_incremental_solutions`: Apply incremental solution tetrads to existing rows and re-sort them.
+- `convert_to_static_ranklist`: Add precomputed per-series rank values and segment indexes to each row.

algoux_standard_ranklist_utils-0.3.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "algoux-standard-ranklist-utils"
+version = "0.3.0"
+description = "Utilities for Standard Ranklist (srk)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "bLue" }]
+keywords = ["standard ranklist", "srk", "ranklist", "icpc"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/algoux/standard-ranklist-utils"
+Repository = "https://github.com/algoux/standard-ranklist-utils"
+Issues = "https://github.com/algoux/standard-ranklist-utils/issues"
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "pytest>=8.0",
+  "ruff>=0.5",
+  "twine>=5.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/standard_ranklist_utils"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

algoux_standard_ranklist_utils-0.3.0/src/standard_ranklist_utils/__init__.py

@@ -0,0 +1,72 @@
+from .constants import MIN_REGEN_SUPPORTED_VERSION, SRK_SUPPORTED_VERSIONS
+from .enums import EnumTheme
+from .formatters import (
+    alphabet_to_number,
+    format_time_duration,
+    number_to_alphabet,
+    pre_zero_fill,
+    sec_to_time_str,
+)
+from .ranklist import (
+    convert_to_static_ranklist,
+    regenerate_ranklist_by_solutions,
+    regenerate_rows_by_incremental_solutions,
+    sort_rows,
+)
+from .resolvers import (
+    resolve_color,
+    resolve_contributor,
+    resolve_style,
+    resolve_text,
+    resolve_theme_color,
+    resolve_user_markers,
+)
+from .types import (
+    CalculatedSolutionTetrad,
+    Color,
+    I18NStringSet,
+    Marker,
+    Ranklist,
+    RanklistRow,
+    RankProblemStatus,
+    RankValue,
+    Text,
+    ThemeColor,
+    ThemeColorInput,
+    TimeDuration,
+    TimeUnit,
+)
+
+__all__ = [
+    "MIN_REGEN_SUPPORTED_VERSION",
+    "SRK_SUPPORTED_VERSIONS",
+    "EnumTheme",
+    "TimeUnit",
+    "TimeDuration",
+    "I18NStringSet",
+    "Text",
+    "Color",
+    "ThemeColorInput",
+    "ThemeColor",
+    "RankValue",
+    "CalculatedSolutionTetrad",
+    "Ranklist",
+    "RanklistRow",
+    "RankProblemStatus",
+    "Marker",
+    "format_time_duration",
+    "pre_zero_fill",
+    "sec_to_time_str",
+    "number_to_alphabet",
+    "alphabet_to_number",
+    "resolve_text",
+    "resolve_contributor",
+    "resolve_color",
+    "resolve_theme_color",
+    "resolve_style",
+    "resolve_user_markers",
+    "sort_rows",
+    "regenerate_ranklist_by_solutions",
+    "regenerate_rows_by_incremental_solutions",
+    "convert_to_static_ranklist",
+]

algoux_standard_ranklist_utils-0.3.0/src/standard_ranklist_utils/constants.py

@@ -0,0 +1,2 @@
+MIN_REGEN_SUPPORTED_VERSION = "0.3.0"
+SRK_SUPPORTED_VERSIONS = ">=0.3.0 <0.4.0"

algoux_standard_ranklist_utils-0.3.0/src/standard_ranklist_utils/enums.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class EnumTheme(str, Enum):
+    light = "light"
+    dark = "dark"

algoux_standard_ranklist_utils-0.3.0/src/standard_ranklist_utils/formatters.py

@@ -0,0 +1,99 @@
+import math
+from collections.abc import Sequence
+from typing import Callable, Union
+
+from .types import TimeUnit
+
+NumberLike = Union[int, float, str]
+
+
+def _to_milliseconds(time: Sequence[Union[int, float, str]]) -> float:
+    value = time[0]
+    unit = time[1]
+    if not isinstance(value, (int, float)) or not math.isfinite(value) or value < 0:
+        raise ValueError(f"Invalid source time value {value}")
+    if unit == "ms":
+        return value
+    if unit == "s":
+        return value * 1000
+    if unit == "min":
+        return value * 1000 * 60
+    if unit == "h":
+        return value * 1000 * 60 * 60
+    if unit == "d":
+        return value * 1000 * 60 * 60 * 24
+    raise ValueError(f"Invalid source time unit {unit}")
+
+
+def format_time_duration(
+    time: Sequence[Union[int, float, str]],
+    target_unit: TimeUnit = "ms",
+    fmt: Callable[[float], float] = lambda number: number,
+) -> float:
+    ms = _to_milliseconds(time)
+    if target_unit == "ms":
+        return ms
+    if target_unit == "s":
+        return fmt(ms / 1000)
+    if target_unit == "min":
+        return fmt(ms / 1000 / 60)
+    if target_unit == "h":
+        return fmt(ms / 1000 / 60 / 60)
+    if target_unit == "d":
+        return fmt(ms / 1000 / 60 / 60 / 24)
+    raise ValueError(f"Invalid target time unit {target_unit}")
+
+
+def pre_zero_fill(num: int, size: int) -> str:
+    if num >= 10**size:
+        return str(num)
+    text = ("0" * size) + str(num)
+    return text[len(text) - size :]
+
+
+def sec_to_time_str(second: float, *, fill_hour: bool = False, show_day: bool = False) -> str:
+    if second < 0:
+        return "--"
+    sec = second
+    days = 0
+    if show_day:
+        days = math.floor(sec / 86400)
+        sec %= 86400
+    hours = math.floor(sec / 3600)
+    sec %= 3600
+    minutes = math.floor(sec / 60)
+    sec %= 60
+    seconds = math.floor(sec)
+    day_text = f"{days}D " if show_day and days >= 1 else ""
+    hour_text = pre_zero_fill(hours, 2) if fill_hour else str(hours)
+    return f"{day_text}{hour_text}:{pre_zero_fill(minutes, 2)}:{pre_zero_fill(seconds, 2)}"
+
+
+def number_to_alphabet(number: NumberLike) -> str:
+    n = int(float(number))
+    radix = 26
+    count = 1
+    power = radix
+    while n >= power:
+        n -= power
+        count += 1
+        power *= radix
+    result = []
+    while count > 0:
+        result.append(chr((n % radix) + 65))
+        n = math.trunc(n / radix)
+        count -= 1
+    return "".join(reversed(result))
+
+
+def alphabet_to_number(alphabet: str) -> int:
+    if not isinstance(alphabet, str) or not alphabet:
+        return -1
+    chars = list(reversed(alphabet.upper()))
+    radix = 26
+    power = 1
+    result = -1
+    for char in chars:
+        result += (ord(char) - 65) * power + power
+        power *= radix
+    return result

algoux_standard_ranklist_utils-0.3.0/src/standard_ranklist_utils/py.typed

@@ -0,0 +1 @@
+