Tibia.py

https://tibiapy.readthedocs.io/en/latest/
Admin
A Python library for parsing HTML content from Tibia.com into well-structured Python objects with...
Tokens:85,420
Snippets:347
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Tibia.py via pip

Source: https://tibiapy.readthedocs.io/en/latest/intro.html

Standard installation command for the library from PyPi.

```bash
python -m pip install tibia.py
```

--------------------------------

### Attribute Migration Setup

Source: https://tibiapy.readthedocs.io/en/latest/_modules/pydantic/main.html

Initializes the __getattr__ method using the migration utility.

```python
__getattr__ = getattr_migration(__name__)
```

--------------------------------

### Run the Tibia.py Docker container

Source: https://tibiapy.readthedocs.io/en/latest/intro.html

Start the container and map port 8000 to access the API documentation.

```bash
docker run \
    -p 8000:8000 \
    --rm -ti \
    galarzaa90/tibia.py

```

--------------------------------

### Install system dependencies for lxml

Source: https://tibiapy.readthedocs.io/en/latest/intro.html

Required on Linux systems to support lxml parsing dependencies.

```bash
sudo apt-get install libxml2-dev libxslt-dev python-dev
```

--------------------------------

### Define post-initialization logic

Source: https://tibiapy.readthedocs.io/en/latest/_modules/pydantic/main.html

Overrides model_post_init to perform validation or setup that requires the fully initialized model instance.

```python
def model_post_init(self, context: Any, /) -> None:
        """Override this method to perform additional initialization after `__init__` and `model_construct`.
        This is useful if you want to do some validation that requires the entire model to be initialized.
        """
```

--------------------------------

### model_post_init

Source: https://tibiapy.readthedocs.io/en/latest/_modules/pydantic/main.html

An initialization hook that can be overridden to perform additional validation or setup after the model has been initialized.

```APIDOC
## model_post_init

### Description
Override this method to perform additional initialization after `__init__` and `model_construct`. This is useful if you want to do some validation that requires the entire model to be initialized.

### Parameters
- **context** (Any) - Required - The context provided during initialization.
```

--------------------------------

### Initialize Client Class

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Constructor for the client, allowing custom event loops, sessions, or proxy configurations.

```python
def __init__(
        self,
        loop: asyncio.AbstractEventLoop = None,
        session: aiohttp.ClientSession = None,
        *,
        proxy_url: str = None,
):
    self.loop: asyncio.AbstractEventLoop = asyncio.get_event_loop() if loop is None else loop
    self._session_ready = asyncio.Event()
    self.proxy_url = proxy_url
    if session is not None:
        self.session: aiohttp.ClientSession = session
        self._session_ready.set()
    else:
        self.loop.create_task(self._initialize_session(proxy_url))
```

--------------------------------

### Initialize Session

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Internal method to set up the aiohttp session with appropriate headers and optional SOCKS proxy.

```python
async def _initialize_session(self, proxy_url: str = None):
    """Initialize the aiohttp session object."""
    headers = {
        "User-Agent": f"Tibia.py/{tibiapy.__version__} (+https://github.com/Galarzaa90/tibia.py)",
        "Accept-Encoding": "deflate, gzip",
    }
    connector = aiohttp_socks.SocksConnector.from_url(proxy_url) if proxy_url else None
    self.session: aiohttp.ClientSession = aiohttp.ClientSession(
        loop=self.loop,
        headers=headers,
        connector=connector,
    )
    self._session_ready.set()
```

--------------------------------

### Get Specific Spell URL

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/urls.html

Retrieves the direct URL for a specific spell using its identifier.

```python
def get_spell_url(identifier: str) -> str:
    """Get the URL to a spell in the Tibia.com spells section.

    Parameters
    ----------
    identifier: :class:`str`
        The identifier of the spell.

    Returns
    -------
    :class:`str`
        The URL to the spell.

    """
    return get_tibia_url("library", "spells", spell=identifier.lower())
```

--------------------------------

### Get Pydantic JSON Schema hook

Source: https://tibiapy.readthedocs.io/en/latest/_modules/pydantic/main.html

Hook for customizing the generation of a model's JSON schema.

```python
@classmethod
def __get_pydantic_json_schema__(
    cls,
    core_schema: CoreSchema,
    handler: GetJsonSchemaHandler,
    /,
) -> JsonSchemaValue:
    """Hook into generating the model's JSON schema.

    Args:
        core_schema: A `pydantic-core` CoreSchema.
            You can ignore this argument and call the handler with a new CoreSchema,
            wrap this CoreSchema (`{'type': 'nullable', 'schema': current_schema}`),
            or just call the handler with the original schema.
        handler: Call into Pydantic's internal JSON schema generation.
            This will raise a `pydantic.errors.PydanticInvalidForJsonSchema` if JSON schema
            generation fails.
            Since this gets called by `BaseModel.model_json_schema` you can override the
            `schema_generator` argument to that function to change JSON schema generation globally
            for a type.

    Returns:
        A JSON schema, as a Python object.
    """
    return handler(core_schema)
```

--------------------------------

### Implement ItemSummary Class

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/models/bazaar.html

Manages items in a character's inventory and depot.

