pointblank 0.9.4__tar.gz → 0.9.6__tar.gz

pointblank-0.9.6/.github/workflows/ci-docs.yaml

@@ -0,0 +1,111 @@
+name: CI Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build-docs:
+    name: "Build Docs"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install dependencies
+        run: |
+          python -m pip install -e .
+          python -m pip install ".[docs]"
+          python -m pip install ibis-framework[duckdb]
+          python -m pip install pins
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+      - name: Build docs
+        run: |
+          make docs-build
+      - name: Save docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_site
+
+  publish-docs:
+    name: "Publish Docs"
+    runs-on: ubuntu-latest
+    needs: "build-docs"
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_site
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_site
+  preview-docs:
+    name: "Preview Docs"
+    runs-on: ubuntu-latest
+    needs: "build-docs"
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_site
+
+      # start deployment ----
+      - name: Configure pull release name
+        if: ${{github.event_name == 'pull_request'}}
+        run: |
+          echo "RELEASE_NAME=pr-${PR_NUMBER}" >> $GITHUB_ENV
+        env:
+          PR_NUMBER: ${{ github.event.number }}
+      - name: Configure branch release name
+        if: ${{github.event_name != 'pull_request'}}
+        run: |
+          # use branch name, but replace slashes. E.g. feat/a -> feat-a
+          echo "RELEASE_NAME=${GITHUB_REF_NAME/\//-}" >> $GITHUB_ENV
+      # deploy ----
+      - name: Create Github Deployment
+        uses: bobheadxi/deployments@v1
+        id: deployment
+        if: ${{ !github.event.pull_request.head.repo.fork }}
+        with:
+          step: start
+          token: ${{ secrets.GITHUB_TOKEN }}
+          env: ${{ env.RELEASE_NAME }}
+          ref: ${{ github.head_ref }}
+          transient: true
+          logs: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+
+      - name: Netlify docs preview
+        if: ${{ !github.event.pull_request.head.repo.fork }}
+        run: |
+          npm install -g netlify-cli
+          # push main branch to production, others to preview --
+          netlify link --name="$PREVIEW_SITE"
+          if [ "${ALIAS}" == "main" ]; then
+            netlify deploy --dir=docs/_site --alias="main"
+          else
+            netlify deploy --dir=docs/_site --alias="${ALIAS}"
+          fi
+        env:
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_NAME: ${{ secrets.NETLIFY_SITE_NAME }}
+          ALIAS: ${{ steps.deployment.outputs.env }}
+
+      - name: Update Github Deployment
+        uses: bobheadxi/deployments@v1
+        if: ${{ !github.event.pull_request.head.repo.fork && always() }}
+        with:
+          step: finish
+          token: ${{ secrets.GITHUB_TOKEN }}
+          status: ${{ job.status }}
+          env: ${{ steps.deployment.outputs.env }}
+          env_url: "https://${{ steps.deployment.outputs.env }}--${{ secrets.NETLIFY_SITE_NAME }}.netlify.app"
+          deployment_id: ${{ steps.deployment.outputs.deployment_id }}

{pointblank-0.9.4 → pointblank-0.9.6}/.gitignore

