python-postman 0.9.0__tar.gz → 0.9.1__tar.gz

{python_postman-0.9.0 → python_postman-0.9.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: python-postman
-Version: 0.9.0
+Version: 0.9.1
 Summary: A Python library for parsing and working with Postman collection.json files
-Project-URL: Homepage, https://github.com/python-postman/python-postman
-Project-URL: Repository, https://github.com/python-postman/python-postman
-Project-URL: Documentation, https://python-postman.readthedocs.io
-Project-URL: Bug Tracker, https://github.com/python-postman/python-postman/issues
+Project-URL: Homepage, https://github.com/yudiell/python-postman
+Project-URL: Repository, https://github.com/yudiell/python-postman
+Project-URL: Documentation, https://github.com/yudiell/python-postman/blob/main/docs/usage.md
+Project-URL: Bug Tracker, https://github.com/yudiell/python-postman/issues
 Author: Python Postman Contributors
 License: MIT
 License-File: LICENSE
@@ -15,7 +15,6 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -25,7 +24,8 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Software Development :: Testing
 Requires-Python: >=3.9
-Requires-Dist: httpx>=0.28.1
+Provides-Extra: all
+Requires-Dist: httpx>=0.28.1; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: black>=23.0.0; extra == 'dev'
 Requires-Dist: isort>=5.12.0; extra == 'dev'
@@ -33,12 +33,15 @@ Requires-Dist: mypy>=1.0.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
 Requires-Dist: pytest>=8.4.2; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'dev'
 Provides-Extra: execution
-Requires-Dist: python-dotenv>=1.0.0; extra == 'execution'
+Requires-Dist: httpx>=0.28.1; extra == 'execution'
 Description-Content-Type: text/markdown
 
 # Python Postman
 
+> **Disclaimer:** This is an independent, community-maintained open-source project. It is not affiliated with, endorsed by, or sponsored by Postman, Inc. "Postman" is a registered trademark of Postman, Inc.
+
 A comprehensive Python library for working with Postman collections. Parse, execute, search, and analyze Postman collection.json files with a clean, object-oriented interface. Execute HTTP requests with full async/sync support, dynamic variable resolution, and authentication handling.
 
 ## Features
@@ -181,11 +184,11 @@ if collection.auth:
 
     # Access auth details based on type
     if collection.auth.type == "bearer":
-        token = collection.auth.bearer.get("token")
+        token = collection.auth.get_bearer_token()
         print(f"Bearer Token: {token}")
     elif collection.auth.type == "basic":
-        username = collection.auth.basic.get("username")
-        print(f"Basic Auth Username: {username}")
+        credentials = collection.auth.get_basic_credentials()
+        print(f"Basic Auth Username: {credentials['username']}")
 
 # Request-level auth (overrides collection auth)
 for request in collection.get_requests():
@@ -202,13 +205,14 @@ for event in collection.events:
     print(f"Script Content: {event.script}")
 
 # Access script content from request-level events
-# Note: JavaScript execution is not supported - scripts are accessible as text only
+# Note: Scripts are converted from JavaScript to Python and executed in a sandboxed environment
+# during request execution. You can also access script content directly:
 for request in collection.get_requests():
     for event in request.events:
         if event.listen == "prerequest":
-            print(f"Pre-request script for {request.name}: {event.script}")
+            print(f"Pre-request script for {request.name}: {event.get_script_content()}")
         elif event.listen == "test":
-            print(f"Test script for {request.name}: {event.script}")
+            print(f"Test script for {request.name}: {event.get_script_content()}")
 ```
 
 ### Validation
@@ -259,7 +263,9 @@ async def main():
     # Create executor
     executor = RequestExecutor(
         client_config={"timeout": 30.0, "verify": True},
-        global_headers={"User-Agent": "python-postman/1.0"}
+        global_headers={"User-Agent": "python-postman/1.0"},
+        variable_overrides={"env": "production"},  # Highest precedence variables
+        request_delay=0.1,  # Delay between sequential requests (seconds)
     )
 
     # Create execution context with variables
@@ -322,9 +328,9 @@ async def execute_collection():
     )
 
     # Get the request responses
-    for result in result.results:
-        print(f"Request: {result.request.name}")
-        print(f"Result Text: {result.response.text}")
+    for exec_result in result.results:
+        print(f"Request: {exec_result.request.name}")
+        print(f"Result Text: {exec_result.response.text}")
 
     print(f"Parallel execution completed in {result.total_time_ms:.2f}ms")
 
@@ -457,13 +463,16 @@ from python_postman.execution import (
     ExecutionError,
     RequestExecutionError,
     VariableResolutionError,
-    AuthenticationError
+    AuthenticationError,
+    ExecutionTimeoutError,
 )
 
 try:
     result = await executor.execute_request(request, context)
     if not result.success:
         print(f"Request failed: {result.error}")
+except ExecutionTimeoutError as e:
+    print(f"Timeout: {e}")
 except VariableResolutionError as e:
     print(f"Variable error: {e}")
 except AuthenticationError as e:
@@ -482,7 +491,7 @@ except RequestExecutionError as e:
 - **`Folder`**: Container for organizing requests and sub-folders
 - **`Variable`**: Collection, folder, or request-level variables
 - **`Auth`**: Authentication configuration
-- **`Event`**: Pre-request and test script definitions (text only, execution not supported)
+- **`Event`**: Pre-request and test script definitions (executed in a sandboxed environment during request execution)
 
 ### Exception Handling
 
@@ -508,7 +517,7 @@ except CollectionValidationError as e:
 
 ## Requirements
 
-- Python 3.8+
+- Python 3.9+
 - No external dependencies for core functionality
 
 ## Development
@@ -569,15 +578,17 @@ This project is licensed under the MIT License - see the LICENSE file for detail
 
 ## Changelog
 
-### 0.8.0 (Updated version)
-
-- Updated version to 0.8.0
-- Updated README.md
-- Updated pyproject.toml
-- Updated tests
-- Updated docs
-- Updated examples
-- Updated code
+### 0.9.0
+
+- Added HTTP request execution layer with full async/sync support
+- Added variable resolution with proper scoping and precedence
+- Added authentication handling (Bearer, Basic, API Key)
+- Added request extensions for runtime modification
+- Added search and statistics modules
+- Added introspection utilities (AuthResolver, VariableTracer)
+- Added comprehensive type hints and type safety enhancements
+- Added path parameter support (:parameterName syntax)
+- Added collection and folder execution with parallel mode
 
 ## Support
 

{python_postman-0.9.0 → python_postman-0.9.1}/README.md

@@ -1,5 +1,7 @@
 # Python Postman
 
+> **Disclaimer:** This is an independent, community-maintained open-source project. It is not affiliated with, endorsed by, or sponsored by Postman, Inc. "Postman" is a registered trademark of Postman, Inc.
+
 A comprehensive Python library for working with Postman collections. Parse, execute, search, and analyze Postman collection.json files with a clean, object-oriented interface. Execute HTTP requests with full async/sync support, dynamic variable resolution, and authentication handling.
 
 ## Features
@@ -142,11 +144,11 @@ if collection.auth:
 
     # Access auth details based on type
     if collection.auth.type == "bearer":
-        token = collection.auth.bearer.get("token")
+        token = collection.auth.get_bearer_token()
         print(f"Bearer Token: {token}")
     elif collection.auth.type == "basic":
-        username = collection.auth.basic.get("username")
-        print(f"Basic Auth Username: {username}")
+        credentials = collection.auth.get_basic_credentials()
+        print(f"Basic Auth Username: {credentials['username']}")
 
 # Request-level auth (overrides collection auth)
 for request in collection.get_requests():
@@ -163,13 +165,14 @@ for event in collection.events:
     print(f"Script Content: {event.script}")
 
 # Access script content from request-level events
-# Note: JavaScript execution is not supported - scripts are accessible as text only
+# Note: Scripts are converted from JavaScript to Python and executed in a sandboxed environment
+# during request execution. You can also access script content directly:
 for request in collection.get_requests():
     for event in request.events:
         if event.listen == "prerequest":
-            print(f"Pre-request script for {request.name}: {event.script}")
+            print(f"Pre-request script for {request.name}: {event.get_script_content()}")
         elif event.listen == "test":
-            print(f"Test script for {request.name}: {event.script}")
+            print(f"Test script for {request.name}: {event.get_script_content()}")
 ```
 
 ### Validation
@@ -220,7 +223,9 @@ async def main():
     # Create executor
     executor = RequestExecutor(
         client_config={"timeout": 30.0, "verify": True},
-        global_headers={"User-Agent": "python-postman/1.0"}
+        global_headers={"User-Agent": "python-postman/1.0"},
+        variable_overrides={"env": "production"},  # Highest precedence variables
+        request_delay=0.1,  # Delay between sequential requests (seconds)
     )
 
     # Create execution context with variables
@@ -283,9 +288,9 @@ async def execute_collection():
     )
 
     # Get the request responses
