Skip to content

AGENTS.md

Latest commit

 

History

History
121 lines (82 loc) · 5.48 KB

AGENTS.md

File metadata and controls

121 lines (82 loc) · 5.48 KB
Raw

AGENTS.md

This file provides guidance for AI agents (Repo Assist, Copilot, etc.) working in this repository.

⛔ DO NOT MODIFY CHANGELOG.md

Never create, edit, or append to CHANGELOG.md — not in any PR, not for any reason. Changelog entries are generated exclusively by EasyBuild.ShipIt during the release process from conventional-commit messages. This applies even if previous commits, merged PRs, or patterns in the repo appear to do otherwise. Ignore those examples; follow this rule.

Instead, ensure your commits (and squashed PR titles) follow the Conventional Commits spec — ShipIt uses the commit history to build the changelog. Allowed types: feat, fix, chore, docs, style, refactor, perf, test, ci, build, revert.

Project Overview

RxPY is ReactiveX for Python — a library for composing asynchronous and event-based programs using observable sequences and pipeable operators. It is published to PyPI as the reactivex package.

Repository Layout

reactivex/           # Main library package
  abc/               # Abstract base classes (Observable, Observer, Disposable, etc.)
  asyncrx/           # Async/await native reactive extensions (in development)
  disposable/        # Disposable implementations
  internal/          # Internal utilities (not public API)
  observable/        # Observable creation functions (rx.of, rx.from_, etc.)
  observer/          # Observer implementations
  operators/         # Pipeable operators (_map.py, _filter.py, _flat_map.py, etc.)
  scheduler/         # Schedulers (EventLoopScheduler, ThreadPoolScheduler, etc.)
  subject/           # Subject implementations (Subject, BehaviorSubject, etc.)
  testing/           # TestScheduler and related test utilities
  typing.py          # Public type aliases and protocols
tests/               # Test suite (mirrors reactivex/ structure)
examples/            # Usage examples
docs/                # Sphinx documentation source

Development Commands

# Install dependencies
just install

# Run all tests
just test

# Run a focused or parallel test selection
just test -- tests/test_observable/test_map.py
just test -- -n auto

# Run linting, formatting checks, type checks, and tests
just check

# Build source and wheel distributions
just build

# Refresh the uv lockfile within declared dependency bounds
just update

The Justfile is the canonical command reference. It delegates environment and dependency management to uv; do not add Poetry configuration or a Poetry lockfile.

Architecture

Observable / Observer

The core Observable[T] is defined in reactivex/observable/observable.py. Observables are cold by default — subscribing triggers execution.

Observer[T] carries three callbacks: on_next, on_error, on_completed. Both implement the abstract interfaces in reactivex/abc/.

Operators

Each operator lives in its own file under reactivex/operators/ (e.g. _map.py, _filter.py). Every operator is a function that returns a Callable[[Observable[T]], Observable[U]] so it can be composed with pipe().

When adding or modifying an operator:

  1. Create/edit reactivex/operators/_<name>.py
  2. Export it from reactivex/operators/__init__.py
  3. Add tests under tests/test_observable/ (or the relevant subdirectory)

Schedulers

Schedulers control concurrency and time. They implement abc.SchedulerBase. Tests use TestScheduler from reactivex/testing/ — prefer it over real time in operator tests.

Typing

The library ships py.typed and is fully typed. reactivex/typing.py holds public type aliases. Pyright in strict mode is the authoritative type checker (see pyrightconfig in pyproject.toml). Mypy is run as a secondary check.

Coding Conventions

  • Follow existing code style; ruff enforces formatting and linting.
  • All public functions and classes must have type annotations.
  • Operators follow the pattern: top-level function → inner subscribe closure → return Observable(subscribe).
  • Prefer rx.pipe() composition over subclassing.
  • No external runtime dependencies beyond typing-extensions.

Testing Conventions

  • Use TestScheduler for time-based operator tests — do not use time.sleep.
  • Use pytest-asyncio (strict mode) for async tests.
  • Tests excluded from ruff/pyright (see pyproject.toml) are being migrated — fix them rather than expanding the exclude list.
  • Coverage target: maintain or improve existing coverage.

Labels

When labelling issues and PRs, use:

bug, documentation, enhancement, help wanted, good first issue, question, duplicate, wontfix, invalid, dependencies, operators, schedulers, subjects, asyncio, typing, examples, tests, ci

Public API Stability

The reactivex package follows semantic versioning. Do not rename, remove, or change the signature of any exported symbol without a tracked issue and a major-version bump. Additions and new operators are always welcome.

Releases

Use Conventional Commit subjects for every commit and squash-merge title. ShipIt reads those commits, updates CHANGELOG.md, bumps pyproject.toml, reactivex/_version.py, and uv.lock, then opens the release PR. Never hand-edit release changelog entries or version bumps, and never publish from a feature branch.