python-kanka 2.2.0__tar.gz → 2.4.0__tar.gz

{python_kanka-2.2.0 → python_kanka-2.4.0}/.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 2.2.0
+current_version = 2.4.0
 commit = True
 tag = True
 tag_name = v{new_version}
@@ -8,3 +8,7 @@ message = Bump version: {current_version} → {new_version}
 [bumpversion:file:src/kanka/_version.py]
 search = __version__ = "{current_version}"
 replace = __version__ = "{new_version}"
+
+[bumpversion:file:pyproject.toml]
+search = version = "{current_version}"
+replace = version = "{new_version}"

{python_kanka-2.2.0 → python_kanka-2.4.0}/.github/renovate.json

@@ -7,7 +7,8 @@
     ":disableRateLimiting",
     ":separateMajorReleases",
     ":combinePatchMinorReleases",
-    ":ignoreUnstable"
+    ":ignoreUnstable",
+    ":pinVersions"
   ],
   "timezone": "America/Chicago",
   "assignees": [

{python_kanka-2.2.0 → python_kanka-2.4.0}/.github/workflows/ci.yml

@@ -12,42 +12,36 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.12", "3.13", "3.14"]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
       with:
-        python-version: ${{ matrix.python-version }}
+        enable-cache: true
+        cache-dependency-glob: "uv.lock"
 
-    - name: Cache pip dependencies
-      uses: actions/cache@v4
-      with:
-        path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt', '**/dev-requirements.txt') }}
-        restore-keys: |
-          ${{ runner.os }}-pip-
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
 
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
-        pip install -r requirements.txt
-        pip install -r dev-requirements.txt
-        pip install -e .
+        uv sync --all-groups
+        uv pip install -e .
 
     - name: Run all quality checks
       run: |
         make check
 
     - name: Generate coverage report
-      if: matrix.python-version == '3.11'
+      if: matrix.python-version == '3.14'
       run: |
         make coverage
 
     - name: Upload coverage reports to Codecov
-      if: matrix.python-version == '3.11'
+      if: matrix.python-version == '3.14'
       uses: codecov/codecov-action@v5
       env:
         CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

{python_kanka-2.2.0 → python_kanka-2.4.0}/.github/workflows/publish.yml

@@ -16,22 +16,24 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.12", "3.13", "3.14"]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
       with:
-        python-version: ${{ matrix.python-version }}
+        enable-cache: true
+        cache-dependency-glob: "uv.lock"
+
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
 
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
-        pip install -r requirements.txt
-        pip install -r dev-requirements.txt
-        pip install -e .
+        uv sync --all-groups
+        uv pip install -e .
 
     - name: Run all quality checks
       run: |
@@ -41,26 +43,20 @@ jobs:
     needs: test
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.13'
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
 
-    - name: Install build dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install build twine
+    - name: Set up Python
+      run: uv python install 3.14
 
     - name: Build package
-      run: python -m build
-
-    - name: Check package
-      run: twine check dist/*
+      run: |
+        uv build
 
     - name: Upload artifacts
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v5
       with:
         name: dist
         path: dist/
@@ -75,7 +71,7 @@ jobs:
 
     steps:
     - name: Download artifacts
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v6
       with:
         name: dist
         path: dist/

{python_kanka-2.2.0 → python_kanka-2.4.0}/.gitignore

@@ -111,6 +111,7 @@ celerybeat.pid
 
 # Environments
 .env
+.envrc
 .venv
 env/
 venv/

{python_kanka-2.2.0 → python_kanka-2.4.0}/.pre-commit-config.yaml

@@ -2,7 +2,7 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v6.0.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -15,19 +15,19 @@ repos:
       - id: mixed-line-ending
 
   - repo: https://github.com/psf/black
-    rev: 23.12.1
+    rev: 26.1.0
     hooks:
       - id: black
         language_version: python3
 
   - repo: https://github.com/pycqa/isort
-    rev: 5.13.2
+    rev: 8.0.0
     hooks:
       - id: isort
         args: ["--profile", "black"]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.9
+    rev: v0.15.2
     hooks:
       - id: ruff
         args: ["--fix"]

{python_kanka-2.2.0 → python_kanka-2.4.0}/CLAUDE.md

@@ -4,10 +4,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Key Development Commands
 
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management. All commands are wrapped in the Makefile for convenience:
+
 ```bash
-# Install development environment
+# Install development environment (uses uv sync)
 make install
 
+# Sync dependencies without updating lock file
+make sync
+
 # Run unit tests only (no integration tests)
 make test
 
@@ -31,12 +36,67 @@ make typecheck
 make check
 
 # Build the package
-python -m build
+make build
 
 # Generate coverage report
 make coverage
 ```
 
+### Direct uv commands
+
+```bash
+# Install dependencies
+uv sync --all-groups
+
+# Run a command in the environment
+uv run pytest
+
+# Add a new dependency
+uv add package-name
+
+# Add a dev dependency
+uv add --group dev package-name
+
+# Update dependencies
+uv lock --upgrade
+
+# Build the package
+uv build
+```
+
+## Git Commit Message Format
+
+This project uses conventional commits format:
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only changes
+- `style`: Code style changes (formatting, missing semicolons, etc)
+- `refactor`: Code change that neither fixes a bug nor adds a feature
+- `test`: Adding missing tests or correcting existing tests
+- `chore`: Changes to build process, dependencies, or auxiliary tools
+
+**Examples:**
+- `feat: add pagination properties to EntityManager`
+- `fix: replace is_private with visibility_id parameter for posts`
+- `chore(deps): update dependency ruff to v0.11.13`
+- `refactor: reorganize package structure for PyPI publishing`
+
+**Note:** When Claude generates commits, they should include the attribution at the end of the commit body:
+```
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
 ## Architecture Overview
 
 The SDK follows a **Client → Manager → Model** pattern that requires understanding across multiple files:
@@ -118,25 +178,35 @@ When testing against the real API:
 
 **CRITICAL**: When making ANY changes to the API, models, exceptions, or client behavior:
 
-1. **Always update API_REFERENCE.md** to reflect:
-   - New/changed model fields and their types
-   - New/changed method signatures
-   - New/changed exception types
-   - New/changed client constructor parameters
-   - Any breaking changes or deprecations
+1. **Always update the relevant files in `docs/`** to reflect:
+   - New/changed model fields and their types → `docs/entity-types-reference.md` and `docs/api-reference.md`
+   - New/changed method signatures → `docs/api-reference.md` and the relevant guide page
+   - New/changed exception types → `docs/error-handling.md` and `docs/api-reference.md`
+   - New/changed client constructor parameters → `docs/api-reference.md`
+   - New features or usage patterns → the relevant guide page in `docs/`
 
-2. **Always update README.md** when changes affect:
+2. **Always update `README.md`** when changes affect:
    - Installation instructions
    - Basic usage examples
    - Key features or capabilities
-   - Version compatibility
 
 3. **Documentation must be 100% accurate** - inconsistencies between docs and implementation cause significant user confusion
 
 4. **Remove deprecated features** - don't just mark as deprecated, actively remove outdated documentation when legacy code is removed
 
-**Example workflow:**
-- Add new model field → Update API_REFERENCE.md model documentation
-- Change method signature → Update API_REFERENCE.md method documentation
-- Remove deprecated exception → Remove from API_REFERENCE.md exceptions section
-- Add new client feature → Update both README.md and API_REFERENCE.md
+**Documentation structure:**
+- `docs/README.md` — Index page linking to all docs
+- `docs/getting-started.md` — Installation and quick start
+- `docs/core-concepts.md` — Architecture and key concepts
+- `docs/entities.md` — CRUD operations guide
+- `docs/entity-types-reference.md` — All entity type fields
+- `docs/posts.md` — Posts management
+- `docs/assets-and-images.md` — Assets, images, automatic image management
+- `docs/gallery.md` — Campaign gallery
+- `docs/search-and-filtering.md` — Search and filtering
+- `docs/pagination.md` — Pagination
+- `docs/error-handling.md` — Exception types and patterns
+- `docs/rate-limiting.md` — Rate limit configuration
+- `docs/api-reference.md` — Complete API reference
+- `docs/debug-mode.md` — Debug mode
+- `docs/known-limitations.md` — API quirks and gotchas

{python_kanka-2.2.0 → python_kanka-2.4.0}/Makefile

@@ -1,9 +1,10 @@
-.PHONY: install test lint format typecheck check clean coverage help
+.PHONY: install test lint format typecheck check clean coverage help sync build
 
 # Default target
 help:
 	@echo "Available commands:"
-	@echo "  make install   - Install development dependencies"
+	@echo "  make install   - Install development dependencies with uv"
+	@echo "  make sync      - Sync dependencies with uv.lock"
 	@echo "  make test      - Run all tests"
 	@echo "  make lint      - Run code linting"
 	@echo "  make typecheck - Run type checking with mypy"
@@ -11,36 +12,39 @@ help:
 	@echo "  make check     - Run all checks (lint + typecheck + test)"
 	@echo "  make clean     - Clean up temporary files"
 	@echo "  make coverage  - Run tests with coverage report"
+	@echo "  make build     - Build the package"
 
-# Install development dependencies
+# Install development dependencies and sync with lock file
 install:
-	pip install -r requirements.txt
-	pip install -r dev-requirements.txt
-	pip install -e .
+	uv sync --all-groups
+
+# Sync dependencies without updating lock file
+sync:
+	uv sync --all-groups
 
 # Run all tests
 test:
-	pytest tests/ -v
+	uv run pytest tests/ -v
 
 # Run linting
 lint:
-	ruff check .
-	black --check .
-	isort --check-only .
+	uv run ruff check .
+	uv run black --check .
+	uv run isort --check-only .
 
 # Run type checking
 typecheck:
-	mypy src/kanka tests examples --ignore-missing-imports
+	uv run mypy src/kanka tests --ignore-missing-imports
 
 # Format code
 format:
-	black .
-	isort .
-	ruff check --fix .
+	uv run black .
+	uv run isort .
+	uv run ruff check --fix .
 
 # Run pre-commit hooks on all files
 pre-commit:
-	pre-commit run --all-files
+	uv run pre-commit run --all-files
 
 # Run all checks
 check: lint typecheck test
@@ -62,4 +66,8 @@ clean:
 
 # Run tests with coverage
 coverage:
-	pytest tests/ -v --cov=src/kanka --cov-report=html --cov-report=term
+	uv run pytest tests/ -v --cov=src/kanka --cov-report=html --cov-report=term
+
+# Build the package
+build:
+	uv build

python_kanka-2.4.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: python-kanka
+Version: 2.4.0
+Summary: Python client for the Kanka API
+Project-URL: Homepage, https://github.com/ervwalter/python-kanka
+Project-URL: Documentation, https://github.com/ervwalter/python-kanka#readme
+Project-URL: Repository, https://github.com/ervwalter/python-kanka
+Project-URL: Issues, https://github.com/ervwalter/python-kanka/issues
+Author-email: Erv Walter <erv@ewal.net>
+License: MIT
+License-File: LICENSE
+Keywords: api,campaign,dnd,kanka,pathfinder,rpg,tabletop,ttrpg,worldbuilding
+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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment :: Role-Playing
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: requests-toolbelt==1.0.0
+Requires-Dist: requests==2.32.5
+Description-Content-Type: text/markdown
+
+# python-kanka
+
+A modern Python client for the [Kanka API](https://app.kanka.io/api-docs/1.0), the collaborative worldbuilding and campaign management platform.
+
+*Originally inspired by/forked from [Kathrin Weihe's python-kanka](https://github.com/rbtnx/python-kanka). Thank you to Kathrin for the foundation and inspiration.*
+
+## Features
+
+- **12 Entity Types**: Characters, Locations, Organisations, Families, Calendars, Events, Quests, Journals, Notes, Tags, Races, Creatures
+- **Type Safety**: Built with Pydantic v2 for data validation and type hints
+- **Consistent API**: Same CRUD interface across all entity types
+- **Posts, Assets & Images**: Full support for entity sub-resources and automatic image management
+- **Search & Filtering**: Search across types, filter by name/tags/privacy/dates
+- **Rate Limit Handling**: Automatic retry with exponential backoff
+- **Pagination**: Built-in pagination support with metadata
+
+## Installation
+
+```bash
+pip install python-kanka
+```
+
+## Quick Start
+
+```python
+from kanka import KankaClient
+
+client = KankaClient(token="your-api-token", campaign_id=12345)
+
+# Create a character
+gandalf = client.characters.create(
+    name="Gandalf the Grey",
+    type="Wizard",
+    title="Istari",
+)
+
+# List with filters
+wizards = client.characters.list(type="Wizard", is_private=False)
+
+# Search across all entity types
+results = client.search("dragon")
+
+# Update and delete
+gandalf = client.characters.update(gandalf, title="The White")
+client.characters.delete(gandalf)
+```
+
+## Documentation
+
+See the **[full documentation](docs/)** for guides, examples, and complete API reference.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Links
+
+- [Kanka.io](https://kanka.io) - The Kanka platform
+- [Kanka API Documentation](https://app.kanka.io/api-docs/1.0) - Official API docs
+- [GitHub Repository](https://github.com/ervwalter/python-kanka) - Source code
+- [Issue Tracker](https://github.com/ervwalter/python-kanka/issues) - Report bugs or request features

python_kanka-2.4.0/README.md

@@ -0,0 +1,61 @@
+# python-kanka
+
+A modern Python client for the [Kanka API](https://app.kanka.io/api-docs/1.0), the collaborative worldbuilding and campaign management platform.
+
+*Originally inspired by/forked from [Kathrin Weihe's python-kanka](https://github.com/rbtnx/python-kanka). Thank you to Kathrin for the foundation and inspiration.*
+
+## Features
+
+- **12 Entity Types**: Characters, Locations, Organisations, Families, Calendars, Events, Quests, Journals, Notes, Tags, Races, Creatures
+- **Type Safety**: Built with Pydantic v2 for data validation and type hints
+- **Consistent API**: Same CRUD interface across all entity types
+- **Posts, Assets & Images**: Full support for entity sub-resources and automatic image management
+- **Search & Filtering**: Search across types, filter by name/tags/privacy/dates
+- **Rate Limit Handling**: Automatic retry with exponential backoff
+- **Pagination**: Built-in pagination support with metadata
+
+## Installation
+
+```bash
+pip install python-kanka
+```
+
+## Quick Start
+
+```python
+from kanka import KankaClient
+
+client = KankaClient(token="your-api-token", campaign_id=12345)
+
+# Create a character
+gandalf = client.characters.create(
+    name="Gandalf the Grey",
+    type="Wizard",
+    title="Istari",
+)
+
+# List with filters
+wizards = client.characters.list(type="Wizard", is_private=False)
+
+# Search across all entity types
+results = client.search("dragon")
+
+# Update and delete
+gandalf = client.characters.update(gandalf, title="The White")
+client.characters.delete(gandalf)
+```
+
+## Documentation
+
+See the **[full documentation](docs/)** for guides, examples, and complete API reference.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Links
+
+- [Kanka.io](https://kanka.io) - The Kanka platform
+- [Kanka API Documentation](https://app.kanka.io/api-docs/1.0) - Official API docs
+- [GitHub Repository](https://github.com/ervwalter/python-kanka) - Source code
+- [Issue Tracker](https://github.com/ervwalter/python-kanka/issues) - Report bugs or request features

python_kanka-2.4.0/docs/README.md

@@ -0,0 +1,55 @@
+# python-kanka Documentation
+
+A modern Python client for the [Kanka API](https://app.kanka.io/api-docs/1.0), the collaborative worldbuilding and campaign management platform.
+
+## Guides
+
+| Page | Description |
+|------|-------------|
+| [Getting Started](getting-started.md) | Installation, setup, and your first API call |
+| [Core Concepts](core-concepts.md) | Client-Manager-Model pattern, entity IDs, immutable models |
+| [Entity CRUD Operations](entities.md) | Create, read, update, and delete entities |
+| [Entity Types Reference](entity-types-reference.md) | All 12 entity types with their specific fields |
+| [Posts](posts.md) | Attach notes and comments to any entity |
+| [Search and Filtering](search-and-filtering.md) | Global search, entities endpoint, list filters |
+| [Pagination](pagination.md) | Navigate large result sets |
+| [Assets and Images](assets-and-images.md) | File/link/alias assets, entity images, automatic image management |
+| [Campaign Gallery](gallery.md) | Campaign-level image storage |
+| [Error Handling](error-handling.md) | Exception types and recommended patterns |
+| [Rate Limiting](rate-limiting.md) | Automatic retry behavior and configuration |
+| [Debug Mode](debug-mode.md) | Request/response logging for troubleshooting |
+| [Known Limitations](known-limitations.md) | API quirks and gotchas |
+
+## Reference
+
+| Page | Description |
+|------|-------------|
+| [API Reference](api-reference.md) | Complete reference for all classes, methods, and models |
+
+## Quick Example
+
+```python
+from kanka import KankaClient
+
+client = KankaClient(token="your-token", campaign_id=12345)
+
+# Create a character
+character = client.characters.create(
+    name="Gandalf",
+    type="Wizard",
+    title="The Grey",
+)
+
+# Search across all entities
+results = client.search("dragon")
+
+# List with filters
+npcs = client.characters.list(type="NPC", is_private=False)
+```
+
+## Links
+
+- [Kanka.io](https://kanka.io) — The Kanka platform
+- [Kanka API Docs](https://app.kanka.io/api-docs/1.0) — Official API documentation
+- [GitHub Repository](https://github.com/ervwalter/python-kanka) — Source code
+- [PyPI](https://pypi.org/project/python-kanka/) — Package page