Welcome to sarge’s documentation!

Release:	0.1.8.dev0
Date:	Dec 13, 2023

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
  • Change log
    • 0.1.8 (future)
    • 0.1.7
    • 0.1.6
    • 0.1.5
    • 0.1.4
    • 0.1.3
    • 0.1.2
    • 0.1.1
    • 0.1
  • Next steps
• Tutorial
  • Installation and testing
  • Common usage patterns
    • Finding commands under Windows
    • Parsing commands under Windows
    • Chaining commands
    • Handling user input safely
    • Formatting commands with placeholders for safe usage
  • Passing input data to commands
    • Passing input data to commands dynamically
  • Chaining commands conditionally
  • Creating command pipelines
  • Using redirection
  • Capturing stdout and stderr from commands
  • Iterating over captures
  • Interacting with child processes
    • Buffering issues
    • Looking for specific patterns in child process output
    • Displaying progress as a child process runs
    • Direct terminal usage
  • Environments
  • Working directory and other options
  • Unicode and bytes
  • Use as context managers
  • Synchronous and asynchronous execution of commands
  • Handling errors in asynchronous mode
  • About threading and forking on POSIX
  • 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
    • default_capture_timeout
  • Functions
    • run()
    • capture_stdout()
    • get_stdout()
    • capture_stderr()
    • get_stderr()
    • capture_both()
    • get_both()
    • shell_quote()
    • shell_format()
  • Classes
    • Command
    • Pipeline
    • Capture
    • Popen
  • Shell syntax understood by sarge
    • Command syntax
    • Redirections
  • Next steps

Please report any problems or suggestions for improvement either via the mailing list or the issue tracker.