Welcome to the python-postman documentation! This guide will help you understand and use the library effectively.

Learn about the library's internal structure and design:

• Overview - High-level architecture and design principles
• Model Layer - Parsing and representing collections
• Execution Layer - Runtime request execution
• Layer Interaction - How layers work together

Practical guides for common tasks:

• Decision Tree - Choose the right features for your use case
• Optional Dependencies - Understanding dependency groups
• Variable Scoping - Understanding variable scopes and resolution
• Description Fields - Using description fields effectively
• Troubleshooting - Diagnose and fix common issues

Complete working examples:

• Parse → Inspect → Modify → Execute - Complete workflow example
• Generate Documentation - Generate API docs from collections
• Variable Introspection - Trace and analyze variable usage
• Description Usage - Working with description fields

For core functionality (parsing, validation, transformation):

pip install python-postman

For API testing (includes HTTP execution):

pip install python-postman[execution]

from python_postman import PythonPostman

# Parse collection
collection = PythonPostman.from_file("collection.json")

# Analyze
print(f"Collection: {collection.info.name}")
print(f"Requests: {len(list(collection.get_requests()))}")

# Validate
result = collection.validate()
if result.is_valid:
    print("✓ Collection is valid")

from python_postman import PythonPostman
from python_postman.execution import RequestExecutor, ExecutionContext

# Parse collection
collection = PythonPostman.from_file("collection.json")

# Setup execution
executor = RequestExecutor()
context = ExecutionContext()
context.set_variable("api_key", "your-key")

# Execute
collection_result = await executor.execute_collection(collection, context=context)

# Check results
for result in collection_result.results:
    print(f"{result.request.name}: {result.response.status_code}")

Goal: Generate markdown/HTML documentation from Postman collections

Approach: Use Model Layer only

Guide: Generate Documentation Example

Key Features:

• Collection parsing
• Request introspection
• Example responses
• Custom formatting

Goal: Automated API testing in CI/CD

Approach: Use Model + Execution Layer

Guide: Parse → Inspect → Modify → Execute

Key Features:

• Request execution
• Test scripts
• Variable management
• Result validation

Goal: Validate collection structure before deployment

Approach: Use Model Layer + optional execution

Key Features:

• Schema validation
• Structure validation
• Optional smoke testing

Example:

collection = PythonPostman.from_file("collection.json")

# Validate structure
result = collection.validate()
if not result.is_valid:
    for error in result.errors:
        print(f"Error: {error}")
    exit(1)

# Optional: Execute critical requests
critical = collection.search().by_folder("Critical").execute()
for search_result in critical:
    result = await executor.execute_request(search_result.request, context)
    if not result.success:
        exit(1)

Goal: Transform collections for different environments

Approach: Use Model Layer only

Key Features:

• URL transformation
• Variable updates
• Serialization

Example:

collection = PythonPostman.from_file("staging_collection.json")

# Update URLs
for request in collection.get_requests():
    request.url.host = request.url.host.replace("staging", "production")

# Save
with open("production_collection.json", "w") as f:
    f.write(collection.to_json(indent=2))

Goal: Analyze collection structure and complexity

Approach: Use Model Layer + Introspection

Key Features:

• Search and filtering
• Authentication resolution
• Statistics collection

Example:

from python_postman.introspection import AuthResolver

collection = PythonPostman.from_file("collection.json")

# Analyze authentication
for request in collection.get_requests():
    resolved_auth = AuthResolver.resolve_auth(request, None, collection)
    print(f"{request.name}: {resolved_auth.source.value}")

# Find requests without auth
no_auth = [r for r in collection.get_requests() if not r.has_auth()]
print(f"Requests without auth: {len(no_auth)}")

Need to execute HTTP requests?
│
├─ NO → Install: pip install python-postman
│   └─ Use: Model Layer
│       ├─ Documentation generation
│       ├─ Collection validation
│       ├─ Collection transformation
│       └─ Static analysis
│
└─ YES → Install: pip install python-postman[execution]
    └─ Use: Model + Execution Layer
        ├─ API testing
        ├─ Integration testing
        ├─ Automated workflows
        └─ CI/CD pipelines

See Decision Tree Guide for detailed decision flow.

A Postman collection is a hierarchical structure:

Collection
├── Info (metadata)
├── Auth (optional)
├── Variables
└── Items
    ├── Requests
    └── Folders (containing more items)

Model Layer (Core):

• No external dependencies
• Parse and represent collections
• Validate and transform
• Search and filter

Execution Layer (Optional):

• Requires httpx
• Execute HTTP requests
• Run scripts
• Manage variables

Variables can be defined at multiple levels:

1. Request variables (highest precedence)
2. Folder variables
3. Collection variables
4. Environment variables (lowest precedence)

Precedence: Request > Folder > Collection > Environment

Authentication can be defined at:

1. Request level (highest priority)
2. Folder level
3. Collection level (lowest priority)

Use AuthResolver to determine effective authentication.

• PythonPostman - Entry point for parsing
• Collection - Represents a collection
• Request - Represents an HTTP request
• Folder - Represents a folder
• Url - Represents a URL
• Auth - Represents authentication
• Body - Represents request body
• Response - Represents example response

• RequestExecutor - Executes requests
• ExecutionContext - Manages execution state
• ExecutionResult - Contains execution results
• ExecutionResponse - HTTP response

• AuthResolver - Resolves authentication
• VariableTracer - Traces variables
• RequestQuery - Search builder

1. Always validate collections:

   result = collection.validate()
   if not result.is_valid:
       handle_errors(result.errors)

2. Use ExecutionContext for variables:

   context = ExecutionContext()
   context.set_variable("api_key", api_key)

3. Reuse executor instances:

   executor = RequestExecutor()
   for request in requests:
       result = await executor.execute_request(request, context)

4. Handle errors appropriately:

   if not result.success:
       print(f"Error: {result.error}")

5. Use search for filtering:

   requests = collection.search().by_method("POST").execute()

1. Use iterators for large collections:

   for request in collection.get_requests():
       process(request)

2. Execute requests concurrently:

   results = await asyncio.gather(*[
       executor.execute_request(req, context)
       for req in requests
   ])

3. Cache search results:

   post_requests = collection.search().by_method("POST").execute()
   # Reuse post_requests

Common issues and solutions:

• Import errors → Check installation and dependencies
• Parsing errors → Validate JSON format
• Execution timeouts → Increase timeout setting
• SSL errors → Check certificates or disable verification (dev only)
• Variable not resolving → Check ExecutionContext

See Troubleshooting Guide for detailed solutions.

Contributions are welcome! To contribute:

1. Install development dependencies:

   pip install python-postman[dev]

2. Run tests:

   pytest

3. Check types:

   mypy python_postman

4. Format code:

   black python_postman

• Documentation: You're reading it!
• Examples: See examples/ directory
• Issues: Report bugs on GitHub
• Discussions: Ask questions in GitHub Discussions

python-postman is released under the MIT License.

• New users: Start with Decision Tree
• API testing: Read Execution Layer
• Documentation generation: See Generate Documentation Example
• Having issues: Check Troubleshooting Guide