tb_lint package

Subpackages

Submodules

tb_lint.tb_lint module

Unified Linter - Modular Linting Framework

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Flexible, plugin-based linting system supporting multiple linters

Usage:

python3 tb_lint.py [options] <file.sv> [<file2.sv> …]

Options:
--help

Show this help message

--config FILE

Configuration file (JSON)

--linter NAME

Run specific linter (default: all)

--list-linters

List available linters

--strict

Treat warnings as errors

--json

Output in JSON format

--color

Enable colored output

-f FILE_LIST

File containing list of files (one per line)

-o OUTPUT_FILE

Output file for results

Examples

# Run all linters python3 tb_lint.py -f file_list.txt

# Run only NaturalDocs linter python3 tb_lint.py –linter naturaldocs file.sv

# Use custom config python3 tb_lint.py –config my_config.json -f files.txt

class tb_lint.tb_lint.Colors[source]

Bases: object

ANSI color codes

RED = '\x1b[0;31m'
GREEN = '\x1b[0;32m'
YELLOW = '\x1b[1;33m'
BLUE = '\x1b[0;34m'
CYAN = '\x1b[0;36m'
BOLD = '\x1b[1m'
NC = '\x1b[0m'
class tb_lint.tb_lint.UnifiedLinter(config_file: str | None = None, use_color: bool = False, strict_mode: bool = False)[source]

Bases: object

Unified linting orchestrator

Manages multiple linters and aggregates results

__init__(config_file: str | None = None, use_color: bool = False, strict_mode: bool = False)[source]

Initialize unified linter

Parameters:

  • config_file – Path to configuration file

  • use_color – Enable colored output

  • strict_mode – Treat warnings as errors

list_linters() → List[str][source]

Get list of available linters

run_linter(linter_name: str, file_paths: List[str]) → LinterResult[source]

Run a specific linter on files

Parameters:

  • linter_name – Name of linter to run

  • file_paths – List of files to check

Returns:

LinterResult with violations found

run_all_linters(file_paths: List[str]) → dict[source]

Run all enabled linters on files

Parameters:

file_paths – List of files to check

Returns:

Dictionary mapping linter names to results

print_result(result: LinterResult, output_file=None)[source]

Print linter results in human-readable format

Parameters:

  • result – LinterResult to print

  • output_file – File handle for output (default: stdout)

print_json(results: dict, output_file=None)[source]

Print results in JSON format

Parameters:

  • results – Dictionary of linter results

  • output_file – File handle for output (default: stdout)

print_command_info(args, files_to_check: List[str], output_file=None)[source]

Print command line information for tb_lint and each enabled linter

Parameters:

  • args – Command line arguments

  • files_to_check – List of files to check

  • output_file – File handle for output (default: stdout)

print_final_summary(results: dict, output_file=None)[source]

Print final TB_LINT summary

Parameters:

  • results – Dictionary of linter results

  • output_file – File handle for output (default: stdout)

get_exit_code(results: dict) → int[source]

Determine exit code based on results

Parameters:

results – Dictionary of linter results

Returns:

0 if all passed, 1 if violations found

tb_lint.tb_lint.main()[source]

Main entry point

tb_lint.verible_verilog_syntax module

Wrapper for verible-verilog-syntax --export_json

class tb_lint.verible_verilog_syntax.PreOrderTreeIterator(tree: Node, filter_: Callable[[Node], bool] | None = None, reverse_children: bool = False)[source]

Bases: _TreeIteratorBase

class tb_lint.verible_verilog_syntax.PostOrderTreeIterator(tree: Node, filter_: Callable[[Node], bool] | None = None, reverse_children: bool = False)[source]

Bases: _TreeIteratorBase

class tb_lint.verible_verilog_syntax.LevelOrderTreeIterator(tree: Node, filter_: Callable[[Node], bool] | None = None, reverse_children: bool = False)[source]

Bases: _TreeIteratorBase

