From cc279a0fde57fcf97a91b5b3d88ae0803c302ce6 Mon Sep 17 00:00:00 2001 From: bohd4nx Date: Thu, 21 May 2026 17:17:49 +0300 Subject: [PATCH] docs: add examples to various API methods for better clarity --- docs/README.md | 6 ++++++ docs/client/ads/recharge-ads.md | 7 +++++++ docs/client/ads/topup-ton.md | 7 +++++++ docs/client/anonymous-numbers/get-login-code.md | 7 +++++++ docs/client/anonymous-numbers/terminate-sessions.md | 7 +++++++ docs/client/anonymous-numbers/toggle-login-codes.md | 6 ++++++ docs/client/marketplace/search-gifts.md | 12 ++++++++++++ docs/client/marketplace/search-numbers.md | 7 +++++++ docs/client/marketplace/search-usernames.md | 7 +++++++ docs/client/premium/giveaway.md | 7 +++++++ docs/client/premium/purchase.md | 7 +++++++ docs/client/stars/giveaway.md | 7 +++++++ docs/client/stars/purchase.md | 7 +++++++ 13 files changed, 94 insertions(+) diff --git a/docs/README.md b/docs/README.md index f1ee60c..6cad028 100644 --- a/docs/README.md +++ b/docs/README.md @@ -40,3 +40,9 @@ If you are integrating Fragment into a bot or backend, this docs set is meant to - [Result Models](reference/models.md) - [Literal Types](reference/literals.md) - [Troubleshooting](advanced/troubleshooting.md) + +## Live examples + +**Up-to-date runnable examples live in the main repository:** + +- https://github.com/bohd4nx/pyfragment/tree/master/examples diff --git a/docs/client/ads/recharge-ads.md b/docs/client/ads/recharge-ads.md index e86c07c..e604e4a 100644 --- a/docs/client/ads/recharge-ads.md +++ b/docs/client/ads/recharge-ads.md @@ -21,3 +21,10 @@ await client.recharge_ads( ## Return - `AdsRechargeResult(transaction_id, amount)` + +## Example + +```python +result: AdsRechargeResult = await client.recharge_ads("@mychannel", amount=50) +print(result.transaction_id) +``` diff --git a/docs/client/ads/topup-ton.md b/docs/client/ads/topup-ton.md index aebdfd3..657152f 100644 --- a/docs/client/ads/topup-ton.md +++ b/docs/client/ads/topup-ton.md @@ -23,3 +23,10 @@ await client.topup_ton( ## Return - `AdsTopupResult(transaction_id, username, amount)` + +## Example + +```python +result: AdsTopupResult = await client.topup_ton("@username", amount=10, show_sender=True) +print(result.transaction_id) +``` diff --git a/docs/client/anonymous-numbers/get-login-code.md b/docs/client/anonymous-numbers/get-login-code.md index 9e20770..6450ae6 100644 --- a/docs/client/anonymous-numbers/get-login-code.md +++ b/docs/client/anonymous-numbers/get-login-code.md @@ -17,3 +17,10 @@ await client.get_login_code(number: str) -> LoginCodeResult - `number` - `code` (`None` if no pending code) - `active_sessions` + +## Example + +```python +result: LoginCodeResult = await client.get_login_code("+1234567890") +print(result.code) +``` diff --git a/docs/client/anonymous-numbers/terminate-sessions.md b/docs/client/anonymous-numbers/terminate-sessions.md index a803e67..60deed4 100644 --- a/docs/client/anonymous-numbers/terminate-sessions.md +++ b/docs/client/anonymous-numbers/terminate-sessions.md @@ -16,3 +16,10 @@ await client.terminate_sessions(number: str) -> TerminateSessionsResult - `number` - `message` + +## Example + +```python +result: TerminateSessionsResult = await client.terminate_sessions("+1234567890") +print(result.message) +``` diff --git a/docs/client/anonymous-numbers/toggle-login-codes.md b/docs/client/anonymous-numbers/toggle-login-codes.md index 2ecba8e..3a385ec 100644 --- a/docs/client/anonymous-numbers/toggle-login-codes.md +++ b/docs/client/anonymous-numbers/toggle-login-codes.md @@ -16,3 +16,9 @@ await client.toggle_login_codes(number: str, can_receive: bool) -> None ## Return - `None` + +## Example + +```python +await client.toggle_login_codes("+1234567890", can_receive=False) +``` diff --git a/docs/client/marketplace/search-gifts.md b/docs/client/marketplace/search-gifts.md index 9e309d3..1d2da1c 100644 --- a/docs/client/marketplace/search-gifts.md +++ b/docs/client/marketplace/search-gifts.md @@ -73,3 +73,15 @@ In requests, each trait is sent as `attr[trait]` with a list of values. ## Pagination If `next_offset` is not `None`, pass it back as `offset` to load the next page. + +## Example + +```python +result: GiftsResult = await client.search_gifts( + query="", + collection="plushpepe", + sort="price_desc", + filter="auction", +) +print(len(result.items), result.next_offset) +``` diff --git a/docs/client/marketplace/search-numbers.md b/docs/client/marketplace/search-numbers.md index c5f902a..88d2c03 100644 --- a/docs/client/marketplace/search-numbers.md +++ b/docs/client/marketplace/search-numbers.md @@ -52,3 +52,10 @@ Common values accepted by Fragment: If `next_offset_id` is not `None`, pass it back as `offset_id` to load the next page. Keep requesting pages until `next_offset_id` becomes `None`. + +## Example + +```python +result: NumbersResult = await client.search_numbers("888", sort="price_asc", filter="sale") +print(len(result.items), result.next_offset_id) +``` diff --git a/docs/client/marketplace/search-usernames.md b/docs/client/marketplace/search-usernames.md index a34066b..e45459c 100644 --- a/docs/client/marketplace/search-usernames.md +++ b/docs/client/marketplace/search-usernames.md @@ -52,3 +52,10 @@ Common values accepted by Fragment: If `next_offset_id` is not `None`, pass it back as `offset_id` to load the next page. This is cursor pagination, so do not try to calculate offsets manually. + +## Example + +```python +result: UsernamesResult = await client.search_usernames("durov", sort="price_desc", filter="auction") +print(len(result.items), result.next_offset_id) +``` diff --git a/docs/client/premium/giveaway.md b/docs/client/premium/giveaway.md index ec67c0a..3c88c05 100644 --- a/docs/client/premium/giveaway.md +++ b/docs/client/premium/giveaway.md @@ -32,3 +32,10 @@ await client.giveaway_premium( - `UserNotFoundError` - `WalletError` - `VerificationError` + +## Example + +```python +result: PremiumGiveawayResult = await client.giveaway_premium("@channel", winners=100, months=3) +print(result.amount) +``` diff --git a/docs/client/premium/purchase.md b/docs/client/premium/purchase.md index 49ed3ee..2fdcdbd 100644 --- a/docs/client/premium/purchase.md +++ b/docs/client/premium/purchase.md @@ -32,3 +32,10 @@ await client.purchase_premium( - `UserNotFoundError` - `WalletError` - `VerificationError` + +## Example + +```python +result: PremiumResult = await client.purchase_premium("@username", months=6, payment_method="ton") +print(result.transaction_id) +``` diff --git a/docs/client/stars/giveaway.md b/docs/client/stars/giveaway.md index c3cea9a..5d783c0 100644 --- a/docs/client/stars/giveaway.md +++ b/docs/client/stars/giveaway.md @@ -32,3 +32,10 @@ await client.giveaway_stars( - `UserNotFoundError` - `WalletError` - `VerificationError` + +## Example + +```python +result: StarsGiveawayResult = await client.giveaway_stars("@channel", winners=3, amount=1000) +print(result.transaction_id) +``` diff --git a/docs/client/stars/purchase.md b/docs/client/stars/purchase.md index d8bd3d5..7a55435 100644 --- a/docs/client/stars/purchase.md +++ b/docs/client/stars/purchase.md @@ -32,3 +32,10 @@ await client.purchase_stars( - `UserNotFoundError`: target user not found - `WalletError`: insufficient balance or wallet-side issue - `VerificationError`: verification/KYC required for operation + +## Example + +```python +result: StarsResult = await client.purchase_stars("@username", amount=500, payment_method="ton") +print(result.amount) +```