You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by "danepitkin (via GitHub)" <gi...@apache.org> on 2023/04/04 20:03:00 UTC
[GitHub] [arrow] danepitkin opened a new pull request, #34894: GH-34868: [Python] Share docstrings between classes
danepitkin opened a new pull request, #34894:
URL: https://github.com/apache/arrow/pull/34894
### Rationale for this change
Python classes sometimes duplicate docstrings, but change one word such as class name. Add a decorator function as a utility to help deduplicate docstring descriptions. Only works in Python. Does not work in Cython due to this CPython issue https://github.com/python/cpython/issues/91309.
### What changes are included in this PR?
Add a decorator `@doc` that can copy, concatenate, and/or format docstrings between classes.
### Are these changes tested?
Tests added.
```
>>> import pyarrow
>>> from pyarrow.filesystem import FileSystem, LocalFileSystem, DaskFileSystem, S3FSWrapper
>>> from pyarrow.hdfs import HadoopFileSystem
>>> for fs in [FileSystem, LocalFileSystem, DaskFileSystem, S3FSWrapper, HadoopFileSystem]:
... print(fs.__name__)
... print(fs.isdir.__doc__)
...
FileSystem
Return True if path is a directory.
Parameters
----------
path : str
Path to check.
LocalFileSystem
Return True if path is a directory.
Parameters
----------
path : str
Path to check.
DaskFileSystem
Return True if path is a directory.
Parameters
----------
path : str
Path to check.
S3FSWrapper
Return True if path is a directory.
Parameters
----------
path : str
Path to check.
HadoopFileSystem
Return True if path is a directory.
Parameters
----------
path : str
Path to check.
```
Note that `FileSystem.isdir.__doc__` is not dedented because it does not use the `@doc` decorator.
### Are there any user-facing changes?
No
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] danepitkin commented on a diff in pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "danepitkin (via GitHub)" <gi...@apache.org>.
danepitkin commented on code in PR #34894:
URL: https://github.com/apache/arrow/pull/34894#discussion_r1160106181
##########
python/pyarrow/types.py:
##########
@@ -407,155 +223,71 @@ def is_unicode(t):
return is_string(t)
+@doc(is_null, datatype="string (utf8 unicode)")
def is_string(t):
- """
- Return True if value is an instance of string (utf8 unicode) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_STRING
+@doc(is_unicode, method="is_large_string")
def is_large_unicode(t):
- """
- Alias for is_large_string.
-
- Parameters
- ----------
- t : DataType
- """
return is_large_string(t)
+@doc(is_null, datatype="large string (utf8 unicode)")
def is_large_string(t):
- """
- Return True if value is an instance of large string (utf8 unicode) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_LARGE_STRING
+@doc(is_null, datatype="fixed size binary")
def is_fixed_size_binary(t):
- """
- Return True if value is an instance of a fixed size binary type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_FIXED_SIZE_BINARY
+@doc(is_null, datatype="date")
def is_date(t):
- """
- Return True if value is an instance of a date type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _DATE_TYPES
+@doc(is_null, datatype="date32 (days)")
def is_date32(t):
- """
- Return True if value is an instance of a date32 (days) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DATE32
+@doc(is_null, datatype="date64 (milliseconds)")
def is_date64(t):
- """
- Return True if value is an instance of a date64 (milliseconds) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DATE64
+@doc(is_null, datatype="logical map")
Review Comment:
The underlying implementation is `@GARROW_TYPE_MAP: A repeated struct logical type.`
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "AlenkaF (via GitHub)" <gi...@apache.org>.
AlenkaF commented on PR #34894:
URL: https://github.com/apache/arrow/pull/34894#issuecomment-1504612159
OK. Well, I do not have much against that (using `dict` or `set` instead of `{}`).
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] github-actions[bot] commented on pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #34894:
URL: https://github.com/apache/arrow/pull/34894#issuecomment-1496525503
* Closes: #34868
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] danepitkin commented on pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "danepitkin (via GitHub)" <gi...@apache.org>.
danepitkin commented on PR #34894:
URL: https://github.com/apache/arrow/pull/34894#issuecomment-1498020010
`arrow/python/pyarrow/types.py` could be a good option! This is the first one that stood out to me, but I haven't yet thoroughly reviewed all python code. Most of the benefit would be in Cython code unfortunately..
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] danepitkin commented on a diff in pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "danepitkin (via GitHub)" <gi...@apache.org>.
danepitkin commented on code in PR #34894:
URL: https://github.com/apache/arrow/pull/34894#discussion_r1160100765
##########
python/pyarrow/types.py:
##########
@@ -407,155 +223,71 @@ def is_unicode(t):
return is_string(t)
+@doc(is_null, datatype="string (utf8 unicode)")
def is_string(t):
- """
- Return True if value is an instance of string (utf8 unicode) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_STRING
+@doc(is_unicode, method="is_large_string")
def is_large_unicode(t):
- """
- Alias for is_large_string.
-
- Parameters
- ----------
- t : DataType
- """
return is_large_string(t)
+@doc(is_null, datatype="large string (utf8 unicode)")
def is_large_string(t):
- """
- Return True if value is an instance of large string (utf8 unicode) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_LARGE_STRING
+@doc(is_null, datatype="fixed size binary")
def is_fixed_size_binary(t):
- """
- Return True if value is an instance of a fixed size binary type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_FIXED_SIZE_BINARY
+@doc(is_null, datatype="date")
def is_date(t):
- """
- Return True if value is an instance of a date type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _DATE_TYPES
+@doc(is_null, datatype="date32 (days)")
def is_date32(t):
- """
- Return True if value is an instance of a date32 (days) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DATE32
+@doc(is_null, datatype="date64 (milliseconds)")
def is_date64(t):
- """
- Return True if value is an instance of a date64 (milliseconds) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DATE64
+@doc(is_null, datatype="logical map")
Review Comment:
Do we want to keep "logical" in `logical map`?
##########
python/pyarrow/types.py:
##########
@@ -54,351 +56,165 @@ def is_null(t):
return t.id == lib.Type_NA
+@doc(is_null, datatype="boolean")
def is_boolean(t):
- """
- Return True if value is an instance of a boolean type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_BOOL
+@doc(is_null, datatype="integer")
def is_integer(t):
- """
- Return True if value is an instance of any integer type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _INTEGER_TYPES
+@doc(is_null, datatype="signed integer")
def is_signed_integer(t):
- """
- Return True if value is an instance of any signed integer type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _SIGNED_INTEGER_TYPES
+@doc(is_null, datatype="unsigned integer")
def is_unsigned_integer(t):
- """
- Return True if value is an instance of any unsigned integer type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _UNSIGNED_INTEGER_TYPES
+@doc(is_null, datatype="int8")
def is_int8(t):
- """
- Return True if value is an instance of an int8 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_INT8
+@doc(is_null, datatype="int16")
def is_int16(t):
- """
- Return True if value is an instance of an int16 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_INT16
+@doc(is_null, datatype="int32")
def is_int32(t):
- """
- Return True if value is an instance of an int32 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_INT32
+@doc(is_null, datatype="int64")
def is_int64(t):
- """
- Return True if value is an instance of an int64 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_INT64
+@doc(is_null, datatype="uint8")
def is_uint8(t):
- """
- Return True if value is an instance of an uint8 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_UINT8
+@doc(is_null, datatype="uint16")
def is_uint16(t):
- """
- Return True if value is an instance of an uint16 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_UINT16
+@doc(is_null, datatype="uint32")
def is_uint32(t):
- """
- Return True if value is an instance of an uint32 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_UINT32
+@doc(is_null, datatype="uint64")
def is_uint64(t):
- """
- Return True if value is an instance of an uint64 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_UINT64
+@doc(is_null, datatype="floating point numeric")
def is_floating(t):
- """
- Return True if value is an instance of a floating point numeric type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _FLOATING_TYPES
+@doc(is_null, datatype="float16 (half-precision)")
def is_float16(t):
- """
- Return True if value is an instance of a float16 (half-precision) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_HALF_FLOAT
+@doc(is_null, datatype="float32 (single precision)")
def is_float32(t):
- """
- Return True if value is an instance of a float32 (single precision) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_FLOAT
+@doc(is_null, datatype="float64 (double precision)")
def is_float64(t):
- """
- Return True if value is an instance of a float64 (double precision) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DOUBLE
+@doc(is_null, datatype="list")
def is_list(t):
- """
- Return True if value is an instance of a list type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_LIST
+@doc(is_null, datatype="large list")
def is_large_list(t):
- """
- Return True if value is an instance of a large list type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_LARGE_LIST
+@doc(is_null, datatype="fixed size list")
def is_fixed_size_list(t):
- """
- Return True if value is an instance of a fixed size list type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_FIXED_SIZE_LIST
+@doc(is_null, datatype="struct")
def is_struct(t):
- """
- Return True if value is an instance of a struct type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_STRUCT
+@doc(is_null, datatype="union")
def is_union(t):
- """
- Return True if value is an instance of a union type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _UNION_TYPES
+@doc(is_null, datatype="nested")
Review Comment:
Do we like `nested` or `nested type`?
##########
python/pyarrow/types.py:
##########
@@ -407,155 +223,71 @@ def is_unicode(t):
return is_string(t)
+@doc(is_null, datatype="string (utf8 unicode)")
def is_string(t):
- """
- Return True if value is an instance of string (utf8 unicode) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_STRING
+@doc(is_unicode, method="is_large_string")
def is_large_unicode(t):
- """
- Alias for is_large_string.
-
- Parameters
- ----------
- t : DataType
- """
return is_large_string(t)
+@doc(is_null, datatype="large string (utf8 unicode)")
def is_large_string(t):
- """
- Return True if value is an instance of large string (utf8 unicode) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_LARGE_STRING
+@doc(is_null, datatype="fixed size binary")
def is_fixed_size_binary(t):
- """
- Return True if value is an instance of a fixed size binary type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_FIXED_SIZE_BINARY
+@doc(is_null, datatype="date")
def is_date(t):
- """
- Return True if value is an instance of a date type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _DATE_TYPES
+@doc(is_null, datatype="date32 (days)")
def is_date32(t):
- """
- Return True if value is an instance of a date32 (days) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DATE32
+@doc(is_null, datatype="date64 (milliseconds)")
def is_date64(t):
- """
- Return True if value is an instance of a date64 (milliseconds) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DATE64
+@doc(is_null, datatype="logical map")
def is_map(t):
- """
- Return True if value is an instance of a map logical type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_MAP
+@doc(is_null, datatype="decimal")
def is_decimal(t):
- """
- Return True if value is an instance of a decimal type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _DECIMAL_TYPES
+@doc(is_null, datatype="decimal128")
def is_decimal128(t):
- """
- Return True if value is an instance of a decimal type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DECIMAL128
+@doc(is_null, datatype="decimal256")
Review Comment:
Added "256" to `decimal256` here.
##########
python/pyarrow/types.py:
##########
@@ -407,155 +223,71 @@ def is_unicode(t):
return is_string(t)
+@doc(is_null, datatype="string (utf8 unicode)")
def is_string(t):
- """
- Return True if value is an instance of string (utf8 unicode) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_STRING
+@doc(is_unicode, method="is_large_string")
def is_large_unicode(t):
- """
- Alias for is_large_string.
-
- Parameters
- ----------
- t : DataType
- """
return is_large_string(t)
+@doc(is_null, datatype="large string (utf8 unicode)")
def is_large_string(t):
- """
- Return True if value is an instance of large string (utf8 unicode) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_LARGE_STRING
+@doc(is_null, datatype="fixed size binary")
def is_fixed_size_binary(t):
- """
- Return True if value is an instance of a fixed size binary type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_FIXED_SIZE_BINARY
+@doc(is_null, datatype="date")
def is_date(t):
- """
- Return True if value is an instance of a date type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _DATE_TYPES
+@doc(is_null, datatype="date32 (days)")
def is_date32(t):
- """
- Return True if value is an instance of a date32 (days) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DATE32
+@doc(is_null, datatype="date64 (milliseconds)")
def is_date64(t):
- """
- Return True if value is an instance of a date64 (milliseconds) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DATE64
+@doc(is_null, datatype="logical map")
def is_map(t):
- """
- Return True if value is an instance of a map logical type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_MAP
+@doc(is_null, datatype="decimal")
def is_decimal(t):
- """
- Return True if value is an instance of a decimal type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _DECIMAL_TYPES
+@doc(is_null, datatype="decimal128")
def is_decimal128(t):
- """
- Return True if value is an instance of a decimal type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DECIMAL128
+@doc(is_null, datatype="decimal256")
def is_decimal256(t):
- """
- Return True if value is an instance of a decimal type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DECIMAL256
+@doc(is_null, datatype="dictionary-encoded")
def is_dictionary(t):
- """
- Return True if value is an instance of a dictionary-encoded type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DICTIONARY
+@doc(is_null, datatype="interval")
def is_interval(t):
- """
- Return True if the value is an instance of an interval type.
-
- Parameters
- ----------
- t : DateType
- """
return t.id == lib.Type_INTERVAL_MONTH_DAY_NANO
+@doc(is_null, datatype="primitive")
Review Comment:
Do we like `primitive` or `primitive type` better?
##########
python/pyarrow/types.py:
##########
@@ -407,155 +223,71 @@ def is_unicode(t):
return is_string(t)
+@doc(is_null, datatype="string (utf8 unicode)")
def is_string(t):
- """
- Return True if value is an instance of string (utf8 unicode) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_STRING
+@doc(is_unicode, method="is_large_string")
def is_large_unicode(t):
- """
- Alias for is_large_string.
-
- Parameters
- ----------
- t : DataType
- """
return is_large_string(t)
+@doc(is_null, datatype="large string (utf8 unicode)")
def is_large_string(t):
- """
- Return True if value is an instance of large string (utf8 unicode) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_LARGE_STRING
+@doc(is_null, datatype="fixed size binary")
def is_fixed_size_binary(t):
- """
- Return True if value is an instance of a fixed size binary type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_FIXED_SIZE_BINARY
+@doc(is_null, datatype="date")
def is_date(t):
- """
- Return True if value is an instance of a date type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _DATE_TYPES
+@doc(is_null, datatype="date32 (days)")
def is_date32(t):
- """
- Return True if value is an instance of a date32 (days) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DATE32
+@doc(is_null, datatype="date64 (milliseconds)")
def is_date64(t):
- """
- Return True if value is an instance of a date64 (milliseconds) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DATE64
+@doc(is_null, datatype="logical map")
def is_map(t):
- """
- Return True if value is an instance of a map logical type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_MAP
+@doc(is_null, datatype="decimal")
def is_decimal(t):
- """
- Return True if value is an instance of a decimal type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _DECIMAL_TYPES
+@doc(is_null, datatype="decimal128")
Review Comment:
Added "128" to `decimal128` here.
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] danepitkin commented on a diff in pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "danepitkin (via GitHub)" <gi...@apache.org>.
danepitkin commented on code in PR #34894:
URL: https://github.com/apache/arrow/pull/34894#discussion_r1160104485
##########
python/pyarrow/types.py:
##########
@@ -54,351 +56,165 @@ def is_null(t):
return t.id == lib.Type_NA
+@doc(is_null, datatype="boolean")
def is_boolean(t):
- """
- Return True if value is an instance of a boolean type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_BOOL
+@doc(is_null, datatype="integer")
def is_integer(t):
- """
- Return True if value is an instance of any integer type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _INTEGER_TYPES
+@doc(is_null, datatype="signed integer")
def is_signed_integer(t):
- """
- Return True if value is an instance of any signed integer type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _SIGNED_INTEGER_TYPES
+@doc(is_null, datatype="unsigned integer")
def is_unsigned_integer(t):
- """
- Return True if value is an instance of any unsigned integer type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _UNSIGNED_INTEGER_TYPES
+@doc(is_null, datatype="int8")
def is_int8(t):
- """
- Return True if value is an instance of an int8 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_INT8
+@doc(is_null, datatype="int16")
def is_int16(t):
- """
- Return True if value is an instance of an int16 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_INT16
+@doc(is_null, datatype="int32")
def is_int32(t):
- """
- Return True if value is an instance of an int32 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_INT32
+@doc(is_null, datatype="int64")
def is_int64(t):
- """
- Return True if value is an instance of an int64 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_INT64
+@doc(is_null, datatype="uint8")
def is_uint8(t):
- """
- Return True if value is an instance of an uint8 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_UINT8
+@doc(is_null, datatype="uint16")
def is_uint16(t):
- """
- Return True if value is an instance of an uint16 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_UINT16
+@doc(is_null, datatype="uint32")
def is_uint32(t):
- """
- Return True if value is an instance of an uint32 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_UINT32
+@doc(is_null, datatype="uint64")
def is_uint64(t):
- """
- Return True if value is an instance of an uint64 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_UINT64
+@doc(is_null, datatype="floating point numeric")
def is_floating(t):
- """
- Return True if value is an instance of a floating point numeric type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _FLOATING_TYPES
+@doc(is_null, datatype="float16 (half-precision)")
def is_float16(t):
- """
- Return True if value is an instance of a float16 (half-precision) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_HALF_FLOAT
+@doc(is_null, datatype="float32 (single precision)")
def is_float32(t):
- """
- Return True if value is an instance of a float32 (single precision) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_FLOAT
+@doc(is_null, datatype="float64 (double precision)")
def is_float64(t):
- """
- Return True if value is an instance of a float64 (double precision) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DOUBLE
+@doc(is_null, datatype="list")
def is_list(t):
- """
- Return True if value is an instance of a list type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_LIST
+@doc(is_null, datatype="large list")
def is_large_list(t):
- """
- Return True if value is an instance of a large list type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_LARGE_LIST
+@doc(is_null, datatype="fixed size list")
def is_fixed_size_list(t):
- """
- Return True if value is an instance of a fixed size list type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_FIXED_SIZE_LIST
+@doc(is_null, datatype="struct")
def is_struct(t):
- """
- Return True if value is an instance of a struct type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_STRUCT
+@doc(is_null, datatype="union")
def is_union(t):
- """
- Return True if value is an instance of a union type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _UNION_TYPES
+@doc(is_null, datatype="nested")
Review Comment:
I chose `nested type` since it's describing where the type comes from.
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] jorisvandenbossche commented on pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "jorisvandenbossche (via GitHub)" <gi...@apache.org>.
jorisvandenbossche commented on PR #34894:
URL: https://github.com/apache/arrow/pull/34894#issuecomment-1507109050
> If it's a doctest, we would need to replace `{}` with an equivalent like `dict()` or `set()`. If it's part of the descriptions, it can be escaped e.g. `{{}}`
I think also in a doctest you can use the `{{ .. }}` escape approach?
(and to be clear, the current PR doesn't run into that, right? It's only for when we would want to use it more broadly for docstrings with examples?)
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] danepitkin commented on a diff in pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "danepitkin (via GitHub)" <gi...@apache.org>.
danepitkin commented on code in PR #34894:
URL: https://github.com/apache/arrow/pull/34894#discussion_r1160104485
##########
python/pyarrow/types.py:
##########
@@ -54,351 +56,165 @@ def is_null(t):
return t.id == lib.Type_NA
+@doc(is_null, datatype="boolean")
def is_boolean(t):
- """
- Return True if value is an instance of a boolean type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_BOOL
+@doc(is_null, datatype="integer")
def is_integer(t):
- """
- Return True if value is an instance of any integer type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _INTEGER_TYPES
+@doc(is_null, datatype="signed integer")
def is_signed_integer(t):
- """
- Return True if value is an instance of any signed integer type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _SIGNED_INTEGER_TYPES
+@doc(is_null, datatype="unsigned integer")
def is_unsigned_integer(t):
- """
- Return True if value is an instance of any unsigned integer type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _UNSIGNED_INTEGER_TYPES
+@doc(is_null, datatype="int8")
def is_int8(t):
- """
- Return True if value is an instance of an int8 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_INT8
+@doc(is_null, datatype="int16")
def is_int16(t):
- """
- Return True if value is an instance of an int16 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_INT16
+@doc(is_null, datatype="int32")
def is_int32(t):
- """
- Return True if value is an instance of an int32 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_INT32
+@doc(is_null, datatype="int64")
def is_int64(t):
- """
- Return True if value is an instance of an int64 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_INT64
+@doc(is_null, datatype="uint8")
def is_uint8(t):
- """
- Return True if value is an instance of an uint8 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_UINT8
+@doc(is_null, datatype="uint16")
def is_uint16(t):
- """
- Return True if value is an instance of an uint16 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_UINT16
+@doc(is_null, datatype="uint32")
def is_uint32(t):
- """
- Return True if value is an instance of an uint32 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_UINT32
+@doc(is_null, datatype="uint64")
def is_uint64(t):
- """
- Return True if value is an instance of an uint64 type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_UINT64
+@doc(is_null, datatype="floating point numeric")
def is_floating(t):
- """
- Return True if value is an instance of a floating point numeric type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _FLOATING_TYPES
+@doc(is_null, datatype="float16 (half-precision)")
def is_float16(t):
- """
- Return True if value is an instance of a float16 (half-precision) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_HALF_FLOAT
+@doc(is_null, datatype="float32 (single precision)")
def is_float32(t):
- """
- Return True if value is an instance of a float32 (single precision) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_FLOAT
+@doc(is_null, datatype="float64 (double precision)")
def is_float64(t):
- """
- Return True if value is an instance of a float64 (double precision) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DOUBLE
+@doc(is_null, datatype="list")
def is_list(t):
- """
- Return True if value is an instance of a list type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_LIST
+@doc(is_null, datatype="large list")
def is_large_list(t):
- """
- Return True if value is an instance of a large list type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_LARGE_LIST
+@doc(is_null, datatype="fixed size list")
def is_fixed_size_list(t):
- """
- Return True if value is an instance of a fixed size list type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_FIXED_SIZE_LIST
+@doc(is_null, datatype="struct")
def is_struct(t):
- """
- Return True if value is an instance of a struct type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_STRUCT
+@doc(is_null, datatype="union")
def is_union(t):
- """
- Return True if value is an instance of a union type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _UNION_TYPES
+@doc(is_null, datatype="nested")
Review Comment:
I chose `nested type` since it's describing a where the type comes from.
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] danepitkin commented on pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "danepitkin (via GitHub)" <gi...@apache.org>.
danepitkin commented on PR #34894:
URL: https://github.com/apache/arrow/pull/34894#issuecomment-1503979067
> Thanks so much for the updates, the optimisation in the types.py looks great! 👏
>
> > One interesting limitation is if there are docstrings that use curly braces `{}`. If it's a doctest, we would need to replace `{}` with an equivalent like `dict()` or `set()`. If it's part of the descriptions, it can be escaped e.g. `{{}}`
>
> Oh, this is not ideal. What exactly happens in the case where the examples use curly braces? Does this happen often?
If the example uses curly braces, pyarrow will throw a runtime error:
```
@doc(is_null, datatype="primitive type")
def is_primitive(t):
"""
Example
>>> pydict = {"cat": 0, "dog": 1}
"""
return lib._is_primitive(t.id)
```
```
>>> import pyarrow as pa
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/Users/dane/code/arrow/python/pyarrow/__init__.py", line 288, in <module>
import pyarrow.types as types
File "/Users/dane/code/arrow/python/pyarrow/types.py", line 291, in <module>
@doc(is_null, datatype="primitive type")
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/Users/dane/code/arrow/python/pyarrow/util.py", line 76, in decorator
params_applied = [
^
File "/Users/dane/code/arrow/python/pyarrow/util.py", line 77, in <listcomp>
component.format(**params)
KeyError: '"cat"'
```
The fix would be to replace them like this:
```
>>> pydict = dict("cat": 0, "dog": 1)
```
This mostly shows up in Cython docstrings, which are not applicable at the moment!
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] ursabot commented on pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "ursabot (via GitHub)" <gi...@apache.org>.
ursabot commented on PR #34894:
URL: https://github.com/apache/arrow/pull/34894#issuecomment-1519690196
Benchmark runs are scheduled for baseline = f4bd43d28eae13a48d5225ea44a16646ef093155 and contender = cd14e2019ce93e1d6ffadc2556cc4275eeadd9f2. cd14e2019ce93e1d6ffadc2556cc4275eeadd9f2 is a master commit associated with this PR. Results will be available as each benchmark for each run completes.
Conbench compare runs links:
[Finished :arrow_down:0.0% :arrow_up:0.0%] [ec2-t3-xlarge-us-east-2](https://conbench.ursa.dev/compare/runs/7b126dc7e5114c0f863233c98c90efa3...a9d65838ff0d4598ae1b31bde909796c/)
[Failed] [test-mac-arm](https://conbench.ursa.dev/compare/runs/ae5cd72d2c754fb3ad59dcebe261ec1a...fc0946e0e0ba4ab593baaa828a1c7237/)
[Finished :arrow_down:0.26% :arrow_up:0.0%] [ursa-i9-9960x](https://conbench.ursa.dev/compare/runs/4a27255bc87b4187992365743224ec34...eb72e243ef36433a833d151e62f3b315/)
[Finished :arrow_down:0.75% :arrow_up:0.12%] [ursa-thinkcentre-m75q](https://conbench.ursa.dev/compare/runs/c1e220877ff04ea5a26d29526d31683c...e409ead015ca40e6ab907eecc1aef007/)
Buildkite builds:
[Finished] [`cd14e201` ec2-t3-xlarge-us-east-2](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ec2-t3-xlarge-us-east-2/builds/2772)
[Failed] [`cd14e201` test-mac-arm](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-test-mac-arm/builds/2806)
[Finished] [`cd14e201` ursa-i9-9960x](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-i9-9960x/builds/2770)
[Finished] [`cd14e201` ursa-thinkcentre-m75q](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-thinkcentre-m75q/builds/2797)
[Finished] [`f4bd43d2` ec2-t3-xlarge-us-east-2](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ec2-t3-xlarge-us-east-2/builds/2771)
[Failed] [`f4bd43d2` test-mac-arm](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-test-mac-arm/builds/2805)
[Finished] [`f4bd43d2` ursa-i9-9960x](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-i9-9960x/builds/2769)
[Finished] [`f4bd43d2` ursa-thinkcentre-m75q](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-thinkcentre-m75q/builds/2796)
Supported benchmarks:
ec2-t3-xlarge-us-east-2: Supported benchmark langs: Python, R. Runs only benchmarks with cloud = True
test-mac-arm: Supported benchmark langs: C++, Python, R
ursa-i9-9960x: Supported benchmark langs: Python, R, JavaScript
ursa-thinkcentre-m75q: Supported benchmark langs: C++, Java
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF merged pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "AlenkaF (via GitHub)" <gi...@apache.org>.
AlenkaF merged PR #34894:
URL: https://github.com/apache/arrow/pull/34894
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] danepitkin commented on pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "danepitkin (via GitHub)" <gi...@apache.org>.
danepitkin commented on PR #34894:
URL: https://github.com/apache/arrow/pull/34894#issuecomment-1500292554
I applied `@doc` to the types.py!
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] danepitkin commented on pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "danepitkin (via GitHub)" <gi...@apache.org>.
danepitkin commented on PR #34894:
URL: https://github.com/apache/arrow/pull/34894#issuecomment-1500555404
One interesting limitation is if there are docstrings that use curly braces `{}`. If it's a doctest, we would need to replace `{}` with an equivalent like `dict()` or `set()`. If it's part of the descriptions, it can be escaped e.g. `{{}}`
example:
```
Examples
--------
>>> import pyarrow as pa
>>> import pandas as pd
>>> df = pd.DataFrame({'year': [2020, 2022, 2019, 2021],
... 'n_legs': [2, 4, 5, 100],
... 'animals': ["Flamingo", "Horse", "Brittle stars", "Centipede"]})
```
vs.
```
Examples
--------
>>> import pyarrow as pa
>>> import pandas as pd
>>> df = pd.DataFrame(dict('year': [2020, 2022, 2019, 2021],
... 'n_legs': [2, 4, 5, 100],
... 'animals': ["Flamingo", "Horse", "Brittle stars", "Centipede"]))
```
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] danepitkin commented on pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "danepitkin (via GitHub)" <gi...@apache.org>.
danepitkin commented on PR #34894:
URL: https://github.com/apache/arrow/pull/34894#issuecomment-1499422391
Updated `types.py`:
```
>>> import pyarrow
>>> from pyarrow.types import *
>>> print(is_null.__doc__)
Return True if value is an instance of type: null.
Parameters
----------
t : DataType
>>> print(is_boolean.__doc__)
Return True if value is an instance of type: boolean.
Parameters
----------
t : DataType
>>> print(is_map.__doc__)
Return True if value is an instance of type: logical map.
Parameters
----------
t : DataType
>>> print(is_unicode.__doc__)
Alias for is_string.
Parameters
----------
t : DataType
>>> print(is_large_unicode.__doc__)
Alias for is_large_string.
Parameters
----------
t : DataType
```
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] github-actions[bot] commented on pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #34894:
URL: https://github.com/apache/arrow/pull/34894#issuecomment-1496525561
:warning: GitHub issue #34868 **has been automatically assigned in GitHub** to PR creator.
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] jorisvandenbossche commented on a diff in pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "jorisvandenbossche (via GitHub)" <gi...@apache.org>.
jorisvandenbossche commented on code in PR #34894:
URL: https://github.com/apache/arrow/pull/34894#discussion_r1165640449
##########
python/pyarrow/types.py:
##########
@@ -54,351 +56,165 @@ def is_null(t):
return t.id == lib.Type_NA
+@doc(is_null, datatype="boolean")
def is_boolean(t):
- """
- Return True if value is an instance of a boolean type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_BOOL
+@doc(is_null, datatype="integer")
Review Comment:
```suggestion
@doc(is_null, datatype="any integer")
```
I would keep the "any" to clearly indicate this is for _any_ integer (i.e. all bitwidths and signed/unsigned)
##########
python/pyarrow/types.py:
##########
@@ -407,155 +223,71 @@ def is_unicode(t):
return is_string(t)
+@doc(is_null, datatype="string (utf8 unicode)")
def is_string(t):
- """
- Return True if value is an instance of string (utf8 unicode) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_STRING
+@doc(is_unicode, method="is_large_string")
def is_large_unicode(t):
- """
- Alias for is_large_string.
-
- Parameters
- ----------
- t : DataType
- """
return is_large_string(t)
+@doc(is_null, datatype="large string (utf8 unicode)")
def is_large_string(t):
- """
- Return True if value is an instance of large string (utf8 unicode) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_LARGE_STRING
+@doc(is_null, datatype="fixed size binary")
def is_fixed_size_binary(t):
- """
- Return True if value is an instance of a fixed size binary type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_FIXED_SIZE_BINARY
+@doc(is_null, datatype="date")
def is_date(t):
- """
- Return True if value is an instance of a date type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _DATE_TYPES
+@doc(is_null, datatype="date32 (days)")
def is_date32(t):
- """
- Return True if value is an instance of a date32 (days) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DATE32
+@doc(is_null, datatype="date64 (milliseconds)")
def is_date64(t):
- """
- Return True if value is an instance of a date64 (milliseconds) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DATE64
+@doc(is_null, datatype="logical map")
Review Comment:
I think we can remove that. We don't have a clear definition of "logical" types in the arrow format spec, and the fact that a map type is basically a list of structs is an implementation detail (and adding "logical" here doesn't help making that clear)
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "AlenkaF (via GitHub)" <gi...@apache.org>.
AlenkaF commented on PR #34894:
URL: https://github.com/apache/arrow/pull/34894#issuecomment-1503049366
Thanks so much for the updates, the optimisation in the types.py looks great! 👏
> One interesting limitation is if there are docstrings that use curly braces `{}`. If it's a doctest, we would need to replace `{}` with an equivalent like `dict()` or `set()`. If it's part of the descriptions, it can be escaped e.g. `{{}}`
Oh, this is not ideal.
What exactly happens in the case where the examples use curly braces? Does this happen often?
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] danepitkin commented on a diff in pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "danepitkin (via GitHub)" <gi...@apache.org>.
danepitkin commented on code in PR #34894:
URL: https://github.com/apache/arrow/pull/34894#discussion_r1167060100
##########
python/pyarrow/types.py:
##########
@@ -54,351 +56,165 @@ def is_null(t):
return t.id == lib.Type_NA
+@doc(is_null, datatype="boolean")
def is_boolean(t):
- """
- Return True if value is an instance of a boolean type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_BOOL
+@doc(is_null, datatype="integer")
Review Comment:
Good call! Will update
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] jorisvandenbossche commented on pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "jorisvandenbossche (via GitHub)" <gi...@apache.org>.
jorisvandenbossche commented on PR #34894:
URL: https://github.com/apache/arrow/pull/34894#issuecomment-1499114897
> Do we know if there are other places in pyarrow that would benefit from it?
I am not sure we have many places that currently are not in cython, and have repetition in docstrings. Looking through our python files, we do already have some manual templating in parquet/core.py, ipc.py or orc.py (eg to share the explanation of certain parameters between multiple docstrings), but I don't know if they would fit this pattern for using `@doc`.
`pyarrow.filesystem` is also deprecated, so that will be removed in a few releases (not that we can't improve the docs with this PR in the meantime). `types.py` indeed looks like the main obvious candidate where this could be useful.
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] danepitkin commented on a diff in pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "danepitkin (via GitHub)" <gi...@apache.org>.
danepitkin commented on code in PR #34894:
URL: https://github.com/apache/arrow/pull/34894#discussion_r1160104046
##########
python/pyarrow/types.py:
##########
@@ -407,155 +223,71 @@ def is_unicode(t):
return is_string(t)
+@doc(is_null, datatype="string (utf8 unicode)")
def is_string(t):
- """
- Return True if value is an instance of string (utf8 unicode) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_STRING
+@doc(is_unicode, method="is_large_string")
def is_large_unicode(t):
- """
- Alias for is_large_string.
-
- Parameters
- ----------
- t : DataType
- """
return is_large_string(t)
+@doc(is_null, datatype="large string (utf8 unicode)")
def is_large_string(t):
- """
- Return True if value is an instance of large string (utf8 unicode) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_LARGE_STRING
+@doc(is_null, datatype="fixed size binary")
def is_fixed_size_binary(t):
- """
- Return True if value is an instance of a fixed size binary type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_FIXED_SIZE_BINARY
+@doc(is_null, datatype="date")
def is_date(t):
- """
- Return True if value is an instance of a date type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _DATE_TYPES
+@doc(is_null, datatype="date32 (days)")
def is_date32(t):
- """
- Return True if value is an instance of a date32 (days) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DATE32
+@doc(is_null, datatype="date64 (milliseconds)")
def is_date64(t):
- """
- Return True if value is an instance of a date64 (milliseconds) type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DATE64
+@doc(is_null, datatype="logical map")
def is_map(t):
- """
- Return True if value is an instance of a map logical type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_MAP
+@doc(is_null, datatype="decimal")
def is_decimal(t):
- """
- Return True if value is an instance of a decimal type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id in _DECIMAL_TYPES
+@doc(is_null, datatype="decimal128")
def is_decimal128(t):
- """
- Return True if value is an instance of a decimal type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DECIMAL128
+@doc(is_null, datatype="decimal256")
def is_decimal256(t):
- """
- Return True if value is an instance of a decimal type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DECIMAL256
+@doc(is_null, datatype="dictionary-encoded")
def is_dictionary(t):
- """
- Return True if value is an instance of a dictionary-encoded type.
-
- Parameters
- ----------
- t : DataType
- """
return t.id == lib.Type_DICTIONARY
+@doc(is_null, datatype="interval")
def is_interval(t):
- """
- Return True if the value is an instance of an interval type.
-
- Parameters
- ----------
- t : DateType
- """
return t.id == lib.Type_INTERVAL_MONTH_DAY_NANO
+@doc(is_null, datatype="primitive")
Review Comment:
I chose `primitive type` since it's describing a family of types.
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] danepitkin commented on pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "danepitkin (via GitHub)" <gi...@apache.org>.
danepitkin commented on PR #34894:
URL: https://github.com/apache/arrow/pull/34894#issuecomment-1508980154
All feedback is applied!
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] danepitkin commented on pull request #34894: GH-34868: [Python] Share docstrings between classes
Posted by "danepitkin (via GitHub)" <gi...@apache.org>.
danepitkin commented on PR #34894:
URL: https://github.com/apache/arrow/pull/34894#issuecomment-1507120380
> > If it's a doctest, we would need to replace `{}` with an equivalent like `dict()` or `set()`. If it's part of the descriptions, it can be escaped e.g. `{{}}`
>
> I think also in a doctest you can use the `{{ .. }}` escape approach?
>
> (and to be clear, the current PR doesn't run into that, right? It's only for when we would want to use it more broadly for docstrings with examples?)
Correct! There are no uses of `{}` in the docstrings of this PR. You can also use `{{ .. }}` for descriptions, but my guess is that doctests would fail if you tried to use it in the code examples. I noticed Pandas usage always uses `dict()` instead of `{{ .. }}` in code examples explicitly, but does use `{{ .. }}` in the descriptions.
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org