diff --git a/README.md b/README.md index a0bf1ff..8eab0e8 100644 --- a/README.md +++ b/README.md @@ -84,9 +84,9 @@ - [Data Aggregation](#data-aggregation) - [Aggregation Functions](#aggregation-functions) - [Utilities](#utilities) - - [1. `inspect`](#1-inspect) + - [1. `inspect()`](#1-inspect) - [2. `decorators`](#2-decorators) - - [`@initialize`](#initialize) + - [`@initialize()`](#initialize) - [3. `count()`](#3-count) - [4. `min()`](#4-min) - [5. `max()`](#5-max) @@ -182,7 +182,7 @@ if __name__ == "__main__": conn.close() ``` -In dataloom you can use connection uris to establish a connection to the database in `postgres` as follows: +In `dataloom` you can use connection uris to establish a connection to the database in `postgres` as follows: ```py pg_loom = Loom( @@ -222,7 +222,7 @@ if __name__ == "__main__": ``` -In dataloom you can use connection uris to establish a connection to the database in `mysql` as follows: +In `dataloom` you can use connection uris to establish a connection to the database in `mysql` as follows: ```py mysql_loom = Loom( @@ -258,7 +258,7 @@ if __name__ == "__main__": conn.close() ``` -In dataloom you can use connection uris to establish a connection to the database in `sqlite` as follows: +In `dataloom` you can use connection uris to establish a connection to the database in `sqlite` as follows: ```py sqlite_loom = Loom( @@ -303,7 +303,7 @@ The `Loom` class takes in the following options: | Parameter | Description | Value Type | Default Value | Required | | --------------- | --------------------------------------------------------------------------------- | --------------- | -------------- | -------- | | `connection_uri` | The connection `uri` for the specified dialect. | `str` or `None` | `None` | `No` | -| `dialect` | Dialect for the database connection. Options are `mysql`, `postgres`, or `sqlite` | `str` or `None` | `None` | `Yes` | +| `dialect` | Dialect for the database connection. Options are `mysql`, `postgres`, or `sqlite` | `"mysql" \| "postgres" \| "sqlite"` | `None` | `Yes` | | `database` | Name of the database for `mysql` and `postgres`, filename for `sqlite` | `str` or `None` | `None` | `No` | | `password` | Password for the database user (only for `mysql` and `postgres`) | `str` or `None` | `None` | `No` | | `user` | Database user (only for `mysql` and `postgres`) | `str` or `None` | `None` | `No` | @@ -362,7 +362,7 @@ class Post(Model): > 👉:**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. -- 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. +- 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. - The `Column` class represents a regular column, allowing the inclusion of various options such as type and whether it is required. - 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. - 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 | `"json"` | JSON (JavaScript Object Notation) data type. | | `"blob"` | Binary Large Object (BLOB) data type. | -> Note: Every table is required to have a primary key column and this column should be 1. Let's talk about the `PrimaryKeyColumn` +> 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` #### `PrimaryKeyColumn` Class @@ -522,8 +522,8 @@ This column accepts the following arguments: | `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` | | | `type` | Optional. Specifies the data type of the foreign key. If not provided, dataloom can infer it from the parent table. | `str` \| `None` | `None` | | `required` | Optional. Indicates whether the foreign key is required or not. | `bool` | `False` | -| `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"` | -| `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"` | +| `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"` | +| `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"` | 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: @@ -562,7 +562,7 @@ So from the above example we are applying filters while updating a `Post` here a |-------------------------|------------------------------------------------------------|-------------------------------------------|------------------------| | `column` | The name of the column to apply the filter on | `String` | - | | `value` | The value to filter against | `Any` | - | -| `operator` | The comparison operator to use for the filter | `'eq'`, `'neq'`. `'lt'`, `'gt'`, `'leq'`, `'geq'`, `'in'`, `'notIn'`, `'like'` | `'eq'` | +| `operator` | The comparison operator to use for the filter | `'eq'`, `'neq'`. `'lt'`, `'gt'`, `'leq'`, `'geq'`, `'in'`, `'notIn'`, `'like'`, `'between'`, `'not'` | `'eq'` | | `join_next_with` | The logical operator to join this filter with the next one | `'AND'`, `'OR'` | `'AND'` | > 👍**Pro Tip:** Note You can apply either a list of filters or a single filter when filtering records. @@ -671,14 +671,14 @@ print(tables) 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: -| Argument | Description | Type | Default | -| -------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------- | -| `models` | A collection or a single instance(s) of your table classes that inherit from the Model class. | `list[Model]\|Any` | `[]` | -| `drop` | Whether to drop tables during syncing or not. | `bool` | `False` | -| `force` | Forcefully drop tables during syncing. In `mysql` this will temporarily disable foreign key checks when droping the tables. | `bool` | `False` | -| `alter` | Alter tables instead of dropping them during syncing or not. | `bool` | `False` | +| Argument | Description | Type | Default | +| -------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------- | +| `models` | A collection or a single instance(s) of your table classes that inherit from the Model class. | `list[Model]\|Model` | `[]` | +| `drop` | Whether to drop tables during syncing or not. | `bool` | `False` | +| `force` | Forcefully drop tables during syncing. In `mysql` this will temporarily disable foreign key checks when droping the tables. | `bool` | `False` | +| `alter` | Alter tables instead of dropping them during syncing or not. | `bool` | `False` | -> 🥇 **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.** +> 🥇 **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.** > 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. @@ -804,7 +804,7 @@ The `find_all()` method takes in the following arguments: | `select` | Collection or a string of fields to select from the documents. | `list[str]\|str` | `None` | `No` | | `limit` | Maximum number of documents to retrieve. | `int` | `None` | `No` | | `offset` | Number of documents to skip before retrieving. | `int` | `0` | `No` | -| `order` | Collection of columns to order the documents by. | `list[Order]` | `None` | `No` | +| `order` | Collection of `Order` or a single `Order` to order the documents when querying. | `list[Order]\|Order` | `None` | `No` | | `include` | Collection or a `Include` of related models to eagerly load. | `list[Include]\|Include` | `None` | `No` | | `group` | Collection of `Group` which specifies how you want your data to be grouped during queries. | `list[Group]\|Group` | `None` | `No` | | `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: | `select` | Collection or a string of fields to select from the documents. | `list[str]\|str` | `None` | `No` | | `limit` | Maximum number of documents to retrieve. | `int` | `None` | `No` | | `offset` | Number of documents to skip before retrieving. | `int` | `0` | `No` | -| `order` | Collection of columns to order the documents by. | `list[Order]` | `None` | `No` | +| `order` | Collection of `Order` or a single `Order` to order the documents when querying. | `list[Order]\|Order` | `None` | `No` | | `include` | Collection or a `Include` of related models to eagerly load. | `list[Include]\|Include` | `None` | `No` | | `group` | Collection of `Group` which specifies how you want your data to be grouped during queries. | `list[Group]\|Group` | `None` | `No` | | `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'} The method takes the following as arguments: -| Argument | Description | Type | Default | Required | -| ---------- | ---------------------------------------------------------------------------------- | --------------- | ------- | -------- | -| `instance` | The model class to retrieve instances from. | `Model` | | `Yes` | -| `pk` | The primary key value to use for retrieval. | `Any` | | `Yes` | -| `select` | Collection column names to select from the instances. | `list[str]` | `[]` | `No` | -| `include` | A Collection of `Include` or a single `Include` of related models to eagerly load. | `list[Include]` | `[]` | `No` | +| Argument | Description | Type | Default | Required | +| ---------- | ---------------------------------------------------------------------------------- | ------------------------ | ------- | -------- | +| `instance` | The model class to retrieve instances from. | `Model` | | `Yes` | +| `pk` | The primary key value to use for retrieval. | `Any` | | `Yes` | +| `select` | Collection column names to select from the instances. | `list[str]` | `[]` | `No` | +| `include` | A Collection of `Include` or a single `Include` of related models to eagerly load. | `list[Include]\|Include` | `[]` | `No` | #### 3. Updating a record @@ -1352,7 +1352,7 @@ You can use the following aggregation functions that dataloom supports: 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: -#### 1. `inspect` +#### 1. `inspect()` 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. @@ -1398,7 +1398,7 @@ The `inspect` function take the following arguments. 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." -##### `@initialize` +##### `@initialize()` Let's examine a model named `Profile`, which appears as follows: