qsu 0.1.0__py3-none-any.whl

qsu/__init__.py

@@ -0,0 +1,56 @@
+"""qsu - Quick & Simple Utility.
+
+A utility library that collects frequently used functions.
+This package mirrors the JavaScript implementation of qsu.
+
+Unlike the JavaScript package (where filesystem/OS/network/crypto helpers live
+under `qsu/node`), Python has no browser/runtime split, so every function is
+importable directly from the top-level `qsu` package.
+"""
+
+from . import (
+	array,
+	crypto,
+	date,
+	file,
+	format,
+	math,
+	misc,
+	net,
+	object,
+	os,
+	string,
+	verify,
+	web,
+)
+from .array import *  # noqa: F401,F403
+from .crypto import *  # noqa: F401,F403
+from .date import *  # noqa: F401,F403
+from .file import *  # noqa: F401,F403
+from .format import *  # noqa: F401,F403
+from .math import *  # noqa: F401,F403
+from .misc import *  # noqa: F401,F403
+from .net import *  # noqa: F401,F403
+from .object import *  # noqa: F401,F403
+from .os import *  # noqa: F401,F403
+from .string import *  # noqa: F401,F403
+from .verify import *  # noqa: F401,F403
+from .web import *  # noqa: F401,F403
+
+__version__ = '0.1.0'
+
+__all__ = [
+	*array.__all__,
+	*crypto.__all__,
+	*date.__all__,
+	*file.__all__,
+	*format.__all__,
+	*math.__all__,
+	*misc.__all__,
+	*net.__all__,
+	*object.__all__,
+	*os.__all__,
+	*string.__all__,
+	*verify.__all__,
+	*web.__all__,
+]

qsu/array/__init__.py

@@ -0,0 +1,29 @@
+from .arrCount import arrCount
+from .arrGroupByMaxCount import arrGroupByMaxCount
+from .arrMove import arrMove
+from .arrPick import arrPick
+from .arrRepeat import arrRepeat
+from .arrShuffle import arrShuffle
+from .arrTo1dArray import arrTo1dArray
+from .arrUnique import arrUnique
+from .arrWithDefault import arrWithDefault
+from .arrWithNumber import arrWithNumber
+from .average import average
+from .sortByObjectKey import sortByObjectKey
+from .sortNumeric import sortNumeric
+
+__all__ = [
+	'arrCount',
+	'arrGroupByMaxCount',
+	'arrMove',
+	'arrPick',
+	'arrRepeat',
+	'arrShuffle',
+	'arrTo1dArray',
+	'arrUnique',
+	'arrWithDefault',
+	'arrWithNumber',
+	'average',
+	'sortByObjectKey',
+	'sortNumeric',
+]

qsu/array/arrCount.py

@@ -0,0 +1,8 @@
+def arrCount(array: list) -> dict:
+	result = {}
+
+	for item in array:
+		key = str(item)
+		result[key] = result.get(key, 0) + 1
+
+	return result

qsu/array/arrGroupByMaxCount.py

@@ -0,0 +1,15 @@
+def arrGroupByMaxCount(array: list, maxLengthPerGroup: int = 1) -> list:
+	result = []
+	tempArray = []
+
+	for item in array:
+		if len(tempArray) == maxLengthPerGroup:
+			result.append(tempArray)
+			tempArray = []
+
+		tempArray.append(item)
+
+	if len(tempArray) > 0:
+		result.append(tempArray)
+
+	return result

qsu/array/arrMove.py

@@ -0,0 +1,9 @@
+def arrMove(array: list, fromIndex: int, to: int) -> list:
+	arrayLength = len(array)
+
+	if arrayLength <= fromIndex or arrayLength <= to:
+		raise Exception('Invalid move params')
+
+	array.insert(to, array.pop(fromIndex))
+
+	return array

qsu/array/arrPick.py

@@ -0,0 +1,8 @@
+import random
+
+
+def arrPick(array: list):
+	if not array or not isinstance(array, list) or len(array) < 1:
+		return None
+
+	return array[int(random.random() * len(array))]

qsu/array/arrRepeat.py

