Больше комментариев

user_api/call2user_api.py

@@ -54,16 +54,37 @@ async def call(api_url, data, pre=True, fix=True):
 # UserAPI
 #------------------------------------------------------------
 # Получение информации о токене
+# IN : username (str), user_token (str)
+# OUT: {'issue_date': str, 'logs': str} / 'Invalid username or token' (401) / 'Token not exist' (404) / General error (500)
 async def get_user_token_info(username, user_token):
 	data = {'username': username, 'user_token': user_token}
 	return await call('api/get_user_token_info/', data)
 
 # Получение пользователя (ник, айди ТГ, ДС и т.п.)
+# IN : username (str), user_token (str)
+# OUT: {
+#   "creator_id_type": str,
+#   "username": str,
+#   "mine_uuid": str,
+#   "tg_id": int,
+#   "balance": float,
+#   "tokens": "{}",
+#   "password": "HIDDEN",
+#   "creator_id": str,
+#   "mine_name": str,
+#   "ds_id": int,
+#   "frozen": "no"/"temporarily"/"forever",
+#   "last_activity": null,
+# } / 'Invalid username or token' (401) / 'User not found' (404) / General error (500)
 async def user_in_db(username, user_token):
 	data = {'username': username, 'user_token': user_token}
 	return await call('api/user_in_db/', data)
 
 # Перевод монет
