odyn 0.3.0

Odyn is a python client for Business Central Web Services API.

Odyn

Odyn is a modern, async-first Python client for Microsoft Dynamics 365 Business Central Web Services. It provides a high-level interface for extracting and interacting with data from Business Central using OData, handling the complexities of authentication, rate limiting, and data transformation.

Project Scope

This project was designed for personal use and follows an opinionated structure. It currently supports Business Central OData Web Services specifically. It is not intended for use with the standard Business Central API v2.0 endpoints.

Problem Solved

Integrating with Business Central Web Services often involves significant boilerplate for authentication, manual construction of OData queries, complex pagination logic, and data conversion. Odyn eliminates this overhead by providing a type-safe, fluent API that returns native Polars DataFrames, designed specifically for data engineering and high-performance integration tasks.

Capabilities

• Async Execution: Built on httpx for high-performance asynchronous I/O.
• Polars Integration: Native support for Polars DataFrames for efficient data processing.
• Query Builder: Type-safe OData query builder with support for filters, expansions, and ordering.
• Caching: Persistent Parquet-based caching with configurable TTL to reduce API load.
• Resilience: Automatic retries with exponential backoff and configurable rate limiting (via aiolimiter).
• Data Handling: Automatic pagination, streaming, and efficient batching for large datasets.

Dependencies

• Python 3.12+
• httpx
• polars
• aiolimiter

Installation

pip install odyn

Quick Example

import asyncio
from odyn import BCWebServiceClient, BasicAuth
from odyn.query import ODataQuery, F

async def main():
    async with BCWebServiceClient.create(
        server="https://bc-server:7048",
        instance="BC200",
        auth=BasicAuth("user", "password"),
        company="CRONUS",
    ) as client:
        # Fetch customers with balance > 1000
        query = ODataQuery().filter(F.Balance > 1000)
        df = await client.get("customers", query=query)
        print(df)

if __name__ == "__main__":
    asyncio.run(main())

Documentation

Comprehensive documentation is available in the docs/ directory:

• API Reference — Detailed class and method reference.
• Client Configuration — Setting up the BCWebServiceClient.
• Authentication — Configuring authentication for your environment.
• Query Builder — Building type-safe filters and expansions.
• Caching — Improving performance with local Parquet caching.
• Exception Handling — Understanding the error hierarchy.
• Troubleshooting — Solutions for common BC integration issues.

Examples

Refer to the examples/ directory for functional examples covering various use cases:

• Quickstart: Basic setup and simple GET request.
• Query Builder: Filtering, selection, ordering, and expands.
• Lookups: Fetching single records by key or ID.
• Batch Operations: Concurrent lookups for multiple IDs.
• Streaming: Processing large datasets page-by-page.
• Caching: Persistent Parquet-based caching.
• Error Handling: Common exceptions and error patterns.
• Configuration: Advanced client settings (retries, rate limits).
• Sync Compatibility: Using Odyn in non-async applications.
• Metadata: Inspecting available endpoints and counts.

License

MIT