Add a demonstrational notebook and prepare for notebook usage

.pre-commit-config.yaml

@@ -64,9 +64,14 @@ repos:
     hooks:
     -   id: vulture
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.15.0
+    rev: v1.16.0
     hooks:
     -   id: mypy
+        exclude: >
+          (?x)(
+              test_convert\.py$ |
+              cytotable_mise_en_place\.py$
+          )
 -   repo: https://github.com/citation-file-format/cffconvert
     rev: 5295f87c0e261da61a7b919fc754e3a77edd98a7
     hooks:

cytotable/__init__.py

@@ -5,6 +5,18 @@
 # note: version data is maintained by poetry-dynamic-versioning (do not edit)
 __version__ = "0.0.0"
 
+# filter warnings about pkg_resources deprecation
+# note: these stem from cloudpathlib google cloud
+# dependencies.
+import warnings
+
+warnings.filterwarnings(
+    "ignore",
+    message=(".*pkg_resources is deprecated as an API.*"),
+    category=UserWarning,
+    module="google_crc32c.__config__",
+)
+
 from .convert import convert
 from .exceptions import (
     CytoTableException,

cytotable/utils.py

@@ -166,12 +166,6 @@ def _duckdb_reader() -> duckdb.DuckDBPyConnection:
         https://duckdb.org/docs/sql/configuration#configuration-reference
         */
         PRAGMA preserve_insertion_order=FALSE;
-
-        /*
-        Disable progress bar from displaying (defaults to TRUE)
-        See earlier documentation references above for more information.
-        */
-        SET enable_progress_bar=FALSE;
         """,
     )
 

docs/source/conf.py

@@ -33,13 +33,16 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "myst_parser",
+    "myst_nb",
     "sphinxcontrib.mermaid",
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
 ]
 
+# turn off notebook execution for docs rendering
+nb_execution_mode = "off"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/source/examples.md

@@ -0,0 +1,7 @@
+# Examples
+
+The following example notebooks are provided to help you get started with CytoTable.
+
+```{toctree}
+examples/cytotable_mise_en_place
+```