apify-client 3.3.0__tar.gz → 3.3.1b2__tar.gz

{apify_client-3.3.0 → apify_client-3.3.1b2}/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+<!-- git-cliff-unreleased-start -->
+## 3.3.1 - **not yet released**
+
+### 🚀 Features
+
+- Add support for Python 3.15 ([#1122](https://github.com/apify/apify-client-python/pull/1122)) ([ef8f088](https://github.com/apify/apify-client-python/commit/ef8f088c3d4fb5f6facfc2728343298464c5ecb6)) by [@vdusek](https://github.com/vdusek)
+
+### 🐛 Bug Fixes
+
+- Redirect the run log when the first log stream comes back empty ([#1084](https://github.com/apify/apify-client-python/pull/1084)) ([a370e7a](https://github.com/apify/apify-client-python/commit/a370e7a9db75053c2f65ad626ba1bcb67c4cf398)) by [@vdusek](https://github.com/vdusek)
+- **deps:** Allow impit v0.15 ([#1128](https://github.com/apify/apify-client-python/pull/1128)) ([eb9e188](https://github.com/apify/apify-client-python/commit/eb9e188dfb4cdbae620307c7696b0886ed8a6db3)) by [@vdusek](https://github.com/vdusek)
+
+
+<!-- git-cliff-unreleased-end -->
 ## [3.3.0](https://github.com/apify/apify-client-python/releases/tag/v3.3.0) (2026-10-08)
 
 ### 🚀 Features

apify_client-3.3.1b2/CONTRIBUTING.md

@@ -0,0 +1,166 @@
+# Development
+
+Here you'll find a contributing guide to get started with development.
+
+## Environment
+
+For local development, you need a Python version that satisfies `requires-python` in `pyproject.toml`.
+
+We use [uv](https://docs.astral.sh/uv/) for project management. Install it and set up your IDE accordingly.
+
+We use [Poe the Poet](https://poethepoet.natn.io/) as a task runner, similar to npm scripts in `package.json`. All tasks are defined in `pyproject.toml` under `[tool.poe.tasks]`. Run `uv run poe` to list them with their descriptions, and `uv run poe <task>` to run one.
+
+## Dependencies
+
+To install this package with its development dependencies and the pre-commit hooks, run:
+
+```sh
+uv run poe install-dev
+```
+
+## Code checking
+
+To run all code checks (lint, type check, async docstring check, and unit tests), run:
+
+```sh
+uv run poe check-code
+```
+
+We use [ruff](https://docs.astral.sh/ruff/) for linting and formatting, [ty](https://docs.astral.sh/ty/) for type checking, and [pytest](https://docs.pytest.org/) for tests. All of them are configured in `pyproject.toml`, and each has its own task (`lint`, `format`, `type-check`, `unit-tests`).
+
+## Tests
+
+- **Unit tests** (`tests/unit`) are isolated from the Apify API. See [`tests/unit/README.md`](tests/unit/README.md) for the rules they follow. Run them with `uv run poe unit-tests`, or a single test with `uv run pytest tests/unit/<path>.py::<test_name>`.
+- **Integration tests** (`tests/integration`) call the real Apify API. See [`tests/integration/README.md`](tests/integration/README.md) for the tokens they need. Run them with `uv run poe integration-tests`.
+
+## Code style
+
+### Readability
+
+- Prefer a few simple statements over one dense line. Give intermediate values a name instead of nesting calls, comprehensions, and unpacking into a single long expression.
+- When replacing a call with an equivalent one, change only the call and keep the surrounding statements as they were.
+
+### Comments and docstrings
+
+- Every module starts with `from __future__ import annotations`.
+- Comments and docstrings describe what the code does now. The bug a change fixed, what a PR changed, and contrasts with removed behavior (`instead of ...`, `no longer ...`) belong in the commit message.
+- Don't explain language features in comments. A comment earns its place with a domain reason, an invariant the types can't express, or a non-obvious consequence for callers.
+- Use single backticks for code references, never RST-style double backticks.
+- Wrap docstrings and prose comments to the full line length configured in `pyproject.toml`.
+- Write only ASCII in source files: `->` instead of an arrow, `-` instead of a dash, straight quotes.
+- Write `RQ` for the request queue. Log messages and public `.mdx` docs spell out the full term.
+
+### Tests
+
+- Write flat `def test_*()` functions, never `class Test*`, and no section-header comments between tests.
+- Almost every test gets a one-line docstring stating what it verifies, without a `Regression test:`-style prefix.
+- In `@pytest.mark.parametrize`, wrap each case in `pytest.param(..., id='...')` with an id that describes the case.
+- Use `Mock` and the `monkeypatch` fixture for test doubles, not hand-rolled stubs, counters, or flags.
+- A test that changes process-wide or event-loop-wide state restores it. Prefer `monkeypatch`; for APIs it can't patch (`loop.set_exception_handler()`, `signal.signal()`, logging config, `os.chdir()`), capture the original value and restore it in a `finally`.
+- On Windows with Python 3.12 or older, `datetime.now()` ticks in 1-15 ms steps, so two timestamps taken a few milliseconds apart can be equal. A test that asserts one timestamp is later than another injects a `Mock` clock instead of sleeping.
+- For a TCP endpoint that must refuse connections, bind a socket to `('127.0.0.1', 0)` and hold it open without calling `listen()`. A hard-coded port can be taken by a server in a parallel xdist worker. Test servers use `127.0.0.1`, since on Windows `localhost` resolves to both IPv4 and IPv6.
+
+### YAML
+
+Use double quotes for quoted YAML values (`retries: "3"`). Keep single quotes when the value itself contains double quotes, and for string literals inside GitHub Actions expressions (`${{ ... }}`, `if:` conditions), where double quotes are invalid.
+
+## Generated models
+
+`src/apify_client/_models.py`, `_typeddicts.py`, and `_literals.py` are generated from the Apify OpenAPI specification by [datamodel-code-generator](https://github.com/koxudaxi/datamodel-code-generator) and post-processed by `scripts/postprocess_generated_models.py`. Never edit them by hand; make lasting fixes in the post-processing script. The generator is configured under `[tool.datamodel-codegen]` in `pyproject.toml`, with field aliases in `datamodel_codegen_aliases.json`.
+
+- `uv run poe generate-models` regenerates them from the published specification. `scripts/openapi_spec.py` describes how the specification version is recorded. Don't commit a regeneration that only moves that version.
+- `uv run poe generate-models-from-file <path>` generates them from a local specification, for trying out unpublished changes. Don't commit the result.
+- The nightly `Regenerate models` workflow opens a `chore:` PR when the models change. If the diff is user-facing, retitle it to `fix:` or `feat:` so it lands in the changelog and triggers a release.
+
+## Documentation
+
+We adhere to the [Google docstring format](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) for documenting our codebase. Every user-facing class or method is documented. Documentation standards are enforced using [Ruff](https://docs.astral.sh/ruff/).
+
+Resource client docstrings follow one pattern:
+
+- The first line is `Sub-client for managing a specific <resource>.` or `Sub-client for the <resource> collection.`
+- The second paragraph names two or three things the client does (not every method) and says to obtain an instance via an appropriate method on the parent client class, without naming that method.
+
+Docstrings are written on the sync clients only. After editing one, run `uv run poe fix-docstrings` to copy it to the async client; `uv run poe check-docstrings` fails when the two differ.
+
+Our API documentation is generated from these docstrings using [pydoc-markdown](https://pypi.org/project/pydoc-markdown/) with additional post-processing. Markdown files in the `docs/` folder complement the autogenerated content. Final documentation is rendered using [Docusaurus](https://docusaurus.io/) and published to GitHub Pages.
+
+A user-facing feature ships with its documentation in the same PR: a page in `docs/02_concepts/` that explains the mechanism and, where it helps, a page in `docs/03_guides/` that shows a realistic use.
+
+Code examples in `docs/` come in `_sync.py` / `_async.py` pairs and have their own lint settings in `docs/pyproject.toml`. Never edit `website/versioned_docs/`: those snapshots are produced by the release automation and frozen against the code that shipped. Fix `docs/`, and the next release snapshot carries the change.
+
+To run the documentation locally (requires Node.js):
+
+```sh
+uv run poe run-docs
+```
+
+### Linting the docs and website
+
+Markdown content (this guide, `README.md`, and the `docs/` folder) is checked with
+[markdownlint](https://github.com/DavidAnson/markdownlint). The Docusaurus website code is linted
+with [oxlint](https://oxc.rs/) in type-aware mode (types come from `website/tsconfig.json`) and
+formatted with [oxfmt](https://oxc.rs/). All of them run in CI.
+To run them locally (requires Node.js 22.12 or newer and pnpm), from the `website/` directory:
+
+```sh
+pnpm lint          # lint Markdown and website code
+pnpm lint:fix      # auto-fix both
+pnpm format        # format the website code
+```
+
+Doc images are committed as optimized `.webp`. To convert a new image, run
+`pnpm opt:images <path-to-image>` from the `website/` directory.
+
+## Commits
+
+We use [Conventional Commits](https://www.conventionalcommits.org/) format for commit messages. The release process reads them to determine the version bump and build the changelog. Pick the type by what the commit changes, not by why:
+
+| Type | Description |
+| ---- | ----------- |
+| `feat` | A new feature in the source code |
+| `fix` | A bug fix in the source code |
+| `perf` | A source code change that improves performance |
+| `refactor` | A source code change that neither fixes a bug nor adds a feature |
+| `style` | A source code change that doesn't affect its meaning (white-space, formatting) |
+| `test` | Adding or changing tests |
+| `docs` | Documentation changes |
+| `ci` | CI workflow changes |
+| `build` | Build system changes |
+| `chore` | Dependency bumps, tooling, generated files, and other housekeeping |
+| `revert` | Reverting a previous commit |
+
+`feat`, `fix`, `perf`, `refactor`, and `style` trigger a release and appear in the changelog, so use them for source code changes only. `docs` triggers a docs release on master.
+
+Logging changes are breaking: changing a log level, a logger name, or the wording of a log message, or removing one, breaks downstream log-based tooling. Keep the accurate type, add `!` after it, and list the changes in a `BREAKING CHANGE:` footer. PRs are squash-merged, so the `!` must also be in the PR title.
+
+## Release process
+
+Publishing new versions to [PyPI](https://pypi.org/project/apify_client) is automated through GitHub Actions.
+
+- **Beta releases**: On each commit to the master branch, a new beta release is automatically published. The version number is determined based on the latest release and conventional commits. The beta version suffix is incremented by 1 from the last beta release on PyPI.
+- **Stable releases**: A stable version release may be created by triggering the `release` GitHub Actions workflow. The version number is determined based on the latest release and conventional commits (`auto` release type), or it may be overridden using the `custom` release type.
+
+### Publishing to PyPI manually
+
+1. **Do not do this unless absolutely necessary.** In all conceivable scenarios, you should use the `release` workflow instead.
+2. **Make sure you know what you're doing.**
+3. Update the version number by modifying the `version` field under `project` in `pyproject.toml`:
+
+    ```toml
+    [project]
+    name = "apify_client"
+    version = "x.z.y"
+    ```
+
+4. Build the package:
+
+    ```sh
+    uv run poe build
+    ```
+
+5. Upload to PyPI:
+
+    ```sh
+    uv publish --token YOUR_API_TOKEN
+    ```

{apify_client-3.3.0 → apify_client-3.3.1b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apify_client
-Version: 3.3.0
+Version: 3.3.1b2
 Summary: Apify API client for Python
 Keywords: apify,api,client,automation,crawling,scraping
 Author: Apify Technologies s.r.o.
@@ -15,9 +15,10 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Software Development :: Libraries
 Requires-Dist: colorama>=0.4.0
-Requires-Dist: impit~=0.14.0
+Requires-Dist: impit>=0.14.0,<0.16.0
 Requires-Dist: more-itertools>=10.0.0
 Requires-Dist: pydantic[email]>=2.11.0
 Requires-Dist: typing-extensions>=4.6.0
@@ -261,12 +262,7 @@ The full documentation lives at **[docs.apify.com/api/client/python](https://doc
 
 ## Contributing
 
-Bug reports, fixes, and improvements are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development setup, coding standards, testing, and the release process. The repo uses [uv](https://docs.astral.sh/uv/) for project management and [Poe the Poet](https://poethepoet.natn.io/) as a task runner; the typical loop is:
-
-```bash
-uv run poe install-dev   # install dev deps and git hooks
-uv run poe check-code    # lint, type-check, unit tests, docstring check
-```
+Bug reports, fixes, and improvements are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development setup, coding standards, testing, and the release process.
 
 ## License
 

{apify_client-3.3.0 → apify_client-3.3.1b2}/README.md

@@ -224,12 +224,7 @@ The full documentation lives at **[docs.apify.com/api/client/python](https://doc
 
 ## Contributing
 
-Bug reports, fixes, and improvements are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development setup, coding standards, testing, and the release process. The repo uses [uv](https://docs.astral.sh/uv/) for project management and [Poe the Poet](https://poethepoet.natn.io/) as a task runner; the typical loop is:
-
-```bash
-uv run poe install-dev   # install dev deps and git hooks
-uv run poe check-code    # lint, type-check, unit tests, docstring check
-```
+Bug reports, fixes, and improvements are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development setup, coding standards, testing, and the release process.
 
 ## License
 

{apify_client-3.3.0 → apify_client-3.3.1b2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "apify_client"
-version = "3.3.0"
+version = "3.3.1b2"
 description = "Apify API client for Python"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
@@ -19,6 +19,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Topic :: Software Development :: Libraries",
 ]
 keywords = [
@@ -31,7 +32,7 @@ keywords = [
 ]
 dependencies = [
     "colorama>=0.4.0",
-    "impit~=0.14.0",
+    "impit>=0.14.0,<0.16.0",
     "more_itertools>=10.0.0",
     "pydantic[email]>=2.11.0",
     "typing-extensions>=4.6.0",
@@ -68,7 +69,7 @@ dev = [
     "pytest-timeout<3.0.0",
     "pytest-xdist<4.0.0",
     "pytest<10.0.0",
-    "ruff~=0.16.0",
+    "ruff~=0.17.0",
     "setuptools",
     "types-colorama<0.5.0",
     "ty~=0.0.0",
@@ -262,56 +263,99 @@ apify-client = false
 apify-shared = false
 apify_fingerprint_datapoints = false
 crawlee = false
+impit = false
 
-[tool.poe.tasks]
-clean = "rm -rf .coverage .pytest_cache .ruff_cache .ty_cache build dist htmlcov"
-install-sync = "uv sync --all-extras"
-build = "uv build"
-publish-to-pypi = "uv publish --token ${APIFY_PYPI_TOKEN_CRAWLEE}"
-type-check = "uv run ty check"
-unit-tests = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} tests/unit"
-unit-tests-cov = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} --cov=src/apify_client --cov-report=xml:coverage-unit.xml tests/unit"
-integration-tests = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} tests/integration"
-integration-tests-cov = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} --cov=src/apify_client --cov-report=xml:coverage-integration.xml tests/integration"
-check-docstrings = "uv run python -m scripts.check_docstrings"
-fix-docstrings = "uv run python -m scripts.fix_docstrings"
-check-code = [
+[tool.poe.tasks.clean]
+cmd = "rm -rf .coverage .pytest_cache .ruff_cache .ty_cache build dist htmlcov"
+help = "Remove build artifacts and clean caches"
+
+[tool.poe.tasks.install-sync]
+cmd = "uv sync --all-extras"
+help = "Sync dependencies with all extras"
+
+[tool.poe.tasks.build]
+cmd = "uv build"
+help = "Build the package"
+
+[tool.poe.tasks.publish-to-pypi]
+cmd = "uv publish --token ${APIFY_PYPI_TOKEN_CRAWLEE}"
+help = "Publish the package to PyPI"
+
+[tool.poe.tasks.type-check]
+cmd = "uv run ty check"
+help = "Run the type checker"
+
+[tool.poe.tasks.unit-tests]
+cmd = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} tests/unit"
+help = "Run unit tests"
+
+[tool.poe.tasks.unit-tests-cov]
+cmd = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} --cov=src/apify_client --cov-report=xml:coverage-unit.xml tests/unit"
+help = "Run unit tests with an XML coverage report"
+
+[tool.poe.tasks.integration-tests]
+cmd = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} tests/integration"
+help = "Run integration tests"
+
+[tool.poe.tasks.integration-tests-cov]
+cmd = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} --cov=src/apify_client --cov-report=xml:coverage-integration.xml tests/integration"
+help = "Run integration tests with an XML coverage report"
+
+[tool.poe.tasks.check-docstrings]
+cmd = "uv run python -m scripts.check_docstrings"
+help = "Check that async client docstrings match their sync counterparts"
+
+[tool.poe.tasks.fix-docstrings]
+cmd = "uv run python -m scripts.fix_docstrings"
+help = "Copy sync client docstrings to their async counterparts"
+
+[tool.poe.tasks.check-code]
+sequence = [
     "lint",
     "type-check",
     "check-docstrings",
     "unit-tests",
 ]
+help = "Run lint, type check, docstring check, and unit tests"
 
 [tool.poe.tasks.install-dev]
 shell = "uv sync --all-extras && uv run pre-commit install"
+help = "Install development dependencies and pre-commit hooks"
 
 [tool.poe.tasks.lint]
 shell = "uv run ruff format --check && uv run ruff check"
+help = "Run the linter and check formatting"
 
 [tool.poe.tasks.format]
 shell = "uv run ruff check --fix && uv run ruff format"
+help = "Fix lint issues and format code"
 
 [tool.poe.tasks.update-docs-theme]
 shell = "pnpm update @apify/docs-theme"
 cwd = "website"
+help = "Update the documentation website theme"
 
 [tool.poe.tasks.build-docs]
 shell = "./build_api_reference.sh && pnpm install && uv run pnpm build"
 cwd = "website"
+help = "Build the documentation website"
 
 [tool.poe.tasks.run-docs]
 shell = "./build_api_reference.sh && pnpm install && uv run pnpm start"
 cwd = "website"
+help = "Run the documentation website locally"
 
 [tool.poe.tasks.generate-models]
 shell = """
 uv run python -m scripts.openapi_spec fetch && uv run datamodel-codegen --input tmp/openapi.json --alias-generator to_camel && uv run datamodel-codegen --input tmp/openapi.json --output src/apify_client/_typeddicts.py --output-model-type typing.TypedDict --no-use-closed-typed-dict && python scripts/postprocess_generated_models.py && uv run python -m scripts.openapi_spec record-version
 """
+help = "Regenerate models from the published OpenAPI specification"
 
 [tool.poe.tasks.generate-models-from-file]
 shell = """
 uv run datamodel-codegen --input $input_file --alias-generator to_camel && uv run datamodel-codegen --input $input_file --output src/apify_client/_typeddicts.py --output-model-type typing.TypedDict --no-use-closed-typed-dict && python scripts/postprocess_generated_models.py && echo "Generated from $input_file - the version in [tool.apify.openapi-spec] still names the published specification, so do not commit these models."
 """
+help = "Generate models from a local OpenAPI specification file (don't commit the result)"
 
 [[tool.poe.tasks.generate-models-from-file.args]]
 name = "input-file"

{apify_client-3.3.0 → apify_client-3.3.1b2}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "apify_client"
-version = "3.3.0"
+version = "3.3.1b2"
 description = "Apify API client for Python"
 authors = [{ name = "Apify Technologies s.r.o.", email = "support@apify.com" }]
 license = "Apache-2.0"
@@ -20,12 +20,13 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Topic :: Software Development :: Libraries",
 ]
 keywords = ["apify", "api", "client", "automation", "crawling", "scraping"]
 dependencies = [
     "colorama>=0.4.0",
-    "impit~=0.14.0",
+    "impit>=0.14.0,<0.16.0",
     "more_itertools>=10.0.0",
     "pydantic[email]>=2.11.0",
     # 4.6.0 is the first release whose runtime protocol checks look attributes up statically.
@@ -63,7 +64,7 @@ dev = [
     "pytest-timeout<3.0.0",
     "pytest-xdist<4.0.0",
     "pytest<10.0.0",
-    "ruff~=0.16.0",
+    "ruff~=0.17.0",
     "setuptools", # setuptools are used by pytest but not explicitly required
     "types-colorama<0.5.0",
     "ty~=0.0.0",
@@ -262,42 +263,49 @@ apify-client = false
 apify-shared = false
 apify_fingerprint_datapoints = false
 crawlee = false
+impit = false
 
 # Run tasks with: uv run poe <task>
 [tool.poe.tasks]
-clean = "rm -rf .coverage .pytest_cache .ruff_cache .ty_cache build dist htmlcov"
-install-sync = "uv sync --all-extras"
-build = "uv build"
-publish-to-pypi = "uv publish --token ${APIFY_PYPI_TOKEN_CRAWLEE}"
-type-check = "uv run ty check"
-unit-tests = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} tests/unit"
-unit-tests-cov = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} --cov=src/apify_client --cov-report=xml:coverage-unit.xml tests/unit"
-integration-tests = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} tests/integration"
-integration-tests-cov = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} --cov=src/apify_client --cov-report=xml:coverage-integration.xml tests/integration"
-check-docstrings = "uv run python -m scripts.check_docstrings"
-fix-docstrings = "uv run python -m scripts.fix_docstrings"
-check-code = ["lint", "type-check", "check-docstrings", "unit-tests"]
+clean = { cmd = "rm -rf .coverage .pytest_cache .ruff_cache .ty_cache build dist htmlcov", help = "Remove build artifacts and clean caches" }
+install-sync = { cmd = "uv sync --all-extras", help = "Sync dependencies with all extras" }
+build = { cmd = "uv build", help = "Build the package" }
+publish-to-pypi = { cmd = "uv publish --token ${APIFY_PYPI_TOKEN_CRAWLEE}", help = "Publish the package to PyPI" }
+type-check = { cmd = "uv run ty check", help = "Run the type checker" }
+unit-tests = { cmd = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} tests/unit", help = "Run unit tests" }
+unit-tests-cov = { cmd = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} --cov=src/apify_client --cov-report=xml:coverage-unit.xml tests/unit", help = "Run unit tests with an XML coverage report" }
+integration-tests = { cmd = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} tests/integration", help = "Run integration tests" }
+integration-tests-cov = { cmd = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} --cov=src/apify_client --cov-report=xml:coverage-integration.xml tests/integration", help = "Run integration tests with an XML coverage report" }
+check-docstrings = { cmd = "uv run python -m scripts.check_docstrings", help = "Check that async client docstrings match their sync counterparts" }
+fix-docstrings = { cmd = "uv run python -m scripts.fix_docstrings", help = "Copy sync client docstrings to their async counterparts" }
+check-code = { sequence = ["lint", "type-check", "check-docstrings", "unit-tests"], help = "Run lint, type check, docstring check, and unit tests" }
 
 [tool.poe.tasks.install-dev]
 shell = "uv sync --all-extras && uv run pre-commit install"
+help = "Install development dependencies and pre-commit hooks"
 
 [tool.poe.tasks.lint]
 shell = "uv run ruff format --check && uv run ruff check"
+help = "Run the linter and check formatting"
 
 [tool.poe.tasks.format]
 shell = "uv run ruff check --fix && uv run ruff format"
+help = "Fix lint issues and format code"
 
 [tool.poe.tasks.update-docs-theme]
 shell = "pnpm update @apify/docs-theme"
 cwd = "website"
+help = "Update the documentation website theme"
 
 [tool.poe.tasks.build-docs]
 shell = "./build_api_reference.sh && pnpm install && uv run pnpm build"
 cwd = "website"
+help = "Build the documentation website"
 
 [tool.poe.tasks.run-docs]
 shell = "./build_api_reference.sh && pnpm install && uv run pnpm start"
 cwd = "website"
+help = "Run the documentation website locally"
 
 # Both passes read one downloaded copy, so a specification redeployed mid-run can't leave the generated files
 # describing two different inputs. The version is recorded last, once generation succeeded.
@@ -316,6 +324,7 @@ uv run python -m scripts.openapi_spec fetch \
     && python scripts/postprocess_generated_models.py \
     && uv run python -m scripts.openapi_spec record-version
 """
+help = "Regenerate models from the published OpenAPI specification"
 
 # For a candidate specification that isn't published yet. The recorded version deliberately stays put - it names
 # the published specification - so models generated this way must not be committed, hence the warning.
@@ -331,3 +340,4 @@ uv run datamodel-codegen --input $input_file \
     && echo "Generated from $input_file - the version in [tool.apify.openapi-spec] still names the published specification, so do not commit these models."
 """
 args = [{ name = "input-file", positional = true, required = true }]
+help = "Generate models from a local OpenAPI specification file (don't commit the result)"

{apify_client-3.3.0 → apify_client-3.3.1b2}/src/apify_client/_resource_clients/dataset.py

@@ -12,7 +12,7 @@ from apify_client._utils.crypto import create_storage_content_signature
 from apify_client._utils.http import response_to_dict, response_to_list
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterator, Iterator
+    from collections.abc import AsyncGenerator, AsyncIterator, Generator, Iterator
     from datetime import timedelta
 
     from apify_client._literals import GeneralAccess
@@ -405,7 +405,7 @@ class DatasetClient(ResourceClient):
         flatten: list[str] | None = None,
         signature: str | None = None,
         timeout: Timeout = 'long',
-    ) -> Iterator[HttpResponse]:
+    ) -> Generator[HttpResponse]:
         """Retrieve the items in the dataset as a stream.
 
         https://docs.apify.com/api/v2#/reference/datasets/item-collection/get-items
@@ -970,7 +970,7 @@ class DatasetClientAsync(ResourceClientAsync):
         flatten: list[str] | None = None,
         signature: str | None = None,
         timeout: Timeout = 'long',
-    ) -> AsyncIterator[HttpResponse]:
+    ) -> AsyncGenerator[HttpResponse]:
         """Retrieve the items in the dataset as a stream.
 
         https://docs.apify.com/api/v2#/reference/datasets/item-collection/get-items

{apify_client-3.3.0 → apify_client-3.3.1b2}/src/apify_client/_resource_clients/key_value_store.py

@@ -22,7 +22,7 @@ from apify_client._utils.http import response_to_dict, to_path_segment
 from apify_client.errors import ApifyApiError, InvalidResponseBodyError
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterator, Iterator
+    from collections.abc import AsyncGenerator, AsyncIterator, Generator, Iterator
     from datetime import timedelta
 
     from apify_client._literals import GeneralAccess
@@ -318,7 +318,7 @@ class KeyValueStoreClient(ResourceClient):
     @contextmanager
     def stream_record(
         self, key: str, *, signature: str | None = None, timeout: Timeout = 'long'
-    ) -> Iterator[dict | None]:
+    ) -> Generator[dict | None]:
         """Retrieve the given record from the key-value store, as a stream.
 
         https://docs.apify.com/api/v2#/reference/key-value-stores/record/get-record
@@ -756,7 +756,7 @@ class KeyValueStoreClientAsync(ResourceClientAsync):
     @asynccontextmanager
     async def stream_record(
         self, key: str, *, signature: str | None = None, timeout: Timeout = 'long'
-    ) -> AsyncIterator[dict | None]:
+    ) -> AsyncGenerator[dict | None]:
         """Retrieve the given record from the key-value store, as a stream.
 
         https://docs.apify.com/api/v2#/reference/key-value-stores/record/get-record

{apify_client-3.3.0 → apify_client-3.3.1b2}/src/apify_client/_resource_clients/log.py

@@ -9,7 +9,7 @@ from apify_client._utils.errors import catch_not_found_for_resource_or_throw
 from apify_client.errors import ApifyApiError
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterator, Iterator
+    from collections.abc import AsyncGenerator, Generator
 
     from apify_client.http_clients import HttpResponse
     from apify_client.types import Timeout
@@ -96,7 +96,7 @@ class LogClient(ResourceClient):
         return None
 
     @contextmanager
-    def stream(self, *, raw: bool = False, timeout: Timeout = 'long') -> Iterator[HttpResponse | None]:
+    def stream(self, *, raw: bool = False, timeout: Timeout = 'long') -> Generator[HttpResponse | None]:
         """Retrieve the log as a stream.
 
         https://docs.apify.com/api/v2#/reference/logs/log/get-log
@@ -211,7 +211,7 @@ class LogClientAsync(ResourceClientAsync):
         return None
 
     @asynccontextmanager
-    async def stream(self, *, raw: bool = False, timeout: Timeout = 'long') -> AsyncIterator[HttpResponse | None]:
+    async def stream(self, *, raw: bool = False, timeout: Timeout = 'long') -> AsyncGenerator[HttpResponse | None]:
         """Retrieve the log as a stream.
 
         https://docs.apify.com/api/v2#/reference/logs/log/get-log

{apify_client-3.3.0 → apify_client-3.3.1b2}/src/apify_client/_streamed_log.py

@@ -32,6 +32,17 @@ class StreamedLogBase:
     duration of the run (Impit currently maps it to an effective 24-hour cap) and mirrors the JS client.
     """
 
+    _empty_stream_retry_s: ClassVar[float] = 0.5
+    """Pause before the first reopen of a log stream that ended before the run logged anything.
+
+    The API serves the log of a run that has not logged anything yet as an empty stream that ends at once. Each further
+    reopen doubles the pause up to `_empty_stream_max_retry_s`, which bounds the request rate while a run waits long to
+    start, for example for free memory.
+    """
+
+    _empty_stream_max_retry_s: ClassVar[float] = 5
+    """Upper bound on the pause between reopens of an empty log stream."""
+
     def __init__(self, to_logger: logging.Logger, *, from_start: bool = True) -> None:
         if self._force_propagate:
             to_logger.propagate = True
@@ -39,8 +50,11 @@ class StreamedLogBase:
         self._stream_buffer = list[bytes]()
         self._split_marker = re.compile(rb'(?:\n|^)(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)')
         self._relevancy_time_limit: datetime | None = None if from_start else datetime.now(tz=UTC)
+        self._received_data = False
 
     def _process_new_data(self, data: bytes) -> None:
+        if data:
+            self._received_data = True
         new_chunk = data
         self._stream_buffer.append(new_chunk)
         if re.findall(self._split_marker, new_chunk):
@@ -75,6 +89,12 @@ class StreamedLogBase:
             message = decoded_marker + decoded_content
             self._to_logger.log(level=self._guess_log_level_from_message(message), msg=message.strip())
 
+    def _process_whole_log(self, log: bytes | None) -> None:
+        """Redirect a whole log read in one request, including its last part."""
+        if log:
+            self._process_new_data(log)
+            self._log_buffer_content(include_last_part=True)
+
     @staticmethod
     def _guess_log_level_from_message(message: str) -> int:
         """Guess the log level from the message."""
@@ -120,7 +140,7 @@ class StreamedLog(StreamedLogBase):
         self._log_client = log_client
         self._streaming_thread: Thread | None = None
         self._log_stream: HttpResponse | None = None
-        self._stop_logging = False
+        self._stop_event = threading.Event()
 
     def start(self) -> Thread:
         """Start the streaming thread.
@@ -129,7 +149,8 @@ class StreamedLog(StreamedLogBase):
         """
         if self._streaming_thread and self._streaming_thread.is_alive():
             raise RuntimeError('Streaming thread already active')
-        self._stop_logging = False
+        self._stop_event.clear()
+        self._received_data = False
         # A daemon thread so a stream still blocked on a read can never hold up interpreter shutdown.
         self._streaming_thread = threading.Thread(target=self._stream_log, daemon=True)
         self._streaming_thread.start()
@@ -138,13 +159,14 @@ class StreamedLog(StreamedLogBase):
     def stop(self) -> None:
         """Signal the streaming thread to stop logging and wait up to `_stop_timeout_s` for it to finish.
 
-        A thread that outlives the wait is a daemon with `_stop_logging` set, so it exits after at most one more chunk,
+        A thread that outlives the wait is a daemon with `_stop_event` set, so it exits after at most one more chunk,
         and only then does its buffered tail reach the logger. Its handle is kept while it is alive, so `start` cannot
-        revive it beside a second thread on the same buffer.
+        revive it beside a second thread on the same buffer. If no stream has delivered anything yet, the thread reads
+        the whole log in one request before it ends.
         """
         if not self._streaming_thread:
             raise RuntimeError('Streaming thread is not active')
-        self._stop_logging = True
+        self._stop_event.set()
         # Read once; the streaming thread clears the attribute as soon as the stream ends.
         log_stream = self._log_stream
         if log_stream is not None:
@@ -173,39 +195,60 @@ class StreamedLog(StreamedLogBase):
 
     def _stream_log(self) -> None:
         try:
-            with self._log_client.stream(raw=True, timeout=self._stream_timeout) as log_stream:
-                if not log_stream:
+            # An empty stream means the run has not logged anything yet, so reopen it until the first bytes arrive.
+            retry_s = self._empty_stream_retry_s
+            while not self._stop_event.is_set():
+                if not self._stream_log_once() or self._received_data:
                     return
-                # Published so `stop` can close the response.
-                self._log_stream = log_stream
-                try:
-                    # `stop` may have run before the response existed for it to close.
-                    if self._stop_logging:
-                        return
-                    for data in log_stream.iter_bytes():
-                        self._process_new_data(data)
-                        if self._stop_logging:
-                            break
-                finally:
-                    self._log_stream = None
-                    try:
-                        # Flush the last buffered part even if the read timed out or was stopped.
-                        self._log_buffer_content(include_last_part=True)
-                    except Exception:
-                        # A truncated stream leaves an undecodable tail, which is worth a traceback even while a stop
-                        # is in progress.
-                        self._to_logger.exception('Log redirection stopped due to unexpected error:')
+                self._stop_event.wait(retry_s)
+                retry_s = min(retry_s * 2, self._empty_stream_max_retry_s)
         except Exception as exc:
-            if self._stop_logging:
+            if self._stop_event.is_set():
                 # `stop` closed the stream out from under the read, so the failure is expected.
                 self._to_logger.debug('Log streaming stopped while `stop` was in progress: %r', exc)
-                return
-            if self._log_client._http_client.is_timeout_error(exc):  # noqa: SLF001
+            elif self._log_client._http_client.is_timeout_error(exc):  # noqa: SLF001
                 # The stream cannot continue, so warn and let the thread end instead of leaking a traceback.
                 self._to_logger.warning('Log streaming stopped: the log stream request timed out.')
+                return
             else:
                 # Any other failure in log redirection must not escape the background thread; log it instead.
                 self._to_logger.exception('Log redirection stopped due to unexpected error:')
+                return
+        if self._received_data:
+            return
+        # Stopped before any stream delivered a byte, which a run that finishes quickly can cause.
+        try:
+            self._process_whole_log(self._log_client.get_as_bytes(raw=True))
+        except Exception:
+            self._to_logger.exception('Log redirection stopped due to unexpected error:')
+
+    def _stream_log_once(self) -> bool:
+        """Redirect one log stream until it ends or `stop` is called. Return `False` when the log does not exist."""
+        with self._log_client.stream(raw=True, timeout=self._stream_timeout) as log_stream:
+            if not log_stream:
+                return False
+            # Published so `stop` can close the response.
+            self._log_stream = log_stream
+            try:
+                # `stop` may have run before the response existed for it to close. No earlier stream delivered
+                # anything, and one opened this late would end after its first chunk, so read the whole log in one
+                # request.
+                if self._stop_event.is_set():
+                    return True
+                for data in log_stream.iter_bytes():
+                    self._process_new_data(data)
+                    if self._stop_event.is_set():
+                        break
+            finally:
+                self._log_stream = None
+                try:
+                    # Flush the last buffered part even if the read timed out or was stopped.
+                    self._log_buffer_content(include_last_part=True)
+                except Exception:
+                    # A truncated stream leaves an undecodable tail, which is worth a traceback even while a stop is
+                    # in progress.
+                    self._to_logger.exception('Log redirection stopped due to unexpected error:')
+        return True
 
 
 @docs_group('Other')
@@ -240,14 +283,19 @@ class StreamedLogAsync(StreamedLogBase):
         """
         if self._streaming_task and not self._streaming_task.done():
             raise RuntimeError('Streaming task already active')
+        self._received_data = False
         self._streaming_task = asyncio.create_task(self._stream_log())
         return self._streaming_task
 
     async def stop(self) -> None:
-        """Stop the streaming task."""
+        """Stop the streaming task.
+
+        If no stream has delivered anything yet, read the whole log in one request instead.
+        """
         if not self._streaming_task:
             raise RuntimeError('Streaming task is not active')
 
+        was_streaming = not self._streaming_task.done()
         self._streaming_task.cancel()
         try:
             await self._streaming_task
@@ -255,6 +303,13 @@ class StreamedLogAsync(StreamedLogBase):
             pass
         finally:
             self._streaming_task = None
+        if not was_streaming or self._received_data:
+            return
+        # Stopped before any stream delivered a byte, which a run that finishes quickly can cause.
+        try:
+            self._process_whole_log(await self._log_client.get_as_bytes(raw=True))
+        except Exception:
+            self._to_logger.exception('Log redirection stopped due to unexpected error:')
 
     async def __aenter__(self) -> Self:
         """Start the streaming task within the context. Exiting the context will cancel the streaming task."""
@@ -269,20 +324,27 @@ class StreamedLogAsync(StreamedLogBase):
 
     async def _stream_log(self) -> None:
         try:
-            async with self._log_client.stream(raw=True, timeout=self._stream_timeout) as log_stream:
-                if not log_stream:
-                    return
-                try:
-                    async for data in log_stream.aiter_bytes():
-                        self._process_new_data(data)
-                finally:
+            # An empty stream means the run has not logged anything yet, so reopen it until the first bytes arrive.
+            retry_s = self._empty_stream_retry_s
+            while True:
+                async with self._log_client.stream(raw=True, timeout=self._stream_timeout) as log_stream:
+                    if not log_stream:
+                        return
                     try:
-                        # Flush the last buffered part even if the task is cancelled by `stop()`.
-                        self._log_buffer_content(include_last_part=True)
-                    except Exception:
-                        # A truncated stream leaves an undecodable tail. Keeping the failure here also keeps the
-                        # cancellation `stop` raised propagating, so the task ends up cancelled as asyncio expects.
-                        self._to_logger.exception('Log redirection stopped due to unexpected error:')
+                        async for data in log_stream.aiter_bytes():
+                            self._process_new_data(data)
+                    finally:
+                        try:
+                            # Flush the last buffered part even if the task is cancelled by `stop()`.
+                            self._log_buffer_content(include_last_part=True)
+                        except Exception:
+                            # A truncated stream leaves an undecodable tail. Keeping the failure here also keeps the
+                            # cancellation `stop` raised propagating, so the task ends up cancelled as asyncio expects.
+                            self._to_logger.exception('Log redirection stopped due to unexpected error:')
+                if self._received_data:
+                    return
+                await asyncio.sleep(retry_s)
+                retry_s = min(retry_s * 2, self._empty_stream_max_retry_s)
         except Exception as exc:
             if self._log_client._http_client.is_timeout_error(exc):  # noqa: SLF001
                 # A timeout on the long-lived stream is an expected terminal condition, not an error.

{apify_client-3.3.0 → apify_client-3.3.1b2}/src/apify_client/_utils/try_import.py

@@ -7,7 +7,7 @@ from types import ModuleType
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Generator
     from typing import Any
 
 
@@ -19,7 +19,7 @@ class ImportState:
 
 
 @contextmanager
-def try_import(module_name: str, *symbol_names: str, dependency_name: str, extra_name: str) -> Iterator[ImportState]:
+def try_import(module_name: str, *symbol_names: str, dependency_name: str, extra_name: str) -> Generator[ImportState]:
     """Context manager to attempt importing symbols into a module.
 
     If the named optional dependency is missing, the symbols are replaced with `FailedImport` objects whose message

apify_client-3.3.0/CONTRIBUTING.md

@@ -1,189 +0,0 @@
-# Development
-
-Here you'll find a contributing guide to get started with development.
-
-## Environment
-
-For local development, it is required to have Python 3.11 (or a later version) installed.
-
-We use [uv](https://docs.astral.sh/uv/) for project management. Install it and set up your IDE accordingly.
-
-We use [Poe the Poet](https://poethepoet.natn.io/) as a task runner, similar to npm scripts in `package.json`.
-All tasks are defined in `pyproject.toml` under `[tool.poe.tasks]` and can be run with `uv run poe <task>`.
-
-### Available tasks
-
-| Task | Description |
-| ---- | ----------- |
-| `install-dev` | Install development dependencies |
-| `check-code` | Run lint, type-check, unit-tests, and docstring check |
-| `lint` | Run linter |
-| `format` | Fix lint issues and format code |
-| `type-check` | Run type checker |
-| `unit-tests` | Run unit tests |
-| `unit-tests-cov` | Run unit tests with coverage |
-| `integration-tests` | Run integration tests |
-| `integration-tests-cov` | Run integration tests with coverage |
-| `check-docstrings` | Check async client docstrings |
-| `fix-docstrings` | Fix async client docstrings |
-| `build-docs` | Build documentation website |
-| `run-docs` | Run documentation website locally |
-| `build` | Build package |
-| `clean` | Remove build artifacts and clean caches |
-
-## Dependencies
-
-To install this package and its development dependencies, run:
-
-```sh
-uv run poe install-dev
-```
-
-## Code checking
-
-To execute all code checking tools together, run:
-
-```sh
-uv run poe check-code
-```
-
-### Linting
-
-We utilize [ruff](https://docs.astral.sh/ruff/) for linting, which analyzes code for potential issues and enforces consistent style. Refer to `pyproject.toml` for configuration details.
-
-To run linting:
-
-```sh
-uv run poe lint
-```
-
-### Formatting
-
-Our automated code formatting also leverages [ruff](https://docs.astral.sh/ruff/), ensuring uniform style and addressing fixable linting issues. Configuration specifics are outlined in `pyproject.toml`.
-
-To run formatting:
-
-```sh
-uv run poe format
-```
-
-### Type checking
-
-Type checking is handled by [ty](https://docs.astral.sh/ty/), verifying code against type annotations. Configuration settings can be found in `pyproject.toml`.
-
-To run type checking:
-
-```sh
-uv run poe type-check
-```
-
-### Unit tests
-
-We use [pytest](https://docs.pytest.org/) as a testing framework with many plugins. Check `pyproject.toml` for configuration details and installed plugins.
-
-To run unit tests:
-
-```sh
-uv run poe unit-tests
-```
-
-To run unit tests with XML coverage report:
-
-```sh
-uv run poe unit-tests-cov
-```
-
-## Integration tests
-
-We have integration tests which interact with the Apify platform.
-
-Prerequisites:
-
-- Set `APIFY_TEST_USER_API_TOKEN` to your Apify API token
-- Set `APIFY_TEST_USER_2_API_TOKEN` for storage access tests (requires two accounts)
-- Optionally set `APIFY_INTEGRATION_TESTS_API_URL` to use a different Apify API environment
-
-To run integration tests:
-
-```sh
-uv run poe integration-tests
-```
-
-## Documentation
-
-We adhere to the [Google docstring format](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) for documenting our codebase. Every user-facing class or method is documented. Documentation standards are enforced using [Ruff](https://docs.astral.sh/ruff/).
-
-Our API documentation is generated from these docstrings using [pydoc-markdown](https://pypi.org/project/pydoc-markdown/) with additional post-processing. Markdown files in the `docs/` folder complement the autogenerated content. Final documentation is rendered using [Docusaurus](https://docusaurus.io/) and published to GitHub Pages.
-
-To run the documentation locally (requires Node.js):
-
-```sh
-uv run poe run-docs
-```
-
-### Linting the docs and website
-
-Markdown content (this guide, `README.md`, and the `docs/` folder) is checked with
-[markdownlint](https://github.com/DavidAnson/markdownlint). The Docusaurus website code is linted
-with [oxlint](https://oxc.rs/) and formatted with [oxfmt](https://oxc.rs/). All of them run in CI.
-To run them locally (requires Node.js 22.12 or newer and pnpm), from the `website/` directory:
-
-```sh
-pnpm lint          # lint Markdown and website code
-pnpm lint:fix      # auto-fix both
-pnpm format        # format the website code
-```
-
-Doc images are committed as optimized `.webp`. To convert a new image, run
-`pnpm opt:images <path-to-image>` from the `website/` directory.
-
-## Commits
-
-We use [Conventional Commits](https://www.conventionalcommits.org/) format for commit messages. This convention is used to automatically determine version bumps during the release process.
-
-### Available commit types
-
-| Type | Description |
-| ---- | ----------- |
-| `feat` | A new feature |
-| `fix` | A bug fix |
-| `docs` | Documentation only changes |
-| `style` | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) |
-| `refactor` | A code change that neither fixes a bug nor adds a feature |
-| `perf` | A code change that improves performance |
-| `test` | Adding missing tests or correcting existing tests |
-| `build` | Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) |
-| `ci` | Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) |
-| `chore` | Other changes that don't modify src or test files |
-| `revert` | Reverts a previous commit |
-
-## Release process
-
-Publishing new versions to [PyPI](https://pypi.org/project/apify_client) is automated through GitHub Actions.
-
-- **Beta releases**: On each commit to the master branch, a new beta release is automatically published. The version number is determined based on the latest release and conventional commits. The beta version suffix is incremented by 1 from the last beta release on PyPI.
-- **Stable releases**: A stable version release may be created by triggering the `release` GitHub Actions workflow. The version number is determined based on the latest release and conventional commits (`auto` release type), or it may be overridden using the `custom` release type.
-
-### Publishing to PyPI manually
-
-1. **Do not do this unless absolutely necessary.** In all conceivable scenarios, you should use the `release` workflow instead.
-2. **Make sure you know what you're doing.**
-3. Update the version number by modifying the `version` field under `project` in `pyproject.toml`:
-
-    ```toml
-    [project]
-    name = "apify_client"
-    version = "x.z.y"
-    ```
-
-4. Build the package:
-
-    ```sh
-    uv run poe build
-    ```
-
-5. Upload to PyPI:
-
-    ```sh
-    uv publish --token YOUR_API_TOKEN
-    ```