@@ -0,0 +1,17 @@
+from ..verify.isObject import isObject
+
+
+def arrRepeat(array, count: int) -> list:
+	if not array or count < 1 or not isinstance(array, (list, tuple, dict)):
+		return []
+
+	isObj = isObject(array)
+	result = []
+
+	for _ in range(count):
+		if isObj:
+			result.append(array)
+		else:
+			result.extend(array)
+
+	return result

qsu/array/arrShuffle.py

@@ -0,0 +1,15 @@
+import math
+import random
+
+
+def arrShuffle(array: list):
+	if len(array) == 1:
+		return array[0]
+
+	newArray = array
+
+	for i in range(len(array) - 1, 0, -1):
+		j = math.floor(random.random() * (i + 1))
+		newArray[i], newArray[j] = array[j], array[i]
+
+	return newArray

qsu/array/arrTo1dArray.py

@@ -0,0 +1,18 @@
+from ..verify.is2dArray import is2dArray
+
+
+def arrTo1dArray(array: list) -> list:
+	def convert1dArray(arr: list) -> list:
+		tempArr = []
+
+		for item in arr:
+			if not isinstance(item, (list, tuple)):
+				tempArr.append(item)
+			elif is2dArray(item):
+				tempArr.extend(convert1dArray(item))
+			else:
+				tempArr.extend(item)
+
+		return tempArr
+
+	return convert1dArray(array)

qsu/array/arrUnique.py

@@ -0,0 +1,28 @@
+import json
+
+from ..verify.is2dArray import is2dArray
+
+
+def arrUnique(array: list) -> list:
+	if is2dArray(array):
+		seen = set()
+		result = []
+
+		for item in array:
+			key = json.dumps(item, separators=(',', ':'))
+
+			if key not in seen:
+				seen.add(key)
+				result.append(json.loads(key))
+
+		return result
+
+	seen = []
+	result = []
+
+	for item in array:
+		if not any(existing is item or (type(existing) is type(item) and existing == item) for existing in seen):
+			seen.append(item)
+			result.append(item)
+
+	return result

qsu/array/arrWithDefault.py

@@ -0,0 +1,5 @@
+def arrWithDefault(defaultValue, length: int = 0) -> list:
+	if length < 1:
+		return []
+
+	return [defaultValue] * length

qsu/array/arrWithNumber.py

@@ -0,0 +1,5 @@
+def arrWithNumber(start: int, end: int) -> list:
+	if start > end:
+		raise Exception('`end` is greater than `start`.')
+
+	return list(range(start, end + 1))

qsu/array/average.py

@@ -0,0 +1,2 @@
+def average(array: list) -> float:
+	return sum(array) / len(array)

qsu/array/sortByObjectKey.py

@@ -0,0 +1,20 @@
+from .sortNumeric import _naturalKey
+
+
+def sortByObjectKey(
+	array: list,
+	key: str,
+	descending: bool = False,
+	numerically: bool = False,
+) -> list:
+	if numerically:
+		array.sort(key=lambda item: _naturalKey(item[key]))
+
+		if descending:
+			array.reverse()
+
+		return array
+
+	array.sort(key=lambda item: item[key], reverse=descending)
+
+	return array

qsu/array/sortNumeric.py

@@ -0,0 +1,16 @@
+import re
+
+
+def _naturalKey(value: str):
+	parts = re.split(r'(\d+)', str(value))
+
+	return [(0, int(part)) if part.isdigit() else (1, part) for part in parts if part != '']
+
+
+def sortNumeric(array: list, descending: bool = False) -> list:
+	array.sort(key=_naturalKey)
+
+	if descending:
+		array.reverse()
+
+	return array

qsu/crypto/__init__.py

@@ -0,0 +1,23 @@
+from .decodeBase64 import decodeBase64
+from .decrypt import decrypt
+from .encodeBase64 import encodeBase64
+from .encrypt import encrypt
+from .md5Hash import md5Hash
+from .numberHash import numberHash
+from .objectId import objectId
+from .sha1Hash import sha1Hash
+from .sha256Hash import sha256Hash
+from .sha512Hash import sha512Hash
+
+__all__ = [
+	'decodeBase64',
+	'decrypt',
+	'encodeBase64',
+	'encrypt',
+	'md5Hash',
+	'numberHash',
+	'objectId',
+	'sha1Hash',
+	'sha256Hash',
+	'sha512Hash',
+]

