Road to OData V4

Road to OData V4

pyodata 1.x — V4 arrives as Experimental, V2 must remain Stable

• The guiding rule for pyodata 1.x is zero regression on OData V2.
• Changes related to OData V4 MUST NOT break existing V2 users of the library (function signatures or imports).
• There will be a period where new work for V4 lives next to bugfixes and features for V2.
• V4 goal is the "feature parity" with V2 pyodata. V4 support will be out before complete protocol coverage, similar to Odata V2, which still have portion of Odata specification not covered at all.

Parallel namespace approach

There was a "Big Bang — refactor everything up-front" approach in the past that fizzled. This time, simplicity, readability, and a maintenance-first mindset will take priority, even if it results in non-ideal, non-DRY code. Iterating on code is far cheaper now than during the earlier rewrite (when LLMs did not exist), so quick experiments based on existing patterns may move forward faster than a perfect, future-proofed-from-the-start design.

A parallel v4/ package will be added next to v2/, and client.py will route to it. The only edited source file used by v2 is client.py, which will have an ODATA_VERSION_4 = 4 constant and a dispatch branch.

V4-specific behavior will be written fresh but should stay as close to the pyodata OData V2 API as possible, for ease of migration. Classes that are byte-for-byte identical between the two versions — error policies, Identifier, Typ, the generic Collection, pure utilities — are imported straight from v2/, so there is no duplicated code for them and a fix to a shared class benefits both versions. The import from v2/ is a temporary solution for 1.x releases. When an import is not possible for some reason, a direct copy will be the solution, sacrificing DRY.

pyodata/
├── client.py        # only edited file: ODATA_VERSION_4 + dispatch
├── v2/              # UNTOUCHED — model.py, service.py
├── v4/              # new package
│   ├── model.py     # V4 classes fresh; identical ones imported from v2
│   └── service.py   # same pattern
└── exceptions.py    # unchanged

import pyodata, requests
session = requests.Session()

# V2 — unchanged, still the default
client_v2 = pyodata.Client(url, session)

# V4 — explicit opt-in
client_v4 = pyodata.Client(url, session,
                           odata_version=pyodata.Client.ODATA_VERSION_4)

Milestones

• First, the feature branch v4 will hold the experimental changes. Users can try it with pip/uv installation from GitHub URL.
• In an (unspecified) 1.x release, it will be merged into main and shipped as part of the PyPI package release, although still considered "Under Development" and "Experimental". Breaking changes can happen within the v4 package (backward incompatibility relative to earlier V4-specific code).
• Testing and stabilization of V4 work will continue in subsequent 1.x releases, where V2 must remain unaffected.

pyodata 2.x — OData V4 considered Stable, extracting the shared core, backward-incompatible changes

The 2.0 release cleans up the imports from v2/ by introducing a pyodata/base/ package: the shared classes move there, and both v2/ and v4/ import from base/.

For V4 this is a mechanical one-line change per file (pyodata.v2.model → pyodata.base.model) with no logic or test changes, because they are the same objects at a new path.

2.0 will also address identified and deferred breaking changes — top-level pyodata.Config, the proprties→properties typo fix, and per-service HttpError state. These should be announced with deprecation warnings during 1.x and accompanied by a migration guide.

Parallel maintenance

For a period that is unknown at this moment, both 1.x and 2.x will be maintained.

However, 1.x will not be a long-term effort: once 2.x is released, 1.x will receive critical bugfixes and security patches only — bugfix releases, with no minor releases.

New features will land only in pyodata 2.x releases going forward.