Skip to content

Commit

Permalink
docs-update
Browse files Browse the repository at this point in the history
  • Loading branch information
@CrispenGari
CrispenGari committed Feb 27, 2024
1 parent 6dfaff0 commit f632f74
Showing 1 changed file with 28 additions and 28 deletions.
56 changes: 28 additions & 28 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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` |
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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` |
Expand Down Expand Up @@ -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` |
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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:

Expand Down

0 comments on commit f632f74

Please sign in to comment.