baidu/CUP: the utility layer Baidu service code is built on

What CUP collects that a service codebase keeps rewriting

CUP is described by its own authors as a common useful python library and, in the repository description, as the most popular Python library at Baidu. The concrete content is a support layer rather than an application framework. It carries a thread pool, a logging module, an email sender, a shell execution package, a memory cache, decorators, exception classes and a set of resource query helpers that read from /proc. That is the profile of a library that grew out of running services: the pieces a team writes once and copies between internal projects, then publishes so that other teams can stop copying them.

The audience is therefore Python developers writing long running server side code, especially in the Linux centric environments the /proc based resource package targets. It is not a web framework, it has no routing layer, and it does not model your data. If you are building a REST service, CUP sits below the service, next to your own configuration and logging setup, and you adopt it to delete a few hundred lines of internal helper code. The trade-off is that you adopt one team's conventions along with the code, including their assumptions about logging format and thread handling that are documented on the project wiki rather than in the README.

Inside the cup package: proc parsing, thread pools, mail and shell

The package tree is the clearest statement of intent. cup/res is a package for resource usage queries in /proc, process queries and device information. cup/util holds the ThreadPool, an Interruptable-Thread and a rich configuration file implementation. cup/services holds a heartbeat, thread pool based executors and a file service. cup/shell covers shell operations and cross-hosts execution, cup/net covers network operations such as net handler parameter tuning, and cup/thirdp carries pure Python third party modules.

Two of those entries carry weight for adoption decisions. The shell package exists to run commands on other hosts, which puts CUP close to remote execution territory and makes it a candidate for anyone building deployment or maintenance tooling. The unittest module provides unittest support, assertions and a noseClass, which links directly to how the project tests itself. The rest is utility surface: decorators.py holds a Singleton style decorator, mail.py sends email, log.py provides CUP logging, cache.py is a memory cache, and platforms.py holds cross platform operations. The directory listing is broad rather than deep, and each module is a small surface you would either adopt whole or route around.

Installing cup and reading CPU and memory counters

The README gives two installation routes. The primary one installs from pip, and the source route runs the setup script directly:

pip install cup

python setup.py install

A first real use is a resource query. The example in the README reads CPU usage over an interval and then memory counters, and it is worth copying exactly because the attribute names are the API:

# Examples:
# 1. Get system info
import cup
# count cpu usage in interval, by default 60 seconds
from cup.res import linux
cpuinfo = linux.get_cpu_usage(intvl_in_sec=60)
print cpuinfo.usr

# total, available, percent, used, free, active, inactive, buffers, cached
from cup.res import linux
meminfo = linux.get_meminfo()
print meminfo.total
print meminfo.available

Note what this example does and does not tell you. get_cpu_usage takes an interval in seconds and returns an object whose usr attribute is the user portion of the usage. get_meminfo returns an object carrying total, available, percent, used, free, active, inactive, buffers and cached. Both calls live under cup.res.linux, so the example is Linux specific by construction. The printed statements use Python 2 print syntax, which is a leftover from the README text and does not match the Python 3 only support the project states elsewhere.

A version story told in three different numbers

The packaging metadata and the README do not agree on the version scheme, and this is the first thing to check before you pin a dependency. The pyproject.toml file in the repository declares version 3.2.39, and the same file requires python = ">=3.9". The release list shows 3.2.37 published on 2026-04-02 and 3.2.35 on 2026-01-31, with an earlier 3.2.28 in October 2022 described as a minor release for Python 3 compatibility. Meanwhile the README notice says that from version 3.3.1 on, CUP will only support Python 3.

There is no 3.3.1 in the release list and no 3.2.39 either, so the notice describes a boundary that the published numbering never reached. The practical consequence is narrower than the confusion suggests: anything from the 3.2 series will run on Python 3, and the README still directs Python 2.7 users to an older build, with the comment that cup 3.2.X versions will only maintain bug fixes for Python2 and will not add any new features. If your team still has Python 2 services, the README gives the exact pin to use: # python -m pip install cup==3.2.31. For a new deployment, install the current pip release and read pyproject.toml, not the version notice, to learn the Python floor.