qsu/crypto/decodeBase64.py

@@ -0,0 +1,5 @@
+import base64
+
+
+def decodeBase64(encodedStr: str) -> str:
+	return base64.b64decode(encodedStr).decode('utf-8')

qsu/crypto/decrypt.py

@@ -0,0 +1,34 @@
+import base64
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+
+def decrypt(
+	str: str,
+	secret: str,
+	algorithm: str = 'aes-256-cbc',
+	toBase64: bool = False,
+) -> str:
+	if not str or len(str) < 1:
+		return ''
+
+	arrStr = str.split(':')
+	iv_part = arrStr.pop(0)
+	enc_part = ':'.join(arrStr)
+
+	if toBase64:
+		iv = base64.b64decode(iv_part)
+		enc = base64.b64decode(enc_part)
+	else:
+		iv = bytes.fromhex(iv_part)
+		enc = bytes.fromhex(enc_part)
+
+	cipher = Cipher(algorithms.AES(secret.encode('utf-8')), modes.CBC(iv))
+	decryptor = cipher.decryptor()
+	decrypted = decryptor.update(enc) + decryptor.finalize()
+
+	# Remove PKCS7 padding.
+	pad_len = decrypted[-1]
+	decrypted = decrypted[:-pad_len]
+
+	return decrypted.decode('utf-8')

qsu/crypto/encodeBase64.py

@@ -0,0 +1,5 @@
+import base64
+
+
+def encodeBase64(str: str) -> str:
+	return base64.b64encode(str.encode('utf-8')).decode('utf-8')

qsu/crypto/encrypt.py

@@ -0,0 +1,35 @@
+import base64
+import os
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+
+def encrypt(
+	str: str,
+	secret: str,
+	algorithm: str = 'aes-256-cbc',
+	ivSize: int = 16,
+	toBase64: bool = False,
+) -> str:
+	if not str or len(str) < 1:
+		return ''
+
+	iv = os.urandom(ivSize)
+	cipher = Cipher(algorithms.AES(secret.encode('utf-8')), modes.CBC(iv))
+	encryptor = cipher.encryptor()
+
+	data = str.encode('utf-8')
+	block_size = 16
+	pad_len = block_size - (len(data) % block_size)
+	padded = data + bytes([pad_len]) * pad_len
+
+	enc = encryptor.update(padded) + encryptor.finalize()
+
+	if toBase64:
+		iv_str = base64.b64encode(iv).decode('ascii')
+		enc_str = base64.b64encode(enc).decode('ascii')
+	else:
+		iv_str = iv.hex()
+		enc_str = enc.hex()
+
+	return f'{iv_str}:{enc_str}'

qsu/crypto/md5Hash.py

@@ -0,0 +1,19 @@
+import base64
+import hashlib
+from typing import Optional
+
+
+def md5Hash(str: str, encoding: Optional[str] = None) -> str:
+	digest = hashlib.md5(str.encode('utf-8')).digest()
+	enc = encoding or 'hex'
+
+	if enc == 'hex':
+		return digest.hex()
+	if enc == 'base64':
+		return base64.b64encode(digest).decode('ascii')
+	if enc == 'base64url':
+		return base64.urlsafe_b64encode(digest).decode('ascii').rstrip('=')
+	if enc == 'binary':
+		return digest.decode('latin-1')
+
+	raise ValueError(f'Unsupported encoding: {encoding}')

qsu/crypto/numberHash.py

@@ -0,0 +1,14 @@
+def numberHash(str: str) -> int:
+	if not str:
+		return 0
+
+	hash = 0
+
+	for ch in str:
+		hash = (hash << 5) - hash + ord(ch)
+		# Emulate JS `hash |= 0`: keep low 32 bits and interpret as signed.
+		hash &= 0xFFFFFFFF
+		if hash >= 0x80000000:
+			hash -= 0x100000000
+
+	return hash

