Skip to content

Commit

Permalink
docs: fill out more docstrings
Browse files Browse the repository at this point in the history
  • Loading branch information
@cpcloud @kszucs
cpcloud authored and kszucs committed Apr 21, 2023
1 parent fd081a0 commit dc0289c
Show file tree
Hide file tree
Showing 5 changed files with 127 additions and 47 deletions.
32 changes: 24 additions & 8 deletions ibis/expr/types/arrays.py
View file
Expand Up @@ -771,10 +771,7 @@ class ArrayColumn(Column, ArrayValue):


@public
def array(
values: Iterable[V],
type: str | dt.DataType | None = None,
) -> ArrayValue:
def array(values: Iterable[V], type: str | dt.DataType | None = None) -> ArrayValue:
"""Create an array expression.
If the input expressions are all column expressions, then the output will
Expand Down Expand Up @@ -809,13 +806,32 @@ def array(
Examples
--------
Create an array column from column expressions
>>> import ibis
>>> t = ibis.table([('a', 'int64'), ('b', 'int64')], name='t')
>>> result = ibis.array([t.a, t.b])
>>> ibis.options.interactive = True
>>> t = ibis.memtable({'a': [1, 2, 3], 'b': [4, 5, 6]})
>>> ibis.array([t.a, t.b])
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ ArrayColumn() ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int64> │
├──────────────────────┤
│ [1, 4] │
│ [2, 5] │
│ [3, 6] │
└──────────────────────┘
Create an array scalar from Python literals
>>> import ibis
>>> result = ibis.array([1.0, 2.0, 3.0])
>>> ibis.array([1.0, 2.0, 3.0])
[1.0, 2.0, 3.0]
Mixing scalar and column expressions is not allowed
>>> ibis.array([t.a, 1.0])
Traceback (most recent call last):
...
ibis.common.exceptions.IbisTypeError: To create an array column using `array`, all input values must be column expressions.
"""
if all(isinstance(value, Column) for value in values):
return ops.ArrayColumn(values).to_expr()
Expand Down
2 changes: 1 addition & 1 deletion ibis/expr/types/core.py
View file
Expand Up @@ -3,7 +3,7 @@
import contextlib
import os
import webbrowser
from typing import TYPE_CHECKING, Any, Mapping
from typing import TYPE_CHECKING, Any, Mapping, Tuple

import toolz
from public import public
Expand Down
51 changes: 29 additions & 22 deletions ibis/expr/types/logical.py
View file
Expand Up @@ -14,19 +14,15 @@

