You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@iceberg.apache.org by "rodrigc (via GitHub)" <gi...@apache.org> on 2025/01/16 23:38:19 UTC
[PR] docs: Add docstrings for Identifier, Properties, RecursiveDict [iceberg-python]
rodrigc opened a new pull request, #1530:
URL: https://github.com/apache/iceberg-python/pull/1530
This allows mkdocstrings to generate hyperlinks
to these types in the documentation.
Fixes: #1529
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs: Add docstrings for Identifier, Properties, RecursiveDict [iceberg-python]
Posted by "rodrigc (via GitHub)" <gi...@apache.org>.
rodrigc commented on PR #1530:
URL: https://github.com/apache/iceberg-python/pull/1530#issuecomment-2598850660
I rebased this PR. Do you have any further suggestions for improving the docstrings for `Properties` and `RecursiveDict`?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs: Add docstrings for Identifier, Properties, RecursiveDict [iceberg-python]
Posted by "pawamoy (via GitHub)" <gi...@apache.org>.
pawamoy commented on PR #1530:
URL: https://github.com/apache/iceberg-python/pull/1530#issuecomment-2598415684
@rodrigc do note that I'm just a passer-by! I have no authority here :smile: I'm the maintainer of mkdocstrings and found this issue while stalking a bit, just wanted to help :slightly_smiling_face:
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs: Add docstrings for Identifier, Properties, RecursiveDict [iceberg-python]
Posted by "rodrigc (via GitHub)" <gi...@apache.org>.
rodrigc commented on code in PR #1530:
URL: https://github.com/apache/iceberg-python/pull/1530#discussion_r1919447875
##########
pyiceberg/typedef.py:
##########
@@ -74,8 +74,14 @@ def __missing__(self, key: K) -> V:
Identifier = Tuple[str, ...]
+"""Type for identifiers in PyIceberg."""
Review Comment:
OK, I added this.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs: Add docstrings for Identifier, Properties, RecursiveDict [iceberg-python]
Posted by "rodrigc (via GitHub)" <gi...@apache.org>.
rodrigc commented on PR #1530:
URL: https://github.com/apache/iceberg-python/pull/1530#issuecomment-2597207467
The issue with the linter is that it does not allow docstrings to appear after the variable.
For this code:
```
Identifier = Tuple[str, ...]
"""A tuple of strings representing a table identifier.
Each string in the tuple represents a part of the table's unique path. For example,
a table in a namespace might be identified as:
("namespace", "table_name")
Examples:
>>> identifier: Identifier = ("namespace", "table_name")
"""
Properties = Dict[str, Any]
"""A dictionary type for properties in PyIceberg."""
RecursiveDict = Dict[str, Union[str, "RecursiveDict"]]
"""A recursive dictionary type for nested structures in PyIceberg."""
```
The linter fails with:
```
- hook id: check-docstring-first
- exit code: 1
pyiceberg/typedef.py:77: Module docstring appears after code (code seen on line 17).
```
If I change to:
```
check docstring is first.................................................Failed
- hook id: check-docstring-first
- exit code: 1
pyiceberg/typedef.py:76: Module docstring appears after code (code seen on line 17).
```
the linter fails with:
```
check docstring is first.................................................Failed
- hook id: check-docstring-first
- exit code: 1
pyiceberg/typedef.py:76: Module docstring appears after code (code seen on line 17).
```
Any ideas as to the best way forward?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs: Add docstrings for Identifier, Properties, RecursiveDict [iceberg-python]
Posted by "rodrigc (via GitHub)" <gi...@apache.org>.
rodrigc commented on PR #1530:
URL: https://github.com/apache/iceberg-python/pull/1530#issuecomment-2597351863
@pawamoy I submitted a separate PR: https://github.com/apache/iceberg-python/pull/1531 to remove `check-docstring-first`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs: Add docstrings for Identifier, Properties, RecursiveDict [iceberg-python]
Posted by "rodrigc (via GitHub)" <gi...@apache.org>.
rodrigc commented on PR #1530:
URL: https://github.com/apache/iceberg-python/pull/1530#issuecomment-2603011752
@Fokko is this PR OK land?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs: Add docstrings for Identifier, Properties, RecursiveDict [iceberg-python]
Posted by "rodrigc (via GitHub)" <gi...@apache.org>.
rodrigc commented on PR #1530:
URL: https://github.com/apache/iceberg-python/pull/1530#issuecomment-2597332238
I see what you are saying. It looks like this issue has come up before:
https://github.com/pre-commit/pre-commit-hooks/issues/159
This project chose to remove the check-docstring-first pre-commit hook:
https://github.com/tiacsys/verylittlewire/commit/07b2cd225524308a2e158bafbc48b7e0fd712e49
Do you suggest that pyiceberg do the same?
Should that sort of change be done in a separate PR, or can it be combined with this one?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs: Add docstrings for Identifier, Properties, RecursiveDict [iceberg-python]
Posted by "pawamoy (via GitHub)" <gi...@apache.org>.
pawamoy commented on PR #1530:
URL: https://github.com/apache/iceberg-python/pull/1530#issuecomment-2597266654
Docstrings must definitely be written *below* attribute assignments for mkdocstrings to pick them up. I'd recommend disabling this lint rule as it apparently doesn't support code with several docstrings at module top-level.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs: Add docstrings for Identifier, Properties, RecursiveDict [iceberg-python]
Posted by "kevinjqliu (via GitHub)" <gi...@apache.org>.
kevinjqliu commented on PR #1530:
URL: https://github.com/apache/iceberg-python/pull/1530#issuecomment-2598837296
Looks like #1531 is merged, could you rebase this PR?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs: Add docstrings for Identifier, Properties, RecursiveDict [iceberg-python]
Posted by "rodrigc (via GitHub)" <gi...@apache.org>.
rodrigc commented on PR #1530:
URL: https://github.com/apache/iceberg-python/pull/1530#issuecomment-2598877837