```python
class ItemSummary(AuctionSummary[ItemEntry]):
    """Items in a character's inventory and depot."""

    def get_by_id(self, entry_id: int) -> Optional[ItemEntry]:
        """Get an item by its item id.

        Parameters
        ----------
        entry_id: :class:`int`
            The ID of the item.

        Returns
        -------
        :class:`ItemEntry`
            The item matching the id.

        """
        return next((e for e in self.entries if e.item_id == entry_id), None)
```

--------------------------------

### BaseModel Initialization

Source: https://tibiapy.readthedocs.io/en/latest/_modules/pydantic/main.html

The __init__ method handles parsing and validation of input data.

```python
def __init__(self, /, **data: Any) -> None:
    """Create a new model by parsing and validating input data from keyword arguments.

    Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be
    validated to form a valid model.

    `self` is explicitly positional-only to allow `self` as a field name.
    """
    # `__tracebackhide__` tells pytest and some other tools to omit this function from tracebacks
    __tracebackhide__ = True
    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
    if self is not validated_self:
        warnings.warn(
            'A custom validator is returning a value other than `self`.
' 
            "Returning anything other than `self` from a top level model validator isn't supported when validating via `__init__`.
" 
            'See the `model_validator` docs (https://docs.pydantic.dev/latest/concepts/validators/#model-validators) for more details.',
            stacklevel=2,
        )

# The following line sets a flag that we use to determine when `__init__` gets overridden by the user
__init__.__pydantic_base_init__ = True  # pyright: ignore[reportFunctionMemberAccess]
```

--------------------------------

### Get Pydantic Core Schema hook

Source: https://tibiapy.readthedocs.io/en/latest/_modules/pydantic/main.html

Internal method for generating the core schema, which triggers a deprecation warning if super() is called directly.

```python
@classmethod
def __get_pydantic_core_schema__(cls, source: type[BaseModel], handler: GetCoreSchemaHandler, /) -> CoreSchema:
    # This warning is only emitted when calling `super().__get_pydantic_core_schema__` from a model subclass.
    # In the generate schema logic, this method (`BaseModel.__get_pydantic_core_schema__`) is special cased to
    # *not* be called if not overridden.
    warnings.warn(
        'The `__get_pydantic_core_schema__` method of the `BaseModel` class is deprecated. If you are calling '
        '`super().__get_pydantic_core_schema__` when overriding the method on a Pydantic model, consider using '
        '`handler(source)` instead. However, note that overriding this method on models can lead to unexpected '
        'side effects.',
        PydanticDeprecatedSince211,
        stacklevel=2,
    )
    # Logic copied over from `GenerateSchema._model_schema`:
    schema = cls.__dict__.get('__pydantic_core_schema__')
    if schema is not None and not isinstance(schema, _mock_val_ser.MockCoreSchema):
        return cls.__pydantic_core_schema__

    return handler(source)
```

--------------------------------

### Fetch News Archive

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Retrieves news entries within a specified date range. Raises ValueError if the start date is after the end date.

```python
    async def fetch_news_archive(
            self,
            from_date: datetime.date,
            to_date: datetime.date = None,
            categories: set[NewsCategory] = None,
            types: set[NewsType] = None,
            *,
            test: bool = False,
    ) -> TibiaResponse[NewsArchive]:
        """Fetch news from the archive meeting the search criteria.

        .. versionchanged:: 5.0.0
            The data attribute of the response contains an instance of :class:`NewsArchive` instead.

        Parameters
        ----------
        from_date:
            The beginning date to search dates in.
        to_date:
            The end date to search dates in.
        categories:
            The allowed categories to show. If left blank, all categories will be searched.
        types:
            The allowed news types to show. if unused, all types will be searched.
        test:
            Whether to request the test website instead.

        Returns
        -------
        TibiaResponse[NewsArchive]
            The news meeting the search criteria.

        Raises
        ------
        :exc:`ValueError`:
            If ``begin_date`` is more recent than ``to_date``.
        Forbidden
            If a 403 Forbidden error was returned.
            This usually means that Tibia.com is rate-limiting the client because of too many requests.
        NetworkError
            If there's any connection errors during the request.

        """
        to_date = to_date or datetime.date.today()
        if from_date > to_date:
            raise ValueError("start_date can't be more recent than end_date")

        form_data = NewsArchiveParser.get_form_data(from_date, to_date, categories, types)
        response = await self._request("POST", get_news_archive_url(), form_data, test=test)
        return response.parse(NewsArchiveParser.from_content)
```

--------------------------------

### Fetch World Overview

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Retrieves the general world overview information.

```python
    async def fetch_world_overview(self, *, test: bool = False) -> TibiaResponse[WorldOverview]:
        """Fetch the world overview information from Tibia.com.

        Parameters
        ----------
        test:
            Whether to request the test website instead.

        Returns
        -------
        TibiaResponse[WorldOverview]
            A response containing the world overview information.

        Raises
        ------
        Forbidden
            If a 403 Forbidden error was returned.
            This usually means that Tibia.com is rate-limiting the client because of too many requests.
        NetworkError
            If there's any connection errors during the request.

        """
        response = await self._request("GET", get_world_overview_url(), test=test)
        return response.parse(WorldOverviewParser.from_content)
```

--------------------------------

### Generate a Static File URL

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/urls.html

Creates a URL pointing to a static asset hosted on static.tibia.com.

