├── .github └── workflows │ └── publish.yml ├── .gitignore ├── LICENSE ├── README.md ├── pyxivapi ├── __init__.py ├── client.py ├── decorators.py ├── exceptions.py └── models.py ├── requirements.txt └── setup.py /.github/workflows/publish.yml: -------------------------------------------------------------------------------- 1 | name: Publish to PyPI 2 | 3 | on: 4 | release: 5 | types: [created] 6 | 7 | jobs: 8 | deploy: 9 | runs-on: ubuntu-latest 10 | steps: 11 | - uses: actions/checkout@v1 12 | - name: Set up Python 13 | uses: actions/setup-python@v1 14 | with: 15 | python-version: '3.x' 16 | - name: Install dependencies 17 | run: | 18 | python -m pip install --upgrade pip 19 | pip install setuptools wheel twine 20 | - name: Build and publish 21 | env: 22 | TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }} 23 | TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }} 24 | run: | 25 | python setup.py sdist bdist_wheel 26 | twine upload dist/* 27 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | 6 | # C extensions 7 | *.so 8 | 9 | # Distribution / packaging 10 | .Python 11 | build/ 12 | develop-eggs/ 13 | dist/ 14 | downloads/ 15 | eggs/ 16 | .eggs/ 17 | lib/ 18 | lib64/ 19 | parts/ 20 | sdist/ 21 | var/ 22 | wheels/ 23 | *.egg-info/ 24 | .installed.cfg 25 | *.egg 26 | MANIFEST 27 | 28 | # PyInstaller 29 | # Usually these files are written by a python script from a template 30 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 31 | *.manifest 32 | *.spec 33 | 34 | # Installer logs 35 | pip-log.txt 36 | pip-delete-this-directory.txt 37 | 38 | # Unit test / coverage reports 39 | htmlcov/ 40 | .tox/ 41 | .coverage 42 | .coverage.* 43 | .cache 44 | nosetests.xml 45 | coverage.xml 46 | *.cover 47 | .hypothesis/ 48 | .pytest_cache/ 49 | 50 | # Translations 51 | *.mo 52 | *.pot 53 | 54 | # Django stuff: 55 | *.log 56 | local_settings.py 57 | db.sqlite3 58 | 59 | # Flask stuff: 60 | instance/ 61 | .webassets-cache 62 | 63 | # Scrapy stuff: 64 | .scrapy 65 | 66 | # Sphinx documentation 67 | docs/_build/ 68 | 69 | # PyBuilder 70 | target/ 71 | 72 | # Jupyter Notebook 73 | .ipynb_checkpoints 74 | 75 | # pyenv 76 | .python-version 77 | 78 | # celery beat schedule file 79 | celerybeat-schedule 80 | 81 | # SageMath parsed files 82 | *.sage.py 83 | 84 | # Environments 85 | .env 86 | .venv 87 | env/ 88 | venv/ 89 | ENV/ 90 | env.bak/ 91 | venv.bak/ 92 | 93 | # Spyder project settings 94 | .spyderproject 95 | .spyproject 96 | 97 | # Rope project settings 98 | .ropeproject 99 | 100 | # mkdocs documentation 101 | /site 102 | 103 | # mypy 104 | .mypy_cache/ 105 | .DS_Store 106 | example.py 107 | 108 | # pycharm 109 | .idea 110 | 111 | .vscode 112 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 Lethys 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # pyxivapi 2 | An asynchronous Python client for XIVAPI 3 | 4 | [![Codacy Badge](https://api.codacy.com/project/badge/Grade/741f410aefad4fa69cc6925ff5d83b4b)](https://www.codacy.com/manual/Yandawl/xivapi-py?utm_source=github.com&utm_medium=referral&utm_content=xivapi/xivapi-py&utm_campaign=Badge_Grade) 5 | [![PyPI version](https://badge.fury.io/py/pyxivapi.svg)](https://badge.fury.io/py/pyxivapi) 6 | [![Python 3.6](https://img.shields.io/badge/python-3.6-green.svg)](https://www.python.org/downloads/release/python-360/) 7 | 8 | ## Requirements 9 | ```python 10 | python>=3.6.0 11 | asyncio 12 | aiohttp 13 | ``` 14 | 15 | ## Installation 16 | ```python 17 | pip install pyxivapi 18 | ``` 19 | 20 | ## Supported API end points 21 | 22 | * /character/search 23 | * /character/id 24 | * /freecompany/search 25 | * /freecompany/id 26 | * /linkshell/search 27 | * /linkshell/id 28 | * /pvpteam/search 29 | * /pvpteam/id 30 | * /index/search (e.g. recipe, item, action, pvpaction, mount, e.t.c.) 31 | * /index/id 32 | * /lore/search 33 | * /lodestone/worldstatus 34 | 35 | ## Documentation 36 | 37 | 38 | ## Example 39 | ```python 40 | import asyncio 41 | import logging 42 | 43 | import aiohttp 44 | import pyxivapi 45 | from pyxivapi.models import Filter, Sort 46 | 47 | 48 | async def fetch_example_results(): 49 | client = pyxivapi.XIVAPIClient(api_key="your_key_here") 50 | 51 | # Search Lodestone for a character 52 | character = await client.character_search( 53 | world="odin", 54 | forename="lethys", 55 | surname="lightpaw" 56 | ) 57 | 58 | # Get a character by Lodestone ID with extended data & include their Free Company information, if it has been synced. 59 | character = await client.character_by_id( 60 | lodestone_id=8255311, 61 | extended=True, 62 | include_freecompany=True 63 | ) 64 | 65 | # Search Lodestone for a free company 66 | freecompany = await client.freecompany_search( 67 | world="gilgamesh", 68 | name="Elysium" 69 | ) 70 | 71 | # Item search with paging 72 | item = await client.index_search( 73 | name="Eden", 74 | indexes=["Item"], 75 | columns=["ID", "Name"], 76 | filters=[ 77 | Filter("LevelItem", "gt", 520) 78 | ], 79 | sort=Sort("LevelItem", False), 80 | page=0, 81 | per_page=10 82 | ) 83 | 84 | # Fuzzy search XIVAPI game data for a recipe by name. Results will be in English. 85 | recipe = await client.index_search( 86 | name="Crimson Cider", 87 | indexes=["Recipe"], 88 | columns=["ID", "Name", "Icon", "ItemResult.Description"] 89 | ) 90 | 91 | # Fuzzy search XIVAPI game data for a recipe by name. Results will be in French. 92 | recipe = await client.index_search( 93 | name="Cidre carmin", 94 | indexes=["Recipe"], 95 | columns=["ID", "Name", "Icon", "ItemResult.Description"], 96 | language="fr" 97 | ) 98 | 99 | # Get an item by its ID (Omega Rod) and return the data in German 100 | item = await client.index_by_id( 101 | index="Item", 102 | content_id=23575, 103 | columns=["ID", "Name", "Icon", "ItemUICategory.Name"], 104 | language="de" 105 | ) 106 | 107 | filters = [ 108 | Filter("ClassJobLevel", "gte", 0) 109 | ] 110 | 111 | # Get non-npc actions matching a given term (Defiance) 112 | action = await client.index_search( 113 | name="Defiance", 114 | indexes=["Action", "PvPAction", "CraftAction"], 115 | columns=["ID", "Name", "Icon", "Description", "ClassJobCategory.Name", "ClassJobLevel", "ActionCategory.Name"], 116 | filters=filters, 117 | string_algo="match" 118 | ) 119 | 120 | # Search ingame data for matches against a given query. Includes item, minion, mount & achievement descriptions, quest dialog & more. 121 | lore = await client.lore_search( 122 | query="Shiva", 123 | language="fr" 124 | ) 125 | 126 | # Search for an item using specific filters 127 | filters = [ 128 | Filter("LevelItem", "gte", 100) 129 | ] 130 | 131 | sort = Sort("LevelItem", True) 132 | 133 | item = await client.index_search( 134 | name="Omega Rod", 135 | indexes=["Item"], 136 | columns=["ID", "Name", "Icon", "Description", "LevelItem"], 137 | filters=filters, 138 | sort=sort, 139 | language="de" 140 | ) 141 | 142 | await client.session.close() 143 | 144 | 145 | if __name__ == '__main__': 146 | logging.basicConfig(level=logging.INFO, format='%(message)s', datefmt='%H:%M') 147 | loop = asyncio.get_event_loop() 148 | loop.run_until_complete(fetch_example_results()) 149 | 150 | ``` 151 | -------------------------------------------------------------------------------- /pyxivapi/__init__.py: -------------------------------------------------------------------------------- 1 | __title__ = 'pyxivapi' 2 | __author__ = 'Lethys' 3 | __license__ = 'MIT' 4 | __copyright__ = 'Copyright 2019 (c) Lethys' 5 | __version__ = '0.5.1' 6 | 7 | from .client import XIVAPIClient 8 | from .exceptions import ( 9 | XIVAPIForbidden, 10 | XIVAPIBadRequest, 11 | XIVAPINotFound, 12 | XIVAPIServiceUnavailable, 13 | XIVAPIInvalidLanguage, 14 | XIVAPIInvalidIndex, 15 | XIVAPIInvalidColumns, 16 | XIVAPIInvalidFilter, 17 | XIVAPIInvalidWorlds, 18 | XIVAPIInvalidDatacenter, 19 | XIVAPIError, 20 | XIVAPIInvalidAlgo 21 | ) 22 | -------------------------------------------------------------------------------- /pyxivapi/client.py: -------------------------------------------------------------------------------- 1 | import logging 2 | from typing import List, Optional 3 | 4 | from aiohttp import ClientSession 5 | 6 | from .exceptions import ( 7 | XIVAPIBadRequest, XIVAPIForbidden, XIVAPINotFound, XIVAPIServiceUnavailable, 8 | XIVAPIInvalidLanguage, XIVAPIError, XIVAPIInvalidIndex, XIVAPIInvalidColumns, 9 | XIVAPIInvalidAlgo 10 | ) 11 | from .decorators import timed 12 | from .models import Filter, Sort 13 | 14 | __log__ = logging.getLogger(__name__) 15 | 16 | 17 | class XIVAPIClient: 18 | """ 19 | Asynchronous client for accessing XIVAPI's endpoints. 20 | Parameters 21 | ------------ 22 | api_key: str 23 | The API key used for identifying your application with XIVAPI.com. 24 | session: Optional[ClientSession] 25 | Optionally include your aiohttp session 26 | """ 27 | base_url = "https://xivapi.com" 28 | languages = ["en", "fr", "de", "ja"] 29 | 30 | def __init__(self, api_key: str, session: Optional[ClientSession] = None) -> None: 31 | self.api_key = api_key 32 | self._session = session 33 | 34 | self.base_url = "https://xivapi.com" 35 | self.languages = ["en", "fr", "de", "ja"] 36 | self.string_algos = [ 37 | "custom", "wildcard", "wildcard_plus", "fuzzy", "term", "prefix", "match", "match_phrase", 38 | "match_phrase_prefix", "multi_match", "query_string" 39 | ] 40 | 41 | @property 42 | def session(self) -> ClientSession: 43 | if self._session is None or self._session.closed: 44 | self._session = ClientSession() 45 | return self._session 46 | 47 | @timed 48 | async def character_search(self, world, forename, surname, page=1): 49 | """|coro| 50 | Search for character data directly from the Lodestone. 51 | Parameters 52 | ------------ 53 | world: str 54 | The world that the character is attributed to. 55 | forename: str 56 | The character's forename. 57 | surname: str 58 | The character's surname. 59 | Optional[page: int] 60 | The page of results to return. Defaults to 1. 61 | """ 62 | url = f'{self.base_url}/character/search?name={forename}%20{surname}&server={world}&page={page}&private_key={self.api_key}' 63 | async with self.session.get(url) as response: 64 | return await self.process_response(response) 65 | 66 | @timed 67 | async def character_by_id(self, lodestone_id: int, extended=False, include_achievements=False, include_minions_mounts=False, include_classjobs=False, include_friendslist=False, include_freecompany=False, include_freecompany_members=False, include_pvpteam=False, language="en"): 68 | """|coro| 69 | Request character data from XIVAPI.com 70 | Please see XIVAPI documentation for more information about character sync state https://xivapi.com/docs/Character#character 71 | Parameters 72 | ------------ 73 | lodestone_id: int 74 | The character's Lodestone ID. 75 | """ 76 | 77 | params = { 78 | "private_key": self.api_key, 79 | "language": language 80 | } 81 | 82 | if language.lower() not in self.languages: 83 | raise XIVAPIInvalidLanguage(f'"{language}" is not a valid language code for XIVAPI.') 84 | 85 | if extended is True: 86 | params["extended"] = 1 87 | 88 | data = [] 89 | if include_achievements is True: 90 | data.append("AC") 91 | 92 | if include_minions_mounts is True: 93 | data.append("MIMO") 94 | 95 | if include_friendslist is True: 96 | data.append("FR") 97 | 98 | if include_classjobs is True: 99 | data.append("CJ") 100 | 101 | if include_freecompany is True: 102 | data.append("FC") 103 | 104 | if include_freecompany_members is True: 105 | data.append("FCM") 106 | 107 | if include_pvpteam is True: 108 | data.append("PVP") 109 | 110 | if len(data) > 0: 111 | params["data"] = ",".join(data) 112 | 113 | url = f'{self.base_url}/character/{lodestone_id}' 114 | async with self.session.get(url, params=params) as response: 115 | return await self.process_response(response) 116 | 117 | @timed 118 | async def freecompany_search(self, world, name, page=1): 119 | """|coro| 120 | Search for Free Company data directly from the Lodestone. 121 | Parameters 122 | ------------ 123 | world: str 124 | The world that the Free Company is attributed to. 125 | name: str 126 | The Free Company's name. 127 | Optional[page: int] 128 | The page of results to return. Defaults to 1. 129 | """ 130 | url = f'{self.base_url}/freecompany/search?name={name}&server={world}&page={page}&private_key={self.api_key}' 131 | async with self.session.get(url) as response: 132 | return await self.process_response(response) 133 | 134 | @timed 135 | async def freecompany_by_id(self, lodestone_id: int, extended=False, include_freecompany_members=False): 136 | """|coro| 137 | Request Free Company data from XIVAPI.com by Lodestone ID 138 | Please see XIVAPI documentation for more information about Free Company info at https://xivapi.com/docs/Free-Company#profile 139 | Parameters 140 | ------------ 141 | lodestone_id: int 142 | The Free Company's Lodestone ID. 143 | """ 144 | 145 | params = { 146 | "private_key": self.api_key 147 | } 148 | 149 | if extended is True: 150 | params["extended"] = 1 151 | 152 | data = [] 153 | if include_freecompany_members is True: 154 | data.append("FCM") 155 | 156 | if len(data) > 0: 157 | params["data"] = ",".join(data) 158 | 159 | url = f'{self.base_url}/freecompany/{lodestone_id}' 160 | async with self.session.get(url, params=params) as response: 161 | return await self.process_response(response) 162 | 163 | @timed 164 | async def linkshell_search(self, world, name, page=1): 165 | """|coro| 166 | Search for Linkshell data directly from the Lodestone. 167 | Parameters 168 | ------------ 169 | world: str 170 | The world that the Linkshell is attributed to. 171 | name: str 172 | The Linkshell's name. 173 | Optional[page: int] 174 | The page of results to return. Defaults to 1. 175 | """ 176 | url = f'{self.base_url}/linkshell/search?name={name}&server={world}&page={page}&private_key={self.api_key}' 177 | async with self.session.get(url) as response: 178 | return await self.process_response(response) 179 | 180 | @timed 181 | async def linkshell_by_id(self, lodestone_id: int): 182 | """|coro| 183 | Request Linkshell data from XIVAPI.com by Lodestone ID 184 | Parameters 185 | ------------ 186 | lodestone_id: int 187 | The Linkshell's Lodestone ID. 188 | """ 189 | url = f'{self.base_url}/linkshell/{lodestone_id}?private_key={self.api_key}' 190 | async with self.session.get(url) as response: 191 | return await self.process_response(response) 192 | 193 | @timed 194 | async def pvpteam_search(self, world, name, page=1): 195 | """|coro| 196 | Search for PvPTeam data directly from the Lodestone. 197 | Parameters 198 | ------------ 199 | world: str 200 | The world that the PvPTeam is attributed to. 201 | name: str 202 | The PvPTeam's name. 203 | Optional[page: int] 204 | The page of results to return. Defaults to 1. 205 | """ 206 | url = f'{self.base_url}/pvpteam/search?name={name}&server={world}&page={page}&private_key={self.api_key}' 207 | async with self.session.get(url) as response: 208 | return await self.process_response(response) 209 | 210 | @timed 211 | async def pvpteam_by_id(self, lodestone_id): 212 | """|coro| 213 | Request PvPTeam data from XIVAPI.com by Lodestone ID 214 | Parameters 215 | ------------ 216 | lodestone_id: str 217 | The PvPTeam's Lodestone ID. 218 | """ 219 | url = f'{self.base_url}/pvpteam/{lodestone_id}?private_key={self.api_key}' 220 | async with self.session.get(url) as response: 221 | return await self.process_response(response) 222 | 223 | @timed 224 | async def index_search(self, name, indexes=(), columns=(), filters: List[Filter] = (), sort: Sort = None, page=0, per_page=10, language="en", string_algo="match"): 225 | """|coro| 226 | Search for data from on specific indexes. 227 | Parameters 228 | ------------ 229 | name: str 230 | The name of the item to retrieve the recipe data for. 231 | indexes: list 232 | A named list of indexes to search XIVAPI. At least one must be specified. 233 | e.g. ["Recipe", "Item"] 234 | Optional[columns: list] 235 | A named list of columns to return in the response. ID, Name, Icon & ItemDescription will be returned by default. 236 | e.g. ["ID", "Name", "Icon"] 237 | Optional[filters: list] 238 | A list of type Filter. Filter must be initialised with Field, Comparison (e.g. lt, lte, gt, gte) and value. 239 | e.g. filters = [ Filter("LevelItem", "gte", 100) ] 240 | Optional[sort: Sort] 241 | The name of the column to sort on. 242 | Optional[page: int] 243 | The page of results to return. Defaults to 1. 244 | Optional[language: str] 245 | The two character length language code that indicates the language to return the response in. Defaults to English (en). 246 | Valid values are "en", "fr", "de" & "ja" 247 | Optional[string_algo: str] 248 | The search algorithm to use for string matching (default = "match") 249 | Valid values are "custom", "wildcard", "wildcard_plus", "fuzzy", "term", "prefix", "match", "match_phrase", 250 | "match_phrase_prefix", "multi_match", "query_string" 251 | """ 252 | 253 | if len(indexes) == 0: 254 | raise XIVAPIInvalidIndex("Please specify at least one index to search for, e.g. [\"Recipe\"]") 255 | 256 | if language.lower() not in self.languages: 257 | raise XIVAPIInvalidLanguage(f'"{language}" is not a valid language code for XIVAPI.') 258 | 259 | if len(columns) == 0: 260 | raise XIVAPIInvalidColumns("Please specify at least one column to return in the resulting data.") 261 | 262 | if string_algo not in self.string_algos: 263 | raise XIVAPIInvalidAlgo(f'"{string_algo}" is not a supported string_algo for XIVAPI') 264 | 265 | body = { 266 | "indexes": ",".join(list(set(indexes))), 267 | "columns": "ID", 268 | "body": { 269 | "query": { 270 | "bool": { 271 | "should": [{ 272 | string_algo: { 273 | "NameCombined_en": { 274 | "query": name, 275 | "fuzziness": "AUTO", 276 | "prefix_length": 1, 277 | "max_expansions": 50 278 | } 279 | } 280 | }, { 281 | string_algo: { 282 | "NameCombined_de": { 283 | "query": name, 284 | "fuzziness": "AUTO", 285 | "prefix_length": 1, 286 | "max_expansions": 50 287 | } 288 | } 289 | }, { 290 | string_algo: { 291 | "NameCombined_fr": { 292 | "query": name, 293 | "fuzziness": "AUTO", 294 | "prefix_length": 1, 295 | "max_expansions": 50 296 | } 297 | } 298 | }, { 299 | string_algo: { 300 | "NameCombined_ja": { 301 | "query": name, 302 | "fuzziness": "AUTO", 303 | "prefix_length": 1, 304 | "max_expansions": 50 305 | } 306 | } 307 | }] 308 | } 309 | }, 310 | "from": page, 311 | "size": per_page 312 | } 313 | } 314 | 315 | if len(columns) > 0: 316 | body["columns"] = ",".join(list(set(columns))) 317 | 318 | if len(filters) > 0: 319 | filts = [] 320 | for f in filters: 321 | filts.append({ 322 | "range": { 323 | f.Field: { 324 | f.Comparison: f.Value 325 | } 326 | } 327 | }) 328 | 329 | body["body"]["query"]["bool"]["filter"] = filts 330 | 331 | if sort: 332 | body["body"]["sort"] = [{ 333 | sort.Field: "asc" if sort.Ascending else "desc" 334 | }] 335 | 336 | url = f'{self.base_url}/search?language={language}&private_key={self.api_key}' 337 | async with self.session.post(url, json=body) as response: 338 | return await self.process_response(response) 339 | 340 | @timed 341 | async def index_by_id(self, index, content_id: int, columns=(), language="en"): 342 | """|coro| 343 | Request data from a given index by ID. 344 | Parameters 345 | ------------ 346 | index: str 347 | The index to which the content is attributed. 348 | content_id: int 349 | The ID of the content 350 | Optional[columns: list] 351 | A named list of columns to return in the response. ID, Name, Icon & ItemDescription will be returned by default. 352 | e.g. ["ID", "Name", "Icon"] 353 | Optional[language: str] 354 | The two character length language code that indicates the language to return the response in. Defaults to English (en). 355 | Valid values are "en", "fr", "de" & "ja" 356 | """ 357 | if index == "": 358 | raise XIVAPIInvalidIndex("Please specify an index to search on, e.g. \"Item\"") 359 | 360 | if len(columns) == 0: 361 | raise XIVAPIInvalidColumns("Please specify at least one column to return in the resulting data.") 362 | 363 | params = { 364 | "private_key": self.api_key, 365 | "language": language 366 | } 367 | 368 | if len(columns) > 0: 369 | params["columns"] = ",".join(list(set(columns))) 370 | 371 | url = f'{self.base_url}/{index}/{content_id}' 372 | async with self.session.get(url, params=params) as response: 373 | return await self.process_response(response) 374 | 375 | @timed 376 | async def lore_search(self, query, language="en"): 377 | """|coro| 378 | Search cutscene subtitles, quest dialog, item, achievement, mount & minion descriptions and more for any text that matches query. 379 | Parameters 380 | ------------ 381 | query: str 382 | The text to search game content for. 383 | Optional[language: str] 384 | The two character length language code that indicates the language to return the response in. Defaults to English (en). 385 | Valid values are "en", "fr", "de" & "ja" 386 | """ 387 | params = { 388 | "private_key": self.api_key, 389 | "language": language, 390 | "string": query 391 | } 392 | 393 | url = f'{self.base_url}/lore' 394 | async with self.session.get(url, params=params) as response: 395 | return await self.process_response(response) 396 | 397 | @timed 398 | async def lodestone_worldstatus(self): 399 | """|coro| 400 | Request world status post from the Lodestone. 401 | """ 402 | url = f'{self.base_url}/lodestone/worldstatus?private_key={self.api_key}' 403 | async with self.session.get(url) as response: 404 | return await self.process_response(response) 405 | 406 | async def process_response(self, response): 407 | __log__.info(f'{response.status} from {response.url}') 408 | 409 | if response.status == 200: 410 | return await response.json() 411 | 412 | if response.status == 400: 413 | raise XIVAPIBadRequest("Request was bad. Please check your parameters.") 414 | 415 | if response.status == 401: 416 | raise XIVAPIForbidden("Request was refused. Possibly due to an invalid API key.") 417 | 418 | if response.status == 404: 419 | raise XIVAPINotFound("Resource not found.") 420 | 421 | if response.status == 500: 422 | raise XIVAPIError("An internal server error has occured on XIVAPI.") 423 | 424 | if response.status == 503: 425 | raise XIVAPIServiceUnavailable("Service is unavailable. This could be because the Lodestone is under maintenance.") 426 | -------------------------------------------------------------------------------- /pyxivapi/decorators.py: -------------------------------------------------------------------------------- 1 | import logging 2 | from functools import wraps 3 | from time import time 4 | 5 | __log__ = logging.getLogger(__name__) 6 | 7 | 8 | def timed(func): 9 | """This decorator prints the execution time for the decorated function.""" 10 | @wraps(func) 11 | async def wrapper(*args, **kwargs): 12 | start = time() 13 | result = await func(*args, **kwargs) 14 | __log__.info("{} executed in {}s".format(func.__name__, round(time() - start, 2))) 15 | return result 16 | return wrapper 17 | -------------------------------------------------------------------------------- /pyxivapi/exceptions.py: -------------------------------------------------------------------------------- 1 | class XIVAPIForbidden(Exception): 2 | """ 3 | XIVAPI Forbidden Request error 4 | """ 5 | pass 6 | 7 | 8 | class XIVAPIBadRequest(Exception): 9 | """ 10 | XIVAPI Bad Request error 11 | """ 12 | pass 13 | 14 | 15 | class XIVAPINotFound(Exception): 16 | """ 17 | XIVAPI not found error 18 | """ 19 | pass 20 | 21 | 22 | class XIVAPIServiceUnavailable(Exception): 23 | """ 24 | XIVAPI service unavailable error 25 | """ 26 | pass 27 | 28 | 29 | class XIVAPIInvalidLanguage(Exception): 30 | """ 31 | XIVAPI invalid language error 32 | """ 33 | pass 34 | 35 | 36 | class XIVAPIInvalidIndex(Exception): 37 | """ 38 | XIVAPI invalid index error 39 | """ 40 | pass 41 | 42 | 43 | class XIVAPIInvalidColumns(Exception): 44 | """ 45 | XIVAPI invalid columns error 46 | """ 47 | pass 48 | 49 | 50 | class XIVAPIInvalidFilter(Exception): 51 | """ 52 | XIVAPI invalid filter error 53 | """ 54 | pass 55 | 56 | 57 | class XIVAPIInvalidWorlds(Exception): 58 | """ 59 | XIVAPI invalid world(s) error 60 | """ 61 | pass 62 | 63 | 64 | class XIVAPIInvalidDatacenter(Exception): 65 | """ 66 | XIVAPI invalid datacenter error 67 | """ 68 | pass 69 | 70 | 71 | class XIVAPIError(Exception): 72 | """ 73 | XIVAPI error 74 | """ 75 | pass 76 | 77 | 78 | class XIVAPIInvalidAlgo(Exception): 79 | """ 80 | Invalid String Algo 81 | """ 82 | pass 83 | -------------------------------------------------------------------------------- /pyxivapi/models.py: -------------------------------------------------------------------------------- 1 | from .exceptions import XIVAPIInvalidFilter 2 | 3 | 4 | class Filter: 5 | """ 6 | Model class for DQL filters 7 | """ 8 | 9 | comparisons = ["gt", "gte", "lt", "lte"] 10 | 11 | def __init__(self, field: str, comparison: str, value: int): 12 | comparison = comparison.lower() 13 | 14 | if comparison not in self.comparisons: 15 | raise XIVAPIInvalidFilter(f'"{comparison}" is not a valid DQL filter comparison.') 16 | 17 | self.Field = field 18 | self.Comparison = comparison 19 | self.Value = value 20 | 21 | 22 | class Sort: 23 | """ 24 | Model class for sort field 25 | """ 26 | 27 | def __init__(self, field: str, ascending: bool): 28 | self.Field = field 29 | self.Ascending = ascending 30 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | aiohttp 2 | asyncio -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | import re 2 | 3 | import setuptools 4 | 5 | with open('requirements.txt') as f: 6 | REQUIREMENTS = f.readlines() 7 | 8 | with open('README.md') as f: 9 | README = f.read() 10 | 11 | with open('pyxivapi/__init__.py') as f: 12 | VERSION = re.search(r'^__version__\s*=\s*[\'"]([^\'"]*)[\'"]', f.read(), re.MULTILINE).group(1) 13 | 14 | setuptools.setup( 15 | name='pyxivapi', 16 | author='Lethys', 17 | author_email='seraymericbot@gmail.com', 18 | url='https://github.com/xivapi/xivapi-py', 19 | version=VERSION, 20 | packages=['pyxivapi'], 21 | license='MIT', 22 | description='An asynchronous Python client for XIVAPI', 23 | long_description=README, 24 | long_description_content_type="text/markdown", 25 | keywords='ffxiv xivapi', 26 | include_package_data=True, 27 | install_requires=REQUIREMENTS, 28 | classifiers=[ 29 | 'License :: OSI Approved :: MIT License', 30 | 'Intended Audience :: Developers', 31 | 'Natural Language :: English', 32 | 'Operating System :: OS Independent', 33 | 'Programming Language :: Python :: 3.7', 34 | 'Programming Language :: Python :: 3.8', 35 | 'Topic :: Internet', 36 | 'Topic :: Software Development :: Libraries', 37 | 'Topic :: Software Development :: Libraries :: Python Modules', 38 | 'Topic :: Utilities', 39 | ] 40 | ) 41 | --------------------------------------------------------------------------------