Expand README; prepare release (#41)

.github/workflows/test.yml

@@ -25,6 +25,9 @@ jobs:
         - name: py310
           python: '3.10'
           toxenv: py310
+        - name: py311
+          python: '3.11-dev'
+          toxenv: py311
         - name: black
           python: '3.9'
           toxenv: black
@@ -33,9 +36,9 @@ jobs:
           toxenv: pyanalyze
 
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v3
     - name: Set up Python ${{ matrix.python }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python }}
     - name: Install dependencies

README.md

@@ -1,14 +1,13 @@
 # sqltree
 
-sqltree is an experimental parser for SQL, providing
+`sqltree` is an experimental parser for SQL, providing
 a syntax tree for SQL queries. Possible use cases include:
 
 - Static analysis (for example, to validate column names)
 - Translating queries to another SQL dialect
 - Autoformatting
 
-sqltree is in an early stage of development, but it
-can parse basic queries:
+`sqltree` can parse queries:
 
 ```
 $ python -m sqltree "SELECT * FROM x WHERE x = 3"
@@ -24,6 +23,44 @@ FROM x
 WHERE x = 3
 ```
 
+SQL is a big language with a complicated grammar that varies significantly
+between database vendors. `sqltree` is designed to be flexible enough to parse
+the full syntax supported by different databases, but I am prioritizing
+constructs used in my use cases for the parser. So far, that has meant a focus
+on parsing MySQL 8 queries. Further syntax will be added as I have time.
+
+## Features
+
+Useful features of `sqltree` include:
+
+### Placeholder support
+
+`sqltree` supports placeholders such as `%s` or `?` in various positions in
+the query, so that queries using such placeholders can be formatted and analyzed.
+
+```shell
+$ python -m sqltree.formatter 'select * from x where y = 3 %(limit)s'
+SELECT *
+FROM x
+WHERE y = 3
+%(limit)s
+```
+
+### Better error messages
+
+`sqltree`'s handwritten parser often produces better error messages than MySQL
+itself. For example:
+
+```shell
+$ mysql
+mysql> show replicca status;
+ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'replicca status' at line 1
+$ python -m sqltree 'show replicca status'
+Unexpected 'replicca' (expected one of REPLICA, SLAVE, REPLICAS, TABLES, TABLE, TRIGGERS, VARIABLES, STATUS, COUNT, WARNINGS, ERRORS, COLUMNS, FIELDS, INDEX, INDEXES, KEYS)
+0: show replicca status
+        ^^^^^^^^
+```
+
 ## API
 
 - `sqltree.sqltree`: parse a SQL query and return the parse tree. See `sqltree.parser`
@@ -33,6 +70,10 @@ WHERE x = 3
 
 More detailed documentation to follow.
 
+## Requirements
+
+`sqltree` runs on Python 3.6 and up and it has no dependencies.
+
 ## Using the fixit rule
 
 sqltree embeds a [fixit](https://fixit.readthedocs.io/en/latest/) rule for
@@ -42,3 +83,9 @@ formatting SQL. Here is how to use it:
   - `pip install fixit`
   - `python -m fixit.cli.init_config`
 - Run `python -m fixit.cli.apply_fix --rules sqltree.fixit.SqlFormatRule path/to/your/code`
+
+## Changelog
+
+### Version 0.1.0 (June 13, 2022)
+
+- Initial release

sqltree/__init__.py

@@ -1,5 +1,5 @@
 """A SQL parser."""
 
-__version__ = "0.1b1"
+__version__ = "0.1.0"
 
 from .api import sqltree as sqltree

tox.ini

@@ -1,7 +1,7 @@
 [tox]
 isolated_build = True
 envlist =
-    py36,py37,py38,py39,py310,black,pyanalyze
+    py36,py37,py38,py39,py310,py311,black,pyanalyze
 
 [testenv]
 deps =
@@ -22,7 +22,7 @@ commands =
 deps =
     pytest
     fixit
-    pyanalyze==0.6.0
+    pyanalyze==0.7.0
 
 commands =
     python -m pyanalyze -v sqltree/ tests/