class tb_lint.verible_verilog_syntax.Node(parent: Node | None = None)[source]

Bases: NodeMixin

Base VeribleVerilogSyntax syntax tree node.

parent

Parent node.

Type:

Optional[Node]

__init__(parent: Node | None = None)[source]
property syntax_data: SyntaxData | None

Parent SyntaxData

property start: int | None

Byte offset of node’s first character in source text

property end: int | None

Byte offset of a character just past the node in source text.

property text: str

Source code fragment spanning all tokens in a node.

to_formatted_string() → str[source]

Print node representation formatted for printing in terminal.

class tb_lint.verible_verilog_syntax.BranchNode(tag: str, parent: Node | None = None, children: List[Node] | None = None)[source]

Bases: Node

Syntax tree branch node

tag

Node tag.

Type:

str

children

Child nodes.

Type:

Optional[Node]

__init__(tag: str, parent: Node | None = None, children: List[Node] | None = None)[source]
property start: int | None

Byte offset of node’s first character in source text

property end: int | None

Byte offset of a character just past the node in source text.

iter_find_all(filter_: ~typing.Callable[[~tb_lint.verible_verilog_syntax.Node], bool] | ~typing.Dict[str, str | ~typing.List[str]] | None, max_count: int = 0, iter_: ~tb_lint.verible_verilog_syntax._TreeIteratorBase | ~anytree.iterators.abstractiter.AbstractIter = <class 'tb_lint.verible_verilog_syntax.LevelOrderTreeIterator'>, **kwargs) → Iterable[Node][source]

Iterate all nodes matching specified filter.

Parameters:

  • filter –

    Describes what to search for. Might be: * Callable taking Node as an argument and returning True for accepted

    nodes.

    • Dict mapping Node attribute names to searched value or list of searched values.

  • max_count – Stop searching after finding that many matching nodes.

  • iter – Tree iterator. Decides in what order nodes are visited.

Yields:

Nodes matching specified filter.

find(filter_: ~typing.Callable[[~tb_lint.verible_verilog_syntax.Node], bool] | ~typing.Dict[str, str | ~typing.List[str]] | None, iter_: ~tb_lint.verible_verilog_syntax._TreeIteratorBase | ~anytree.iterators.abstractiter.AbstractIter = <class 'tb_lint.verible_verilog_syntax.LevelOrderTreeIterator'>, **kwargs) → Node | None[source]

Find node matching specified filter.

Parameters:

  • filter –

    Describes what to search for. Might be: * Callable taking Node as an argument and returning True for accepted

    node.

    • Dict mapping Node attribute names to searched value or list of searched values.

  • iter – Tree iterator. Decides in what order nodes are visited.

Returns:

First Node matching filter.

find_all(filter_: ~typing.Callable[[~tb_lint.verible_verilog_syntax.Node], bool] | ~typing.Dict[str, str | ~typing.List[str]] | None, max_count: int = 0, iter_: ~tb_lint.verible_verilog_syntax._TreeIteratorBase | ~anytree.iterators.abstractiter.AbstractIter = <class 'tb_lint.verible_verilog_syntax.LevelOrderTreeIterator'>, **kwargs) → List[Node][source]

Find all nodes matching specified filter.

Parameters:

  • filter –

    Describes what to search for. Might be: * Callable taking Node as an argument and returning True for accepted

    nodes.

    • Dict mapping Node attribute names to searched value or list of searched values.

  • max_count – Stop searching after finding that many matching nodes.

  • iter – Tree iterator. Decides in what order nodes are visited.

Returns:

List of nodes matching specified filter.

to_formatted_string() → str[source]

Print node representation formatted for printing in terminal.

class tb_lint.verible_verilog_syntax.RootNode(tag: str, syntax_data: SyntaxData | None = None, children: List[Node] | None = None)[source]

Bases: BranchNode

Syntax tree root node.

