This is an automated email from the ASF dual-hosted git repository.
aroy pushed a commit to branch royari-update-docs
in repository
https://gitbox.apache.org/repos/asf/incubator-resilientdb-python-sdk.git
The following commit(s) were added to refs/heads/royari-update-docs by this
push:
new ac21909 Update docs
ac21909 is described below
commit ac21909914d06c1f1eedf573df7c43c31de66d10
Author: Arindaam Roy <alpharo...@gmail.com>
AuthorDate: Tue May 20 18:55:40 2025 -0700
Update docs
- update readme
- add contributing strategy
---
CONTRIBUTING.md | 87 ++++++++++++++++++++++
README.md | 218 ++++++++++++++++++++++++++++++++++++++++++++++++--------
2 files changed, 277 insertions(+), 28 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..f87c715
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,87 @@
+# Contributing to Apache ResilientDB Python SDK
+
+We love your input! We want to make contributing to Apache ResilientDB Python
SDK as easy and transparent as possible, whether it's:
+
+- Reporting a bug
+- Discussing the current state of the code
+- Submitting a fix
+- Proposing new features
+- Becoming a maintainer
+
+## Development Process
+
+We use GitHub to host code, to track issues and feature requests, as well as
accept pull requests.
+
+1. Fork the repo and create your branch from `main`.
+2. If you've added code that should be tested, add tests.
+3. If you've changed APIs, update the documentation.
+4. Ensure the test suite passes.
+5. Make sure your code follows the project's coding standards.
+6. Issue that pull request!
+
+## Development Setup
+
+1. Clone your fork:
+ ```bash
+ git clone
https://github.com/YOUR_USERNAME/incubator-resilientdb-python-sdk.git
+ cd incubator-resilientdb-python-sdk
+ ```
+
+2. Set up development environment:
+ ```bash
+ sh INSTALL.sh
+ python3.10 -m venv venv
+ source venv/bin/activate
+ pip install -r requirements.txt
+ ```
+
+3. Create a branch:
+ ```bash
+ git checkout -b your-feature-name
+ ```
+
+## Coding Standards
+
+- Follow PEP 8 style guide for Python code
+- Use type hints for function parameters and return values
+- Write docstrings for all public methods and classes
+- Keep functions focused and concise
+- Add comments for complex logic
+- Include unit tests for new functionality
+
+## Pull Request Process
+
+1. Update the README.md with details of changes to the interface, if
applicable.
+2. Update the documentation with details of any new functionality.
+3. The PR will be merged once you have the sign-off of at least one maintainer.
+
+
+## Issue Reporting Guidelines
+
+
+### Bug Reports
+
+When filing an issue, make sure to answer these questions:
+
+1. What version of Python are you using?
+2. What operating system are you using?
+3. What did you do?
+4. What did you expect to see?
+5. What did you see instead?
+
+### Feature Requests
+
+We welcome feature requests! When submitting a feature request, please:
+
+1. Explain the problem you're trying to solve
+2. Describe the solution you'd like to see
+3. Provide context about alternative solutions you've considered
+
+## Community
+
+- Subscribe to our [mailing
lists](https://lists.apache.org/list.html?dev@resilientdb.apache.org)
+- Join our discussions on [GitHub
Issues](https://github.com/apache/incubator-resilientdb-python-sdk/issues)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
Apache License, Version 2.0.
\ No newline at end of file
diff --git a/README.md b/README.md
index d4fe107..fa5ba5f 100644
--- a/README.md
+++ b/README.md
@@ -1,52 +1,214 @@
-# ResilientDB SDK
+# Apache ResilientDB Python SDK (Incubating)
-## Check Python is up-to-date (3.9+)
-`$ python3 --version`
+<div align="center">
+
+[](LICENSE)
+[](https://github.com/apache/incubator-resilientdb-python-sdk)
+[](./docs)
+[](./CONTRIBUTING.md)
+[]()
-If your Python version number is too low you may encounter type hinting issues
when attempting to run the code. You can use a Python virtual environment, as
shown below.
+High-performance blockchain database SDK for Python applications
+
+[Quick Start](#quick-start) β’
+[Documentation](#documentation) β’
+[Examples](#examples) β’
+[Contributing](#contributing) β’
+[Support](#support)
-## First-time set up
+</div>
-`$ sh INSTALL.sh`
+> [!NOTE]
+> Apache ResilientDB is an effort undergoing incubation at The Apache Software
Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of
all newly accepted projects until a further review indicates that the
infrastructure, communications, and decision making process have stabilized in
a manner consistent with other successful ASF projects.
-`$ python3.10 -m venv venv`
+## π Quick Start
-`$ source venv/bin/activate`
+### Installation
-`$ pip install -r requirements.txt`
+```bash
+# Clone the repository
+git clone https://github.com/apache/incubator-resilientdb-python-sdk.git
+cd incubator-resilientdb-python-sdk
-The correct Python configuration is needed for transaction validation.
+# Set up the environment
+sh INSTALL.sh
+python3.10 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
-## Running KV service
+### Basic Usage
-If your virtual environment is not already active:
+```python
+from resdb_driver import Resdb
+from resdb_driver.crypto import generate_keypair
+from typing import Dict, Any
-`$ source venv/bin/activate`
+# Initialize the client
+db = Resdb('http://127.0.0.1:18000')
+
+# Generate keypairs for the example
+alice, bob = generate_keypair(), generate_keypair()
+
+# Create a digital asset
+asset = {
+ "data": {
+ "token_for": "example",
+ "description": "Example token",
+ },
+}
-Run the script to start 4 local nodes
+# Prepare transaction
+prepared_tx = db.transactions.prepare(
+ operation='CREATE',
+ signers=alice.public_key,
+ recipients=[([bob.public_key], 10)], # Transfer 10 tokens to Bob
+ asset=asset,
+)
-`$ sh service/tools/start_kv_service_sdk.sh`
+# Sign the transaction
+fulfilled_tx = db.transactions.fulfill(
+ prepared_tx,
+ private_keys=alice.private_key
+)
-## Running Crow service (HTTP endpoints)
+# Send the transaction
+tx_id_str = db.transactions.send_commit(fulfilled_tx)
-`$ bazel build service/http_server/crow_service_main`
-`$ bazel-bin/service/http_server/crow_service_main
service/tools/config/interface/client.config
service/http_server/server_config.config`
+# Retrieve the transaction
+result = db.transactions.retrieve(fulfilled_tx["id"])
+print(f"Retrieved transaction: {result}")
+```
-For a list of endpoints visit [here](./service/http_server/README.md)
+## π Features
-## Testing
+- **Transaction Management**
+ - Create and send transactions with digital signatures
+ - Retrieve and query transaction details
+ - Asset-based transaction querying
-`$ bazel-bin/service/kv_service/kv_service_tools
service/tools/config/interface/service.config set test 1234`
+- **Block Operations**
+ - Retrieve blocks by transaction
+ - Query block ranges
+ - Real-time block updates
-## Running the driver
+- **Asset & Metadata Management**
+ - Asset search and retrieval
+ - Metadata management
+ - Output tracking
-Examples of using the driver can be seen in [test_driver](/test_driver.py)
+- **DB Connection**
+ - Automatic failover
+ - Round-robin load balancing
+ - Connection pooling
+ - Exponential backoff
-Replace the db_root_url with the address of the ResilientDB HTTP endpoints
e.g. `127.0.0.1:18000`
+## π Requirements
+- Python 3.9 or higher
+- Bazel build system
+- Debian based linux distros e.g. Ubuntu
+- Virtual environment (recommended)
+
+## π§ Setup & Configuration
+
+### 1. Start the Key-Value Service
+
+```bash
+source venv/bin/activate
+sh service/tools/start_kv_service_sdk.sh
+```
+
+### 2. Start the HTTP Service
+
+```bash
+bazel build service/http_server/crow_service_main
+bazel-bin/service/http_server/crow_service_main \\
+ service/tools/config/interface/client.config \\
+ service/http_server/server_config.config
+```
+
+## π Documentation
+
+- [Complete API Reference](./docs/api_reference.md)
+- [HTTP Endpoints Guide](./service/http_server/README.md)
+- [Contributing Guidelines](./CONTRIBUTING.md)
+- [Example Use Cases](./test_driver_2.py)
+
+## ποΈ Project Structure
+
+```
+resilientdb-python-sdk/
+βββ docs/ # Documentation and guides
+βββ resdb_driver/ # Core SDK implementation
+βββ service/ # Service implementations
+β βββ http_server/ # HTTP API service (Crow)
+β βββ kv_service/ # Key-Value service
+βββ test/ # Test suite
+```
+
+## π§ͺ Testing
+TODO: add tests
+
+## π Troubleshooting
+
+### Common Issues
+
+1. **Connection Refused**
+ ```
+ Solution: Ensure the HTTP service is running on port 18000
+ ```
+
+2. **Python Version Mismatch**
+ ```
+ Solution: Use Python 3.9 or higher, preferably in a virtual environment
+ ```
+
+3. **Bazel Build Failures**
+ ```
+ Solution: Check Bazel version and ensure all dependencies are installed
+ ```
-## TODO
-- Setting up linting (using [black](https://github.com/psf/black)) through
github hooks
-- convert the sdk into a package (for pip install)
-- Potentially have a docker setup which fetched the Resdb image and runs it
locally
+## π€ Contributing
+
+We welcome contributions! See our [Contributing Guidelines](./CONTRIBUTING.md)
for:
+- How to submit patches
+- Development workflow
+- Coding standards
+
+## π License
+
+This project is licensed under the Apache License 2.0 - see the
[LICENSE](LICENSE) file for details.
+
+## π¬ Support
+
+- [GitHub
Issues](https://github.com/apache/incubator-resilientdb-python-sdk/issues)
+- [Mailing
Lists](https://lists.apache.org/list.html?dev@resilientdb.apache.org)
+
+## πΊοΈ Roadmap
+
+### Current Goals
+- [ ] Setting up linting (using [black](https://github.com/psf/black))
+- [ ] Convert to pip-installable package
+- [ ] Docker setup for local ResilientDB
+
+### Connection Improvements
+- [ ] WebSocket support for real-time updates
+- [ ] Connection pooling optimization
+- [ ] Automatic node health checking
+- [ ] Custom retry strategies
+- [ ] Connection encryption options
+- [ ] Bulk operations support
+- [ ] Load balancing strategies
+- [ ] Metrics and monitoring
+
+### API Enhancements
+- [ ] Add async/await support using aiohttp
+- [ ] Complete implementation of async/sync transaction modes
+- [ ] Add batch transaction support
+- [ ] Implement streaming responses for large datasets
+- [ ] Add support for complex query operations
+- [ ] Implement automatic request compression
+- [ ] Improve transaction ID handling
+- [ ] Add retry mechanisms for failed transactions
\ No newline at end of file