@public
class BooleanValue(NumericValue):
def ifelse(
self,
true_expr: ir.Value,
false_expr: ir.Value,
) -> ir.Value:
def ifelse(self, true_expr: ir.Value, false_expr: ir.Value) -> ir.Value:
"""Construct a ternary conditional expression.
Parameters
----------
true_expr
Expression to return if `self` evaluates to `True`
false_expr
Expression to return if `self` evaluates to `False`
Expression to return if `self` evaluates to `False` or `NULL`
Returns
-------
Expand All @@ -36,11 +32,19 @@ def ifelse(
Examples
--------
>>> import ibis
>>> t = ibis.table([("is_person", "boolean")], name="t")
>>> expr = t.is_person.ifelse("yes", "no")
>>> print(ibis.impala.compile(expr.name("tmp")))
SELECT if(t0.`is_person`, 'yes', 'no') AS `tmp`
FROM t t0
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"is_person": [True, False, True, None]})
>>> t.is_person.ifelse("yes", "no")
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Where(is_person, 'yes', 'no') ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ string │
├───────────────────────────────┤
│ yes │
│ no │
│ yes │
│ no │
└───────────────────────────────┘
"""
# Result will be the result of promotion of true/false exprs. These
# might be conflicting types; same type resolution as case expressions
Expand All @@ -50,7 +54,6 @@ def ifelse(
def __and__(self, other: BooleanValue) -> BooleanValue:
"""Construct a binary AND conditional expression with `self` and `other`.
Parameters
----------
self
Expand Down Expand Up @@ -99,7 +102,6 @@ def __and__(self, other: BooleanValue) -> BooleanValue:
def __or__(self, other: BooleanValue) -> BooleanValue:
"""Construct a binary OR conditional expression with `self` and `other`.
Parameters
----------
self
Expand Down Expand Up @@ -136,7 +138,6 @@ def __or__(self, other: BooleanValue) -> BooleanValue:
def __xor__(self, other: BooleanValue) -> BooleanValue:
"""Construct a binary XOR conditional expression with `self` and `other`.
Parameters
----------
self
Expand Down Expand Up @@ -198,7 +199,6 @@ def __xor__(self, other: BooleanValue) -> BooleanValue:
def __invert__(self) -> BooleanValue:
"""Construct a unary NOT conditional expression with `self`.
Parameters
----------
self
Expand Down Expand Up @@ -250,7 +250,8 @@ def any(self, where: BooleanValue | None = None) -> BooleanValue:
Returns
-------
Boolean Value
BooleanValue
Whether at least one element is `True`.
Examples
--------
Expand Down Expand Up @@ -279,7 +280,9 @@ def notany(self, where: BooleanValue | None = None) -> BooleanValue:
Returns
-------
Boolean Value
BooleanValue
Whether no elements are `True`.
Examples
--------
>>> import ibis
Expand All @@ -306,8 +309,9 @@ def all(self, where: BooleanValue | None = None) -> BooleanScalar:
Optional filter for the aggregation
Returns
-------
Boolean Value
-------
BooleanValue
Whether all elements are `True`
Examples
--------
Expand Down Expand Up @@ -336,7 +340,8 @@ def notall(self, where: BooleanValue | None = None) -> BooleanScalar:
Returns
-------
Boolean Value
BooleanValue
Whether not all elements are `True`
Examples
--------
Expand All @@ -359,7 +364,8 @@ def cumany(self) -> BooleanColumn:
Returns
-------
BooleanColumns
BooleanColumn
A boolean column with the cumulative `any` aggregate.
Examples
--------
Expand Down Expand Up @@ -397,7 +403,8 @@ def cumall(self) -> BooleanColumn:
Returns
-------
BooleanColumns
BooleanColumn
A boolean column with the cumulative `all` aggregate.
Examples
--------
Expand Down
4 changes: 2 additions & 2 deletions ibis/expr/types/relations.py
View file
Expand Up @@ -2545,6 +2545,8 @@ def cross_join(
>>> from ibis import _
>>> ibis.options.interactive = True
>>> t = ibis.examples.penguins.fetch()
>>> t.count()
344
>>> agg = t.drop("year").agg(s.across(s.numeric(), _.mean()))
>>> expr = t.cross_join(agg)
>>> expr
Expand Down Expand Up @@ -2580,8 +2582,6 @@ def cross_join(
'body_mass_g_right']
>>> expr.count()
344
>>> t.count()
344
"""
op = ops.CrossJoin(
left,
Expand Down
85 changes: 71 additions & 14 deletions ibis/expr/types/structs.py
View file
Expand Up @@ -101,7 +101,6 @@ class StructValue(Value):
Examples
--------
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({'s': [{'a': 1, 'b': 'foo'}, {'a': 3, 'b': None}, None]})
Expand Down Expand Up @@ -198,17 +197,75 @@ def __getitem__(self, name: str) -> ir.Value:
│ NULL │
│ NULL │
└────────┘
>>> t.s['foo_bar']
Traceback (most recent call last):
...
KeyError: 'foo_bar'
"""
if name not in self.names:
raise KeyError(name)
return ops.StructField(self, name).to_expr()

def __setstate__(self, instance_dictionary):
self.__dict__ = instance_dictionary

def __getattr__(self, name: str) -> ir.Value:
"""Extract the `name` field from this struct."""
if name in self.names:
return self.__getitem__(name)
raise AttributeError(name)
"""Extract the `name` field from this struct.
Parameters
----------
name
The name of the field to access.
Returns
-------
Value
An expression with the type of the field being accessed.
Examples
--------
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({'s': [{'a': 1, 'b': 'foo'}, {'a': 3, 'b': None}, None]})
>>> t
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ s ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ struct<a: int64, b: string> │
├─────────────────────────────┤
│ {'a': 1, 'b': 'foo'} │
│ {'a': 3, 'b': None} │
│ NULL │
└─────────────────────────────┘
>>> t.s.a
┏━━━━━━━┓
┃ a ┃
┡━━━━━━━┩
│ int64 │
├───────┤
│ 1 │
│ 3 │
│ NULL │
└───────┘
>>> t.s.b
┏━━━━━━━━┓
┃ b ┃
┡━━━━━━━━┩
│ string │
├────────┤
│ foo │
│ NULL │
│ NULL │
└────────┘
>>> t.s.foo_bar
Traceback (most recent call last):
...
AttributeError: foo_bar
"""
try:
return self[name]
except KeyError:
raise AttributeError(name) from None

@property
def names(self) -> Sequence[str]:
Expand Down Expand Up @@ -241,14 +298,15 @@ def lift(self) -> ir.Table:
--------
>>> import ibis
>>> ibis.options.interactive = True
>>> lines = '''
... {"pos": {"lat": 10.1, "lon": 30.3}}
... {"pos": {"lat": 10.2, "lon": 30.2}}
... {"pos": {"lat": 10.3, "lon": 30.1}}
... '''
>>> with open("/tmp/lines.json", "w") as f:
... _ = f.write(lines)
>>> t = ibis.read_json("/tmp/lines.json")
>>> t = ibis.memtable(
... {
... "pos": [
... {"lat": 10.1, "lon": 30.3},
... {"lat": 10.2, "lon": 30.2},
... {"lat": 10.3, "lon": 30.1},
... ]
... }
... )
>>> t
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ pos ┃
Expand Down Expand Up @@ -293,7 +351,6 @@ def destructure(self) -> list[ir.ValueExpr]:
Examples
--------
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({'s': [{'a': 1, 'b': 'foo'}, {'a': 3, 'b': None}, None]})
Expand Down

0 comments on commit dc0289c

Please sign in to comment.