Metadata-Version: 2.4
Name: ds-provider-xledger-py-lib
Version: 0.1.0a3
Summary: A Python package from the DS library collection
Author-email: Kristopy <hello@grasplabs.com>
Maintainer-email: Kristopy <hello@grasplabs.com>
License-Expression: Apache-2.0
Project-URL: Documentation, https://grasp-labs.github.io/ds-provider-xledger-py-lib/
Project-URL: Repository, https://github.com/grasp-labs/ds-provider-xledger-py-lib/
Project-URL: Issues, https://github.com/grasp-labs/ds-provider-xledger-py-lib/issues/
Project-URL: Changelog, https://github.com/grasp-labs/ds-provider-xledger-py-lib/releases
Keywords: ds,python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE-APACHE
Requires-Dist: ds-resource-plugin-py-lib<1.0.0,>=0.1.0rc2
Requires-Dist: ds-common-serde-py-lib<1.0.0,>=0.1.0b1
Requires-Dist: ds-common-logger-py-lib<1.0.0,>=0.1.0a5
Requires-Dist: ds-protocol-http-py-lib<1.0.0,>=0.1.0b4
Provides-Extra: dev
Requires-Dist: ruff>=0.1.8; extra == "dev"
Requires-Dist: mypy>=1.7.0; extra == "dev"
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.3.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Requires-Dist: sphinx>=7.1.0; extra == "dev"
Requires-Dist: sphinx-autoapi>=3.0.0; extra == "dev"
Requires-Dist: sphinx-material>=0.0.35; extra == "dev"
Requires-Dist: bandit>=1.7.0; extra == "dev"
Requires-Dist: pandas-stubs>=2.1.0; extra == "dev"
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.4.0; extra == "test"
Requires-Dist: pytest-cov>=4.1.0; extra == "test"
Requires-Dist: pytest-xdist>=3.3.0; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=7.1.0; extra == "docs"
Requires-Dist: sphinx-autoapi>=3.0.0; extra == "docs"
Requires-Dist: sphinx-material>=0.0.35; extra == "docs"
Dynamic: license-file

# ds-provider-xledger-py-lib

A Python package from the ds-common library collection.

## Installation

Install the package using pip:

```bash
pip install ds-provider-xledger-py-lib
```

Or using uv (recommended):

```bash
uv pip install ds-provider-xledger-py-lib
```

## Quick Start

```python
from ds_provider_xledger_py_lib import __version__

print(f"ds-provider-xledger-py-lib version: {__version__}")
```

## Features

- Linked service support for Xledger GraphQL authentication and connectivity checks
- Dataset operations for read, create, update, and delete workflows
- Pagination and checkpoint support for resilient read operations
- Structured GraphQL error mapping into provider-specific exceptions

## Usage

### 1) Test linked service connection

```python
from uuid import uuid4

from ds_provider_xledger_py_lib.linked_service import (
    XledgerLinkedService,
    XledgerLinkedServiceSettings,
)

linked_service = XledgerLinkedService(
    id=uuid4(),
    name="xledger-linked-service",
    version="1.0.0",
    settings=XledgerLinkedServiceSettings(
        host="https://demo.xledger.net/graphql",
        token="YOUR_XLEDGER_TOKEN",
        timeout=60,
    ),
)

success, message = linked_service.test_connection()
print(success, message)
```

### 2) Read data from an entrypoint

```python
from uuid import uuid4

from ds_provider_xledger_py_lib.dataset import XledgerDataset, XledgerDatasetSettings
from ds_provider_xledger_py_lib.dataset.xledger import XledgerReadSettings
from ds_provider_xledger_py_lib.linked_service import XledgerLinkedService, XledgerLinkedServiceSettings

linked_service = XledgerLinkedService(
    id=uuid4(),
    name="xledger-linked-service",
    version="1.0.0",
    settings=XledgerLinkedServiceSettings(
        host="https://demo.xledger.net/graphql",
        token="YOUR_XLEDGER_TOKEN",
        timeout=60,
    ),
)

dataset = XledgerDataset(
    id=uuid4(),
    name="xledger-dataset-read",
    version="1.0.0",
    linked_service=linked_service,
    settings=XledgerDatasetSettings(
        entrypoint="employees",
        read=XledgerReadSettings(
            columns=["dbId", "code", "description"],
            limit=1000,
            first=1000,
        ),
    ),
)

linked_service.connect()
dataset.read()
print(dataset.output.head())
```

### 3) Update rows

```python
from uuid import uuid4

import pandas as pd
from ds_provider_xledger_py_lib.dataset import XledgerDataset, XledgerDatasetSettings
from ds_provider_xledger_py_lib.dataset.xledger import XledgerUpdateSettings
from ds_provider_xledger_py_lib.linked_service import XledgerLinkedService, XledgerLinkedServiceSettings

linked_service = XledgerLinkedService(
    id=uuid4(),
    name="xledger-linked-service",
    version="1.0.0",
    settings=XledgerLinkedServiceSettings(
        host="https://demo.xledger.net/graphql",
        token="YOUR_XLEDGER_TOKEN",
        timeout=60,
    ),
)

dataset = XledgerDataset(
    id=uuid4(),
    name="xledger-dataset-update",
    version="1.0.0",
    linked_service=linked_service,
    settings=XledgerDatasetSettings(
        entrypoint="employees",
        update=XledgerUpdateSettings(
            return_columns=["dbId", "code", "description"],
        ),
    ),
)

dataset.input = pd.DataFrame(
    [{"dbId": 1, "code": "EMP-001", "description": "Updated employee"}]
)
linked_service.connect()
dataset.update()
print(dataset.output)
```

For complete runnable scripts, see the repository's `examples/` folder.

## Requirements

- Python 3.11 or higher

## Optional Dependencies

- ds-protocol-http-py-lib>=0.1.0-beta.4,<1.0.0
- ds-resource-plugin-py-lib>=0.1.0-rc.2,<1.0.0
- ds-common-logger-py-lib>=0.1.0-alpha.5,<1.0.0

## Documentation

Full documentation is available at:

- [GitHub Repository](https://github.com/grasp-labs/ds-provider-xledger-py-lib)
- [Documentation Site](https://grasp-labs.github.io/ds-provider-xledger-py-lib/)

## Development

To contribute or set up a development environment:

```bash
# Clone the repository
git clone https://github.com/grasp-labs/ds-provider-xledger-py-lib.git
cd ds-provider-xledger-py-lib

# Install development dependencies
uv sync --all-extras --dev

# Run tests
make test
```

See the [README](https://github.com/grasp-labs/ds-provider-xledger-py-lib#readme)
for more information.

## License

This package is licensed under the Apache License 2.0.
See the [LICENSE-APACHE](https://github.com/grasp-labs/ds-provider-xledger-py-lib/blob/main/LICENSE-APACHE)
file for details.

## Support

- **Issues**: [GitHub Issues](https://github.com/grasp-labs/ds-provider-xledger-py-lib/issues)
- **Releases**: [GitHub Releases](https://github.com/grasp-labs/ds-provider-xledger-py-lib/releases)
