You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by GitBox <gi...@apache.org> on 2023/01/19 12:27:50 UTC
[GitHub] [arrow] AlenkaF opened a new pull request, #33785: GH-33741: [Python] Address docstrings in Data Types Factory Functions
AlenkaF opened a new pull request, #33785:
URL: https://github.com/apache/arrow/pull/33785
### Rationale for this change
Ensure docstrings for [Data Types Factory Functions](https://arrow.apache.org/docs/python/api/datatypes.html#factory-functions) have an Examples section.
### What changes are included in this PR?
Docstrings are added to listed Data Types Factory Functions.
### Are these changes tested?
Yes, locally with `pytest --doctest-cython --disable-warnings` pyarrow and on the CI with `Python / AMD64 Conda Python 3.9 Sphinx & Numpydoc` build.
### 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] github-actions[bot] commented on pull request #33785: GH-33741: [Python] Address docstrings in Data Types Factory Functions
Posted by GitBox <gi...@apache.org>.
github-actions[bot] commented on PR #33785:
URL: https://github.com/apache/arrow/pull/33785#issuecomment-1396903229
* Closes: #33741
--
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 #33785: GH-33741: [Python] Address docstrings in Data Types Factory Functions
Posted by "danepitkin (via GitHub)" <gi...@apache.org>.
danepitkin commented on code in PR #33785:
URL: https://github.com/apache/arrow/pull/33785#discussion_r1107761340
##########
python/pyarrow/types.pxi:
##########
@@ -2347,69 +2369,260 @@ cdef set PRIMITIVE_TYPES = set([
def null():
"""
Create instance of null type.
+
+ Examples
+ --------
+ Create an instance of a null type:
+
+ >>> import pyarrow as pa
+ >>> pa.null()
+ DataType(null)
+ >>> print(pa.null())
+ null
+
+ Create a ``Field`` type with a null type and a name:
+
+ >>> pa.field('null_field', pa.null())
+ pyarrow.Field<null_field: null>
"""
return primitive_type(_Type_NA)
def bool_():
"""
Create instance of boolean type.
+
+ Examples
+ --------
+ Create an instance of a boolean type:
+
+ >>> import pyarrow as pa
+ >>> pa.bool_()
+ DataType(bool)
+ >>> print(pa.bool_())
+ bool
+
+ Create a ``Field`` type with a boolean type
+ and a name:
+
+ >>> pa.field('null_field', pa.bool_())
+ pyarrow.Field<null_field: bool>
Review Comment:
should we rename `null_field` -> `bool_field`?
--
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 #33785: GH-33741: [Python] Address docstrings in Data Types Factory Functions
Posted by "jorisvandenbossche (via GitHub)" <gi...@apache.org>.
jorisvandenbossche commented on PR #33785:
URL: https://github.com/apache/arrow/pull/33785#issuecomment-1472114433
Thanks!
--
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 #33785: GH-33741: [Python] Address docstrings in Data Types Factory Functions
Posted by "jorisvandenbossche (via GitHub)" <gi...@apache.org>.
jorisvandenbossche commented on code in PR #33785:
URL: https://github.com/apache/arrow/pull/33785#discussion_r1112696114
##########
python/pyarrow/types.pxi:
##########
@@ -2509,6 +2724,16 @@ def timestamp(unit, tz=None):
>>> pa.timestamp('s', tz='+07:30')
TimestampType(timestamp[s, tz=+07:30])
+ Use timestamp type when creating a scalar object:
+
+ >>> from datetime import datetime
+ >>> pa.scalar(datetime(2012, 1, 1),
+ ... type=pa.timestamp('s', tz='+07:30'))
Review Comment:
```suggestion
>>> pa.scalar(datetime(2012, 1, 1), type=pa.timestamp('s', tz='+07:30'))
```
(this fits on a single line for PEP8?)
##########
python/pyarrow/types.pxi:
##########
@@ -2664,41 +2901,145 @@ def month_day_nano_interval():
"""
Create instance of an interval type representing months, days and
nanoseconds between two dates.
+
+ Examples
+ --------
+ Create an instance of an month_day_nano_interval type:
+
+ >>> import pyarrow as pa
+ >>> pa.month_day_nano_interval()
+ DataType(month_day_nano_interval)
+
+ Create a scalar with month_day_nano_interval type:
+
+ >>> pa.scalar((1, 15, -30), type=pa.month_day_nano_interval())
+ <pyarrow.MonthDayNanoIntervalScalar: MonthDayNano(months=1, days=15, nanoseconds=-30)>
"""
return primitive_type(_Type_INTERVAL_MONTH_DAY_NANO)
def date32():
"""
Create instance of 32-bit date (days since UNIX epoch 1970-01-01).
+
+ Examples
+ --------
+ Create an instance of 32-bit date type:
+
+ >>> import pyarrow as pa
+ >>> pa.date32()
+ DataType(date32[day])
+
+ Create a scalar with 32-bit date type:
+
+ >>> from datetime import datetime
+ >>> pa.scalar(datetime(2012, 1, 1), type=pa.date32())
Review Comment:
Do we want to show creating it from `datetime.date` instead? (or in addition)
##########
python/pyarrow/types.pxi:
##########
@@ -2509,6 +2724,16 @@ def timestamp(unit, tz=None):
>>> pa.timestamp('s', tz='+07:30')
TimestampType(timestamp[s, tz=+07:30])
+ Use timestamp type when creating a scalar object:
+
+ >>> from datetime import datetime
+ >>> pa.scalar(datetime(2012, 1, 1),
+ ... type=pa.timestamp('s', tz='+07:30'))
+ <pyarrow.TimestampScalar: datetime.datetime(2012, 1, 1, 7, 30, tzinfo=pytz.FixedOffset(450))>
+ >>> pa.scalar(datetime(2012, 1, 1),
+ ... type=pa.timestamp('us'))
Review Comment:
```suggestion
>>> pa.scalar(datetime(2012, 1, 1), type=pa.timestamp('us'))
```
##########
python/pyarrow/types.pxi:
##########
@@ -2509,6 +2724,16 @@ def timestamp(unit, tz=None):
>>> pa.timestamp('s', tz='+07:30')
TimestampType(timestamp[s, tz=+07:30])
+ Use timestamp type when creating a scalar object:
+
+ >>> from datetime import datetime
+ >>> pa.scalar(datetime(2012, 1, 1),
+ ... type=pa.timestamp('s', tz='+07:30'))
Review Comment:
And I would maybe show a timezone name instead of a fixed offset (in general there are not many reasons to use a fixed offset, I think). Maybe "UTC", to show that that is also an option.
##########
python/pyarrow/types.pxi:
##########
@@ -2914,6 +3454,34 @@ cpdef MapType map_(key_type, item_type, keys_sorted=False):
Returns
-------
map_type : DataType
+
+ Examples
+ --------
+ Create an instance of MapType:
+
+ >>> import pyarrow as pa
+ >>> pa.map_(pa.string(), pa.int32())
+ MapType(map<string, int32>)
+ >>> pa.map_(pa.string(), pa.int32(), keys_sorted=True)
+ MapType(map<string, int32, keys_sorted>)
+
+ Use MapType to create an array:
+
+ >>> data = [[{'key': 'a', 'value': 1}, {'key': 'b', 'value': 2}]]
Review Comment:
```suggestion
>>> data = [[{'key': 'a', 'value': 1}, {'key': 'b', 'value': 2}], [{'key': 'c', 'value': 3}]]
```
By adding a second element of the array, it might be clearer that this is actually like a nested list (where the first element of the map has two key/values mappings, and the second element has one). Currently someone not familiar with the repr might interpret it as an array of length 2
##########
python/pyarrow/types.pxi:
##########
@@ -2810,6 +3237,26 @@ def large_binary():
This data type may not be supported by all Arrow implementations. Unless
you need to represent data larger than 2GB, you should prefer binary().
+
+ Examples
+ --------
+ Create an instance of large variable-length binary type:
+
+ >>> import pyarrow as pa
+ >>> pa.large_binary()
+ DataType(large_binary)
+
+ and use the type to create an array:
+
+ >>> pa.array(['foo', 'bar'] * 50, type=pa.large_binary())
Review Comment:
I don't know if the `* 50` is needed here. I would maybe use the same `['foo', 'bar', 'baz']` as you used above for the normal binary type. The `* 50` might indicate that it is "larger", but at the same time it is still tiny data, so I am not sure that helps.
--
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 #33785: GH-33741: [Python] Address docstrings in Data Types Factory Functions
Posted by "ursabot (via GitHub)" <gi...@apache.org>.
ursabot commented on PR #33785:
URL: https://github.com/apache/arrow/pull/33785#issuecomment-1472434019
Benchmark runs are scheduled for baseline = fe88d9ad5c346786842913c8d2a369db099b5406 and contender = 427f1b649e36ef3c64dd61ed86808463a440eb94. 427f1b649e36ef3c64dd61ed86808463a440eb94 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/3ba17652f4cc4d938983effe7a7034bd...e2e45921c6b84ef4a841005f5d4d07f0/)
[Finished :arrow_down:0.12% :arrow_up:0.03%] [test-mac-arm](https://conbench.ursa.dev/compare/runs/f4098b43b2834a619ea53466e0c54de2...f5b46d91df044acc8a8d2d0d97abb361/)
[Finished :arrow_down:0.0% :arrow_up:0.0%] [ursa-i9-9960x](https://conbench.ursa.dev/compare/runs/875a157a023d4114926a2710847c8f2c...b23af1ff504048f3b15aa49621d8b7ea/)
[Finished :arrow_down:0.09% :arrow_up:0.0%] [ursa-thinkcentre-m75q](https://conbench.ursa.dev/compare/runs/fd3662d05dcc457fbcada269829ada7a...75c3d62ba1534602a493b33071560534/)
Buildkite builds:
[Finished] [`427f1b64` ec2-t3-xlarge-us-east-2](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ec2-t3-xlarge-us-east-2/builds/2531)
[Finished] [`427f1b64` test-mac-arm](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-test-mac-arm/builds/2561)
[Finished] [`427f1b64` ursa-i9-9960x](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-i9-9960x/builds/2529)
[Finished] [`427f1b64` ursa-thinkcentre-m75q](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-thinkcentre-m75q/builds/2552)
[Finished] [`fe88d9ad` ec2-t3-xlarge-us-east-2](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ec2-t3-xlarge-us-east-2/builds/2530)
[Finished] [`fe88d9ad` test-mac-arm](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-test-mac-arm/builds/2560)
[Finished] [`fe88d9ad` ursa-i9-9960x](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-i9-9960x/builds/2528)
[Finished] [`fe88d9ad` ursa-thinkcentre-m75q](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-thinkcentre-m75q/builds/2551)
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] danepitkin commented on a diff in pull request #33785: GH-33741: [Python] Address docstrings in Data Types Factory Functions
Posted by "danepitkin (via GitHub)" <gi...@apache.org>.
danepitkin commented on code in PR #33785:
URL: https://github.com/apache/arrow/pull/33785#discussion_r1107767830
##########
python/pyarrow/types.pxi:
##########
@@ -2664,41 +2901,132 @@ def month_day_nano_interval():
"""
Create instance of an interval type representing months, days and
nanoseconds between two dates.
+
+ Examples
+ --------
+ Create an instance of an month_day_nano_interval type:
+
+ >>> import pyarrow as pa
+ >>> pa.month_day_nano_interval()
+ DataType(month_day_nano_interval)
+
+ Create a scalar with month_day_nano_interval type:
+
+ >>> pa.scalar((1, 15, -30), type=pa.month_day_nano_interval())
+ <pyarrow.MonthDayNanoIntervalScalar: MonthDayNano(months=1, days=15, nanoseconds=-30)>
"""
return primitive_type(_Type_INTERVAL_MONTH_DAY_NANO)
def date32():
"""
Create instance of 32-bit date (days since UNIX epoch 1970-01-01).
+
+ Examples
+ --------
+ Create an instance of 32-bit date type:
+
+ >>> import pyarrow as pa
+ >>> pa.date32()
+ DataType(date32[day])
+
+ Create a scalar with 32-bit date type:
+
+ >>> from datetime import datetime
+ >>> pa.scalar(datetime(2012, 1, 1), type=pa.date32())
+ <pyarrow.Date32Scalar: datetime.date(2012, 1, 1)>
"""
return primitive_type(_Type_DATE32)
def date64():
"""
Create instance of 64-bit date (milliseconds since UNIX epoch 1970-01-01).
+
+ Examples
+ --------
+ Create an instance of 64-bit date type:
+
+ >>> import pyarrow as pa
+ >>> pa.date64()
+ DataType(date64[ms])
+
+ Create a scalar with 64-bit date type:
+
+ >>> from datetime import datetime
+ >>> pa.scalar(datetime(2012, 1, 1), type=pa.date64())
+ <pyarrow.Date64Scalar: datetime.date(2012, 1, 1)>
"""
return primitive_type(_Type_DATE64)
def float16():
"""
Create half-precision floating point type.
+
+ Examples
+ --------
+ Create an instance of float16 type:
+
+ >>> import pyarrow as pa
+ >>> pa.float16()
+ DataType(halffloat)
+ >>> print(pa.float16())
+ halffloat
"""
Review Comment:
Should we create an array with float16 type, too?
--
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 merged pull request #33785: GH-33741: [Python] Address docstrings in Data Types Factory Functions
Posted by "jorisvandenbossche (via GitHub)" <gi...@apache.org>.
jorisvandenbossche merged PR #33785:
URL: https://github.com/apache/arrow/pull/33785
--
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