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

   ![a](https://github.com/user-attachments/assets/172fe989-5fe7-4412-81c2-72e0cabf656f)
   ![b](https://github.com/user-attachments/assets/49ac4a80-80e6-4b2c-af6e-e8e7447b7ff2)
   ![c](https://github.com/user-attachments/assets/7bac8826-4c53-4803-a943-2fe0ac8188b2)
   ![d](https://github.com/user-attachments/assets/46b92bfe-b222-4b33-a2c9-6abe886b99e3)
   ![e](https://github.com/user-attachments/assets/306f235e-5b39-495f-a82b-a588a7cf6cc1)
   
   


-- 
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