utils.py

# -*- coding: utf-8 -*-
"""通用工具: PHP 风格格式化 / 时间格式化 / 带缓存的 HTTP 请求"""
import hashlib
import json
import os
import re
import time
import urllib.parse
import urllib.request

CACHE_DIRECTORY = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'cache')

_FMT_RE = re.compile(
    r"%(?:(\d+)\$)?([-+ 0']*)(\d+)?(?:\.(\d+))?(l?)([bcdeEfFgGosuxX%])"
)


def _format_one(arg, flags, width, precision, conv):
    if conv == 's':
        s = '' if arg is None else str(arg)
        if precision is not None:
            s = s[:int(precision)]
        if width:
            w = int(width)
            if '-' in flags:
                s = s.ljust(w)
            elif '0' in flags:
                s = s.rjust(w, '0')
            else:
                s = s.rjust(w)
        return s
    if conv in 'duxX':
        try:
            n = int(round(float(arg or 0)))
        except (TypeError, ValueError):
            n = 0
        spec = ''
        if '-' in flags:
            spec += '<'
        if '+' in flags:
            spec += '+'
        if '0' in flags and '-' not in flags:
            spec += '0'
        if width:
            spec += width
        spec += {'d': 'd', 'u': 'd', 'x': 'x', 'X': 'X'}[conv]
        return format(n, spec)
    if conv in 'eEfFgG':
        try:
            n = float(arg or 0)
        except (TypeError, ValueError):
            n = 0.0
        spec = ''
        if '-' in flags:
            spec += '<'
        if '+' in flags:
            spec += '+'
        if '0' in flags and '-' not in flags:
            spec += '0'
        if width:
            spec += width
        spec += '.' + (precision if precision is not None else '6')
        spec += conv if conv in 'eEgG' else 'f'
        return format(n, spec)
    return '' if arg is None else str(arg)


def php_vsprintf(fmt, args):
    """模拟 PHP vsprintf, 支持 %1$s 位置参数与 %.3lf 等格式"""
    pos = [0]

    def repl(m):
        argnum, flags, width, precision, _l, conv = m.groups()
        if conv == '%':
            return '%'
        if argnum is not None:
            idx = int(argnum) - 1
        else:
            idx = pos[0]
            pos[0] += 1
        arg = args[idx] if 0 <= idx < len(args) else None
        return _format_one(arg, flags or '', width, precision, conv)

    return _FMT_RE.sub(repl, fmt)


def build_string(layout, placeholders=None):
    """按 PHP vsprintf 风格拼接多行文本"""
    placeholders = placeholders or []
    if isinstance(layout, list):
        joined = '\n'.join('' if x is None else str(x) for x in layout)
        return php_vsprintf(joined, placeholders).replace('\n\n', '\n')
    return php_vsprintf(str(layout), placeholders)


def number_format(num, decimals=0):
    """模拟 PHP number_format, None 按 0 处理"""
    try:
        n = float(num or 0)
    except (TypeError, ValueError):
        n = 0.0
    if decimals == 0:
        return format(int(round(n)), ',d')
    return format(round(n, decimals), ',.{}f'.format(decimals))


def div(a, b, nd=3):
    """安全除法, 任一为 0/None 时返回 0"""
    if not a or not b:
        return 0
    return round(a / b, nd)


_PHP_TO_STRFTIME = {
    'Y': '%Y', 'm': '%m', 'd': '%d',
    'H': '%H', 'i': '%M', 's': '%S',
}


def format_time(timestamp, in_seconds=False, fmt='Y-m-d H:i', offset=0):
    """gmdate 风格时间格式化, None 按 0 处理"""
    ts = timestamp or 0
    secs = round(ts) if in_seconds else round(ts / 1000) + offset
    strf = ''.join(_PHP_TO_STRFTIME.get(c, c) for c in fmt)
    return time.strftime(strf, time.gmtime(secs))


def get_url(url, query=None, cache_expiration=0, timeout=15):
    """带文件缓存的 GET 请求, 返回 (body, status) 失败时 body 为 None"""
    query = query or {}
    full_url = url + '?' + urllib.parse.urlencode(query)
    os.makedirs(CACHE_DIRECTORY, exist_ok=True)
    cache_file = os.path.join(CACHE_DIRECTORY, hashlib.md5(full_url.encode()).hexdigest())
    if os.path.isfile(cache_file) and time.time() - os.path.getmtime(cache_file) <= cache_expiration:
        with open(cache_file, 'r', encoding='utf-8') as f:
            return f.read(), 200

    headers = {'User-Agent': 'HypixelCheckPy/1.0'}
    # 根据最新 api.hypixel.net 文档, API Key 通过 API-Key 请求头传递
    if 'key' in query:
        q = dict(query)
        headers['API-Key'] = q.pop('key')
        full_url_req = url + '?' + urllib.parse.urlencode(q)
    else:
        full_url_req = full_url
    req = urllib.request.Request(full_url_req, headers=headers)
    try:
        with urllib.request.urlopen(req, timeout=timeout) as resp:
            body = resp.read().decode('utf-8')
            status = resp.status
    except urllib.error.HTTPError as e:
        return None, e.code
    except Exception:
        return None, 0
    if status == 200:
        with open(cache_file, 'w', encoding='utf-8') as f:
            f.write(body)
        return body, 200
    return None, status


def json_get(data, path, default=None):
    """按 a.b.c 路径取 JSON 值"""
    cur = data
    for key in path.split('.'):
        if isinstance(cur, dict) and key in cur:
            cur = cur[key]
        else:
            return default
    return cur


def size_format(byte):
    units = ['B', 'KB', 'MB', 'GB', 'TB', 'PB']
    pos = 0
    b = float(byte)
    while b >= 1024 and pos < len(units) - 1:
        b /= 1024
        pos += 1
    return '{} {}'.format(round(b, 2), units[pos])


def plain_string(formatted):
    """去除 Minecraft 颜色代码"""
    if formatted is None:
        return None
    return re.sub('§[0-9a-fk-or]', '', str(formatted))