__init__(tag: str, syntax_data: SyntaxData | None = None, children: List[Node] | None = None)[source]
property syntax_data: SyntaxData | None

Parent SyntaxData

class tb_lint.verible_verilog_syntax.LeafNode(parent: Node | None = None)[source]

Bases: Node

Syntax tree leaf node.

This specific class is used for null nodes.

property start: None

Byte offset of token’s first character in source text

property end: None

Byte offset of a character just past the token in source text.

to_formatted_string() → str[source]

Print node representation formatted for printing in terminal.

class tb_lint.verible_verilog_syntax.TokenNode(tag: str, start: int, end: int, parent: Node | None = None)[source]

Bases: LeafNode

Tree node with token data

Represents single token in a syntax tree.

tag

Token tag.

Type:

str

__init__(tag: str, start: int, end: int, parent: Node | None = None)[source]
property start: int

Byte offset of token’s first character in source text

property end: int

Byte offset of a character just past the token in source text.

to_formatted_string() → str[source]

Print node representation formatted for printing in terminal.

class tb_lint.verible_verilog_syntax.Token(tag: str, start: int, end: int, syntax_data: SyntaxData | None = None)[source]

Bases: object

Token data

Represents single token in tokens and rawtokens lists.

tag

Token tag.

Type:

str

start

Byte offset of token’s first character in source text.

Type:

int

end

Byte offset of a character just past the token in source text.

Type:

int

syntax_data

Parent SyntaxData.

Type:

Optional[“SyntaxData”]

__init__(tag: str, start: int, end: int, syntax_data: SyntaxData | None = None)[source]
property text: str

Token text in source code.

to_formatted_string() → str[source]
class tb_lint.verible_verilog_syntax.Error(line: int, column: int, phase: str, message: str = '')[source]

Bases: object

line: int
column: int
phase: str
message: str = ''
__init__(line: int, column: int, phase: str, message: str = '') → None
class tb_lint.verible_verilog_syntax.SyntaxData(source_code: str | None = None, tree: tb_lint.verible_verilog_syntax.RootNode | None = None, tokens: List[tb_lint.verible_verilog_syntax.Token] | None = None, rawtokens: List[tb_lint.verible_verilog_syntax.Token] | None = None, errors: List[tb_lint.verible_verilog_syntax.Error] | None = None)[source]

Bases: object

source_code: str | None = None
tree: RootNode | None = None
tokens: List[Token] | None = None
rawtokens: List[Token] | None = None
errors: List[Error] | None = None
__init__(source_code: str | None = None, tree: RootNode | None = None, tokens: List[Token] | None = None, rawtokens: List[Token] | None = None, errors: List[Error] | None = None) → None
class tb_lint.verible_verilog_syntax.VeribleVerilogSyntax(executable: str = 'verible-verilog-syntax')[source]

Bases: object

verible-verilog-syntax wrapper.

This class provides methods for running verible-verilog-syntax and transforming its output into Python data structures.

Parameters:

executable – path to verible-verilog-syntax binary.

__init__(executable: str = 'verible-verilog-syntax')[source]
parse_files(paths: List[str], options: Dict[str, Any] | None = None) → Dict[str, SyntaxData][source]

Parse multiple SystemVerilog files.

Parameters:

  • paths – list of paths to files to parse.

  • options –

    dict with parsing options. Available options:

    gen_tree (boolean): whether to generate syntax tree. skip_null (boolean): null nodes won’t be stored in a tree if True. gen_tokens (boolean): whether to generate tokens list. gen_rawtokens (boolean): whether to generate raw token list.

    By default only gen_tree is True.

Returns:

A dict that maps file names to their parsing results in SyntaxData object.

parse_file(path: str, options: Dict[str, Any] | None = None) → SyntaxData | None[source]

Parse single SystemVerilog file.