qsu/crypto/objectId.py

@@ -0,0 +1,9 @@
+import secrets
+import time
+
+
+def objectId() -> str:
+	timestamp = format(int(time.time()), 'x')
+	random_hex = ''.join(format(secrets.randbelow(16), 'x') for _ in range(16))
+
+	return timestamp + random_hex

qsu/crypto/sha1Hash.py

@@ -0,0 +1,19 @@
+import base64
+import hashlib
+from typing import Optional
+
+
+def sha1Hash(str: str, encoding: Optional[str] = None) -> str:
+	digest = hashlib.sha1(str.encode('utf-8')).digest()
+	enc = encoding or 'hex'
+
+	if enc == 'hex':
+		return digest.hex()
+	if enc == 'base64':
+		return base64.b64encode(digest).decode('ascii')
+	if enc == 'base64url':
+		return base64.urlsafe_b64encode(digest).decode('ascii').rstrip('=')
+	if enc == 'binary':
+		return digest.decode('latin-1')
+
+	raise ValueError(f'Unsupported encoding: {encoding}')

qsu/crypto/sha256Hash.py

@@ -0,0 +1,19 @@
+import base64
+import hashlib
+from typing import Optional
+
+
+def sha256Hash(str: str, encoding: Optional[str] = None) -> str:
+	digest = hashlib.sha256(str.encode('utf-8')).digest()
+	enc = encoding or 'hex'
+
+	if enc == 'hex':
+		return digest.hex()
+	if enc == 'base64':
+		return base64.b64encode(digest).decode('ascii')
+	if enc == 'base64url':
+		return base64.urlsafe_b64encode(digest).decode('ascii').rstrip('=')
+	if enc == 'binary':
+		return digest.decode('latin-1')
+
+	raise ValueError(f'Unsupported encoding: {encoding}')

qsu/crypto/sha512Hash.py

@@ -0,0 +1,19 @@
+import base64
+import hashlib
+from typing import Optional
+
+
+def sha512Hash(str: str, encoding: Optional[str] = None) -> str:
+	digest = hashlib.sha512(str.encode('utf-8')).digest()
+	enc = encoding or 'hex'
+
+	if enc == 'hex':
+		return digest.hex()
+	if enc == 'base64':
+		return base64.b64encode(digest).decode('ascii')
+	if enc == 'base64url':
+		return base64.urlsafe_b64encode(digest).decode('ascii').rstrip('=')
+	if enc == 'binary':
+		return digest.decode('latin-1')
+
+	raise ValueError(f'Unsupported encoding: {encoding}')

qsu/date/__init__.py

@@ -0,0 +1,13 @@
+from .createDateListFromRange import createDateListFromRange
+from .dateToYYYYMMDD import dateToYYYYMMDD
+from .dayDiff import dayDiff
+from .isValidDate import isValidDate
+from .today import today
+
+__all__ = [
+	'createDateListFromRange',
+	'dateToYYYYMMDD',
+	'dayDiff',
+	'isValidDate',
+	'today',
+]

qsu/date/createDateListFromRange.py

@@ -0,0 +1,55 @@
+import math
+import re
+from datetime import datetime
+
+from .dateToYYYYMMDD import dateToYYYYMMDD
+from .isValidDate import isValidDate
+
+_YEAR_END_RE = re.compile(r'[0-9]{4}-12-31')
+
+
+def createDateListFromRange(startDate: datetime, endDate: datetime):
+	if not isValidDate(dateToYYYYMMDD(startDate)) or not isValidDate(
+		dateToYYYYMMDD(endDate)
+	):
+		raise ValueError('Either the start date or end date is an invalid date.')
+
+	date_diff = math.floor((endDate.timestamp() - startDate.timestamp()) / 86400)
+
+	if date_diff < 0:
+		raise ValueError('The start date is more recent than the end date.')
+
+	end_date_str = dateToYYYYMMDD(endDate)
+	all_date = []
+	current_year = startDate.year
+	current_month = startDate.month
+	current_day = startDate.day
+	current_date_str = ''
+
+	def create_new_date_str(year: int, month: int, day: int) -> str:
+		m = f'0{month}' if month < 10 else f'{month}'
+		d = f'0{day}' if day < 10 else f'{day}'
+		return f'{year}-{m}-{d}'
+
+	while end_date_str != current_date_str:
+		if _YEAR_END_RE.search(current_date_str):
+			current_year += 1
+			current_month = 1
+			current_day = 1
+
+		current_new_date_str = create_new_date_str(
+			current_year, current_month, current_day
+		)
+
+		if isValidDate(current_new_date_str):
+			current_day += 1
+			all_date.append(current_new_date_str)
+			current_date_str = current_new_date_str
+		else:
+			current_month += 1
+			current_day = 1
+			current_date_str = create_new_date_str(
+				current_year, current_month, current_day
+			)
+
+	return all_date