```python
>>> get_static_file_url("images", "global", "content", "newsicon_community_big.gif")
https://static.tibia.com/images/global/content/newsicon_community_big.gif
```

--------------------------------

### Get Forum Thread Page URL

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/models/forum.html

Generates the URL for a specific page of a forum thread. Raises a ValueError if the page number is less than 1.

```python
def get_page_url(self, page: int) -> str:
    """Get the URL to a given page of the board.

    Parameters
    ----------
    page: :class:`int`
        The desired page.

    Returns
    -------
    :class:`str`
        The URL to the desired page.

    """
    if page <= 0:
        raise ValueError("page must be 1 or greater")

    return get_forum_thread_url(self.thread_id, page)
```

--------------------------------

### fetch_world_overview

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Fetches the overview of all game worlds.

```APIDOC
## fetch_world_overview(*, test: bool = False)

### Description
Fetch the world overview information from Tibia.com.

### Parameters
- **test** (bool) - Optional - Whether to request the test website instead.

### Returns
- **TibiaResponse[WorldOverview]** - A response containing the world overview information.
```

--------------------------------

### Get Forum Board Page URL

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/models/forum.html

Generates the URL for a specific page of a forum board. Raises a ValueError if the page number is less than 1.

```python
def get_page_url(self, page: int) -> str:
    """Get the URL to a given page of the board.

    Parameters
    ----------
    page: :class:`int`
        The desired page.

    Returns
    -------
    :class:`str`
        The URL to the desired page.

    """
    if page <= 0:
        raise ValueError("page must be 1 or greater")

    return get_forum_board_url(self.board_id, page, self.age)
```

--------------------------------

### Fetch CM Post Archive

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Retrieves a list of CM posts within a specified date range. Validates that the start date precedes the end date and the page number is positive.

```python
    async def fetch_cm_post_archive(
            self,
            start_date: datetime.datetime,
            end_date: datetime.datetime,
            page: int = 1,
            *,
            test: bool = False,
    ) -> TibiaResponse[CMPostArchive]:
        """Fetch the CM post archive.

        .. versionadded:: 3.0.0

        Parameters
        ----------
        start_date:
            The start date to display.
        end_date:
            The end date to display.
        page:
            The desired page to display.
        test:
            Whether to request the test website instead.

        Returns
        -------
        TibiaResponse[CMPostArchive]
            The CM Post Archive.

        Raises
        ------
        Forbidden
            If a 403 Forbidden error was returned.
            This usually means that Tibia.com is rate-limiting the client because of too many requests.
        NetworkError
            If there's any connection errors during the request.
        ValueError
            If the start_date is more recent than the end date or page number is not 1 or greater.

        """
        if start_date > end_date:
            raise ValueError("start_date cannot be more recent than end_date")

        if page <= 0:
            raise ValueError("page cannot be lower than 1.")

        response = await self._request("GET", get_cm_post_archive_url(start_date, end_date, page), test=test)
        return response.parse(CMPostArchiveParser.from_content)
```

--------------------------------

### Fetch and parse data using custom networking

Source: https://tibiapy.readthedocs.io/en/latest/intro.html

Demonstrates using the requests library to fetch HTML content and passing it to a Tibia.py parser.

```python
import requests
import tibiapy
from tibiapy.parsers import CharacterParser

# Fetching a character using requests instead of aiohttp
def get_character(name):
    url = tibiapy.urls.get_character_url(name)

    r = requests.get(url)
    content = r.text
    return CharacterParser.from_content(content)
```

--------------------------------

### Implement Mounts Class

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/models/bazaar.html

Manages mounts the character has unlocked or purchased.

```python
class Mounts(AuctionSummary[MountEntry]):
    """The mounts the character has unlocked or purchased."""

    def get_by_id(self, entry_id: int) -> Optional[MountEntry]:
        """Get a mount by its mount id.

        Parameters
        ----------
        entry_id: :class:`int`
            The ID of the mount.

        Returns
        -------
        :class:`MountEntry`
            The mount matching the id.

        """
        return next((e for e in self.entries if e.mount_id == entry_id), None)
```

--------------------------------

### Fetch Forum Support Boards

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Retrieves the forum's support boards. Requires an asynchronous context.

```python
async def fetch_forum_support_boards(self, *, test: bool = False) -> TibiaResponse[Optional[ForumSection]]:
        response = await self._request("GET", get_support_boards_url(), test=test)
        return response.parse(ForumSectionParser.from_content)
```

--------------------------------

### Generate a Custom Tibia.com URL

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/urls.html

Constructs a URL with optional query parameters and anchors. Use keyword arguments or a dictionary to pass parameters.

```python
>>> get_tibia_url("community", "houses", page="view", houseid=55302, world="Gladera")
https://www.tibia.com/community/?subtopic=houses&page=view&houseid=55302&world=Gladera
```

```python
>>> params = {'world': "Gladera"}
>>> get_tibia_url("community", "worlds", **params)
https://www.tibia.com/community/?subtopic=worlds&world=Gladera
```

--------------------------------

### Implement AuctionSummary Base Class

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/models/bazaar.html

Provides base functionality for searching and retrieving auction entries by name or ID.