The nose test command and the pytest dependency

The README's test instructions are short and specific: install python-nose before running the tests, then run cd ./cup_tests; nosetests -s. The repository layout, however, shows a cup_test/ directory and a cup_test_manually/ directory rather than a cup_tests/ directory, so the path in the README does not match the tree as it stands. That is worth knowing before you try to reproduce a green test run.

There is a second inconsistency. pyproject.toml lists pytest ^8.3.5 among the runtime dependencies, alongside cffi, requests, psutil, pexpect, twist, netifaces and pytz, and the build backend is poetry-core with the package collected from ./src. The README still points at nose. Two testing stories, one test runner in the dependencies and a different one in the docs.

Contributing has its own gate. The README asks contributors to commit code to GITHUB and to check pep8 and pylint rules before opening a pull request, and the repository does include a pylintrc file, so the style expectations are enforced by configuration rather than by convention. For a reader who is not contributing, the practical point is that the test story has not been tidied, and you should expect to spend time reconciling nose, pytest and the directory names before you can trust the suite.

Vendored pexpect and httplib2 versus depending upstream

The alternative to CUP is not another utility library but the approach of taking the pieces you actually need from their upstream projects and wrapping them yourself. The repository makes that comparison concrete in two ways. The cup/thirdp package is described as third party modules containing pexpect and httplib2, both shipped as pure Python modules inside the tree, and the README reference list credits pexpect, httplib2, requests and pymysql with their own licences.

So the choice is between a wide, opinionated bundle and a narrow set of direct dependencies. If your service needs only a thread pool, a mail helper and CPU counters, pulling requests, pexpect and psutil directly gives you a smaller dependency tree, a normal release cadence from each upstream project and no constraint that your Python version matches Baidu's floor. CUP's counterargument is that it gives you the versions its own service code was written against, so that a subprocess helper, a logger and a thread pool behave consistently instead of drifting apart in each internal project.

Licence handling is a smaller difference than it looks. The project itself is Apache-2.0, and the vendored components are credited as MIT or Apache V2 licensed, so redistribution under those terms is not blocked. That is a compliance note rather than legal advice, and it says nothing about who is responsible for updating a vendored copy of pexpect when upstream fixes a defect.

Where CUP is the wrong tool

CUP is the wrong choice in a few clear situations. It is wrong for a new greenfield library, because the library is an internal conventions bundle and its documentation lives on a Wiki and a separate doc site, not in the README, so the cost of learning the conventions is paid at adoption time. It is wrong for a Python 2.7 codebase that wants new features, since the README states that the 3.2 series carries bug fixes only for Python 2. It is wrong for a team that has already standardised on a different logging, thread pool or configuration library, since duplicating those inside one service is worse than not having them.

It is also wrong when the /proc assumption breaks. The resource package is described as reading everything available in /proc, and the example imports cup.res.linux, so on a non Linux host the resource helpers are the wrong tool, and the README does not document a fallback for that case. For containerized workloads, where CPU accounting moves away from the host view that /proc exposes, the same caution applies.

One more limit deserves plain naming. The README does not document a rollback procedure, a support policy or a deprecation schedule, and it does not explain what changed between 3.2.28 in October 2022 and the 3.2.35 and 3.2.37 releases in 2026. The last push was on 2026-06-26, so commits are landing, but if you need a written changelog to justify an upgrade, the project does not currently supply one.

Editorial conclusion

CUP earns a place inside a service codebase that already shares one thread pool, one logging setup and one /proc parsing path, and it suits engineers who want Baidu's shaped version of those pieces. It is a poor fit for a fresh library, for a Python 2 shop beyond 3.2.31, or for anyone who needs documented rollback and release notes. Before adopting it, check the pip install cup version against the 3.2.39 declared in pyproject.toml, read the Wiki pages for the services and util packages, and confirm that the nose test command still runs in your own environment.

Frequently asked questions

Official sources

1. baidu/CUP on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases