realed 2026.8__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
realed/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ from .realed import Relation
2
+
3
+ __all__ = ["Relation"]
realed/realed.py ADDED
@@ -0,0 +1,406 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ Implementation of relational algebra operations using pandas
4
+ """
5
+
6
+ import pathlib
7
+
8
+ import pandas as pd
9
+
10
+
11
+ class Relation:
12
+ """Relation that stores tabular data"""
13
+
14
+ def __init__(
15
+ self, data_src: "str | pathlib.Path | Relation | pd.DataFrame | None", *args, **kwargs
16
+ ):
17
+ """Create a new relation either from a CSV file or from another Relation
18
+
19
+ :param data: data source
20
+ :raises ValueError: if the source is empty
21
+ :raises TypeError: if the source cannot be processed
22
+ """
23
+ if isinstance(data_src, str) and pathlib.Path(data_src).suffix == ".csv":
24
+ if not pathlib.Path(data_src).exists():
25
+ raise FileNotFoundError(f"Check the path to {data_src}.")
26
+ self._data = pd.DataFrame(pd.read_csv(data_src, *args, **kwargs))
27
+ elif isinstance(data_src, pathlib.Path) and data_src.suffix == ".csv":
28
+ if not data_src.exists():
29
+ raise FileNotFoundError(f"Check the path to {data_src}.")
30
+ self._data = pd.DataFrame(pd.read_csv(data_src, *args, **kwargs))
31
+ elif isinstance(data_src, (pd.DataFrame, Relation)):
32
+ self._data = data_src.copy().drop_duplicates()
33
+ elif data_src is None:
34
+ raise ValueError(
35
+ "A relation can only be created from a valid source but none was provided."
36
+ )
37
+ else:
38
+ raise TypeError(
39
+ f"A relation can not be created from the provided data source >>{data_src}<<."
40
+ )
41
+
42
+ @property
43
+ def data(self):
44
+ """Data as a property"""
45
+ return self._data
46
+
47
+ @property
48
+ def columns(self):
49
+ """Names of the attributes"""
50
+ return self._data.columns
51
+
52
+ @property
53
+ def dim(self):
54
+ """Return dimensions (rows x columns) of the relation"""
55
+ return len(self._data), len(self._data.columns)
56
+
57
+ @property
58
+ def one(self) -> dict:
59
+ """Return one (first) record of the relation"""
60
+ if len(self._data) == 0:
61
+ raise ValueError("The relation is empty")
62
+ return self._data.iloc[0].to_dict()
63
+
64
+ def __getitem__(self, key):
65
+ """Allow getting a specific attribute"""
66
+ return self._data[key]
67
+
68
+ def __setitem__(self, key, value) -> None:
69
+ """Allow setting a specific attribute"""
70
+ self._data[key] = value
71
+
72
+ def __bool__(self) -> bool:
73
+ """Evaluate the relation as a boolean"""
74
+ return bool(self._data)
75
+
76
+ def __repr__(self) -> str:
77
+ """Represent the relation"""
78
+ return repr(self._data)
79
+
80
+ def __str__(self) -> str:
81
+ """Convert the relation to a string"""
82
+ return str(self._data)
83
+
84
+ def __len__(self) -> int:
85
+ """Get the length of the relation"""
86
+ return len(self._data)
87
+
88
+ def __add__(self, other) -> "Relation":
89
+ """Add two relations"""
90
+ return self.union(other)
91
+
92
+ def __sub__(self, other) -> "Relation":
93
+ """Subtract two relations"""
94
+ return self.minus(other)
95
+
96
+ def __mul__(self, other) -> "Relation":
97
+ """Multiply two relations"""
98
+ return self.product(other)
99
+
100
+ def head(self, n: int = 5):
101
+ """Return the first couple records"""
102
+ return self._data.head(n)
103
+
104
+ def tail(self, n: int = 5):
105
+ """Return the last couple records"""
106
+ return self._data.tail(n)
107
+
108
+ def to_csv(self, filepath):
109
+ """Save the relation to a CSV file"""
110
+ self._data.to_csv(filepath, index=False)
111
+
112
+ def copy(self):
113
+ """Return a deep copy of the relation"""
114
+ return self._data.copy()
115
+
116
+ def cleanup(self):
117
+ """Remove empty (all NA) records from the relation"""
118
+ return Relation(self._data.dropna(how="all"))
119
+
120
+ def equals(self, other) -> bool:
121
+ """Compare two relations for equality"""
122
+ return self._data.equals(other.data)
123
+
124
+ def minus(self, other) -> "Relation":
125
+ """Find the difference between two relations"""
126
+ if not isinstance(other, Relation):
127
+ raise TypeError("Can only find the difference between two relations.")
128
+ return Relation(self._data[~self._data.isin(other.data)]).cleanup()
129
+
130
+ def intersection(self, other):
131
+ """Find the intersection of two relations"""
132
+ if not isinstance(other, Relation):
133
+ raise TypeError("Can only find the intersection of two relations.")
134
+ return Relation(self._data[self._data.isin(other.data)]).cleanup()
135
+
136
+ def query(self, expr, *args, **kwargs):
137
+ """A simple pass-through to the pandas query"""
138
+ return Relation(self._data.query(expr, *args, **kwargs))
139
+
140
+ def select(self, expr: str) -> "Relation":
141
+ """Selection operation of the relational algebra
142
+
143
+ :param expr: query string
144
+ :return: a new relation
145
+ """
146
+ return Relation(self._data.query(expr))
147
+
148
+ def project(self, attributes: list[str]) -> "Relation":
149
+ """Projection operation of the relational algebra
150
+
151
+ :param attributes: a list of attributes to extract
152
+ :raises TypeError: if the argument is not a list
153
+ :raises ValueError: if any attribute is not a valid column name
154
+ :return: a new relation
155
+ """
156
+ if not isinstance(attributes, list):
157
+ raise TypeError("Projection uses a list of attributes as an argument.")
158
+ missing_attributes = set(attributes).difference(set(self._data.columns))
159
+ if len(missing_attributes) > 0:
160
+ raise ValueError(
161
+ f"There are no attributes >>{', '.join(sorted(missing_attributes))}<< in this relation."
162
+ )
163
+ return Relation(self._data[attributes])
164
+
165
+ def rename(self, old_name: str, new_name: str) -> "Relation":
166
+ """Rename operation of the relational algebra
167
+
168
+ :param old_name: old name of an attribute
169
+ :param new_name: new name of an attribute
170
+ :raises ValueError: if the old name is not a valid column name
171
+ :raises ValueError: if the new name is a name of an existing attribute
172
+ :return: a new relation
173
+ """
174
+ if old_name not in self._data.columns:
175
+ raise ValueError(f"There is no attribute >>{old_name}<< in this relation.")
176
+ if new_name in self._data.columns:
177
+ raise ValueError(f"There is already an attribute >>{new_name}<< in this relation.")
178
+ return Relation(self._data.rename(columns={old_name: new_name}))
179
+
180
+ def sort(self, attributes: list[str], *args, **kwargs) -> "Relation":
181
+ """Sorting operation of the relational algebra
182
+
183
+ :param query: attributes to sort by
184
+ :param ascending: default True
185
+ :return: a new relation
186
+ """
187
+ return Relation(self._data.sort_values(attributes, *args, **kwargs))
188
+
189
+ def extend(self, new_attribute: str, new_values: pd.Series) -> "Relation":
190
+ """Extending operation of the relational algebra
191
+
192
+ :param new_attribute: name of the new attribute
193
+ :param new_values: series of values
194
+ :raises ValueError: if the new name is a name of an existing attribute
195
+ :return: a new relation
196
+ """
197
+ if new_attribute in self._data.columns:
198
+ raise ValueError(f"There is already an attribute >>{new_attribute}<< in this relation.")
199
+ new_values.name = new_attribute
200
+ return Relation(pd.concat([self._data, new_values], axis=1))
201
+
202
+ def groupby(self, attributes: list[str]) -> "RelationGroupBy":
203
+ """GroupBy operation of the relational algebra
204
+
205
+ :param query: attributes to group by
206
+ :raises TypeError: if the argument is not a list
207
+ :return: a new relation group by object
208
+
209
+ """
210
+ if not isinstance(attributes, list):
211
+ raise TypeError("Grouping uses a list of attributes as an argument.")
212
+ return self.RelationGroupBy(self._data.groupby(attributes), attributes)
213
+
214
+ class RelationGroupBy:
215
+ """An intermediate grouping object"""
216
+
217
+ def __init__(self, grouping: pd.api.typing.DataFrameGroupBy, attributes: list[str]):
218
+ self.grouping = grouping
219
+ self.attributes = attributes
220
+
221
+ def __repr__(self):
222
+ """Represent the grouping"""
223
+ return str(pd.DataFrame(list(self.grouping.groups.keys()), columns=self.attributes))
224
+
225
+ def __str__(self):
226
+ """Convert the grouping to a string"""
227
+ return str(pd.DataFrame(list(self.grouping.groups.keys()), columns=self.attributes))
228
+
229
+ def count(self, attribute: str):
230
+ """Compute count of group"""
231
+ return Relation(
232
+ self.grouping[attribute].count().to_frame(name=f"count_{attribute}").reset_index()
233
+ )
234
+
235
+ def sum(self, attribute: str):
236
+ """Compute sum of group values"""
237
+ return Relation(
238
+ self.grouping[attribute].sum().to_frame(name=f"sum_{attribute}").reset_index()
239
+ )
240
+
241
+ def min(self, attribute: str):
242
+ """Compute min of group values"""
243
+ return Relation(
244
+ self.grouping[attribute].min().to_frame(name=f"min_{attribute}").reset_index()
245
+ )
246
+
247
+ def max(self, attribute: str):
248
+ """Compute max of group values"""
249
+ return Relation(
250
+ self.grouping[attribute].max().to_frame(name=f"max_{attribute}").reset_index()
251
+ )
252
+
253
+ def avg(self, attribute: str):
254
+ """Compute average of group values"""
255
+ return Relation(
256
+ self.grouping[attribute].mean().to_frame(name=f"avg_{attribute}").reset_index()
257
+ )
258
+
259
+ def mean(self, attribute: str):
260
+ """Compute mean of group values"""
261
+ return Relation(
262
+ self.grouping[attribute].mean().to_frame(name=f"mean_{attribute}").reset_index()
263
+ )
264
+
265
+ def median(self, attribute: str):
266
+ """Compute median of group values"""
267
+ return Relation(
268
+ self.grouping[attribute].median().to_frame(name=f"median_{attribute}").reset_index()
269
+ )
270
+
271
+ def product(self, other: "Relation") -> "Relation":
272
+ """Cartesian product operation of the relational algebra
273
+
274
+ :param other: another relation
275
+ :raises TypeError: if the argument is not a relation
276
+ :raises ValueError: if the attributes are not disjoint
277
+ :return: a new relation
278
+ """
279
+ if not isinstance(other, Relation):
280
+ raise TypeError("Can only find a product of two relations.")
281
+ if set(self.columns).intersection(set(other.columns)):
282
+ raise ValueError(
283
+ "Two relations must have disjoint attributes for cartesian product to work."
284
+ )
285
+ return Relation(self._data.merge(other.data, how="cross"))
286
+
287
+ def union(self, other: "Relation") -> "Relation":
288
+ """Union operation of the relational algebra
289
+
290
+ :param other: another relation
291
+ :raises TypeError: if the argument is not a relation
292
+ :raises ValueError: if attributes do not match
293
+ :return: a new relation
294
+ """
295
+ if not isinstance(other, Relation):
296
+ raise TypeError("Can only find a union of two relations.")
297
+ if not self.columns.equals(other.columns):
298
+ raise ValueError("Names of the attributes must be the same in both relations.")
299
+ return Relation(pd.concat([self._data, other.data]))
300
+
301
+ def naturaljoin(self, other: "Relation") -> "Relation":
302
+ """Natural join operation of the relational algebra
303
+
304
+ :param other: another relation
305
+ :raises TypeError: if the argument is not a relation
306
+ :raises TypeError: if either of the provided attributes is not a string
307
+ :raises ValueError: if there are no matching attributes
308
+ :return: a new relation
309
+ :alias: njoin
310
+ """
311
+ if not isinstance(other, Relation):
312
+ raise TypeError("Can only join two relations.")
313
+ if not set(self.columns).intersection(set(other.columns)):
314
+ raise ValueError("There are no common attributes between these relations to join them.")
315
+ return Relation(self._data.merge(other.data, how="inner"))
316
+
317
+ njoin = naturaljoin
318
+
319
+ def equijoin(self, other: "Relation", left_attrib: str, right_attrib: str) -> "Relation":
320
+ """Equijoin operation of the relational algebra
321
+
322
+ :param other: another relation
323
+ :param left_attrib: attribute in the left relation
324
+ :param right_attrib: attribute in the right relation
325
+ :raises TypeError: if the argument is not a relation
326
+ :raises TypeError: if either of the provided attributes is not a string
327
+ :raises ValueError: if the provided left attribute is not found in the left relation
328
+ :raises ValueError: if the provided right attribute is not found in the right relation
329
+ :return: a new relation
330
+ :alias: ejoin
331
+ """
332
+ if not isinstance(other, Relation):
333
+ raise TypeError("Can only join two relations.")
334
+ if not isinstance(left_attrib, str) or not isinstance(right_attrib, str):
335
+ raise TypeError("Attributes must be strings.")
336
+ if left_attrib not in self.columns:
337
+ raise ValueError(f"There is no attribute >>{left_attrib}<< in the left relation.")
338
+ if right_attrib not in other.columns:
339
+ raise ValueError(f"There is no attribute >>{right_attrib}<< in the right relation.")
340
+ return Relation(
341
+ self._data.merge(other.data, how="inner", left_on=left_attrib, right_on=right_attrib)
342
+ )
343
+
344
+ ejoin = equijoin
345
+
346
+ def semijoin(self, other: "Relation", left_attrib: str, right_attrib: str) -> "Relation":
347
+ """Semijoin operation of the relational algebra
348
+
349
+ :param other: another relation
350
+ :param left_attrib: attribute in the left relation
351
+ :param right_attrib: attribute in the right relation
352
+ :raises TypeError: if the argument is not a relation
353
+ :raises TypeError: if either of the provided attributes is not a string
354
+ :raises ValueError: if the provided left attribute is not found in the left relation
355
+ :raises ValueError: if the provided right attribute is not found in the right relation
356
+ :return: a new relation
357
+ :alias: sjoin
358
+ """
359
+ if not isinstance(other, Relation):
360
+ raise TypeError("Can only join two relations.")
361
+ if not isinstance(left_attrib, str) or not isinstance(right_attrib, str):
362
+ raise TypeError("Attributes must be strings.")
363
+ if left_attrib not in self.columns:
364
+ raise ValueError(f"There is no attribute >>{left_attrib}<< in the left relation.")
365
+ if right_attrib not in other.columns:
366
+ raise ValueError(f"There is no attribute >>{right_attrib}<< in the right relation.")
367
+ return Relation(self[self[left_attrib].isin(other[right_attrib])])
368
+
369
+ sjoin = semijoin
370
+
371
+ def antijoin(self, other: "Relation", left_attrib: str, right_attrib: str) -> "Relation":
372
+ """Antijoin operation of the relational algebra
373
+
374
+ :param other: another relation
375
+ :param left_attrib: attribute in the left relation
376
+ :param right_attrib: attribute in the right relation
377
+ :raises TypeError: if the argument is not a relation
378
+ :raises TypeError: if either of the provided attributes is not a string
379
+ :return: a new relation
380
+ :alias: ajoin
381
+ """
382
+ if not isinstance(other, Relation):
383
+ raise TypeError("Can only join two relations.")
384
+ if not isinstance(left_attrib, str) or not isinstance(right_attrib, str):
385
+ raise TypeError("Attributes must be strings.")
386
+ return Relation(self[~self[left_attrib].isin(other[right_attrib])])
387
+
388
+ ajoin = antijoin
389
+
390
+ def outerjoin(self, other: "Relation") -> "Relation":
391
+ """Full outer join operation of the relational algebra
392
+
393
+ :param other: another relation
394
+ :param left_attrib: attribute in the left relation
395
+ :param right_attrib: attribute in the right relation
396
+ :raises TypeError: if the argument is not a relation
397
+ :raises ValueError: if the provided left attribute is not found in the left relation
398
+ :raises ValueError: if the provided right attribute is not found in the right relation
399
+ :return: a new relation
400
+ :alias: ojoin
401
+ """
402
+ if not isinstance(other, Relation):
403
+ raise TypeError("Can only join two relations.")
404
+ return Relation(self._data.merge(other.data, how="outer"))
405
+
406
+ ojoin = outerjoin
@@ -0,0 +1,443 @@
1
+ Metadata-Version: 2.4
2
+ Name: realed
3
+ Version: 2026.8
4
+ Summary: Relational Algebra for Educational purposes
5
+ Author: Roman Yasinovskyy
6
+ Author-email: Roman Yasinovskyy <yasinovskyy@gmail.com>
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Classifier: Development Status :: 5 - Production/Stable
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: Education
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3 :: Only
15
+ Classifier: Topic :: Education
16
+ Requires-Dist: numpy>=2.5.0
17
+ Requires-Dist: pandas>=3.0.5
18
+ Requires-Python: >=3.12
19
+ Project-URL: Homepage, https://github.com/yasinovskyy/realed
20
+ Project-URL: Issues, https://github.com/yasinovskyy/realed/issues
21
+ Description-Content-Type: text/markdown
22
+
23
+ # *ReAlEd*: Relational Algebra for Education
24
+
25
+ A simple wrapper around `pandas` to demonstrate common relational algebra operations:
26
+
27
+ - Selection (`select`)
28
+ - Projection (`project`)
29
+ - Renaming (`rename`)
30
+ - Extending (`extend`)
31
+ - Sorting (`sort`)
32
+ - Grouping (`groupby`)
33
+ - Cartesian product (`product`)
34
+ - Concatenation (`union`)
35
+ - Natural join (`njoin`)
36
+ - Equijoin (`ejoin`)
37
+ - Semijoin (`sjoin`)
38
+ - Antijoin (`ajoin`)
39
+ - Outer join (`ojoin`)
40
+
41
+ This implementation is a thin layer above the underlying `DataFrame` with some error handling and data cleaning added to make the resulting operations match those of the relational algebra.
42
+
43
+ Each operation returns a new relation without modifying the original.
44
+ Operations can be chained in various combinations.
45
+
46
+ It is a rewrite of [Brad Miller's reframe](https://github.com/bnmnetp/reframe) with the following major differences:
47
+
48
+ - expanded list of operations (various joins)
49
+ - the more recent version of `pandas` as a dependency
50
+ - composition used instead of inheritance
51
+
52
+ ## Initialization
53
+
54
+ A new relation can be created from a CSV file, a `DataFrame`, or another `Relation`.
55
+ Some arguments can be passed to the constructor in order to override defaults used by `pandas`:
56
+
57
+ ```python
58
+ penguins = Relation("palmerpenguins.csv")
59
+ penguins = Relation("palmerpenguins.csv", sep=",")
60
+ ```
61
+
62
+ Test data includes [Palmer penguins](https://allisonhorst.github.io/palmerpenguins/) and information about a couple Palmer islands to demonstrate multi-relation operations.
63
+
64
+ ```python
65
+ >>> from realed import Relation
66
+ >>> penguins = Relation("palmerpenguins.csv")
67
+ >>> penguins
68
+ rowid species island bill_length_mm ... flipper_length_mm body_mass_g sex year
69
+ 0 1 Adelie Torgersen 39.1 ... 181.0 3750.0 male 2007
70
+ 1 2 Adelie Torgersen 39.5 ... 186.0 3800.0 female 2007
71
+ 2 3 Adelie Torgersen 40.3 ... 195.0 3250.0 female 2007
72
+ 3 4 Adelie Torgersen NaN ... NaN NaN NaN 2007
73
+ 4 5 Adelie Torgersen 36.7 ... 193.0 3450.0 female 2007
74
+ .. ... ... ... ... ... ... ... ... ...
75
+ 339 340 Chinstrap Dream 55.8 ... 207.0 4000.0 male 2009
76
+ 340 341 Chinstrap Dream 43.5 ... 202.0 3400.0 female 2009
77
+ 341 342 Chinstrap Dream 49.6 ... 193.0 3775.0 male 2009
78
+ 342 343 Chinstrap Dream 50.8 ... 210.0 4100.0 male 2009
79
+ 343 344 Chinstrap Dream 50.2 ... 198.0 3775.0 female 2009
80
+ >>> islands = Relation("palmerislands.csv")
81
+ >>> islands
82
+ id island explored expedition name_origin
83
+ 0 1 Amsler 1955 Falkland Islands Dependencies Survey Margaret Amsler
84
+ 1 2 Anvers 1832 Southern Ocean Expedition Antwerp province
85
+ 2 3 Biscoe 1832 Southern Ocean Expedition John Biscoe
86
+ 3 4 Christiania 1898 Belgian Antarctic Expedition Oslo
87
+ 4 5 Dream 1956 British Naval Hydrographic Survey Unit Natural features
88
+ 5 6 Torgersen 1955 Falkland Islands Dependencies Survey Torstein Torgersen
89
+ >>>
90
+ ```
91
+
92
+ Certain helper methods and properties are available:
93
+
94
+ - property `data`: internal `DataFrame`
95
+ - property `columns`: names of the attributes
96
+ - property `dim`: dimensions of the relation (rows, columns)
97
+ - property `one`: the first record of the relation as a dictionary
98
+ - method `head`: return the first couple of records
99
+ - method `tail`: return the last couple of records
100
+ - method `to_csv`: export the `data` to a csv file
101
+ - method `copy`: deep copy of the `data`
102
+ - method `cleanup`: removal of empty records
103
+ - method `equals`: comparison of two relations
104
+ - method `minus`: difference between two relations
105
+ - method `intersection`: intersection of two relations
106
+
107
+ ## Selection (`select`)
108
+
109
+ Selection is a simplified version of the `query` method available in `pandas.DataFrame`.
110
+ It only takes one argument, the query expression.
111
+
112
+ ```python
113
+ >>> islands.select("expedition == 'Southern Ocean Expedition'")
114
+ id island explored expedition name_origin
115
+ 1 2 Anvers 1832 Southern Ocean Expedition Antwerp province
116
+ 2 3 Biscoe 1832 Southern Ocean Expedition John Biscoe
117
+ >>>
118
+ ```
119
+
120
+ ```python
121
+ >>> penguins.select("species == 'Adelie' and island == 'Torgersen' and year == 2009 and body_mass_g >= 4000")
122
+ rowid species island bill_length_mm bill_depth_mm flipper_length_mm body_mass_g sex year
123
+ 125 126 Adelie Torgersen 40.6 19.0 199.0 4000.0 male 2009
124
+ 127 128 Adelie Torgersen 41.5 18.3 195.0 4300.0 male 2009
125
+ 129 130 Adelie Torgersen 44.1 18.0 210.0 4000.0 male 2009
126
+ ```
127
+
128
+ Since each operation returns a `Relation`, operations can be chained:
129
+
130
+ ```python
131
+ >>> penguins.select("species == 'Adelie'").select("island == 'Torgersen'").select("year == 2009").select("body_mass_g >= 4000")
132
+ rowid species island bill_length_mm bill_depth_mm flipper_length_mm body_mass_g sex year
133
+ 125 126 Adelie Torgersen 40.6 19.0 199.0 4000.0 male 2009
134
+ 127 128 Adelie Torgersen 41.5 18.3 195.0 4300.0 male 2009
135
+ 129 130 Adelie Torgersen 44.1 18.0 210.0 4000.0 male 2009
136
+ ```
137
+
138
+ A separate method,`query`, is also available.
139
+ It passes all provided named arguments and keyword arguments to the `query` method of the `pandas.DataFrame`.
140
+
141
+ ## Projection (`project`)
142
+
143
+ For the sake of consistency names of attributes must be a list of strings, even if a single attribute is being projected.
144
+
145
+ ```python
146
+ >>> penguins.project(["island"])
147
+ island
148
+ 0 Torgersen
149
+ 20 Biscoe
150
+ 30 Dream
151
+ >>> penguins.project(["species", "island"])
152
+ species island
153
+ 0 Adelie Torgersen
154
+ 20 Adelie Biscoe
155
+ 30 Adelie Dream
156
+ 152 Gentoo Biscoe
157
+ 276 Chinstrap Dream
158
+ >>>
159
+ ```
160
+
161
+ ## Renaming (`rename`)
162
+
163
+ If the old name is not among the attributes or the new name is already there, a `ValueError` is raised.
164
+
165
+ ```python
166
+ >>> penguins.rename("island", "location").project(["species", "location"])
167
+ species location
168
+ 0 Adelie Torgersen
169
+ 20 Adelie Biscoe
170
+ 30 Adelie Dream
171
+ 152 Gentoo Biscoe
172
+ 276 Chinstrap Dream
173
+ >>>
174
+ ```
175
+
176
+ ## Sorting (`sort`)
177
+
178
+ ```python
179
+ >>> islands.sort(["explored"])
180
+ id island explored expedition name_origin
181
+ 1 2 Anvers 1832 Southern Ocean Expedition Antwerp province
182
+ 2 3 Biscoe 1832 Southern Ocean Expedition John Biscoe
183
+ 3 4 Christiania 1898 Belgian Antarctic Expedition Oslo
184
+ 0 1 Amsler 1955 Falkland Islands Dependencies Survey Margaret Amsler
185
+ 5 6 Torgersen 1955 Falkland Islands Dependencies Survey Torstein Torgersen
186
+ 4 5 Dream 1956 British Naval Hydrographic Survey Unit Natural features
187
+ >>> islands.sort(["explored"], ascending=False)
188
+ id island explored expedition name_origin
189
+ 4 5 Dream 1956 British Naval Hydrographic Survey Unit Natural features
190
+ 0 1 Amsler 1955 Falkland Islands Dependencies Survey Margaret Amsler
191
+ 5 6 Torgersen 1955 Falkland Islands Dependencies Survey Torstein Torgersen
192
+ 3 4 Christiania 1898 Belgian Antarctic Expedition Oslo
193
+ 1 2 Anvers 1832 Southern Ocean Expedition Antwerp province
194
+ 2 3 Biscoe 1832 Southern Ocean Expedition John Biscoe
195
+ ```
196
+
197
+ ```python
198
+ >>> penguins.sort(["species", "rowid"]).head(3)
199
+ rowid species island bill_length_mm ... flipper_length_mm body_mass_g sex year
200
+ 0 1 Adelie Torgersen 39.1 ... 181.0 3750.0 male 2007
201
+ 1 2 Adelie Torgersen 39.5 ... 186.0 3800.0 female 2007
202
+ 2 3 Adelie Torgersen 40.3 ... 195.0 3250.0 female 2007
203
+ ```
204
+
205
+ Be mindful of the order of sorting operations.
206
+
207
+ ```python
208
+ >>> penguins.sort(["body_mass_g"], ascending=False).sort(["species"]).head(3)
209
+ rowid species island bill_length_mm ... flipper_length_mm body_mass_g sex year
210
+ 111 112 Adelie Biscoe 45.6 ... 191.0 4600.0 male 2009
211
+ 76 77 Adelie Torgersen 40.9 ... 191.0 3700.0 female 2008
212
+ 14 15 Adelie Torgersen 34.6 ... 198.0 4400.0 male 2007
213
+ >>> penguins.sort(["species"]).sort(["body_mass_g"], ascending=False).head(3)
214
+ rowid species island bill_length_mm ... flipper_length_mm body_mass_g sex year
215
+ 169 170 Gentoo Biscoe 49.2 ... 221.0 6300.0 male 2007
216
+ 185 186 Gentoo Biscoe 59.6 ... 230.0 6050.0 male 2007
217
+ 269 270 Gentoo Biscoe 48.8 ... 222.0 6000.0 male 2009
218
+ ```
219
+
220
+ ## Extending (`extend`)
221
+
222
+ The new name cannot match the name of an existing attribute.
223
+ New data must be a of type `pandas.Series`.
224
+
225
+ ```python
226
+ >>> penguins.extend("years_since_study", 2026-penguins["year"])
227
+ rowid species island bill_length_mm ... body_mass_g sex year years_since_study
228
+ 0 1 Adelie Torgersen 39.1 ... 3750.0 male 2007 19
229
+ 1 2 Adelie Torgersen 39.5 ... 3800.0 female 2007 19
230
+ 2 3 Adelie Torgersen 40.3 ... 3250.0 female 2007 19
231
+ 3 4 Adelie Torgersen NaN ... NaN NaN 2007 19
232
+ 4 5 Adelie Torgersen 36.7 ... 3450.0 female 2007 19
233
+ .. ... ... ... ... ... ... ... ... ...
234
+ 339 340 Chinstrap Dream 55.8 ... 4000.0 male 2009 17
235
+ 340 341 Chinstrap Dream 43.5 ... 3400.0 female 2009 17
236
+ 341 342 Chinstrap Dream 49.6 ... 3775.0 male 2009 17
237
+ 342 343 Chinstrap Dream 50.8 ... 4100.0 male 2009 17
238
+ 343 344 Chinstrap Dream 50.2 ... 3775.0 female 2009 17
239
+ >>>
240
+ ```
241
+
242
+ ## Grouping (`groupby`) and aggregation
243
+
244
+ Grouping without an aggregate function eliminates duplicates in the chosen categories.
245
+
246
+ ```python
247
+ >>> penguins.groupby(["species"])
248
+ species
249
+ 0 Adelie
250
+ 1 Chinstrap
251
+ 2 Gentoo
252
+ ```
253
+
254
+ Typically, grouping is followed by an aggregate function `count`, `sum`, `min`, `max`, `mean` (`avg`), or `median`.
255
+ The aggregate function is added as a prefix to the name of the resulting column.
256
+
257
+ ```python
258
+ >>> penguins.groupby(["species"]).count("rowid")
259
+ species count_rowid
260
+ 0 Adelie 152
261
+ 1 Chinstrap 68
262
+ 2 Gentoo 124
263
+ >>> penguins.groupby(["island"]).count("rowid")
264
+ island count_rowid
265
+ 0 Biscoe 168
266
+ 1 Dream 124
267
+ 2 Torgersen 52
268
+ >>> penguins.groupby(["species", "island"]).count("rowid")
269
+ species island count_rowid
270
+ 0 Adelie Biscoe 44
271
+ 1 Adelie Dream 56
272
+ 2 Adelie Torgersen 52
273
+ 3 Chinstrap Dream 68
274
+ 4 Gentoo Biscoe 124
275
+ >>> penguins.groupby(["island"]).sum("body_mass_g")
276
+ island sum_body_mass_g
277
+ 0 Biscoe 787575.0
278
+ 1 Dream 460400.0
279
+ 2 Torgersen 189025.0
280
+ >>> penguins.groupby(["island"]).min("body_mass_g")
281
+ island min_body_mass_g
282
+ 0 Biscoe 2850.0
283
+ 1 Dream 2700.0
284
+ 2 Torgersen 2900.0
285
+ >>> penguins.groupby(["island"]).max("body_mass_g")
286
+ island max_body_mass_g
287
+ 0 Biscoe 6300.0
288
+ 1 Dream 4800.0
289
+ 2 Torgersen 4700.0
290
+ >>> penguins.groupby(["island"]).mean("body_mass_g")
291
+ island mean_body_mass_g
292
+ 0 Biscoe 4716.017964
293
+ 1 Dream 3712.903226
294
+ 2 Torgersen 3706.372549
295
+ >>> penguins.groupby(["island"]).avg("body_mass_g")
296
+ island avg_body_mass_g
297
+ 0 Biscoe 4716.017964
298
+ 1 Dream 3712.903226
299
+ 2 Torgersen 3706.372549
300
+ >>> penguins.groupby(["island"]).median("body_mass_g")
301
+ island median_body_mass_g
302
+ 0 Biscoe 4775.0
303
+ 1 Dream 3687.5
304
+ 2 Torgersen 3700.0
305
+ ```
306
+
307
+ ## Cartesian product (`product`)
308
+
309
+ Two relations must have disjoint attributes for this operation to work.
310
+
311
+ ```python
312
+ >>> penguins.product(islands.rename("island", "name"))
313
+ rowid species ... expedition name_origin
314
+ 0 1 Adelie ... Falkland Islands Dependencies Survey Margaret Amsler
315
+ 1 1 Adelie ... Southern Ocean Expedition Antwerp province
316
+ 2 1 Adelie ... Southern Ocean Expedition John Biscoe
317
+ 3 1 Adelie ... Belgian Antarctic Expedition Oslo
318
+ 4 1 Adelie ... British Naval Hydrographic Survey Unit Natural features
319
+ ... ... ... ... ... ...
320
+ 2059 344 Chinstrap ... Southern Ocean Expedition Antwerp province
321
+ 2060 344 Chinstrap ... Southern Ocean Expedition John Biscoe
322
+ 2061 344 Chinstrap ... Belgian Antarctic Expedition Oslo
323
+ 2062 344 Chinstrap ... British Naval Hydrographic Survey Unit Natural features
324
+ 2063 344 Chinstrap ... Falkland Islands Dependencies Survey Torstein Torgersen
325
+ ```
326
+
327
+ ## Concatenation (`union`)
328
+
329
+ Attributes of both relations must be the same.
330
+
331
+ ```python
332
+ >>> penguins.select("species == 'Adelie'").union(penguins.select("species == 'Gentoo'"))
333
+ rowid species island bill_length_mm ... flipper_length_mm body_mass_g sex year
334
+ 0 1 Adelie Torgersen 39.1 ... 181.0 3750.0 male 2007
335
+ 1 2 Adelie Torgersen 39.5 ... 186.0 3800.0 female 2007
336
+ 2 3 Adelie Torgersen 40.3 ... 195.0 3250.0 female 2007
337
+ 3 4 Adelie Torgersen NaN ... NaN NaN NaN 2007
338
+ 4 5 Adelie Torgersen 36.7 ... 193.0 3450.0 female 2007
339
+ .. ... ... ... ... ... ... ... ... ...
340
+ 271 272 Gentoo Biscoe NaN ... NaN NaN NaN 2009
341
+ 272 273 Gentoo Biscoe 46.8 ... 215.0 4850.0 female 2009
342
+ 273 274 Gentoo Biscoe 50.4 ... 222.0 5750.0 male 2009
343
+ 274 275 Gentoo Biscoe 45.2 ... 212.0 5200.0 female 2009
344
+ 275 276 Gentoo Biscoe 49.9 ... 213.0 5400.0 male 2009
345
+ ```
346
+
347
+ ## Natural join (`naturaljoin` or `njoin`)
348
+
349
+ There must be at least one common attribute in both relations.
350
+
351
+ ```python
352
+ >>> penguins.njoin(islands)
353
+ rowid species island ... explored expedition name_origin
354
+ 0 1 Adelie Torgersen ... 1955 Falkland Islands Dependencies Survey Torstein Torgersen
355
+ 1 2 Adelie Torgersen ... 1955 Falkland Islands Dependencies Survey Torstein Torgersen
356
+ 2 3 Adelie Torgersen ... 1955 Falkland Islands Dependencies Survey Torstein Torgersen
357
+ 3 4 Adelie Torgersen ... 1955 Falkland Islands Dependencies Survey Torstein Torgersen
358
+ 4 5 Adelie Torgersen ... 1955 Falkland Islands Dependencies Survey Torstein Torgersen
359
+ .. ... ... ... ... ... ... ...
360
+ 339 340 Chinstrap Dream ... 1956 British Naval Hydrographic Survey Unit Natural features
361
+ 340 341 Chinstrap Dream ... 1956 British Naval Hydrographic Survey Unit Natural features
362
+ 341 342 Chinstrap Dream ... 1956 British Naval Hydrographic Survey Unit Natural features
363
+ 342 343 Chinstrap Dream ... 1956 British Naval Hydrographic Survey Unit Natural features
364
+ 343 344 Chinstrap Dream ... 1956 British Naval Hydrographic Survey Unit Natural features
365
+ ```
366
+
367
+ ## Equijoin (`equijoin` or `ejoin`)
368
+
369
+ A simple version of the theta-join that checks two attributes for equality.
370
+ Both left and right attributes must be strings.
371
+
372
+ ```python
373
+ >>> penguins.ejoin(islands, "island", "island")
374
+ rowid species island ... explored expedition name_origin
375
+ 0 1 Adelie Torgersen ... 1955 Falkland Islands Dependencies Survey Torstein Torgersen
376
+ 1 2 Adelie Torgersen ... 1955 Falkland Islands Dependencies Survey Torstein Torgersen
377
+ 2 3 Adelie Torgersen ... 1955 Falkland Islands Dependencies Survey Torstein Torgersen
378
+ 3 4 Adelie Torgersen ... 1955 Falkland Islands Dependencies Survey Torstein Torgersen
379
+ 4 5 Adelie Torgersen ... 1955 Falkland Islands Dependencies Survey Torstein Torgersen
380
+ .. ... ... ... ... ... ... ...
381
+ 339 340 Chinstrap Dream ... 1956 British Naval Hydrographic Survey Unit Natural features
382
+ 340 341 Chinstrap Dream ... 1956 British Naval Hydrographic Survey Unit Natural features
383
+ 341 342 Chinstrap Dream ... 1956 British Naval Hydrographic Survey Unit Natural features
384
+ 342 343 Chinstrap Dream ... 1956 British Naval Hydrographic Survey Unit Natural features
385
+ 343 344 Chinstrap Dream ... 1956 British Naval Hydrographic Survey Unit Natural features
386
+ ```
387
+
388
+ ## Semijoin (`semijoin` or `sjoin`)
389
+
390
+ Both left and right attributes must be strings.
391
+
392
+ ```python
393
+ >>> islands.sjoin(penguins, "island", "island")
394
+ id island explored expedition name_origin
395
+ 2 3 Biscoe 1832 Southern Ocean Expedition John Biscoe
396
+ 4 5 Dream 1956 British Naval Hydrographic Survey Unit Natural features
397
+ 5 6 Torgersen 1955 Falkland Islands Dependencies Survey Torstein Torgersen
398
+ ```
399
+
400
+ ## Antijoin (`antijoin` or `ajoin`)
401
+
402
+ Both left and right attributes must be strings.
403
+
404
+ ```python
405
+ >>> islands.ajoin(penguins, "island", "island")
406
+ id island explored expedition name_origin
407
+ 0 1 Amsler 1955 Falkland Islands Dependencies Survey Margaret Amsler
408
+ 1 2 Anvers 1832 Southern Ocean Expedition Antwerp province
409
+ 3 4 Christiania 1898 Belgian Antarctic Expedition Oslo
410
+ ```
411
+
412
+ ## Outer join (`outerjoin` or `ojoin`)
413
+
414
+ Full outer join.
415
+
416
+ ```python
417
+ >>> islands.ojoin(penguins)
418
+ id island explored ... body_mass_g sex year
419
+ 0 1 Amsler 1955 ... NaN NaN NaN
420
+ 1 2 Anvers 1832 ... NaN NaN NaN
421
+ 2 3 Biscoe 1832 ... 3400.0 female 2007.0
422
+ 3 3 Biscoe 1832 ... 3600.0 male 2007.0
423
+ 4 3 Biscoe 1832 ... 3800.0 female 2007.0
424
+ .. .. ... ... ... ... ... ...
425
+ 342 6 Torgersen 1955 ... 4300.0 male 2009.0
426
+ 343 6 Torgersen 1955 ... 3050.0 female 2009.0
427
+ 344 6 Torgersen 1955 ... 4000.0 male 2009.0
428
+ 345 6 Torgersen 1955 ... 3325.0 female 2009.0
429
+ 346 6 Torgersen 1955 ... 3500.0 male 2009.0
430
+ >>> penguins.ojoin(islands)
431
+ rowid species island ... explored expedition name_origin
432
+ 0 NaN NaN Amsler ... 1955 Falkland Islands Dependencies Survey Margaret Amsler
433
+ 1 NaN NaN Anvers ... 1832 Southern Ocean Expedition Antwerp province
434
+ 2 21.0 Adelie Biscoe ... 1832 Southern Ocean Expedition John Biscoe
435
+ 3 22.0 Adelie Biscoe ... 1832 Southern Ocean Expedition John Biscoe
436
+ 4 23.0 Adelie Biscoe ... 1832 Southern Ocean Expedition John Biscoe
437
+ .. ... ... ... ... ... ... ...
438
+ 342 128.0 Adelie Torgersen ... 1955 Falkland Islands Dependencies Survey Torstein Torgersen
439
+ 343 129.0 Adelie Torgersen ... 1955 Falkland Islands Dependencies Survey Torstein Torgersen
440
+ 344 130.0 Adelie Torgersen ... 1955 Falkland Islands Dependencies Survey Torstein Torgersen
441
+ 345 131.0 Adelie Torgersen ... 1955 Falkland Islands Dependencies Survey Torstein Torgersen
442
+ 346 132.0 Adelie Torgersen ... 1955 Falkland Islands Dependencies Survey Torstein Torgersen
443
+ ```
@@ -0,0 +1,6 @@
1
+ realed/__init__.py,sha256=BtbxYW1OLOJ1mKMSYMDbR7rwvqXAc0Ndy7DrApom4Cg,53
2
+ realed/realed.py,sha256=ha9igc19wcwtlnJKWNRfyBNRf_aWzvgUw7e6X2eSzIA,16560
3
+ realed-2026.8.dist-info/licenses/LICENSE,sha256=084_k6a1qx34UVSwftXe7-Mdb_NTbhdyV2hTP-OJYLs,1074
4
+ realed-2026.8.dist-info/WHEEL,sha256=lrO5MD1WVAWzcbNy_L2BwtfPrcM3KfUFpbKYXLkJX4A,80
5
+ realed-2026.8.dist-info/METADATA,sha256=KK7Zaoy4ppM2mpKRFclgiIpGodgVbpk_9eaa-1nKbpk,22465
6
+ realed-2026.8.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: uv 0.12.1
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Roman Yasinovskyy
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.