|
84 | 84 | - [Data Aggregation](#data-aggregation) |
85 | 85 | - [Aggregation Functions](#aggregation-functions) |
86 | 86 | - [Utilities](#utilities) |
87 | | - - [1. `inspect`](#1-inspect) |
| 87 | + - [1. `inspect()`](#1-inspect) |
88 | 88 | - [2. `decorators`](#2-decorators) |
89 | | - - [`@initialize`](#initialize) |
| 89 | + - [`@initialize()`](#initialize) |
90 | 90 | - [3. `count()`](#3-count) |
91 | 91 | - [4. `min()`](#4-min) |
92 | 92 | - [5. `max()`](#5-max) |
@@ -182,7 +182,7 @@ if __name__ == "__main__": |
182 | 182 | conn.close() |
183 | 183 | ``` |
184 | 184 |
|
185 | | -In dataloom you can use connection uris to establish a connection to the database in `postgres` as follows: |
| 185 | +In `dataloom` you can use connection uris to establish a connection to the database in `postgres` as follows: |
186 | 186 |
|
187 | 187 | ```py |
188 | 188 | pg_loom = Loom( |
@@ -222,7 +222,7 @@ if __name__ == "__main__": |
222 | 222 |
|
223 | 223 | ``` |
224 | 224 |
|
225 | | -In dataloom you can use connection uris to establish a connection to the database in `mysql` as follows: |
| 225 | +In `dataloom` you can use connection uris to establish a connection to the database in `mysql` as follows: |
226 | 226 |
|
227 | 227 | ```py |
228 | 228 | mysql_loom = Loom( |
@@ -258,7 +258,7 @@ if __name__ == "__main__": |
258 | 258 | conn.close() |
259 | 259 | ``` |
260 | 260 |
|
261 | | -In dataloom you can use connection uris to establish a connection to the database in `sqlite` as follows: |
| 261 | +In `dataloom` you can use connection uris to establish a connection to the database in `sqlite` as follows: |
262 | 262 |
|
263 | 263 | ```py |
264 | 264 | sqlite_loom = Loom( |
@@ -303,7 +303,7 @@ The `Loom` class takes in the following options: |
303 | 303 | | Parameter | Description | Value Type | Default Value | Required | |
304 | 304 | | --------------- | --------------------------------------------------------------------------------- | --------------- | -------------- | -------- | |
305 | 305 | | `connection_uri` | The connection `uri` for the specified dialect. | `str` or `None` | `None` | `No` | |
306 | | -| `dialect` | Dialect for the database connection. Options are `mysql`, `postgres`, or `sqlite` | `str` or `None` | `None` | `Yes` | |
| 306 | +| `dialect` | Dialect for the database connection. Options are `mysql`, `postgres`, or `sqlite` | `"mysql" \| "postgres" \| "sqlite"` | `None` | `Yes` | |
307 | 307 | | `database` | Name of the database for `mysql` and `postgres`, filename for `sqlite` | `str` or `None` | `None` | `No` | |
308 | 308 | | `password` | Password for the database user (only for `mysql` and `postgres`) | `str` or `None` | `None` | `No` | |
309 | 309 | | `user` | Database user (only for `mysql` and `postgres`) | `str` or `None` | `None` | `No` | |
@@ -362,7 +362,7 @@ class Post(Model): |
362 | 362 |
|
363 | 363 | > 👉:**Note:** When defining a table name, it's not necessary to specify the property as `__tablename__`. However, it's considered good practice to name your table column like that to avoid potential clashes with other columns in the table. |
364 | 364 |
|
365 | | -- Every table must include exactly one primary key column. To define this, the `PrimaryKeyColumn` class is employed, signaling to `dataloom` that the specified field is a primary key. |
| 365 | +- Every table must include exactly one primary key column unless it is a `joint_table` for `N-N` relations that requires no primary key column. To define this, the `PrimaryKeyColumn` class is employed, signaling to `dataloom` that the specified field is a primary key. |
366 | 366 | - The `Column` class represents a regular column, allowing the inclusion of various options such as type and whether it is required. |
367 | 367 | - The `CreatedAtColumn` and `UpdatedAt` column types are automatically generated by the database as timestamps. If timestamps are unnecessary or only one of them is needed, they can be omitted. |
368 | 368 | - The `ForeignKeyColumn` establishes a relationship between the current (child) table and a referenced (parent) table. |
@@ -470,7 +470,7 @@ In this section we will list all the `datatypes` that are supported for each dia |
470 | 470 | | `"json"` | JSON (JavaScript Object Notation) data type. | |
471 | 471 | | `"blob"` | Binary Large Object (BLOB) data type. | |
472 | 472 |
|
473 | | -> Note: Every table is required to have a primary key column and this column should be 1. Let's talk about the `PrimaryKeyColumn` |
| 473 | +> Note: Every table that is not a `joint_table` is required to have a primary key column and this column should be 1. Let's talk about the `PrimaryKeyColumn` |
474 | 474 |
|
475 | 475 | #### `PrimaryKeyColumn` Class |
476 | 476 |
|
@@ -522,8 +522,8 @@ This column accepts the following arguments: |
522 | 522 | | `table` | Required. This is the parent table that the current model references. In our example, this is referred to as `User`. It can be used as a string in self relations. | `Model`\| `str` | | |
523 | 523 | | `type` | Optional. Specifies the data type of the foreign key. If not provided, dataloom can infer it from the parent table. | `str` \| `None` | `None` | |
524 | 524 | | `required` | Optional. Indicates whether the foreign key is required or not. | `bool` | `False` | |
525 | | -| `onDelete` | Optional. Specifies the action to be taken when the associated record in the parent table is deleted. | `str` [`"NO ACTION"`, `"SET NULL"`, `"CASCADE"`] | `"NO ACTION"` | |
526 | | -| `onUpdate` | Optional. Specifies the action to be taken when the associated record in the parent table is updated. | str [`"NO ACTION"`, `"SET NULL"`, `"CASCADE"`] | `"NO ACTION"` | |
| 525 | +| `onDelete` | Optional. Specifies the action to be taken when the associated record in the parent table is deleted. |`"NO ACTION"`, `"SET NULL"`, `"CASCADE"` | `"NO ACTION"` | |
| 526 | +| `onUpdate` | Optional. Specifies the action to be taken when the associated record in the parent table is updated. | `"NO ACTION"`, `"SET NULL"`, `"CASCADE"`| `"NO ACTION"` | |
527 | 527 |
|
528 | 528 | It is crucial to specify the actions for `onDelete` and `onUpdate` to ensure that `dataloom` manages your model's relationship actions appropriately. The available actions are: |
529 | 529 |
|
@@ -562,7 +562,7 @@ So from the above example we are applying filters while updating a `Post` here a |
562 | 562 | |-------------------------|------------------------------------------------------------|-------------------------------------------|------------------------| |
563 | 563 | | `column` | The name of the column to apply the filter on | `String` | - | |
564 | 564 | | `value` | The value to filter against | `Any` | - | |
565 | | -| `operator` | The comparison operator to use for the filter | `'eq'`, `'neq'`. `'lt'`, `'gt'`, `'leq'`, `'geq'`, `'in'`, `'notIn'`, `'like'` | `'eq'` | |
| 565 | +| `operator` | The comparison operator to use for the filter | `'eq'`, `'neq'`. `'lt'`, `'gt'`, `'leq'`, `'geq'`, `'in'`, `'notIn'`, `'like'`, `'between'`, `'not'` | `'eq'` | |
566 | 566 | | `join_next_with` | The logical operator to join this filter with the next one | `'AND'`, `'OR'` | `'AND'` | |
567 | 567 |
|
568 | 568 | > 👍**Pro Tip:** Note You can apply either a list of filters or a single filter when filtering records. |
@@ -671,14 +671,14 @@ print(tables) |
671 | 671 |
|
672 | 672 | The method returns a list of table names that have been created or that exist in your database. The `sync` method accepts the following arguments: |
673 | 673 |
|
674 | | -| Argument | Description | Type | Default | |
675 | | -| -------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------- | |
676 | | -| `models` | A collection or a single instance(s) of your table classes that inherit from the Model class. | `list[Model]\|Any` | `[]` | |
677 | | -| `drop` | Whether to drop tables during syncing or not. | `bool` | `False` | |
678 | | -| `force` | Forcefully drop tables during syncing. In `mysql` this will temporarily disable foreign key checks when droping the tables. | `bool` | `False` | |
679 | | -| `alter` | Alter tables instead of dropping them during syncing or not. | `bool` | `False` | |
| 674 | +| Argument | Description | Type | Default | |
| 675 | +| -------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------- | |
| 676 | +| `models` | A collection or a single instance(s) of your table classes that inherit from the Model class. | `list[Model]\|Model` | `[]` | |
| 677 | +| `drop` | Whether to drop tables during syncing or not. | `bool` | `False` | |
| 678 | +| `force` | Forcefully drop tables during syncing. In `mysql` this will temporarily disable foreign key checks when droping the tables. | `bool` | `False` | |
| 679 | +| `alter` | Alter tables instead of dropping them during syncing or not. | `bool` | `False` | |
680 | 680 |
|
681 | | -> 🥇 **We recommend you to use `drop` or `force` if you are going to change or modify `foreign` and `primary` keys. This is because setting the option `alter` doe not have an effect on `primary` key columns.** |
| 681 | +> 🥇 **We recommend you to use `drop` or `force` if you are going to change or modify `foreign` and `primary` keys. This is because setting the option `alter` does not have an effect on `primary` key columns.** |
682 | 682 |
|
683 | 683 | > We've noticed two steps involved in starting to work with our `orm`. Initially, you need to create a connection and then synchronize the tables in another step. |
684 | 684 |
|
@@ -804,7 +804,7 @@ The `find_all()` method takes in the following arguments: |
804 | 804 | | `select` | Collection or a string of fields to select from the documents. | `list[str]\|str` | `None` | `No` | |
805 | 805 | | `limit` | Maximum number of documents to retrieve. | `int` | `None` | `No` | |
806 | 806 | | `offset` | Number of documents to skip before retrieving. | `int` | `0` | `No` | |
807 | | -| `order` | Collection of columns to order the documents by. | `list[Order]` | `None` | `No` | |
| 807 | +| `order` | Collection of `Order` or a single `Order` to order the documents when querying. | `list[Order]\|Order` | `None` | `No` | |
808 | 808 | | `include` | Collection or a `Include` of related models to eagerly load. | `list[Include]\|Include` | `None` | `No` | |
809 | 809 | | `group` | Collection of `Group` which specifies how you want your data to be grouped during queries. | `list[Group]\|Group` | `None` | `No` | |
810 | 810 | | `distinct` | Boolean telling dataloom to return distinct row values based on selected fields or not. | `bool` | `False` | `No` | |
@@ -835,7 +835,7 @@ The `find_many()` method takes in the following arguments: |
835 | 835 | | `select` | Collection or a string of fields to select from the documents. | `list[str]\|str` | `None` | `No` | |
836 | 836 | | `limit` | Maximum number of documents to retrieve. | `int` | `None` | `No` | |
837 | 837 | | `offset` | Number of documents to skip before retrieving. | `int` | `0` | `No` | |
838 | | -| `order` | Collection of columns to order the documents by. | `list[Order]` | `None` | `No` | |
| 838 | +| `order` | Collection of `Order` or a single `Order` to order the documents when querying. | `list[Order]\|Order` | `None` | `No` | |
839 | 839 | | `include` | Collection or a `Include` of related models to eagerly load. | `list[Include]\|Include` | `None` | `No` | |
840 | 840 | | `group` | Collection of `Group` which specifies how you want your data to be grouped during queries. | `list[Group]\|Group` | `None` | `No` | |
841 | 841 | | `filters` | Collection of `Filter` or a `Filter` to apply to the query. | `list[Filter] \| Filter` | `None` | `No` | |
@@ -877,12 +877,12 @@ print(user) # ? {'id': 1, 'username': '@miller'} |
877 | 877 |
|
878 | 878 | The method takes the following as arguments: |
879 | 879 |
|
880 | | -| Argument | Description | Type | Default | Required | |
881 | | -| ---------- | ---------------------------------------------------------------------------------- | --------------- | ------- | -------- | |
882 | | -| `instance` | The model class to retrieve instances from. | `Model` | | `Yes` | |
883 | | -| `pk` | The primary key value to use for retrieval. | `Any` | | `Yes` | |
884 | | -| `select` | Collection column names to select from the instances. | `list[str]` | `[]` | `No` | |
885 | | -| `include` | A Collection of `Include` or a single `Include` of related models to eagerly load. | `list[Include]` | `[]` | `No` | |
| 880 | +| Argument | Description | Type | Default | Required | |
| 881 | +| ---------- | ---------------------------------------------------------------------------------- | ------------------------ | ------- | -------- | |
| 882 | +| `instance` | The model class to retrieve instances from. | `Model` | | `Yes` | |
| 883 | +| `pk` | The primary key value to use for retrieval. | `Any` | | `Yes` | |
| 884 | +| `select` | Collection column names to select from the instances. | `list[str]` | `[]` | `No` | |
| 885 | +| `include` | A Collection of `Include` or a single `Include` of related models to eagerly load. | `list[Include]\|Include` | `[]` | `No` | |
886 | 886 |
|
887 | 887 | #### 3. Updating a record |
888 | 888 |
|
@@ -1352,7 +1352,7 @@ You can use the following aggregation functions that dataloom supports: |
1352 | 1352 |
|
1353 | 1353 | Dataloom comes up with some utility functions that works on an instance of a model. This is very useful when debuging your tables to see how do they look like. These function include: |
1354 | 1354 |
|
1355 | | -#### 1. `inspect` |
| 1355 | +#### 1. `inspect()` |
1356 | 1356 |
|
1357 | 1357 | This function takes in a model as argument and inspect the model fields or columns. The following examples show how we can use this handy function in inspecting table names. |
1358 | 1358 |
|
@@ -1398,7 +1398,7 @@ The `inspect` function take the following arguments. |
1398 | 1398 |
|
1399 | 1399 | These modules contain several decorators that can prove useful when creating models. These decorators originate from `dataloom.decorators`, and at this stage, we are referring to them as "experimental." |
1400 | 1400 |
|
1401 | | -##### `@initialize` |
| 1401 | +##### `@initialize()` |
1402 | 1402 |
|
1403 | 1403 | Let's examine a model named `Profile`, which appears as follows: |
1404 | 1404 |
|
|
0 commit comments