Parameters:

  • path – path to a file to parse.

  • options –

    dict with parsing options. Available options:

    gen_tree (boolean): whether to generate syntax tree. skip_null (boolean): null nodes won’t be stored in a tree if True. gen_tokens (boolean): whether to generate tokens list. gen_rawtokens (boolean): whether to generate raw token list.

    By default only gen_tree is True.

Returns:

Parsing results in SyntaxData object.

parse_string(string: str, options: Dict[str, Any] | None = None) → SyntaxData | None[source]

Parse a string with SystemVerilog code.

Parameters:

  • string – SystemVerilog code to parse.

  • options –

    dict with parsing options. Available options:

    gen_tree (boolean): whether to generate syntax tree. skip_null (boolean): null nodes won’t be stored in a tree if True. gen_tokens (boolean): whether to generate tokens list. gen_rawtokens (boolean): whether to generate raw token list.

    By default only gen_tree is True.

Returns:

Parsing results in SyntaxData object.

Module contents

Unified Linter - Modular Linting Framework

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Flexible, plugin-based linting system supporting multiple linters

Usage:

python3 tb_lint.py [options] <file.sv> [<file2.sv> …]

Options:
--help

Show this help message

--config FILE

Configuration file (JSON)

--linter NAME

Run specific linter (default: all)

--list-linters

List available linters

--strict

Treat warnings as errors

--json

Output in JSON format

--color

Enable colored output

-f FILE_LIST

File containing list of files (one per line)

-o OUTPUT_FILE

Output file for results

Examples

# Run all linters python3 tb_lint.py -f file_list.txt

# Run only NaturalDocs linter python3 tb_lint.py –linter naturaldocs file.sv

# Use custom config python3 tb_lint.py –config my_config.json -f files.txt

class tb_lint.Colors[source]

Bases: object

ANSI color codes

RED = '\x1b[0;31m'
GREEN = '\x1b[0;32m'
YELLOW = '\x1b[1;33m'
BLUE = '\x1b[0;34m'
CYAN = '\x1b[0;36m'
BOLD = '\x1b[1m'
NC = '\x1b[0m'
class tb_lint.UnifiedLinter(config_file: str | None = None, use_color: bool = False, strict_mode: bool = False)[source]

Bases: object

Unified linting orchestrator

Manages multiple linters and aggregates results

__init__(config_file: str | None = None, use_color: bool = False, strict_mode: bool = False)[source]

Initialize unified linter

Parameters:

  • config_file – Path to configuration file

  • use_color – Enable colored output

  • strict_mode – Treat warnings as errors

list_linters() → List[str][source]

Get list of available linters

run_linter(linter_name: str, file_paths: List[str]) → LinterResult[source]

Run a specific linter on files

Parameters:

  • linter_name – Name of linter to run

  • file_paths – List of files to check

Returns:

LinterResult with violations found

run_all_linters(file_paths: List[str]) → dict[source]

Run all enabled linters on files

Parameters:

file_paths – List of files to check

Returns:

Dictionary mapping linter names to results

print_result(result: LinterResult, output_file=None)[source]

Print linter results in human-readable format

Parameters:

  • result – LinterResult to print

  • output_file – File handle for output (default: stdout)

print_json(results: dict, output_file=None)[source]

Print results in JSON format

Parameters:

  • results – Dictionary of linter results

  • output_file – File handle for output (default: stdout)

print_command_info(args, files_to_check: List[str], output_file=None)[source]

Print command line information for tb_lint and each enabled linter

Parameters:

  • args – Command line arguments

  • files_to_check – List of files to check

  • output_file – File handle for output (default: stdout)

print_final_summary(results: dict, output_file=None)[source]

Print final TB_LINT summary

Parameters:

  • results – Dictionary of linter results

  • output_file – File handle for output (default: stdout)

get_exit_code(results: dict) → int[source]

Determine exit code based on results

Parameters:

results – Dictionary of linter results

Returns:

0 if all passed, 1 if violations found

tb_lint.main()[source]

Main entry point