# Agent Notes (pydivkit)

PyDivKit is a Python library for creating DivKit JSON configurations
declaratively. Requires Python >= 3.9. Dependency management uses `uv`, and the
package build backend is `hatchling`.

This directory can be used both:

- Standalone (open-source style): `uv` + `make`
- Inside the Arcadia monorepo: `ya` (plus local `.build/` artifacts)

See `pyproject.toml` for version/tooling config.


## Repo Layout

- Sources: `pydivkit/`
- Tests: `tests/`
- Generated API surface: `pydivkit/div/` (do not hand-edit)
- Codegen entrypoints: `codegen.sh`, `codegen_config.json`

All generated files in `pydivkit/div/` start with "Generated code. Do not modify."


## Local Development (uv + Makefile)

Preferred entrypoints:

```bash
make format   # ruff check --fix + ruff format
make lint     # ruff + formatting check + mypy
make test     # pytest
make codegen  # regenerate pydivkit/div + format
```

Manual equivalents:

```bash
uv sync --group dev --group test
uv run pytest tests/
uv run ruff check --fix . && uv run ruff format .
uv run ruff check .
uv run mypy pydivkit/core
```


## Generated Components

- `pydivkit/div/` is generated from DivKit schema (see `codegen.sh`).
- The directory is excluded from repo-wide ruff linting via `pyproject.toml`,
  but `make codegen` still formats that output.


## Code Generation

- Schema source: `../../schema/`
- Generator: `../../api_generator/` (`python3 -m api_generator`)
- Entry points: `make codegen` or `./codegen.sh` (see `codegen_config.json`)


## Arcadia Development (ya)

This workspace is often a small VSCode/clangd wrapper around the real Arcadia tree.
Local artifacts land in `.build/`.

Build (debug):

```bash
ya make -d "-DBUILD_LANGUAGES=CPP PY3" -DCONSISTENT_DEBUG=yes --prefetch -j8 \
  /Users/p-mosein/arcadia/divkit/public/json-builder/python
```

Build (release):

```bash
ya make -r "-DBUILD_LANGUAGES=CPP PY3" -DCONSISTENT_DEBUG=yes --prefetch -j8 \
  /Users/p-mosein/arcadia/divkit/public/json-builder/python
```

Test (SMALL, default):

```bash
ya test "-DBUILD_LANGUAGES=CPP PY3" -DCONSISTENT_DEBUG=yes --prefetch -j8 \
  /Users/p-mosein/arcadia/divkit/public/json-builder/python
```

Re-run last failed:

```bash
ya test -A -X "-DBUILD_LANGUAGES=CPP PY3" -DCONSISTENT_DEBUG=yes --prefetch -j8 \
  /Users/p-mosein/arcadia/divkit/public/json-builder/python
```

Style gate (Arcadia):

```bash
ya test --style /Users/p-mosein/arcadia/divkit/public/json-builder/python
```

Single test workflow:

```bash
ya test -L /Users/p-mosein/arcadia/divkit/public/json-builder/python
ya test -F "*test_expr*" /Users/p-mosein/arcadia/divkit/public/json-builder/python
ya test --test-filename="*test_expr.py" /Users/p-mosein/arcadia/divkit/public/json-builder/python
```

Arcadia-managed venv (includes tests):

```bash
ya ide venv \
  "-DBUILD_LANGUAGES=CPP PY3" -DCONSISTENT_DEBUG=yes --prefetch \
  --venv-root="/Users/p-mosein/Source/pydivkit/venv" \
  --venv-with-pip --venv-add-tests \
  /Users/p-mosein/arcadia/divkit/public/json-builder/python
```


## Architecture Notes

Core modules in `pydivkit/core/`:

- `entities.py`: Base entity classes (`BaseEntity`, `BaseDiv`)
- `fields.py`: fields, references, expressions (`Field`, `Ref`, `Expr`)
- `compat.py`: compatibility helpers
- `types/union.py`: union type injection/handling

Key concepts:

- Templates: subclasses of Div components become templates; `Field()` defines
  parameters and `Ref()` references them.
- Serialization: `.dict()` produces DivKit JSON; `dump()` handles recursive
  serialization.
- `make_div()` combines components + templates.

Key components:

- `BaseEntity`: foundation class for all PyDivKit objects with field validation
  and serialization.
- `BaseDiv`: base class for all DivKit components, extends `BaseEntity` with
  template support.

Type system notes:

- Casting/validation lives in core helpers (e.g. `cast_value_type()`), handling
  unions, sequences, mappings, and `BaseEntity` objects.
- Union type injection supports discriminated unions via the `type` field.

Template names default to `{module_name}.{class_name}` but can be overridden via
`__template_name__`.

Template sketch:

```python
import pydivkit as dk


class MyTemplate(dk.DivContainer):
    text: str = dk.Field()
    items = [dk.DivText(text=dk.Ref(text))]
```


## Tests

Tests focus on serialization correctness (Python objects -> expected DivKit JSON),
covering core entities, fields/refs/expr, and template behavior.


## Code Style / Typing

- Imports: stdlib, third-party, local (`pydivkit.*`); prefer explicit imports.
- Python: keep code compatible with Python 3.9.
- Types: use `from __future__ import annotations` in typed modules; avoid PEP604
  unions (`T | None`) since the min version is 3.9.
- Prefer `collections.abc` (`Sequence`, `Mapping`, `Iterator`) in runtime code.
- Avoid `Any` unless the data is truly dynamic/JSON-like.
- Errors: prefer early validation + actionable `ValueError`; use `TypeError` for
  incompatible type relationships.


## Tooling Notes

- Lint/format: `ruff` (see `pyproject.toml`), generated `pydivkit/div/` is
  excluded globally but codegen still formats that directory explicitly.
- Types: `mypy` runs in strict mode (see `pyproject.toml`).
- `pydivkit.code-workspace` may configure `clangd`/`clang-tidy` for the Arcadia tree.
