fileaudit.python_check module

License MPL-2.0 (C) 2026 Created by Maikel Mardjan - https://nocomplexity.com/ FileAudit Security Checker - Checks if a Python file is valid Python

exception fileaudit.python_check.PythonValidationError(message)

Bases: Exception

Custom exception for Python/AST validation failures in FileAudit.

fileaudit.python_check.validate_python(func_or_path=None, max_file_size=None, max_lines=100000, max_line_length=10000, max_ast_nodes=500000, allowed_base_dir=None, allow_symlinks=False, parse_timeout=10)

Validate Python source files via decorator or direct invocation.

A Python file validator that can operate in two modes:

1. Decorator mode — wraps a function to validate a Python file path passed as an argument before the function body runs.

2. Direct call / CLI mode — validates a file immediately and returns a boolean result.

Security checks performed before (and during) AST parsing:

• File existence and regular-file type

• Symlink rejection (unless allow_symlinks=True)

• Directory containment / path-traversal guard (via allowed_base_dir)

• File size limit (DoS mitigation) — checked before reading into memory

• Only .py extension is accepted

• UTF-8 BOM detection and stripping

• Strict UTF-8 decoding

• Rejection of null bytes (\0)

• Line count and per-line length limits (tokenizer DoS protection)

• Safe ast.parse with explicit catching of SyntaxError, ValueError, MemoryError and RecursionError

• Optional parse timeout via SIGALRM (Unix only)

• Post-parse AST node count limit (protects downstream SAST walkers)

Usage:

@validate_python
@validate_python()
@validate_python("custom_arg_name")
@validate_python(max_file_size=5000)
validate_python("path/to/file.py")          # CLI / direct call usage

Args:

func_or_path (callable, str, pathlib.Path, or None):
    * If a **callable**: the function to decorate (bare decorator
      usage: ``@validate_python``).
    * If a **str** or **Path** that looks like a file path:
      the file path to validate (direct call usage).
    * If a **str** that is a valid Python identifier (not a path):
      treated as the target argument name to inspect in decorator
      mode (e.g., ``@validate_python("source_path")``).
    * If **None**: returns a decorator factory
      (``@validate_python()`` or ``@validate_python(max_file_size=…)``).
max_file_size (int or None): Maximum allowed file size in bytes.
    Falls back to ``DEFAULT_MAX_FILE_SIZE`` if omitted.
max_lines (int): Maximum number of lines allowed.
max_line_length (int): Maximum characters per line allowed.
max_ast_nodes (int): Maximum AST nodes allowed after parsing.
allowed_base_dir (str or Path or None): If set, the resolved local
    path must lie inside this directory (path-traversal protection).
allow_symlinks (bool): If False (default), symlinks are rejected.
parse_timeout (int): Seconds to allow for ``ast.parse`` before
    aborting. Uses ``SIGALRM``; only effective on Unix-like systems.

Returns:

• In decorator mode: the wrapped function.

• In direct call mode: True if validation passes, False if it fails (errors are printed to stdout).

Return type:

Union[callable, bool, function]

Raises:

PythonValidationError – If validation fails in decorator mode, or if the decorated function has no arguments, the target argument is missing, or the argument type is not str or Path.