qsu/date/dateToYYYYMMDD.py

@@ -0,0 +1,20 @@
+from datetime import date as _date
+from datetime import datetime
+
+
+def dateToYYYYMMDD(date, separator: str = '-') -> str:
+	if isinstance(date, datetime):
+		year = date.year
+		month = date.month
+		day = date.day
+	elif isinstance(date, _date):
+		year = date.year
+		month = date.month
+		day = date.day
+	else:
+		raise TypeError('date must be a datetime or date instance')
+
+	month_str = f'0{month}' if month < 10 else f'{month}'
+	day_str = f'0{day}' if day < 10 else f'{day}'
+
+	return f'{year}{separator}{month_str}{separator}{day_str}'

qsu/date/dayDiff.py

@@ -0,0 +1,10 @@
+import math
+from datetime import datetime
+
+
+def dayDiff(date1: datetime, date2: datetime = None) -> int:
+	date2c = date2 if date2 is not None else datetime.now()
+
+	diff_ms = abs(date2c.timestamp() - date1.timestamp()) * 1000
+
+	return math.ceil(diff_ms / (1000 * 3600 * 24))

qsu/date/isValidDate.py

@@ -0,0 +1,27 @@
+import re
+
+_FORMAT_RE = re.compile(r'^[0-9]{4}-[0-9]{2}-[0-9]{2}$')
+
+# Support range: 1600-01-01 ~ 9999/12/31
+_VALID_RE = re.compile(
+	r'^(?=\d)(?:(?:31(?!.(?:0?[2469]|11))|(?:30|29)(?!.0?2)|29(?=.0?2.(?:(?:1[6-9]|[2-9]\d)?'
+	r'(?:0[48]|[2468][048]|[13579][26])|(?:16|[2468][048]|[3579][26])00)(?:\x20|$))|'
+	r'(?:2[0-8]|1\d|0?[1-9]))([-./])(?:1[012]|0?[1-9])\1(?:1[6-9]|[2-9]\d)?\d\d'
+	r'(?:(?=\x20\d)\x20|$))?(((0?[1-9]|1[012])(:[0-5]\d){0,2}(\x20[AP]M))|'
+	r'([01]\d|2[0-3])(:[0-5]\d){1,2})?$'
+)
+
+
+def isValidDate(dateYYYYMMDD: str) -> bool:
+	if not _FORMAT_RE.match(dateYYYYMMDD):
+		raise ValueError("The date format must be 'YYYY-MM-DD'")
+
+	converted_date = dateYYYYMMDD.split('-')
+
+	candidate = (
+		f'{int(converted_date[2], 10)}-'
+		f'{int(converted_date[1], 10)}-'
+		f'{int(converted_date[0], 10)}'
+	)
+
+	return bool(_VALID_RE.match(candidate))

qsu/date/today.py

@@ -0,0 +1,19 @@
+from datetime import datetime
+
+
+def today(separator: str = '-', yearFirst: bool = True) -> str:
+	date = datetime.now()
+	month = date.month
+	day = date.day
+
+	date_arr = [
+		f"{'0' if month < 10 else ''}{month}",
+		f"{'0' if day < 10 else ''}{day}",
+	]
+
+	if yearFirst:
+		date_arr.insert(0, str(date.year))
+	else:
+		date_arr.append(str(date.year))
+
+	return separator.join(date_arr)