Wrap a library when it is hard to replace, sits on a sensitive path, or is likely to change. Put a thin interface of your own in front of it so only one module imports the library. Skip the wrapper for tiny, stable helpers where the indirection costs more than it saves.
What a wrapper is
A wrapper, sometimes called an adapter, is a small module that exposes only the operations your code needs, in your own types. The rest of the application calls the wrapper. Only the wrapper imports the third-party package.
When you later replace the library, you rewrite one module and its tests instead of touching every caller.
A short example
Suppose services send email through a vendor-neutral package. Without a wrapper, a hundred files import the package and pass its message objects around. With a wrapper:
# mail.py (the only file that imports the third-party package)
import thirdparty_mail
def send_message(to, subject, body):
client = thirdparty_mail.Client()
client.send(recipient=to, title=subject, text=body)
Callers use send_message and never see the package. Swapping providers means editing mail.py.
When wrapping pays off
| Situation | Wrap? |
|---|---|
| Library used in many files | Yes |
| Library handles crypto, auth, parsing or payments | Yes, and also keep the wrapper small and reviewed |
| Library is pre-1.0 or changes its API often | Yes |
| One-line utility, stable for years | No |
| Framework that shapes your whole app | No, a wrapper cannot hide it; plan a migration instead |
The semantic versioning specification says major version zero is for initial development, where anything may change at any time and the public API should not be considered stable. A zero-major library is a strong candidate for a wrapper.
Costs to be honest about
- More code. A wrapper is a small amount of code to write and test.
- Lowest common denominator. If you expose only features every alternative has, you may give up useful ones. Expose what you use, not what exists.
- False comfort. A wrapper hides the API, not the behavior. Different libraries handle edge cases, encodings and errors differently, so tests on your side of the wrapper matter.
Steps to introduce one
- Search the repository for imports of the library and count them.
- List the distinct operations actually called.
- Define a function or class for each, using your own types and error classes.
- Move the imports into the wrapper and update the callers.
- Add tests at the wrapper boundary that describe behavior you depend on, so any replacement must pass them.
- Add a lint rule or review note that blocks new direct imports.
This pairs naturally with a written exit plan. Related: direct versus transitive dependencies.
Where Safeguard fits
A wrapper limits your code's exposure to the library's API, but the package still ships. Safeguard's SBOM and dependency scanning and reachability analysis show what you include and which vulnerable paths your code reaches. Try the free scan at gold.safeguard.sh/scan.
Quick check
Does a wrapper make the library safer?
No. It makes the library easier to replace. You still need to review and update it like any dependency.
Should the wrapper be generic enough for any provider?
Only as generic as your current needs. Over-designed wrappers add work and rarely match a future replacement exactly.
Sources
Last reviewed: 19 October 2026.
