tweaked docs

Author: dantownsend

docs/src/piccolo/features/syntax.rst

@@ -20,7 +20,7 @@ underlying SQL - making the ORM feel less magic.
 
 .. code-block:: python
 
-    query = Band.select().columns(Band.name).where(Band.popularity >= 100)
+    query = Band.select(Band.name).where(Band.popularity >= 100)
 
     print(query)
     'SELECT name from band where popularity > 100'

docs/src/piccolo/migrations/create.rst

@@ -121,26 +121,4 @@ Altering tables
 ---------------
 
 To alter tables, you'll use mostly use alter queries (see :ref:`alter`), and
-occassionally raw queries (see :ref:`raw`).
-
-Auto populating migrations
---------------------------
-
-Instead of manually populating your migrations each time, Piccolo has helpers
-for common use cases.
-
-Creating tables
-~~~~~~~~~~~~~~~
-
-Rather than having to copy in your table definitions manually, you can ask
-Piccolo to do it for you using the ``-c`` flag and passing in the import path
-for the table. Multiple ``-c`` flags can be used.
-
-.. code-block:: bash
-
-    piccolo migration new -c ..tables.Band -c ..tables.Manager
-
-Piccolo needs to be able to import these files using ``importlib``, so make
-sure the paths are correct.
-
-Piccolo will then add the table definitions the migration.
+occasionally raw queries (see :ref:`raw`).

docs/src/piccolo/query_clauses/limit.rst

@@ -8,8 +8,8 @@ You can use ``limit`` clauses with the following queries:
 * :ref:`Objects`
 * :ref:`Select`
 
-Rather than returning a list of results, it will only return the number you ask
-for.
+Rather than returning all of the matching results, it will only return the
+number you ask for.
 
 .. code-block:: python
 

docs/src/piccolo/query_clauses/offset.rst

@@ -8,8 +8,7 @@ You can use ``offset`` clauses with the following queries:
 * :ref:`Objects`
 * :ref:`Select`
 
-This will omit the first X rows from the response. It's useful for things like
-pagination.
+This will omit the first X rows from the response.
 
 It's highly recommended to use it along with an :ref:`order_by` clause,
 otherwise the results returned could be different each time.

docs/src/piccolo/query_clauses/where.rst

@@ -14,7 +14,7 @@ You can use ``where`` clauses with the following queries:
 It allows powerful filtering of your data.
 
 Equal / Not Equal
------
+-----------------
 
 .. code-block:: python
 
@@ -132,3 +132,22 @@ Using multiple ``where`` clauses is equivalent to an AND.
     ).where(
         b.popularity < 1000
     ).run_sync()
+
+Using And / Or directly
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Rather than using the ``|`` and ``&`` characters, you can use the ``And`` and
+``Or`` classes, which are what's used under the hood.
+
+.. code-block:: python
+
+    from piccolo.columns.combination import And, Or
+
+    b = Band
+
+    b.select().where(
+        Or(
+            And(b.popularity >= 100, b.popularity < 1000),
+            b.name == 'Pythonistas'
+        )
+    ).run_sync()

docs/src/piccolo/query_types/update.rst

@@ -7,7 +7,7 @@ This is used to update any rows in the table which match the criteria.
 
 .. code-block:: python
 
-    >>> Band.update().values({
+    >>> Band.update({
     >>>     Band.name: 'Pythonistas 2'
     >>> }).where(
     >>>     Band.name == 'Pythonistas'

docs/src/piccolo/schema/column_types.rst

@@ -3,7 +3,8 @@
 Column Types
 ============
 
-.. hint:: You'll notice that all of the column names match their SQL equivalents.
+.. hint:: You'll notice that the column names tend to match their SQL
+    equivalents.
 
 Column
 ------
@@ -123,3 +124,16 @@ UUID
 
     class Band(Table):
         uuid = UUID()
+
+Secret
+------
+
+The database treats it the same as a Varchar, but Piccolo may treat it
+differently internally - for example, allowing a user to automatically omit any
+secret fields when doing a select query, to help prevent inadvertant leakage.
+A common use for a Secret field is a password.
+
+.. code-block:: python
+
+    class Band(Table):
+        password = Secret(length=100)

piccolo/commands/migration/new.py

@@ -1,16 +1,12 @@
 from __future__ import annotations
 import datetime
-import importlib
-import importlib.util
 import os
-import sys
 import typing as t
 from types import ModuleType
 
 import click
 
 from piccolo.migrations.template import TEMPLATE
-from piccolo.table import Table
 
 
 MIGRATION_MODULES: t.Dict[str, ModuleType] = {}
@@ -44,12 +40,6 @@ def _create_new_migration(migrations_path) -> None:
 ###############################################################################
 
 
-@click.option(
-    "-c",
-    "--create",
-    multiple=True,
-    help="Path to a table class which you want to create, e.g. tables.Band",
-)
 @click.option(
     "-p",
     "--path",
@@ -66,17 +56,5 @@ def new(create: t.Tuple[str], path: str):
     root_dir = path if path else os.getcwd()
     migrations_path = os.path.join(root_dir, "migrations")
 
-    # TODO - might remove this. Does nothing currently.
-    for path in create:
-        module_path, table_name = path.rsplit(".", maxsplit=1)
-        module = importlib.import_module(module_path)
-        try:
-            table_class: Table = getattr(module, table_name)
-        except AttributeError:
-            print(f"Unable to find {path} - aborting")
-            sys.exit(1)
-
-        print(table_class._table_str())
-
     _create_migrations_folder(migrations_path)
     _create_new_migration(migrations_path)