bashlex

library0.18pypypi✓ verified 25d ago

Bashlex is a Python library providing a parser for bash commands. It can take a bash command string and convert it into an Abstract Syntax Tree (AST), allowing for programmatic inspection and manipulation of shell commands. The current version is 0.18, with releases occurring roughly annually or bi-annually.

serialization

pip install bashlex

github ↗package ↗

INSTALL

IMPORT

SIG · BASHLEX

bashlex

serializationpythonv0.18

Install

1.6s avg

Import

376ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.18 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.388s · 18.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.364s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ from bashlex import parse

tokenize

✓ from bashlex import tokenize

This quickstart demonstrates parsing a bash command string using `bashlex.parse()` to obtain an AST, and `bashlex.tokenize()` to get all individual tokens including operators and comments. It shows how to inspect the structure and access parts of the parsed command.

import bashlex command_string = "echo 'Hello World' && ls -l $HOME/#my-list.txt" try: # Parse the command string into an Abstract Syntax Tree (AST) tree = bashlex.parse(command_string) print(f"Parsed command: {command_string}") print("--- AST Structure ---") for i, part in enumerate(tree): print(f"[{i}] Kind: {part.kind}, Value: {part.word if hasattr(part, 'word') else str(part)}") if hasattr(part, 'parts'): for p_sub in part.parts: print(f" - Sub-part Kind: {p_sub.kind}, Word: {p_sub.word if hasattr(p_sub, 'word') else p_sub.value}") # Example: Tokenize the command to see all tokens, including comments and operators print("\n--- Tokens (including comments/operators) ---") tokens = bashlex.tokenize(command_string) for token in tokens: print(f"Token: '{token.word}', Pos: ({token.pos[0]},{token.pos[1]}), Kind: {token.kind}") except bashlex.errors.BashlexError as e: print(f"Error parsing command: {e}")

Debug

Known issues

gotchaBashlex is strictly a *syntax parser* for bash commands and does not act as a shell emulator. It will not perform variable expansion (e.g., `$VAR`, `~`), command substitution (e.g., `$(cmd)`), globbing (`*`), or interpret complex shell logic. Users are responsible for implementing these behaviors if needed after parsing.

fix

Do not expect `bashlex` to resolve environment variables, execute subcommands, or expand file paths. It provides the parsed structure, which you can then process with other tools or logic.

affects: All versions

gotchaComments (`# ...`) are parsed as distinct tokens during `bashlex.tokenize()` but are generally *not* included as part of the AST `parts` of command nodes returned by `bashlex.parse()`. If your application requires analyzing or extracting comments, you must use the `bashlex.tokenize()` function directly.

fix

For comment awareness, iterate through `bashlex.tokenize()` output. For command structure without comments, `bashlex.parse()` is appropriate.

affects: All versions

gotchaThe library maintains compatibility with both Python 2.7 and Python 3.5+. While this broad support exists, be cautious about `str`/`bytes` differences between Python 2 and 3 when processing input, especially in mixed environments or when migrating legacy code. Ensure your input strings are consistent (e.g., unicode in Python 3).

fix

In Python 3, always pass unicode strings to `bashlex` functions. If dealing with byte strings from external sources, decode them explicitly before passing to `bashlex`.

affects: All versions up to 0.18

breakingThe specific exception class `bashlex.errors.BashlexError` may not exist in newer versions of the library. Users attempting to catch this specific exception type will encounter an `AttributeError`. The library's custom exceptions (e.g., `ParserError`, `LexerError`) are now typically found directly within the `bashlex` module itself.

fix

Update exception handling code to catch the specific exception types defined in the `bashlex` module (e.g., `bashlex.ParserError`, `bashlex.LexerError`) or a more general `Exception` if broad error handling is sufficient. Consult `bashlex` documentation or source code for the correct exception classes in your installed version.

affects: Versions >= 0.19

Errors

Common errors & fixes

bashlex.errors.ParsingError: unexpected EOF

Bashlex, while powerful, does not support all Bash syntax and features; this specific error often occurs when the input string is an incomplete command, contains unsupported syntax like certain line continuations, comments, or complex expansions, or is otherwise malformed according to bashlex's parsing rules.

fix

Ensure the input Bash command is syntactically complete and adheres to the subset of Bash syntax supported by bashlex. For complex scripts, try to isolate the problematic parts. Consider pre-processing the input to remove unsupported features like comments or specific types of line continuations if they are not critical for your AST analysis. Example: `import bashlex; bashlex.parse('echo hello')`

AttributeError: 'str' object has no attribute 'kind'

This error typically occurs when attempting to access AST node attributes (like 'kind') on an object that is actually a string, usually because bashlex's `parse` method or an AST traversal yielded a string instead of a `Node` object, possibly due to a parsing error or incorrect handling of the AST structure.

fix

Verify that `bashlex.parse()` successfully returns a list of AST nodes before attempting to access node attributes. When iterating over results, ensure you're handling only `Node` objects or checking the type if strings might be present. Example: `import bashlex; parts = bashlex.parse('ls -l'); for node in parts: print(node.kind)`

ModuleNotFoundError: No module named 'bashlex'

The 'bashlex' package is not installed in the Python environment being used, or the Python interpreter cannot find the installed package due to an incorrect PYTHONPATH or virtual environment activation.

fix

Install the package using pip: `pip install bashlex`. If using a virtual environment, ensure it is activated before running your script. If the package is installed but not found, check your Python environment's `PYTHONPATH`.

Upgrade

Version history

0.18latest on PyPI · released Jan 18, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

33 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/idank/bashlex.git ↗

packagehttps://pypi.org/project/bashlex/ ↗