+# IN : username (str), user_token (str), dst_username (str), amount (float)
+# OUT: 'OK' / 'Invalid username or token' (401) / 'No money' (400) / 'Too low' (400)
+# / 'User not found' (404) / 'Frozen temporarily' (401) / 'Frozen forever' (401)
+# / General error (500)
 async def transfer_coins(username, user_token,
 						 dst_username, amount):
 	data = {'username': username, 'user_token': user_token,
@@ -71,12 +92,26 @@ async def transfer_coins(username, user_token,
 	return await call('api/transfer_coins/', data)
 
 # Получение глобальной статистики
+# IN : username (str), user_token (str)
+# OUT: {
+#   "amount": float,
+#   "frozen_amount": int,
+#   "users": int,
+#   "frozen_users": int,
+#   "average": float,
+#   "median": float,
+#   "min": float,
+#   "max": float
+# } / 'Invalid username or token' (401) / General error (500)
 async def get_stats(username, user_token):
 	data = {'username': username, 'user_token': user_token}
 	return await call('api/get_stats/', data)
 
 # Создание счёта на оплату, чтобы проверить оплачен ли он
 # Использование в боте: /pay <ник> <сумма> <invoice_id>
+# IN : username (str), user_token (str), amount (float)
+# OUT: invoice_id (str) / 'Invalid username or token' (401) / 'Destination user not found' (401)
+# / General error (500)
 async def create_invoice(username, user_token, amount=None):
 	data = {'username': username, 'user_token': user_token}
 	if amount:
@@ -84,12 +119,20 @@ async def create_invoice(username, user_token, amount=None):
 	return await call('api/create_invoice/', data)
 
 # Удаление счёта на оплату по invoice_id
+# IN : username (str), user_token (str), invoice_id (str)
+# OUT: 'OK' / 'Invalid username or token' (401) / 'Invoice id not found' (404) / General error (500)
 async def delete_invoice(username, user_token, id):
 	data = {'username': username, 'user_token': user_token, 'id': id}
 	return await call('api/delete_invoice/', data)
 
-# Получение информации о счёте на оплату:
+# Получение информации о счёте на оплату
-# конечный получатель, сумма, статус (оплачен/нет: True/False)
+# IN : username (str), user_token (str), invoice_id (str)
+# OUT: {
+#   "id": str,
+#   "dst_username": str,
+#   "amount": null / float,
+#   "status": false/true
+# } / 'Invalid username or token' (401) / 'Invoice id not found' (404) / General error (500)
 async def get_invoice(username, user_token, id):
 	data = {'username': username, 'user_token': user_token, 'id': id}
 	return await call('api/get_invoice/', data)
@@ -100,10 +143,17 @@ async def get_invoice(username, user_token, id):
 # SystemAPI usage only
 #------------------------------------------------------------
 # Здесь вы ничего не используете, пропускайте
+
+# For SystemAPI ONLY
+# IN : token (str), user_token (str)
+# OUT: 'OK' / 'Invalid token' (401) / 'Token already exist' (409) / General error (500)
 async def register_user_token(token, user_token):
 	data = {'token': token, 'user_token': user_token}
 	return await call('api/register_user_token/', data)
 
+# For SystemAPI ONLY
+# IN : token (str), user_token (str)
+# OUT: 'OK' / 'Invalid token' (401) / 'Token not exist' (404) / General error (500)
 async def unregister_user_token(token, user_token):
 	data = {'token': token, 'user_token': user_token}
 	return await call('api/unregister_user_token/', data)

user_api/call2user_api_sync.py

@@ -53,16 +53,37 @@ def call(api_url, data, pre=True, fix=True):
 # UserAPI
 #------------------------------------------------------------
 # Получение информации о токене
+# IN : username (str), user_token (str)
+# OUT: {'issue_date': str, 'logs': str} / 'Invalid username or token' (401) / 'Token not exist' (404) / General error (500)
 def get_user_token_info(username, user_token):
 	data = {'username': username, 'user_token': user_token}
 	return call('api/get_user_token_info/', data)
 
 # Получение пользователя (ник, айди ТГ, ДС и т.п.)
+# IN : username (str), user_token (str)
+# OUT: {
+#   "creator_id_type": str,
+#   "username": str,
+#   "mine_uuid": str,
+#   "tg_id": int,
+#   "balance": float,
+#   "tokens": "{}",
+#   "password": "HIDDEN",
+#   "creator_id": str,
+#   "mine_name": str,
+#   "ds_id": int,
+#   "frozen": "no"/"temporarily"/"forever",
+#   "last_activity": null,
+# } / 'Invalid username or token' (401) / 'User not found' (404) / General error (500)
 def user_in_db(username, user_token):
 	data = {'username': username, 'user_token': user_token}
 	return call('api/user_in_db/', data)
 
 # Перевод монет
+# IN : username (str), user_token (str), dst_username (str), amount (float)
+# OUT: 'OK' / 'Invalid username or token' (401) / 'No money' (400) / 'Too low' (400)
+# / 'User not found' (404) / 'Frozen temporarily' (401) / 'Frozen forever' (401)
+# / General error (500)
 def transfer_coins(username, user_token,
 				   dst_username, amount):
 	data = {'username': username, 'user_token': user_token,
@@ -70,12 +91,26 @@ def transfer_coins(username, user_token,
 	return call('api/transfer_coins/', data)
 
 # Получение глобальной статистики
+# IN : username (str), user_token (str)
+# OUT: {
+#   "amount": float,
+#   "frozen_amount": int,
+#   "users": int,
+#   "frozen_users": int,
+#   "average": float,
+#   "median": float,
+#   "min": float,
+#   "max": float
+# } / 'Invalid username or token' (401) / General error (500)
 def get_stats(username, user_token):
 	data = {'username': username, 'user_token': user_token}
 	return call('api/get_stats/', data)
 
 # Создание счёта на оплату, чтобы проверить оплачен ли он
 # Использование в боте: /pay <ник> <сумма> <invoice_id>
+# IN : username (str), user_token (str), amount (float)
+# OUT: invoice_id (str) / 'Invalid username or token' (401) / 'Destination user not found' (401)
+# / General error (500)
 def create_invoice(username, user_token, amount=None):
 	data = {'username': username, 'user_token': user_token}
 	if amount:
@@ -83,12 +118,20 @@ def create_invoice(username, user_token, amount=None):
 	return call('api/create_invoice/', data)
 
 # Удаление счёта на оплату по invoice_id
+# IN : username (str), user_token (str), invoice_id (str)
+# OUT: 'OK' / 'Invalid username or token' (401) / 'Invoice id not found' (404) / General error (500)
 def delete_invoice(username, user_token, id):
 	data = {'username': username, 'user_token': user_token, 'id': id}
 	return call('api/delete_invoice/', data)
 
-# Получение информации о счёте на оплату:
+# Получение информации о счёте на оплату
-# конечный получатель, сумма, статус (оплачен/нет: True/False)
+# IN : username (str), user_token (str), invoice_id (str)
+# OUT: {
+#   "id": str,
+#   "dst_username": str,
+#   "amount": null / float,
+#   "status": false/true
+# } / 'Invalid username or token' (401) / 'Invoice id not found' (404) / General error (500)
 def get_invoice(username, user_token, id):
 	data = {'username': username, 'user_token': user_token, 'id': id}
 	return call('api/get_invoice/', data)

user_api/user_api.py

@@ -35,6 +35,9 @@ async def token_check(username, user_token):
 	else:
 		return False
 
+# For SystemAPI ONLY
+# IN : token (str), user_token (str)
+# OUT: 'OK' / 'Invalid token' (401) / 'Token already exist' (409) / General error (500)
 @app.post('/api/register_user_token/')
 async def register_user_token_api(
 	token: str = Body(),
@@ -56,6 +59,9 @@ async def register_user_token_api(
 		await session.rollback()
 		raise HTTPException(status_code=500, detail=str(e))
 
+# For SystemAPI ONLY
+# IN : token (str), user_token (str)
+# OUT: 'OK' / 'Invalid token' (401) / 'Token not exist' (404) / General error (500)
 @app.post('/api/unregister_user_token/')
 async def unregister_user_token_api(
 	token: str = Body(),
@@ -66,7 +72,7 @@ async def unregister_user_token_api(
 		raise HTTPException(status_code=401, detail='Invalid token')
 	user_token_db = await user_token_in_db_func(session, user_token)
 	if not user_token_db:
-		raise HTTPException(status_code=409, detail='Token not exist')
+		raise HTTPException(status_code=404, detail='Token not exist')
 	try:
 		await session.delete(user_token_db)
 		await session.commit()
@@ -75,6 +81,8 @@ async def unregister_user_token_api(
 		await session.rollback()
 		raise HTTPException(status_code=500, detail=str(e))
 
+# IN : username (str), user_token (str)
+# OUT: {'issue_date': str, 'logs': str} / 'Invalid username or token' (401) / 'Token not exist' (404) / General error (500)
 @app.post('/api/get_user_token_info/')
 async def get_user_token_info_api(
 	username: str | None = Body(None),
@@ -85,12 +93,27 @@ async def get_user_token_info_api(
 		raise HTTPException(status_code=401, detail='Invalid username or token')
 	user_token_db = await user_token_in_db_func(session, user_token)
 	if not user_token_db:
-		raise HTTPException(status_code=409, detail='Token not exist')
+		raise HTTPException(status_code=404, detail='Token not exist')
 	# Force data retrieval (DB can not load it properly, because it "lazy")
 	issue_date = await session.run_sync(lambda sess: user_token_db.issue_date)
 	logs = await session.run_sync(lambda sess: user_token_db.logs)
 	return {'issue_date': issue_date, 'logs': logs}
 
+# IN : username (str), user_token (str)
+# OUT: {
+#   "creator_id_type": str,
+#   "username": str,
+#   "mine_uuid": str,
+#   "tg_id": int,
+#   "balance": float,
+#   "tokens": "{}",
+#   "password": "HIDDEN",
+#   "creator_id": str,
+#   "mine_name": str,
+#   "ds_id": int,
+#   "frozen": "no"/"temporarily"/"forever",
+#   "last_activity": null,
+# } / 'Invalid username or token' (401) / 'User not found' (404) / General error (500)
 @app.post('/api/user_in_db/')
 async def user_in_db_api(
 	username: str | None = Body(None),
@@ -102,6 +125,10 @@ async def user_in_db_api(
 	await log(session, user_token, f'/user_in_db')
 	return await user_in_db(token=SYSTEM_API_TOKEN, username=username)
 
+# IN : username (str), user_token (str), dst_username (str), amount (float)
+# OUT: 'OK' / 'Invalid username or token' (401) / 'No money' (400) / 'Too low' (400)
+# / 'User not found' (404) / 'Frozen temporarily' (401) / 'Frozen forever' (401)
+# / General error (500)
 @app.post('/api/transfer_coins/')
 async def transfer_coins_api(
 	username: str = Body(),
@@ -116,6 +143,17 @@ async def transfer_coins_api(
 	return await transfer_coins(token=SYSTEM_API_TOKEN, src_username=username
 								, dst_username=dst_username, amount=amount)
 
+# IN : username (str), user_token (str)
+# OUT: {
+#   "amount": float,
+#   "frozen_amount": int,
+#   "users": int,
+#   "frozen_users": int,
+#   "average": float,
+#   "median": float,
+#   "min": float,
+#   "max": float
+# } / 'Invalid username or token' (401) / General error (500)
 @app.post('/api/get_stats/')
 async def get_stats_api(
 	username: str = Body(),
@@ -127,6 +165,9 @@ async def get_stats_api(
 	await log(session, user_token, f'/get_stats')
 	return await get_stats(token=SYSTEM_API_TOKEN)
 
+# IN : username (str), user_token (str), amount (float)
+# OUT: invoice_id (str) / 'Invalid username or token' (401) / 'Destination user not found' (401)
+# / General error (500)
 @app.post('/api/create_invoice/')
 async def create_invoice_api(
 	username: str = Body(),
@@ -139,29 +180,38 @@ async def create_invoice_api(
 	await log(session, user_token, f'/create_invoice: (amount: {amount})')
 	return await create_invoice(token=SYSTEM_API_TOKEN, dst_username=username, amount=amount)
 
+# IN : username (str), user_token (str), invoice_id (str)
+# OUT: 'OK' / 'Invalid username or token' (401) / 'Invoice id not found' (404) / General error (500)
 @app.post('/api/delete_invoice/')
 async def delete_invoice_api(
 	username: str = Body(),
 	user_token: str = Body(),
-	id: str = Body(),
+	invoice_id: str = Body(),
 	session: AsyncSession = Depends(get_session)
 ):
 	if not await token_check(username, user_token):
 		raise HTTPException(status_code=401, detail='Invalid username or token')
-	await log(session, user_token, f'/delete_invoice: (id: {id})')
+	await log(session, user_token, f'/delete_invoice: (id: {invoice_id})')
-	return await delete_invoice(token=SYSTEM_API_TOKEN, id=id)
+	return await delete_invoice(token=SYSTEM_API_TOKEN, id=invoice_id)
 
+# IN : username (str), user_token (str), invoice_id (str)
+# OUT: {
+#   "id": str,
+#   "dst_username": str,
+#   "amount": null / float,
+#   "status": false/true
+# } / 'Invalid username or token' (401) / 'Invoice id not found' (404) / General error (500)
 @app.post('/api/get_invoice/')
 async def get_invoice_api(
 	username: str = Body(),
 	user_token: str = Body(),
-	id: str = Body(),
+	invoice_id: str = Body(),
 	session: AsyncSession = Depends(get_session)
 ):
 	if not await token_check(username, user_token):
 		raise HTTPException(status_code=401, detail='Invalid username or token')
-	await log(session, user_token, f'/get_invoice: (id: {id})')
+	await log(session, user_token, f'/get_invoice: (id: {invoice_id})')
-	return await get_invoice(token=SYSTEM_API_TOKEN, id=id)
+	return await get_invoice(token=SYSTEM_API_TOKEN, id=invoice_id)
 
 #------------------------- END ------------------------------