cleaned up the docs

dantownsend · dantownsend · commit ccc93b7623ed · 2019-09-12T20:47:12.000+01:00
diff --git a/dev-requirements.txt b/dev-requirements.txt
@@ -1,4 +1,4 @@
 ipdb==0.11
-ipython==7.1.1
+ipython==7.8.0
 twine==1.12.1
 mypy==0.720
diff --git a/docs/src/index.rst b/docs/src/index.rst
@@ -2,7 +2,7 @@ Welcome to Piccolo's documentation!
 ===================================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
    piccolo/getting_started/index
@@ -14,8 +14,8 @@ Welcome to Piccolo's documentation!
    piccolo/authentication/index
    piccolo/features/index
    piccolo/playground/index
-   piccolo/articles/index
    piccolo/ecosystem/index
+   piccolo/contributing/index
 
 Indices and tables
 ==================
diff --git a/docs/src/piccolo/articles/index.rst b/docs/src/piccolo/articles/index.rst
diff --git a/docs/src/piccolo/articles/tuning_postgres.rst b/docs/src/piccolo/articles/tuning_postgres.rst
diff --git a/docs/src/piccolo/contributing/index.rst b/docs/src/piccolo/contributing/index.rst
@@ -0,0 +1,29 @@
+.. _Contributing:
+
+Contributing
+============
+
+If you want to dig deeper into the Piccolo internals, follow these
+instructions.
+
+Get the tests running
+---------------------
+
+ * Create a new virtualenv
+ * Clone the `Git repo <https://github.com/piccolo-orm/piccolo>`_.
+ * Install the dependencies: ``pip install -r requirements.txt``.
+ * ``cd tests``
+ * Install the test dependencies: ``pip install -r test-requirements.txt``.
+ * Setup Postgres
+ * Run the tests: ``./run-tests.sh``
+
+Contributing to the docs
+------------------------
+
+The docs are written using Sphinx. To get them running locally:
+
+ * ``cd docs``
+ * Install the requirements: ``pip install -r doc-requirements.txt``
+ * Do an initial build of the docs: ``make html``
+ * Serve the docs: ``python serve_docs.py``
+ * The docs will auto rebuild as you make changes.
diff --git a/docs/src/piccolo/features/index.rst b/docs/src/piccolo/features/index.rst
@@ -6,3 +6,5 @@ Features
 
     ./tab_completion
     ./supported_databases
+    ./security
+    ./syntax
diff --git a/docs/src/piccolo/features/security.rst b/docs/src/piccolo/features/security.rst
@@ -0,0 +1,12 @@
+.. _Security:
+
+Security
+========
+
+SQL Injection protection
+------------------------
+
+If you look under the hood, Piccolo uses a custom class called `QueryString`
+for composing queries. It keeps query parameters separate from the query
+string, so we can pass parameterised queries to the engine. This helps
+prevent SQL Injection attacks.
diff --git a/docs/src/piccolo/features/supported_databases.rst b/docs/src/piccolo/features/supported_databases.rst
@@ -8,4 +8,5 @@ will be using in production.
 
 SQLite
 ------
-SQLite support is not as complete as Postgres, but it is available.
+SQLite support is not as complete as Postgres, but it is available - mostly
+because it's easy to setup.
diff --git a/docs/src/piccolo/features/syntax.rst b/docs/src/piccolo/features/syntax.rst
@@ -1,5 +1,5 @@
-Design Decisions
-================
+Syntax
+======
 
 As close as possible to SQL
 ---------------------------
diff --git a/docs/src/piccolo/features/tab_completion.rst b/docs/src/piccolo/features/tab_completion.rst
@@ -3,7 +3,7 @@
 Tab Completion
 ==============
 
-Why is tab completion useful?
-------------------------------
+Piccolo does everything possible to support tab completion. It has been tested
+with iPython and VSCode.
 
