Welcome to sarge’s documentation!

Welcome to the documentation for sarge, a wrapper for subprocess which aims to make life easier for anyone who needs to interact with external applications from their Python code.

Please note: this documentation is work in progress.

• Overview
  • What is Sarge for?
  • Why not just use subprocess?
  • Main features
  • Python version and platform compatibility
  • Project status
  • API stability
  • Next steps
• Tutorial
  • Installation and testing
  • Common usage patterns
    • Chaining commands
    • Handling user input safely
    • Formatting commands with placeholders for safe usage
  • Passing input to commands
  • Chaining commands conditionally
  • Creating command pipelines
  • Using redirection
  • Capturing stdout and stderr from commands
  • Iterating over captures
  • Interacting with child processes
  • Environments
  • Working directory and other options
  • Unicode and bytes
  • Use as context managers
  • Synchronous and asynchronous execution of commands
  • About threading and forking
  • Next steps
• Under the hood
  • How capturing works
    • Basic approach
    • Blocking and timeouts
    • Implications when handling large amounts of data
  • Swapping output streams
  • How shell quoting works
  • How shell command formatting works
  • How command parsing works
  • Thread debugging
  • Future changes
  • Next steps
• API Reference
  • Attributes
  • Functions
  • Classes
  • Shell syntax understood by sarge
    • Command syntax
    • Redirections
  • Next steps