gunspec 0.1.0__tar.gz

gunspec-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+node_modules/
+dist/
+.dev.vars
+.wrangler/
+.seed-tmp/
+.seed-hashes.json
+*.tsbuildinfo
+.env
+.env.local
+
+# Drizzle
+drizzle/meta/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test
+coverage/
+
+# Scraped data (ephemeral)
+data/scraped/*.csv
+
+# Inspiration
+inspiration/
+
+frontend/public/models/animations/
+frontend/public/models/people/
+frontend/public/firearms/photos/
+frontend/public/firearms/archive/
+frontend/public/firearms/line/*.png
+frontend/public/manufacturers/archived
+frontend/public/firearms/packs/

gunspec-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: gunspec
+Version: 0.1.0
+Summary: Python SDK for the GunSpec.io firearms specification API
+Project-URL: Homepage, https://gunspec.io
+Project-URL: Documentation, https://gunspec.io/docs
+Project-URL: Repository, https://github.com/buun-group/gunspec
+Project-URL: Issues, https://github.com/buun-group/gunspec/issues
+Author: GunSpec.io
+License-Expression: MIT
+Keywords: api,database,firearms,gunspec,sdk,specifications
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Requires-Dist: pydantic<3,>=2
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gunspec
+
+Official Python SDK for the [GunSpec.io](https://gunspec.io) firearms specification database API.
+
+## Installation
+
+```bash
+pip install gunspec
+```
+
+## Quick Start
+
+```python
+from gunspec import GunSpec
+
+# Reads GUNSPEC_API_KEY from environment automatically
+client = GunSpec()
+
+# List firearms
+result = client.firearms.list({"category": "pistol", "manufacturer": "glock"})
+for firearm in result.data:
+    print(firearm["name"], firearm["caliber"])
+
+# Get a single firearm
+result = client.firearms.get("glock-g17")
+print(result.data["name"])
+```
+
+## Async Usage
+
+```python
+from gunspec import AsyncGunSpec
+
+async with AsyncGunSpec() as client:
+    result = await client.firearms.list({"category": "rifle"})
+    for firearm in result.data:
+        print(firearm["name"])
+```
+
+## Configuration
+
+```python
+from gunspec import GunSpec, RetryConfig
+
+# Reads GUNSPEC_API_KEY from env automatically
+client = GunSpec()
+
+# Or configure explicitly
+client = GunSpec(
+    api_key="gs_...",                         # or set GUNSPEC_API_KEY env var
+    base_url="https://api.gunspec.io",        # default
+    timeout=30.0,                              # 30s default
+    retry=RetryConfig(
+        max_retries=2,                         # default
+        initial_delay_s=0.5,                   # default
+    ),
+)
+```
+
+## Resources
+
+| Resource | Methods |
+|----------|---------|
+| `client.firearms` | `list`, `get`, `search`, `compare`, `game_meta`, `action_types`, `filter_options`, `random`, `top`, `head_to_head`, `by_feature`, `by_action`, `by_material`, `by_designer`, `power_rating`, `timeline`, `by_conflict`, `get_variants`, `get_images`, `get_game_stats`, `get_dimensions`, `get_users`, `get_family_tree`, `get_similar`, `get_adoption_map`, `get_game_profile`, `get_silhouette`, `calculate`, `load`, `list_auto_paging` |
+| `client.manufacturers` | `list`, `get`, `get_firearms`, `get_timeline`, `get_stats`, `list_auto_paging` |
+| `client.calibers` | `list`, `get`, `compare`, `ballistics`, `get_firearms`, `get_parent_chain`, `get_family`, `get_ammunition`, `list_auto_paging` |
+| `client.categories` | `list`, `get_firearms` |
+| `client.stats` | `summary`, `production_status`, `field_coverage`, `popular_calibers`, `prolific_manufacturers`, `by_category`, `by_era`, `materials`, `adoption_by_country`, `adoption_by_type`, `action_types`, `feature_frequency`, `caliber_popularity_by_era` |
+| `client.game` | `balance_report`, `tier_list`, `matchups`, `role_roster`, `stat_distribution` |
+| `client.game_stats` | `list_versions`, `list_firearms`, `get_firearm` |
+| `client.ammunition` | `list`, `get`, `get_bullet_svg`, `ballistics`, `list_auto_paging` |
+| `client.countries` | `list`, `get_arsenal` |
+| `client.conflicts` | `list` |
+| `client.data_quality` | `coverage`, `confidence` |
+| `client.favorites` | `list`, `add`, `remove` |
+| `client.reports` | `create`, `list` |
+| `client.support` | `create`, `list`, `get`, `reply` |
+| `client.webhooks` | `list`, `create`, `get`, `update`, `delete`, `test` |
+| `client.usage` | `get` |
+
+## Auto-Pagination
+
+```python
+# Sync
+for firearm in client.firearms.list_auto_paging({"category": "rifle"}):
+    print(firearm["name"])
+
+# Async
+async for firearm in client.firearms.list_auto_paging({"category": "rifle"}):
+    print(firearm["name"])
+```
+
+## Error Handling
+
+```python
+from gunspec import (
+    GunSpec,
+    NotFoundError,
+    RateLimitError,
+    AuthenticationError,
+)
+
+client = GunSpec()
+
+try:
+    result = client.firearms.get("nonexistent")
+except NotFoundError as e:
+    print(f"Not found: {e.message}")
+    print(f"Request ID: {e.request_id}")
+except RateLimitError as e:
+    print(f"Retry after: {e.retry_after}s")
+except AuthenticationError:
+    print("Invalid API key")
+```
+
+## Context Managers
+
+```python
+# Sync
+with GunSpec() as client:
+    result = client.firearms.list()
+
+# Async
+async with AsyncGunSpec() as client:
+    result = await client.firearms.list()
+```
+
+## Requirements
+
+- Python >= 3.9
+- httpx >= 0.25
+- pydantic >= 2
+
+## Publishing
+
+```bash
+cd packages/sdk-python
+
+# Install build tools
+pip install build twine
+
+# Build sdist and wheel
+python -m build
+
+# Verify package
+twine check dist/*
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+For TestPyPI first:
+
+```bash
+twine upload --repository testpypi dist/*
+pip install --index-url https://test.pypi.org/simple/ gunspec
+```
+
+## Development
+
+```bash
+cd packages/sdk-python
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# Run tests
+python -m pytest
+
+# Lint
+ruff check src/
+
+# Type check
+mypy src/gunspec/
+```
+
+## License
+
+MIT

gunspec-0.1.0/README.md

@@ -0,0 +1,178 @@
+# gunspec
+
+Official Python SDK for the [GunSpec.io](https://gunspec.io) firearms specification database API.
+
+## Installation
+
+```bash
+pip install gunspec
+```
+
+## Quick Start
+
+```python
+from gunspec import GunSpec
+
+# Reads GUNSPEC_API_KEY from environment automatically
+client = GunSpec()
+
+# List firearms
+result = client.firearms.list({"category": "pistol", "manufacturer": "glock"})
+for firearm in result.data:
+    print(firearm["name"], firearm["caliber"])
+
+# Get a single firearm
+result = client.firearms.get("glock-g17")
+print(result.data["name"])
+```
+
+## Async Usage
+
+```python
+from gunspec import AsyncGunSpec
+
+async with AsyncGunSpec() as client:
+    result = await client.firearms.list({"category": "rifle"})
+    for firearm in result.data:
+        print(firearm["name"])
+```
+
+## Configuration
+
+```python
+from gunspec import GunSpec, RetryConfig
+
+# Reads GUNSPEC_API_KEY from env automatically
+client = GunSpec()
+
+# Or configure explicitly
+client = GunSpec(
+    api_key="gs_...",                         # or set GUNSPEC_API_KEY env var
+    base_url="https://api.gunspec.io",        # default
+    timeout=30.0,                              # 30s default
+    retry=RetryConfig(
+        max_retries=2,                         # default
+        initial_delay_s=0.5,                   # default
+    ),
+)
+```
+
+## Resources
+
+| Resource | Methods |
+|----------|---------|
+| `client.firearms` | `list`, `get`, `search`, `compare`, `game_meta`, `action_types`, `filter_options`, `random`, `top`, `head_to_head`, `by_feature`, `by_action`, `by_material`, `by_designer`, `power_rating`, `timeline`, `by_conflict`, `get_variants`, `get_images`, `get_game_stats`, `get_dimensions`, `get_users`, `get_family_tree`, `get_similar`, `get_adoption_map`, `get_game_profile`, `get_silhouette`, `calculate`, `load`, `list_auto_paging` |
+| `client.manufacturers` | `list`, `get`, `get_firearms`, `get_timeline`, `get_stats`, `list_auto_paging` |
+| `client.calibers` | `list`, `get`, `compare`, `ballistics`, `get_firearms`, `get_parent_chain`, `get_family`, `get_ammunition`, `list_auto_paging` |
+| `client.categories` | `list`, `get_firearms` |
+| `client.stats` | `summary`, `production_status`, `field_coverage`, `popular_calibers`, `prolific_manufacturers`, `by_category`, `by_era`, `materials`, `adoption_by_country`, `adoption_by_type`, `action_types`, `feature_frequency`, `caliber_popularity_by_era` |
+| `client.game` | `balance_report`, `tier_list`, `matchups`, `role_roster`, `stat_distribution` |
+| `client.game_stats` | `list_versions`, `list_firearms`, `get_firearm` |
+| `client.ammunition` | `list`, `get`, `get_bullet_svg`, `ballistics`, `list_auto_paging` |
+| `client.countries` | `list`, `get_arsenal` |
+| `client.conflicts` | `list` |
+| `client.data_quality` | `coverage`, `confidence` |
+| `client.favorites` | `list`, `add`, `remove` |
+| `client.reports` | `create`, `list` |
+| `client.support` | `create`, `list`, `get`, `reply` |
+| `client.webhooks` | `list`, `create`, `get`, `update`, `delete`, `test` |
+| `client.usage` | `get` |
+
+## Auto-Pagination
+
+```python
+# Sync
+for firearm in client.firearms.list_auto_paging({"category": "rifle"}):
+    print(firearm["name"])
+
+# Async
+async for firearm in client.firearms.list_auto_paging({"category": "rifle"}):
+    print(firearm["name"])
+```
+
+## Error Handling
+
+```python
+from gunspec import (
+    GunSpec,
+    NotFoundError,
+    RateLimitError,
+    AuthenticationError,
+)
+
+client = GunSpec()
+
+try:
+    result = client.firearms.get("nonexistent")
+except NotFoundError as e:
+    print(f"Not found: {e.message}")
+    print(f"Request ID: {e.request_id}")
+except RateLimitError as e:
+    print(f"Retry after: {e.retry_after}s")
+except AuthenticationError:
+    print("Invalid API key")
+```
+
+## Context Managers
+
+```python
+# Sync
+with GunSpec() as client:
+    result = client.firearms.list()
+
+# Async
+async with AsyncGunSpec() as client:
+    result = await client.firearms.list()
+```
+
+## Requirements
+
+- Python >= 3.9
+- httpx >= 0.25
+- pydantic >= 2
+
+## Publishing
+
+```bash
+cd packages/sdk-python
+
+# Install build tools
+pip install build twine
+
+# Build sdist and wheel
+python -m build
+
+# Verify package
+twine check dist/*
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+For TestPyPI first:
+
+```bash
+twine upload --repository testpypi dist/*
+pip install --index-url https://test.pypi.org/simple/ gunspec
+```
+
+## Development
+
+```bash
+cd packages/sdk-python
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# Run tests
+python -m pytest
+
+# Lint
+ruff check src/
+
+# Type check
+mypy src/gunspec/
+```
+
+## License
+
+MIT

gunspec-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gunspec"
+version = "0.1.0"
+description = "Python SDK for the GunSpec.io firearms specification API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "GunSpec.io" },
+]
+keywords = ["gunspec", "firearms", "api", "sdk", "specifications", "database"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "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",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25,<1",
+    "pydantic>=2,<3",
+]
+
+[project.urls]
+Homepage = "https://gunspec.io"
+Documentation = "https://gunspec.io/docs"
+Repository = "https://github.com/buun-group/gunspec"
+Issues = "https://github.com/buun-group/gunspec/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "mypy>=1.0",
+    "ruff>=0.1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gunspec"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+
+[tool.ruff]
+target-version = "py39"

gunspec-0.1.0/src/gunspec/__init__.py

@@ -0,0 +1,57 @@
+"""GunSpec.io Python SDK."""
+
+from __future__ import annotations
+
+from gunspec._client import AsyncGunSpec, GunSpec
+from gunspec._core._errors import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectError,
+    GunSpecError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    RequestTimeoutError,
+)
+from gunspec._core._http_client import (
+    APIResponse,
+    HttpClientConfig,
+    PaginatedResponse,
+    PaginationMeta,
+    RateLimitInfo,
+)
+from gunspec._core._pagination import AsyncPage, SyncPage
+from gunspec._core._retry import RetryConfig
+from gunspec._version import __version__
+
+__all__ = [
+    # Client
+    "GunSpec",
+    "AsyncGunSpec",
+    # Version
+    "__version__",
+    # Config
+    "HttpClientConfig",
+    "RetryConfig",
+    # Response types
+    "APIResponse",
+    "PaginatedResponse",
+    "PaginationMeta",
+    "RateLimitInfo",
+    # Pagination
+    "SyncPage",
+    "AsyncPage",
+    # Errors
+    "GunSpecError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "BadRequestError",
+    "RateLimitError",
+    "InternalServerError",
+    "ConnectError",
+    "RequestTimeoutError",
+]