pyquickbase 0.1.0a1__tar.gz → 0.2.0a1__tar.gz

{pyquickbase-0.1.0a1 → pyquickbase-0.2.0a1}/.github/workflows/ci.yml

@@ -25,6 +25,8 @@ jobs:
         run: uv run scripts/generate_sync.py --check
       - name: Build the package
         run: uv build
+      - name: Build the docs, failing on broken links
+        run: uv run --locked --group docs mkdocs build
 
   test:
     runs-on: ubuntu-latest

pyquickbase-0.2.0a1/.github/workflows/docs.yml

@@ -0,0 +1,37 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - run: uv run --locked --group docs mkdocs build
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

{pyquickbase-0.1.0a1 → pyquickbase-0.2.0a1}/.gitignore

@@ -9,6 +9,7 @@ __pycache__/
 .venv/
 build/
 dist/
+site/
 *.egg-info/
 
 # Tool caches

pyquickbase-0.2.0a1/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0a1] - 2026-11-02
+
+### Added
+
+- A documentation site.
+- Reports: `table.reports()`, `table.report()`, and `Report` with `run()`, `run_page()`, and
+  `info()`, plus `ReportInfo`, `UnknownReportError`, and `UnsupportedReportError`. Only table reports
+  can be read as records.
+- File attachments: `FileUpload` for writes, plus `table.download_file()` and
+  `table.delete_file_version()`.
+- `pyquickbase codegen`, which generates a typed class for each table, and `app.typed()`, which reads
+  and writes through those classes, including `query()`, `insert()`, `update()`, and `upsert()`. A
+  class that no longer matches its table raises `SchemaMismatchError`.
+- Formulas: `table.run_formula()`, which returns a `FormulaResult`, `formula=` on `create_field()` and
+  `update_field()`, and `Field.formula`.
+
+### Changed
+
+- `read_only` and `allowed_writes` clients now allow running formulas, with `POST /formula/run`.
+- A blank formula now raises `InvalidValueError` on `create_field()` and `update_field()`, including
+  through `properties`, because Quickbase accepts it on a formula field and empties the field's values.
+- A file attachment field now accepts only a `FileUpload`, and raises `InvalidValueError` for anything
+  else, including `None` and hand-built dictionaries, because Quickbase silently accepts those and
+  keeps or loses the file.
+- Writes are also split by size, to stay under Quickbase's 40 MiB request limit, so `batch_size` is
+  now an upper limit.
+- `read_only` and `allowed_writes` clients now allow running reports, with
+  `POST /reports/{id}/run`. This adds to the report's usage count in Quickbase, but changes no
+  records.
+- `Record.id` now explains what's missing when a report's records have no Record ID#. It still
+  raises `KeyError`.
+
+### Fixed
+
+- A rate limit error now includes Quickbase's message, which arrives in a different format.
+- A README example that was missing an import.
+
+## [0.1.0a1] - 2026-11-02
+
+First alpha release.
+
+### Added
+
+- `Quickbase` and `AsyncQuickbase` clients with `request()` for calling any endpoint.
+- `RetryPolicy`, with retries for HTTP 429 and connection failures.
+- The `QuickbaseError` exception hierarchy.
+- `qb.app()` and `app.table()`, with app, table, field, and relationship metadata and a schema cache.
+- `F` for building queries by field label, with values escaped for you.
+- Checks that reject broken `where` strings that Quickbase would otherwise accept.
+- `table.query()` for automatic paging, plus `query_page()` and `count()`.
+- `Record`, with access by label or ID and date and timestamp conversion.
+- `read_only=True` on the clients, which refuses any request that could change data.
+- `allowed_writes` on the clients, which limits them to reads plus the writes you list.
+- `parse_where()` for inspecting a hand-written `where` string.
+- `table.insert()`, `update()`, `upsert()`, and `delete()`, with per-row error reporting in `WriteError`.
+- `app.create_table()`, `table.create_field()`, `update_field()`, `delete_fields()`,
+  `create_relationship()`, and `drop()`.

{pyquickbase-0.1.0a1 → pyquickbase-0.2.0a1}/CONTRIBUTING.md

@@ -14,6 +14,11 @@ uv run pytest --cov
 
 Tests use mocked HTTP and need no Quickbase account.
 
