odyn 0.1.0__tar.gz

odyn-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop, master ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        version: "latest"
+
+    - name: Cache dependencies
+      uses: actions/cache@v4
+      with:
+        path: |
+          .uv-cache
+          .venv
+        key: ${{ runner.os }}-uv-${{ hashFiles('**/pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-uv-
+
+    - name: Install dependencies
+      run: |
+        uv sync --dev
+
+    - name: Run linting
+      run: |
+        uv run ruff check src/ tests/
+        uv run ruff format --check src/ tests/
+
+    - name: Run type checking
+      run: |
+        uv run ty check src/
+
+    - name: Run tests with coverage
+      run: |
+        uv run pytest --cov=odyn --cov-report=xml --cov-report=term-missing
+
+    - name: Upload coverage to Codecov (oidc)
+      uses: codecov/codecov-action@v5
+      with:
+        fail_ci_if_error: false
+        verbose: true
+        token: ${{ secrets.CODECOV_TOKEN }}
+        slug: konspec/odyn

odyn-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish Python 🐍 distribution 📦 to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    name: Build and publish Python 🐍 distribution 📦 to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi-publish
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build --out-dir dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

odyn-0.1.0/.gitignore

@@ -0,0 +1,194 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the enitre vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore

odyn-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,63 @@
+# Pre-commit configuration for odyn project
+# See https://pre-commit.com for more information
+
+repos:
+  # Python code formatting and linting
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.0
+    hooks:
+      - id: ruff-check
+        name: ruff-check
+        description: Run Ruff linter
+        args: [--fix]
+        types_or: [python, pyi]
+      - id: ruff-format
+        name: ruff-format
+        description: Run Ruff formatter
+        types_or: [python, pyi]
+
+  # General file checks and cleanup
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-ast
+        name: check-ast
+        description: Check Python AST validity
+      - id: check-yaml
+        name: check-yaml
+        description: Check YAML file syntax
+      - id: check-toml
+        name: check-toml
+        description: Check TOML file syntax
+      - id: check-json
+        name: check-json
+        description: Check JSON file syntax
+      - id: end-of-file-fixer
+        name: end-of-file-fixer
+        description: Ensure files end with newline
+      - id: trailing-whitespace
+        name: trailing-whitespace
+        description: Remove trailing whitespace
+      - id: check-added-large-files
+        name: check-added-large-files
+        description: Prevent large files from being committed
+        args: [--maxkb=1000]
+      - id: check-merge-conflict
+        name: check-merge-conflict
+        description: Check for merge conflict markers
+      - id: mixed-line-ending
+        name: mixed-line-ending
+        description: Check for mixed line endings
+        args: [--fix=lf]
+
+  # Commit message formatting and validation
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.8.3
+    hooks:
+      - id: commitizen
+        name: commitizen-check
+        description: Check commit message format
+      - id: commitizen-branch
+        name: commitizen-branch
+        description: Check branch naming convention
+        stages: [pre-push]

odyn-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

odyn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Konkan Speciality Polyproducts Private Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

odyn-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: odyn
+Version: 0.1.0
+Summary: Odyn – Python adapter for Microsoft Dynamics 365 Business Central OData v4 API
+Author-email: kon-fin <erpsupport@konspec.com>
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: requests>=2.32.4
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://konspec.com/wp-content/uploads/2024/05/Konspec-web1.png" alt="Konspec Logo" width="320"/>
+</p>
+
+# Odyn
+
+**A modern, typed, and robust Python client for the Microsoft Dynamics 365 Business Central OData V4 API**
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](docs/index.md)
+[![Tests](https://github.com/konspec/odyn/workflows/CI/badge.svg)](https://github.com/konspec/odyn/actions)
+[![codecov](https://codecov.io/gh/konspec/odyn/graph/badge.svg?token=H8MK6DP96P)](https://codecov.io/gh/konspec/odyn)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+---
+
+Odyn provides a convenient and feature-rich interface for interacting with Microsoft Dynamics 365 Business Central, including automatic retry mechanisms, pagination handling, and pluggable authentication sessions.
+
+## Features
+
+- **Type Safety**: Fully typed with comprehensive type annotations for better IDE support and runtime safety.
+- **Automatic Retry Logic**: Built-in exponential backoff retry mechanism for handling transient network failures.
+- **Smart Pagination**: Automatic handling of OData pagination with transparent multi-page data retrieval.
+- **Flexible Authentication**: Pluggable `requests.Session` based authentication. Comes with `BearerAuthSession` and `BasicAuthSession` out of the box.
+- **Comprehensive Logging**: Detailed logging with `loguru` integration for easy debugging and monitoring.
+- **Production Ready**: Robust error handling, validation, and timeout management.
+- **Extensible Design**: Easily extendable to support custom authentication strategies or other session-level features.
+
+## Quick Install
+
+```bash
+pip install odyn
+```
+
+Or see [full installation instructions](docs/installation.md) for pip, uv, and poetry.
+
+## Quick Start
+
+```python
+from odyn import Odyn, BearerAuthSession
+
+# Create an authenticated session
+session = BearerAuthSession("your-access-token")
+
+# Initialize the client
+client = Odyn(
+    base_url="https://your-tenant.businesscentral.dynamics.com/api/v2.0/",
+    session=session
+)
+
+# Fetch data with automatic pagination
+customers = client.get("customers")
+print(f"Retrieved {len(customers)} customers")
+
+# Use OData query parameters
+filtered_customers = client.get(
+    "customers",
+    params={
+        "$top": 10,
+        "$filter": "contains(name, 'Adventure')",
+        "$select": "id,name,phoneNumber"
+    }
+)
+```
+
+## Requirements
+
+- **Python 3.12+**
+- **requests** (≥2.32.4)
+- **loguru** (≥0.7.3)
+
+## Documentation
+
+- 📚 **Full documentation:** [docs/index.md](docs/index.md)
+
+### Getting Started
+- [Installation](docs/installation.md) - Install Odyn using pip, uv, or poetry
+- [Getting Started](docs/getting-started.md) - Quick setup and first API call
+
+### Usage Guides
+- [Odyn Client](docs/usage/odyn.md) - Complete API reference for the main client
+- [Authentication Sessions](docs/usage/sessions.md) - Session management and authentication
+- [Exception Handling](docs/usage/exceptions.md) - Understanding and handling errors
+
+### Advanced Topics
+- [Configuration](docs/advanced/configuration.md) - Timeouts, retries, and advanced settings
+- [Logging](docs/advanced/logging.md) - Logging behavior and customization
+
+### Reference
+- [FAQ](docs/faq.md) - Frequently asked questions
+- [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
+
+## Examples
+
+### Bearer Token Authentication
+```python
+from odyn import Odyn, BearerAuthSession
+
+# Create a session with your bearer token
+session = BearerAuthSession(token="your-access-token")
+
+# Initialize the client
+client = Odyn(
+    base_url="https://api.businesscentral.dynamics.com/v2.0/your-tenant-id/production/",
+    session=session,
+)
+
+# Get all customers with automatic pagination handling
+customers = client.get("customers")
+print(f"Retrieved {len(customers)} customers")
+
+# Get the top 10 items, filtering by name and selecting specific fields
+items = client.get(
+    "items",
+    params={
+        "$top": 10,
+        "$filter": "contains(displayName, 'Desk')",
+        "$select": "id,displayName,itemCategoryCode",
+    },
+)
+print(f"Filtered items: {items}")
+```
+
+### Basic Authentication
+```python
+from odyn import Odyn, BasicAuthSession
+
+# Create a session with your username and web service access key
+session = BasicAuthSession(username="your-username", password="your-web-service-access-key")
+
+# Initialize the client
+client = Odyn(
+    base_url="https://api.businesscentral.dynamics.com/v2.0/your-tenant-id/production/",
+    session=session,
+)
+
+# Get all vendors
+vendors = client.get("vendors")
+print(f"Retrieved {len(vendors)} vendors")
+```
+
+### Advanced Configuration
+```python
+from odyn import Odyn, BearerAuthSession
+from loguru import logger
+
+# Bind a custom component to the logger for easy filtering
+custom_logger = logger.bind(component="business-central-client")
+
+# Create a session with custom retry settings
+# This example uses a more aggressive retry strategy than the default.
+session = BearerAuthSession(
+    token="your-token",
+    retries=10,
+    backoff_factor=0.5,
+    status_forcelist=[408, 429, 500, 502, 503, 504],
+)
+
+# Initialize a client with a custom timeout and the custom logger
+client = Odyn(
+    base_url="https://api.businesscentral.dynamics.com/v2.0/your-tenant-id/production/",
+    session=session,
+    logger=custom_logger,
+    timeout=(10, 60),  # 10s connect timeout, 60s read timeout
+)
+```
+
+### Error Handling
+```python
+from odyn import (
+    Odyn,
+    BearerAuthSession,
+    InvalidURLError,
+    InvalidSessionError,
+    InvalidTimeoutError,
+    InvalidLoggerError,
+)
+import requests
+
+try:
+    # Intentionally create an invalid session
+    session = BearerAuthSession(token=None) # type: ignore
+    client = Odyn(base_url="not-a-valid-url", session=session)
+    client.get("customers")
+
+except InvalidURLError as e:
+    print(f"Invalid URL: {e}")
+except InvalidSessionError as e:
+    print(f"Invalid session: {e}")
+except InvalidTimeoutError as e:
+    print(f"Invalid timeout configuration: {e}")
+except InvalidLoggerError as e:
+    print(f"Invalid logger object provided: {e}")
+except requests.exceptions.HTTPError as e:
+    # Handle HTTP errors (e.g., 401 Unauthorized, 404 Not Found)
+    print(f"HTTP Error: {e.response.status_code} - {e.response.text}")
+except requests.exceptions.RequestException as e:
+    # Handle network-related errors (e.g., connection refused)
+    print(f"Network Error: {e}")
+except Exception as e:
+    print(f"An unexpected error occurred: {e}")
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](docs/contributing.md) for details.
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/konspec/odyn.git
+cd odyn
+
+# Install dependencies (we recommend using uv)
+uv pip install -e .[dev]
+
+# Run tests
+pytest
+
+# Run linting
+ruff check .
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- [Documentation](docs/index.md)
+- [FAQ](docs/faq.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Issues](https://github.com/konspec/odyn/issues)
+
+## Related
+
+- [Microsoft Dynamics 365 Business Central OData Web Services](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/odata-web-services)
+- [OData V4 Specification](https://docs.oasis-open.org/odata/odata/v4.0/os/part1-protocol/odata-v4.0-os-part1-protocol.html)
+- [requests](https://docs.python-requests.org/) - HTTP library
+- [loguru](https://loguru.readthedocs.io/) - Logging library