```python
class AuctionSummary(AjaxPaginator[T], Generic[T], ABC):
    def get_by_name(self, name: str):
        """Get an entry by its name.

        Parameters
        ----------
        name: :class:`str`
            The name of the entry, case-insensitive.

        Returns
        -------
        :class:`object`:
            The entry matching the name.

        """
        return next((e for e in self.entries if e.name.lower() == name.lower()), None)

    def search(self, value: str):
        """Search an entry by its name.

        Parameters
        ----------
        value: :class:`str`
            The value to look for.

        Returns
        -------
        :class:`list`
            A list of entries with names containing the search term.

        """
        return [e for e in self.entries if value.lower() in e.name.lower()]

    @abstractmethod
    def get_by_id(self, entry_id: int):
        ...
```

--------------------------------

### Pull the Tibia.py Docker image

Source: https://tibiapy.readthedocs.io/en/latest/intro.html

Download the official Tibia.py Docker image from Docker Hub.

```bash
docker pull galarzaa90/tibia.py

```

--------------------------------

### Fetch creatures from the library

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Retrieves the creatures section from Tibia.com. Requires an asynchronous context.

```python
async def fetch_creatures(self, *, test: bool = False) -> TibiaResponse[CreaturesSection]:
        """Fetch the creatures from the library section.

        .. versionadded:: 4.0.0

        Parameters
        ----------
        test:
            Whether to request the test website instead.

        Returns
        -------
        TibiaResponse[CreaturesSection]
            The creature's section in Tibia.com

        Raises
        ------
        Forbidden
            If a 403 Forbidden error was returned.
            This usually means that Tibia.com is rate-limiting the client because of too many requests.
        NetworkError
            If there's any connection errors during the request.

        """
        response = await self._request("GET", get_creatures_section_url(), test=test)
        return response.parse(CreaturesSectionParser.from_content)
```

--------------------------------

### Parse World Creation Date

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/parsers/world.html

Parses a date string in 'Month Year' format and updates the builder with a formatted 'YYYY-MM' string.

```python
@classmethod
def _parse_creation_date(cls, builder: WorldBuilder, value: str) -> None:
    parsed_date = datetime.datetime.strptime(value, "%B %Y").astimezone(datetime.timezone.utc)
    year, month = parsed_date.year, parsed_date.month
    builder.creation_date(f"{year:d}-{month:02d}")
```

--------------------------------

### Generate Fansites and World Overview URLs

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/urls.html

Functions to retrieve static URLs for the fansites and world overview sections.

```python
def get_fansites_url() -> str:
    """Get the Tibia.com URL for the fansites section.

    Returns
    -------
    :class:`str`
        The URL to the fansites section.

    """
    return get_tibia_url("community", "fansites")
```

```python
def get_world_overview_url() -> str:
    """Get the URL to world overview section in Tibia.com.

    Returns
    -------
    :class:`str`
        The URL to the world overview section in Tibia.com.

    """
    return get_tibia_url("community", "worlds")
```

--------------------------------

### Parse Tibia.com Content

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/utils.html

Initializes a BeautifulSoup object from raw HTML content retrieved from Tibia.com.

```python
def parse_tibiacom_content(
        content: str,
        *,
        html_class: str = "BoxContent",
        tag: str = "div",
        builder: str = "lxml",
) -> bs4.BeautifulSoup:
    """Parse HTML content from Tibia.com into a BeautifulSoup object.
```

--------------------------------

### Generate Houses Section URL

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/urls.html

Constructs a URL for the house list on Tibia.com based on world, town, and house status filters.

```python
def get_houses_section_url(world: str, town: str, house_type: HouseType, status: HouseStatus = None,
                           order: HouseOrder = None) -> str:
    """Get the URL to the house list on Tibia.com with the specified filters.

    Parameters
    ----------
    world: :class:`str`
        The world to search in.
    town: :class:`str`
        The town to show results for.
    house_type: :class:`HouseType`
        The type of houses to show.
    status: :class:`HouseStatus`
        The status of the houses to show.
    order: :class:`HouseOrder`
        The sorting parameter to use for the results.

    Returns
    -------
    :class:`str`
        The URL to the list matching the parameters.

    """
    params = {
        "world": world,
        "town": town,
        "type": house_type.plural if house_type else None,
        "state": status.value if status else None,
        "order": order.value if order else None,
    }
    return get_tibia_url("community", "houses", **{k: v for k, v in params.items() if v is not None})
```

--------------------------------

### create_model(model_name, /, *, __config__, __doc__, __base__, __module__, __validators__, __cls_kwargs__, __qualname__, **field_definitions)

Source: https://tibiapy.readthedocs.io/en/latest/_modules/pydantic/main.html

Dynamically creates and returns a new Pydantic model subclass of BaseModel.

```APIDOC
## create_model

### Description
Dynamically creates and returns a new Pydantic model, effectively creating a subclass of BaseModel at runtime.

### Parameters
- **model_name** (str) - Required - The name of the newly created model.
- **__config__** (ConfigDict) - Optional - The configuration of the new model.
- **__doc__** (str) - Optional - The docstring of the new model.
- **__base__** (type | tuple) - Optional - The base class or classes for the new model.
- **__module__** (str) - Optional - The name of the module that the model belongs to.
- **__validators__** (dict) - Optional - A dictionary of methods that validate fields.
- **__cls_kwargs__** (dict) - Optional - A dictionary of keyword arguments for class creation.
- **__qualname__** (str) - Optional - The qualified name of the newly created model.
- ****field_definitions** (Any | tuple) - Optional - Field definitions where values are either a type annotation or a two-tuple of (type, default/Field).

### Returns
- **model** (type[BaseModel]) - The newly created Pydantic model class.

### Raises
- **PydanticUserError** - If both __base__ and __config__ are provided.
```

