[GitHub] [arrow] jorisvandenbossche commented on a diff in pull request #12783: ARROW-15431: [Python] Address docstrings in Schema

[GitBox <gi...@apache.org>]

jorisvandenbossche commented on code in PR #12783:
URL: https://github.com/apache/arrow/pull/12783#discussion_r842777634


##########
python/pyarrow/types.pxi:
##########
@@ -1367,6 +1367,28 @@ cdef class Field(_Weakrefable):
 
 
 cdef class Schema(_Weakrefable):
+    """
+    A named collection of types a.k.a schema.
+

Review Comment:
   Can you add a reference to `pa.schema` as the function how to create a Schema object manually? (eg with a "See Also" section)



##########
python/pyarrow/types.pxi:
##########
@@ -1687,6 +1852,15 @@ cdef class Schema(_Weakrefable):
         Returns
         -------
         schema: Schema
+
+        Examples
+        --------
+        >>> import pyarrow as pa
+        >>> schema = pa.schema([
+        ...     pa.field('n_legs', pa.int64()),
+        ...     pa.field('animals', pa.string())])
+        >>> schema.remove(1)

Review Comment:
   ```suggestion
           ...     pa.field('animals', pa.string())])
   
           Remove the second field of the schema:
   
           >>> schema.remove(1)
   ```
   
   (as general feedback point: I would add a bit more this kind of "introduction sentence" briefly stating what the example does)



##########
python/pyarrow/types.pxi:
##########
@@ -1367,6 +1367,28 @@ cdef class Field(_Weakrefable):
 
 
 cdef class Schema(_Weakrefable):
+    """
+    A named collection of types a.k.a schema.

Review Comment:
   I would maybe try to give a bit more detailed description of what a schema is? (eg that it describes the data types of a record batch or table)



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