--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs: Add docstrings for Identifier, Properties, RecursiveDict [iceberg-python]
Posted by "Fokko (via GitHub)" <gi...@apache.org>.
Fokko merged PR #1530:
URL: https://github.com/apache/iceberg-python/pull/1530
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs: Add docstrings for Identifier, Properties, RecursiveDict [iceberg-python]
Posted by "kevinjqliu (via GitHub)" <gi...@apache.org>.
kevinjqliu commented on code in PR #1530:
URL: https://github.com/apache/iceberg-python/pull/1530#discussion_r1919407904
##########
pyiceberg/typedef.py:
##########
@@ -74,8 +74,14 @@ def __missing__(self, key: K) -> V:
Identifier = Tuple[str, ...]
+"""Type for identifiers in PyIceberg."""
Review Comment:
Since the hyperlink will show this docstring, lets add something more descriptive.
Perhaps something like
```
Identifier = Tuple[str, ...]
"""A tuple of strings representing a table identifier.
Each string in the tuple represents a part of the table's unique path. For example,
a table in a namespace might be identified as:
("namespace", "table_name")
Examples:
>>> identifier: Identifier = ("namespace", "table_name")
"""
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs: Add docstrings for Identifier, Properties, RecursiveDict [iceberg-python]
Posted by "kevinjqliu (via GitHub)" <gi...@apache.org>.
kevinjqliu commented on PR #1530:
URL: https://github.com/apache/iceberg-python/pull/1530#issuecomment-2598884049
Amazing, thank you!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] docs: Add docstrings for Identifier, Properties, RecursiveDict [iceberg-python]
Posted by "kevinjqliu (via GitHub)" <gi...@apache.org>.
kevinjqliu commented on PR #1530:
URL: https://github.com/apache/iceberg-python/pull/1530#issuecomment-2598860604
Could you add some screenshots to the PR description showing the hyperlink?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org