This is an automated email from the ASF dual-hosted git repository.
yihua pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/hudi-rs.git
The following commit(s) were added to refs/heads/main by this push:
new af1b6299 docs(python): add doctests to builder and config APIs, enable
--doctest-modules (#623)
af1b6299 is described below
commit af1b629994bc5f287614604a3ce0042387fd2d88
Author: GayathriSrividya <[email protected]>
AuthorDate: Wed Oct 28 07:42:28 2026 +0530
docs(python): add doctests to builder and config APIs, enable
--doctest-modules (#623)
Co-authored-by: Gayathri Srividya Rajavarapu
<[email protected]>
---
.github/workflows/ci.yml | 4 +--
python/hudi/_config.py | 27 +++++++++++++++++--
python/hudi/table/builder.py | 64 ++++++++++++++++++++++++++++++++++++++++++++
python/pyproject.toml | 1 +
4 files changed, 92 insertions(+), 4 deletions(-)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 611b0c57..2b860c07 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -248,14 +248,14 @@ jobs:
if: ${{ !((matrix.os == 'ubuntu-24.04') && (matrix.python-version ==
'3.13')) }}
run: |
source .venv/bin/activate
- pytest -v
+ pytest -v python
- name: Python unit tests with coverage report
# Only compute coverage for ubuntu-24.04 with Python 3.13
if: ${{ (matrix.os == 'ubuntu-24.04') && (matrix.python-version ==
'3.13') }}
run: |
source .venv/bin/activate
- coverage run --include 'python/hudi/*' -m pytest -v
+ coverage run --include 'python/hudi/*' -m pytest -v python
coverage xml --data-file=.coverage -o
./cov-reports/cov-report-python-tests-${{ join(matrix.*, '-') }}.xml
- name: Upload coverage report
diff --git a/python/hudi/_config.py b/python/hudi/_config.py
index 2a4eb3b3..2e59d914 100644
--- a/python/hudi/_config.py
+++ b/python/hudi/_config.py
@@ -38,6 +38,13 @@ HudiTableConfig = Enum(
)
HudiTableConfig.__doc__ = (
"Configurations for Hudi tables, most of them are persisted in
`hoodie.properties`."
+ "\n\n"
+ "Examples:\n"
+ " >>> from hudi import HudiTableConfig\n"
+ " >>> HudiTableConfig.BASE_PATH.value\n"
+ " 'hoodie.base.path'\n"
+ " >>> HudiTableConfig.TABLE_NAME.value\n"
+ " 'hoodie.table.name'\n"
)
HudiReadConfig = Enum(
@@ -47,7 +54,16 @@ HudiReadConfig = Enum(
module=__name__,
qualname="HudiReadConfig",
)
-HudiReadConfig.__doc__ = "Configurations for reading Hudi tables."
+HudiReadConfig.__doc__ = (
+ "Configurations for reading Hudi tables."
+ "\n\n"
+ "Examples:\n"
+ " >>> from hudi import HudiReadConfig\n"
+ " >>> HudiReadConfig.QUERY_TYPE.value\n"
+ " 'hoodie.read.query.type'\n"
+ " >>> HudiReadConfig.AS_OF_TIMESTAMP.value\n"
+ " 'hoodie.read.as.of.timestamp'\n"
+)
HudiPlanConfig = Enum(
"HudiPlanConfig",
@@ -56,6 +72,13 @@ HudiPlanConfig = Enum(
module=__name__,
qualname="HudiPlanConfig",
)
-HudiPlanConfig.__doc__ = "Configurations for query planning in Hudi."
+HudiPlanConfig.__doc__ = (
+ "Configurations for query planning in Hudi."
+ "\n\n"
+ "Examples:\n"
+ " >>> from hudi import HudiPlanConfig\n"
+ " >>> HudiPlanConfig.LISTING_PARALLELISM.value\n"
+ " 'hoodie.plan.listing.parallelism'\n"
+)
__all__ = ["HudiPlanConfig", "HudiReadConfig", "HudiTableConfig"]
diff --git a/python/hudi/table/builder.py b/python/hudi/table/builder.py
index ae31abf7..d732efe5 100644
--- a/python/hudi/table/builder.py
+++ b/python/hudi/table/builder.py
@@ -55,6 +55,16 @@ class HudiTableBuilder:
Returns:
HudiTableBuilder: An instance of the builder.
+
+ Examples:
+ >>> from hudi import HudiTableBuilder
+ >>> builder =
HudiTableBuilder.from_base_uri("s3://my-bucket/trips")
+ >>> builder.base_uri
+ 's3://my-bucket/trips'
+ >>> builder.hudi_options
+ {}
+ >>> builder.storage_options
+ {}
"""
builder = cls(base_uri)
return builder
@@ -75,6 +85,13 @@ class HudiTableBuilder:
Returns:
HudiTableBuilder: The builder instance.
+
+ Examples:
+ >>> from hudi import HudiTableBuilder
+ >>> builder =
HudiTableBuilder.from_base_uri("s3://my-bucket/trips")
+ >>> builder =
builder.with_hudi_option("read.timeline.num-instants", "5")
+ >>> builder.hudi_options
+ {'read.timeline.num-instants': '5'}
"""
self._add_options({_coerce_key(k): v}, "hudi")
return self
@@ -88,6 +105,16 @@ class HudiTableBuilder:
Returns:
HudiTableBuilder: The builder instance.
+
+ Examples:
+ >>> from hudi import HudiTableBuilder
+ >>> builder =
HudiTableBuilder.from_base_uri("s3://my-bucket/trips")
+ >>> builder = builder.with_hudi_options({
+ ... "read.timeline.num-instants": "5",
+ ... "read.use.new.log.record.reader": "true",
+ ... })
+ >>> sorted(builder.hudi_options.items())
+ [('read.timeline.num-instants', '5'),
('read.use.new.log.record.reader', 'true')]
"""
self._add_options(hudi_options, "hudi")
return self
@@ -102,6 +129,13 @@ class HudiTableBuilder:
Returns:
HudiTableBuilder: The builder instance.
+
+ Examples:
+ >>> from hudi import HudiTableBuilder
+ >>> builder =
HudiTableBuilder.from_base_uri("s3://my-bucket/trips")
+ >>> builder = builder.with_storage_option("aws.region",
"us-east-1")
+ >>> builder.storage_options
+ {'aws.region': 'us-east-1'}
"""
self._add_options({k: v}, "storage")
return self
@@ -117,6 +151,13 @@ class HudiTableBuilder:
Returns:
HudiTableBuilder: The builder instance.
+
+ Examples:
+ >>> from hudi import HudiTableBuilder
+ >>> builder =
HudiTableBuilder.from_base_uri("s3://my-bucket/trips")
+ >>> builder = builder.with_storage_options({"aws.region":
"us-east-1"})
+ >>> builder.storage_options
+ {'aws.region': 'us-east-1'}
"""
self._add_options(storage_options, "storage")
return self
@@ -131,6 +172,13 @@ class HudiTableBuilder:
Returns:
HudiTableBuilder: The builder instance.
+
+ Examples:
+ >>> from hudi import HudiTableBuilder
+ >>> builder =
HudiTableBuilder.from_base_uri("s3://my-bucket/trips")
+ >>> builder = builder.with_option("aws.region", "eu-west-1")
+ >>> builder.options
+ {'aws.region': 'eu-west-1'}
"""
self._add_options({_coerce_key(k): v})
return self
@@ -144,6 +192,13 @@ class HudiTableBuilder:
Returns:
HudiTableBuilder: The builder instance.
+
+ Examples:
+ >>> from hudi import HudiTableBuilder
+ >>> builder =
HudiTableBuilder.from_base_uri("s3://my-bucket/trips")
+ >>> builder = builder.with_options({"aws.region":
"ap-southeast-1"})
+ >>> builder.options
+ {'aws.region': 'ap-southeast-1'}
"""
self._add_options(options)
return self
@@ -154,6 +209,15 @@ class HudiTableBuilder:
Returns:
HudiTable: The constructed HudiTable object.
+
+ Examples:
+ >>> from hudi import HudiTableBuilder
+ >>> table = (
+ ... HudiTableBuilder.from_base_uri("s3://my-bucket/trips")
+ ... .with_hudi_option("read.timeline.num-instants", "5")
+ ... .with_storage_option("aws.region", "us-east-1")
+ ... .build()
+ ... ) # doctest: +SKIP
"""
return build_hudi_table(
self.base_uri, self.hudi_options, self.storage_options,
self.options
diff --git a/python/pyproject.toml b/python/pyproject.toml
index bfa5b53a..16c5d1b3 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -87,6 +87,7 @@ exclude = "^tests"
strict = true
[tool.pytest.ini_options]
+addopts = "--doctest-modules"
testpaths = [
"tests",
"hudi",
