feat: support primary_key/db_index and mark pk/index as deprecated (#…

…1621)

* feat: support primary_key/db_index and make pk/index as alias

* Make style

* Add testcases for pk alias

* Add index alias tests

* Fix error message not match

* Update change log

CHANGELOG.rst

@@ -32,6 +32,7 @@ Changed
 ^^^^^^^
 - Change `utils.chunk` from function to return iterables lazily.
 - Removed lower bound of id keys in generated pydantic models. (#1602)
+- Rename Field initial arguments `pk`/`index` to `primary_key`/`db_index`. (#1621)
 
 Breaking Changes
 ^^^^^^^^^^^^^^^^

README.rst

@@ -101,15 +101,15 @@ You can start writing models like this:
     from tortoise import fields
 
     class Tournament(Model):
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.TextField()
 
         def __str__(self):
             return self.name
 
 
     class Event(Model):
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.TextField()
         tournament = fields.ForeignKeyField('models.Tournament', related_name='events')
         participants = fields.ManyToManyField('models.Team', related_name='events', through='event_team')
@@ -119,7 +119,7 @@ You can start writing models like this:
 
 
     class Team(Model):
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.TextField()
 
         def __str__(self):

docs/contrib/pydantic.rst

@@ -40,7 +40,7 @@ Lets start with a basic Tortoise Model:
         """
         This references a Tournament
         """
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.CharField(max_length=100)
         #: The date-time the Tournament record was created at
         created_at = fields.DatetimeField(auto_now_add=True)
@@ -131,7 +131,7 @@ Source to example: :ref:`example_pydantic_tut2`
         """
         This references a Tournament
         """
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.CharField(max_length=100)
         #: The date-time the Tournament record was created at
         created_at = fields.DatetimeField(auto_now_add=True)
@@ -278,7 +278,7 @@ We define our models with a relationship:
         This references a Tournament
         """
 
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.CharField(max_length=100)
         #: The date-time the Tournament record was created at
         created_at = fields.DatetimeField(auto_now_add=True)
@@ -288,7 +288,7 @@ We define our models with a relationship:
         This references an Event in a Tournament
         """
 
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.CharField(max_length=100)
         created_at = fields.DatetimeField(auto_now_add=True)
 
@@ -533,7 +533,7 @@ Let's add some methods that calculate data, and tell the creators to use them:
         This references a Tournament
         """
 
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.CharField(max_length=100)
         created_at = fields.DatetimeField(auto_now_add=True)
 
@@ -568,7 +568,7 @@ Let's add some methods that calculate data, and tell the creators to use them:
         This references an Event in a Tournament
         """
 
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.CharField(max_length=100)
         created_at = fields.DatetimeField(auto_now_add=True)
 

docs/fields.rst

@@ -16,7 +16,7 @@ Fields are defined as properties of a ``Model`` class object:
     from tortoise import fields
 
     class Tournament(Model):
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.CharField(max_length=255)
 
 

docs/getting_started.rst

@@ -84,7 +84,7 @@ You can start writing models like this:
     class Tournament(Model):
         # Defining `id` field is optional, it will be defined automatically
         # if you haven't done it yourself
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.CharField(max_length=255)
 
         # Defining ``__str__`` is also optional, but gives you pretty
@@ -94,7 +94,7 @@ You can start writing models like this:
 
 
     class Event(Model):
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.CharField(max_length=255)
         # References to other models are defined in format
         # "{app_name}.{model_name}" - where {app_name} is defined in tortoise config
@@ -106,7 +106,7 @@ You can start writing models like this:
 
 
     class Team(Model):
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.CharField(max_length=255)
 
         def __str__(self):

docs/index.rst

@@ -58,7 +58,7 @@ Define your models like so:
     from tortoise import fields
 
     class Tournament(Model):
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.TextField()
 
 Initialise your models and database like so:

docs/indexes.rst

@@ -4,7 +4,7 @@
 Indexes
 =======
 
-Default tortoise use `BTree` index when define index use `index=True` in field, or define indexes use in `Meta` class, but if you want use other index types, like `FullTextIndex` in `MySQL`, or `GinIndex` in `Postgres`, you should use `tortoise.indexes.Index` and its subclasses.
+Default tortoise use `BTree` index when define index use `db_index=True` in field, or define indexes use in `Meta` class, but if you want use other index types, like `FullTextIndex` in `MySQL`, or `GinIndex` in `Postgres`, you should use `tortoise.indexes.Index` and its subclasses.
 
 Usage
 =====

docs/models.rst

@@ -20,7 +20,7 @@ With that you can start describing your own models like that
 .. code-block:: python3
 
     class Tournament(Model):
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.TextField()
         created = fields.DatetimeField(auto_now_add=True)
 
@@ -29,7 +29,7 @@ With that you can start describing your own models like that
 
 
     class Event(Model):
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.TextField()
         tournament = fields.ForeignKeyField('models.Tournament', related_name='events')
         participants = fields.ManyToManyField('models.Team', related_name='events', through='event_team')
@@ -41,7 +41,7 @@ With that you can start describing your own models like that
 
 
     class Team(Model):
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.TextField()
 
         def __str__(self):
@@ -58,7 +58,7 @@ Every model should be derived from base model. You also can derive from your own
 .. code-block:: python3
 
     class AbstractTournament(Model):
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.TextField()
         created = fields.DatetimeField(auto_now_add=True)
 
@@ -97,7 +97,7 @@ That alias field can be used as a field name when doing filtering e.g. ``.filter
     CharField
     UUIDField
 
-One must define a primary key by setting a ``pk`` parameter to ``True``. 
+One must define a primary key by setting a ``primary_key`` parameter to ``True``.
 If you don't define a primary key, we will create a primary key of type ``IntField`` with name of ``id`` for you.
 
 .. note::
@@ -107,11 +107,11 @@ Any of these are valid primary key definitions in a Model:
 
 .. code-block:: python3
 
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
 
-    checksum = fields.CharField(pk=True)
+    checksum = fields.CharField(primary_key=True)
 
-    guid = fields.UUIDField(pk=True)
+    guid = fields.UUIDField(primary_key=True)
 
 
 Inheritance
@@ -141,15 +141,15 @@ Let's have a look at some examples.
         name = fields.CharField(40, unique=True)
 
     class MyAbstractBaseModel(Model):
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
 
         class Meta:
             abstract = True
 
     class UserModel(TimestampMixin, MyAbstractBaseModel):
         # Overriding the id definition
         # from MyAbstractBaseModel
-        id = fields.UUIDField(pk=True)
+        id = fields.UUIDField(primary_key=True)
 
         # Adding additional fields
         first_name = fields.CharField(20, null=True)
@@ -413,7 +413,7 @@ all models including fields for the relations between models.
 
 
     class Tournament(Model):
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.CharField(max_length=255)
 
         events: fields.ReverseRelation["Event"]
@@ -423,7 +423,7 @@ all models including fields for the relations between models.
 
 
     class Event(Model):
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.CharField(max_length=255)
         tournament: fields.ForeignKeyRelation[Tournament] = fields.ForeignKeyField(
             "models.Tournament", related_name="events"
@@ -437,7 +437,7 @@ all models including fields for the relations between models.
 
 
     class Team(Model):
-        id = fields.IntField(pk=True)
+        id = fields.IntField(primary_key=True)
         name = fields.CharField(max_length=255)
 
         events: fields.ManyToManyRelation[Event]

examples/aiohttp/models.py

@@ -2,7 +2,7 @@
 
 
 class Users(Model):
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
     name = fields.CharField(50)
 
     def __str__(self):

examples/basic.py

@@ -7,7 +7,7 @@
 
 
 class Event(Model):
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
     name = fields.TextField()
     datetime = fields.DatetimeField(null=True)
 

examples/basic_comments.py

@@ -8,7 +8,7 @@
 
 
 class Event(Model):
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
     name = fields.TextField(description="Name of the event that corresponds to an action")
     datetime = fields.DatetimeField(
         null=True, description="Datetime of when the event was generated"

examples/blacksheep/models.py

@@ -3,7 +3,7 @@
 
 
 class Users(models.Model):
-    id = fields.UUIDField(pk=True)
+    id = fields.UUIDField(primary_key=True)
     username = fields.CharField(max_length=63)
 
     def __str__(self) -> str:

examples/complex_filtering.py

@@ -10,7 +10,7 @@
 
 
 class Tournament(Model):
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
     name = fields.TextField()
 
     events: fields.ReverseRelation["Event"]
@@ -20,7 +20,7 @@ def __str__(self):
 
 
 class Event(Model):
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
     name = fields.TextField()
     tournament: fields.ForeignKeyRelation[Tournament] = fields.ForeignKeyField(
         "models.Tournament", related_name="events"
@@ -34,7 +34,7 @@ def __str__(self):
 
 
 class Team(Model):
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
     name = fields.TextField()
 
     events: fields.ManyToManyRelation[Event]

examples/complex_prefetching.py

@@ -4,7 +4,7 @@
 
 
 class Tournament(Model):
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
     name = fields.TextField()
 
     events: fields.ReverseRelation["Event"]
@@ -14,7 +14,7 @@ def __str__(self):
 
 
 class Event(Model):
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
     name = fields.TextField()
     tournament: fields.ForeignKeyRelation[Tournament] = fields.ForeignKeyField(
         "models.Tournament", related_name="events"
@@ -28,7 +28,7 @@ def __str__(self):
 
 
 class Team(Model):
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
     name = fields.TextField()
 
     events: fields.ManyToManyRelation[Event]

examples/fastapi/models.py

@@ -7,7 +7,7 @@ class Users(models.Model):
     The User model
     """
 
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
     #: This is a username
     username = fields.CharField(max_length=20, unique=True)
     name = fields.CharField(max_length=50, null=True)

examples/functions.py

@@ -5,7 +5,7 @@
 
 
 class Tournament(Model):
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
     name = fields.TextField()
     desc = fields.TextField(null=True)
 
@@ -16,7 +16,7 @@ def __str__(self):
 
 
 class Event(Model):
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
     name = fields.TextField()
     tournament: fields.ForeignKeyRelation[Tournament] = fields.ForeignKeyField(
         "models.Tournament", related_name="events"
@@ -30,7 +30,7 @@ def __str__(self):
 
 
 class Team(Model):
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
     name = fields.TextField()
 
     events: fields.ManyToManyRelation[Event]

examples/manual_sql.py

@@ -8,7 +8,7 @@
 
 
 class Event(Model):
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
     name = fields.TextField()
     timestamp = fields.DatetimeField(auto_now_add=True)
 

examples/postgres.py

@@ -7,7 +7,7 @@
 
 
 class Report(Model):
-    id = fields.IntField(pk=True)
+    id = fields.IntField(primary_key=True)
     content = fields.JSONField()
 
     def __str__(self):