-    for result in result.results:
-        print(f"Request: {result.request.name}")
-        print(f"Result Text: {result.response.text}")
+    for exec_result in result.results:
+        print(f"Request: {exec_result.request.name}")
+        print(f"Result Text: {exec_result.response.text}")
 
     print(f"Parallel execution completed in {result.total_time_ms:.2f}ms")
 
@@ -418,13 +423,16 @@ from python_postman.execution import (
     ExecutionError,
     RequestExecutionError,
     VariableResolutionError,
-    AuthenticationError
+    AuthenticationError,
+    ExecutionTimeoutError,
 )
 
 try:
     result = await executor.execute_request(request, context)
     if not result.success:
         print(f"Request failed: {result.error}")
+except ExecutionTimeoutError as e:
+    print(f"Timeout: {e}")
 except VariableResolutionError as e:
     print(f"Variable error: {e}")
 except AuthenticationError as e:
@@ -443,7 +451,7 @@ except RequestExecutionError as e:
 - **`Folder`**: Container for organizing requests and sub-folders
 - **`Variable`**: Collection, folder, or request-level variables
 - **`Auth`**: Authentication configuration
-- **`Event`**: Pre-request and test script definitions (text only, execution not supported)
+- **`Event`**: Pre-request and test script definitions (executed in a sandboxed environment during request execution)
 
 ### Exception Handling
 
