ysskrishna logoysskrishna

OSC 7501

Report terminal program status with OSC 7501

Report terminal program status with OSC 7501

When it's useful

A long-running program can be working, finished, failed, or waiting on the user. OSC 9;4 can say busy, a percentage, or failed, and it has no message. OSC 7501 adds a state, a reason (permission, question, or auth), and a stable app name. The terminal decides how to show that. A terminal that does not know the sequence ignores it.

What you can do

  • Send idle, working, done, blocked, error, or clear.
  • Track one job with working() as a context manager. It repeats app, id, and title, and writes the closing state for you.
  • Optionally probe the terminal with detect() before you read input.

Limits and fit

Python 3.11+. The library has no runtime dependencies. Reports go to stderr, and only when stderr is a terminal, unless you pass enabled=True. This release follows Program Status Protocol revision 0.4. Examples are in the GitHub repository.

Frequently asked questions

What does OSC 7501 report?

It sends a program status report the terminal can show: idle, working, done, blocked, error, or clear. A blocked report can say why, using permission, question, or auth. Progress is an integer from 0 to 100 on working or blocked.

How do I install it?

Requires Python 3.11 or newer. Install from PyPI with pip install osc7501. The library has no runtime dependencies.

When are reports written?

Helpers write to stderr, and only when stderr is a terminal, unless you pass enabled=True. A pipe or a file gets no report. Invalid fixed inputs raise ValueError even when output is disabled.

How do I track one job?

working() returns a Job. Use it as a context manager and it repeats app, id, and title. A clean exit writes done. An exception writes error. KeyboardInterrupt writes idle. detect() is optional and is not called by the helpers.

Continue exploring

Explore All Products
ProductDocker Detector

Docker Detector

Detect if Python process is running inside a Docker container
DevOps & Infrastructure
PyPI Packages
Python
uv
ProductContainer Detect

Container Detect

Detect if Python process is running inside a container (Docker, Podman, Kubernetes)
DevOps & Infrastructure
PyPI Packages
Python
uv
ProductNested Utils

Nested Utils

Dot-path access made easy for Python's JSON, dict, and list structures.
PyPI Packages
Python
uv
PyPI
ProductSocial Links

Social Links

Detect, validate, and sanitize social media links in Python
PyPI Packages
Python
uv
PyPI
BlogCover image for How to Automate Airflow Log Cleanup and Reclaim Disk Space

How to Automate Airflow Log Cleanup and Reclaim Disk Space

Airflow
Bash
+3
3 min read
ProductPyPI Package Stats

PyPI Package Stats

CLI and library for PyPI download stats and metadata via the pypistats API, with disk caching.
PyPI Packages
Python
Typer
PyPI