--------------------------------

### fetch_forum_support_boards

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Fetches the forum's support boards.

```APIDOC
## fetch_forum_support_boards

### Description
Fetches the forum's support boards.

### Parameters
- **test** (bool) - Optional - Whether to request the test website instead.

### Returns
- **TibiaResponse[Optional[ForumSection]]** - The forum boards in the community section.
```

--------------------------------

### fetch_kill_statistics

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Fetches the kill statistics of a world from Tibia.com.

```APIDOC
## fetch_kill_statistics

### Description
Fetches the kill statistics of a world from Tibia.com.

### Parameters
- **world** (str) - Required - The name of the world.
- **test** (bool) - Optional - Whether to request the test website instead.

### Returns
- **TibiaResponse[Optional[KillStatistics]]** - The kill statistics of the world if found.
```

--------------------------------

### TibiaResponse Model Implementation

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/models/tibia_response.html

The core model for handling Tibia.com responses, including cache management and data parsing.

```python
"""Models used to wrap responses from Tibia.com."""
import datetime
from typing import Generic, TypeVar

from pydantic import computed_field
from typing_extensions import Self

from tibiapy.models.base import BaseModel

__all__ = (
    "TibiaResponse",
)

T = TypeVar("T")

# Tibia.com's cache for the community section is 5 minutes.
# This limit is not sent anywhere, so there's no way to automate it.
CACHE_LIMIT = 300




[docs]
class TibiaResponse(BaseModel, Generic[T]):
    """Represents a response from Tibia.com."""

    timestamp: datetime.datetime
    """The date and time when the page was fetched, in UTC."""
    cached: bool
    """Whether the response is cached or it is a fresh response."""
    age: int
    """The age of the cache in seconds."""
    fetching_time: float
    """The time in seconds it took for Tibia.com to respond."""
    parsing_time: float
    """The time in seconds it took for the response to be parsed into data."""
    data: T
    """The data contained in the response."""

    @computed_field
    @property
    def time_left(self) -> datetime.timedelta:
        """:class:`datetime.timedelta`: The time left for the cache of this response to expire."""
        return (datetime.timedelta(seconds=CACHE_LIMIT - self.age)
                - (datetime.datetime.now(datetime.timezone.utc) - self.timestamp))

    @property
    def seconds_left(self) -> int:
        """:class:`int`: The time left in seconds for this response's cache to expire."""
        return self.time_left.seconds

[docs]
    @classmethod
    def from_raw(cls, raw_response, data: T, parsing_time: float = None) -> Self:
        """Build an instance from a raw response."""
        return cls(
            timestamp=raw_response.timestamp,
            cached=raw_response.cached,
            age=raw_response.age,
            fetching_time=raw_response.fetching_time,
            parsing_time=parsing_time,
            data=data,
        )
```

--------------------------------

### Define a Pydantic model with extra configuration

Source: https://tibiapy.readthedocs.io/en/latest/_modules/pydantic/main.html

Demonstrates how to use the model_config settings during class definition for type-checking purposes.

```python
from pydantic import BaseModel

class MyModel(BaseModel, extra='allow'): ...
```

--------------------------------

### Fetch Forum World Boards

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Retrieves the forum boards located in the world section.

```python
async def fetch_forum_world_boards(self, *, test: bool = False) -> TibiaResponse[Optional[ForumSection]]:
    """Fetch the forum's world boards.

    .. versionadded:: 3.0.0

    Parameters
    ----------
    test:
        Whether to request the test website instead.

    Returns
    -------
    TibiaResponse[Optional[ForumSection]]
        The forum boards in the world section.

    Raises
    ------
    Forbidden
        If a 403 Forbidden error was returned.
        This usually means that Tibia.com is rate-limiting the client because of too many requests.
    NetworkError
        If there's any connection errors during the request.

    """
    response = await self._request("GET", get_world_boards_url(), test=test)
    return response.parse(ForumSectionParser.from_content)
```

--------------------------------

### fetch_leaderboard

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Fetches the leaderboards for a specific world and rotation.

```APIDOC
## fetch_leaderboard

### Description
Fetches the leaderboards for a specific world and rotation.

### Parameters
- **world** (str) - Required - The name of the world.
- **rotation** (int) - Optional - The ID of the rotation. By default, it will get the current rotation.
- **page** (int) - Optional - The page to get.
- **test** (bool) - Optional - Whether to request the test website instead.

### Returns
- **TibiaResponse[Optional[Leaderboard]]** - The leaderboards of the world if found.
```

--------------------------------

### BaseBoard Class

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/models/forum.html

Base class for forum boards, implementing equality checks and URL generation.

```python
class BaseBoard(BaseModel):
    """Base class for all board classes.

    Implements common properties and methods for boards.

    The following implement this class:

    - :class:`.ForumBoard`
    - :class:`.BoardEntry`
    """

    board_id: int
    """The ID of the board."""

    @property
    def url(self) -> str:
        """The URL of this board."""
        return get_forum_board_url(self.board_id)

    def __eq__(self, o: object) -> bool:
        """Two boards are considered equal if their ids are equal."""
        return self.board_id == o.board_id if isinstance(o, self.__class__) else False
```

--------------------------------

### fetch_boosted_boss

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Fetches today's boosted boss from the Tibia website.

```APIDOC
## fetch_boosted_boss

### Description
Fetches today's boosted boss.

### Parameters
- **test** (bool) - Optional - Whether to request the test website instead.

### Returns
- **TibiaResponse[BossEntry]** - The boosted boss of the day.

### Raises
- **Forbidden** - If a 403 Forbidden error was returned (rate-limiting).
- **NetworkError** - If there's any connection errors during the request.
```

--------------------------------

### fetch_boosted_creature

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Fetches today's boosted creature from the Tibia website.

```APIDOC
## fetch_boosted_creature

### Description
Fetches today's boosted creature.

### Parameters
- **test** (bool) - Optional - Whether to request the test website instead.

### Returns
- **TibiaResponse[CreatureEntry]** - The boosted creature of the day.

### Raises
- **Forbidden** - If a 403 Forbidden error was returned (rate-limiting).
- **NetworkError** - If there's any connection errors during the request.
```

--------------------------------

### Try Datetime Conversion

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/utils.html

Attempts to convert an input object into a UTC-aware datetime object, suitable for use in class constructors.

```python
def try_datetime(obj: Union[str, datetime.datetime]) -> Optional[datetime.datetime]:
    """Attempt to convert an object into a datetime.

    If the date format is known, it's recommended to use the corresponding function
    This is meant to be used in constructors.

    Parameters
    ----------
    obj: :class:`str`, :class:`dict`, :class:`datetime.datetime`
        The object to convert.

    Returns
    -------
    :class:`datetime.datetime`, optional
        The represented datetime, in UTC (timezone aware), or :obj:`None` if conversion wasn't possible.

    """
    if obj is None:
        return None

    return obj if isinstance(obj, datetime.datetime) else parse_tibia_datetime(obj)
```

--------------------------------

### Fetch Leaderboards

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Retrieves the leaderboard for a specific world and rotation.

```python
async def fetch_leaderboard(
            self,
            world: str,
            rotation: int = None,
            page: int = 1,
            *, test: bool = False,
    ) -> TibiaResponse[Optional[Leaderboard]]:
        """Fetch the leaderboards for a specific world and rotation.

        .. versionadded:: 5.0.0

        Parameters
        ----------
        world: :class:`str`
            The name of the world.
        rotation: :class:`int`
            The ID of the rotation. By default, it will get the current rotation.
        page: :class:`int`
            The page to get.
        test:
            Whether to request the test website instead.

        Returns
        -------
        TibiaResponse[Optional[Leaderboard]]
            The leaderboards of the world if found.

        Raises
        ------
        Forbidden
            If a 403 Forbidden error was returned.
            This usually means that Tibia.com is rate-limiting the client because of too many requests.
        NetworkError
            If there's any connection errors during the request.

        """
        response = await self._request("GET", get_leaderboards_url(world, rotation, page), test=test)
        return response.parse(LeaderboardParser.from_content)
```

--------------------------------

### fetch_world

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Fetches information for a specific game world.

```APIDOC
## fetch_world(name: str, *, test: bool = False)

### Description
Fetch a world from Tibia.com.

### Parameters
- **name** (str) - Required - The name of the world.
- **test** (bool) - Optional - Whether to request the test website instead.

### Returns
- **TibiaResponse[Optional[World]]** - A response containing the world's information if found, None otherwise.
```

--------------------------------

### Fetch Forum Board

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Retrieves a specific forum board by ID, with optional pagination and age filtering.

```python
async def fetch_forum_board(self, board_id: int, page: int = 1, age: int = None, *,
                                test: bool = False) -> TibiaResponse[Optional[ForumBoard]]:
        response = await self._request("GET", get_forum_board_url(board_id, page, age), test=test)
        return response.parse(ForumBoardParser.from_content)
```

--------------------------------

### Try Date Conversion

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/utils.html

Attempts to convert an input object into a date object, checking multiple formats if necessary.

```python
def try_date(obj: Union[str, datetime.datetime, datetime.date]) -> Optional[datetime.date]:
    """Attempt to convert an object into a date.

    If the date format is known, it's recommended to use the corresponding function
    This is meant to be used in constructors.

    Parameters
    ----------
    obj: :class:`str`, :class:`datetime.datetime`, :class:`datetime.date`
        The object to convert.

    Returns
    -------
    :class:`datetime.date`, optional
        The represented date, in UTC (timezone aware).

    """
    if obj is None:
        return None

    if isinstance(obj, datetime.datetime):
        return obj.date()

    if isinstance(obj, datetime.date):
        return obj

    res = parse_tibia_date(obj)
    return res if res is not None else parse_tibia_full_date(obj)
```

--------------------------------

### fetch_forum_world_boards

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Fetches the forum's world boards.

