Skip to content

.rules.md

Latest commit

 

History

History
29 lines (19 loc) · 3.17 KB

.rules.md

File metadata and controls

29 lines (19 loc) · 3.17 KB
Raw

Coding guidelines

This file provides guidance to programming agents when working with code in this repository.

The Apify SDK for Python (apify on PyPI) is the library for building Apify Actors in Python. It builds on Crawlee and the Apify API client.

Read CONTRIBUTING.md first. It covers setup, tasks, tests, code style, documentation, and commits, and all of it applies to agents too.

@CONTRIBUTING.md

Pydantic models

Don't introduce a shared Pydantic base model to centralize model_config. Each model inherits pydantic.BaseModel and declares model_config = ConfigDict(...) inline, which also keeps ruff's flake8-type-checking and RUF012 checks working, since they only recognize a literal pydantic.BaseModel base.

model_dump(by_alias=True) serializes every model under camelCase names. Keep it that way:

  • API / event / data models (camelCase JSON round-trip with the platform) — set model_config = ConfigDict(alias_generator=to_camel), so both validation and serialization use the camelCase name.
  • Configuration — validated from environment variables, so each field carries a validation_alias (a plain string, or AliasChoices(...) for several legacy env names). Serialization is handled by the model-level alias_generator=AliasGenerator(serialization_alias=to_camel). Don't use alias= on a Configuration field — it pins serialization to the env-var name and defeats the camelCase generator.
  • Set an explicit serialization_alias only when the wire name isn't the to_camel derivation of the field name (e.g. RequestQueueHead.lock_time -> lockSecs).

Architecture

  • Actor (_actor.py) is a lazy-object-proxy wrapping _ActorType. It works both as a class (Actor.is_at_home()) and as a context manager (async with Actor:); on __aenter__ the proxy's __wrapped__ is replaced with the active _ActorType instance.
  • Configuration (_configuration.py) extends Crawlee's Configuration and is populated from APIFY_* environment variables.
  • Named child runs (_child_runs.py) — runs started with run_name are persisted in the default key-value store so they can be reattached after a migration or resurrection; exposed through Actor.child_runs.
  • Storage clients (storage_clients/) implement Crawlee's storage client interface: ApifyStorageClient talks to the Apify API (separate sub-clients for single vs. shared request queues), FileSystemStorageClient adds Apify-specific key-value store behavior, and SmartApifyStorageClient delegates to the cloud client on the platform and to the local one elsewhere.
  • Events — ApifyEventManager receives platform events over a WebSocket.
  • Errors — apify.errors only re-exports the exceptions from apify_client.errors; the SDK defines no error classes of its own, and API calls raise the client exceptions unchanged.
  • Response and data models (Run, pricing info, webhook representations) come from apify-client; the SDK doesn't define its own. The platform env-var enums (ApifyEnvVars, ActorEnvVars) live in apify._consts.