lpdb_python 0.1.0__tar.gz

lpdb_python-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  checks: write
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Setup project
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest --junit-xml=pytest.xml
+        env:
+          API_KEY: ${{ secrets.LPDB_API_KEY }}
+
+      - name: Publish Test Results
+        if: ${{ always() }}
+        uses: mikepenz/action-junit-report@v6
+        with:
+          report_paths: "**/*.xml"
+          annotate_only: ${{ github.event_name == 'pull_request' }}
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version-file: "pyproject.toml"
+      - name: Check styling
+        uses: psf/black@stable

lpdb_python-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      # Publish on any tag starting with a `v`, e.g., v0.1.0
+      - v*
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish

lpdb_python-0.1.0/.gitignore

@@ -0,0 +1,174 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc

lpdb_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ElectricalBoy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lpdb_python-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: lpdb_python
+Version: 0.1.0
+Author-email: ElectricalBoy <electricalboy01@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ElectricalBoy/LPDB_python
+Project-URL: Changelog, https://github.com/ElectricalBoy/LPDB_python/releases
+Project-URL: Issues, https://github.com/ElectricalBoy/LPDB_python/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32.5
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.13.2; extra == "async"
+Dynamic: license-file
+
+# LPDB_python
+
+[![CI](https://github.com/ElectricalBoy/LPDB_python/actions/workflows/ci.yml/badge.svg)](https://github.com/ElectricalBoy/LPDB_python/actions/workflows/ci.yml)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+![GitHub License](https://img.shields.io/github/license/ElectricalBoy/LPDB-python)
+
+LPDB_python provides Python interfaces for the [Liquipedia Database API](https://liquipedia.net/api) (LPDB API).
+
+## LPDB Session
+
+Python wrapper for LPDB session is defined in [session.py](src/lpdb/session.py). The wrapper provides the following
+differences from making your own requests:
+
+- Type hints
+- Validation of data type names being requested  
+  If an invalid data type is supplied, then the session will raise `ValueError` before attempting to make a request.
+- Error / warning handling  
+  If an error is returned by LPDB, then they will be converted to and raised as a Python exception.
+- Pre-configured request header, including formatting of your API key in the request header  
+  
+  ```python
+  import lpdb_python as lpdb
+
+  # These are equivalent
+  session = lpdb.LpdbSession("your_lpdb_api_key")
+  session = lpdb.LpdbSession("Apikey your_lpdb_api_key")
+  ```
+
+## LPDB Data Types
+
+Data types in LPDB can be found in <https://liquipedia.net/commons/Help:LiquipediaDB>.
+
+The raw data returned from LPDB may not be in the corresponding Python types. To help easily access the data,
+[defs.py](src/lpdb/defs.py) file provides wrappers for each available data types that offers converted data
+as object properties.
+
+A property provided by the wrapper may be `None` if the raw data passed to the constructor of the wrapper
+did not contain the data, or if it contained an empty string. Thus, the user should be checking for `None`
+where appropriate.
+
+### Example
+
+```python
+import lpdb_python as lpdb
+
+session = lpdb.LpdbSession("your_lpdb_api_key")
+
+matches = [
+    lpdb.Match(lpdb_raw_match)
+    for lpdb_raw_match in session.make_request(
+        "match",
+        "leagueoflegends",
+        conditions="[[parent::World_Championship/2025]]",
+        streamurls="true",
+    )
+]
+```
+
+## License
+
+This library is licensed under the [MIT License](./LICENSE), unless otherwise stated in the header of a file.  
+It should be noted, however, that the data you will be fetching from LPDB API is licensed under [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/).
+See Liquipedia API Terms of Use [here](https://liquipedia.net/api-terms-of-use).
+
+## Disclaimer
+
+"Liquipedia" is a registered trademark of Team Liquid. Liquipedia does not endorse or sponsor this project.

lpdb_python-0.1.0/README.md

@@ -0,0 +1,67 @@
+# LPDB_python
+
+[![CI](https://github.com/ElectricalBoy/LPDB_python/actions/workflows/ci.yml/badge.svg)](https://github.com/ElectricalBoy/LPDB_python/actions/workflows/ci.yml)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+![GitHub License](https://img.shields.io/github/license/ElectricalBoy/LPDB-python)
+
+LPDB_python provides Python interfaces for the [Liquipedia Database API](https://liquipedia.net/api) (LPDB API).
+
+## LPDB Session
+
+Python wrapper for LPDB session is defined in [session.py](src/lpdb/session.py). The wrapper provides the following
+differences from making your own requests:
+
+- Type hints
+- Validation of data type names being requested  
+  If an invalid data type is supplied, then the session will raise `ValueError` before attempting to make a request.
+- Error / warning handling  
+  If an error is returned by LPDB, then they will be converted to and raised as a Python exception.
+- Pre-configured request header, including formatting of your API key in the request header  
+  
+  ```python
+  import lpdb_python as lpdb
+
+  # These are equivalent
+  session = lpdb.LpdbSession("your_lpdb_api_key")
+  session = lpdb.LpdbSession("Apikey your_lpdb_api_key")
+  ```
+
+## LPDB Data Types
+
+Data types in LPDB can be found in <https://liquipedia.net/commons/Help:LiquipediaDB>.
+
+The raw data returned from LPDB may not be in the corresponding Python types. To help easily access the data,
+[defs.py](src/lpdb/defs.py) file provides wrappers for each available data types that offers converted data
+as object properties.
+
+A property provided by the wrapper may be `None` if the raw data passed to the constructor of the wrapper
+did not contain the data, or if it contained an empty string. Thus, the user should be checking for `None`
+where appropriate.
+
+### Example
+
+```python
+import lpdb_python as lpdb
+
+session = lpdb.LpdbSession("your_lpdb_api_key")
+
+matches = [
+    lpdb.Match(lpdb_raw_match)
+    for lpdb_raw_match in session.make_request(
+        "match",
+        "leagueoflegends",
+        conditions="[[parent::World_Championship/2025]]",
+        streamurls="true",
+    )
+]
+```
+
+## License
+
+This library is licensed under the [MIT License](./LICENSE), unless otherwise stated in the header of a file.  
+It should be noted, however, that the data you will be fetching from LPDB API is licensed under [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/).
+See Liquipedia API Terms of Use [here](https://liquipedia.net/api-terms-of-use).
+
+## Disclaimer
+
+"Liquipedia" is a registered trademark of Team Liquid. Liquipedia does not endorse or sponsor this project.

lpdb_python-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools >= 80", "setuptools-scm[simple]>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lpdb_python"
+authors = [
+  { name="ElectricalBoy", email="electricalboy01@gmail.com" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dynamic = ["version"]
+requires-python = ">= 3.12"
+readme = "README.md"
+license = "MIT"
+dependencies = [
+  "requests>=2.32.5"
+]
+
+[project.urls]
+Homepage = "https://github.com/ElectricalBoy/LPDB_python"
+Changelog = "https://github.com/ElectricalBoy/LPDB_python/releases"
+Issues = "https://github.com/ElectricalBoy/LPDB_python/issues"
+
+[project.optional-dependencies]
+async = [
+    "aiohttp>=3.13.2"
+]
+
+[dependency-groups]
+dev = [
+    {include-group = "test"},
+    {include-group = "lint"}
+]
+test = [
+    "pytest",
+    "pytest-asyncio",
+]
+lint = [
+    "black",
+]
+
+[tool.pytest.ini_options]
+pythonpath = [
+    "src"
+]

lpdb_python-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lpdb_python-0.1.0/src/lpdb_python/__init__.py

@@ -0,0 +1,37 @@
+"""
+Python interface for Liquipedia Database (LPDB) API
+"""
+
+import importlib.metadata as _metadata
+
+from .defs import *
+from .session import *
+
+__all__ = [
+    "OpponentType",
+    "Broadcasters",
+    "Company",
+    "Datapoint",
+    "ExternalMediaLink",
+    "LpdbError",
+    "LpdbWarning",
+    "LpdbSession",
+    "Match",
+    "MatchGame",
+    "MatchOpponent",
+    "Placement",
+    "Player",
+    "Series",
+    "SquadPlayer",
+    "StandingsEntry",
+    "StandingsTable",
+    "Team",
+    "Tournament",
+    "Transfer",
+    "TeamTemplate",
+]
+
+try:
+    __version__ = _metadata.version(__name__)
+except _metadata.PackageNotFoundError:
+    __version__ = "0.0.0"

lpdb_python-0.1.0/src/lpdb_python/async_session/__init__.py

@@ -0,0 +1,3 @@
+from .async_session import AsyncLpdbSession
+
+__all__ = ["AsyncLpdbSession"]

lpdb_python-0.1.0/src/lpdb_python/async_session/async_session.py

@@ -0,0 +1,133 @@
+from datetime import date
+from http import HTTPStatus
+from types import TracebackType
+from typing import Any, Literal, Optional, override
+
+import aiohttp
+
+from ..session import AbstractLpdbSession, LpdbDataType, LpdbError
+
+__all__ = ["AsyncLpdbSession"]
+
+
+class AsyncLpdbSession(AbstractLpdbSession):
+    """
+    Asynchronous implementation of a LPDB session
+    """
+
+    __session: aiohttp.ClientSession
+
+    def __init__(self, api_key, base_url=AbstractLpdbSession.BASE_URL):
+        super().__init__(api_key, base_url=base_url)
+        self.__session = aiohttp.ClientSession(
+            self._base_url, headers=self._get_header()
+        )
+
+    def __enter__(self) -> None:
+        raise TypeError("Use async with instead")
+
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        pass
+
+    async def __aenter__(self) -> "AsyncLpdbSession":
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        await self.__session.close()
+
+    @staticmethod
+    async def get_wikis() -> set[str]:
+        async with aiohttp.ClientSession("https://liquipedia.net/") as session:
+            async with session.get(
+                "api.php",
+                params={"action": "listwikis"},
+                headers={"accept": "application/json", "accept-encoding": "gzip"},
+            ) as response:
+                wikis = await response.json()
+                return set(wikis["allwikis"].keys())
+
+    @staticmethod
+    async def __handle_response(
+        response: aiohttp.ClientResponse,
+    ) -> list[dict[str, Any]]:
+        return AbstractLpdbSession._parse_results(
+            response.status, await response.json()
+        )
+
+    @override
+    async def make_request(
+        self,
+        lpdb_datatype: LpdbDataType,
+        wiki: str | list[str],
+        limit: int = 20,
+        offset: int = 0,
+        conditions: Optional[str] = None,
+        query: Optional[str | list[str]] = None,
+        order: Optional[str | list[tuple[str, Literal["asc", "desc"]]]] = None,
+        groupby: Optional[str | list[tuple[str, Literal["asc", "desc"]]]] = None,
+        **kwargs,
+    ) -> list[dict[str, Any]]:
+        if not AbstractLpdbSession._validate_datatype_name(lpdb_datatype):
+            raise ValueError(f'Invalid LPDB data type: "{lpdb_datatype}"')
+        async with self.__session.get(
+            lpdb_datatype,
+            params=AbstractLpdbSession._parse_params(
+                wiki=wiki,
+                limit=limit,
+                offset=offset,
+                conditions=conditions,
+                query=query,
+                order=order,
+                groupby=groupby,
+                **kwargs,
+            ),
+        ) as response:
+            return await AsyncLpdbSession.__handle_response(response)
+
+    @override
+    async def make_count_request(
+        self,
+        lpdb_datatype,
+        wiki: str,
+        conditions: Optional[str] = None,
+    ) -> int:
+        response = await self.make_request(
+            lpdb_datatype, wiki=wiki, conditions=conditions, query="count::objectname"
+        )
+        return response[0]["count_objectname"]
+
+    @override
+    async def get_team_template(
+        self, wiki: str, template: str, date: Optional[date] = None
+    ) -> Optional[dict[str, Any]]:
+        params = {
+            "wiki": wiki,
+            "template": template,
+        }
+        if date != None:
+            params["date"] = date.isoformat()
+        async with self.__session.get("teamtemplate", params=params) as response:
+            parsed_response = await AsyncLpdbSession.__handle_response(response)
+            if parsed_response[0] == None:
+                return None
+            return parsed_response[0]
+
+    @override
+    async def get_team_template_list(
+        self, wiki: str, pagination: int = 1
+    ) -> list[dict[str, Any]]:
+        async with self.__session.get(
+            "teamtemplatelist",
+            params={"wiki": wiki, "pagination": pagination},
+        ) as response:
+            return await AsyncLpdbSession.__handle_response(response)