-...
+To find out more about how it was done, read `this article <https://piccolo-orm.com/blog/improving-tab-completion-in-python-libraries>`_
diff --git a/docs/src/piccolo/playground/index.rst b/docs/src/piccolo/playground/index.rst
@@ -1,6 +1,9 @@
 Playground
 ==========
 
+Piccolo ships with a handy command to help learn the different queries. For
+simple usage see :ref:`Playground`.
+
 .. toctree::
     :maxdepth: 1
 
diff --git a/docs/src/piccolo/query_types/objects.rst b/docs/src/piccolo/query_types/objects.rst
@@ -29,7 +29,7 @@ columns.
 Saving objects
 --------------
 
-Objects have a save method, which is convenient for updating values:
+Objects have a `save` method, which is convenient for updating values:
 
 .. code-block:: python
 
@@ -41,6 +41,20 @@ Objects have a save method, which is convenient for updating values:
     pythonistas.popularity = 100000
     pythonistas.save().run_sync()
 
+Deleting objects
+----------------
+
+Similarly, we can delete objects, using the `remove` method.
+
+.. code-block:: python
+
+    # To get certain rows:
+    pythonistas = Band.objects().where(
+        Band.name == 'Pythonistas'
+    ).first().run_sync()
+
+    pythonistas.remove().run_sync()
+
 order_by
 --------
 
diff --git a/docs/src/piccolo/schema/column_types.rst b/docs/src/piccolo/schema/column_types.rst
@@ -23,7 +23,12 @@ default
 null
 ~~~~
 
-...
+Whether the column is nullable.
+
+.. code-block:: python
+
+    class Band(Table):
+        name = Varchar(default="hello", null=False)
 
 Varchar
 -------
@@ -36,6 +41,8 @@ Varchar
 ForeignKey
 ----------
 
+`ForeignKey` takes a `Table` argument.
+
 .. code-block:: python
 
     class Band(Table):
diff --git a/piccolo/querystring.py b/piccolo/querystring.py
@@ -6,24 +6,33 @@
 
 
 @dataclass
-class Unquoted():
+class Unquoted:
     """
     Used when we want the value to be unquoted because it's a Postgres
     keyword - for example DEFAULT.
     """
+
     value: str
 
 
 @dataclass
-class Fragment():
+class Fragment:
     prefix: str
     index: int = 0
     no_arg: bool = False
 
 
-class QueryString():
+class QueryString:
+    """
+    When we're composing complex queries, we're combining QueryStrings, rather
+    than concatenating strings directly. The reason for this is QueryStrings
+    keep the parameters separate, so we can pass parameterised queries to the
+    engine - which helps prevent SQL Injection attacks.
+    """
 
-    def __init__(self, template: str, *args: t.Any, query_type: str = 'generic') -> None:
+    def __init__(
+        self, template: str, *args: t.Any, query_type: str = "generic"
+    ) -> None:
         """
         Example template: "WHERE {} = {}"
 
@@ -40,13 +49,14 @@ def __str__(self):
         - it's just a usability feature.
         """
         _, bundled, combined_args = self.bundle(
-            start_index=1,
-            bundled=[],
-            combined_args=[]
+            start_index=1, bundled=[], combined_args=[]
+        )
+        template = "".join(
+            [
+                fragment.prefix + ("" if fragment.no_arg else "{}")
+                for fragment in bundled
+            ]
         )
-        template = ''.join([
-            fragment.prefix + ('' if fragment.no_arg else '{}') for fragment in bundled
-        ])
 
         # Do some basic type conversion here.
         converted_args = []
@@ -55,10 +65,10 @@ def __str__(self):
             if _type == str:
                 converted_args.append(f"'{arg}'")
             elif _type == datetime:
-                dt_string = arg.isoformat().replace('T', ' ')
+                dt_string = arg.isoformat().replace("T", " ")
                 converted_args.append(f"'{dt_string}'")
             elif arg == None:
