pyquickbase 0.2.0a1__tar.gz → 1.0.0rc1__tar.gz

{pyquickbase-0.2.0a1 → pyquickbase-1.0.0rc1}/CHANGELOG.md

@@ -6,6 +6,30 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [1.0.0rc1] - 2026-11-02
+
+### Added
+
+- A stability and versioning policy, which applies from 1.0.
+
+### Changed
+
+- `TypedTable.check_schema()` now always fetches the table's fields again, instead of doing nothing
+  after the first check. Other methods still check once, on first use, against cached metadata.
+- A generated class no longer fails when a field becomes writable. Otherwise, supporting a new field
+  type in a later version would break classes generated earlier.
+- Generated names no longer depend on the Python version running `pyquickbase codegen`, so a label
+  can't get a different name on a newer Python.
+- The error from `TypedRecord.from_record()` now mentions that a report may have left out a field.
+- `SchemaMismatchError` and `UnknownFieldError` now say a field may be hidden from the token, because
+  Quickbase leaves out fields a role can't see, as if they didn't exist.
+
+### Removed
+
+- `from_api()` on `AppInfo`, `TableInfo`, `Field`, `Relationship`, `ReportInfo`, `FormulaResult`, and
+  `Page`, `FileDownload.from_response()`, `FileUpload.to_api()`, and `WriteResult.merged()` and
+  `summary()`. These were internal helpers, and they're now private so they can change freely.
+
 ## [0.2.0a1] - 2026-11-02
 
 ### Added

{pyquickbase-0.2.0a1 → pyquickbase-1.0.0rc1}/CONTRIBUTING.md

@@ -34,10 +34,22 @@ Anything exported from `pyquickbase/__init__.py` or defined in `errors.py` is pu
 starting with `_` are private and may change at any time. Update `CHANGELOG.md` for changes that
 users would notice.
 
+`docs/stability.md` says what 1.x promises, so check it before changing anything public. From 1.0, a
+breaking change needs a major version, and removing something needs a `DeprecationWarning` in a minor
+release first. Generated code must keep working on later 1.x versions, so treat what it relies on as
+public, even when the name is private. `tests/fixtures/generated_tables.py` is an old generated file
+that the tests run against the current code. From 1.0, don't regenerate it to make a test pass, because
+a failure there means you've broken users' files.
+
 ## Secrets
 
 Never commit real tokens, realm names, or customer data, including in test fixtures. Tokens must
 never appear in exceptions, `repr`s, or logs.
 
-`docs/api-notes.md` tracks which Quickbase API behavior has been confirmed. Please update it if you
+## Notes and plans
+
+`docs/api-notes.md` holds what's been confirmed about the Quickbase API. Please update it if you
 confirm or disprove something.
+
+`ROADMAP.md` holds what's left to do, including anything untested and any limit we may want to change.
+Delete an item once it's done.

