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 Buy me a coffe

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.
  • A code metrics calculator which calculates cyclomatic complexity of functions and classes.

Installation

To install this project you need python3 and pip. Regardless of the target version, installation is done by pip3 command and for stable releases, it downloads the package from PyPI.

Godot 4

pip3 install "gdtoolkit==4.*"
# or
pipx install "gdtoolkit==4.*"

Godot 3

pip3 install "gdtoolkit==3.*"
# or
pipx install "gdtoolkit==3.*"

master (latest)

Latest version (potentially unstable) can be installed directly from git:

pip3 install git+https://github.com/Scony/godot-gdscript-toolkit.git
# or
pipx install git+https://github.com/Scony/godot-gdscript-toolkit.git

Linting with gdlint (more)

To run a linter you need to execute gdlint command like:

$ gdlint misc/MarkovianPCG.gd

Which outputs messages like:

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

Formatting with gdformat (more)

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

To run a formatter you need to execute gdformat on the file you want to format. So, given a test.gd 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:
			print('foo')
func bar():
	print('bar')

when you execute gdformat test.gd command, the test.gd file will be reformatted as follows:

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:
			print('foo')


func bar():
	print('bar')

Parsing with gdparse (more)

To run a parser you need to execute the gdparse command like:

gdparse tests/valid-gd-scripts/recursive_tool.gd -p

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

start
  class_def
    X
    class_body
      tool_stmt
      signal_stmt	sss
  class_def
    Y
    class_body
      tool_stmt
      signal_stmt	sss
  tool_stmt

Calculating cyclomatic complexity with gdradon

To run cyclomatic complexity calculator you need to execute the gdradon command like:

gdradon cc tests/formatter/input-output-pairs/simple-function-statements.in.gd tests/gd2py/input-output-pairs/

The command outputs calculated metrics just like Radon cc command does for Python code:

tests/formatter/input-output-pairs/simple-function-statements.in.gd
    C 1:0 X - A (2)
    F 2:1 foo - A (1)
tests/gd2py/input-output-pairs/class-level-statements.in.gd
    F 22:0 foo - A (1)
    F 24:0 bar - A (1)
    C 18:0 C - A (1)
tests/gd2py/input-output-pairs/func-level-statements.in.gd
    F 1:0 foo - B (8)

Using gdtoolkit's GitHub action

In order to setup a simple action with gdtoolkit's static checks, the base action from this repo can be used:

name: Static checks

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  static-checks:
    name: 'Static checks'
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: Scony/godot-gdscript-toolkit@master
    - run: gdformat --check source/
    - run: gdlint source/

See the discussion in https://github.com/Scony/godot-gdscript-toolkit/issues/239 for more details.

Using gdtookit in pre-commit

To add gdtookit as a pre-commit hook check the latest GitHub version (eg 4.2.2) and add the followingto your pre-commit-config.yaml with the latest version.

repos:
  # GDScript Toolkit
  - repo: https://github.com/Scony/godot-gdscript-toolkit
    rev: 4.2.2
    hooks:
      - id: gdlint
        name: gdlint
        description: "gdlint - linter for GDScript"
        entry: gdlint
        language: python
        language_version: python3
        require_serial: true
        types: [gdscript]
      - id: gdformat
        name: gdformat
        description: "gdformat - formatter for GDScript"
        entry: gdformat
        language: python
        language_version: python3
        require_serial: true
        types: [gdscript]

Development (more)

Everyone is free to fix bugs or introduce new features. For that, however, please refer to existing issue or create one before starting implementation.

Project details


Download files

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

Source Distribution

gdtoolkit-4.3.4.tar.gz (49.0 kB view details)

Uploaded Source

Built Distribution

gdtoolkit-4.3.4-py3-none-any.whl (61.8 kB view details)

Uploaded Python 3

File details

Details for the file gdtoolkit-4.3.4.tar.gz.

File metadata

  • Download URL: gdtoolkit-4.3.4.tar.gz
  • Upload date:
  • Size: 49.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.9.23

File hashes

Hashes for gdtoolkit-4.3.4.tar.gz
Algorithm Hash digest
SHA256 42f8d528829a081809c8492c5936729b9fafca640fc46026ae98299fe0d3a93a
MD5 2d8f31b8e0c7746c6020a3bb54aa9ab4
BLAKE2b-256 8f8cec8eb8e8264fedcfc1f30374b56083b917dd187a9e2452d38cabac69f515

See more details on using hashes here.

File details

Details for the file gdtoolkit-4.3.4-py3-none-any.whl.

File metadata

  • Download URL: gdtoolkit-4.3.4-py3-none-any.whl
  • Upload date:
  • Size: 61.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.9.23

File hashes

Hashes for gdtoolkit-4.3.4-py3-none-any.whl
Algorithm Hash digest
SHA256 b3ba44d81ae41f1fdcdc8b4a79bd7419bb7651cc0f8ed9c5ccab1ff18d2ba2d4
MD5 ac6006fab9b2f188c151988c3cad7750
BLAKE2b-256 5967de74cd511c66935008340ebfc1a3a1a631e01158376e675d84776143b8dc

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page