orphan:

Contributing

The source code for 竜 TatSu is posted to it’s repository on GitHub. Bug reports, patches, suggestions, and improvements are welcome.

If you want to contribute to the development of 竜 TatSu, follow the instructions below to create an environment in which 竜 TatSu can be tested.

Programming 竜 TatSu

prerequisites

Before creating an environment for 竜 TatSu these must be available:

• Python >= 3.12 (use your preferred way of installing it)

• uv as project environment manager (see the uv installation instructions).

• optional installation of Invoke on the system’s python3

竜 TatSu relies on Invoke’s tasks.py to run the tasks for static analysis, testing, building, documentation, and publishing the project. tasks.py resides in ./tatsu/invoke_tasks.py and there is a symbolic link to it at the project’s repository root, ./invoke_tasks.py.

To run the tasks use:

$ uv run invoke

Or fun invoke directly if it’s installed on the system’s python3:

$ invoke

Coding Standard

竜 TatSu targets Python 3.12 and uses the corresponding syntax. Use the latest features allowed in the syntax, and use any new and recommended features in the standard library. Avoid all deprecated features.

• Adhere to the Black formatting standard.

• Use pythonic names; avoid underscores unless necessary for clarity.

• Use the | operator for Union in typing annotations.

• Add type annotations to all functions and methods. When types involving Callable are required, use a type alias for the Callable signature.

type BinaryFunc = Callable[[float, float], float]

• Prefer pathlib over os.path for path manipulation when feasible.

• Avoid type annotations for local variables inside functions unless a type checker/linter such as pyright, ty, mypy, or ruff requests them.

bootstrap

Clone the 竜 TatSu repository and switch to the created directory:

$ git clone git@github.com:neogeny/TatSu.git
$ cd tatsu

There will be at least these directories under the main project directory:

• ./tatsu/ the top level package for the project

• ./tests/ unit and integration tests

• ./grammar/ grammars used by the project

• ./docs/ the Sphinx documentation

• ./examples/ example projects

• ./etc/ configuration files and templates

.
├── docs
│   └── _static
│       ├── css
│       └── images
├── etc
│   ├── sublime
│   └── vim
│       ├── ftdetect
│       └── syntax
├── examples
│   ├── calc
│   │   └── grammars
│   └── g2e
│       └── grammar
├── grammar
├── media
├── scripts
├── tatsu
│   ├── codegen
│   ├── collections
│   ├── g2e
│   ├── mixins
│   ├── ngcodegen
│   └── util
└── tests
    ├── grammar
    └── zzz_bootstrap

environment

Use uv to create and configure a Python environment with the libraries required for development and testing:

$ uv sync

testing

invoke -c invoke_tasks runs all static analysis (linting), typing, unit test, documentation, and build tasks by default:

$ uv run invoke -c invoke_tasks
────────────────────────────────────────────────────────
-> clean
-> ruff
-> ty
-> pyright
──── ✔ lint ────────────────────────────────────────────
-> pytest
──── ✔ test ────────────────────────────────────────────
-> docs
──── ✔ docs ────────────────────────────────────────────
-> examples/g2e
-> examples/calc
──── ✔ examples ────────────────────────────────────────
-> build
──── ✔ build ───────────────────────────────────────────
-> requirements.txt
-> requirements-dev.txt
-> requirements-test.txt
-> requirements-doc.txt
──── ✔ requirements ────────────────────────────────────
──── ✔ all ─────────────────────────────────────────────

Sponsorship

If you’d like to contribute to the future development of 竜 TatSu, please make a donation to the project.

Among the planned new features a unified intermediate model for parsing and translating programming languages.