Metadata-Version: 2.4
Name: xivlodestone
Version: 0.1.0a1
Summary: xivlodestone is a Python library that interacts with the FFXIV Lodestone website.
Project-URL: Homepage, https://github.com/RikuPy/xivlodestone
Project-URL: Issues, https://github.com/RikuPy/xivlodestone/issues
Author: RikuPy
License-Expression: MIT
License-File: LICENSE.md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.11.13
Requires-Dist: beautifulsoup4>=4.13.3
Requires-Dist: msgspec>=0.19.0
Description-Content-Type: text/markdown

# xivlodestone

xivlodestone is a Python library that interacts with the [Lodestone](https://na.finalfantasyxiv.com/lodestone/) website.

Its primary focus is to provide developers with a simple, easy-to-use interface for retrieving up-to-date character information.

It currently supports searching for and retrieving character and free company details. Additional features may be added in the future.

As this project is currently in alpha testing, it is not guaranteed to be stable or feature-complete. Breaking changes may occur anytime, and the API may change without notice.

## Installation

You can install this library using pip:
```shell
pip install xivlodestone
```

## Usage
You can use the `search_character` method to search for a character. With a correctly spelled character name and world, this is usually a single character.

Otherwise, you will get a list of characters that match the search criteria.
```python
import asyncio
from xivlodestone import LodestoneScraper

async def search_example():
    lodestone = LodestoneScraper()
    async for character in lodestone.search_characters("Yoshi'p Sampo", "Mandragora"):
        print(f"Found {character.name} from {character.world}")
        
    # Or if you need to pre-populate the results into a list
    characters = [c async for c in lodestone.search_characters("Yoshi'p Sampo", "Mandragora")]

asyncio.run(search_example())
```
By default, the library will only fetch a maximum of 50 (the first page of) results. 

You can set the `limit` parameter to a higher value to fetch more results or None to fetch the maximum number of results (up to 1,000).

Search results will only provide basic information about a character, such as their name, world, and avatar.

You can use the `get_character` method to fetch more details about the character.
```python
from xivlodestone import LodestoneScraper

async def get_character_example():
    lodestone = LodestoneScraper()
    characters = [c async for c in lodestone.search_characters("Yoshi'p Sampo", "Mandragora")]
    character = await lodestone.get_character(characters[0])  # Also accepts a character ID
    print(f"{character.name} from {character.world}")
    print(f"Birthday: {character.birthday}")
    print(f"Bio: {character.bio}")
    if character.free_company:
        print(f"Free Company: {character.free_company.name}")
```

A common use case for scraping a character's lodestone profile page is verifying a user's ownership. 

This is often done by asking the user to insert a temporary verification code into their character's bio section and then scraping their profile page to verify it.

With xivlodestone, this can be done with just a few lines of code:
```python
from xivlodestone import LodestoneScraper

async def verify_character_bio(character_id: int, verification_code: str):
    lodestone = LodestoneScraper()
    character = await lodestone.get_character(character_id)
    if verification_code in character.bio:
        ...
```
