machbaseapi 2.3

Machbase Python API 2.3 (Pure Python, legacy compatible)

Copyright of this product 2013-2023,
Machbase Corporation(or Inc.) or its subsidiaries.
All Rights reserved.

http://www.machbase.com

[e-mail]

Machbase Python API 2.3 (English introduction)

This package is a pure Python implementation of Machbase client protocol and provides a
drop-in replacement API compatible with the legacy Python API.

Python compatibility

- Supported runtime baseline is Python 3.6 or later.
- The source code avoids Python 3.7+ only syntax and does not depend on `dataclasses`.
- The package can be imported directly via `PYTHONPATH` on Python 3.6.x without extra backport packages.

Key changes in version 2.3

1. Append NULL padding
- Append rows may omit trailing columns. The omitted columns are sent as NULL through
  the append null-bit metadata.
- For TAG tables, values through the summarized `value` column remain required;
  later value/meta columns may be omitted.
- `appendData()` and `appendDataByTime()` send append data immediately. `appendFlush()`
  is an append response synchronization point, not a delayed-send trigger.
- Fixed float/double append NULL values are restored as Python `None` when fetched.

2. Package metadata
- Version is updated to `2.3`.

Key changes in version 2.2

1. Pure Python implementation
- Native binary libraries (`.so`, `.dylib`, `.dll`) are no longer required.
- Wire protocol, packet framing, and marshal/unmarshal logic are implemented in Python modules
  (`protocol.py`, `marshal.py`, `packet.py`).
- Distribution is platform independent (`py3-none-any` wheel).

2. Fully compatible with existing interfaces
- Existing entry points are preserved (`machbase`, `machbaseAPI`, `connect`, `MachbaseConnection`, `MachbaseCursor`).
- Legacy call patterns for common operations are maintained for migration (`open`, `close`, `openEx`,
  `execute`, `select`, `fetch`, `append`, DB-API cursor execution/fetch).
- Existing sample scripts and test code can be executed using the new package without adapter code.
- Existing behavior for unsupported features is preserved as explicit errors.

3. Improved append API
- `append`, `appendByTime` can be used without explicit `types`.
- `appendData`, `appendDataByTime` also support optional type arguments.
- `types` can still be inferred from active append session and explicit table metadata.
- Async-friendly append path: callers can supply callbacks and receive protocol ack handling
  without forcing unnecessary blocking.
- Improved row normalization and validation for mixed input forms.

4. Reliability and API strictness improvements
- Connection pooling is rejected with clear errors because pooling is intentionally not supported.
- Unknown connection options are rejected up front (fast validation).
- Expanded DB-API compatible exception mapping.
- Safer close/shutdown cleanup for sockets and sessions.
- Consistent internal encoding for bytes/binary-like values during legacy-style APIs.

5. Operational and migration notes
- Binary wheel no longer embeds platform native modules.
- Installation is lightweight and easier to mirror in CI/build pipelines.
- Version is updated to `2.2` (Python 3.6 direct-import compatibility and packaging/documentation refresh).

What changed for users migrating from 1.x

- Connection
  - Use the same host/port/user/password defaults as before.
  - No `lib` copy or platform-specific package setup required.
- Append
  - Existing `append` usage is supported; session-based and immediate append flows remain available.
- Compatibility boundaries
  - Existing scripts that relied on hidden/undocumented native behaviors may need review.
  - Pooling-related keys or unsupported options will now raise immediate errors (instead of being ignored).

Known limitations and troubleshooting

- Auto commit model
  - Transactions are auto-commit by protocol design for this API.
- High-volume append
  - Performance gains from batching large payloads are still recommended.
  - For ultra-high throughput scenarios, tune client-side batching strategy in your application.
- Error handling
  - Append/append_data and query errors are surfaced through return status and callbacks according to API layer.

FAQ

- Why only `py3-none-any`?
  - The package does not load platform-specific binaries anymore.
- Where can I check differences from old binaries?
  - Refer to `CHANGELOG.md` and API regression test suite in `test/regress`.

For full behavioral and compatibility reference, see `CHANGELOG.md` and the regression test set.


# Changelog

## 2.3

### Changed
- Version bump from 2.2 to 2.3 for the pure-Python API package.
- Append rows may omit trailing visible/meta columns, which are sent as NULL.
- TAG append still requires input through the summarized `value` column.
- Legacy `appendFlush()` now checks pending append responses instead of returning a session-only stub result.
- Updated package metadata and release documents for the 2.3 release.

### Fixed
- Fixed append NULL fetch handling for fixed float/double sentinel values so they are restored as Python `None`.

### Notes
- Package version is set to `2.3`.

## 2.2

### Changed
- Version bump from 2.1 to 2.2 for the pure-Python API package.
- Removed remaining Python 3.7+ only syntax from the runtime modules.
- Replaced `dataclasses`-based helper containers with plain classes so `PYTHONPATH` execution also works on Python 3.6.x.
- Updated package metadata and release documents for the 2.2 release.

### Notes
- Package version is set to `2.2`.
- The source package can be imported on Python 3.6.x without extra backport dependencies.

## 2.1

### Changed
- Version bump from 2.0 to 2.1 for pure-python API package.
- Documentation and metadata were updated to reflect the 2.1 release.

### Notes
- Package version is set to `2.1`.

## 2.0.0

### Changed
- Migrated to a pure Python implementation of Machbase protocol processing.
- Removed dependency on native dynamic libraries (`.so`, `.dll`, `.dylib`) from runtime package.
- Kept legacy API compatibility as the primary migration strategy:
  - `machbase` and `machbaseAPI` legacy styles
  - `connect`, `MachbaseConnection`, `MachbaseCursor`
  - legacy sample script behavior for connection/query/append use cases
- Improved append handling:
  - more flexible row normalization in session and one-shot append paths
  - async-friendly acknowledgement callback flow
  - stronger validation around row/type consistency
- Strengthened connection argument validation:
  - pooling-related options are explicitly rejected
  - unknown keyword options are rejected with clear error messages

### Fixed
- Unified protocol implementation path to Python-only marshal/packet parsing.
- Removed native bridge-related packaging behavior and binary cleanup assumptions.
- Reduced hidden binary cleanup side effects in build artifacts and packaging files.

### Notes
- Package version is set to `2.0.0`.
- Binary distribution format remains source-compatible with legacy test artifacts when using
  `PYTHONPATH`-based execution.