@@ -469,7 +477,7 @@ except CollectionValidationError as e:
 
 ## Requirements
 
-- Python 3.8+
+- Python 3.9+
 - No external dependencies for core functionality
 
 ## Development
@@ -530,15 +538,17 @@ This project is licensed under the MIT License - see the LICENSE file for detail
 
 ## Changelog
 
-### 0.8.0 (Updated version)
-
-- Updated version to 0.8.0
-- Updated README.md
-- Updated pyproject.toml
-- Updated tests
-- Updated docs
-- Updated examples
-- Updated code
+### 0.9.0
+
+- Added HTTP request execution layer with full async/sync support
+- Added variable resolution with proper scoping and precedence
+- Added authentication handling (Bearer, Basic, API Key)
+- Added request extensions for runtime modification
+- Added search and statistics modules
+- Added introspection utilities (AuthResolver, VariableTracer)
+- Added comprehensive type hints and type safety enhancements
+- Added path parameter support (:parameterName syntax)
+- Added collection and folder execution with parallel mode
 
 ## Support
 

python_postman-0.9.1/audit.md

@@ -0,0 +1,147 @@
+# Code Review Audit — python-postman (Revision 4)
+
+**Date:** 2026-02-11
+**Scope:** Full codebase review (source, tests, packaging, documentation)
+**Test suite:** 1240 passed, 1 skipped, 2 warnings
+
+---
+
+## Executive Summary
+
+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.
+
+### Cumulative Fix Tracker
+
+| Original Finding | Status |
+|-----------------|--------|
+| #1 exec() security — no sandbox | **Fixed** — restricted builtins + AST validation + thread timeout + docs |
+| #2 Broken test file | **Fixed** — file deleted |
+| #3 TimeoutError shadows builtin | **Fixed** — renamed to ExecutionTimeoutError |
+| #4 AuthType enum duplication | **Fixed** — consolidated to single source of truth (alias) |
+| #5 folder.variable vs folder.variables | **Fixed** — corrected to folder.variables |
+| #6 PostmanResponse.json() bug | **Fixed** — now accesses property correctly |
+| #7 Script timeout ineffective | **Fixed** — thread-based timeout implemented |
+| #8 variable_overrides precedence | **Fixed** — overrides now have higher precedence |
+| #10 Changelog self-contradictory | **Fixed** — rewritten with meaningful entries |
+| #11 async_client leak in close() | **Fixed** — proper cleanup with fallback |
+| #12 Duplicate dev dependency groups | **Fixed** — [dependency-groups] removed |
+| #13 PostmanVariables.has() semantics | **Fixed** — now uses has_variable() |
+| Rev2 #2 request.variable singular form | **Fixed** — changed to request.variables |
+| Rev2 #3 VariableTracer wrong scope | **Fixed** — ENVIRONMENT added to VariableScope enum |
+| Rev2 #5 execute_iter() not true iterator | **Fixed** — new _search_items_iter generator |
+| Rev2 #7 Parent hierarchy not wired | **Fixed** — Collection/Folder.from_dict now wire references |
+| Rev2 #13 troubleshooting.md warnings | **Fixed** — removed non-existent warnings reference |
+| Rev2 #14 optional-dependencies.md [all] | **Fixed** — corrected to show [execution] only |
+| Rev2 #18 TestResult pytest warning | **Fixed** — renamed to CftcTestResult |
+| Rev3 #1 exec() residual risk | **Fixed** — AST validator blocks dunder access; `type` removed from safe builtins; security boundaries documented in docstring |
+| Rev3 #2 AuthType enum duplicated | **Fixed** — `AuthType = AuthTypeEnum` alias, single source of truth |
+| Rev3 #3 execute_collection/folder duplication | **Fixed** — `_execute_requests` extracted |
+| Rev3 #4 Missing __eq__ on ValidationResult | **Fixed** — __eq__ added |
+| Rev3 #8 Collection.to_json type hint | **Fixed** — changed to `Optional[int]` |
+| Rev3 #11 No py.typed marker | **Fixed** — py.typed file added |
+
+---
+
+## Remaining Findings
+
+### LOW
+
+#### 1. `to_dict()` Roundtrip Lossy for `Request`
+
+**File:** [request.py:185-216](python_postman/models/request.py#L185-L216)
+
+`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.
+
+#### 2. `Request.to_dict()` Omits `protocolProfileBehavior`
+
+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.
+
+#### 3. `Url.__init__` Parameter `hash` Shadows Builtin
+
+**File:** [url.py:57](python_postman/models/url.py#L57)
+
+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.
+
+---
+
+### INFORMATIONAL
+
+#### 4. JS-to-Python Converter Handles Only Basic Patterns
+
+**File:** [script_runner.py:515-588](python_postman/execution/script_runner.py#L515-L588)
+
+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.
+
+#### 5. Large `__init__.py` Re-exports Surface Area
+
+**File:** [__init__.py](python_postman/__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.
+
+#### 6. Unawaited Coroutine Warnings in Tests
+
+**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 Suite Summary
+
+| Metric | Value |
+|--------|-------|
+| Total tests | 1240 |
+| Passed | 1240 |
+| Skipped | 1 |
+| Errors | 0 |
+| Warnings | 2 (unawaited coroutine warnings in test mocks) |
+| Execution time | 0.50s |
+
+**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
+
+---
+
+## Architecture Assessment
+
+**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.
+
+---
+
+## Recommendations Priority
+
+| Priority | Finding | Effort |
+|----------|---------|--------|
+| P3 | Handle `description` inside `request` object during parsing (#1) | Low |
+| P3 | Preserve `protocolProfileBehavior` in roundtrips (#2) | Low |
+| P4 | No action needed — remaining items are cosmetic/informational | — |

{python_postman-0.9.0 → python_postman-0.9.1}/docs/README.md

@@ -56,8 +56,7 @@ pip install python-postman[execution]
 from python_postman import PythonPostman
 
 # Parse collection
-parser = PythonPostman()
-collection = parser.parse("collection.json")
+collection = PythonPostman.from_file("collection.json")
 
 # Analyze
 print(f"Collection: {collection.info.name}")
@@ -76,8 +75,7 @@ from python_postman import PythonPostman
 from python_postman.execution import RequestExecutor, ExecutionContext
 
 # Parse collection
-parser = PythonPostman()
-collection = parser.parse("collection.json")
+collection = PythonPostman.from_file("collection.json")
 
 # Setup execution
 executor = RequestExecutor()
@@ -85,10 +83,10 @@ context = ExecutionContext()
 context.set_variable("api_key", "your-key")
 
 # Execute
-results = await executor.execute_collection(collection, context=context)
+collection_result = await executor.execute_collection(collection, context=context)
 
 # Check results
-for result in results:
+for result in collection_result.results:
     print(f"{result.request.name}: {result.response.status_code}")
 ```
 
@@ -143,7 +141,7 @@ for result in results:
 **Example:**
 
 ```python
-collection = parser.parse("collection.json")
+collection = PythonPostman.from_file("collection.json")
 
 # Validate structure
 result = collection.validate()
@@ -177,7 +175,7 @@ for search_result in critical:
 **Example:**
 
 ```python
-collection = parser.parse("staging_collection.json")
+collection = PythonPostman.from_file("staging_collection.json")
 
 # Update URLs
 for request in collection.get_requests():
@@ -207,7 +205,7 @@ with open("production_collection.json", "w") as f:
 ```python
 from python_postman.introspection import AuthResolver
 
-collection = parser.parse("collection.json")
+collection = PythonPostman.from_file("collection.json")
 
 # Analyze authentication
 for request in collection.get_requests():
@@ -294,12 +292,12 @@ Collection
 
 Variables can be defined at multiple levels:
 
-1. Collection variables
-2. Environment variables
-3. Global variables
-4. Request variables (set in scripts)
+1. Request variables (highest precedence)
+2. Folder variables
+3. Collection variables
+4. Environment variables (lowest precedence)
 
-**Precedence:** Request > Environment > Collection > Global
+**Precedence:** Request > Folder > Collection > Environment
 
 ### Authentication