Skip to content

docs(python): add doctests to builder and config APIs, enable --doctest-modules #623

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
GayathriSrividya wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(python): add doctests to builder and config APIs, enable --doctest-modules #623

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 25 additions & 2 deletions python/hudi/_config.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,13 @@
)
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(
Expand All @@ -47,7 +54,16 @@
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",
Expand All @@ -56,6 +72,13 @@
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"]
64 changes: 64 additions & 0 deletions python/hudi/table/builder.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,16 @@ def from_base_uri(cls, base_uri: str) -> "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
Expand All @@ -75,6 +85,13 @@ def with_hudi_option(self, k: ConfigKey, v: str) -> "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
Expand All @@ -88,6 +105,16 @@ def with_hudi_options(self, hudi_options: Dict[str, str]) -> "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
Expand All @@ -102,6 +129,13 @@ def with_storage_option(self, k: str, v: str) -> "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
Expand All @@ -117,6 +151,13 @@ def with_storage_options(

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
Expand All @@ -131,6 +172,13 @@ def with_option(self, k: ConfigKey, v: str) -> "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
Expand All @@ -144,6 +192,13 @@ def with_options(self, options: Dict[str, str]) -> "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
Expand All @@ -154,6 +209,15 @@ def build(self) -> "HudiTable":

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
Expand Down
1 change: 1 addition & 0 deletions python/pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ exclude = "^tests"
strict = true

[tool.pytest.ini_options]
addopts = "--doctest-modules"
testpaths = [
"tests",
"hudi",
Expand Down