@@ -124,3 +124,9 @@ datasets/
 /*.parquet
 /*.csv
 .ruff_cache
+
+# Benchmark results and reports
+benchmark/results/
+benchmark/reports/
+benchmark/data/*.csv.gz
+benchmark/data/*.json

{pointblank-0.9.4 → pointblank-0.9.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pointblank
-Version: 0.9.4
+Version: 0.9.6
 Summary: Find out if your data is what you think it is.
 Author-email: Richard Iannone <riannone@me.com>
 License: MIT License
@@ -55,6 +55,8 @@ Requires-Dist: chatlas>=0.3.0; extra == "generate"
 Requires-Dist: anthropic[bedrock]>=0.45.2; extra == "generate"
 Requires-Dist: openai>=1.63.0; extra == "generate"
 Requires-Dist: shiny>=1.3.0; extra == "generate"
+Provides-Extra: bigquery
+Requires-Dist: ibis-framework[bigquery]>=9.5.0; extra == "bigquery"
 Provides-Extra: databricks
 Requires-Dist: ibis-framework[databricks]>=9.5.0; extra == "databricks"
 Provides-Extra: duckdb
@@ -103,7 +105,7 @@ _Data validation made beautiful and powerful_
 
 </div>
 
-<div align="right">
+<div align="center">
    <a href="translations/README.fr.md">Français</a> |
    <a href="translations/README.de.md">Deutsch</a> |
    <a href="translations/README.it.md">Italiano</a> |
@@ -112,7 +114,9 @@ _Data validation made beautiful and powerful_
    <a href="translations/README.nl.md">Nederlands</a> |
    <a href="translations/README.zh-CN.md">简体中文</a> |
    <a href="translations/README.ja.md">日本語</a> |
-   <a href="translations/README.ko.md">한국어</a>
+   <a href="translations/README.ko.md">한국어</a> |
+   <a href="translations/README.hi.md">हिन्दी</a> |
+   <a href="translations/README.ar.md">العربية</a>
 </div>
 
 ## What is Pointblank?

{pointblank-0.9.4 → pointblank-0.9.6}/README.md

@@ -21,7 +21,7 @@ _Data validation made beautiful and powerful_
 
 </div>
 
-<div align="right">
+<div align="center">
    <a href="translations/README.fr.md">Français</a> |
    <a href="translations/README.de.md">Deutsch</a> |
    <a href="translations/README.it.md">Italiano</a> |
@@ -30,7 +30,9 @@ _Data validation made beautiful and powerful_
    <a href="translations/README.nl.md">Nederlands</a> |
    <a href="translations/README.zh-CN.md">简体中文</a> |
    <a href="translations/README.ja.md">日本語</a> |
-   <a href="translations/README.ko.md">한국어</a>
+   <a href="translations/README.ko.md">한국어</a> |
+   <a href="translations/README.hi.md">हिन्दी</a> |
+   <a href="translations/README.ar.md">العربية</a>
 </div>
 
 ## What is Pointblank?

{pointblank-0.9.4 → pointblank-0.9.6}/docs/_quarto.yml

@@ -31,6 +31,7 @@ website:
   search:
     show-item-context: true
   page-navigation: true
+  bread-crumbs: false
   favicon: assets/fav-logo.png
   site-url: https://posit-dev.github.io/pointblank/
   description: "Find out if your data is what you think it is"
@@ -55,15 +56,23 @@ website:
         - section: "Getting Started"
           contents:
             - user-guide/index.qmd
-            - user-guide/thresholds.qmd
-            - user-guide/actions.qmd
-        - section: "Defining Validation Steps"
+            - user-guide/installation.qmd
+        - section: "Validation Plan"
           contents:
-            - user-guide/types.qmd
-            - user-guide/columns.qmd
+            - user-guide/validation-overview.qmd
+            - user-guide/validation-methods.qmd
+            - user-guide/column-selection-patterns.qmd
             - user-guide/preprocessing.qmd
             - user-guide/segmentation.qmd
+            - user-guide/thresholds.qmd
+            - user-guide/actions.qmd
             - user-guide/briefs.qmd
+        - section: "Advanced Validation"
+          contents:
+            - user-guide/expressions.qmd
+            - user-guide/schema-validation.qmd
+            - user-guide/assertions.qmd
+            - user-guide/draft-validation.qmd
         - section: "Post Interrogation"
           contents:
             - user-guide/step-reports.qmd
@@ -90,7 +99,7 @@ quartodoc:
   sections:
     - title: Validate
       desc: >
-        When peforming data validation, you'll need the `Validate` class to get the process started.
+        When performing data validation, you'll need the `Validate` class to get the process started.
         It's given the target table and you can optionally provide some metadata and/or failure
         thresholds (using the `Thresholds` class or through shorthands for this task). The
         `Validate` class has numerous methods for defining validation steps and for obtaining
@@ -126,9 +135,9 @@ quartodoc:
         - name: Validate.col_vals_not_null
         - name: Validate.col_vals_regex
         - name: Validate.col_vals_expr
-        - name: Validate.col_exists
         - name: Validate.rows_distinct
         - name: Validate.rows_complete
+        - name: Validate.col_exists
         - name: Validate.col_schema_match
         - name: Validate.row_count_match
         - name: Validate.col_count_match
@@ -168,6 +177,8 @@ quartodoc:
         - name: Validate.get_data_extracts
         - name: Validate.all_passed
         - name: Validate.assert_passing
+        - name: Validate.assert_below_threshold
+        - name: Validate.above_threshold
         - name: Validate.n
         - name: Validate.n_passed
         - name: Validate.n_failed

pointblank-0.9.6/docs/blog/overhauled-user-guide/index.qmd

@@ -0,0 +1,154 @@
+---
+jupyter: python3
+html-table-processing: none
+title: Overhauling Pointblank's User Guide
+author: Rich Iannone and Michael Chow
+date: 2025-05-20
+freeze: true
+---
+
+```{python}
+#| echo: false
+#| output: false
+import pointblank as pb
+pb.config(report_incl_footer=False)
+```
+
+The Pointblank documentation just got a major upgrade! We've completely overhauled our
+[**User Guide**](../../user-guide/index.qmd). Our goal was to enable readers to start fast on
+validation and work through the many pieces needed in realistic situations.
+
+We realized that at the core of Pointblank is the validation plan. Its made up of rules, results,
+and steps.
+
+![](validation-three-things.png){width=80%}
+
+For example, the first row is a step that checks whether values in column 'a' are less than `10`.
+The `COLUMNS` and `VALUES` column contain the rules used to configure the step. The `PASS` column
+for the first row indicates that all 13 values in the column passed.
+
+In this post, we'll cover:
+
+- using a spiral sequence to balance introductory breadth with subsequent depth
+- improving examples with direct explanatory text
+- rounding out API coverage for cross-linking
+- surfacing advanced topics
+
+Let us walk you through the key improvements in our refreshed [**User Guide**](../../user-guide/index.qmd)!
+
+## Introduction: Embracing the Spiral Sequence
+
+We chose to use a spiral sequence for our [Introduction](../../user-guide/index.qmd) and
+*Validation Plan* section. The [Introduction](../../user-guide/index.qmd) quickly covers parts of
+validation plan, while each article of the *Validation Plan* section dives
+deeper into different aspects of defining validation rules.
+
+<div style="text-align: center;">
+
+![](breadth-and-depth.png){width=50%}
+
+</div>
+
+The introduction does a broad pass on the validation plan table diagram, identifying the core pieces
+of the output and then giving a quick overview of the code that produced it. This sets people up for
+the *Validation Plan* section in the guide, where each concept is discussed in depth.
+
+## Improving Examples
+
+Examples are everywhere in the [**User Guide**](../../user-guide/index.qmd). We've tightened up our
+approach to examples by:
+
+- presenting example code, output, or both, early in each section
+- showing the actual output you'll see in your environment
+- following up with explanatory text that guides attention to specific places in the output
+
+This approach makes learning more intuitive. Here's an excerpt that shows this in practice.
+
+![](explanation-of-visual.png){width=80%}
+
+The blue arrow marks the flow of reading and the red arrows map where we anticipate people will look
+from the text to the output. Focusing explicitly on where we think attention will go forces us to
+think carefully about exactly what readers will get from the output. The hope is that readers get to
+work more quickly on new concepts.
+
+## Rounding Out API Coverage
+
+Documentation has to balance jobs between a user guide and an API Reference:
+
+- User Guide: explains concepts that cut across functions (like common arguments across
+[validation methods](/user-guide/validation-methods.qmd))
+- API Reference: explains each individual function
+
+Importantly, user guides often link to the API reference so, as part of this work, we made sure that
+all individual API entries are well-documented and linked to from the guide.
+Here's an excerpt from the [**User Guide**](../../user-guide/index.qmd) that shows links marked:
+
+![](links-in-guide.png){width=80%}
+
+## Surfacing Advanced Topics
+
+There's a lot of potential slicing and dicing involved in validation, as well as work after
+validation (post interrogation) to make sense of the results. We added pages to the
+[**User Guide**](../../user-guide/index.qmd) for some core situations.
+In this section, I'll highlight two advanced topics we added pages for:
+
+- segmentation: splitting a column into groups, and validating each group
+- step reports: view failing cases (e.g., view rows of data that failed validation)
+
+These are marked in the [**User Guide**](../../user-guide/index.qmd) sidebar screenshot below:
+
+<div style="text-align: center;">
+
+![](advanced-in-sidebar.png){width=35%}
+
+</div>
+
+### Segmentation
+
+Here's a screenshot of a validation report with two validation steps, one for each segment (`"low"`
+and `"high"`) in the `f` column of the `small_table` dataset.
+
+![](segments.png){width=80%}
+
+Notice that segments split columns into groups and apply the same validation to each of the groups.
+Each group is given its own step.
+
+Each of the 20+ validation methods accept a `segment=` argument. The value of the
+[Segmentation article in the User Guide](../../user-guide/segmentation.qmd) is to describe this
+cross-cutting behavior in a single place.
+
+Compare the `segments=` parameter in the API Reference (e.g., look at
+[`col_vals_gt()`](../../reference/Validate.col_vals_gt.qmd)) and the
+[Segmentation article](../../user-guide/segmentation.qmd) to get a feel for how each location
+documents the segments feature.
+
+### Step Report
+
+Step reports display failing cases (e.g., rows) for a validation step, so you can dig deeper into
+validation failures. Here's a screenshot of a step report for some validation step 2:
+
+![](step-report.png){width=80%}
+
+Notice the arrow pointing to 'Step 2' in the title. Failing values are highlighted in red. Once we
+know we have failures, it's important to take action and discover *why* data is failing. Looking at
+failing cases in step reports often uncovers obvious causes behind failures.
+
+The `get_step_report()` entry is one of 50 in the API Reference. Here it is listed the API
+Reference, in the [Interrogation and Reporting section](../../reference/index.qmd#interrogation-and-reporting).
+Critically, it's only one of 20 entries in the [User Guide](../../user-guide/index.qmd), which
+emphasizes its importance in validation workflows.
+
+## Looking Forward
+
+The refreshed **User Guide** is just the beginning of our documentation improvements. We're
+committed to continuously enhancing our documentation to support your data validation needs.
+
+Michael Chow gave feedback on this **User Guide** in preparation for his
+[upcoming talk at SciPy 2025](https://cfp.scipy.org/scipy2025/talk/NRMNDX/).
+
+We'd love to hear your feedback on the new User Guide! Feel free to open an issue on our
+[GitHub repository](https://github.com/posit-dev/pointblank/issues) with suggestions, corrections,
+or requests for additional topics you'd like to see covered. You can also join our community
+discussions in the dedicated `#Documentation` channel on our
+[Discord server](https://discord.com/invite/YH7CybCNCQ), where you can share ideas, ask questions,
+and get help directly from the Pointblank team and other users.

{pointblank-0.9.4 → pointblank-0.9.6}/docs/styles.css

@@ -9,7 +9,7 @@
 }
 
 body {
-    background-color: #F7F8FC;
+    background-color: #FCFEFF;
 }
 
 p a {
@@ -42,6 +42,20 @@ p,h1,h2,h3,#toc-title,#toc-function-reference,.nav-link,.table {
     font-family: "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
 }
 
+.cell-output.cell-output-stdout {
+    border-style: solid;
+    border-width: 1px;
+    border-color: #A1A1A165;
+    border-radius: 4px;
+    padding: 0.4em;
+    background-color: #F7F1EB65;
+    margin-bottom: 12px;
+}
+
+summary::marker {
+  font-size: 1.5em;
+}
+
 [id^=validation-steps] td a:after {
     content: "()"
 }
@@ -54,6 +68,22 @@ p,h1,h2,h3,#toc-title,#toc-function-reference,.nav-link,.table {
     content: "()"
 }
 
+[id^=inspection-and-assistance] td a:after {
+    content: "()"
+}
+
+[id^=utility-functions] td a:after {
+    content: "()"
+}
+
+[id^=prebuilt-actions] td a:after {
+    content: "()"
+}
+
+.parameter-name {
+    margin-right: -10px;
+}
+
 #toc-title {
     font-size: 16px;
 }
@@ -64,6 +94,7 @@ p,h1,h2,h3,#toc-title,#toc-function-reference,.nav-link,.table {
 
 #quarto-margin-sidebar {
     margin-left: 20px;
+    padding-top: 30px;
 }
 
 #quarto-margin-sidebar nav ul li  {
@@ -81,10 +112,26 @@ p,h1,h2,h3,#toc-title,#toc-function-reference,.nav-link,.table {
     font-weight: bold;
 }
 
+a.sidebar-item-text.sidebar-link.text-start[data-bs-toggle="collapse"] {
+    pointer-events: none;
+    cursor: default;
+}
+
+div.sidebar-item-container {
+    cursor: default !important;
+}
+
 a.sidebar-item-toggle.text-start > i {
     color: #FAFAFD;
 }
 
+a.sidebar-item-text.sidebar-link.active {
+    color: rgb(244, 121, 0);
+    text-decoration: underline;
+    text-decoration-thickness: 2px;
+    text-decoration-color: rgba(101, 180, 237, 0.75);
+}
+
 #api-reference > h1 {
     margin: 0;
 }