Date: 2026-02-11 Scope: Full codebase review (source, tests, packaging, documentation) Test suite: 1240 passed, 1 skipped, 2 warnings

python-postman is a well-structured Python library with a clean two-layer architecture (model layer + optional execution layer). The codebase demonstrates solid engineering with comprehensive type hints, thorough validation, and good separation of concerns. The test suite is extensive at 1240 tests, all passing.

Across four revision cycles, all 25 actionable findings from the original audit have been addressed. The codebase is now in excellent shape. The remaining items are exclusively low-severity cosmetic concerns and inherent architectural limitations that are properly documented.

File: request.py:185-216

Request.to_dict() places description at the top level of the dict. In actual Postman collection JSON, the description field may appear either at the item level or inside the request object. The from_dict only reads from the top level (data.get("description")), which means descriptions nested inside the request object are silently dropped during parsing.

Postman collections often contain protocolProfileBehavior fields on items. The parser silently drops these during from_dict, and they're not restored in to_dict. This means from_dict(to_dict()) roundtrips lose data for collections that use this field.

File: url.py:57

The constructor parameter hash shadows the Python builtin hash() function within the method scope. While not a runtime issue (the parameter name matches the Postman schema field name hash), it's a naming concern flagged by linters.

File: script_runner.py:515-588

The _convert_js_to_python() method uses ~20 regex substitutions to convert JavaScript to Python. This handles only basic patterns (var/let/const, true/false/null, ===, simple if/else) and will fail on template literals, destructuring, for...of/for...in loops, complex arrow functions, class syntax, try/catch, and any modern JavaScript features. This limits script execution to only the simplest Postman scripts. This is a known design limitation.

File: init.py

The package re-exports 40+ symbols from its __init__.py. While convenient, it means importing the package loads all model classes even if the user only needs one. For a library of this size, the impact is negligible.

File: tests/test_executor.py

Two tests produce RuntimeWarning: coroutine 'AsyncMockMixin._execute_mock_call' was never awaited. This suggests the mock setup for the async executor path may not be fully correct. Harmless but noisy.

Test coverage areas:

• Model classes: Thorough (all models have dedicated test files)
• Execution layer: Good (executor, context, variable resolver, auth handler, script runner, extensions)
• Search/statistics: Covered
• Introspection: Covered (auth resolver, variable tracer)
• Edge cases: Dedicated test file
• Real-world collections: 9 collections tested
• Integration tests: Present

Gaps:

• No property-based/fuzz testing
• No benchmarks for large collection parsing performance

Strengths:

• Clean separation between parsing (zero dependencies) and execution (optional httpx)
• Consistent from_dict() / to_dict() pattern across all models
• Fluent search API with true iterator support (execute_iter() uses a generator)
• Comprehensive exception hierarchy with contextual details
• Well-implemented variable scoping with correct precedence rules
• Good use of ABC for Item base class with factory methods
• Layered script sandbox: restricted builtins + import blocklist + AST validation + thread timeout, with security boundaries clearly documented
• Proper async client cleanup in close() with sync/async fallback
• Parent hierarchy (_parent_folder, _collection) properly wired during parsing
• VariableScope enum includes all four scopes (REQUEST, FOLDER, COLLECTION, ENVIRONMENT)
• Single source of truth for AuthType via alias to AuthTypeEnum
• DRY execution logic via shared _execute_requests method
• PEP 561 compliant with py.typed marker

No significant weaknesses remain. The only architectural limitations are inherent to the design (regex-based JS conversion, exec() for script execution) and are properly documented.