Skip to content

Commit 3f04717

Browse files
authored
Add cross-reference notes between CLI and Python API documentation (#791)
1 parent 5e8822e commit 3f04717

2 files changed

Lines changed: 210 additions & 0 deletions

File tree

‎docs/cli.rst‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -424,6 +424,9 @@ The ``--functions`` option can be used multiple times to load functions from mul
424424
from urllib.parse import urlparse
425425
return urlparse(url).path'
426426
427+
.. note::
428+
In Python: :ref:`db.register_function() <python_api_register_function>`
429+
427430
.. _cli_query_extensions:
428431

429432
SQLite extensions
@@ -1024,6 +1027,9 @@ To show more than 10 common values, use ``--common-limit 20``. To skip the most
10241027
10251028
sqlite-utils analyze-tables github.db tags --common-limit 20 --no-least
10261029
1030+
.. note::
1031+
In Python: :ref:`table.analyze_column() <python_api_analyze_column>` CLI reference: :ref:`sqlite-utils analyze-tables <cli_ref_analyze_tables>`
1032+
10271033
.. _cli_analyze_tables_save:
10281034

10291035
Saving the analyzed table details
@@ -1191,6 +1197,9 @@ You can delete all the existing rows in the table before inserting the new recor
11911197
11921198
You can add the ``--analyze`` option to run ``ANALYZE`` against the table after the rows have been inserted.
11931199

1200+
.. note::
1201+
In Python: :ref:`table.insert_all() <python_api_bulk_inserts>` CLI reference: :ref:`sqlite-utils insert <cli_ref_insert>`
1202+
11941203
.. _cli_inserting_data_binary:
11951204

11961205
Inserting binary data
@@ -1615,6 +1624,9 @@ To replace a dog with in ID of 2 with a new record, run the following:
16151624
echo '{"id": 2, "name": "Pancakes", "age": 3}' | \
16161625
sqlite-utils insert dogs.db dogs - --pk=id --replace
16171626
1627+
.. note::
1628+
In Python: :ref:`table.insert(..., replace=True) <python_api_insert_replace>` CLI reference: :ref:`sqlite-utils insert <cli_ref_insert>`
1629+
16181630
.. _cli_upsert:
16191631

16201632
Upserting data
@@ -1641,6 +1653,9 @@ The command will fail if you reference columns that do not exist on the table. T
16411653
``upsert`` in sqlite-utils 1.x worked like ``insert ... --replace`` does in 2.x. See `issue #66 <https://github.com/simonw/sqlite-utils/issues/66>`__ for details of this change.
16421654

16431655

1656+
.. note::
1657+
In Python: :ref:`table.upsert() <python_api_upsert>` CLI reference: :ref:`sqlite-utils upsert <cli_ref_upsert>`
1658+
16441659
.. _cli_bulk:
16451660

16461661
Executing SQL in bulk
@@ -1842,6 +1857,9 @@ You can include named parameters in your where clause and populate them using on
18421857
18431858
The ``--dry-run`` option will output a preview of the conversion against the first ten rows, without modifying the database.
18441859

1860+
.. note::
1861+
In Python: :ref:`table.convert() <python_api_convert>` CLI reference: :ref:`sqlite-utils convert <cli_ref_convert>`
1862+
18451863
.. _cli_convert_import:
18461864

18471865
Importing additional modules
@@ -2140,6 +2158,9 @@ If a table with the same name already exists, you will get an error. You can cho
21402158

21412159
You can also pass ``--transform`` to transform the existing table to match the new schema. See :ref:`python_api_explicit_create` in the Python library documentation for details of how this option works.
21422160

2161+
.. note::
2162+
In Python: :ref:`table.create() <python_api_explicit_create>` CLI reference: :ref:`sqlite-utils create-table <cli_ref_create_table>`
2163+
21432164
.. _cli_renaming_tables:
21442165

21452166
Renaming a table
@@ -2153,6 +2174,9 @@ Yo ucan rename a table using the ``rename-table`` command:
21532174
21542175
Pass ``--ignore`` to ignore any errors caused by the table not existing, or the new name already being in use.
21552176

2177+
.. note::
2178+
In Python: :ref:`db.rename_table() <python_api_rename_table>` CLI reference: :ref:`sqlite-utils rename-table <cli_ref_rename_table>`
2179+
21562180
.. _cli_duplicate_table:
21572181

21582182
Duplicating tables
@@ -2164,6 +2188,9 @@ The ``duplicate`` command duplicates a table - creating a new table with the sam
21642188
21652189
sqlite-utils duplicate books.db authors authors_copy
21662190
2191+
.. note::
2192+
In Python: :ref:`table.duplicate() <python_api_duplicate>` CLI reference: :ref:`sqlite-utils duplicate <cli_ref_duplicate>`
2193+
21672194
.. _cli_drop_table:
21682195

21692196
Dropping tables
@@ -2177,6 +2204,9 @@ You can drop a table using the ``drop-table`` command:
21772204
21782205
Use ``--ignore`` to ignore the error if the table does not exist.
21792206

2207+
.. note::
2208+
In Python: :ref:`table.drop() <python_api_drop>` CLI reference: :ref:`sqlite-utils drop-table <cli_ref_drop_table>`
2209+
21802210
.. _cli_transform_table:
21812211

21822212
Transforming tables
@@ -2260,6 +2290,9 @@ If you want to see the SQL that will be executed to make the change without actu
22602290
DROP TABLE "roadside_attractions";
22612291
ALTER TABLE "roadside_attractions_new_4033a60276b9" RENAME TO "roadside_attractions";
22622292
2293+
.. note::
2294+
In Python: :ref:`table.transform() <python_api_transform>` CLI reference: :ref:`sqlite-utils transform <cli_ref_transform>`
2295+
22632296
.. _cli_transform_table_add_primary_key_to_rowid:
22642297

22652298
Adding a primary key to a rowid table
@@ -2437,6 +2470,9 @@ After running the above, the command ``sqlite-utils schema global.db`` reveals t
24372470
CREATE UNIQUE INDEX "idx_countries_country_name"
24382471
ON "countries" ("country", "name");
24392472
2473+
.. note::
2474+
In Python: :ref:`table.extract() <python_api_extract>` CLI reference: :ref:`sqlite-utils extract <cli_ref_extract>`
2475+
24402476
.. _cli_create_view:
24412477

24422478
Creating views
@@ -2458,6 +2494,9 @@ You can create a view using the ``create-view`` command:
24582494
24592495
Use ``--replace`` to replace an existing view of the same name, and ``--ignore`` to do nothing if a view already exists.
24602496

2497+
.. note::
2498+
In Python: :ref:`db.create_view() <python_api_create_view>` CLI reference: :ref:`sqlite-utils create-view <cli_ref_create_view>`
2499+
24612500
.. _cli_drop_view:
24622501

24632502
Dropping views
@@ -2471,6 +2510,9 @@ You can drop a view using the ``drop-view`` command:
24712510
24722511
Use ``--ignore`` to ignore the error if the view does not exist.
24732512

2513+
.. note::
2514+
In Python: :ref:`view.drop() <python_api_drop>` CLI reference: :ref:`sqlite-utils drop-view <cli_ref_drop_view>`
2515+
24742516
.. _cli_add_column:
24752517

24762518
Adding columns
@@ -2511,6 +2553,9 @@ You can set a ``NOT NULL DEFAULT 'x'`` constraint on the new column using ``--no
25112553
25122554
sqlite-utils add-column mydb.db dogs friends_count integer --not-null-default 0
25132555
2556+
.. note::
2557+
In Python: :ref:`table.add_column() <python_api_add_column>` CLI reference: :ref:`sqlite-utils add-column <cli_ref_add_column>`
2558+
25142559
.. _cli_add_column_alter:
25152560

25162561
Adding columns automatically on insert/update
@@ -2522,6 +2567,9 @@ You can use the ``--alter`` option to automatically add new columns if the data
25222567
25232568
sqlite-utils insert dogs.db dogs new-dogs.json --pk=id --alter
25242569
2570+
.. note::
2571+
In Python: :ref:`table.insert(..., alter=True) <python_api_add_column_alter>`
2572+
25252573
.. _cli_add_foreign_key:
25262574

25272575
Adding foreign key constraints
@@ -2549,6 +2597,9 @@ Add ``--ignore`` to ignore an existing foreign key (as opposed to returning an e
25492597
25502598
See :ref:`python_api_add_foreign_key` in the Python API documentation for further details, including how the automatic table guessing mechanism works.
25512599

2600+
.. note::
2601+
In Python: :ref:`table.add_foreign_key() <python_api_add_foreign_key>` CLI reference: :ref:`sqlite-utils add-foreign-key <cli_ref_add_foreign_key>`
2602+
25522603
.. _cli_add_foreign_keys:
25532604

25542605
Adding multiple foreign keys at once
@@ -2564,6 +2615,9 @@ Adding a foreign key requires a ``VACUUM``. On large databases this can be an ex
25642615
25652616
When you are using this command each foreign key needs to be defined in full, as four arguments - the table, column, other table and other column.
25662617

2618+
.. note::
2619+
In Python: :ref:`db.add_foreign_keys() <python_api_add_foreign_keys>` CLI reference: :ref:`sqlite-utils add-foreign-keys <cli_ref_add_foreign_keys>`
2620+
25672621
.. _cli_index_foreign_keys:
25682622

25692623
Adding indexes for all foreign keys
@@ -2575,6 +2629,9 @@ If you want to ensure that every foreign key column in your database has a corre
25752629
25762630
sqlite-utils index-foreign-keys books.db
25772631
2632+
.. note::
2633+
In Python: :ref:`db.index_foreign_keys() <python_api_index_foreign_keys>` CLI reference: :ref:`sqlite-utils index-foreign-keys <cli_ref_index_foreign_keys>`
2634+
25782635
.. _cli_defaults_not_null:
25792636

25802637
Setting defaults and not null constraints
@@ -2590,6 +2647,9 @@ You can use the ``--not-null`` and ``--default`` options (to both ``insert`` and
25902647
--default age 2 \
25912648
--default score 5
25922649
2650+
.. note::
2651+
In Python: :ref:`not_null= and defaults= arguments <python_api_defaults_not_null>`
2652+
25932653
.. _cli_create_index:
25942654

25952655
Creating indexes
@@ -2621,6 +2681,9 @@ If your column names are already prefixed with a hyphen you'll need to manually
26212681

26222682
Add the ``--analyze`` option to run ``ANALYZE`` against the index after it has been created.
26232683

2684+
.. note::
2685+
In Python: :ref:`table.create_index() <python_api_create_index>` CLI reference: :ref:`sqlite-utils create-index <cli_ref_create_index>`
2686+
26242687
.. _cli_drop_index:
26252688

26262689
Dropping indexes
@@ -2634,6 +2697,9 @@ You can drop an index from an existing table using the ``drop-index`` command:
26342697
26352698
Use ``--ignore`` to ignore the error if the index does not exist on that table.
26362699

2700+
.. note::
2701+
In Python: :ref:`table.drop_index() <python_api_create_index>` CLI reference: :ref:`sqlite-utils drop-index <cli_ref_drop_index>`
2702+
26372703
.. _cli_fts:
26382704

26392705
Configuring full-text search
@@ -2687,6 +2753,9 @@ You can rebuild every FTS table by running ``rebuild-fts`` without passing any t
26872753
26882754
sqlite-utils rebuild-fts mydb.db
26892755
2756+
.. note::
2757+
In Python: :ref:`table.enable_fts() <python_api_fts_enable>` CLI reference: :ref:`sqlite-utils enable-fts <cli_ref_enable_fts>`
2758+
26902759
.. _cli_search:
26912760

26922761
Executing searches
@@ -2743,6 +2812,9 @@ Use the ``--sql`` option to output the SQL that would be executed, rather than r
27432812
order by
27442813
"documents_fts".rank
27452814
2815+
.. note::
2816+
In Python: :ref:`table.search() <python_api_fts_search>` CLI reference: :ref:`sqlite-utils search <cli_ref_search>`
2817+
27462818
.. _cli_enable_counts:
27472819

27482820
Enabling cached counts
@@ -2766,6 +2838,9 @@ If the ``_counts`` table ever becomes out-of-sync with the actual table counts y
27662838
27672839
sqlite-utils reset-counts mydb.db
27682840
2841+
.. note::
2842+
In Python: :ref:`table.enable_counts() <python_api_cached_table_counts>` CLI reference: :ref:`sqlite-utils enable-counts <cli_ref_enable_counts>`
2843+
27692844
.. _cli_analyze:
27702845

27712846
Optimizing index usage with ANALYZE
@@ -2789,6 +2864,9 @@ You can run it against specific tables, or against specific named indexes, by pa
27892864
27902865
You can also run ``ANALYZE`` as part of another command using the ``--analyze`` option. This is supported by the ``create-index``, ``insert`` and ``upsert`` commands.
27912866

2867+
.. note::
2868+
In Python: :ref:`db.analyze() <python_api_analyze>` CLI reference: :ref:`sqlite-utils analyze <cli_ref_analyze>`
2869+
27922870
.. _cli_vacuum:
27932871

27942872
Vacuum
@@ -2800,6 +2878,9 @@ You can run VACUUM to optimize your database like so:
28002878
28012879
sqlite-utils vacuum mydb.db
28022880
2881+
.. note::
2882+
In Python: :ref:`db.vacuum() <python_api_vacuum>` CLI reference: :ref:`sqlite-utils vacuum <cli_ref_vacuum>`
2883+
28032884
.. _cli_optimize:
28042885

28052886
Optimize
@@ -2823,6 +2904,9 @@ To optimize specific tables rather than every FTS table, pass those tables as ex
28232904
28242905
sqlite-utils optimize mydb.db table_1 table_2
28252906
2907+
.. note::
2908+
In Python: :ref:`table.optimize() <python_api_fts_optimize>` CLI reference: :ref:`sqlite-utils optimize <cli_ref_optimize>`
2909+
28262910
.. _cli_wal:
28272911

28282912
WAL mode
@@ -2842,6 +2926,9 @@ You can disable WAL mode using ``disable-wal``:
28422926
28432927
Both of these commands accept one or more database files as arguments.
28442928

2929+
.. note::
2930+
In Python: :ref:`db.enable_wal() and db.disable_wal() <python_api_wal>` CLI reference: :ref:`sqlite-utils enable-wal <cli_ref_enable_wal>`
2931+
28452932
.. _cli_dump:
28462933

28472934
Dumping the database to SQL
@@ -2857,6 +2944,9 @@ The ``dump`` command outputs a SQL dump of the schema and full contents of the s
28572944
...
28582945
COMMIT;
28592946
2947+
.. note::
2948+
In Python: :ref:`db.iterdump() <python_api_itedump>` CLI reference: :ref:`sqlite-utils dump <cli_ref_dump>`
2949+
28602950
.. _cli_load_extension:
28612951

28622952
Loading SQLite extensions
@@ -2904,6 +2994,9 @@ Eight (case-insensitive) types are allowed:
29042994
* GEOMETRYCOLLECTION
29052995
* GEOMETRY
29062996

2997+
.. note::
2998+
In Python: :ref:`table.add_geometry_column() <python_api_gis_add_geometry_column>` CLI reference: :ref:`sqlite-utils add-geometry-column <cli_ref_add_geometry_column>`
2999+
29073000
.. _cli_spatialite_indexes:
29083001

29093002
Adding spatial indexes
@@ -2917,6 +3010,9 @@ Once you have a geometry column, you can speed up bounding box queries by adding
29173010
29183011
See this `SpatiaLite Cookbook recipe <http://www.gaia-gis.it/gaia-sins/spatialite-cookbook-5/cookbook_topics.03.html#topic_Wonderful_RTree_Spatial_Index>`__ for examples of how to use a spatial index.
29193012

3013+
.. note::
3014+
In Python: :ref:`table.create_spatial_index() <python_api_gis_create_spatial_index>` CLI reference: :ref:`sqlite-utils create-spatial-index <cli_ref_create_spatial_index>`
3015+
29203016
.. _cli_install:
29213017

29223018
Installing packages

0 commit comments

Comments
 (0)