+## Docs
+
+Preview the docs site with `uv run --group docs mkdocs serve`. Every public name needs an entry in
+`docs/reference.md`, and a test checks this.
+
 ## Sync and async code
 
 **Only edit the async code.** `src/pyquickbase/_sync/` and `tests/_sync/` are generated from their

{pyquickbase-0.1.0a1 → pyquickbase-0.2.0a1}/PKG-INFO

@@ -1,7 +1,8 @@
 Metadata-Version: 2.5
 Name: pyquickbase
-Version: 0.1.0a1
+Version: 0.2.0a1
 Summary: An unofficial, typed Python SDK for the Quickbase API, with sync and async clients.
+Project-URL: Documentation, https://matthew-williams-solutions.github.io/pyquickbase/
 Project-URL: Repository, https://github.com/matthew-williams-solutions/pyquickbase
 Project-URL: Issues, https://github.com/matthew-williams-solutions/pyquickbase/issues
 Project-URL: Changelog, https://github.com/matthew-williams-solutions/pyquickbase/blob/main/CHANGELOG.md
@@ -28,6 +29,8 @@ Description-Content-Type: text/markdown
 An unofficial, typed Python SDK for the [Quickbase](https://www.quickbase.com/) API, with matching
 sync and async clients.
 
+**[Read the documentation](https://matthew-williams-solutions.github.io/pyquickbase/)**
+
 > **Status: early alpha.** Anything may change before 1.0. This project is not affiliated with or endorsed by Quickbase, Inc.
 
 ## What works today
@@ -42,16 +45,16 @@ sync and async clients.
 - Tokens kept out of `repr`s, exceptions, and logs, and never sent to other hosts or over plain HTTP
 - Creating, updating, and deleting records, with errors reported for each failed row
 - Creating and changing tables, fields, and relationships
+- Running table reports, with automatic paging
+- Uploading, downloading, and deleting file attachments
+- Running formulas, and creating formula fields
+- `pyquickbase codegen`, which generates typed classes from your tables
 - `qb.request()` for calling any Quickbase endpoint directly
 
-## Coming next
-
-Reports, formulas, file attachments, temporary tokens, and generated typed tables.
-
 ## Usage
 
 ```bash
-pip install pyquickbase==0.1.0a1
+pip install pyquickbase==0.2.0a1
 ```
 
 This is an alpha release, so pin the exact version.
@@ -129,6 +132,7 @@ Rows are dictionaries keyed by field label or ID. Python dates, timezone-aware d
 | `table.delete(where)` | Deletes matching records and returns the count. `where` is required |
 
 ```python
+from datetime import date
 from pyquickbase import F, WriteError
 
 result = tasks.insert([{"Title": "Pour slab", "Status": "Not Started", "Due Date": date.today()}])
@@ -188,9 +192,10 @@ Quickbase may already have applied it, so check the data before trying again.
 
 ## Limiting what a client can do
 
-Pass `read_only=True` to guarantee a client can't change data. It only sends GET requests and record
-queries, including through `qb.request()`, and raises `ReadOnlyError` for anything else without
-contacting Quickbase.
+Pass `read_only=True` to guarantee a client can't change data. It only sends GET requests, record
+queries, report runs, and formula runs, including through `qb.request()`, and raises `ReadOnlyError`
+for anything else without contacting Quickbase. Running a report adds to its usage count in Quickbase,
+but changes no records.
 
 To allow specific writes and nothing else, pass `allowed_writes={("POST", "/records")}` instead.
 

{pyquickbase-0.1.0a1 → pyquickbase-0.2.0a1}/README.md

@@ -3,6 +3,8 @@
 An unofficial, typed Python SDK for the [Quickbase](https://www.quickbase.com/) API, with matching
 sync and async clients.
 
+**[Read the documentation](https://matthew-williams-solutions.github.io/pyquickbase/)**
+
 > **Status: early alpha.** Anything may change before 1.0. This project is not affiliated with or endorsed by Quickbase, Inc.
 
 ## What works today
@@ -17,16 +19,16 @@ sync and async clients.
 - Tokens kept out of `repr`s, exceptions, and logs, and never sent to other hosts or over plain HTTP
 - Creating, updating, and deleting records, with errors reported for each failed row
 - Creating and changing tables, fields, and relationships
+- Running table reports, with automatic paging
+- Uploading, downloading, and deleting file attachments
+- Running formulas, and creating formula fields
+- `pyquickbase codegen`, which generates typed classes from your tables
 - `qb.request()` for calling any Quickbase endpoint directly
 
-## Coming next
-
-Reports, formulas, file attachments, temporary tokens, and generated typed tables.
-
 ## Usage
 
 ```bash
-pip install pyquickbase==0.1.0a1
+pip install pyquickbase==0.2.0a1
 ```
 
 This is an alpha release, so pin the exact version.
@@ -104,6 +106,7 @@ Rows are dictionaries keyed by field label or ID. Python dates, timezone-aware d
 | `table.delete(where)` | Deletes matching records and returns the count. `where` is required |
 
 ```python
+from datetime import date
 from pyquickbase import F, WriteError
 
 result = tasks.insert([{"Title": "Pour slab", "Status": "Not Started", "Due Date": date.today()}])
@@ -163,9 +166,10 @@ Quickbase may already have applied it, so check the data before trying again.
 
 ## Limiting what a client can do
 
-Pass `read_only=True` to guarantee a client can't change data. It only sends GET requests and record
-queries, including through `qb.request()`, and raises `ReadOnlyError` for anything else without
-contacting Quickbase.
+Pass `read_only=True` to guarantee a client can't change data. It only sends GET requests, record
+queries, report runs, and formula runs, including through `qb.request()`, and raises `ReadOnlyError`
+for anything else without contacting Quickbase. Running a report adds to its usage count in Quickbase,
+but changes no records.
 
 To allow specific writes and nothing else, pass `allowed_writes={("POST", "/records")}` instead.
 

pyquickbase-0.2.0a1/docs/api-notes.md

@@ -0,0 +1,303 @@
+# Quickbase API notes
+
+What this SDK relies on, and how far each point has been confirmed. Much of the developer portal
+renders in the browser and has no published spec that we've found, so check anything marked
+"unverified" against a real app before depending on it.
+
+## Confirmed
+
+| Behavior | Source |
+|---|---|
+| Headers: `QB-Realm-Hostname` (full hostname), `Authorization: QB-USER-TOKEN <token>` | Accepted by the live API |
+| Error body: JSON with `message` and `description` | Live API, 2026-11-02 |
+| `qb-api-ray` response header holds a request ID | Live API, 2026-11-02 |
+| 100 requests per 10 seconds per user token for most endpoints; some differ | [Rate limiting docs](https://help.quickbase.com/docs/rate-limiting-overview.md) |
+| On a 429, read `retry-after`; retry only for 429 | Same page |
+| Operators: CT, XCT, HAS, XHAS, EX, TV, XTV, XEX, SW, XSW, BF, OBF, AF, OAF, IR, XIR, LT, LTE, GT, GTE, uppercase only | [Query docs](https://help.quickbase.com/docs/components-of-a-query) |
+| Query dates: `yyyy-MM-dd` or milliseconds, not date-time strings | Same page |
+| Query `metadata` has `numFields`, `numRecords`, `skip`, `totalRecords`, and `top` when it was sent | Live API, 2026-11-02 |
+| Omitting `options` or sending `top: 0` returns all matches in a small table; a `skip` past the end returns no records | Live API, 2026-11-02 |
+| `EX` on text ignores case | Live API, 2026-11-02 |
+| `AND` and `OR` must be uppercase; whitespace around them is accepted | Live API, 2026-11-02 |
+| Unquoted values such as `{3.EX.5}` work the same as quoted ones | Live API, 2026-11-02 |
+| `EX ''` matches empty fields and `XEX ''` matches non-empty ones | Live API, 2026-11-02 |
+| On a date field, `LT`, `LTE`, `GT`, and `GTE` match the same records as `BF`, `OBF`, `AF`, and `OAF` | Live API, 2026-11-02 |
+| Timestamps can be compared with `AF` and `BF` using milliseconds | Live API, 2026-11-02 |
+| With no `select`, only fields in the table's default set return, and Record ID# may not be one | Live API, 2026-11-02 |
+| Timestamps return as `2026-10-21T11:49:56Z`, dates as `2026-10-18` | Live API, 2026-11-02 |
+| A nonexistent app or table returns 401 with a valid token, not 404 | Live API, 2026-11-02 |
+
+A bad realm or app can return 400 rather than 401 or 404, even with an invalid token, so don't
+assume a 400 means the request body was wrong.
+
+## Query pitfalls
+
+Tested on 2026-11-02 against a small sandbox app. These matter because many mistakes return a
+plausible result instead of an error.
+
+| `where` clause | Result |
+|---|---|
+| Lowercase or unknown operator: `{6.ex.'x'}`, `{6.NOPE.'x'}` | **Behaves like `CT`** and returns matches |
+| Unquoted value: `{6.EX.foo}` | No records, no error |
+| Unknown field: `{999999.EX.'x'}` | No records, no error |
+| Field label instead of ID: `{'Title'.EX.'x'}` | No records, no error |
+| Trailing join: `{6.EX.'x'}AND` | No error |
+| Lowercase join, missing brace, or free text | 400, `Criteria is invalid.` |
+
+**Quoting values.** Tested with a temporary record containing `O'Brien`, a backslash, and a brace:
+
+| Text in a value | Result |
+|---|---|
+| `\'` or an unescaped `'` | Matches a stored apostrophe, but the unescaped form is ambiguous, so `F` and the string validator use `\'` |
+| `''` | Doesn't match a stored apostrophe |
+| `\\` | Matches a stored backslash; a single `\` before another character doesn't |
+| `{` or `}` | 400, `Criteria is invalid.`, so values containing braces can't be searched for |
+
+**A value can break out of its clause.** With `zz'}OR{3.GT.'0` as the value, the query matched every
+record whether the quotes were left alone, written as `\'`, or written as `''`. Every breakout we
+found needs a brace, so `F` rejects braces in values. The string validator can't tell a breakout
+from a genuine second condition, so use `F` for any text you don't control.
+
+## Writes
+
+Tested on 2026-11-02 against temporary tables in a sandbox app.
+
+| Behavior | Result |
+|---|---|
+| A row fails | The request returns 207, other rows are written, and `metadata.lineErrors` maps the row number, starting from 1, to its messages |
+| `{"value": null}` | **Silently ignored**, leaving the old value |
+| `{"value": ""}` | Clears text, date, timestamp, numeric, choice, and checkbox fields |
+| Row with an existing Record ID# | Updates it, or reports it in `unchangedRecordIds` if nothing changed |
+| Row with a missing Record ID#, with or without `mergeFieldId` | Row error, and no record is created |
+| `mergeFieldId` on a unique field, value doesn't match | **Creates a record** |
+| `mergeFieldId` on a non-unique field, or a row without the merge field | 400 for the whole request |
+| Unknown field, formula field, built-in field | Row error |
+| A value outside a field's choices | Accepted when `allowNewChoices` is on, otherwise a row error |
+| Empty `data` | 400 |
+| `DELETE /records` without `where` or with a blank one | 400 |
+| `DELETE /records` with a malformed `where` | **`numberDeleted: 0`, no error** |
+| `DELETE /records` with a lowercase operator | **Acts like `CT`**, so it can delete more than intended |
+| `DELETE /fields` with `{"fieldIds": [...]}` | Partial failures are listed in `errors` beside `deletedFieldIds` |
+| `POST /fields` with `unique` or `required` | 400. Set them afterward with `POST /fields/{id}` |
+| Reading a cleared date or timestamp | Returns `""`, and a cleared numeric returns null |
+| Checkbox queries | `{id.EX.'true'}`, `{id.EX.'1'}`, and `{id.TV.'true'}` match the same records |
+
+## Reports
+
+Tested on 2026-11-02 against a temporary table in a sandbox app, with table, ask-the-user, summary,
+and chart reports built in the UI. The API can't create reports.
+
+| Behavior | Result |
+|---|---|
+| `GET /reports?tableId=` | A list of the same objects as `GET /reports/{id}?tableId=`: `id`, `name`, `type`, `description`, `query`, `properties`, `incomplete`, `usedCount`, and `usedLast` once used |
+| Report IDs | Numeric strings, **unique only within a table**. A new table gets `1` (List All) and `2` (List Changes) |
+| Report names | **Can repeat within a table** |
+| `POST /reports/{id}/run?tableId=` | Needs no body. Returns `fields`, `data`, and `metadata`, as a query does |
+| `top` and `skip` | Must be query parameters. **In the body they're silently ignored, and every record returns** |
+| `top` omitted | Returned every record in a 12-record table |
+| `top` of 0 or less, or a negative `skip` | 400, although a query accepts `top: 0` |
+| `skip` past the end | No records, no error |
+| A report ID with leading zeros, such as `01` | Runs the same report |
+| Missing `tableId` | 400 |
+| Unknown table | 401 for an ID that never existed, 404 for a dropped table |
+| Unknown or non-numeric report ID | 404 |
+| The report's filter, sort, and columns | Applied. Rows hold only the report's columns |
+| A report whose columns leave out Record ID#, including the default `List All` | Rows have no field 3 |
+| Running a report | **Adds 1 to `usedCount`, even when the run fails.** A GET doesn't, and records aren't modified |
+| Ask-the-user report | `incomplete: true`, and running it returns 400, `Incomplete reports not supported` |
+| Summary and chart reports | **Same response shape as a table report, but `fields` IDs are column positions starting at 2.** The second column has ID 3, the Record ID# field in a table report, so nothing in the response tells them apart. Only `type` on the report does |
+| Chart category values | Dates return as text, `01-01-2026`, not `yyyy-MM-dd` |
+| Renaming a column in a report | The UI doesn't offer this |
+
+## File attachments
+
+Tested on 2026-11-02 against a temporary table in a sandbox app, using a new `file` field with its
+default settings.
+
+| Behavior | Result |
+|---|---|
+| Upload | `POST /records` with `{"value": {"fileName": ..., "data": <base64>}}` |
+| Download | `GET /files/{table}/{record}/{field}/{version}`. **The body is base64**, whatever `Content-Type` says. Bytes round-trip exactly, including all 256 values |
+| File name in a download | `Content-Disposition: attachment; filename*=utf-8''<percent-encoded>` |
+| `Content-Type` of a download | Based on the file name's extension: an `.html` name gives `text/html`, with a base64 body |
+| Version `0` | The latest, **for `DELETE` as well as `GET`** |
+| Each upload | Adds a version, even with identical contents, and reports the record as updated |
+| Version limit | A new field has `maxVersions: 3`. **The oldest is silently removed**, and its download returns 404 |
+| Version numbers | Not reused or renumbered after a delete or removal |
+| `DELETE` a version | Returns that version's details. Deleting the last one keeps the record and empties the field |
+| `{"value": ""}` or `{"value": null}` on a file field | **No error and no change**, reported in `unchangedRecordIds`. On insert, creates a record with no file |
+| `{"value": "text"}`, or a value without `data` | Row error |
+| A value without `fileName` | **No error, and creates a record with no file** |
+| Empty `fileName` | Row error |
+| Invalid base64 | **Accepted, and the file holds garbage**, with no row error, also inside a batch |
+| Empty `data` | Accepted, as an empty file |
+| A file value sent to a text field | **Stores the file name and discards the contents** |
+| File names | **Stored as sent, including `../../etc/passwd`, `C:\\x\\y.txt`, and line breaks.** A NUL byte cuts the name short. No extension was refused, including `.exe` and `.html` |
+| Reading a file field | `{"url": "/files/...", "versions": [...]}`, with a relative `url`. Empty is `{"url": "", "versions": []}` |
+| Each entry in `versions` | `versionNumber`, `fileName`, `uploaded`, and `creator`, **which includes the uploader's email address** |
+| Missing record, field, or version | 404 |
+| A non-file field | 400 |
+| Unknown table | 400, `Invalid usertoken`, unlike other endpoints' 401 |
+
+**Request size limit.** `POST /records` accepted a body of exactly 41,943,040 bytes (40 MiB) and
+returned 413, `request entity too large`, at one byte more. It's a limit on the whole request: two 25
+MB files in one request returned 413, and two 15 MB files succeeded. It applies without files too:
+1,500 rows of 30,000 characters returned 413 and wrote nothing. The largest file that fits was
+31,457,208 bytes. Downloads worked up to that size.
+
+## Formulas
+
+Tested on 2026-11-02 against temporary tables in a sandbox app.
+
+| Behavior | Result |
+|---|---|
+| `POST /formula/run` | Takes `formula` and `from`, and `rid` if the formula uses fields. Returns `result`, `resultType`, and `fieldTypeApplied` |
+| `result` | **Always a string**, whatever the type |
+| `resultType` values seen | `text`, `number`, `bool`, `date`, `date/time`, `timeofday`, `duration`, `textlist`, `user`, `null` |
+| Booleans | **`"1"` and `"0"`**, so `"0"` is a truthy string in Python |
+| Numbers | Rounded for display: `1/3` returns `"0.3333333"` |
+| Dates and timestamps | **Display text in the app's format, with no time zone:** `03-04-2026` and `03-03-2026 09:06 PM`, where the stored time was `2026-03-04T05:06:07Z`. A query returns the same field as ISO 8601 |
+| Durations | Display text: `Days(3)` returns `"72:00"` |
+| Empty values | `""`, for any type |
+| A blank formula | `""` returns 400. **Whitespace returns 200 with an empty `null` result** |
+| A formula using a field, with no `rid` | 400 |
+| Missing record | 404, even for a formula that uses no fields |
+| Missing `from` | 400 |
+| Unknown table | 401 |
+| A syntax error, unknown field or function, type mismatch, or `1/0` | 400. **Some messages include HTML**, such as a `javascript:` link |
+| Function and field name case | Ignored: `today()` and `[title]` work |
+| `fieldTypeApplied` | `false` in every test. Sending `fieldType` or `resultType` changed nothing, and we don't know what sets it |
+| **Other tables** | **A formula can read other tables** with `GetRecord()` and `GetRecords()`, whatever `from` says |
+| Other information | `AppID()`, `URLRoot()`, and `UserToEmail(User())` return the app ID, realm, and the token owner's email |
+| Side effects | No record changed, including `Date Modified`, after about 60 runs |
+| Formula length | A 1,000,000-character formula worked |
+
+**Formula fields.** `POST /fields` with `properties.formula` creates one, with `mode: "formula"`. Unlike
+many other mistakes, these are checked:
+
+| Behavior | Result |
+|---|---|
+| A syntax error, unknown field, or result type that doesn't match the field | 400. A failed update keeps the old formula |
+| Updating the formula | Values change right away, and other properties are kept |
+| **Updating to an empty formula** | **200, and the field's values become empty** |
+| Creating with an empty formula, or adding a formula to a plain field | 400, `Field must be of formula mode.` |
+| Renaming a field a formula uses | Quickbase updates the formula's text |
+| Writing to a formula field | Row error |
+| Field types that took a formula | `text`, `numeric`, `date`, `checkbox`, `duration`, `timeofday`, `currency`, `percent`, `rating`, `url`, `email`, and `datetime` |
+| **A timestamp formula** | **`timestamp` returns 400, `[formula] property is not supported`. `datetime` works, and the field then reports its type as `timestamp`** |
+| `text-multi-line` | 400, `[formula] property is not supported` |
+| Reading formula fields in a query | Full precision, unlike a formula run: `1/3` returns `0.3333333333333333`. A duration returns milliseconds, and a time of day `11:34:49.896` |
+
+## Rate limits
+
+Tested on 2026-11-02 with short bursts from 12 threads against temporary tables.
+
+| Behavior | Result |
+|---|---|
+| `retry-after` on a real 429 | **Whole seconds**, such as `9` or `10`. After waiting that long, the next request succeeded |
+| 429 body | `{"error": "Quota has been exceeded"}`, **not the usual `message` and `description`** |
+| When it started | After roughly 170 to 185 responses in 4 to 6 seconds, for both `/formula/run` and `/records/query`. That's more than the documented 100 per 10 seconds, so don't rely on the number. These bursts don't show a difference between the two endpoints |
+
+## Temporary tokens
+
+**The SDK doesn't support temporary tokens.** These findings are kept for when that's revisited.
+
+Tested on 2026-11-02 against temporary tables in a sandbox app, with tokens fetched from a logged-in
+browser's console, because a script can't get one.
+
+| Behavior | Result |
+|---|---|
+| `GET /auth/temporary/{table or app ID}` from a script | **400, `Domain not allowed`, with or without credentials.** The check runs before authentication |
+| The same request from a page on the realm | Works, using the browser's session (`credentials: "include"`). Returns `temporaryAuthorization` |
+| Format | An opaque string of 137 characters, with letters, digits, and `.` or `=` |
+| Header | `Authorization: QB-TEMP-TOKEN <token>` |
+| Lifetime | The token stopped working 266 seconds after being pasted into the test. It was fetched shortly before that, so this fits the documented 5 minutes without confirming it |
+| Expired, or out of scope | Both return 401, `Invalid Authorization.`, so they can't be told apart |
+| A malformed token, or a user token with this header | 400, `Invalid Authorization` |
+| A temporary token with `QB-USER-TOKEN` | 401, `User token is invalid` |
+| Requesting another token with one | 400, `Domain not allowed` |
+
+| Request | Table-scoped token | App-scoped token |
+|---|---|---|
+| Records in its table: query, write | **200, including writes** | 401 |
+| Fields and reports of its table, running a report or formula | 200 | 401 |
+| Another table: query, write, fields | 401 | 401 |
+| `GET /tables` and `GET /apps/{id}` | **401** | 200 |
+| **A formula that reads another table** | **200, and returns that table's data** | 401 |
+
+Tokens are scoped narrowly, and an app-scoped token doesn't reach its tables' contents. **Table scope
+doesn't contain a formula**: `GetRecord()` read a table the token couldn't otherwise reach. Uploads,
+downloads, and file deletes weren't tested with a temporary token, and neither were tokens from users
+with fewer permissions.
+
+## Field types
+
+Tested on 2026-11-02 against temporary tables in a sandbox app. These decide the types in generated
+classes, and an unlisted type becomes `Any` and read-only.
+
+`POST /fields` accepts these types: `text`, `text-multiple-choice`, `text-multi-line`, `rich-text`,
+`numeric`, `currency`, `rating`, `percent`, `multitext`, `email`, `url`, `duration`, `date`,
+`datetime`, `timestamp`, `timeofday`, `checkbox`, `user`, `multiuser`, `address`, `phone`, and `file`.
+A `datetime` field reports its type as `timestamp`.
+
+| Field type | A query returns | When empty |
+|---|---|---|
+| `recordid` | Integer | Never empty |
+| `text`, `text-multiple-choice`, `text-multi-line`, `rich-text`, `email`, `url`, `phone` | Text | **`""`, not null** |
+| `numeric`, `currency`, `rating`, `percent` | Number | null |
+| `duration` | Milliseconds | null |
+| `date` | `2026-03-04` | `""` |
+| `timestamp` | `2026-03-04T05:06:07Z` | `""` |
+| `timeofday` | `13:30:00` | `""` |
+| `checkbox` | Boolean | `false` |
+| `multitext` | A list of text | `[]` |
+| `user` | `{"email", "id", "name"}` | null |
+| `multiuser` | A list of users | `[]` |
+| `file` | `{"url", "versions"}` | `{"url": "", "versions": []}` |
+| `address` | Display text, such as `1 Main St, Springfield 12345` | `""` |
+| `dblink` | `""` in the one case seen | |
+
+| Behavior | Result |
+|---|---|
+| Lookup and formula fields | Return the same shapes as their type. Lookups were tested holding text, numeric, and date values, and empty for user, multitext, and checkbox. A formula of `Null` matched its type on text, numeric, and checkbox fields |
+| Writable fields | Built-in fields 1 to 5 aren't, nor are formula, lookup, and summary fields, or `address` |
+| An `address` field | Is read-only, with text subfields for its parts, which can be written. Creating one also creates its subfields, and sets `Country` to a default |
+| `dblink` | Created by a relationship, on the parent table |
+| Labels | **Can contain almost anything, including `"""`, line breaks, and code**, as can table names |
+| Label uniqueness | Exact duplicates are refused, ignoring case, but `Due Date` and `Due-Date` can both exist |
+| Field IDs | Assigned in order, and address subfields use up IDs |
+| `GET /tables/{id}` | Returned an error without its `appId`, so use `GET /tables?appId=` |
+
+## Unverified
+
+Check these against a sandbox app before the feature that needs them ships.
+
+| Question | Needed for |
+|---|---|
+| Can a query return fewer than `top` records before the end? The test table was too small to show it, so advance by `numRecords` | Paging |
+| Which endpoints have different rate limits? | Transport |
+| Whether a formula can read a table in another app | Formulas |
+| Lookups that hold a value, for types other than text, numeric, and date, and field types only the UI can create | Generated classes |
+| Correct API host for EU realms (pass `base_url` if it differs) | Realm handling |
+| Table reports with a formula column, or with Record ID# as a column | Reports |
+| Whether pages of a report are stable when its sort has ties | Reports |
+| Whether a report's `top`-less run returns every record in a large table | Reports |
+| Whether other endpoints or realms have a different request size limit | Writes |
+| File fields with other version settings, and limits on total storage | File attachments |
+| How reports and files behave for tokens with fewer permissions, since all testing used one token | Reports, file attachments |
+
+## Known limits to revisit
+
+Choices made in the SDK that are worth another look before 1.0.
+
+| Limit | Why it's there | Possible change |
+|---|---|---|
+| Report details are cached for `schema_ttl`, so a report changed in the UI can be checked against old details | Avoids an extra request for every page | Refresh before each run, or compare the run response |
+| Summary and chart reports can only be read through `qb.request()` | Their column IDs are positions, so they can't be records | A separate method returning `{label: value}` rows |
+| `timeout` is set per client, so a large upload on a slow connection may need a larger one for every request | The transport has one timeout | A per-call timeout for uploads and downloads |
+| Files are held in memory as bytes and base64 while being sent | The API takes base64 inside JSON, so there's nothing to stream | Probably none, unless Quickbase adds another upload route |
+| `record["Attachment"]` returns Quickbase's raw dictionary | Kept simple for the first version | A typed value with versions, which could leave out uploader emails |
+| Quickbase's formula error messages can contain HTML, which errors pass on unchanged | Errors keep Quickbase's message intact | Strip HTML from error messages, in case they're displayed |
+| `FormulaResult.value` leaves dates, timestamps, and durations as display text | They depend on app settings, and timestamps have no time zone | Parse them using the app's settings, if a safe way appears |
+| Temporary tokens aren't supported | Their main use is browser code pages, a script can't get one, and the SDK's table lookup needs `GET /tables`, which a table-scoped token can't call | After 1.0, a `temporary_token` client option that treats `app.table()` as an ID and skips that lookup, for a backend acting for a logged-in user |
+| `codegen` writes one class per table, with no way to rename one | Names come from labels, so renaming a label renames the attribute | Keep names in a small config file, if this proves a problem |

pyquickbase-0.2.0a1/docs/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

pyquickbase-0.2.0a1/docs/getting-started.md

@@ -0,0 +1,68 @@
+# Getting started
+
+## Before you start
+
+You need three things from Quickbase:
+
+- **Your realm**, the `acme` in `acme.quickbase.com`.
+- **A user token** with access to your app. Quickbase explains how to create one in its
+  [authentication docs](https://developer.quickbase.com/auth). Treat it like a password, and give it
+  access to as few apps as possible.
+- **Your app's ID**, which appears in the app's URL and usually starts with `b`.
+
+## Install
+
+```bash
+pip install pyquickbase==0.2.0a1
+```
+
+## Read some records
+
+Both clients have the same API. Use the sync client for scripts and notebooks, and the async client
+in applications that already use asyncio or Trio.
+
+=== "Sync"
+
+    ```python
+    from pyquickbase import F, Quickbase
+
+    with Quickbase(realm="acme", token="your_user_token") as qb:
+        tasks = qb.app("bq1234567").table("Tasks")
+
+        for task in tasks.query(where=F("Status") == "Done", select=["Title"]):
+            print(task.id, task["Title"])
+    ```
+
+=== "Async"
+
+    ```python
+    from pyquickbase import AsyncQuickbase, F
+
+    async with AsyncQuickbase(realm="acme", token="your_user_token") as qb:
+        tasks = qb.app("bq1234567").table("Tasks")
+
+        async for task in tasks.query(where=F("Status") == "Done", select=["Title"]):
+            print(task.id, task["Title"])
+    ```
+
+To keep the token out of your code, set `QB_REALM` and `QB_USER_TOKEN` in the environment and use
+`Quickbase.from_env()`.
+
+```python
+from pyquickbase import Quickbase
+
+with Quickbase.from_env() as qb:
+    print(qb.app("bq1234567").info().name)
+```
+
+## Write a record
+
+```python
+tasks.insert([{"Title": "Pour slab", "Status": "Not Started"}])
+```
+
+## Next steps
+
+- [Reading records](guides/reading.md) covers queries, paging, and record values.
+- [Writing records](guides/writing.md) covers inserts, updates, upserts, and deletes.
+- [Handling errors](guides/errors.md) lists what can go wrong.