craaft 1.0.0__tar.gz

craaft-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Upload Package to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/craaft/
+    needs:
+      - release-build
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+            password: ${{ secrets.PYPI_API_TOKEN }}

craaft-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,36 @@
+name: Test Python SDK
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install flake8 pytest
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+        pip install ".[dev]"
+    - name: Lint with flake8
+      run: |
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Test with pytest
+      run: |
+        pytest

craaft-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+htmlcov/
+.coverage
+docs/

craaft-1.0.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: craaft
+Version: 1.0.0
+Summary: Python client for the Craaft API.
+Project-URL: Homepage, https://craaft.io
+Project-URL: Source, https://github.com/craaft/python-sdk
+Project-URL: Issues, https://github.com/craaft/python-sdk/issues
+Author-email: Sean Nieuwoudt <sean@underwulf.com>
+License-Expression: MIT
+Keywords: api,client,craaft,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.32
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Craaft Python SDK
+
+A small, synchronous Python client for the [Craaft API](https://craaft.io). It wraps the REST endpoints with typed dataclasses, a sensible retry policy, and a friendly exception hierarchy.
+
+## Install
+
+```bash
+pip install craaft
+```
+
+Python 3.10 or newer.
+
+## Quickstart
+
+```python
+from datetime import datetime, timedelta, timezone
+
+from craaft import CraaftClient
+
+# Reads CRAAFT_API_TOKEN (and optionally CRAAFT_BASE_URL) from the environment.
+with CraaftClient() as client:
+    me = client.me.get()
+    print(f"Hi {me.name}")
+
+    project = client.projects.create(name="Demo", description="A new board")
+
+    card = client.projects.create_card(
+        project.id,
+        title="Ship the SDK",
+        column="todo",
+        position=1.0,
+        description="all the bits",
+    )
+
+    # Some fields (priority, due_date, size) are best set via PATCH after
+    # the card exists, since POST drops them on some server builds.
+    client.cards.update(
+        card.id,
+        priority="high",
+        due_date=datetime.now(timezone.utc) + timedelta(days=7),
+    )
+
+    client.cards.add_comment(card.id, body="lgtm")
+
+    # upcoming() and search() return CardSummary previews, not full cards.
+    for summary in client.cards.upcoming():
+        print(summary.title, summary.due_date, summary.project_name)
+```
+
+## Examples
+
+The [`examples/`](examples/) directory has runnable scripts for the most common patterns. Each one is self-contained and cleans up after itself, so they're safe to run repeatedly:
+
+| File | What it shows |
+|------|---------------|
+| [`quickstart.py`](examples/quickstart.py) | Sign in, create a card, leave a comment. |
+| [`card_lifecycle.py`](examples/card_lifecycle.py) | Create, set priority and due date via PATCH, comment, move between columns, delete. |
+| [`error_handling.py`](examples/error_handling.py) | Which exceptions to catch and what fields they carry. |
+| [`retries.py`](examples/retries.py) | Tuning `RetryConfig` and reacting to `RateLimitError` yourself. |
+| [`searching.py`](examples/searching.py) | `cards.search()` and `cards.upcoming()`, both returning `CardSummary`. |
+| [`advanced_client.py`](examples/advanced_client.py) | Custom session, alternate base URL, user-agent, debug logging. |
+
+Set `CRAAFT_API_TOKEN` (and optionally `CRAAFT_BASE_URL`) in your environment, then `python examples/quickstart.py`.
+
+## Configuration
+
+```python
+from craaft import CraaftClient, RetryConfig
+
+client = CraaftClient(
+    api_key="cra_...",                     # or CRAAFT_API_TOKEN env var
+    base_url="https://craaft.io/api/v1",   # or CRAAFT_BASE_URL env var (default: prod)
+    timeout=30.0,                          # seconds, or (connect, read) tuple
+    retry=RetryConfig(max_attempts=5),     # or retry=None to disable
+    user_agent="my-app/1.0",
+)
+```
+
+## Resources
+
+| Sub-client          | Methods |
+|---------------------|---------|
+| `client.me`         | `get()`, `update(name=, email=, username=)` |
+| `client.projects`   | `list()`, `get(id)`, `create(name=, description=)`, `update(id, ...)`, `delete(id)`, `list_cards(id)`, `create_card(id, title=, column=, position=, ...)`, `add_column(id, title=)` |
+| `client.cards`      | `update(id, ...)`, `delete(id)`, `upcoming()`, `search(q=, limit=20)`, `list_comments(id)`, `add_comment(id, body=)` |
+| `client.comments`   | `update(id, body=)`, `delete(id)` |
+| `client.columns`    | `update(id, ...)`, `delete(id)` |
+
+`upcoming()` and `search()` return `list[CardSummary]` - lightweight previews with `project_name`, `column_key`, and `column_title`. Every other read returns a full `Card`.
+
+## Models
+
+Frozen dataclasses, keyword-only:
+
+- `User` - id, email, name, username, avatar_url, has_password
+- `Project` - id, workspace_id, name, description, is_favorite, public_token, custom_css, background_image, color_scheme, text_color, total_cards, column_counts, columns, created_at, updated_at
+- `Column` - id, key, title, color, position, is_done, card_limit
+- `Card` - id, project_id, column, title, position, description, due_date, assigned_user_id, size, priority, created_by, attachment_count, created_at, updated_at
+- `CardSummary` - id, project_id, project_name, column_key, column_title, title, description, due_date, assigned_user_id, priority, updated_at
+- `Comment` - id, card_id, author_id, body, created_at, updated_at
+
+`due_date` is a timezone-aware `datetime`. Naive datetimes you pass in are treated as UTC.
+
+## Errors
+
+```python
+from craaft import CraaftAPIError, NotFoundError, RateLimitError
+
+try:
+    client.projects.get("missing")
+except NotFoundError:
+    ...
+except RateLimitError as e:
+    sleep(e.retry_after or 1)
+except CraaftAPIError as e:
+    print(e.status_code, e.message, e.request_id)
+```
+
+Hierarchy: `CraaftError` is the root. API failures raise `CraaftAPIError` or one of its subclasses (`AuthenticationError`, `PermissionError`, `NotFoundError`, `ConflictError`, `PlanLimitError`, `ValidationError`, `RateLimitError`, `ServerError`). Network failures raise `CraaftConnectionError` or `CraaftTimeoutError`.
+
+## Retries
+
+The client retries `429`, `502`, `503`, `504`, and network errors with exponential backoff and `Retry-After`-aware pauses. Writes (`POST` / `PATCH` / `DELETE`) skip 5xx retries by default, since the server may have applied the change before responding. Set `RetryConfig(retry_writes_on_5xx=True)` if your workload is safe to retry.
+
+## Logging
+
+The client logs one DEBUG line per HTTP attempt (method, path, status, duration, attempt number) on the `craaft` logger. The auth header is never logged.
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+logging.getLogger("craaft").setLevel(logging.DEBUG)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check
+mypy
+```
+
+## License
+
+MIT

craaft-1.0.0/README.md

@@ -0,0 +1,146 @@
+# Craaft Python SDK
+
+A small, synchronous Python client for the [Craaft API](https://craaft.io). It wraps the REST endpoints with typed dataclasses, a sensible retry policy, and a friendly exception hierarchy.
+
+## Install
+
+```bash
+pip install craaft
+```
+
+Python 3.10 or newer.
+
+## Quickstart
+
+```python
+from datetime import datetime, timedelta, timezone
+
+from craaft import CraaftClient
+
+# Reads CRAAFT_API_TOKEN (and optionally CRAAFT_BASE_URL) from the environment.
+with CraaftClient() as client:
+    me = client.me.get()
+    print(f"Hi {me.name}")
+
+    project = client.projects.create(name="Demo", description="A new board")
+
+    card = client.projects.create_card(
+        project.id,
+        title="Ship the SDK",
+        column="todo",
+        position=1.0,
+        description="all the bits",
+    )
+
+    # Some fields (priority, due_date, size) are best set via PATCH after
+    # the card exists, since POST drops them on some server builds.
+    client.cards.update(
+        card.id,
+        priority="high",
+        due_date=datetime.now(timezone.utc) + timedelta(days=7),
+    )
+
+    client.cards.add_comment(card.id, body="lgtm")
+
+    # upcoming() and search() return CardSummary previews, not full cards.
+    for summary in client.cards.upcoming():
+        print(summary.title, summary.due_date, summary.project_name)
+```
+
+## Examples
+
+The [`examples/`](examples/) directory has runnable scripts for the most common patterns. Each one is self-contained and cleans up after itself, so they're safe to run repeatedly:
+
+| File | What it shows |
+|------|---------------|
+| [`quickstart.py`](examples/quickstart.py) | Sign in, create a card, leave a comment. |
+| [`card_lifecycle.py`](examples/card_lifecycle.py) | Create, set priority and due date via PATCH, comment, move between columns, delete. |
+| [`error_handling.py`](examples/error_handling.py) | Which exceptions to catch and what fields they carry. |
+| [`retries.py`](examples/retries.py) | Tuning `RetryConfig` and reacting to `RateLimitError` yourself. |
+| [`searching.py`](examples/searching.py) | `cards.search()` and `cards.upcoming()`, both returning `CardSummary`. |
+| [`advanced_client.py`](examples/advanced_client.py) | Custom session, alternate base URL, user-agent, debug logging. |
+
+Set `CRAAFT_API_TOKEN` (and optionally `CRAAFT_BASE_URL`) in your environment, then `python examples/quickstart.py`.
+
+## Configuration
+
+```python
+from craaft import CraaftClient, RetryConfig
+
+client = CraaftClient(
+    api_key="cra_...",                     # or CRAAFT_API_TOKEN env var
+    base_url="https://craaft.io/api/v1",   # or CRAAFT_BASE_URL env var (default: prod)
+    timeout=30.0,                          # seconds, or (connect, read) tuple
+    retry=RetryConfig(max_attempts=5),     # or retry=None to disable
+    user_agent="my-app/1.0",
+)
+```
+
+## Resources
+
+| Sub-client          | Methods |
+|---------------------|---------|
+| `client.me`         | `get()`, `update(name=, email=, username=)` |
+| `client.projects`   | `list()`, `get(id)`, `create(name=, description=)`, `update(id, ...)`, `delete(id)`, `list_cards(id)`, `create_card(id, title=, column=, position=, ...)`, `add_column(id, title=)` |
+| `client.cards`      | `update(id, ...)`, `delete(id)`, `upcoming()`, `search(q=, limit=20)`, `list_comments(id)`, `add_comment(id, body=)` |
+| `client.comments`   | `update(id, body=)`, `delete(id)` |
+| `client.columns`    | `update(id, ...)`, `delete(id)` |
+
+`upcoming()` and `search()` return `list[CardSummary]` - lightweight previews with `project_name`, `column_key`, and `column_title`. Every other read returns a full `Card`.
+
+## Models
+
+Frozen dataclasses, keyword-only:
+
+- `User` - id, email, name, username, avatar_url, has_password
+- `Project` - id, workspace_id, name, description, is_favorite, public_token, custom_css, background_image, color_scheme, text_color, total_cards, column_counts, columns, created_at, updated_at
+- `Column` - id, key, title, color, position, is_done, card_limit
+- `Card` - id, project_id, column, title, position, description, due_date, assigned_user_id, size, priority, created_by, attachment_count, created_at, updated_at
+- `CardSummary` - id, project_id, project_name, column_key, column_title, title, description, due_date, assigned_user_id, priority, updated_at
+- `Comment` - id, card_id, author_id, body, created_at, updated_at
+
+`due_date` is a timezone-aware `datetime`. Naive datetimes you pass in are treated as UTC.
+
+## Errors
+
+```python
+from craaft import CraaftAPIError, NotFoundError, RateLimitError
+
+try:
+    client.projects.get("missing")
+except NotFoundError:
+    ...
+except RateLimitError as e:
+    sleep(e.retry_after or 1)
+except CraaftAPIError as e:
+    print(e.status_code, e.message, e.request_id)
+```
+
+Hierarchy: `CraaftError` is the root. API failures raise `CraaftAPIError` or one of its subclasses (`AuthenticationError`, `PermissionError`, `NotFoundError`, `ConflictError`, `PlanLimitError`, `ValidationError`, `RateLimitError`, `ServerError`). Network failures raise `CraaftConnectionError` or `CraaftTimeoutError`.
+
+## Retries
+
+The client retries `429`, `502`, `503`, `504`, and network errors with exponential backoff and `Retry-After`-aware pauses. Writes (`POST` / `PATCH` / `DELETE`) skip 5xx retries by default, since the server may have applied the change before responding. Set `RetryConfig(retry_writes_on_5xx=True)` if your workload is safe to retry.
+
+## Logging
+
+The client logs one DEBUG line per HTTP attempt (method, path, status, duration, attempt number) on the `craaft` logger. The auth header is never logged.
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+logging.getLogger("craaft").setLevel(logging.DEBUG)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check
+mypy
+```
+
+## License
+
+MIT

craaft-1.0.0/examples/README.md

@@ -0,0 +1,28 @@
+# Examples
+
+Runnable scripts that show how to use the SDK against a real Craaft API.
+
+Set your token first:
+
+```bash
+export CRAAFT_API_TOKEN=cra_...
+# optional: point at a local server
+export CRAAFT_BASE_URL=http://localhost:8080/api/v1
+```
+
+Then run any example:
+
+```bash
+python examples/quickstart.py
+```
+
+| File | What it shows |
+|------|---------------|
+| `quickstart.py` | The shortest path to do something useful: list projects, create a card, leave a comment. |
+| `card_lifecycle.py` | The full flow for a card: create, set priority/size/due date via PATCH, comment, delete. |
+| `error_handling.py` | Which exceptions to catch and how to read the fields they carry. |
+| `retries.py` | Tuning `RetryConfig` and reacting to `RateLimitError`. |
+| `searching.py` | `cards.search()` and `cards.upcoming()`, both of which return `CardSummary`. |
+| `advanced_client.py` | Custom session, debug logging, and pointing the client at a different base URL. |
+
+Each script is self-contained and prints what it did, so you can read along while it runs. None of them write any data they don't clean up themselves.

craaft-1.0.0/examples/advanced_client.py

@@ -0,0 +1,72 @@
+"""Configuring the client beyond the defaults.
+
+Everything you can pass to `CraaftClient` and what it's good for. Useful
+when you're integrating with an existing service that already has its own
+HTTP setup, proxy rules, or logging conventions.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import requests
+
+from craaft import CraaftClient, RetryConfig
+
+
+def with_custom_session() -> CraaftClient:
+    """Inject a pre-configured `requests.Session`.
+
+    Useful for a corporate proxy, a custom retry adapter, mTLS certs, or
+    anything else you'd normally configure on a Session.
+    """
+    session = requests.Session()
+    session.proxies.update({
+        "https": "http://proxy.example.com:3128",
+    })
+    # session.verify = "/etc/ssl/certs/internal-ca.pem"
+    return CraaftClient(session=session)
+
+
+def with_local_server() -> CraaftClient:
+    """Point at a local instance during development."""
+    return CraaftClient(base_url="http://localhost:8080/api/v1")
+
+
+def with_named_user_agent() -> CraaftClient:
+    """Set a User-Agent so server-side logs can tell your app apart from
+    other consumers of the SDK."""
+    return CraaftClient(user_agent="acme-sync-worker/2.4.1")
+
+
+def with_separate_connect_and_read_timeouts() -> CraaftClient:
+    """A short connect timeout and a longer read timeout is a sensible
+    default when you want to fail fast on unreachable hosts but tolerate
+    a slow response."""
+    return CraaftClient(timeout=(3.0, 30.0))
+
+
+def with_debug_logging() -> CraaftClient:
+    """Turn on per-attempt logging.
+
+    The `craaft` logger emits one DEBUG line per HTTP attempt with the
+    method, path, status, duration, and attempt number. The Authorization
+    header is never logged.
+    """
+    logging.basicConfig(level=logging.DEBUG)
+    logging.getLogger("craaft").setLevel(logging.DEBUG)
+    return CraaftClient()
+
+
+def main() -> None:
+    with CraaftClient(
+        timeout=(3.0, 30.0),
+        user_agent="examples/advanced_client.py",
+        retry=RetryConfig(max_attempts=4),
+    ) as client:
+        me = client.me.get()
+        print(f"OK as {me.username}")
+
+
+if __name__ == "__main__":
+    main()

craaft-1.0.0/examples/card_lifecycle.py

@@ -0,0 +1,65 @@
+"""The full flow for a card.
+
+The Craaft API accepts most card fields on PATCH, so the practical pattern
+is: create with the basics, then update to set priority, size, and due
+date. This script walks through that flow, adds a comment, and deletes
+everything at the end.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+from craaft import CraaftClient
+
+
+def main() -> None:
+    with CraaftClient() as client:
+        projects = client.projects.list()
+        if not projects:
+            print("Create a project in the app first.")
+            return
+        project = client.projects.get(projects[0].id)
+        column = project.columns[0]
+
+        # Step 1: create with the bare essentials.
+        card = client.projects.create_card(
+            project.id,
+            title="Migrate the billing service",
+            column=column.key,
+            position=0.0,
+            description="Part of the Q3 reliability work.",
+        )
+        print(f"Created card {card.id}")
+
+        # Step 2: set priority and a due date a week out. PATCH is where
+        # these stick reliably (POST drops them on some server builds).
+        due = datetime.now(timezone.utc) + timedelta(days=7)
+        card = client.cards.update(
+            card.id,
+            priority="high",
+            due_date=due,
+        )
+        print(f"  priority={card.priority} due={card.due_date}")
+
+        # Step 3: leave a comment, then edit it.
+        comment = client.cards.add_comment(card.id, body="Kicking this off")
+        print(f"Posted comment {comment.id}")
+
+        comment = client.comments.update(comment.id, body="Kicking this off today")
+        print(f"  edited: {comment.body!r}")
+
+        # Step 4: move the card to the next column (if there is one).
+        if len(project.columns) > 1:
+            next_col = project.columns[1]
+            card = client.cards.update(card.id, column=next_col.key, position=0.0)
+            print(f"Moved card to {next_col.title!r}")
+
+        # Cleanup.
+        client.comments.delete(comment.id)
+        client.cards.delete(card.id)
+        print("Cleaned up.")
+
+
+if __name__ == "__main__":
+    main()

craaft-1.0.0/examples/error_handling.py

@@ -0,0 +1,67 @@
+"""Which exceptions to catch.
+
+Every API failure raises a subclass of `CraaftAPIError`, and every API
+error carries `status_code`, `message`, `response_body`, and `request_id`
+fields. Network failures raise `CraaftConnectionError` or
+`CraaftTimeoutError` instead.
+"""
+
+from __future__ import annotations
+
+from craaft import (
+    AuthenticationError,
+    ConflictError,
+    CraaftAPIError,
+    CraaftClient,
+    CraaftConnectionError,
+    CraaftTimeoutError,
+    NotFoundError,
+    PlanLimitError,
+    RateLimitError,
+    ValidationError,
+)
+
+
+def main() -> None:
+    with CraaftClient() as client:
+        # 404: easy to reproduce by asking for a project that doesn't exist.
+        try:
+            client.projects.get("00000000-0000-0000-0000-000000000000")
+        except NotFoundError as e:
+            print(f"NotFoundError: status={e.status_code}, message={e.message!r}")
+
+        # If you ever hit your plan limit, you'll see this on POST /projects.
+        try:
+            client.projects.create(name="Example")
+        except PlanLimitError as e:
+            print(f"PlanLimitError: {e.message} (status {e.status_code})")
+        except CraaftAPIError as e:
+            # If the create succeeded, clean it up so the example is idempotent.
+            print(f"Created project; cleaning it up. ({type(e).__name__})")
+
+        # Catching the base class is fine when you don't need to branch.
+        try:
+            client.cards.search(q="anything", limit=10)
+        except CraaftAPIError as e:
+            print(f"Search failed: {e}")
+
+    # Things that aren't API errors:
+    #   AuthenticationError - 401 (bad or missing token)
+    #   ValidationError     - 400 / 422 (bad request body)
+    #   ConflictError       - 409 (e.g. deleting a column that still has cards)
+    #   RateLimitError      - 429 (carries `.retry_after` in seconds)
+    #   CraaftConnectionError - DNS / TLS / connection refused
+    #   CraaftTimeoutError    - request didn't finish in time
+
+    _ = (
+        AuthenticationError,
+        ValidationError,
+        ConflictError,
+        RateLimitError,
+        CraaftConnectionError,
+        CraaftTimeoutError,
+    )
+
+
+if __name__ == "__main__":
+    main()