scrapely-client-python 3.1.3__tar.gz

scrapely_client_python-3.1.3/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [3.1.3] - 2026-09-08
+
+Initial release.
+
+- Python client for the Scrapely API: Actors, runs, datasets, key-value stores, request queues, task management, and webhooks

scrapely_client_python-3.1.3/CONTRIBUTING.md

@@ -0,0 +1,189 @@
+# 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
+    ```

scrapely_client_python-3.1.3/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2023 Apify Technologies s.r.o.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

scrapely_client_python-3.1.3/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: scrapely-client-python
+Version: 3.1.3
+Summary: Scrapely API client for Python - a drop-in replacement for apify-client
+Keywords: scrapely,apify,api,client,automation,crawling,scraping
+Author: Scrapely
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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: Topic :: Software Development :: Libraries
+Requires-Dist: colorama>=0.4.0
+Requires-Dist: impit~=0.13.0
+Requires-Dist: more-itertools>=10.0.0
+Requires-Dist: pydantic[email]>=2.11.0
+Requires-Dist: typing-extensions>=4.6.0
+Requires-Dist: brotli>=1.0.9 ; extra == 'brotli'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://api.scrape.ly
+Project-URL: Changelog, https://github.com/SandeepDev1/scrapely/blob/main/scrapely-client-python/CHANGELOG.md
+Project-URL: Documentation, https://api.scrape.ly
+Project-URL: Issue Tracker, https://github.com/SandeepDev1/scrapely/issues
+Project-URL: Source Code, https://github.com/SandeepDev1/scrapely
+Provides-Extra: brotli
+Description-Content-Type: text/markdown
+
+<h1 align="center">Scrapely API client for Python</h1>
+
+<p align="center">
+  <strong>The official Python client for the <a href="https://api.scrape.ly">Scrapely REST API</a>, and a drop-in replacement for <code>apify-client</code>.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/scrapely-client-python/"><img src="https://badge.fury.io/py/scrapely-client-python.svg" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/scrapely-client-python/"><img src="https://img.shields.io/pypi/dm/scrapely-client-python" alt="PyPI downloads"></a>
+  <a href="https://pypi.org/project/scrapely-client-python/"><img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python versions"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/pypi/l/scrapely-client-python" alt="License"></a>
+</p>
+
+`scrapely-client-python` lets you talk to the [Scrapely platform](https://api.scrape.ly) from Python — run Actors, manage storages (datasets, key-value stores, request queues), schedule tasks, configure webhooks, and use everything else exposed by the Scrapely API. It ships both synchronous and asynchronous clients, fully typed responses, automatic retries with exponential backoff, tiered timeouts, pagination helpers, streaming, and a pluggable HTTP layer.
+
+> **Migrating from `apify-client`?** Just swap the import — the class names (`ApifyClient`, `ApifyClientAsync`), constructor arguments, methods and return types are identical. See [Migrating from apify-client](#migrating-from-apify-client) below.
+>
+> If you want to **build** Actors in Python rather than consume the API, use the Scrapely SDK for Python instead — it bundles this client and adds Actor-side primitives.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Migrating from apify-client](#migrating-from-apify-client)
+- [Features](#features)
+- [Usage examples](#usage-examples)
+- [Documentation](#documentation)
+- [Related projects](#related-projects)
+- [Support and community](#support-and-community)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+`scrapely-client-python` requires **Python 3.11 or higher** and is published on [PyPI](https://pypi.org/project/scrapely-client-python/).
+
+- From [PyPI](https://pypi.org/project/scrapely-client-python/), it can be installed for example with [pip](https://pip.pypa.io/):
+
+    ```bash
+    pip install scrapely-client-python
+    ```
+
+    or with [uv](https://docs.astral.sh/uv/):
+
+    ```bash
+    uv add scrapely-client-python
+    ```
+
+    or any other Python package manager that consumes PyPI.
+
+    The client compresses request bodies with `gzip` by default (no extra dependencies required). To opt in to
+    `brotli` (better compression ratio), install the optional extra and pass `compression='brotli'`:
+
+    ```bash
+    pip install "scrapely-client-python[brotli]"
+    # or
+    uv add "scrapely-client-python[brotli]"
+    ```
+
+
+## Quick start
+
+You'll need a Scrapely API token — find yours in the integrations section of the Scrapely Console. Pass it to the client and you're ready to go.
+
+### Synchronous client
+
+```python
+from scrapely_client import ApifyClient
+
+client = ApifyClient('MY-SCRAPELY-TOKEN')
+
+# Start an Actor and wait for it to finish.
+run = client.actor('apify/hello-world').call(
+    run_input={'message': 'Hello, Scrapely!'},
+)
+if run is None:
+    raise RuntimeError('Actor run was not found.')
+
+# Iterate items from the run's default dataset.
+for item in client.dataset(run.default_dataset_id).iterate_items():
+    print(item)
+```
+
+### Asynchronous client
+
+```python
+import asyncio
+
+from scrapely_client import ApifyClientAsync
+
+
+async def main() -> None:
+    client = ApifyClientAsync('MY-SCRAPELY-TOKEN')
+
+    run = await client.actor('apify/hello-world').call(
+        run_input={'message': 'Hello, Scrapely!'},
+    )
+    if run is None:
+        raise RuntimeError('Actor run was not found.')
+
+    # Iterate items from the run's default dataset.
+    async for item in client.dataset(run.default_dataset_id).iterate_items():
+        print(item)
+
+
+asyncio.run(main())
+```
+
+> **Keep your token secret.** It authorizes requests on your behalf and can incur usage costs. Never commit it to source control or expose it to client-side code.
+
+## Migrating from apify-client
+
+`scrapely-client-python` is a drop-in replacement for `apify-client` — swap the import and nothing else in
+your code needs to change:
+
+```diff
+- from apify_client import ApifyClient, ApifyClientAsync
++ from scrapely_client import ApifyClient, ApifyClientAsync
+```
+
+- The class names (`ApifyClient`, `ApifyClientAsync` and all resource clients), constructor
+  arguments, methods and return types are identical to `apify-client` (aliases `ScrapelyClient` /
+  `ScrapelyClientAsync` are also exported).
+- The client talks to `https://api.scrape.ly` by default; override with the `api_url` /
+  `api_public_url` arguments if you need a different endpoint.
+- Scrapely-specific extensions (e.g. pay-per-event `charging_hooks`, `task().publish()` /
+  `task().unpublish()`, `run().charge()`) are strictly additive — code written for `apify-client`
+  runs unchanged.
+
+For a guided walkthrough — authenticating, running an Actor, and reading its results — see the Quick start guide.
+
+## Features
+
+- **Synchronous and asynchronous clients** — pick `ApifyClient` or `ApifyClientAsync` to match your codebase; both expose the same API (Asyncio support).
+- **Fully typed responses** — every method returns a [Pydantic](https://docs.pydantic.dev/) model generated from the Apify OpenAPI spec, with IDE autocomplete and runtime validation (Typed models).
+- **Automatic retries** — exponential backoff for network errors, HTTP 429, and 5xx responses, configurable per client (Retries).
+- **Tiered timeouts** — short / medium / long tiers picked per endpoint, overridable per call (Timeouts).
+- **Pagination and streaming** — iterate datasets, key-value store keys, or live logs without manual paging or buffering (Pagination, Streaming).
+- **Convenience methods** — `call()`, `wait_for_finish()`, nested resource access, and other shortcuts that hide platform quirks (Convenience methods).
+- **Pluggable HTTP layer** — swap the default Impit-based HTTP client for `httpx`, `requests`, `aiohttp`, or any custom implementation (Custom HTTP clients).
+- **Structured errors** — every API error surfaces as an `ApifyApiError` with HTTP-specific subclasses for precise handling (Error handling).
+- **Debug logging** — opt-in structured logging on the `apify_client` logger captures request URLs, status codes, retry attempts, and more (Logging).
+
+## Usage examples
+
+The client mirrors the platform's resource model. Each entry point returns either a **single-resource client** for an individual item or a **collection client** for listing and creating items (Single and collection clients).
+
+### List Actors and create one
+
+```python
+actors = client.actors()
+print(actors.list(limit=10).items)
+
+new_actor = actors.create(name='my-actor')
+```
+
+### Stream live logs while a run is in progress
+
+```python
+run = client.actor('apify/web-scraper').start(run_input={...})
+
+with client.run(run.id).log().stream() as log_stream:
+    for chunk in log_stream.iter_bytes():
+        print(chunk.decode(), end='')
+```
+
+### Read and write key-value store records
+
+```python
+store = client.key_value_store('STORE-ID')
+store.set_record('greeting', {'message': 'Hello!'})
+record = store.get_record('greeting')
+```
+
+### Iterate dataset items with automatic pagination
+
+```python
+for item in client.dataset('DATASET-ID').iterate_items(fields=['title', 'url']):
+    process(item)
+```
+
+### Tune retries and timeouts
+
+```python
+from datetime import timedelta
+
+from scrapely_client import ApifyClient
+
+client = ApifyClient(
+    token='MY-SCRAPELY-TOKEN',
+    max_retries=8,
+    min_delay_between_retries=timedelta(milliseconds=500),
+    timeout_long=timedelta(minutes=10),
+)
+```
+
+For end-to-end recipes — passing input, managing tasks for reusable input, retrieving and merging Actor data, integrating with Pandas, plugging in a custom HTTP client — see the Guides.
+
+## Documentation
+
+The full documentation lives at **https://api.scrape.ly**.
+
+| Section | What you'll find |
+| --- | --- |
+| Introduction | Overview, prerequisites, and a tour of the client. |
+| Quick start | Authenticate, run an Actor, and fetch its results step by step. |
+| Concepts | Asyncio, single vs. collection clients, nested clients, error handling, retries, logging, convenience methods, pagination, streaming, custom HTTP clients, timeouts. |
+| Guides | Pass input to an Actor, manage tasks for reusable input, retrieve Actor data, integrate with data libraries (e.g. Pandas), use HTTPX as the HTTP client. |
+| Upgrading | Migrating between major versions. |
+| API reference | Generated reference for every class, method, and model. |
+| Changelog | Release history and breaking changes. |
+
+## Related projects
+
+- **Apify SDK for Python** — toolkit for **building** Apify Actors in Python (this client is bundled with it).
+- **[Crawlee for Python](https://crawlee.dev/python)** — high-level web scraping and browser automation framework that powers many Actors.
+- **Apify API client for JavaScript / TypeScript** — equivalent Apify API client for Node.js.
+- **Apify SDK for JavaScript / TypeScript** — equivalent Apify SDK for Node.js.
+- **[Crawlee for JavaScript / TypeScript](https://crawlee.dev)** — original Node.js implementation of the Crawlee framework.
+- **Apify CLI** — command-line tool for interacting with the Scrapely platform: managing Actors, runs, storages, local development, and deployment.
+
+## Support and community
+
+- **GitHub issues** — report a bug or request a feature in the repository's [issue tracker](https://github.com/apify/apify-client-python/issues).
+
+## 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
+```
+
+## License
+
+Released under the [Apache License 2.0](./LICENSE).