getting started¶
install by, write a .by file, and run it. everything below takes about five
minutes
installation¶
basedpython ships as the basedpython package, which installs two executables:
by, the type checker and transpiler, and buff, the linter and formatter
a directory that has no pyproject.toml yet needs uv init --bare first
verify it works:
the executables are in the project's environment, so run them through uv run, or activate the
environment. the rest of these docs write by on its own
your first file¶
basedpython source files use the .by extension. create main.by:
run it directly:
by run main finds main.by in the current directory, transpiles it (and all
other .by files in the project), then executes it with your python interpreter
by run takes a module, not a path
the argument is what you would pass to python -m, so it is main, not
main.by — and a nested entry point is pkg.main
naming the module every time gets old once a project has an entry point. configure one and by run alone is enough:
that goes in the [tool.basedpython] section of pyproject.toml, or in a
basedpython.toml beside it, which holds the same options at the top level:
see configuration for everything that can go in there
building¶
by build writes the project to build/ as python:
that is the whole project, not only its .by files — a hand-written .py
module, a py.typed, a data file the program reads are all carried across to
the same place, so build/ runs the way the source does
the generated .py files are ordinary python. run them with any python tool:
to ship the project rather than run it, build a wheel — see packaging:
compiling¶
by compile writes the same tree with native extension modules beside the python, and python
imports those instead. it takes no change to the source, and a function it cannot compile still
runs interpreted:
CI integration¶
converting python to basedpython¶
you don't have to start from an empty file. by transpile --reverse runs the
transpiler backwards, rewriting python source into the basedpython idiom it
would have lowered from:
from typing import Callable, Optional
class Node:
children: list["Node"]
def __eq__(self, other: object) -> bool:
if other is self:
return True
return isinstance(other, Node) and other.children == self.children
def find(self, key: str) -> Optional["Node"]: ...
on_visit: Callable[[Node], None]
comes back as:
from typing import Optional
class Node:
children: list[Node]
def __eq__(self, other: object) -> bool:
if other === self:
return True
return isinstance(other, Node) and other.children == self.children
def find(self, key: str) -> Optional[Node]: ...
on_visit: (Node) -> None
the identity fast path became ===. the
isinstance call stays a call: basedpython's x is Node is a type test that
the value's static type can settle, and a python check is there to run
whatever the annotations say. the quotes came off the
forward references,
Callable[[Node], None] became an arrow type, and the
now-unused Callable import was pruned. the : ... body stayed: it is a body
the method is entitled to, and only in a stub does dropping it leave a
declaration that says the same thing
point it at a directory to convert a whole tree in place, every .py to a
.by:
each reverse transform mirrors a forward one, so a converted file transpiles back to the program you started with
read the diff
reversing converts the constructs that have a reverse transform and leaves
the rest alone — __init__ does not become
init(...), Optional[T] does not become T?.
it is a head start, not a port. run by check on the result, and read
differences from python before you
commit it
low-level: single file transpilation¶
by transpile is the low-level command for single-file transforms. it reads a
file (or stdin) and writes the transpiled python to stdout:
output goes to stdout - redirect it to a file if you want to keep it
(by transpile hello.by > hello.py). use by build to transpile a whole
project into build/
forward references¶
basedpython has no manual forward-reference syntax — a string in an annotation is a string-literal type, not a deferred name. so when a class refers to itself before its definition finishes, the transpiler quotes the reference for you:
quoting only happens when it's needed. on python 3.14+ annotations are
evaluated lazily (PEP 649), and if you target an older runtime but want
every annotation deferred anyway you can opt into a blanket
from __future__ import annotations — in either case the reference is left
as-is
next¶
-
every piece of syntax basedpython adds, one page at a time
-
what changes when pydantic, sqlalchemy, pytest or django is in the project
-
every command and flag, including the ones inherited from
ty -
what happens between the
.byfile and the python that runs