```APIDOC
## fetch_forum_world_boards

### Description
Fetches the forum's world boards.

### Parameters
- **test** (bool) - Optional - Whether to request the test website instead.

### Returns
- **TibiaResponse[Optional[ForumSection]]** - The forum boards in the world section.
```

--------------------------------

### fetch_guild(name: str, *, test: bool = False)

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Fetches a guild by its exact name.

```APIDOC
## fetch_guild

### Description
Fetch a guild by its name from Tibia.com.

### Parameters
- **name** (str) - Required - The name of the guild. The case must match exactly.
- **test** (bool) - Optional - Whether to request the test website instead.

### Returns
- **TibiaResponse[Optional[Guild]]** - A response containing the found guild, if any.

### Raises
- **Forbidden** - If a 403 Forbidden error was returned (rate-limiting).
- **NetworkError** - If there's any connection errors during the request.
```

--------------------------------

### Generate Event Schedule URL

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/urls.html

Constructs a URL for the event calendar. If no month or year is provided, it defaults to the current date.

```python
def get_event_schedule_url(month: int = None, year: int = None) -> str:
    """Get the URL to the Event Schedule or Event Calendar on Tibia.com.

    Notes
    -----
    If no parameters are passed, it will show the calendar for the current month and year.

    Tibia.com limits the dates that the calendar displays, passing a month and year far from the current ones may
    result in the response being for the current month and year instead.

    Parameters
    ----------
    month: :class:`int`, optional
        The desired month.
    year: :class:`int`, optional
        The desired year.

    Returns
    -------
    :class:`str`
        The URL to the calendar with the given parameters.

    """
    return get_tibia_url("news", "eventcalendar", calendarmonth=month, calendaryear=year)
```

--------------------------------

### Model Copying with Updates

Source: https://tibiapy.readthedocs.io/en/latest/_modules/pydantic/main.html

Creates a new model instance by copying the current one and applying optional updates. Note that the update data is not validated before creation.

```python
        copied = self.__deepcopy__() if deep else self.__copy__()
        if update:
            if self.model_config.get('extra') == 'allow':
                for k, v in update.items():
                    if k in self.__pydantic_fields__:
                        copied.__dict__[k] = v
                    else:
                        if copied.__pydantic_extra__ is None:
                            copied.__pydantic_extra__ = {}
                        copied.__pydantic_extra__[k] = v
            else:
                copied.__dict__.update(update)
            copied.__pydantic_fields_set__.update(update.keys())
        return copied
```

--------------------------------

### fetch_creatures

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Fetches the list of creatures from the library section of Tibia.com.

```APIDOC
## fetch_creatures

### Description
Fetches the creatures from the library section.

### Parameters
- **test** (bool) - Optional - Whether to request the test website instead.

### Returns
- **TibiaResponse[CreaturesSection]** - The creature's section in Tibia.com
```

--------------------------------

### Accessing Guild and War Information

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/models/guild.html

The models provide properties to retrieve URLs for guild pages and war information on Tibia.com.

```python
@property
def in_formation_guilds(self) -> list[GuildEntry]:
    """Get a list of the guilds that are in course of formation."""
    return [g for g in self.entries if not g.active]

@property
def url(self) -> str:
    """Get the URL to this guild section."""
    return get_world_guilds_url(self.world)
```

```python
[docs]
class GuildWarEntry(BaseModel):
    """Represents a guild war entry."""

    guild_name: str
    """The name of the guild."""
    guild_score: int
    """The number of kills the guild has scored."""
    guild_fee: int
    """The number of gold coins the guild will pay if they lose the war."""
    opponent_name: Optional[str] = None
    """The name of the opposing guild. If the guild no longer exist, this will be :obj:`None`."""
    opponent_score: int
    """The number of kills the opposing guild has scored."""
    opponent_fee: int
    """The number of gold coins the opposing guild will pay if they lose the war."""
    start_date: Optional[datetime.date] = None
    """The date when the war started.

    When a war is in progress, the start date is not visible."""
    score_limit: int
    """The number of kills needed to win the war."""
    duration: Optional[datetime.timedelta] = None
    """The set duration of the war.

    When a war is in progress, the duration is not visible."""
    end_date: Optional[datetime.date] = None
    """The deadline for the war to finish if the score is not reached for wars in progress, or the date when the
     war ended."""
    winner: Optional[str] = None
    """The name of the guild that won.

    Note that if the winning guild is disbanded, this may be :obj:`None`."""
    surrender: bool
    """Whether the losing guild surrendered or not."""

    @property
    def guild_url(self) -> str:
        """The URL to the guild's information page on Tibia.com."""
        return get_guild_url(self.guild_name)

    @property
    def opponent_guild_url(self) -> Optional[str]:
        """The URL to the opposing guild's information page on Tibia.com."""
        return get_guild_url(self.opponent_name) if self.opponent_name else None
```

```python
[docs]
class GuildWars(BaseModel):
    """Represents a guild's wars."""

    name: Optional[str] = None
    """The name of the guild."""
    is_current: Optional[GuildWarEntry] = None
    """The current war the guild is involved in."""
    history: list[GuildWarEntry]
    """The previous wars the guild has been involved in."""

    @property
    def url(self) -> str:
        """The URL of this guild's war page on Tibia.com."""
        return get_guild_wars_url(self.name)
```

--------------------------------

### Fetch Forum Trade Boards

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Retrieves the forum boards located in the trade section.

