…1.1 (#482)

- closes #487

Closes #484

We want Actor developers to be able to easily test their full permission
Actors with limited permissions without changing the Actor configuration
for everybody or redeploying the Actor under a different name. For that
reason, we have introduced a new forcePermissionLevel run option. This
PR adds the option to the client.

Full context here: apify/apify-core#22681

This has been already done in Apify JS client:
apify/apify-client-js#743

Co-authored-by: Vlada Dusek <[email protected]>

### Description

- Allow the possibility to define a custom public URL; if not used, the
default API public URL will be used.
- Python version of the following fix JS client fix
apify/apify-client-js#745

### Issues

- Closes: #496

### Testing

- Added new tests for relevant kvs and datasets clients' methods.

---------

Co-authored-by: Jindřich Bär <[email protected]>

…ts (#664)

## Goal

Update default timeout tiers on individual resource client methods.

## Tier philosophy

| Tier | Value | Use for |
|------|-------|---------|
| `short` (5s) | Simple metadata CRUD | get/update/delete single
resources, quick checks |
| `medium` (30s) | Moderate operations | list with pagination, create,
batch ops, triggering runs/builds |
| `long` (360s) | Heavy operations | downloading/streaming large data,
large payloads |
| `no_timeout` | Indefinite | Polling/waiting (`wait_for_finish`,
`call`, streaming logs) |

## Current state

Only storage clients (Dataset, KVS, RQ) were tiered in PR #653.
Everything else defaults to `'long'` — meaning even a simple
`actor.get()` has a 360s timeout.

## Changes description

### ActorClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `get()` | long | **short** | Simple metadata fetch |
| `update()` | long | **short** | Simple metadata update |
| `delete()` | long | **short** | Simple delete |
| `start()` | long | **medium** | Triggers a run, returns run info (some
server processing) |
| `call()` | long | **no_timeout** | Starts run AND waits for finish —
can take minutes or even much more |
| `build()` | long | **medium** | Triggers a build, returns quickly |
| `default_build()` | long | **short** | Simple metadata fetch |
| `last_run()` | long | **short** | Simple metadata fetch |
| `validate_input()` | long | **short** | Quick validation call |

### ActorCollectionClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `list()` | long | **medium** | Paginated list, could be large |
| `create()` | long | **medium** | Creates resource, some processing |

### ActorVersionClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `get()` | long | **short** | Simple metadata |
| `update()` | long | **short** | Simple metadata |
| `delete()` | long | **short** | Simple delete |

### ActorVersionCollectionClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `list()` | long | **short** | Typically small lists |
| `create()` | long | **short** | Simple create |

### ActorEnvVarClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `get()` | long | **short** | Simple metadata |
| `update()` | long | **short** | Simple metadata |
| `delete()` | long | **short** | Simple delete |

### ActorEnvVarCollectionClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `list()` | long | **short** | Small lists |
| `create()` | long | **short** | Simple create |

### BuildClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `get()` | long | **short** | Simple metadata |
| `delete()` | long | **short** | Simple delete |
| `abort()` | long | **short** | Sends abort signal, returns immediately
|
| `get_open_api_definition()` | long | **medium** | Could be a larger
JSON payload |
| `wait_for_finish()` | no_timeout | no_timeout | Already correct |

### BuildCollectionClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `list()` | long | **medium** | Paginated list |

### RunClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `get()` | long | **short** | Simple metadata |
| `update()` | long | **short** | Simple metadata |
| `delete()` | long | **short** | Simple delete |
| `abort()` | long | **short** | Sends abort signal |
| `wait_for_finish()` | no_timeout | no_timeout | Already correct |
| `metamorph()` | long | **medium** | Triggers transformation |
| `resurrect()` | long | **medium** | Restarts a run |
| `reboot()` | long | **medium** | Reboots a run |
| `get_streamed_log()` | long | **long** | Streaming, keep long |
| `charge()` | long | **short** | Quick API call |
| `get_status_message_watcher()` | long | **long** | Long-lived watcher
|

### RunCollectionClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `list()` | long | **medium** | Paginated list |

### TaskClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `get()` | long | **short** | Simple metadata |
| `update()` | long | **short** | Simple metadata |
| `delete()` | long | **short** | Simple delete |
| `start()` | long | **medium** | Triggers a run |
| `call()` | long | **no_timeout** | Starts and waits for completion |
| `get_input()` | long | **short** | Simple metadata |
| `update_input()` | long | **short** | Simple metadata update |
| `last_run()` | long | **short** | Simple metadata |

### TaskCollectionClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `list()` | long | **medium** | Paginated list |
| `create()` | long | **medium** | Creates resource |

### ScheduleClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `get()` | long | **short** | Simple metadata |
| `update()` | long | **short** | Simple metadata |
| `delete()` | long | **short** | Simple delete |
| `get_log()` | long | **medium** | Returns list of schedule invocations
|

### ScheduleCollectionClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `list()` | long | **medium** | Paginated list |
| `create()` | long | **short** | Simple create |

### WebhookClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `get()` | long | **short** | Simple metadata |
| `update()` | long | **short** | Simple metadata |
| `delete()` | long | **short** | Simple delete |
| `test()` | long | **medium** | Triggers test dispatch |

### WebhookCollectionClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `list()` | long | **medium** | Paginated list |
| `create()` | long | **short** | Simple create |

### WebhookDispatchClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `get()` | long | **short** | Simple metadata |

### WebhookDispatchCollectionClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `list()` | long | **medium** | Paginated list |

### StoreCollectionClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `list()` | long | **medium** | Paginated list |

### LogClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `get()` | long | **long** | This is not metadata call. Logs can be
large — keep as is |
| `get_as_bytes()` | long | **long** | Same |
| `stream()` | long | **long** | Streaming — long is reasonable |

### UserClient

| Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `get()` | long | **short** | Simple metadata |
| `monthly_usage()` | long | **short** | Simple metadata |
| `limits()` | long | **short** | Simple metadata |
| `update_limits()` | long | **short** | Simple metadata update |

### Storage Collection Clients (currently all `long`)

| Client.Method | Current | Recommended | Rationale |
|--------|---------|-------------|-----------|
| `DatasetCollectionClient.list()` | long | **medium** | Paginated list
|
| `DatasetCollectionClient.get_or_create()` | long | **short** | Quick
idempotent op |
| `KeyValueStoreCollectionClient.list()` | long | **medium** | Paginated
list |
| `KeyValueStoreCollectionClient.get_or_create()` | long | **short** |
Quick idempotent op |
| `RequestQueueCollectionClient.list()` | long | **medium** | Paginated
list |
| `RequestQueueCollectionClient.get_or_create()` | long | **short** |
Quick idempotent op |

## Summary of Changes

- **~60 methods** `long` → `short` (simple CRUD on non-storage
resources)
- **~20 methods** `long` → `medium` (list operations, creates, trigger
operations)
- **2 methods** `long` → `no_timeout` (`actor.call()`, `task.call()`)
- **~10 methods** stay `long` (log operations, streaming, data-heavy
ops)
- **Storage clients** (dataset, kvs, request_queue) already well-tiered
— only their collection clients need updates

## Test plan

- [x] CI passes

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>

…ent methods (#663)

## Changes summary

- Accept `dict | PydanticModel` union types in resource client methods
that previously only accepted dict, enabling type-safe usage alongside
plain dict input.
- Dicts are validated through Pydantic internally, catching schema
errors earlier than the API would.
- Replace the dict-based `encode_webhook_list_to_base64` utility with a
structured `WebhookRepresentationList` model that handles validation and
base64 encoding.
- Add `RequestInput` and `RequestDeleteInput` models in `_types.py` for
RQ operations, matching the actual API schema requirements.

## Issues

Closes: #421 

## Motivation

Improve typing on the input side of resource client methods. We don't
want to accept only Pydantic models, which would require users to import
additional classes. Instead, methods now accept both dict and the
corresponding Pydantic model. This way, users don't have to import
anything extra, but can optionally use the model types for type-safe
usage and to discover the expected dict shape.

## Next steps
  
Once we fully update the OpenAPI spec
(apify/apify-docs#2286), we can remove the
manually created models in `_types.py` and replace them with the
generated ones.

## Test plan

- [x] CI passes

Co-authored-by: Vlada Dusek <[email protected]>

## Summary

- Add Docusaurus versioning support.
- Add manual snapshot for the latest stable version - `version-2.5`.
- Update the release workflow and `pyproject.toml` to automate doc
version creation on stable releases (minor and major, patch just
overrides the latest one).

### Issues

- apify/crawlee-python#1302

## Test plan

- [x] Manual local build
- [x] CI passes

## Summary

- Add versioned docs for v1.12 (latest 1.x) from git tag `v1.12.2`.
- Fix Python version requirement in v2.5 docs (3.11+ → 3.10+).
- Override `DocsVersionDropdownNavbarItem` so the version dropdown
navigates to `reference/<version>` instead of `docs/<version>` when on
API reference pages.
  - Same as in the JS version.

## Known limitation

- SubNavbar links (Docs/Reference/Changelog) don't preserve the selected
version — tracked in #675.
  - This applies to JS repos (both client & SDK) as well.

## Test plan

- [x] Tested locally
- [x] CI passes

## Summary

- Replace `redbaron` with `griffe` for parsing Python source in
`check_docstrings.py` and `fix_docstrings.py`.
- Use `ast` module for precise docstring source locations in the fix
script.
- Remove all RedBaron bug workarounds (indentation, whitespace,
except/finally formatting).
- Remove `redbaron` from dev dependencies.
- Complete rewrite of these scripts.

## Reasoning

- `redbaron` is more than 6 years non-maintained

## Test plan

- [x] Checked the scripts manually
- [x] CI passes

## Summary

- Same as in apify/apify-sdk-python#834
- Remove redundant `transformDocs.js` and `pydoc-markdown` and other
relevant part of code
- Align versioned docs sidebar and its content (same as it is for JS
projects)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>

Sending `1` and `0` is working, but the validator is complaining about
that.
Lets align with the JS client. [JS client uses `false`,
`true`](https://github.com/apify/apify-client-js/blob/v2.22.2/src/utils.ts)
[OpenAPI spec does not
define](https://spec.openapis.org/oas/v3.2.0.html#boolean-query-parameter-examples)
serialization of Booleans, but tools frequently choose `false/true`

### Issues:

Related to: apify/apify-docs#2286

This PR contains the following updates:

| Update | Change |
|---|---|
| lockFileMaintenance | All locks refreshed |

🔧 This Pull Request updates lock files to use the latest dependency
versions.

---

### Configuration

📅 **Schedule**: Branch creation - "before 4am on monday" (UTC),
Automerge - At any time (no schedule defined).

🚦 **Automerge**: Enabled.

♻ **Rebasing**: Whenever PR is behind base branch, or you tick the
rebase/retry checkbox.

👻 **Immortal**: This PR will be recreated if closed unmerged. Get
[config
help](https://redirect.github.com/renovatebot/renovate/discussions) if
that's undesired.

---

- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check
this box

---

This PR was generated by [Mend Renovate](https://mend.io/renovate/).
View the [repository job
log](https://developer.mend.io/github/apify/apify-client-python).

<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0My42Ni40IiwidXBkYXRlZEluVmVyIjoiNDMuNjYuNCIsInRhcmdldEJyYW5jaCI6Im1hc3RlciIsImxhYmVscyI6W119-->

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

- Update Renovate and project settings to use only package versions
older than 24 hours
- Motivation is to add minimal defence to supply chain attacks.

…688)

)

## Summary

- Replace `logger.warning()` with `warnings.warn(DeprecationWarning)`
for deprecated params in `batch_add_requests()` (both sync and async) to
match the pattern used in `DatasetClient.download_items()`
- `DeprecationWarning` is the Python standard — visible by default,
caught by `pytest -W error::DeprecationWarning`, and filterable via
`warnings.filterwarnings()`
- Remove unused `logging` import

---

Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>

## Summary

- **Fix error handling examples** — `except Exception as ApifyApiError`
was catching all exceptions and shadowing the class name; now properly
uses `from apify_client.errors import ApifyApiError` with `except
ApifyApiError as err`
- **Fix retries page** — default retry count corrected from 8 to 4
(matches `DEFAULT_MAX_RETRIES`); updated outdated
`min_delay_between_retries_millis` to `min_delay_between_retries` (takes
`timedelta`)
- **Fix convenience methods page** — `start()` was described as waiting
for finish (it doesn't); added missing `wait_for_finish()` method
- **Fix nested client examples** — replaced `ty: ignore` comments with
proper `ActorJobStatus.SUCCEEDED` enum usage
- **Fix README** — updated Quick Start to typed attribute access
(`actor_call.default_dataset_id`), corrected retry count and parameter
name
- **Fix comment grammar** — "waits" → "wait" in code examples
- **Add `description` frontmatter** to all 20 doc pages for SEO
- **Standardize guide titles** to imperative form ("Pass input to an
Actor", "Integrate with data libraries", "Use HTTPX as the HTTP client")

---

Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>