diff --git a/README.md b/README.md index 936a15f..3e96af5 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Github stars - the TCGdex Python SDK is released under the MIT license. + Build Status Discord Link @@ -23,86 +23,149 @@ # TCGdex Python SDK -The TCGdex Python SDK provides a convenient access with the Open Source TCGdex API. +A fast, type-safe Python SDK for the TCGdex API. Query Pokémon Trading Card Game data easily. 🚀 -_The full API/SDK documentation is available at [API Documentation - TCGdex](https://www.tcgdex.dev)_ - -### Getting Started +```python +from tcgdexsdk import TCGdex -#### How To install +# Fetch a card in one line +card = await TCGdex().card.get("swsh3-136") +card = await TCGdex().card.getSync("swsh3-136") +print(f"Found: {card.name} ({card.localId}/{card.set.cardCount.total})") +``` -run the following command: +## ⚡️ Quick Install ```bash pip install tcgdex-sdk ``` -#### Getting Started +## 🚀 Features -**Example: Fetch a Card** +- **Type-Safe**: Full typing support for better IDE integration +- **Async/Await**: Built for modern Python applications and compatible with synchronous operations +- **Zero Config**: Works out of the box +- **Multi-Language**: Support for English, French, German, Japanese, Chinese, [and more](https://github.com/tcgdex/cards-database/blob/master/interfaces.d.ts#L1-L5) +- **Rich Data**: Access cards, sets, series, rarities, and more +- **Lightweight**: Minimal dependencies (only [dacite](https://github.com/konradhalas/dacite)) + +## 🎯 Quick Examples + +### Find Cards by Various Criteria ```python -from tcgdexsdk import TCGdex +sdk = TCGdex("en") -tcgdex = TCGdex("en") # You can also use `Language.EN` TCGdex(Language.EN) -res = await tcgdex.card.get("swsh1-136") +# Get the cards made by the illustrator +cards = await sdk.illustrator.get("5ban Graphics") +cards = await sdk.illustrator.getSync("5ban Graphics") + +# Get the data about the Sword & Shield serie by ID +series = await sdk.serie.get("swsh") +series = await sdk.serie.getSync("swsh") + +# Get all cards with 110 HP +hp_cards = await sdk.hp.get("110") +hp_cards = await sdk.hp.getSync("110") + +# List all available rarities +rarities = await sdk.rarity.list() +rarities = await sdk.rarity.listSync() + +# List all cards with the name being "Furret" +rarities = await sdk.card.list(Query().equal("name", "Furret")) +rarities = await sdk.card.listSync(Query().equal("name", "Furret")) ``` -**Other Examples** +### Working with Sets and Series ```python -# fetch a Set using the set's name or ID -await tcgdex.set.get('Darkness Ablaze') +# Get set details +darkness_ablaze = await sdk.set.get("Darkness Ablaze") +# darkness_ablaze = await sdk.set.getSync("Darkness Ablaze") +print(f"Set: {darkness_ablaze.name} ({darkness_ablaze.cardCount.total} cards)") + +# Get series info +swsh = await sdk.serie.get("swsh") +# swsh = await sdk.serie.getSync("swsh") +print(f"Series: {swsh.name} ({len(swsh.sets)} sets)") +``` -# Fetch a serie using the serie's name or ID -await tcgdex.serie.get('Sword & Shield') +## 🛠 Available Endpoints -# Fetch cards possible pokemon cards HP -await tcgdex.hp.list() +### Card Data +```python +sdk.card # Core card data +sdk.rarity # Card rarities +sdk.hp # HP values +sdk.illustrator # Card illustrators +``` -# Fetch Cards with the specific number of HP -await tcgdex.hp.get('110') +### Game Mechanics +```python +sdk.type # Pokémon types +sdk.energyType # Energy types +sdk.retreat # Retreat costs +sdk.stage # Evolution stages +``` -# Fetch cards possible illustrators -await tcgdex.illustrator.list() +### Card Details +```python +sdk.variant # Card variants +sdk.suffix # Card suffixes +sdk.regulationMark # Regulation marks +sdk.dexId # Pokédex IDs +``` -# Fetch Cards with the specific illustrator -await tcgdex.illustrator.get('tetsuya koizumi') +### Collections +```python +sdk.set # Card sets +sdk.serie # Card series ``` -**Other Endpoints** +## 🌐 Language Support + +```python +from tcgdexsdk import TCGdex, Language + +# Using string +sdk = TCGdex("en") # English +sdk = TCGdex("fr") # French + +# Using enum (type-safe) +sdk = TCGdex(Language.EN) +sdk = TCGdex(Language.FR) + +# After creating the instance you can change at any time the language +sdk.setLanguage(Language.FR) +# or +sdk.setLanguage("fr") +``` -Every endpoints below work just like the ones above -- a function `list` to get the list of elements -- a function `get` to get details on the element +_[full list of languages available here](https://github.com/tcgdex/cards-database/blob/master/interfaces.d.ts#L1-L5)_ -- `variant`: fetch by the variants -- `trainerType`: fetch trainer cards types -- `suffix`: fetch differents cards suffixes -- `stage`: fetch differents cards stages -- `regulationMark`: Fetch by the regulation mark (letter at the bottom of the card) -- `energyType`: Fetch different types of energies -- `dexId`: fetch pokemon Global Pokédex IDS -- `type`: fetch the cards using the Pokémon type(s) -- `retreat`: fetch the cards using the retreat count -- `rarity`: fetch the cards rarities -- `illustrator`: fetch all the cards illustrators -- `hp`: fetch the different cards possible HPs -- `category`: the different cards categories +__ +## 🤝 Contributing -## Contributing +We love contributions! Here's how: -See [CONTRIBUTING.md](https://github.com/tcgdex/python-sdk/blob/master/CONTRIBUTING.md) +1. 🍴 Fork it +2. 🌿 Create your feature branch (`git checkout -b feature/amazing`) +3. 🔧 Make your changes +4. 🚀 Push to the branch (`git push origin feature/amazing`) +5. 🎉 Open a PR -TL::DR +## 📘 Documentation -- Fork +- [Full API Documentation](https://www.tcgdex.dev) +- [Python SDK Guide](https://www.tcgdex.dev/sdks/python) -- Commit your changes +## 💬 Community & Support -- Pull Request on this Repository +- [Discord Server](https://discord.gg/peACSRMZ7V) - Get help and discuss features +- [GitHub Issues](https://github.com/tcgdex/python-sdk/issues) - Bug reports and feature requests -## License +## 📜 License -This project is licensed under the MIT License. A copy of the license is available at [LICENSE.md](https://github.com/tcgdex/python-sdk/blob/master/LICENSE.md) +MIT © [TCGdex](https://github.com/tcgdex) diff --git a/pyproject.toml b/pyproject.toml index 797972d..3494fa9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ name = "tcgdex-sdk" # version = "0.0.0" dynamic = ["version"] -description = "The TCGdex Python SDK provides a convenient access to the Open Source TCGdex API." +description = "A fast, type-safe Python SDK for the TCGdex API. Query Pokémon Trading Card Game data easily. 🚀" authors = [{ name = "HellLord77" }, { name = "Avior", email = "git@avior.me" }] dependencies = ["dacite<2.0.0,>=1.8.1"] requires-python = ">=3.8" @@ -26,12 +26,12 @@ classifiers = [ ] [project.urls] -homepage = "https://tcgdex.dev" +homepage = "https://tcgdex.dev/sdks/python" source = "https://github.com/tcgdex/python-sdk" download = "https://github.com/tcgdex/python-sdk/releases/latest" changelog = "https://github.com/tcgdex/python-sdk/releases/latest" releasenotes = "https://github.com/tcgdex/python-sdk/releases/latest" -documentation = "https://tcgdex.dev" +documentation = "https://tcgdex.dev/sdks/python" issues = "https://github.com/tcgdex/python-sdk/issues" funding = "https://github.com/sponsors/tcgdex"