{pyquickbase-0.2.0a1 → pyquickbase-1.0.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyquickbase
-Version: 0.2.0a1
+Version: 1.0.0rc1
 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
@@ -10,7 +10,7 @@ Author: Matthew Williams
 License-Expression: MIT
 License-File: LICENSE
 Keywords: api,async,client,quickbase,sdk
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Framework :: AnyIO
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -31,7 +31,7 @@ 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.
+> **Status: release candidate.** Small changes are still possible before 1.0. This project is not affiliated with or endorsed by Quickbase, Inc.
 
 ## What works today
 
@@ -54,10 +54,10 @@ sync and async clients.
 ## Usage
 
 ```bash
-pip install pyquickbase==0.2.0a1
+pip install pyquickbase==1.0.0rc1
 ```
 
-This is an alpha release, so pin the exact version.
+This is a release candidate, so pin the exact version.
 
 ```python
 from datetime import date

{pyquickbase-0.2.0a1 → pyquickbase-1.0.0rc1}/README.md

@@ -5,7 +5,7 @@ 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.
+> **Status: release candidate.** Small changes are still possible before 1.0. This project is not affiliated with or endorsed by Quickbase, Inc.
 
 ## What works today
 
@@ -28,10 +28,10 @@ sync and async clients.
 ## Usage
 
 ```bash
-pip install pyquickbase==0.2.0a1
+pip install pyquickbase==1.0.0rc1
 ```
 
-This is an alpha release, so pin the exact version.
+This is a release candidate, so pin the exact version.
 
 ```python
 from datetime import date

pyquickbase-1.0.0rc1/ROADMAP.md

@@ -0,0 +1,69 @@
+# Roadmap
+
+What's left to do. Delete an item once it's done: `CHANGELOG.md` and git history record what's
+finished, and `docs/api-notes.md` records what's been confirmed about Quickbase. Limits we've decided
+to keep are explained in the guides, not here.
+
+## Before 1.0
+
+- Install `1.0.0rc1` from PyPI and try it live on a scratch table.
+- In the 1.0 release commit:
+  - Change the classifier in `pyproject.toml` from Beta to Production/Stable.
+  - Remove the release candidate warnings from `README.md` and `docs/index.md`, and the advice to pin
+    the exact version. If the pins go too, update `test_install_pins_match_the_version`.
+  - If codegen's output has changed, refresh `tests/fixtures/generated_tables.py` one last time.
+
+## After 1.0
+
+Nothing here should break anyone.
+
+- Switch the docs from Material to Zensical, **by 2027-05-05**, when Material's maintenance ends. A
+  trial build of 0.0.74 worked, and its strict mode also catches broken anchors, which MkDocs doesn't.
+  Wait for 0.1.0, announced for 2026-11-05.
+- A method for summary and chart reports, returning `{label: value}` rows.
+- A per-call timeout for uploads and downloads.
+- A small config file to choose generated names.
+- `query_page()`, `select`, and `batch_size` on typed tables. `select` needs a design, because a
+  generated class requires every column.
+- A setting that repeats a typed table's schema check after a set time.
+- Typed access to file and user values, as a dictionary subclass, which could leave out uploader emails.
+- Export `FieldRef`, `OrderBy`, and `Expression`, which appear in public signatures.
+- Tie a `Row` to its class when the code runs. Only a type checker refuses a row from another class.
+
+## Open questions
+
+Nothing is waiting on these. Test one against a sandbox app before depending on the answer, then move
+the result to `docs/api-notes.md`.
+
+**Queries and limits**
+
+- Can a query return fewer than `top` records before the end? The SDK already advances by the number
+  returned.
+- Which endpoints have different rate limits?
+- Do other endpoints or realms have a different request size limit?
+
+**Reports**
+
+- Can a deleted report's ID be reused? A new report got ID 8, the highest so far, but the deleted
+  report's own ID wasn't recorded. If it can, cached report details could misread a total as a Record
+  ID#.
+- Do pages stay stable with ties above 1,200 records, or while records are added or removed?
+- Does a run without `top` return every record above 1,200 records? The SDK always sends `top`, so this
+  only affects `qb.request()`.
+
+**Fields and files**
+
+- What do lookups return for types other than text, numeric, and date, and what about field types only
+  the UI can create? These are `Any` and read-only in generated classes until confirmed.
+- How do file fields behave with other version settings, and are there limits on total storage?
+
+**Realms and apps**
+
+- What's the API host for EU realms?
+- Can a formula read a table in another app?
+- How do roles with write access or record-level rules behave, and a report that sorts or filters on a
+  hidden field? Only a view-only role with hidden fields has been tested.
+- Can a restricted user's formula read a table their role has no access to? A role's hidden fields held
+  up, but this wasn't tested, because the role's other tables were the seeded ones.
+- Can renaming a table, or using the UI, give two tables the same name? If so, `app.table()` takes the
+  first match, unlike fields and reports, which raise an error.

{pyquickbase-0.2.0a1 → pyquickbase-1.0.0rc1}/docs/api-notes.md

@@ -1,8 +1,9 @@
 # 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.
+renders in the browser and has no published spec that we've found, so check anything not listed here
+against a real app before depending on it. Questions we haven't answered yet are in the
+[roadmap](https://github.com/matthew-williams-solutions/pyquickbase/blob/main/ROADMAP.md#open-questions).
 
 ## Confirmed
 
@@ -26,6 +27,7 @@ renders in the browser and has no published spec that we've found, so check anyt
 | 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 |
+| Creating a table with a name already in the app, ignoring case, returns 400, `Invalid input` | 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.
@@ -103,6 +105,11 @@ and chart reports built in the UI. The API can't create reports.
 | 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 |
+| A table report with Record ID# as a column, even in second position | `fields` uses the real ID, 3, with type `recordid`, unlike a summary report's positions. All 1,200 rows matched a query's IDs |
+| A table report with a formula column | `fields` uses the formula field's real ID and its type, such as `numeric`. All 1,200 values matched a query |
+| A sort with ties, 400 records on each of 3 values | Ties came back in Record ID# order. Six full runs, with page sizes of 7, 37, 100, and 1,000, gave the same order, with nothing repeated or missing. Editing a tied record's other field didn't move it |
+| `top` omitted, in a 1,200-record table | Returned every record, and `metadata` has no `top` |
+| Changing a saved report's type | The UI doesn't offer this |
 | 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 |
@@ -200,7 +207,11 @@ Tested on 2026-11-02 with short bursts from 12 threads against temporary tables.
 
 ## Temporary tokens
 
-**The SDK doesn't support temporary tokens.** These findings are kept for when that's revisited.
+**The SDK doesn't support temporary tokens.** 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. These
+findings are kept for when that's revisited. Supporting them would need 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.
 
 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.
@@ -230,6 +241,29 @@ doesn't contain a formula**: `GetRecord()` read a table the token couldn't other
 downloads, and file deletes weren't tested with a temporary token, and neither were tokens from users
 with fewer permissions.
 
+## Restricted users
+
+Tested on 2026-11-02 against a temporary table in a sandbox app, with a second user's token. Its role
+could only view that table, had no access to the app's other tables, and had access `None` on one text
+field and one file field. A role with write access or record-level rules wasn't tested.
+
+| Behavior | Result |
+|---|---|
+| A token's permissions | Its user's, through their role |
+| `GET /fields` | **A hidden field is left out**, exactly as if it didn't exist, so a deleted field and a hidden one can't be told apart |
+| `GET /fields/{id}` for a hidden field | 500, `QuickBase is experiencing technical difficulties` |
+| `GET /tables` | Lists only tables the role can use |
+| `GET /apps/{id}` | 403, for this role |
+| `select` with a hidden field and a visible one | **200, and the hidden field is silently left out** |
+| `select` with only hidden fields | 400, `Report contains a restricted field` |
+| `where` or `sortBy` on a hidden field | 403, whether or not anything matches |
+| Running a table report with a hidden column | **200, and the column is silently left out.** A report with a hidden field in its sort or filter wasn't tested |
+| A file field's value, read with view access | Includes `creator`, with **the uploader's email address** |
+| Downloading from a visible file field | 200 |
+| Downloading from a hidden file field | 404, `No such field` |
+| A formula using a hidden field, directly or through `GetRecords()` | 403, including when `GetRecords()` only filters on it. A visible field works |
+| Insert, update, delete, upload, deleting a file version, creating a field | 403, `Insufficient permissions`, and nothing changed |
+
 ## Field types
 
 Tested on 2026-11-02 against temporary tables in a sandbox app. These decide the types in generated
@@ -267,37 +301,3 @@ A `datetime` field reports its type as `timestamp`.
 | 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 → pyquickbase-1.0.0rc1}/docs/getting-started.md

@@ -13,7 +13,7 @@ You need three things from Quickbase:
 ## Install
 
 ```bash
-pip install pyquickbase==0.2.0a1
+pip install pyquickbase==1.0.0rc1
 ```
 
 ## Read some records

{pyquickbase-0.2.0a1 → pyquickbase-1.0.0rc1}/docs/guides/clients.md

@@ -44,6 +44,12 @@ qb = Quickbase(realm="acme", token="your_user_token", retry=policy)
 `max_retry_after` is the longest `Retry-After` the client will wait for. Past that, it raises
 `RateLimitError`. Use `max_retries=0` to disable retrying.
 
+## Using another API host
+
+`base_url` sets the API root, which is `https://api.quickbase.com/v1` by default. The right host for EU
+realms hasn't been confirmed, so pass `base_url` if yours differs. It must use HTTPS, except for
+loopback addresses.
+
 ## Proxies, TLS, and logging
 
 Pass your own [httpx](https://www.python-httpx.org/) client for proxies, custom TLS, event hooks, or

{pyquickbase-0.2.0a1 → pyquickbase-1.0.0rc1}/docs/guides/codegen.md

@@ -53,6 +53,8 @@ selects all of its fields. A record's `repr` leaves out its values, because they
 | `file` | `dict[str, Any]`, as described in [File attachments](files.md) |
 | Anything else | `Any` |
 
+Numbers are `float`, as in `Record`, so currency values aren't exact decimals.
+
 ## Writing
 
 `Tasks.new()` builds a row for a new record, and `Tasks.change()` builds one for an existing record.
@@ -75,9 +77,18 @@ take a `FileUpload`.
 ## Keeping it up to date
 
 A generated class is compared with its table the first time it's used, and `SchemaMismatchError` lists
-what's different if a field was deleted, changed type, or became writable or read-only. Reads and writes
-stop rather than risk returning wrong types. Run the command again to fix it. Adding a field or renaming
-one doesn't cause an error, because the class uses field IDs.
+what's different if a field was deleted, changed type, or became read-only. Reads and writes stop rather
+than risk returning wrong types. Run the command again to fix it. Adding a field, renaming one, or a
+field becoming writable doesn't cause an error, because the class uses field IDs and is still safe.
+
+That first check uses cached metadata, 5 minutes old at most by default (see `schema_ttl`), and later
+changes aren't noticed. A long-running process can call `tasks.check_schema()` from time to time, which
+always fetches the fields again.
+
+**Restricted users.** Quickbase leaves out fields a user's role can't see, so a hidden field looks the
+same as a deleted one, and the class raises `SchemaMismatchError` for that user. Generate a class with a
+token that has the same access as the code using it. A class generated by the most restricted user also
+works for anyone who can see more.
 
 To catch changes sooner, run this in CI. It changes nothing, and fails if the file is out of date.
 
@@ -100,3 +111,8 @@ turned into underscores, so a label can't inject code into the module.
 If two labels give the same name, such as `Due Date` and `Due-Date`, the field with the lowest ID keeps
 it and the other gets its ID added: `due_date_9`. A new field therefore never takes an existing field's
 name. Record ID# is always `id`. Renaming a label renames its attribute the next time you generate.
+
+**Names can move.** If the field holding a plain name is deleted, the next field with that name takes it
+when you generate again, so `due_date` can come to mean a different field with no error. Class names work
+the same way, and a clash between them is settled only among the tables you generate, so `--table` can
+change a class's name. Review the diff when you generate again, and use `--check` in CI.

{pyquickbase-0.2.0a1 → pyquickbase-1.0.0rc1}/docs/guides/errors.md

@@ -1,6 +1,8 @@
 # Handling errors
 
-Everything raised by this library derives from `QuickbaseError`.
+Every exception this library defines derives from `QuickbaseError`. Reading a missing key from a
+`Record`, including `record.id` on a report row without Record ID#, raises Python's `KeyError`, as any
+mapping does.
 
 ```python
 from pyquickbase import AuthenticationError, QuickbaseError, RateLimitError
@@ -26,7 +28,7 @@ These mean nothing was sent to Quickbase.
 | `InvalidValueError` | A row, value, or file request that can't be sent |
 | `SchemaMismatchError` | A generated class no longer matches its table |
 | `UnknownTableError` | No table with that name or ID in this app |
-| `UnknownFieldError` | No field with that label or ID in this table |
+| `UnknownFieldError` | No field with that label or ID in this table, or the token's role can't see it |
 | `UnknownReportError` | No report with that name or ID on this table, or several with that name |
 | `UnsupportedReportError` | A report that can't be read as records, such as a summary or chart |
 | `ReadOnlyError` | The client isn't allowed to send this request |
@@ -50,6 +52,10 @@ and `request_id`. Include `request_id` when reporting a problem to Quickbase sup
     `AuthenticationError` can mean either a bad token or a wrong ID. A bad realm or app can also
     return a 400.
 
+!!! warning "Messages can contain HTML"
+    Quickbase's formula error messages can include HTML, such as a `javascript:` link, and errors
+    pass them on unchanged. Escape them before showing them in a web page.
+
 ## Other failures
 
 | Exception | Cause |

{pyquickbase-0.2.0a1 → pyquickbase-1.0.0rc1}/docs/guides/files.md

@@ -73,8 +73,8 @@ are whatever was uploaded. Treat both as untrusted, especially before opening or
 
 ## Listing versions
 
-Reading a file field in a query returns Quickbase's value unchanged. `url` is an empty string, and
-`versions` an empty list, when the field has no file.
+Reading a file field in a query returns Quickbase's value unchanged, as a plain dictionary. `url` is an
+empty string, and `versions` an empty list, when the field has no file.
 
 ```python
 task = next(iter(tasks.query(where="{3.EX.7}", select=["Attachment"])))

{pyquickbase-0.2.0a1 → pyquickbase-1.0.0rc1}/docs/guides/reading.md

@@ -144,9 +144,13 @@ print(len(page.records), page.total, page.has_more)
 The report decides the filter, sort, and columns:
 
 - **Record ID# may be missing.** `record.id` raises `KeyError` if the report doesn't include that
-  column, and the default `List All` report doesn't.
+  column, and the default `List All` report doesn't. To check first, use `3 in record`, because
+  `hasattr(record, "id")` raises `KeyError` too.
 - **Pages may not be stable.** `query()` adds Record ID# as the last sort key to keep pages stable,
-  but a report's sort can't be changed. If that matters, prefer `query()`.
+  but a report's sort can't be changed. Ties stayed in Record ID# order in a 1,200-record test, but
+  that isn't confirmed for larger tables or while records change. If it matters, prefer `query()`.
+- **Columns can be missing for restricted users.** A column the user's role can't see is left out with
+  no error, so `record["Salary"]` raises `KeyError` for them.
 - **Report IDs are only unique within a table.** Different tables reuse the same IDs, so always get a
   report from its own table.
 - **Names can repeat.** A repeated name raises `UnknownReportError`, which lists the IDs to choose
@@ -160,4 +164,5 @@ ask-the-user reports through the API.
 
 Running a report adds to its usage count in Quickbase, even if the run fails, but changes no records.
 Report details come from the same cache as other metadata, so `usedCount` in `raw` can be out of
-date.
+date, and so can the details used to check that a report is a table report. Quickbase's UI doesn't let
+you change a saved report's type.

{pyquickbase-0.2.0a1 → pyquickbase-1.0.0rc1}/docs/index.md

@@ -3,9 +3,9 @@
 An unofficial, typed Python SDK for the [Quickbase](https://www.quickbase.com/) API, with matching
 sync and async clients.
 
-!!! warning "Alpha"
-    This project is in early alpha, so anything may change before 1.0. Pin the exact version you
-    install. It isn't affiliated with or endorsed by Quickbase, Inc.
+!!! warning "Release candidate"
+    This is a release candidate, so small changes are still possible before 1.0. Pin the exact version
+    you install. It isn't affiliated with or endorsed by Quickbase, Inc.
 
 ```python
 from datetime import date
@@ -39,7 +39,7 @@ writing `null` to a field does nothing. This SDK turns those into errors or corr
 ## Install
 
 ```bash
-pip install pyquickbase==0.2.0a1
+pip install pyquickbase==1.0.0rc1
 ```
 
 It needs Python 3.11 or newer. Next, see [Getting started](getting-started.md).

{pyquickbase-0.2.0a1 → pyquickbase-1.0.0rc1}/docs/reference.md

@@ -1,6 +1,7 @@
 # API reference
 
-Everything listed here is public. Modules starting with `_` are private and may change at any time.
+Everything listed here is public, as described in [Stability and versioning](stability.md). Modules
+starting with `_` are private and may change at any time.
 
 ## Clients
 

pyquickbase-1.0.0rc1/docs/stability.md

@@ -0,0 +1,49 @@
+# Stability and versioning
+
+This policy applies from version 1.0. Until then, anything may change in any release.
+
+From 1.0, pyquickbase follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Breaking
+changes come only in a major version, and anything removed first gets a `DeprecationWarning` in a
+minor release.
+
+## What's covered
+
+- Every name in `pyquickbase.__all__` and `pyquickbase.errors`, with its documented methods,
+  signatures, return types, and defaults.
+- The `pyquickbase` command and its options.
+- The promise that a `read_only` client changes no records. It can still run reports, which adds to
+  their usage count in Quickbase, and formulas.
+- File and user values staying plain dictionaries. Their contents come from Quickbase.
+
+## What isn't covered
+
+- Modules and names starting with `_`.
+- Constructors of objects the client creates for you, such as `App`, `Table`, and `Report`. Use
+  `qb.app()`, `app.table()`, and `table.report()` instead.
+- The wording of error messages and `repr`s, so don't parse them.
+- Quickbase's own behavior, including any change it makes to its responses, and the contents of `raw`
+  attributes.
+
+## Generated code
+
+A file generated by any 1.x version works on every later 1.x version, so upgrading doesn't force you
+to generate it again.
+
+Generating it again can rename attributes, when a label changes or a field with the same name is
+deleted. See [how names are chosen](guides/codegen.md#how-names-are-chosen). Run
+`pyquickbase codegen --check` in CI to catch this.
+
+## Minor and patch releases
+
+A minor release can add features, optional arguments, and support for more field types. A generated
+attribute typed `Any` can become more specific, but only once you generate the file again.
+
+A patch release only fixes bugs.
+
+## Dependencies and Python versions
+
+A Python version is dropped only after it reaches end of life, and only in a minor release. pip
+won't install a release on a Python version it doesn't support, so older Python versions keep the last
+release that worked.
+
+`httpx` stays below version 1 until a major version of pyquickbase, because `http_client` exposes it.

{pyquickbase-0.2.0a1 → pyquickbase-1.0.0rc1}/mkdocs.yml

@@ -39,6 +39,7 @@ nav:
       - Handling errors: guides/errors.md
       - Configuring clients: guides/clients.md
   - API reference: reference.md
+  - Stability and versioning: stability.md
   - Quickbase API notes: api-notes.md
   - Changelog: changelog.md
 

{pyquickbase-0.2.0a1 → pyquickbase-1.0.0rc1}/pyproject.toml

@@ -9,7 +9,7 @@ authors = [{ name = "Matthew Williams" }]
 requires-python = ">=3.11"
 keywords = ["quickbase", "api", "sdk", "client", "async"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Framework :: AnyIO",
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3 :: Only",