-                converted_args.append('null')
+                converted_args.append("null")
             else:
                 converted_args.append(arg)
 
@@ -96,27 +106,31 @@ def bundle(self, start_index=1, bundled=[], combined_args=[]):
         return (start_index, bundled, combined_args)
 
     def compile_string(
-        self,
-        engine_type: str = 'postgres'
+        self, engine_type: str = "postgres"
     ) -> t.Tuple[str, t.List[t.Any]]:
         """
-        Compiles the template ready for Postgres - keeping the arguments
+        Compiles the template ready for the engine - keeping the arguments
         separate from the template.
         """
         _, bundled, combined_args = self.bundle(
-            start_index=1,
-            bundled=[],
-            combined_args=[]
+            start_index=1, bundled=[], combined_args=[]
         )
-        if engine_type == 'postgres':
-            string = ''.join([
-                fragment.prefix + ('' if fragment.no_arg else f'${fragment.index}') for fragment in bundled
-            ])
-        elif engine_type == 'sqlite':
-            string = ''.join([
-                fragment.prefix + ('' if fragment.no_arg else '?') for fragment in bundled
-            ])
+        if engine_type == "postgres":
+            string = "".join(
+                [
+                    fragment.prefix
+                    + ("" if fragment.no_arg else f"${fragment.index}")
+                    for fragment in bundled
+                ]
+            )
+        elif engine_type == "sqlite":
+            string = "".join(
+                [
+                    fragment.prefix + ("" if fragment.no_arg else "?")
+                    for fragment in bundled
+                ]
+            )
         else:
-            raise Exception('Engine type not recognised')
+            raise Exception("Engine type not recognised")
 
         return (string, combined_args)
diff --git a/piccolo/table.py b/piccolo/table.py
@@ -208,7 +208,7 @@ def querystring(self) -> QueryString:
 
         # Strip out any args which are unquoted.
         # TODO Not the cleanest place to have it (would rather have it handled
-        # in the Querystring bundle logic) - might need refactoring.
+        # in the QueryString bundle logic) - might need refactoring.
         filtered_args = [i for i in args_dict.values() if not is_unquoted(i)]
 
         # If unquoted, dump it straight into the query.
diff --git a/tests/query/test_querystring.py b/tests/query/test_querystring.py
@@ -4,46 +4,33 @@
 
 
 # TODO - add more extensive tests (increased nesting and argument count).
-class TestQuerystring(TestCase):
+class TestQueryString(TestCase):
 
     qs = QueryString(
-        'SELECT id FROM band {}',
-        QueryString(
-            "WHERE name = {}",
-            'Pythonistas'
-        )
+        "SELECT id FROM band {}", QueryString("WHERE name = {}", "Pythonistas")
     )
 
     def test_compile_string(self):
         compiled_string, args = self.qs.compile_string()
 
         self.assertEqual(
-            compiled_string,
-            "SELECT id FROM band WHERE name = $1"
+            compiled_string, "SELECT id FROM band WHERE name = $1"
         )
 
-        self.assertEqual(
-            args,
-            ['Pythonistas']
-        )
+        self.assertEqual(args, ["Pythonistas"])
 
     def test_string(self):
         string = self.qs.__str__()
         self.assertEqual(
-            string,
-            "SELECT id FROM band WHERE name = 'Pythonistas'"
+            string, "SELECT id FROM band WHERE name = 'Pythonistas'"
         )
 
     def test_querystring_with_no_args(self):
-        qs = QueryString(
-            'SELECT name FROM band',
-        )
-        self.assertEqual(
-            qs.compile_string(),
-            ('SELECT name FROM band', [])
-        )
+        qs = QueryString("SELECT name FROM band")
+        self.assertEqual(qs.compile_string(), ("SELECT name FROM band", []))
+
 
-# class TestExecuteQuerystring(TestCase):
+# class TestExecuteQueryString(TestCase):
 
 #     def setUp():
 #         Band.create().run_sync()
