Add datatypes and exceptions to Python docs (#3499)

py-polars/docs/source/reference/datatypes.rst

@@ -0,0 +1,58 @@
+==========
+Data Types
+==========
+.. currentmodule:: polars.datatypes
+
+.. autosummary::
+    :toctree: api/
+    :nosignatures:
+
+    DataType
+
+Numeric
+~~~~~~~
+.. autosummary::
+    :toctree: api/
+    :nosignatures:
+
+    Float32
+    Float64
+    Int16
+    Int32
+    Int64
+    Int8
+    UInt16
+    UInt32
+    UInt64
+    UInt8
+
+Date / Time
+~~~~~~~~~~~
+.. autosummary::
+    :toctree: api/
+    :nosignatures:
+
+    Date
+    Datetime
+    Duration
+    Time
+
+Nested
+~~~~~~
+.. autosummary::
+    :toctree: api/
+
+    List
+    Struct
+
+Other
+~~~~~
+.. autosummary::
+    :toctree: api/
+    :nosignatures:
+
+    Boolean
+    Categorical
+    Null
+    Object
+    Utf8

py-polars/docs/source/reference/exceptions.rst

@@ -0,0 +1,17 @@
+==========
+Exceptions
+==========
+.. currentmodule:: polars.exceptions
+
+.. autosummary::
+    :toctree: api/
+    :nosignatures:
+
+    ArrowError
+    ComputeError
+    NoDataError
+    NotFoundError
+    SchemaError
+    ShapeError
+    DuplicateError
+    PanicException

py-polars/docs/source/reference/index.rst

@@ -17,3 +17,5 @@ methods. All classes and functions exposed in ``polars.*`` namespace are public.
    lazyframe
    testing
    config
+   datatypes
+   exceptions

py-polars/docs/source/reference/lazyframe.rst

@@ -3,6 +3,11 @@ LazyFrame
 =========
 .. currentmodule:: polars
 
+.. py:class:: LazyFrame
+    :canonical: polars.internals.lazy_frame.LazyFrame
+
+    Representation of a Lazy computation graph/ query.
+
 Attributes
 ----------
 

py-polars/polars/datatypes.py

@@ -20,6 +20,8 @@
 
 
 class DataType:
+    """Base class for all Polars data types"""
+
     @classmethod
     def string_repr(cls) -> str:
         return dtype_str_repr(cls)
@@ -29,59 +31,93 @@ def __repr__(self) -> str:
 
 
 class Int8(DataType):
+    """8-bit signed integer type"""
+
     pass
 
 
 class Int16(DataType):
+    """16-bit signed integer type"""
+
     pass
 
 
 class Int32(DataType):
+    """32-bit signed integer type"""
+
     pass
 
 
 class Int64(DataType):
+    """64-bit signed integer type"""
+
     pass
 
 
 class UInt8(DataType):
+    """8-bit unsigned integer type"""
+
     pass
 
 
 class UInt16(DataType):
+    """16-bit unsigned integer type"""
+
     pass
 
 
 class UInt32(DataType):
+    """32-bit unsigned integer type"""
+
     pass
 
 
 class UInt64(DataType):
+    """64-bit unsigned integer type"""
+
     pass
 
 
 class Float32(DataType):
+    """32-bit floating point type"""
+
     pass
 
 
 class Float64(DataType):
+    """64-bit floating point type"""
+
     pass
 
 
 class Boolean(DataType):
+    """Boolean type"""
+
     pass
 
 
 class Utf8(DataType):
+    """UTF-8 encoded string type"""
+
     pass
 
 
 class Null(DataType):
+    """Type representing Null / None values"""
+
     pass
 
 
 class List(DataType):
     def __init__(self, inner: Type[DataType]):
+        """
+        Nested list/array type
+
+        Parameters
+        ----------
+        inner
+            The `DataType` of values within the list
+        """
         self.inner = py_type_to_dtype(inner)
 
     def __eq__(self, other: Type[DataType]) -> bool:  # type: ignore
@@ -110,31 +146,53 @@ def __hash__(self) -> int:
 
 
 class Date(DataType):
+    """Calendar date type"""
+
     pass
 
 
 class Datetime(DataType):
+    """Calendar date and time type"""
+
     pass
 
 
 class Duration(DataType):
+    """Time duration/delta type"""
+
     pass
 
 
 class Time(DataType):
+    """Time of day type"""
+
     pass
 
 
 class Object(DataType):
+    """Type for wrapping arbitrary Python objects"""
+
     pass
 
 
 class Categorical(DataType):
+    """A categorical encoding of a set of strings"""
+
     pass
 
 
 class Field:
     def __init__(self, name: str, dtype: Type[DataType]):
+        """
+        Definition of a single field within a `Struct` DataType
+
+        Parameters
+        ----------
+        name
+            The name of the field within its parent `Struct`
+        dtype
+            The `DataType` of the field's values
+        """
         self.name = name
         self.dtype = py_type_to_dtype(dtype)
 
@@ -151,6 +209,14 @@ def __repr__(self) -> str:
 
 class Struct(DataType):
     def __init__(self, fields: Sequence[Field]):
+        """
+        Struct composite type
+
+        Parameters
+        ----------
+        fields
+            The sequence of fields that make up the struct
+        """
         self.fields = fields
 
     def __eq__(self, other: Type[DataType]) -> bool:  # type: ignore
@@ -308,4 +374,5 @@ def maybe_cast(
     return el
 
 
+#: Mapping of `~polars.DataFrame` / `~polars.LazyFrame` column names to their `DataType`
 Schema = Dict[str, Type[DataType]]

py-polars/polars/exceptions.py

@@ -14,27 +14,43 @@
     # when there is no binary yet
 
     class ArrowError(Exception):  # type: ignore
+        """Exception raised the underlying Arrow library encounters an error"""
+
         pass
 
     class ComputeError(Exception):  # type: ignore
+        """Exception raised when we couldn't finish the computation"""
+
         pass
 
     class NoDataError(Exception):  # type: ignore
+        """Exception raised when an operation can not be performed on an empty data structure"""
+
         pass
 
     class NotFoundError(Exception):  # type: ignore
+        """Exception raised when a specified column is not found"""
+
         pass
 
     class SchemaError(Exception):  # type: ignore
+        """Exception raised when trying to combine data structures with mismatched schemas"""
+
         pass
 
     class ShapeError(Exception):  # type: ignore
+        """Exception raised when trying to combine data structures with incompatible shapes"""
+
         pass
 
     class DuplicateError(Exception):  # type: ignore
+        """Exception raised when a column name is duplicated"""
+
         pass
 
     class PanicException(Exception):  # type: ignore
+        """Exception raised when an unexpected state causes a panic in the underlying Rust library"""
+
         pass