acesapi 0.1.0__tar.gz

acesapi-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.venv/
+dist/
+build/

acesapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AcesAPI
+
+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.

acesapi-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: acesapi
+Version: 0.1.0
+Summary: Python client for the AcesAPI tennis data API. No dependencies.
+Project-URL: Homepage, https://acesapi.com
+Project-URL: Documentation, https://acesapi.com/docs
+Project-URL: Repository, https://github.com/noahowsh/puckapi
+Project-URL: Sign up, https://acesapi.com/signup
+Author-email: AcesAPI <support@acesapi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: acesapi,api-client,betting,odds,player-props,sports-data,tennis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == 'pandas'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# AcesAPI for Python
+
+Python client for the [AcesAPI](https://acesapi.com) tennis data API. It has no required dependencies (standard library only) and works on Python 3.9 and newer. Pandas is optional.
+
+## Install
+
+```bash
+pip install acesapi
+pip install "acesapi[pandas]"   # only if you want DataFrames
+```
+
+## Set your key
+
+Get a free key at https://acesapi.com/signup. Free accounts get 500 credits a month.
+
+```bash
+export ACESAPI_API_KEY=your_key_here
+```
+
+```python
+from acesapi import Client
+
+client = Client()                      # reads ACESAPI_API_KEY
+client = Client(api_key="your_key")    # or pass it in
+```
+
+## Examples
+
+### 1. Current rankings
+
+ATP is the default tour. Pass `league="wta"` for the women's tour.
+
+```python
+from acesapi import Client
+
+client = Client()
+
+ranks = client.get_rankings(limit=5)
+for row in ranks["rankings"]:
+    print(row["rank"], row["name"], row["points"])
+```
+
+### 2. Head to head
+
+Look up two player ids with `search_players`, then compare them.
+
+```python
+from acesapi import Client
+
+client = Client()
+
+sinner = client.search_players(name="Sinner", limit=1)["players"][0]
+alcaraz = client.search_players(name="Alcaraz", limit=1)["players"][0]
+h2h = client.get_head_to_head(sinner["player_id"], alcaraz["player_id"])
+print(sinner["name"], "vs", alcaraz["name"])
+print("matches:", h2h["summary"]["matches"])
+print("wins:", h2h["summary"]["wins"])
+```
+
+### 3. Results by surface
+
+`get_surface_splits` shows how a player does on hard, clay and grass.
+
+```python
+from acesapi import Client
+
+client = Client()
+
+sinner = client.search_players(name="Sinner", limit=1)["players"][0]
+splits = client.get_surface_splits(sinner["player_id"])
+for row in splits["splits"]:
+    print(row["surface"], row["wins"], "-", row["losses"], row["win_pct"])
+```
+
+## Credits
+
+Every method returns the `data` object from the response. After each call, `client.last_credits_used` and `client.last_credits_remaining` hold the counters from the `X-Credits-Used` and `X-Credits-Remaining` headers. Methods that take `estimate_only=True` return the price of a call without running or charging it.
+
+## Pandas
+
+```python
+from acesapi import to_dataframe
+
+df = to_dataframe(data)                # finds the main list in the response
+df = to_dataframe(data, key="rows")    # or name the list yourself
+```
+
+Nested fields become dotted columns. Install pandas separately or with `pip install "acesapi[pandas]"`.
+
+## Errors
+
+Every error is an `APIError` subclass, with the server's message and the HTTP status.
+
+| Exception | Status | Meaning |
+| --- | --- | --- |
+| `AuthError` | 401 | Missing, invalid or revoked key |
+| `InsufficientCreditsError` | 402 | Not enough credits for the call |
+| `NotFoundError` | 404 | The id or name does not exist |
+| `RateLimitError` | 429 | Too many requests; has `.retry_after` when the server sends it |
+| `APIError` | 400, 5xx | Bad arguments or a server problem |
+| `APIConnectionError` | none | No response (network or timeout) |
+
+```python
+from acesapi import Client, APIError, InsufficientCreditsError, RateLimitError
+
+client = Client()
+try:
+    data = client.list_tournaments()
+except InsufficientCreditsError:
+    print("Out of credits, top up at https://acesapi.com")
+except RateLimitError as exc:
+    print("Slow down, retry after", exc.retry_after)
+except APIError as exc:
+    print(exc.status_code, exc.message)
+```
+
+The client retries 429 and 5xx responses and connection failures up to 3 times with backoff, and honors `Retry-After`. Set `Client(max_retries=0)` to turn that off.
+
+If you see `CERTIFICATE_VERIFY_FAILED` on a python.org install for macOS, run the "Install Certificates.command" script that came with Python, or `pip install certifi` (the client uses it when present).
+
+## Options
+
+```python
+Client(
+    api_key=None,                          # defaults to $ACESAPI_API_KEY
+    base_url="https://mcp.acesapi.com",           # point at another host
+    timeout=60.0,                          # seconds per request
+    max_retries=3,
+)
+```
+
+`client.call("tool_name", {"arg": "value"})` calls any tool by name, which helps when the API adds a tool before this package does.
+
+## Tools
+
+Method names match the API tool names. Arguments are keyword arguments; required ones can also be passed positionally. Each method's docstring lists its arguments (`help(client.list_tournaments)`).
+
+| Method | Credits | What it does |
+| --- | --- | --- |
+| `list_tournaments` | 1 | List tournaments |
+| `get_tournament` | 2 | Tournament |
+| `get_matches` | 2 | Matches |
+| `get_schedule` | 2 | Schedule |
+| `get_match` | 2 | Match |
+| `search_players` | 1 | Search players |
+| `get_player` | 5 | Player |
+| `get_player_matches` | 5 | Player matches |
+| `get_head_to_head` | 3 | Head to head |
+| `get_surface_splits` | 3 | Surface splits |
+| `get_player_stats` | 3 | Player stats |
+| `get_rankings` | 2 | Rankings |
+| `get_ratings` | 2 | Ratings |
+
+Full API reference: https://acesapi.com/docs
+
+## License
+
+MIT

acesapi-0.1.0/README.md

@@ -0,0 +1,158 @@
+# AcesAPI for Python
+
+Python client for the [AcesAPI](https://acesapi.com) tennis data API. It has no required dependencies (standard library only) and works on Python 3.9 and newer. Pandas is optional.
+
+## Install
+
+```bash
+pip install acesapi
+pip install "acesapi[pandas]"   # only if you want DataFrames
+```
+
+## Set your key
+
+Get a free key at https://acesapi.com/signup. Free accounts get 500 credits a month.
+
+```bash
+export ACESAPI_API_KEY=your_key_here
+```
+
+```python
+from acesapi import Client
+
+client = Client()                      # reads ACESAPI_API_KEY
+client = Client(api_key="your_key")    # or pass it in
+```
+
+## Examples
+
+### 1. Current rankings
+
+ATP is the default tour. Pass `league="wta"` for the women's tour.
+
+```python
+from acesapi import Client
+
+client = Client()
+
+ranks = client.get_rankings(limit=5)
+for row in ranks["rankings"]:
+    print(row["rank"], row["name"], row["points"])
+```
+
+### 2. Head to head
+
+Look up two player ids with `search_players`, then compare them.
+
+```python
+from acesapi import Client
+
+client = Client()
+
+sinner = client.search_players(name="Sinner", limit=1)["players"][0]
+alcaraz = client.search_players(name="Alcaraz", limit=1)["players"][0]
+h2h = client.get_head_to_head(sinner["player_id"], alcaraz["player_id"])
+print(sinner["name"], "vs", alcaraz["name"])
+print("matches:", h2h["summary"]["matches"])
+print("wins:", h2h["summary"]["wins"])
+```
+
+### 3. Results by surface
+
+`get_surface_splits` shows how a player does on hard, clay and grass.
+
+```python
+from acesapi import Client
+
+client = Client()
+
+sinner = client.search_players(name="Sinner", limit=1)["players"][0]
+splits = client.get_surface_splits(sinner["player_id"])
+for row in splits["splits"]:
+    print(row["surface"], row["wins"], "-", row["losses"], row["win_pct"])
+```
+
+## Credits
+
+Every method returns the `data` object from the response. After each call, `client.last_credits_used` and `client.last_credits_remaining` hold the counters from the `X-Credits-Used` and `X-Credits-Remaining` headers. Methods that take `estimate_only=True` return the price of a call without running or charging it.
+
+## Pandas
+
+```python
+from acesapi import to_dataframe
+
+df = to_dataframe(data)                # finds the main list in the response
+df = to_dataframe(data, key="rows")    # or name the list yourself
+```
+
+Nested fields become dotted columns. Install pandas separately or with `pip install "acesapi[pandas]"`.
+
+## Errors
+
+Every error is an `APIError` subclass, with the server's message and the HTTP status.
+
+| Exception | Status | Meaning |
+| --- | --- | --- |
+| `AuthError` | 401 | Missing, invalid or revoked key |
+| `InsufficientCreditsError` | 402 | Not enough credits for the call |
+| `NotFoundError` | 404 | The id or name does not exist |
+| `RateLimitError` | 429 | Too many requests; has `.retry_after` when the server sends it |
+| `APIError` | 400, 5xx | Bad arguments or a server problem |
+| `APIConnectionError` | none | No response (network or timeout) |
+
+```python
+from acesapi import Client, APIError, InsufficientCreditsError, RateLimitError
+
+client = Client()
+try:
+    data = client.list_tournaments()
+except InsufficientCreditsError:
+    print("Out of credits, top up at https://acesapi.com")
+except RateLimitError as exc:
+    print("Slow down, retry after", exc.retry_after)
+except APIError as exc:
+    print(exc.status_code, exc.message)
+```
+
+The client retries 429 and 5xx responses and connection failures up to 3 times with backoff, and honors `Retry-After`. Set `Client(max_retries=0)` to turn that off.
+
+If you see `CERTIFICATE_VERIFY_FAILED` on a python.org install for macOS, run the "Install Certificates.command" script that came with Python, or `pip install certifi` (the client uses it when present).
+
+## Options
+
+```python
+Client(
+    api_key=None,                          # defaults to $ACESAPI_API_KEY
+    base_url="https://mcp.acesapi.com",           # point at another host
+    timeout=60.0,                          # seconds per request
+    max_retries=3,
+)
+```
+
+`client.call("tool_name", {"arg": "value"})` calls any tool by name, which helps when the API adds a tool before this package does.
+
+## Tools
+
+Method names match the API tool names. Arguments are keyword arguments; required ones can also be passed positionally. Each method's docstring lists its arguments (`help(client.list_tournaments)`).
+
+| Method | Credits | What it does |
+| --- | --- | --- |
+| `list_tournaments` | 1 | List tournaments |
+| `get_tournament` | 2 | Tournament |
+| `get_matches` | 2 | Matches |
+| `get_schedule` | 2 | Schedule |
+| `get_match` | 2 | Match |
+| `search_players` | 1 | Search players |
+| `get_player` | 5 | Player |
+| `get_player_matches` | 5 | Player matches |
+| `get_head_to_head` | 3 | Head to head |
+| `get_surface_splits` | 3 | Surface splits |
+| `get_player_stats` | 3 | Player stats |
+| `get_rankings` | 2 | Rankings |
+| `get_ratings` | 2 | Ratings |
+
+Full API reference: https://acesapi.com/docs
+
+## License
+
+MIT

acesapi-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "acesapi"
+dynamic = ["version"]
+description = "Python client for the AcesAPI tennis data API. No dependencies."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "AcesAPI", email = "support@acesapi.com" }]
+keywords = ["tennis", "sports-data", "api-client", "betting", "player-props", "odds", "acesapi"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+pandas = ["pandas>=1.5"]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://acesapi.com"
+Documentation = "https://acesapi.com/docs"
+Repository = "https://github.com/noahowsh/puckapi"
+"Sign up" = "https://acesapi.com/signup"
+
+[tool.hatch.version]
+path = "src/acesapi/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/acesapi"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

acesapi-0.1.0/src/acesapi/__init__.py

@@ -0,0 +1,25 @@
+"""AcesAPI: Python client for the AcesAPI tennis data API."""
+from ._core import (
+    APIConnectionError,
+    APIError,
+    AuthError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    to_dataframe,
+)
+from ._version import __version__
+from .client import TOOLS, Client
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "AuthError",
+    "Client",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "RateLimitError",
+    "TOOLS",
+    "__version__",
+    "to_dataframe",
+]