oe-sdk 0.1.0a3

Python SDK for Octopus Energy.

oe-sdk

Octopus Energy Python SDK.

oe-sdk provides standardised, production-ready plumbing for common infrastructure so that services benefit from consistent, safe, and well-maintained implementations. It is not a collection of high-level API wrappers or opinionated utilities, it provides the core building blocks that every service can use to interact with external systems in a reliable, predictable way.

Example: uv add oe-sdk[s3], write a with S3Client() as s3:, and get straight to the actual work.

Philosophy

The SDK exists so engineers can focus on business problems, not infrastructure plumbing.

Every team eventually needs to talk to a common service. Without a shared foundation, each team ends up writing its own version, copy-pasted from a blog post, a previous project, or a colleague's Slack snippet. These ad-hoc implementations are rarely tested, inconsistently configured, and silently diverge over time.

The SDK solves this by providing a single, trusted source for that plumbing.

What belongs in the SDK

• Obviously common things. If nearly every service needs it (S3 access, a common internal API, a team's data control plane, etc.), it belongs here.
• Patterns duplicated in 2+ places. If two or more teams have independently written the same integration, that's a sign for us. We extract it, test it properly, and put it in the SDK so nobody has to write it again.

What the SDK is not

• Not a framework. It doesn't dictate how you structure your application, which web framework you use, or how you organise your business logic.
• Not opinionated about your domain. It handles the infrastructure layer and gets out of the way. Your modelling, your validation rules, your API design.

Design principles

• Minimal surface, maximum trust. Each module does the smallest useful thing well: lifecycle, config, retries, logging, and exposes the raw underlying client for everything else. No leaky abstractions that go stale when the upstream library adds features.
• Tested and validated. Every module ships with tests. Configuration is validated at construction. If you can instantiate it, it's correctly configured.
• Consistent patterns. Same context-manager lifecycle, same Pydantic config, same sync/async split, same naming conventions. Learn one module, you can instinctively know them all.
• Unopinionated where possible. The SDK follows established best practices but doesn't force architectural choices on callers.

Installation

Install the core SDK:

uv add oe-sdk

Then enable the modules you need via extras:

uv add oe-sdk[s3]          # S3 client plumbing

Multiple extras can be combined:

uv add oe-sdk[s3,...]      # add more as they become available

Modules

Each module has its own README with full usage, configuration, and testing guidance.

Module	Extra	Description	Docs
s3	oe-sdk[s3]	Context-managed sync & async S3 clients with retry, timeout, and logging	README

Contributing

See CONTRIBUTING.md for development setup, design decisions, and guidance on adding new modules.