Skip to main content

Independent set of tools for working with GDScript - parser, linter and formatter

Project description

GDScript Toolkit

License: MIT Code style: black

This project provides a set of tools for daily work with GDScript. At the moment it provides:

  • A parser that produces a parse tree for debugging and educational purposes.
  • A linter that performs a static analysis according to some predefined configuration.
  • A formatter that formats the code according to some predefined rules.


To install this project you need python3 and pip.

Use this command in your terminal to install from this git repository:

pip3 install gdtoolkit

Linting with gdlint

To run a linter you need to perform installation first. Once done, you can run e.g.:

$ gdlint misc/

Which outputs messages like:

misc/ Error: Function argument name "aOrigin" is not valid (function-argument-name)
misc/ Error: Function argument name "aPos" is not valid (function-argument-name)

To tweak the default check settings, you can dump the default config to a file:

$ gdlint -d
$ cat gdlintrc
class-load-variable-name: (([A-Z][a-z0-9]*)+|_?[a-z][a-z0-9]*(_[a-z0-9]+)*)
class-name: ([A-Z][a-z0-9]*)+
class-variable-name: _?[a-z][a-z0-9]*(_[a-z0-9]+)*
constant-name: '[A-Z][A-Z0-9]*(_[A-Z0-9]+)*'
disable: []
enum-element-name: '[A-Z][A-Z0-9]*(_[A-Z0-9]+)*'
enum-name: ([A-Z][a-z0-9]*)+
function-argument-name: _?[a-z][a-z0-9]*(_[a-z0-9]+)*
function-arguments-number: 10
function-preload-variable-name: ([A-Z][a-z0-9]*)+
function-name: (_on_([A-Z][a-z0-9]*)+(_[a-z0-9]+)*|_?[a-z][a-z0-9]*(_[a-z0-9]+)*)
function-variable-name: '[a-z][a-z0-9]*(_[a-z0-9]+)*'
load-constant-name: (([A-Z][a-z0-9]*)+|[A-Z][A-Z0-9]*(_[A-Z0-9]+)*)
loop-variable-name: _?[a-z][a-z0-9]*(_[a-z0-9]+)*
signal-name: '[a-z][a-z0-9]*(_[a-z0-9]+)*'
sub-class-name: _?([A-Z][a-z0-9]*)+

Once the dump is performed, you can modify the gdlintrc file and optionally rename it to .gdlintrc. From now on, linter will use this config file to override the default config.

Formatting with gdformat

Formatting may lead to data loss, so it's highly recommended to use it along with Version Control System (VCS) e.g. git

gdformat is the uncompromising GDScript code formatter. The only configurable thing is max line length allowed (--line-length). The rest will be taken care of by gdformat in a one, consistent way.

To run a formatter you need to perform installation first. Once done, given a file:

class X:
	var x=[1,2,{'a':1}]
	var y=[1,2,3,]     # trailing comma
	func foo(a:int,b,c=[1,2,3]):
		if a in c and \
		   b > 100:
func bar():

when you run gdformat, the file will be reformatted as follows:

class X:
	var x = [1, 2, {'a': 1}]
	var y = [
	]  # trailing comma

	func foo(a: int, b, c = [1, 2, 3]):
		if a in c and b > 100:

func bar():

If the program formats your files successfully, it will return the exit code 0. Non-zero code will be returned otherwise.

Parsing with gdparse

To parse a file, use the gdparse program:

gdparse tests/valid-gd-scripts/ -p

The parser outputs a tree that represents your code's structure:

      signal_stmt	sss
      signal_stmt	sss

If the program parses your file sucessfully, it will return the exit code 0.

Running tests

To run tests you need tox, a tool to automate testing in Python.

Install it with:

pip3 install tox

To invoke entire test suite, in the godot-gdscript-toolkit project directory, run:


You can run only selected test cases:

tox -e py3 -- -k lint

For manual testing, you can consider installing package in editable mode:

pip3 install -e .

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for gdtoolkit, version 3.3.1
Filename, size File type Python version Upload date Hashes
Filename, size gdtoolkit-3.3.1-py3-none-any.whl (45.4 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size gdtoolkit-3.3.1.tar.gz (34.3 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page