```python
async def fetch_forum_trade_boards(self, *, test: bool = False) -> TibiaResponse[Optional[ForumSection]]:
    """Fetch the forum's trade boards.

    .. versionadded:: 3.0.0

    Parameters
    ----------
    test:
        Whether to request the test website instead.

    Returns
    -------
    TibiaResponse[Optional[ForumSection]]
        The forum boards in the trade section.

    Raises
    ------
    Forbidden
        If a 403 Forbidden error was returned.
        This usually means that Tibia.com is rate-limiting the client because of too many requests.
    NetworkError
        If there's any connection errors during the request.

    """
    response = await self._request("GET", get_trade_boards_url(), test=test)
    return response.parse(ForumSectionParser.from_content)
```

--------------------------------

### Fetch Forum Section

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Retrieves a specific forum section by its ID.

```python
async def fetch_forum_section(
        self,
        section_id: int,
        *,
        test: bool = False,
) -> TibiaResponse[Optional[ForumSection]]:
    """Fetch a forum's section by its ID.

    Parameters
    ----------
    section_id:
        The ID of the section.
    test:
        Whether to request the test website instead.

    Returns
    -------
    TibiaResponse[Optional[ForumSection]]
        The forum section with the provided ID.

    Raises
    ------
    Forbidden
        If a 403 Forbidden error was returned.
        This usually means that Tibia.com is rate-limiting the client because of too many requests.
    NetworkError
        If there's any connection errors during the request.

    """
    response = await self._request("GET", get_forum_section_url(section_id), test=test)
    return response.parse(ForumSectionParser.from_content)
```

--------------------------------

### Dynamic Model Creation Logic

Source: https://tibiapy.readthedocs.io/en/latest/_modules/pydantic/main.html

Internal logic for preparing the namespace and class structure when dynamically creating a Pydantic model.

```python
namespace: dict[str, Any] = {'__annotations__': annotations, '__module__': __module__}
if __doc__:
    namespace['__doc__'] = __doc__
if __qualname__ is not None:
    namespace['__qualname__'] = __qualname__
if __validators__:
    namespace.update(__validators__)
namespace.update(fields)
if __config__:
    namespace['model_config'] = __config__
resolved_bases = types.resolve_bases(__base__)
meta, ns, kwds = types.prepare_class(model_name, resolved_bases, kwds=__cls_kwargs__)
if resolved_bases is not __base__:
    ns['__orig_bases__'] = __base__
namespace.update(ns)

return meta(
    model_name,
    resolved_bases,
    namespace,
    __pydantic_reset_parent_namespace__=False,
    _create_model_module=__module__,
    **kwds,
)
```

--------------------------------

### fetch_house(house_id: int, world: str, *, test: bool = False)

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/client.html

Fetches a specific house in a given world by its ID.

```APIDOC
## fetch_house

### Description
Fetches a house in a specific world by its id.

### Parameters
- **house_id** (int) - Required - The house's internal id.
- **world** (str) - Required - The name of the world to look for.
- **test** (bool) - Optional - Whether to request the test website instead.

### Returns
- **TibiaResponse[Optional[House]]** - The house if found, None otherwise.

### Raises
- **Forbidden** - If a 403 Forbidden error was returned (rate-limiting).
- **NetworkError** - If there's any connection errors during the request.
```

--------------------------------

### Parse House State Description

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/parsers/house.html

Internal method to parse the renting state of a house and apply it to a HouseBuilder.

```python
@classmethod
def _parse_status(cls, builder: HouseBuilder, status: str) -> None:
    """Parse the house's state description and applies the corresponding values.

    Parameters
    ----------
    builder: :class:`HouseBuilder`
        The instance of the builder where data will be collected.
    status: :class:`str`
        Plain text string containing the current renting state of the house.

    """
    if m := rented_regex.search(status):
        builder.status(HouseStatus.RENTED)
        builder.owner(m.group("owner"))
        builder.owner_sex(Sex.MALE if m.group("pronoun") == "He" else Sex.FEMALE)
        builder.paid_until(parse_tibia_datetime(m.group("paid_until")))
    else:
        builder.status(HouseStatus.AUCTIONED)
```

--------------------------------

### Generate Library Section URLs

Source: https://tibiapy.readthedocs.io/en/latest/_modules/tibiapy/urls.html

Functions to retrieve URLs for the creatures library section, specific creature details, and boostable bosses.

```python
def get_creatures_section_url() -> str:
    """Get the URL to the Tibia.com library section.

    Returns
    -------
    :class:`str`:
        The URL to the Tibia.com library section.

    """
    return get_tibia_url("library", "creature")
```

```python
def get_creature_url(identifier: str) -> str:
    """Get the URL to the creature's detail page on Tibia.com.

    Parameters
    ----------
    identifier: :class:`str`
        The race's internal name.

    Returns
    -------
    :class:`str`
        The URL to the detail page.

    """
    return get_tibia_url("library", "creatures", race=identifier)
```

```python
def get_boostable_bosses_url() -> str:
    """Get the URL to the Tibia.com boostable bosses.

    Returns
    -------
    :class:`str`:
        The URL to the Tibia.com library section.

    """
    return get_tibia_url("library", "boostablebosses")
```
Tokens:
Raw