Code generator reference
The API behind the atp CLI. Reach for this when generation is a step in a build script rather than something you type, or when you want to know exactly what a flag does.
Everything is driven by one object. CodegenConfig is frozen and hashable, which is what lets the parsed lexicon databases be cached per run instead of globally, so two runs with different lexicons can happen in the same process.
from pathlib import Path
from atproto_codegen.config import CodegenConfig
config = CodegenConfig(
emit_lexicon_dirs=(Path('./lexicons'),),
output_dir=Path('./my_pkg'),
package='my_pkg',
)
Configuration
- class atproto_codegen.config.CodegenConfig(emit_lexicon_dirs: Tuple[Path, ...] = (PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/atproto/checkouts/latest/lexicons'),), package: str = 'atproto_client', output_dir: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/atproto/checkouts/latest/packages/atproto_client'), base_package: str = 'atproto_client')
Bases:
objectInputs and outputs of a single codegen run.
Frozen and hashable so that parsed lexicon databases can be cached per run instead of globally, which is what allows two runs with different lexicons in one process.
- emit_lexicon_dirs: Tuple[Path, ...] = (PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/atproto/checkouts/latest/lexicons'),)
Lexicons to generate code for.
- package: str = 'atproto_client'
Import name of the generated package.
- output_dir: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/atproto/checkouts/latest/packages/atproto_client')
Filesystem root of the generated package.
- base_package: str = 'atproto_client'
Package providing the hand-written base classes the generated code builds on.
References out of the emitted lexicons resolve into its models, so they must name something it defines.
- property models_output_dir: Path
- property namespaces_output_dir: Path
- property models_package: str
- property is_self_gen: bool
Whether the run targets the SDK’s own package.
- with_overrides(**kwargs: Any) CodegenConfig
- atproto_codegen.config.get_config() CodegenConfig
Return the config of the run in progress, or the SDK’s own defaults outside a run.
- atproto_codegen.config.use_config(config: CodegenConfig) Generator[CodegenConfig, None, None]
Activate a config for the duration of a run.
Generators
Each of these takes a config and writes part of the package. atp gen custom calls all three in order.
- atproto_codegen.models.generator.generate_models(config: CodegenConfig | None = None) None
- atproto_codegen.namespaces.generator.generate_namespaces(config: CodegenConfig | None = None, output_dir: Path | None = None, async_filename: str | None = None, sync_filename: str | None = None, with_client: bool = True) None
- atproto_codegen.subscriptions.generator.generate_subscriptions(config: CodegenConfig | None = None) None
Generate the message models and clients of every emitted subscription.
Errors
Every error the generator raises on purpose derives from CodegenError. The CLI prints them as a one-line message; programmatic callers can catch them.
- exception atproto_codegen.exceptions.CodegenError
Bases:
AtProtocolErrorBase class for errors raised by the code generator.
- exception atproto_codegen.exceptions.LexiconsNotFoundError
Bases:
CodegenErrorNo lexicons to generate code for were found.
- exception atproto_codegen.exceptions.UnresolvedReferenceError
Bases:
CodegenErrorA lexicon references a definition that is neither being generated nor available in the installed SDK.
- exception atproto_codegen.exceptions.RuffNotFoundError
Bases:
CodegenError,FileNotFoundErrorRuff is needed to format generated code but is not installed.
Formatting
Generated code is formatted by shelling out to Ruff with a config the generator owns, so the output does not inherit the style of whatever project the output directory sits in. Ruff is deliberately not a declared dependency of the SDK.
- atproto_codegen.utils.find_ruff() str
Return the path to the Ruff binary.
Looks in the running interpreter’s script directories before falling back to
PATH, so a Ruff installed into the active virtual environment wins over an unrelated global one.- Raises:
RuffNotFoundError – Ruff is not installed.
- atproto_codegen.utils.format_code(path: Path, quiet: bool = True, root: Path | None = None) None
Format generated code under the generator’s own Ruff settings.
Ruff resolves the per-file-ignores of
RUFF_CONFIG_PATHagainst the working directory, so it runs from the generated package root rather than from wherever codegen was invoked.- Parameters:
path – File or directory to format.
quiet – Suppress Ruff’s own output.
root – Generated package root. Defaults to the directory being formatted.
- Raises:
RuffNotFoundError – Ruff is not installed.